From 044e14092074bc2b18594360057dea2ec8e069c7 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 11:19:10 -0700 Subject: [PATCH] adding manpage --- docs/conf.py | 239 +++++++++++++++++++++++++++ docs/ldptool-man.rst | 375 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 614 insertions(+) create mode 100644 docs/conf.py create mode 100644 docs/ldptool-man.rst diff --git a/docs/conf.py b/docs/conf.py new file mode 100644 index 0000000..39d0537 --- /dev/null +++ b/docs/conf.py @@ -0,0 +1,239 @@ +# -*- coding: utf-8 -*- +# +# tox documentation build configuration file, created by +# sphinx-quickstart on Fri Nov 9 19:00:14 2012. +# +# This file is execfile()d with the current directory set to its containing dir. +# +# Note that not all possible configuration values are present in this +# autogenerated file. +# +# All configuration values have a default; values that are commented out +# serve to show the default. + +import sys, os + +# If extensions (or modules to document with autodoc) are in another directory, +# add these directories to sys.path here. If the directory is relative to the +# documentation root, use os.path.abspath to make it absolute, like shown here. +#sys.path.insert(0, os.path.abspath('.')) + +# -- General configuration ----------------------------------------------------- + +# If your documentation needs a minimal Sphinx version, state it here. +#needs_sphinx = '1.0' + +# Add any Sphinx extension module names here, as strings. They can be extensions +# coming with Sphinx (named 'sphinx.ext.*') or your custom ones. +extensions = ['sphinx.ext.autodoc'] + +# Add any paths that contain templates here, relative to this directory. +templates_path = ['_templates'] + +# The suffix of source filenames. +source_suffix = '.rst' + +# The encoding of source files. +#source_encoding = 'utf-8-sig' + +# The master toctree document. +master_doc = 'ldptool-man' + +# General information about the project. +project = u'ldptool' +copyright = u'Manual page (C) 2016, Linux Documentation Project' + +# The version info for the project you're documenting, acts as replacement for +# |version| and |release|, also used in various other places throughout the +# built documents. +# +# The short X.Y version. +version = '1.9.2' +# The full version, including alpha/beta/rc tags. +release = '1.9.2' + +# The language for content autogenerated by Sphinx. Refer to documentation +# for a list of supported languages. +#language = None + +# There are two options for replacing |today|: either, you set today to some +# non-false value, then it is used: +#today = '' +# Else, today_fmt is used as the format for a strftime call. +#today_fmt = '%B %d, %Y' + +# List of patterns, relative to source directory, that match files and +# directories to ignore when looking for source files. +exclude_patterns = ['_build'] + +# The reST default role (used for this markup: `text`) to use for all documents. +#default_role = None + +# If true, '()' will be appended to :func: etc. cross-reference text. +#add_function_parentheses = True + +# If true, the current module name will be prepended to all description +# unit titles (such as .. function::). +#add_module_names = True + +# If true, sectionauthor and moduleauthor directives will be shown in the +# output. They are ignored by default. +#show_authors = False + +# The name of the Pygments (syntax highlighting) style to use. +pygments_style = 'sphinx' + +# A list of ignored prefixes for module index sorting. +#modindex_common_prefix = [] + + +# -- Options for HTML output --------------------------------------------------- + +# The theme to use for HTML and HTML Help pages. See the documentation for +# a list of builtin themes. +html_theme = 'default' + +# Theme options are theme-specific and customize the look and feel of a theme +# further. For a list of options available for each theme, see the +# documentation. +#html_theme_options = {} + +# Add any paths that contain custom themes here, relative to this directory. +#html_theme_path = [] + +# The name for this set of Sphinx documents. If None, it defaults to +# " v documentation". +#html_title = None + +# A shorter title for the navigation bar. Default is the same as html_title. +#html_short_title = None + +# The name of an image file (relative to this directory) to place at the top +# of the sidebar. +#html_logo = None + +# The name of an image file (within the static path) to use as favicon of the +# docs. This file should be a Windows icon file (.ico) being 16x16 or 32x32 +# pixels large. +#html_favicon = None + +# Add any paths that contain custom static files (such as style sheets) here, +# relative to this directory. They are copied after the builtin static files, +# so a file named "default.css" will overwrite the builtin "default.css". +html_static_path = ['_static'] + +# If not '', a 'Last updated on:' timestamp is inserted at every page bottom, +# using the given strftime format. +#html_last_updated_fmt = '%b %d, %Y' + +# If true, SmartyPants will be used to convert quotes and dashes to +# typographically correct entities. +#html_use_smartypants = True + +# Custom sidebar templates, maps document names to template names. +#html_sidebars = {} + +# Additional templates that should be rendered to pages, maps page names to +# template names. +#html_additional_pages = {} + +# If false, no module index is generated. +#html_domain_indices = True + +# If false, no index is generated. +#html_use_index = True + +# If true, the index is split into individual pages for each letter. +#html_split_index = False + +# If true, links to the reST sources are added to the pages. +#html_show_sourcelink = True + +# If true, "Created using Sphinx" is shown in the HTML footer. Default is True. +#html_show_sphinx = True + +# If true, "(C) Copyright ..." is shown in the HTML footer. Default is True. +#html_show_copyright = True + +# If true, an OpenSearch description file will be output, and all pages will +# contain a tag referring to it. The value of this option must be the +# base URL from which the finished HTML is served. +#html_use_opensearch = '' + +# This is the file name suffix for HTML files (e.g. ".xhtml"). +#html_file_suffix = None + +# Output file base name for HTML help builder. +htmlhelp_basename = 'ldptooldoc' + + +# -- Options for LaTeX output -------------------------------------------------- + +latex_elements = { +# The paper size ('letterpaper' or 'a4paper'). +#'papersize': 'letterpaper', + +# The font size ('10pt', '11pt' or '12pt'). +#'pointsize': '10pt', + +# Additional stuff for the LaTeX preamble. +#'preamble': '', +} + +# Grouping the document tree into LaTeX files. List of tuples +# (source start file, target name, title, author, documentclass [howto/manual]). +latex_documents = [] + +# The name of an image file (relative to this directory) to place at the top of +# the title page. +#latex_logo = None + +# For "manual" documents, if this is true, then toplevel headings are parts, +# not chapters. +#latex_use_parts = False + +# If true, show page references after internal links. +#latex_show_pagerefs = False + +# If true, show URL addresses after external links. +#latex_show_urls = False + +# Documents to append as an appendix to all manuals. +#latex_appendices = [] + +# If false, no module index is generated. +#latex_domain_indices = True + + +# -- Options for manual page output -------------------------------------------- + +# One entry per manual page. List of tuples +# (source start file, name, description, authors, manual section). +man_pages = [ + ('ldptool-man', 'ldptool', u'DocBook, Linuxdoc and Asciidoc build/publishing tool.', + [u'Martin A. Brown ',], 1) +] + +# If true, show URL addresses after external links. +#man_show_urls = False + + +# -- Options for Texinfo output ------------------------------------------------ + +# Grouping the document tree into Texinfo files. List of tuples +# (source start file, target name, title, author, +# dir menu entry, description, category) +texinfo_documents = [ + ('ldptool-man', 'ldptool', u'ldptool(1)', + u'Martin A. Brown', 'ldptool', 'DocBook, Linuxdoc and Asciidoc build/publishing tool.', + 'Miscellaneous'), +] + +# Documents to append as an appendix to all manuals. +#texinfo_appendices = [] + +# If false, no module index is generated. +#texinfo_domain_indices = True + +# How to display URL addresses: 'footnote', 'no', or 'inline'. +#texinfo_show_urls = 'footnote' diff --git a/docs/ldptool-man.rst b/docs/ldptool-man.rst new file mode 100644 index 0000000..094d0c0 --- /dev/null +++ b/docs/ldptool-man.rst @@ -0,0 +1,375 @@ +:orphan: + +ldptool manual page +=================== + +Synopsis +-------- + +**ldptool** [*options*] [*pathname* [...]] + + +Description +----------- + +:program:`ldptool` creates chunked HTML, single-page HTML, PDF and plain text +outputs for each source document it is passed as a *pathname*. See +`Source document discovery`_. + +If it is not passed any arguments, `ldptool` will collect all of the +directories specified with the --sourcedir option and scan through these +directories looking for valid source documents. + +The action taken depends on the options passed to the utility. If no options +are passed, then the default `--build` action will be attempted. The options +controlling the overall program are described in the sections `Action +options`_ and `Main options`_. All other options are relegated to the tail of +the manpage, because they are merely configurables for individual document +processors. + +The `ldptool` can: + +- generate an inventory from multiple source directories (`--sourcedir`) +- crawl through a single output collection (`--pubdir`) +- match the sources to the outputs (based on document stem name) +- describe the collection by type and status (`--summary`) +- list out individual document type and status (`--list`) +- describe supported source formats (`--formats`) +- describe the meaning of document status (`--statustypes`) +- build the expected (non-configurable) set of outputs (`--build`) +- build and publish the outputs (`--publish`) +- produce runnable shell script to STDOUT (`--script`) +- generate configuration files that it can then take as input + + +Action options +-------------- +-h, --help + show a help message and exit + +-b, --build + Build LDP documentation into the `--builddir` and exit. + This is the default action if no other action is specified. + +-p, --publish + Build LDP documentation into the `--builddir`. If all builds are + successful, then copy the result for each source document into the + `--pubdir`, effectively replacing (and deleting) the older documents; + finally, remove `--builddir`, if empty. + +-S, --script + Print a runnable bash script to STDOUT. This will produce a + shell script showing what would be executed upon `--build`. + +-l, --detail, --list + Examine the various SOURCEDIRs and the PUBDIR and generate a report + showing the FORMAT of the source document and STATUS of the document. + Add the `--verbose` flag for more information. + +-t, --summary + Examine the various SOURCEDIRs and the PUBDIR and generate a short + report summarizing documents by STATUS and by DOCTYPE. Add the + `--verbose` flag for more information. + +-T, --doctypes, --formats, --format, --list-doctypes, --list-formats + List the supported DOCTYPEs; there is one processor for each DOCTYPE. + +--statustypes, --list-statustypes + List the possible document STATUS types. There are only seven basic status + types, but several synonyms and groups of STATUS types (internally called + 'classes'). + +Main options +------------ +-s, --sourcedir, --source-dir, --source-directory SOURCEDIR (default: None) + Specify the name of a SOURCEDIR which contains source documents. See + also `Source document discovery`_. + + The `--sourcedir` option may be used more than once. + +-o, --pubdir, --output, --outputdir, --outdir PUBDIR (default: None) + Specify the the name of a PUBDIR. Used as the publication if the build + succeeds. When `--publish` is used with `--pubdir`, the output of + a successful document build will be used to replace any existing document + output directory in PUBDIR. + +-d, --builddir, --build-dir, --build-directory BUILDDIR (default: 'ldptool-build') + Specify the name of a BUILDDIR. A scratch directory used to build each + source document; directory is temporary and will be removed if the + build succeeds AND `--publish` has been requested. Under the `--build` + action, all output directories and contents remain in the BUILDDIR for + inspection. + +--verbose [True | False] (default: False) + Provide more information in --list and --detail actions. The option can + be thrown without an argument which is equivalent to True. To allow the + CLI to supersede environment or configuration file values, `--verbose + false` is also supported. + +--skip [STEM | DOCTYPE | STATUS] + Specify a source document name, document type or document status to skip + during processing. Each document is known by its STEM (see also `Source + document discovery`_), its document DOCTYPE (see list below), + and by the document STATUS (see list below). + + The `--skip` option may be used more than once. + + DOCTYPE can be one of: + Asciidoc, Docbook4XML, Docbook5XML, DocbookSGML, or Linuxdoc + (See also output of `--doctypes`) + + STATUS can be one of: + source, sources, output, outputs, published, stale, broken, new + orphan, orphans, orphaned, problems, work, all + (See also output of `--statustypes`) + +--resources RESOURCEDIR (default: ['images', 'resources']) + Some source documents provide images, scripts and other content. These + files are usually stored in a directory such as ./images/ that need to be + copied intact into the output directory. Adjust the set of resource + directories wyth this option. + + The `--resources` option may be used more than once. + +--loglevel LOGLEVEL (default: ERROR) + set the loglevel to LOGLEVEL; can be passed as numeric or textual; in + increasing order: CRITICAL (50), ERROR (40), WARNING (30), INFO (20), + DEBUG (10); N.B. the text names are not case-sensitive: 'info' is OK + +-c, --configfile, --config-file, --cfg CONFIGFILE (default: None) + Specify the name of a CONFIGFILE containing parameters to be read for + this invocation; an INI-style configuration file. A sample can be + generated with --dump-cfg. Although only one CONFIGFILE can be specified + via the environment or the command-line, the system config file + (/etc/ldptool/ldptool.ini) is always read. + +--dump_cli, --dump-cli + Produce the resulting, merged configuration as in CLI form. (After + processing all configuration sources (defaults, system configuration, user + configuration, environment variables, command-line.) + +--dump_env, --dump-env + Produce the resulting, merged configuration as a shell environment file. + +--dump_cfg, --dump-cfg + Produce the resulting, merged configuration as an INI-configuration file. + +--debug_options, --debug-options + Provide lots of debugging information on option-processing; see also + `--loglevel debug`. + + +Source document discovery +------------------------- +Almost all documentation formats provide the possibility that a document can +span multiple files. Although more than half of the LDP document collection +consists of single-file HOWTO contributions, there are a number of documents +that are composed of dozens, even hundreds of files. In order to accommodate +both the simple documents and these much more complex documents, LDP adopted a +simple (unoriginal) naming strategy to allow a single document to span +multiple files:: + + Each document is referred to by a stem, which is the filename without any + extension. A single file document is simple STEM.EXT. A document that + requires many files must be contained in a directory with the STEM name. + Therefore, the primary source document will always be called either STEM.EXT + or STEM/STEM.EXT. + +(If there is a STEM/STEM.xml and STEM/STEM.sgml in the same directory, that is +an error, and `ldptool` will freak out and shoot pigeons.) + +During document discovery, `ldptool` will walk through all of the source +directories specified with `--sourcedir` and build a complete list of all +identifiable source documents. Then, it will walk through the publication +directory `--pubdir` and match up each output directory (by its STEM) with the +corresponding STEM found in one of the source directories. + +Then, `ldptool` can then determine whether any source files are newer. It uses +content-hashing, i.e. MD5, and if a source file is newer, the status is +`stale`. If there is no matching output, the source file is `new`. If +there's an output with no source, that is in `orphan`. See the +`--statustypes` output for the full list of STATUS types. + + +Examples +-------- +To build and publish a single document:: + + $ ldptool --publish DocBook-Demystification-HOWTO + $ ldptool --publish ~/vcs/LDP/LDP/howto/docbook/Valgrind-HOWTO.xml + +To build and publish anything that is new or updated work:: + + $ ldptool --publish + $ ldptool --publish work + +To (re-)build and publish everything, regardless of state:: + + $ ldptool --publish all + +To generate a specific output (into a --builddir):: + + $ ldptool --build DocBook-Demystification-HOWTO + +To generate all outputs into a --builddir (should exist):: + + $ ldptool --builddir ~/tmp/scratch-directory/ --build all + +To build new/updated work, but pass over a trouble-maker:: + + $ ldptool --build --skip HOWTO-INDEX + +To loudly generate all outputs, except a trouble-maker:: + + $ ldptool --build all --loglevel debug --skip HOWTO-INDEX + +To print out a shell script for building a specific document:: + + $ ldptool --script TransparentProxy + $ ldptool --script ~/vcs/LDP/LDP/howto/docbook/Assembly-HOWTO.xml + + +Environment +----------- + +The `ldptool` accepts configuration via environment variables. All such +environment variables are prefixed with the name `LDPTOOL_`. + +The name of each variable is constructed from the primary +command-line option name. The `-b` is better known as `--builddir`, so the +environment variable would be `LDPTOOL_BUILDDIR`. Similarly, the environment +variable names for each of the handlers can be derived from the name of the +handler and its option. For example, the Asciidoc processor needs to have +access to the `xmllint` and `asciidoc` utilities. + +The environment variable corresponding to the CLI option `--asciidoc-xmllint` +would be `LDPTOOL_ASCIIDOC_XMLLINT`. Similarly, `--asciidoc-asciidoc` should +be `LDPTOOL_ASCIIDOC_ASCIIDOC`. + +Variables accepting multiple options use the comma as a separator:: + + LDPTOOL_RESOURCES=images,resources + +The complete listing of possible environment variables with all current values +can be printed by using `ldptool --dump-env`. + +Configuration file +------------------ +The system-installed configuration file is `/etc/ldptool/ldptool.ini`. The +format is a simple INI-style configuration file with a block for the main +program and a block for each handler. Here's a partial example:: + + [ldptool] + resources = images, + resources + loglevel = 40 + + [ldptool-asciidoc] + asciidoc = /usr/bin/asciidoc + xmllint = /usr/bin/xmllint + +Note that the comma separates multiple values for a single option +(`resources`) in the above config fragment. + +The complete, current configuration file can be printed by using `ldptool +--dump-cfg`. + + +Configuration option fragments for each DOCTYPE handler +------------------------------------------------------- +Every source format has a single handler and each DOCTYPE handler may require +a different set of executables and/or data files to complete its job. The +defaults depend on the platform and are detected at runtime. In most cases, +the commands are found in `/usr/bin` (see below). The data files, for example +the LDP XSL files and the docbook.rng, may live in different places on +different systems. + +If a given DOCTYPE handler cannot find all of its requirements, it will +complain to STDERR during execution, but will not abort the rest of the run. + +If, for some reason, `ldptool` cannot find data files, but you know where they +are, consider generating a configuration file with the `--dump-cfg` option, +adjusting the relevant options and then passing the `--configfile your.ini` to +specify these paths. + + +Asciidoc +-------- +--asciidoc-asciidoc PATH + full path to asciidoc [/usr/bin/asciidoc] +--asciidoc-xmllint PATH + full path to xmllint [/usr/bin/xmllint] + +N.B. The Asciidoc processor simply converts the source document to a +Docbook4XML document and then uses the richer Docbook4XML toolchain. + +Docbook4XML +----------- +--docbook4xml-xslchunk PATH + full path to LDP HTML chunker XSL +--docbook4xml-xslsingle PATH + full path to LDP HTML single-page XSL +--docbook4xml-xslprint PATH + full path to LDP FO print XSL +--docbook4xml-xmllint PATH + full path to xmllint [/usr/bin/xmllint] +--docbook4xml-xsltproc PATH + full path to xsltproc [/usr/bin/xsltproc] +--docbook4xml-html2text PATH + full path to html2text [/usr/bin/html2text] +--docbook4xml-fop PATH + full path to fop [/usr/bin/fop] +--docbook4xml-dblatex PATH + full path to dblatex [/usr/bin/dblatex] + +Docbook5XML +----------- +--docbook5xml-xslchunk PATH + full path to LDP HTML chunker XSL +--docbook5xml-xslsingle PATH + full path to LDP HTML single-page XSL +--docbook5xml-xslprint PATH + full path to LDP FO print XSL +--docbook5xml-rngfile PATH + full path to docbook.rng +--docbook5xml-xmllint PATH + full path to xmllint [/usr/bin/xmllint] +--docbook5xml-xsltproc PATH + full path to xsltproc [/usr/bin/xsltproc] +--docbook5xml-html2text PATH + full path to html2text [/usr/bin/html2text] +--docbook5xml-fop PATH + full path to fop [/usr/bin/fop] +--docbook5xml-dblatex PATH + full path to dblatex [/usr/bin/dblatex] +--docbook5xml-jing PATH + full path to jing [/usr/bin/jing] + +DocbookSGML +----------- +--docbooksgml-docbookdsl PATH + full path to html/docbook.dsl +--docbooksgml-ldpdsl PATH + full path to ldp/ldp.dsl [None] +--docbooksgml-jw PATH + full path to jw [/usr/bin/jw] +--docbooksgml-html2text PATH + full path to html2text [/usr/bin/html2text] +--docbooksgml-openjade PATH + full path to openjade [/usr/bin/openjade] +--docbooksgml-dblatex PATH + full path to dblatex [/usr/bin/dblatex] +--docbooksgml-collateindex PATH + full path to collateindex + +Linuxdoc +-------- +--linuxdoc-sgmlcheck PATH + full path to sgmlcheck [/usr/bin/sgmlcheck] +--linuxdoc-sgml2html PATH + full path to sgml2html [/usr/bin/sgml2html] +--linuxdoc-html2text PATH + full path to html2text [/usr/bin/html2text] +--linuxdoc-htmldoc PATH + full path to htmldoc [/usr/bin/htmldoc] +