adding manpage

8 years ago · 044e140920
parent 3693264ca2
commit 044e140920
2 changed files with 614 additions and 0 deletions
--- a/docs/conf.py
+++ 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
+# "<project> v<release> 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 <link> 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 <martin@linux-ip.net>',], 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'
--- a/docs/ldptool-man.rst
+++ 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]
+