..
/
download
s1kd-fmgen(1) s1kd-tools s1kd-fmgen(1)
NAME
s1kd-fmgen - Generate front matter data module contents
SYNOPSIS
s1kd-fmgen [-D <TYPE>] [-F <FMTYPES>] [-I <date>] [-P <PM>]
[-p <name>=<val> ...] [-t <TYPE>] [-x <XSL>]
[-,.flqvh?] [<DM>...]
DESCRIPTION
The s1kd-fmgen tool generates the content section for front matter data
modules from either a standard publication module, or the combined for‐
mat of the s1kd-flatten(1) tool. Some front matter types require the
use of the combined format, particularly those that list information
not directly found in the publication module, such as the highlights
(HIGH) type.
OPTIONS
-,, --dump-fmtypes-xml
Dump the built-in .fmtypes XML format.
-., --dump-fmtypes
Dump the built-in .fmtypes simple text format.
-D, --dump-xsl <TYPE>
Dump the built-in XSLT used to generate the specified type of
front matter.
-F, --fmtypes <FMTYPES>
Specify a custom .fmtypes file.
-f, --overwrite
Overwrite the specified front matter data module files after
generating their content.
-h, -?, --help
Show usage message.
-I, --date <date>
Set the issue date of the generated front matter data modules.
This can be a specific date in the form of "YYYY-MM-DD", "-" for
the current date, or "pm" to use the issue date of the publica‐
tion module.
-l, --list
Treat input (stdin or arguments) as lists of front matter data
modules to generate content for, rather than data modules them‐
selves. If reading list from stdin, the -P option must be used
to specify the publication module.
-P, --pm <PM>
Publication module or s1kd-flatten(1) PM format file to generate
contents from. If none is specified, the tool will read from
stdin.
-p, --param <name>=<value>
Pass a parameter to the XSLT stylesheets used to generate the
front matter content. Multiple parameters can be specified by
using this option multiple times.
The following parameters are automatically supplied to any
stylesheet, and therefore their names should be considered re‐
served:
· "type" - The front matter type name (e.g., HIGH) that was
matched in the .fmtypes file or specified by the user with the
-t option.
-q, --quiet
Quiet mode. Do not print errors.
-t, --type <TYPE>
Generate content for this type of front matter. Supported types
are:
· HIGH - Highlights
· LOA - List of abbreviations
· LOASD - List of applicable specifications and documentation
· LOEDM - List of effective data modules
· LOI - List of illustrations
· LOS - List of symbols
· LOT - List of terms
· LOTBL - List of tables
· TOC - Table of contents
· TP - Title page
-v, --verbose
Verbose output. Specify multiple times to increase the verbosi‐
ty.
-x, --xsl <XSL>
Use the specified XSLT script to generate the front matter con‐
tents instead of the built-in XSLT or the user-configured XSLT
from the .fmtypes file.
--version
Show version information.
<DM>...
Front matter data modules to generate content for. If no front
matter type can be determined for a data module, it will be ig‐
nored.
In addition, the following options allow configuration of the XML pars‐
er:
--dtdload
Load the external DTD.
--huge Remove any internal arbitrary parser limits.
--net Allow network access to load external DTD and entities.
--noent
Resolve entities.
--parser-errors
Emit errors from parser.
--parser-warnings
Emit warnings from parser.
--xinclude
Do XInclude processing.
--xml-catalog <file>
Use an XML catalog when resolving entities. Multiple catalogs
may be loaded by specifying this option multiple times.
.fmtypes file
This file specifies a list of info codes to associate with a particular
type of front matter.
Optionally, a path to an XSLT script can be given for each info code,
which will be used to generate the front matter instead of the built-in
XSLT. The path to an XSLT script will be interpreted relative to the
location of the .fmtypes file (typically, the top directory of the CS‐
DB). The -D option can be used to dump the built-in XSLT for a type of
front matter as a starting point for a custom script.
Optionally, in the XML format, the attribute ignoreDel may be specified
to control whether deleted data modules and elements are ignored when
generating front matter contents. These are data modules with an issue
type of "deleted" and elements with a change type of "delete". A value
of "yes" means deleted content will not be included, while "no" means
it will. If this attribute is not specified, then a default value will
be used based on the type of front matter. The following types will
ignore deleted content by default:
· LOA
· LOASD
· LOI
· LOS
· LOTBL
· TOC
· TP
By default, the program will search for a file named .fmtypes in the
current directory and parent directories, but any file can be specified
using the -F option.
Example of simple text format:
001 TP
005 LOA
006 LOT
007 LOS
009 TOC
00A LOA
00S LOEDM
00U HIGH fm/high.xsl
00V LOASD
00Z LOTBL
Example of XML format:
<fmtypes>
<fm infoCode="001" type="TP"/>
<fm infoCode="005" type="LOA"/>
<fm infoCode="006" type="LOT"/>
<fm infoCode="007" type="LOS"/>
<fm infoCode="009" type="TOC"/>
<fm infoCode="00A" type="LOI"/>
<fm infoCode="00S" type="LOEDM"/>
<fm infoCode="00U" type="HIGH" xsl="fm/high.xsl"/>
<fm infoCode="00V" type="LOASD"/>
<fm infoCode="00Z" type="LOTBL"/>
</fmtypes>
The info code of each entry in the .fmtypes file may also include an
info code variant. This allows different transformations to be used
based on the variant:
<fmtypes>
<fm infoCode="00UA" type="HIGH" xsl="fm/high.xsl"/>
<fm infoCode="00UB" type="HIGH" xsl="fm/high-updates.xsl"/>
<fm infoCode="00U" type="HIGH"/>
</fmtypes>
In the example above, a highlights data module (00U) with info code
variant A will use an XSL transformation that creates a simple high‐
lights, while a highlights data module with info code variant B will
use an XSL transformation that creates a highlights with update in‐
structions. All other variants will use the built-in XSLT.
Entries are chosen in the order they are listed in the .fmtypes file.
An info code which does not specify a variant matches all possible
variants.
Optional title page elements
When re-generating the front matter content for a title page data mod‐
ule, optional elements which cannot be derived from the publication
module (such as the product illustration or bar code) will be copied
from the source data module when updating it.
Multi-pass transforms
Rather than a literal XSLT file, the path specified for the xsl at‐
tribute in the .fmtypes file or the -x (--xsl) option may be an XProc
file which contains a pipeline with multiple stylesheets. This allows
for multi-pass transformations.
Only a small subset of XProc is supported at this time.
Example:
<p:pipeline
xmlns:p="http://www.w3.org/ns/xproc"
xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
version="1.0">
<p:xslt name="Pass 1">
<p:input port="stylesheet">
<p:document href="pass1.xsl"/>
</p:input>
<p:with-param name="update-instr" select="true()"/>
</p:xslt>
<p:xslt name="Pass 2">
<p:input port="stylesheet">
<p:inline>
<xsl:transform version="1.0">
...
</xsl:transform>
</p:inline>
</p:input>
</p:xslt>
</p:pipeline>
EXIT STATUS
0 No errors.
1 The date specified with -I is invalid.
2 No front matter types were specified.
3 An unknown front matter type was specified.
4 The resulting front matter content could not be merged in to a
data module.
5 The stylesheet specified for a type of front matter was invalid.
EXAMPLE
Generate the content for a title page front matter data module and
overwrite the file:
$ s1kd-flatten PMC-EX-12345-00001-00_001-00_EN-CA.XML |
> s1kd-fmgen -f DMC-EX-A-00-00-00-00A-001A-D_001-00_EN-CA.XML
AUTHORS
khzae.net.
2021-04-16 s1kd-fmgen(1)
gopher://khzae.net/0/s1000d/s1kd-tools/docs/publishing/s1kd-fmgen.txt