.\" Automatically generated by Pandoc 2.9.2.1
.\"
.TH "s1kd-acronyms" "1" "2021-04-16" "" "s1kd-tools"
.hy
.SH NAME
.PP
s1kd-acronyms - Manage acronyms in S1000D data modules
.SH SYNOPSIS
.IP
.nf
\f[C]
s1kd-acronyms -h?
s1kd-acronyms [-dlpqtvx\[ha]] [-n <#>] [-o <file>] [-T <types>]
              [<dmodule>...]
s1kd-acronyms [-flqv] [-i|-I|-!] [-m|-M <acr>] [-o <file>] [-X <xpath>]
              [<dmodule>...]
s1kd-acronyms [-D|-P] [-flqv] [-o <file>] [<dmodule>...]
\f[R]
.fi
.SH DESCRIPTION
.PP
The \f[I]s1kd-acronyms\f[R] tool is used to manage acronyms in S1000D
data modules in one of three ways:
.IP \[bu] 2
Generate a list of unique acronyms used in all specified data modules.
.IP \[bu] 2
Mark up acronyms automatically based on a specified list.
.IP \[bu] 2
Remove acronym markup.
.SH OPTIONS
.TP
-D, --delete
Remove acronym markup, flattening it to the acronym term.
.TP
-d, --deflist
Format XML output as an S1000D \f[C]<definitionList>\f[R].
.TP
-f, --overwrite
When marking up acronyms with the -m option, overwrite the input data
modules instead of writing to stdout.
.TP
-h, -?, --help
Show help/usage message.
.TP
-I, --always-ask
In interactive mode, show a prompt for all acronyms, not just those with
multiple definitions.
This can be useful if some occurrences of acronym terms should be
ignored.
.TP
-i, --interactive
Markup acronyms in interactive mode.
If the specified acronyms list contains multiple definitions for a given
acronym term, the tool will prompt the user with the context in which
the acronym is used and present a list of the definitions for them to
choose from.
.RS
.PP
When not in interactive mode, the first definition found will be used.
.RE
.TP
-l, --list
Treat input (stdin or arguments) as lists of filenames of data modules
to find or markup acronyms in, rather than data modules themselves.
.TP
-M, --acronym-list <list>
Like the -m option, but use a custom list of acronyms instead of the
default \f[C].acronyms\f[R] file.
.TP
-m, --markup
Instead of listing acronyms in the specified data modules, automatically
markup acronyms in the data module using the \f[C].acronyms\f[R] file.
.TP
-n, --width <#>
Minimum number of spaces after the term in pretty-printed text output.
.TP
-o, --out <file>
Output to <file> instead of stdout.
.TP
-P, --preformat
Remove acronym markup by preformatting it.
The element \f[C]<acronym>\f[R] is flattened to the definition, followed
by the term in brackets [()].
The element \f[C]<acronymTerm>\f[R] is flattened to the term.
.TP
-p, --pretty
Pretty print text/XML acronym list output.
.TP
-q, --quiet
Quiet mode.
Errors are not printed.
.TP
-T, --types <types>
Only search for acronyms with an attribute \f[C]acronymType\f[R] whose
value is contained within the string <types>.
.TP
-t, --table
Format XML output as an S1000D \f[C]<table>\f[R].
.TP
-v, --verbose
Verbose output.
.TP
-X, --select <xpath>
When marking up acronyms with -m/-M, use a custom XPath expression to
specify which text nodes to search for acronyms in.
By default, this is all text nodes in any element where acronyms are
allowed.
This must be the path to the text() nodes, not the elements, e.g.
\f[C]//para/text()\f[R] and not simply \f[C]//para\f[R].
.TP
-x, --xml
Use XML output instead of plain text.
.TP
-!, --defer-choice
Mark where acronyms are found using a \f[C]<chooseAcronym>\f[R] element,
whose child elements are all possible acronyms matching the term.
Another program can then use this as input to actually prompt the user.
.TP
-\[ha], --remove-deleted
List acronyms with elements that have a change type of \[dq]delete\[dq]
removed.
.TP
--version
Show version information.
.TP
<dmodule>...
Data modules to find acronyms in.
If none are specified, input is taken from stdin.
.PP
In addition, the following options allow configuration of the XML
parser:
.TP
--dtdload
Load the external DTD.
.TP
--huge
Remove any internal arbitrary parser limits.
.TP
--net
Allow network access to load external DTD and entities.
.TP
--noent
Resolve entities.
.TP
--parser-errors
Emit errors from parser.
.TP
--parser-warnings
Emit warnings from parser.
.TP
--xinclude
Do XInclude processing.
.TP
--xml-catalog <file>
Use an XML catalog when resolving entities.
Multiple catalogs may be loaded by specifying this option multiple
times.
.SS \f[C].acronyms\f[R] file
.PP
This file specifies a list of acronyms for a project.
By default, the program will search for a file named \f[C].acronyms\f[R]
in the current directory and parent directories, but any file can be
specified using the -M option.
.PP
Example of .acronyms file format:
.IP
.nf
\f[C]
<acronyms>
<acronym acronymType=\[dq]at01\[dq]>
<acronymTerm>BREX</acronymTerm>
<acronymDefinition>Business Rules Exchange</acronymDefinition>
</acronym>
<acronym acronymType=\[dq]at01\[dq]>
<acronymTerm>SNS</acronymTerm>
<acronymDefinition>Standard Numbering System</acronymDefinition>
</acronym>
</acronyms>
\f[R]
.fi
.SH EXAMPLES
.PP
List all acronyms used in all data modules:
.IP
.nf
\f[C]
$ s1kd-acronyms DMC-*.XML
\f[R]
.fi
.PP
Markup predefined acronyms in a data module:
.IP
.nf
\f[C]
$ s1kd-acronyms -mf DMC-EX-A-00-00-00-00A-040A-D_EN-CA.XML
\f[R]
.fi
.PP
Unmarkup acronyms in a data module:
.IP
.nf
\f[C]
$ s1kd-acronyms -Df DMC-EX-A-00-00-00-00A-040A-D_EN-CA.XML
\f[R]
.fi
.SH AUTHORS
khzae.net.