diff --git a/MANIFEST.in b/MANIFEST.in index 4ae1a5a..7f8a170 100644 --- a/MANIFEST.in +++ b/MANIFEST.in @@ -1,3 +1,4 @@ include README.rst recursive-include etc * +recursive-include docs * recursive-include contrib * diff --git a/contrib/tldp.spec b/contrib/tldp.spec index 6cb5c19..5bec0a4 100644 --- a/contrib/tldp.spec +++ b/contrib/tldp.spec @@ -1,8 +1,8 @@ %define sourcename tldp %define name python-tldp -%define version 0.7.5 -%define unmangled_version 0.7.5 -%define unmangled_version 0.7.5 +%define version 0.7.7 +%define unmangled_version 0.7.7 +%define unmangled_version 0.7.7 %define release 1 Summary: processing tools for Asciidoc, DocBook XML, DocBook SGML and Linuxdoc @@ -54,6 +54,7 @@ python setup.py build %install python setup.py install --single-version-externally-managed -O1 --root=$RPM_BUILD_ROOT --record=INSTALLED_FILES +install -D --mode 0644 docs/ldptool.1 %{buildroot}%{_mandir}/man1/ldptool.1 perl -pi -e 's,(/etc/ldptool/ldptool.ini),%config(noreplace) $1,' INSTALLED_FILES %clean @@ -61,3 +62,4 @@ rm -rf $RPM_BUILD_ROOT %files -f INSTALLED_FILES %defattr(-,root,root) +%{_mandir}/man1/ldptool.1* diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 0000000..cbe873d --- /dev/null +++ b/debian/changelog @@ -0,0 +1,13 @@ +tldp (0.7.7) unstable; urgency=low + + * creating a manpage to satisfy Lintian, bumping version + * renamed source package to 'tldp' + * Initial release (Closes: #822181) + + -- Martin A. Brown Tue, 19 Apr 2016 15:40:13 -0400 + +python3-tldp (0.7.5) UNRELEASED; urgency=low + + * first attempt at Debianization + + -- Martin A. Brown Tue, 19 Apr 2016 15:40:13 -0400 diff --git a/debian/compat b/debian/compat new file mode 100644 index 0000000..ec63514 --- /dev/null +++ b/debian/compat @@ -0,0 +1 @@ +9 diff --git a/debian/control b/debian/control new file mode 100644 index 0000000..59b703d --- /dev/null +++ b/debian/control @@ -0,0 +1,42 @@ +Source: tldp +Maintainer: Martin A. Brown +Section: python +X-Python3-Version: >= 3.4 +Priority: optional +Homepage: https://github.com/tLDP/python-tldp +Build-Depends: debhelper (>= 9), + dh-python, + python3-all, + python3-networkx, + python3-nose, + python3-coverage, + htmldoc, + fop, + jing, + sgml2x, + xsltproc, + asciidoc, + docbook, + docbook5-xml, + docbook-xsl-ns, + linuxdoc-tools-latex, + linuxdoc-tools-text, + ldp-docbook-xsl, + ldp-docbook-dsssl, + html2text +Standards-Version: 3.9.8 +Vcs-Git: https://github.com/tLDP/python-tldp.git +Vcs-Browser: https://github.com/tLDP/python-tldp + +Package: python3-tldp +Architecture: all +Depends: ${misc:Depends}, + ${python3:Depends}, + python3, + python3-networkx +Description: automatic publishing tool for DocBook, Linuxdoc and Asciidoc + The Linux Documentation Project (TLDP) stores hundreds of documents in + DocBook SGML, DocBook XML, Linuxdoc and Asciidoc formats. This tool + automatically detects the source format and generates a directory containing + chunked and single-page HTML, a PDF and a plain text output. + diff --git a/debian/copyright b/debian/copyright new file mode 100644 index 0000000..d1789a1 --- /dev/null +++ b/debian/copyright @@ -0,0 +1,64 @@ +Format: http://www.debian.org/doc/packaging-manuals/copyright-format/1.0/ +Upstream-Name: python-tldp +Upstream-Contact: Martin A. Brown +Source: https://github.com/tLDP/python-tldp + +Files: * +Copyright: 2016 Linux Documentation Project +License: MIT + +Files: extras/dsssl/* extras/css/* +Copyright: 2000-2003 - Greg Ferguson (gferg@metalab.unc.edu) +License: GPL-2.0+ + +Files: extras/dsssl/* extras/xsl/* extras/css/* +Copyright: 2000-2002 - David Horton (dhorton@speakeasy.net) +License: GFDL-1.2 + +Files: tests/sample-documents/Docbook-4.2-WHYNOT/images/* tests/sample-documents/DocBookSGML-Larger/images/bullet.png tests/sample-documents/Linuxdoc-Larger/images/* +Copyright: Copyright (C) 2011-2012 O'Reilly Media +License: MIT + +Files: extras/collateindex.pl +Copyright: 1997-2001 Norman Walsh +License: MIT + +License: MIT + Permission is hereby granted, free of charge, to any person obtaining a + copy of this software and associated documentation files (the "Software"), + to deal in the Software without restriction, including without limitation + the rights to use, copy, modify, merge, publish, distribute, sublicense, + and/or sell copies of the Software, and to permit persons to whom the + Software is furnished to do so, subject to the following conditions: + . + The above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. + . + THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS + OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF + MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. + IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY + CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, + TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE + SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. + +License: GPL-2.0+ + This package is free software; you can redistribute it and/or modify + it under the terms of the GNU General Public License as published by + the Free Software Foundation; either version 2 of the License, or + (at your option) any later version. + . + This package is distributed in the hope that it will be useful, + but WITHOUT ANY WARRANTY; without even the implied warranty of + MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the + GNU General Public License for more details. + . + You should have received a copy of the GNU General Public License + along with this program. If not, see + . + On Debian systems, the complete text of the GNU General + Public License version 2 can be found in "/usr/share/common-licenses/GPL-2". + +License: GFDL-1.2 + On Debian systems, the complete text of the GFDL-1.2 can be found in + /usr/share/common-licenses/GFDL-1.2 diff --git a/debian/rules b/debian/rules new file mode 100755 index 0000000..1009a1c --- /dev/null +++ b/debian/rules @@ -0,0 +1,18 @@ +#!/usr/bin/make -f +# export PYBUILD_VERBOSE=1 +export PYBUILD_NAME=tldp + +%: + dh $@ --with=python3 --buildsystem=pybuild + +override_dh_installman: + (cd docs && \ + sphinx-build \ + -b man -D today="$(BUILD_DATE)" \ + -d _build/doctrees . _build/man) + dh_installman docs/_build/man/ldptool.1 + +override_dh_clean: + (cd docs && \ + rm -rf -- ./_build) + dh_clean diff --git a/debian/source/format b/debian/source/format new file mode 100644 index 0000000..89ae9db --- /dev/null +++ b/debian/source/format @@ -0,0 +1 @@ +3.0 (native) diff --git a/debian/watch b/debian/watch new file mode 100644 index 0000000..b8249b6 --- /dev/null +++ b/debian/watch @@ -0,0 +1,3 @@ +version=3 +opts=uversionmangle=s/(rc|a|b|c)/~$1/ \ +https://pypi.debian.net/tldp/tldp-(.+)\.(?:zip|tgz|tbz|txz|(?:tar\.(?:gz|bz2|xz))) 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] + diff --git a/docs/ldptool.1 b/docs/ldptool.1 new file mode 100644 index 0000000..5d031e3 --- /dev/null +++ b/docs/ldptool.1 @@ -0,0 +1,528 @@ +.\" Man page generated from reStructuredText. +. +.TH "LDPTOOL" "1" "2016-04-21" "1.9.2" "ldptool" +.SH NAME +ldptool \- DocBook, Linuxdoc and Asciidoc build/publishing tool. +. +.nr rst2man-indent-level 0 +. +.de1 rstReportMargin +\\$1 \\n[an-margin] +level \\n[rst2man-indent-level] +level margin: \\n[rst2man-indent\\n[rst2man-indent-level]] +- +\\n[rst2man-indent0] +\\n[rst2man-indent1] +\\n[rst2man-indent2] +.. +.de1 INDENT +.\" .rstReportMargin pre: +. RS \\$1 +. nr rst2man-indent\\n[rst2man-indent-level] \\n[an-margin] +. nr rst2man-indent-level +1 +.\" .rstReportMargin post: +.. +.de UNINDENT +. RE +.\" indent \\n[an-margin] +.\" old: \\n[rst2man-indent\\n[rst2man-indent-level]] +.nr rst2man-indent-level -1 +.\" new: \\n[rst2man-indent\\n[rst2man-indent-level]] +.in \\n[rst2man-indent\\n[rst2man-indent-level]]u +.. +.SH SYNOPSIS +.sp +\fBldptool\fP [\fIoptions\fP] [\fIpathname\fP [...]] +.SH DESCRIPTION +.sp +\fBldptool\fP creates chunked HTML, single\-page HTML, PDF and plain text +outputs for each source document it is passed as a \fIpathname\fP\&. See +\fI\%Source document discovery\fP\&. +.sp +If it is not passed any arguments, \fIldptool\fP will collect all of the +directories specified with the \-\-sourcedir option and scan through these +directories looking for valid source documents. +.sp +The action taken depends on the options passed to the utility. If no options +are passed, then the default \fI\-\-build\fP action will be attempted. The options +controlling the overall program are described in the sections \fI\%Action +options\fP and \fI\%Main options\fP\&. All other options are relegated to the tail of +the manpage, because they are merely configurables for individual document +processors. +.sp +The \fIldptool\fP can: +.INDENT 0.0 +.IP \(bu 2 +generate an inventory from multiple source directories (\fI\-\-sourcedir\fP) +.IP \(bu 2 +crawl through a single output collection (\fI\-\-pubdir\fP) +.IP \(bu 2 +match the sources to the outputs (based on document stem name) +.IP \(bu 2 +describe the collection by type and status (\fI\-\-summary\fP) +.IP \(bu 2 +list out individual document type and status (\fI\-\-list\fP) +.IP \(bu 2 +describe supported source formats (\fI\-\-formats\fP) +.IP \(bu 2 +describe the meaning of document status (\fI\-\-statustypes\fP) +.IP \(bu 2 +build the expected (non\-configurable) set of outputs (\fI\-\-build\fP) +.IP \(bu 2 +build and publish the outputs (\fI\-\-publish\fP) +.IP \(bu 2 +produce runnable shell script to STDOUT (\fI\-\-script\fP) +.IP \(bu 2 +generate configuration files that it can then take as input +.UNINDENT +.SH ACTION OPTIONS +.INDENT 0.0 +.TP +.B \-h\fP,\fB \-\-help +show a help message and exit +.TP +.B \-b\fP,\fB \-\-build +Build LDP documentation into the \fI\-\-builddir\fP and exit. +This is the default action if no other action is specified. +.TP +.B \-p\fP,\fB \-\-publish +Build LDP documentation into the \fI\-\-builddir\fP\&. If all builds are +successful, then copy the result for each source document into the +\fI\-\-pubdir\fP, effectively replacing (and deleting) the older documents; +finally, remove \fI\-\-builddir\fP, if empty. +.TP +.B \-S\fP,\fB \-\-script +Print a runnable bash script to STDOUT. This will produce a +shell script showing what would be executed upon \fI\-\-build\fP\&. +.TP +.B \-l\fP,\fB \-\-detail\fP,\fB \-\-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 \fI\-\-verbose\fP flag for more information. +.TP +.B \-t\fP,\fB \-\-summary +Examine the various SOURCEDIRs and the PUBDIR and generate a short +report summarizing documents by STATUS and by DOCTYPE. Add the +\fI\-\-verbose\fP flag for more information. +.TP +.B \-T\fP,\fB \-\-doctypes\fP,\fB \-\-formats\fP,\fB \-\-format\fP,\fB \-\-list\-doctypes\fP,\fB \-\-list\-formats +List the supported DOCTYPEs; there is one processor for each DOCTYPE. +.TP +.B \-\-statustypes\fP,\fB \-\-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 +\(aqclasses\(aq). +.UNINDENT +.SH MAIN OPTIONS +.INDENT 0.0 +.TP +.B \-s, \-\-sourcedir, \-\-source\-dir, \-\-source\-directory SOURCEDIR (default: None) +Specify the name of a SOURCEDIR which contains source documents. See +also \fI\%Source document discovery\fP\&. +.sp +The \fI\-\-sourcedir\fP option may be used more than once. +.TP +.B \-o, \-\-pubdir, \-\-output, \-\-outputdir, \-\-outdir PUBDIR (default: None) +Specify the the name of a PUBDIR. Used as the publication if the build +succeeds. When \fI\-\-publish\fP is used with \fI\-\-pubdir\fP, the output of +a successful document build will be used to replace any existing document +output directory in PUBDIR. +.TP +.B \-d, \-\-builddir, \-\-build\-dir, \-\-build\-directory BUILDDIR (default: \(aqldptool\-build\(aq) +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 \fI\-\-publish\fP has been requested. Under the \fI\-\-build\fP +action, all output directories and contents remain in the BUILDDIR for +inspection. +.TP +.B \-\-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, \fI\-\-verbose +false\fP is also supported. +.TP +.B \-\-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 \fI\%Source +document discovery\fP), its document DOCTYPE (see list below), +and by the document STATUS (see list below). +.sp +The \fI\-\-skip\fP option may be used more than once. +.INDENT 7.0 +.TP +.B DOCTYPE can be one of: +Asciidoc, Docbook4XML, Docbook5XML, DocbookSGML, or Linuxdoc +(See also output of \fI\-\-doctypes\fP) +.TP +.B STATUS can be one of: +source, sources, output, outputs, published, stale, broken, new +orphan, orphans, orphaned, problems, work, all +(See also output of \fI\-\-statustypes\fP) +.UNINDENT +.TP +.B \-\-resources RESOURCEDIR (default: [\(aqimages\(aq, \(aqresources\(aq]) +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. +.sp +The \fI\-\-resources\fP option may be used more than once. +.TP +.B \-\-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: \(aqinfo\(aq is OK +.TP +.B \-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. +.UNINDENT +.INDENT 0.0 +.TP +.B \-\-dump_cli\fP,\fB \-\-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.) +.TP +.B \-\-dump_env\fP,\fB \-\-dump\-env +Produce the resulting, merged configuration as a shell environment file. +.TP +.B \-\-dump_cfg\fP,\fB \-\-dump\-cfg +Produce the resulting, merged configuration as an INI\-configuration file. +.TP +.B \-\-debug_options\fP,\fB \-\-debug\-options +Provide lots of debugging information on option\-processing; see also +\fI\-\-loglevel debug\fP\&. +.UNINDENT +.SH SOURCE DOCUMENT DISCOVERY +.sp +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: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +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. +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +(If there is a STEM/STEM.xml and STEM/STEM.sgml in the same directory, that is +an error, and \fIldptool\fP will freak out and shoot pigeons.) +.sp +During document discovery, \fIldptool\fP will walk through all of the source +directories specified with \fI\-\-sourcedir\fP and build a complete list of all +identifiable source documents. Then, it will walk through the publication +directory \fI\-\-pubdir\fP and match up each output directory (by its STEM) with the +corresponding STEM found in one of the source directories. +.sp +Then, \fIldptool\fP 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 +\fIstale\fP\&. If there is no matching output, the source file is \fInew\fP\&. If +there\(aqs an output with no source, that is in \fIorphan\fP\&. See the +\fI\-\-statustypes\fP output for the full list of STATUS types. +.SH EXAMPLES +.sp +To build and publish a single document: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-publish DocBook\-Demystification\-HOWTO +$ ldptool \-\-publish ~/vcs/LDP/LDP/howto/docbook/Valgrind\-HOWTO.xml +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To build and publish anything that is new or updated work: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-publish +$ ldptool \-\-publish work +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To (re\-)build and publish everything, regardless of state: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-publish all +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To generate a specific output (into a \-\-builddir): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-build DocBook\-Demystification\-HOWTO +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To generate all outputs into a \-\-builddir (should exist): +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-builddir ~/tmp/scratch\-directory/ \-\-build all +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To build new/updated work, but pass over a trouble\-maker: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-build \-\-skip HOWTO\-INDEX +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To loudly generate all outputs, except a trouble\-maker: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-build all \-\-loglevel debug \-\-skip HOWTO\-INDEX +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +To print out a shell script for building a specific document: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +$ ldptool \-\-script TransparentProxy +$ ldptool \-\-script ~/vcs/LDP/LDP/howto/docbook/Assembly\-HOWTO.xml +.ft P +.fi +.UNINDENT +.UNINDENT +.SH ENVIRONMENT +.sp +The \fIldptool\fP accepts configuration via environment variables. All such +environment variables are prefixed with the name \fILDPTOOL_\fP\&. +.sp +The name of each variable is constructed from the primary +command\-line option name. The \fI\-b\fP is better known as \fI\-\-builddir\fP, so the +environment variable would be \fILDPTOOL_BUILDDIR\fP\&. 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 \fIxmllint\fP and \fIasciidoc\fP utilities. +.sp +The environment variable corresponding to the CLI option \fI\-\-asciidoc\-xmllint\fP +would be \fILDPTOOL_ASCIIDOC_XMLLINT\fP\&. Similarly, \fI\-\-asciidoc\-asciidoc\fP should +be \fILDPTOOL_ASCIIDOC_ASCIIDOC\fP\&. +.sp +Variables accepting multiple options use the comma as a separator: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +LDPTOOL_RESOURCES=images,resources +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +The complete listing of possible environment variables with all current values +can be printed by using \fIldptool \-\-dump\-env\fP\&. +.SH CONFIGURATION FILE +.sp +The system\-installed configuration file is \fI/etc/ldptool/ldptool.ini\fP\&. The +format is a simple INI\-style configuration file with a block for the main +program and a block for each handler. Here\(aqs a partial example: +.INDENT 0.0 +.INDENT 3.5 +.sp +.nf +.ft C +[ldptool] +resources = images, + resources +loglevel = 40 + +[ldptool\-asciidoc] +asciidoc = /usr/bin/asciidoc +xmllint = /usr/bin/xmllint +.ft P +.fi +.UNINDENT +.UNINDENT +.sp +Note that the comma separates multiple values for a single option +(\fIresources\fP) in the above config fragment. +.sp +The complete, current configuration file can be printed by using \fIldptool +\-\-dump\-cfg\fP\&. +.SH CONFIGURATION OPTION FRAGMENTS FOR EACH DOCTYPE HANDLER +.sp +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 \fI/usr/bin\fP (see below). The data files, for example +the LDP XSL files and the docbook.rng, may live in different places on +different systems. +.sp +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. +.sp +If, for some reason, \fIldptool\fP cannot find data files, but you know where they +are, consider generating a configuration file with the \fI\-\-dump\-cfg\fP option, +adjusting the relevant options and then passing the \fI\-\-configfile your.ini\fP to +specify these paths. +.SH ASCIIDOC +.INDENT 0.0 +.TP +.BI \-\-asciidoc\-asciidoc \ PATH +full path to asciidoc [/usr/bin/asciidoc] +.TP +.BI \-\-asciidoc\-xmllint \ PATH +full path to xmllint [/usr/bin/xmllint] +.UNINDENT +.sp +N.B. The Asciidoc processor simply converts the source document to a +Docbook4XML document and then uses the richer Docbook4XML toolchain. +.SH DOCBOOK4XML +.INDENT 0.0 +.TP +.BI \-\-docbook4xml\-xslchunk \ PATH +full path to LDP HTML chunker XSL +.TP +.BI \-\-docbook4xml\-xslsingle \ PATH +full path to LDP HTML single\-page XSL +.TP +.BI \-\-docbook4xml\-xslprint \ PATH +full path to LDP FO print XSL +.TP +.BI \-\-docbook4xml\-xmllint \ PATH +full path to xmllint [/usr/bin/xmllint] +.TP +.BI \-\-docbook4xml\-xsltproc \ PATH +full path to xsltproc [/usr/bin/xsltproc] +.TP +.BI \-\-docbook4xml\-html2text \ PATH +full path to html2text [/usr/bin/html2text] +.TP +.BI \-\-docbook4xml\-fop \ PATH +full path to fop [/usr/bin/fop] +.TP +.BI \-\-docbook4xml\-dblatex \ PATH +full path to dblatex [/usr/bin/dblatex] +.UNINDENT +.SH DOCBOOK5XML +.INDENT 0.0 +.TP +.BI \-\-docbook5xml\-xslchunk \ PATH +full path to LDP HTML chunker XSL +.TP +.BI \-\-docbook5xml\-xslsingle \ PATH +full path to LDP HTML single\-page XSL +.TP +.BI \-\-docbook5xml\-xslprint \ PATH +full path to LDP FO print XSL +.TP +.BI \-\-docbook5xml\-rngfile \ PATH +full path to docbook.rng +.TP +.BI \-\-docbook5xml\-xmllint \ PATH +full path to xmllint [/usr/bin/xmllint] +.TP +.BI \-\-docbook5xml\-xsltproc \ PATH +full path to xsltproc [/usr/bin/xsltproc] +.TP +.BI \-\-docbook5xml\-html2text \ PATH +full path to html2text [/usr/bin/html2text] +.TP +.BI \-\-docbook5xml\-fop \ PATH +full path to fop [/usr/bin/fop] +.TP +.BI \-\-docbook5xml\-dblatex \ PATH +full path to dblatex [/usr/bin/dblatex] +.TP +.BI \-\-docbook5xml\-jing \ PATH +full path to jing [/usr/bin/jing] +.UNINDENT +.SH DOCBOOKSGML +.INDENT 0.0 +.TP +.BI \-\-docbooksgml\-docbookdsl \ PATH +full path to html/docbook.dsl +.TP +.BI \-\-docbooksgml\-ldpdsl \ PATH +full path to ldp/ldp.dsl [None] +.TP +.BI \-\-docbooksgml\-jw \ PATH +full path to jw [/usr/bin/jw] +.TP +.BI \-\-docbooksgml\-html2text \ PATH +full path to html2text [/usr/bin/html2text] +.TP +.BI \-\-docbooksgml\-openjade \ PATH +full path to openjade [/usr/bin/openjade] +.TP +.BI \-\-docbooksgml\-dblatex \ PATH +full path to dblatex [/usr/bin/dblatex] +.TP +.BI \-\-docbooksgml\-collateindex \ PATH +full path to collateindex +.UNINDENT +.SH LINUXDOC +.INDENT 0.0 +.TP +.BI \-\-linuxdoc\-sgmlcheck \ PATH +full path to sgmlcheck [/usr/bin/sgmlcheck] +.TP +.BI \-\-linuxdoc\-sgml2html \ PATH +full path to sgml2html [/usr/bin/sgml2html] +.TP +.BI \-\-linuxdoc\-html2text \ PATH +full path to html2text [/usr/bin/html2text] +.TP +.BI \-\-linuxdoc\-htmldoc \ PATH +full path to htmldoc [/usr/bin/htmldoc] +.UNINDENT +.SH AUTHOR +Martin A. Brown +.SH COPYRIGHT +Manual page (C) 2016, Linux Documentation Project +.\" Generated by docutils manpage writer. +. diff --git a/setup.py b/setup.py index 2c6e1b0..14c2375 100644 --- a/setup.py +++ b/setup.py @@ -11,7 +11,7 @@ with open(os.path.join(os.path.dirname(__file__), 'README.rst')) as r_file: setup( name='tldp', - version='0.7.5', + version='0.7.7', license='MIT', author='Martin A. Brown', author_email='martin@linux-ip.net', diff --git a/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.png b/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.png index c505414..1c33db8 100644 Binary files a/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.png and b/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.png differ diff --git a/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.svg b/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.svg index 0de77fa..8dad121 100644 --- a/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.svg +++ b/tests/sample-documents/DocBook-4.2-WHYNOT/images/warning.svg @@ -1,17 +1,28 @@ - - + + +ZGF0ZTpjcmVhdGUAMjAxNi0wNC0xOVQyMToxMToxNy0wNzowMOsKgVIAAAAldEVYdGRhdGU6bW9k +aWZ5ADIwMTYtMDQtMTlUMjE6MTE6MTctMDc6MDCaVznuAAAAKnRFWHRTaWduYXR1cmUAYzQyYjdk +MmQ1NjRhYWI1ODg4OTE5Nzk3MDNmMDJiNDVPEd+TAAAAQ3RFWHRTb2Z0d2FyZQBAKCMpSW1hZ2VN +YWdpY2sgNC4yLjggOTkvMDgvMDEgY3Jpc3R5QG15c3RpYy5lcy5kdXBvbnQuY29tkbohuAAAAABJ +RU5ErkJggg==" /> diff --git a/tests/sample-documents/Linuxdoc-Larger/images/another.png b/tests/sample-documents/Linuxdoc-Larger/images/another.png deleted file mode 100644 index 99d1313..0000000 Binary files a/tests/sample-documents/Linuxdoc-Larger/images/another.png and /dev/null differ diff --git a/tests/sample-documents/Linuxdoc-Larger/images/another.png b/tests/sample-documents/Linuxdoc-Larger/images/another.png new file mode 120000 index 0000000..50cf5a2 --- /dev/null +++ b/tests/sample-documents/Linuxdoc-Larger/images/another.png @@ -0,0 +1 @@ +../../DocBookSGML-Larger/images/bullet.png \ No newline at end of file diff --git a/tests/sample-documents/Linuxdoc-Larger/images/tiny.png b/tests/sample-documents/Linuxdoc-Larger/images/tiny.png deleted file mode 100644 index 99d1313..0000000 Binary files a/tests/sample-documents/Linuxdoc-Larger/images/tiny.png and /dev/null differ diff --git a/tests/sample-documents/Linuxdoc-Larger/images/tiny.png b/tests/sample-documents/Linuxdoc-Larger/images/tiny.png new file mode 120000 index 0000000..50cf5a2 --- /dev/null +++ b/tests/sample-documents/Linuxdoc-Larger/images/tiny.png @@ -0,0 +1 @@ +../../DocBookSGML-Larger/images/bullet.png \ No newline at end of file diff --git a/tldp/driver.py b/tldp/driver.py index 678e104..f81ce8d 100644 --- a/tldp/driver.py +++ b/tldp/driver.py @@ -106,10 +106,11 @@ def summary(config, *args, **kwargs): if inv is None: inv = Inventory(config.pubdir, config.sourcedir) width = Namespace() - width.doctype = max([len(x.formatname) for x in knowndoctypes]) + width.doctype = max([len(x.__name__) for x in knowndoctypes]) width.status = max([len(x) for x in status_types]) width.count = len(str(len(inv.source.keys()))) - print('By Status Type', '--------------', sep='\n', file=file) + print('By Document Status (STATUS)', '---------------------------', + sep='\n', file=file) for status in status_types: count = len(getattr(inv, status, 0)) s = '{0:{w.status}} {1:{w.count}} '.format(status, count, w=width) @@ -128,10 +129,11 @@ def summary(config, *args, **kwargs): if abbrev: s = s + ', and %d more ...' % (len(abbrev)) print(s, file=file) - print('', 'By Document Type', '----------------', sep='\n', file=file) + print('', 'By Document Type (DOCTYPE)', '--------------------------', + sep='\n', file=file) summarybytype = collections.defaultdict(list) for doc in inv.source.values(): - name = doc.doctype.formatname + name = doc.doctype.__name__ summarybytype[name].append(doc.stem) for doctype, docs in summarybytype.items(): count = len(docs) @@ -158,7 +160,7 @@ def summary(config, *args, **kwargs): def detail(config, docs, **kwargs): file = kwargs.get('file', sys.stdout) width = Namespace() - width.doctype = max([len(x.formatname) for x in knowndoctypes]) + width.doctype = max([len(x.__name__) for x in knowndoctypes]) width.status = max([len(x) for x in status_types]) width.stem = max([len(x.stem) for x in docs]) # -- if user just said "list" with no args, then give the user something diff --git a/tldp/sources.py b/tldp/sources.py index b64ddd2..5cf27b3 100644 --- a/tldp/sources.py +++ b/tldp/sources.py @@ -204,7 +204,7 @@ class SourceDocument(object): def detail(self, widths, verbose, file=sys.stdout): '''produce a small tabular output about the document''' template = ' '.join(('{s.status:{w.status}}', - '{s.doctype.formatname:{w.doctype}}', + '{s.doctype.__name__:{w.doctype}}', '{s.stem:{w.stem}}')) outstr = template.format(s=self, w=widths) print(outstr, file=file)