Provided by: latexml_0.8.8-1_all 
NAME
"LaTeXML::Common::Config" - Configuration logic for LaTeXML
SYNPOSIS
use LaTeXML::Common::Config;
my $config = LaTeXML::Common::Config->new(
profile=>'name',
timeout=>60,
... );
$config->read(\@ARGV);
$config->check;
my $value = $config->get($name);
$config->set($name,$value);
$config->delete($name);
my $bool = $config->exists($name);
my @keys = $config->keys;
my $options_hashref = $config->options;
my $config_clone = $config->clone;
DESCRIPTION
Configuration management class for LaTeXML options.
* Responsible for defining the options interface
and parsing the usual Perl command-line options syntax
* Provides the intuitive getters, setters, as well as
hash methods for manipulating the option values.
* Also supports cloning into new configuration objects.
METHODS
"my $config = LaTeXML::Common::Config->new(%options);"
Creates a new configuration object. Note that you should try
not to provide your own %options hash but rather create an empty
configuration and use $config->read to read in the options.
"$config->read(\@ARGV);"
This is the main method for parsing in LaTeXML options.
The input array should either be @ARGV, e.g. when the
options were provided from the command line using the
classic Getopt::Long syntax,
or any other array reference that conforms to that setup.
"$config->check;"
Ensures that the configuration obeys the given profile and
performs a set of assignments of meaningful defaults
(when needed) and normalizations (for relative paths, etc).
"my $value = $config->get($name);"
Classic getter for the $value of an option $name.
"$config->set($name,$value);"
Classic setter for the $value of an option $name.
"$config->delete($name);"
Deletes option $name from the configuration.
"my $bool = $config->exists($name);"
Checks whether the key $name exists in the options hash of the configuration.
Similarly to Perl's "exist" for hashes, it returns true even when
the option's value is undefined.
"my @keys = $config->keys;"
Similar to "keys %hash" in Perl. Returns an array of all option names.
"my $options_hashref = $config->options;"
Returns the actual hash reference that holds all options within the configuration object.
"my $config_clone = $config->clone;"
Clones $config into a new LaTeXML::Common::Config object, $config_clone.
OPTION SYNOPSIS
latexmlc [options]
Options:
--VERSION show version number.
--help shows this help message.
--destination=file specifies destination file.
--output=file [obsolete synonym for --destination]
--preload=module requests loading of an optional module;
can be repeated
--preamble=file loads a tex file containing document
frontmatter. MUST include \begin{document}
or equivalent
--postamble=file loads a tex file containing document
backmatter. MUST include \end{document}
or equivalent
--includestyles allows latexml to load raw *.sty file;
by default it avoids this.
--base=dir sets the current working directory
--path=dir adds dir to the paths searched for files,
modules, etc;
--log=file specifies log file (default: STDERR)
--autoflush=count Automatically restart the daemon after
"count" inputs. Good practice for vast
batch jobs. (default: 100)
--timeout=secs Timecap for conversions (default 600)
--expire=secs Timecap for server inactivity (default 600)
--address=URL Specify server address (default: localhost)
--port=number Specify server port (default: 3354)
--documentid=id assign an id to the document root.
--quiet suppress messages (can repeat)
--verbose more informative output (can repeat)
--strict makes latexml less forgiving of errors
--bibtex processes a BibTeX bibliography.
--xml requests xml output (default).
--tex requests TeX output after expansion.
--box requests box output after expansion
and digestion.
--format=name requests "name" as the output format.
Supported: tex,box,xml,html4,html5,xhtml
html implies html5
--noparse suppresses parsing math (default: off)
--parse=name enables parsing math (default: on)
and selects parser framework "name".
Supported: RecDescent, no
--profile=name specify profile as defined in
LaTeXML::Common::Config
Supported: standard|math|fragment|...
(default: standard)
--mode=name Alias for profile
--cache_key=name Provides a name for the current option set,
to enable daemonized conversions without
needing re-initializing
--whatsin=chunk Defines the provided input chunk,
choose from document (default), fragment
and formula
--whatsout=chunk Defines the expected output chunk,
choose from document (default), fragment
and formula
--post requests a followup post-processing
--nopost forbids followup post-processing
--validate, --novalidate Enables (the default) or disables
validation of the source xml.
--omitdoctype omits the Doctype declaration,
--noomitdoctype disables the omission (the default)
--numbersections enables (the default) the inclusion of
section numbers in titles, crossrefs.
--nonumbersections disables the above
--timestamp provides a timestamp (typically a time and date)
to be embedded in the comments
--embed requests an embeddable XHTML snippet
(requires: --post,--profile=fragment)
DEPRECATED: Use --whatsout=fragment
TODO: Remove completely
--stylesheet specifies a stylesheet,
to be used by the post-processor.
--css=cssfile adds a css stylesheet to html/xhtml
(can be repeated)
--nodefaultresources disables processing built-in resources
--javascript=jsfile adds a link to a javascript file into
html/html5/xhtml (can be repeated)
--icon=iconfile specify a file to use as a "favicon"
--xsltparameter=name:value passes parameters to the XSLT.
--split requests splitting each document
--nosplit disables the above (default)
--splitat sets level to split the document
--splitpath=xpath sets xpath expression to use for
splitting (default splits at
sections, if splitting is enabled)
--splitnaming=(id|idrelative|label|labelrelative) specifies
how to name split files (idrelative).
--scan scans documents to extract ids,
labels, etc.
section titles, etc. (default)
--noscan disables the above
--crossref fills in crossreferences (default)
--nocrossref disables the above
--urlstyle=(server|negotiated|file) format to use for urls
(default server).
--navigationtoc=(context|none) generates a table of contents
in navigation bar
--index requests creating an index (default)
--noindex disables the above
--splitindex Splits index into pages per initial.
--nosplitindex disables the above (default)
--permutedindex permutes index phrases in the index
--nopermutedindex disables the above (default)
--bibliography=file sets a bibliography file
--splitbibliography splits the bibliography into pages per
initial.
--nosplitbibliography disables the above (default)
--prescan carries out only the split (if
enabled) and scan, storing
cross-referencing data in dbfile
(default is complete processing)
--dbfile=dbfile sets file to store crossreferences
--sitedirectory=dir sets the base directory of the site
--sourcedirectory=dir sets the base directory of the
original TeX source
--source=input as an alternative to passing the input as
the last argument, after the option set
you can also specify it as the value here.
useful for predictable API calls
--mathimages converts math to images
(default for html4 format)
--nomathimages disables the above
--mathimagemagnification=mag specifies magnification factor
--presentationmathml converts math to Presentation MathML
(default for xhtml & html5 formats)
--pmml alias for --presentationmathml
--nopresentationmathml disables the above
--linelength=n formats presentation mathml to a
linelength max of n characters
--contentmathml converts math to Content MathML
--nocontentmathml disables the above (default)
--cmml alias for --contentmathml
--openmath converts math to OpenMath
--noopenmath disables the above (default)
--om alias for --openmath
--keepXMath preserves the intermediate XMath
representation (default is to remove)
--mathtex adds TeX annotation to parallel markup
--nomathtex disables the above (default)
--unicodemath adds UnicodeMath annotation to parallel markup
--nounicodemath disables the above (default)
--parallelmath use parallel math annotations (default)
--noparallelmath disable parallel math annotations
--plane1 use plane-1 unicode for symbols
(default, if needed)
--noplane1 do not use plane-1 unicode
--graphicimages converts graphics to images (default)
--nographicimages disables the above
--graphicsmap=type.type specifies a graphics file mapping
--pictureimages converts picture environments to
images (default)
--nopictureimages disables the above
--svg converts picture environments to SVG
--nosvg disables the above (default)
--nocomments omit comments from the output
--inputencoding=enc specify the input encoding.
--debug=package enables debugging output for the named
package
If you want to provide a TeX snippet directly on input, rather than supply a filename, use the "literal:"
protocol to prefix your snippet.
OPTIONS AND ARGUMENTS
General Options
"--verbose"
Increases the verbosity of output during processing, used twice is pretty chatty.
Can be useful for getting more details when errors occur.
"--quiet"
Reduces the verbosity of output during processing, used twice is pretty silent.
"--VERSION"
Shows the version number of the LaTeXML package..
"--debug"=package
Enables debugging output for the named package. The package is given without the leading LaTeXML::.
"--base"=dir
Specifies the base working directory for the conversion server.
Useful when converting sets of documents that use relative paths.
"--log"=file
Specifies the log file; be default any conversion messages are printed to STDERR.
"--help"
Shows this help message.
Source Options
"--destination"=file
Specifies the destination file; by default the XML is written to STDOUT.
"--preload"=module
Requests the loading of an optional module or package. This may be useful if the TeX code
does not specifically require the module (eg. through input or usepackage).
For example, use "--preload=LaTeX.pool" to force LaTeX mode.
"--preamble"=file
Requests the loading of a tex file with document frontmatter, to be read in before the converted
document,
but after all --preload entries.
Note that the given file MUST contain \begin{document} or an equivalent environment start,
when processing LaTeX documents.
If the file does not contain content to appear in the final document, but only macro definitions and
setting of internal counters, it is more appropriate to use --preload instead.
"--postamble"=file
Requests the loading of a tex file with document backmatter, to be read in after the converted
document.
Note that the given file MUST contain \end{document} or an equivalent environment end,
when processing LaTeX documents.
"--sourcedirectory"=source
Specifies the directory where the original latex source is located. Unless LaTeXML is run from that
directory, or it can be determined from the xml filename, it may be necessary to specify this option
in order to find graphics and style files.
"--path"=dir
Add dir to the search paths used when searching for files, modules, style files, etc;
somewhat like TEXINPUTS. This option can be repeated.
"--validate", "--novalidate"
Enables (or disables) the validation of the source XML document (the default).
"--bibtex"
Forces latexml to treat the file as a BibTeX bibliography.
Note that the timing is slightly different than the usual
case with BibTeX and LaTeX. In the latter case, BibTeX simply
selects and formats a subset of the bibliographic entries; the
actual TeX expansion is carried out when the result is included
in a LaTeX document. In contrast, latexml processes and expands
the entire bibliography; the selection of entries is done
during post-processing. This also means that any packages
that define macros used in the bibliography must be
specified using the "--preload" option.
"--inputencoding="encoding
Specify the input encoding, eg. "--inputencoding=iso-8859-1".
The encoding must be one known to Perl's Encode package.
Note that this only enables the translation of the input bytes to
UTF-8 used internally by LaTeXML, but does not affect catcodes.
In such cases, you should be using the inputenc package.
Note also that this does not affect the output encoding, which is
always UTF-8.
TeX Conversion Options
"--includestyles"
This optional allows processing of style files (files with extensions "sty",
"cls", "clo", "cnf"). By default, these files are ignored unless a latexml
implementation of them is found (with an extension of "ltxml").
These style files generally fall into two classes: Those
that merely affect document style are ignorable in the XML.
Others define new markup and document structure, often using
deeper LaTeX macros to achieve their ends. Although the omission
will lead to other errors (missing macro definitions), it is
unlikely that processing the TeX code in the style file will
lead to a correct document.
"--timeout"=secs
Set time cap for conversion jobs, in seconds. Any job failing to convert in the
time range would return with a Fatal error of timing out.
Default value is 600, set to 0 to disable.
"--nocomments"
Normally latexml preserves comments from the source file, and adds a comment every 25 lines as
an aid in tracking the source. The option --nocomments discards such comments.
"--documentid"=id
Assigns an ID to the root element of the XML document. This ID is generally
inherited as the prefix of ID's on all other elements within the document.
This is useful when constructing a site of multiple documents so that
all nodes have unique IDs.
"--strict"
Specifies a strict processing mode. By default, undefined control sequences and
invalid document constructs (that violate the DTD) give warning messages, but attempt
to continue processing. Using "--strict" makes them generate fatal errors.
"--post"
Request post-processing, auto-enabled by any requested post-processor. Disabled by default.
If post-processing is enabled, the graphics and cross-referencing processors are on by default.
Format Options
"--format"="(html|html5|html4|xhtml|xml|epub)"
Specifies the output format for post processing. By default, it will be guessed from the file
extension of the destination (if given), with html implying "html5", xhtml implying "xhtml" and the
default being "xml", which you probably don't want.
The "html5" format converts the material to html5 form with mathematics as MathML; "html5" supports
SVG. "html4" format converts the material to the earlier html form, version 4, and the mathematics
to png images. "xhtml" format converts to xhtml and uses presentation MathML (after attempting to
parse the mathematics) for representing the math. "html5" similarly converts math to presentation
MathML. In these cases, any graphics will be converted to web-friendly formats and/or copied to the
destination directory. If you simply specify "html", it will treat that as "html5".
For the default, "xml", the output is left in LaTeXML's internal xml, although the math can be
converted by enabling one of the math postprocessors, such as --pmml to obtain presentation MathML.
For html, html5 and xhtml, a default stylesheet is provided, but see the "--stylesheet" option.
"--xml"
Requests XML output; this is the default.
DEPRECATED: use --format=xml instead
"--tex"
Requests TeX output for debugging purposes;
processing is only carried out through expansion and digestion.
This may not be quite valid TeX, since Unicode may be introduced.
"--box"
Requests Box output for debugging purposes;
processing is carried out through expansion and digestions,
and the result is printed.
"--profile"
Variety of shorthand profiles.
Note that the profiles come with a variety of preset options.
You can examine any of them in their "resources/Profiles/name.opt"
file.
Example: "latexmlc --profile=math 'literal:1+2=3'"
"--omitdoctype", "--noomitdoctype"
Omits (or includes) the document type declaration. The default is to include it if the document
model was based on a DTD.
"--numbersections", "--nonumbersections"
Includes (default), or disables the inclusion of section, equation, etc, numbers in the formatted
document and crossreference links.
"--stylesheet"=xslfile
Requests the XSL transformation of the document using the given xslfile as stylesheet. If the
stylesheet is omitted, a `standard' one appropriate for the format (html4, html5 or xhtml) will be
used.
"--css"=cssfile
Adds cssfile as a css stylesheet to be used in the transformed html/html5/xhtml. Multiple
stylesheets can be used; they are included in the html in the order given, following the default
"ltx-LaTeXML.css" (unless "--nodefaultcss"). The stylesheet is copied to the destination directory,
unless it is an absolute url.
Some stylesheets included in the distribution are
--css=navbar-left Puts a navigation bar on the left.
(default omits navbar)
--css=navbar-right Puts a navigation bar on the left.
--css=theme-blue A blue coloring theme for headings.
--css=amsart A style suitable for journal articles.
"--javascript"=jsfile
Includes a link to the javascript file jsfile, to be used in the transformed html/html5/xhtml.
Multiple javascript files can be included; they are linked in the html in the order given. The
javascript file is copied to the destination directory, unless it is an absolute url.
"--icon"=iconfile
Copies iconfile to the destination directory and sets up the linkage in the transformed
html/html5/xhtml to use that as the "favicon".
"--nodefaultresources"
Disables the copying and inclusion of resources added by the binding files; This includes CSS,
javascript or other files. This does not affect resources explicitly requested by the "--css" or
"--javascript" options.
"--timestamp"=timestamp
Provides a timestamp (typically a time and date) to be embedded in the comments by the stock XSLT
stylesheets. If you don't supply a timestamp, the current time and date will be used. (You can use
"--timestamp=0" to omit the timestamp).
"--xsltparameter"=name:value
Passes parameters to the XSLT stylesheet. See the manual or the stylesheet itself for available
parameters.
Site & Crossreferencing Options
"--split", "--nosplit"
Enables or disables (default) the splitting of documents into multiple `pages'. If enabled, the the
document will be split into sections, bibliography, index and appendices (if any) by default, unless
"--splitpath" is specified.
"--splitat="unit
Specifies what level of the document to split at. Should be one of "chapter", "section" (the
default), "subsection" or "subsubsection". For more control, see "--splitpath".
"--splitpath="xpath
Specifies an XPath expression to select nodes that will generate separate pages. The default
splitpath is
//ltx:section | //ltx:bibliography | //ltx:appendix | //ltx:index
Specifying
--splitpath="//ltx:section | //ltx:subsection
| //ltx:bibliography | //ltx:appendix | //ltx:index"
would split the document at subsections as well as sections.
"--splitnaming"="(id|idrelative|label|labelrelative)"
Specifies how to name the files for subdocuments created by splitting. The values "id" and "label"
simply use the id or label of the subdocument's root node for it's filename. "idrelative" and
"labelrelative" use the portion of the id or label that follows the parent document's id or label.
Furthermore, to impose structure and uniqueness, if a split document has children that are also
split, that document (and it's children) will be in a separate subdirectory with the name index.
"--scan", "--noscan"
Enables (default) or disables the scanning of documents for ids, labels, references, indexmarks, etc,
for use in filling in refs, cites, index and so on. It may be useful to disable when generating
documents not based on the LaTeXML doctype.
"--crossref", "--nocrossref"
Enables (default) or disables the filling in of references, hrefs, etc based on a previous scan
(either from "--scan", or "--dbfile") It may be useful to disable when generating documents not based
on the LaTeXML doctype.
"--urlstyle"="(server|negotiated|file)"
This option determines the way that URLs within the documents are formatted, depending on the way
they are intended to be served. The default, "server", eliminates unnecessary trailing "index.html".
With "negotiated", the trailing file extension (typically "html" or "xhtml") are eliminated. The
scheme "file" preserves complete (but relative) urls so that the site can be browsed as files without
any server.
"--navigationtoc"="(context|none)"
Generates a table of contents in the navigation bar; default is "none". The `context' style of TOC,
is somewhat verbose and reveals more detail near the current page; it is most suitable for navigation
bars placed on the left or right. Other styles of TOC should be developed and added here, such as a
short form.
"--index", "--noindex"
Enables (default) or disables the generation of an index from indexmarks embedded within the
document. Enabling this has no effect unless there is an index element in the document (generated by
\printindex).
"--splitindex", "--nosplitindex"
Enables or disables (default) the splitting of generated indexes into separate pages per initial
letter.
"--bibliography="pathname
Specifies a bibliography generated from a BibTeX file to be used to fill in a bibliography element.
Hand-written bibliographies placed in a "thebibliography" environment do not need this. The option
has no effect unless there is an bibliography element in the document (generated by \bibliography).
Note that this option provides the bibliography to be used to fill in the bibliography element
(generated by "\bibliography"); latexmlpost does not (currently) directly process and format such a
bibliography.
"--splitbibliography", "--nosplitbibliography"
Enables or disables (default) the splitting of generated bibliographies into separate pages per
initial letter.
"--prescan"
By default "latexmlpost" processes a single document into one (or more; see "--split") destination
files in a single pass. When generating a complicated site consisting of several documents it may be
advantageous to first scan through the documents to extract and store (in "dbfile") cross-referencing
data (such as ids, titles, urls, and so on). A later pass then has complete information allowing all
documents to reference each other, and also constructs an index and bibliography that reflects the
entire document set. The same effect (though less efficient) can be achieved by running
"latexmlpost" twice, provided a "dbfile" is specified.
"--dbfile"=file
Specifies a filename to use for the crossreferencing data when using two-pass processing. This file
may reside in the intermediate destination directory.
"--sitedirectory="dir
Specifies the base directory of the overall web site. Pathnames in the database are stored in a form
relative to this directory to make it more portable.
"--embed"
TODO: Deprecated, use --whatsout=fragment Requests an embeddable XHTML div (requires: --post
--format=xhtml),
respectively the top division of the document's body.
Caveat: This experimental mode is enabled only for fragment profile and post-processed
documents (to XHTML).
Math Options
These options specify how math should be converted into other formats. Multiple formats can be
requested; how they will be combined depends on the format and other options.
"--noparse"
Suppresses parsing math (default: parsing is on)
"--parse=name"
Enables parsing math (default: parsing is on)
and selects parser framework "name".
Supported: RecDescent, no
Tip: --parse=no is equivalent to --noparse
"--mathimages", "--nomathimages"
Requests or disables the conversion of math to images (png by default). Conversion is the default
for html4 format.
"--mathsvg", "--nomathsvg"
Requests or disables the conversion of math to svg images.
"--mathimagemagnification="factor
Specifies the magnification used for math images (both png and svg), if they are made. Default is
1.75.
"--presentationmathml", "--nopresentationmathml"
Requests or disables conversion of math to Presentation MathML. Conversion is the default for xhtml
and html5 formats.
"--linelength"=number
(Experimental) Line-breaks the generated Presentation MathML so that it is no longer than number
`characters'.
"--plane1"
Converts the content of Presentation MathML token elements to the appropriate Unicode Plane-1
codepoints according to the selected font, when applicable (the default).
"--hackplane1"
Converts the content of Presentation MathML token elements to the appropriate Unicode Plane-1
codepoints according to the selected font, but only for the mathvariants double-struck, fraktur and
script. This gives support for current (as of August 2009) versions of Firefox and MathPlayer,
provided a sufficient set of fonts is available (eg. STIX).
"--contentmathml", "--nocontentmathml"
Requests or disables conversion of math to Content MathML. Conversion is disabled by default. Note
that this conversion is only partially implemented.
"--openmath"
Requests or disables conversion of math to OpenMath. Conversion is disabled by default. Note that
this conversion is only partially implemented.
"--keepXMath", "--xmath"
By default, when any of the MathML or OpenMath conversions are used, the intermediate math
representation will be removed; this option preserves it; it will be used as secondary parallel
markup, when it follows the options for other math representations.
Graphics Options
"--graphicimages", "--nographicimages"
Enables (default) or disables the conversion of graphics to web-appropriate format (png).
"--graphicsmap="sourcetype.desttype
Specifies a mapping of graphics file types. Typically, graphics elements specify a graphics file that
will be converted to a more appropriate file target format; for example, postscript files used for
graphics with LaTeX will be converted to png format for use on the web. As with LaTeX, when a
graphics file is specified without a file type, the system will search for the most appropriate
target type file.
When this option is used, it overrides and replaces the defaults and provides a mapping of sourcetype
to desttype. The option can be repeated to provide several mappings, with the earlier formats
preferred. If the desttype is omitted, it specifies copying files of type sourcetype, unchanged.
The default settings is equivalent to having supplied the options:
svg png gif jpg jpeg eps.png ps.png ai.png pdf.png
The first formats are preferred and used unchanged, while the latter ones are converted to png.
"--pictureimages", "--nopictureimages"
Enables (default) or disables the conversion of picture environments and pstricks material into
images.
"--svg", "--nosvg"
Enables or disables (default) the conversion of picture environments and pstricks material to SVG.
Daemon, Server and Client Options
Options used only for daemonized conversions, e.g. talking to a remote server via latexmlc, or local
processing via the "LaTeXML::Plugin::latexmls" plugin.
For reliable communication and a stable conversion experience, invoke latexmls only through the latexmlc
client (you need to set --expire to a positive value, in order to request auto-spawning of a dedicated
conversion server).
"--autoflush"=count
Automatically restart the daemon after converting "count" inputs.
Good practice for vast batch jobs. (default: 100)
"--expire"=secs
Set an inactivity timeout value in seconds.
If the server process is not given any input for the specified duration,
it will automatically terminate.
The default value is 600 seconds, set to 0 to never expire,
-1 to entirely opt out of using an independent server.
"--address"=URL
Specify server address (default: localhost)
"--port"=number
Specify server port (default: 3334 for math, 3344 for fragment and 3354 for standard)
AUTHOR
Bruce Miller <bruce.miller@nist.gov> Deyan Ginev <deyan.ginev@nist.gov>
COPYRIGHT
Public domain software, produced as part of work done by the United States Government & not subject to
copyright in the US.
perl v5.38.2 2024-02-27 LaTeXML::Common::Config(3pm)