From a1c20ce125c5090aeaf4d382f2aaf04c460f50b4 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Tue, 19 Apr 2016 21:13:57 -0700 Subject: [PATCH 01/16] to fix licensing issues --- .../DocBook-4.2-WHYNOT/images/warning.png | Bin 457 -> 1241 bytes 1 file changed, 0 insertions(+), 0 deletions(-) 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 c505414e5fe3ac842a57e4c7e1465b828d5f3a62..1c33db8f34a8b42b373179b46a2d8d8a10e061a9 100644 GIT binary patch literal 1241 zcmeHH+e?!H6#vDtmgHCxG{Q}12(7`~)|MMe^RnTlY0JD#q1sIwW1DTCqzzwWg@Q=t zBC2Iceu@w4LHM97Gb5%*E%9MN*%m}jvs!{N@Pd8$H}vS?TsRzlzr#5kPPe|YG%fXL zDu6VdR$WC$&Oc)^X#ZjK-7LU>{!F!o39xr+d_Vw5fMTEwpb-s#9q<5Nzz6gIepyU?Lctpr{ZK zVzWaWPAC)#17S8h%;AIuf(Q_yeIybEqS0s^i1YdJcsv0ln9M{Xkpz;-I_^=P))~D~!!Hvpq{Dl8O{rN@cECkt>#DncX%I(O&3i_YgL-$m$VU zT3cLBLS%M1`o{TBX}S|Tbhc)vk!Yp)%rdDd&my(RPsxl%lU$)tC?(1~WuEwClUQn! n$Q8O{Mxt@ukkcT{K0> delta 432 zcmV;h0Z;zf3CRPHBYyy*P)t-srKP1x005dP#t;yt007U2_IXP$KW*|$s{(glc-JApR%yk09Rms(c5a(Qau)tf-&UFNF zpTR8o3bg~8MDKzd;Y(B<{1d)}2=UXK5I>87Ke6AI-b8f|-GprKf$cpeYf#6+E~W`~ zDw^)*5;BKu57zI>=j*ELhj`N?lGKk={YG{XH_BuR$0;{;nx30;bVXwlN%t=~eb24d a Date: Wed, 20 Apr 2016 07:34:12 -0700 Subject: [PATCH 02/16] adjusting file sources for Debian copyright explanations --- .../DocBook-4.2-WHYNOT/images/warning.svg | 23 +++++++++++++----- .../Linuxdoc-Larger/images/another.png | Bin 71 -> 42 bytes .../Linuxdoc-Larger/images/tiny.png | Bin 71 -> 42 bytes 3 files changed, 17 insertions(+), 6 deletions(-) mode change 100644 => 120000 tests/sample-documents/Linuxdoc-Larger/images/another.png mode change 100644 => 120000 tests/sample-documents/Linuxdoc-Larger/images/tiny.png 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 99d131317bbbbe26a0836b70954232053c1f0281..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 71 zcmeAS@N?(olHy`uVBq!ia0vp^Od!kwBpAZ)2K@k1e4Z|jAr*6ya}pAg5`c1(7+Sv9 RERF!F@O1TaS?83{1OVi15On|m 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 99d131317bbbbe26a0836b70954232053c1f0281..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 71 zcmeAS@N?(olHy`uVBq!ia0vp^Od!kwBpAZ)2K@k1e4Z|jAr*6ya}pAg5`c1(7+Sv9 RERF!F@O1TaS?83{1OVi15On|m 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 From 3693264ca2c75559ef199d809ba6a4e3cbab764a Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Wed, 20 Apr 2016 22:38:45 -0700 Subject: [PATCH 03/16] switch to using the doc.__name__, not doc.formatname --- tldp/driver.py | 12 +++++++----- tldp/sources.py | 2 +- 2 files changed, 8 insertions(+), 6 deletions(-) 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) From 044e14092074bc2b18594360057dea2ec8e069c7 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 11:19:10 -0700 Subject: [PATCH 04/16] 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] + From 48298f3cfb51c0b8c48259baa16c7ce3530e25f1 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 11:21:49 -0700 Subject: [PATCH 05/16] initial crack at debian packaging files --- debian/changelog | 5 +++ debian/compat | 1 + debian/control | 42 ++++++++++++++++++++++ debian/copyright | 84 ++++++++++++++++++++++++++++++++++++++++++++ debian/rules | 14 ++++++++ debian/source/format | 1 + debian/watch | 3 ++ 7 files changed, 150 insertions(+) create mode 100644 debian/changelog create mode 100644 debian/compat create mode 100644 debian/control create mode 100644 debian/copyright create mode 100755 debian/rules create mode 100644 debian/source/format create mode 100644 debian/watch diff --git a/debian/changelog b/debian/changelog new file mode 100644 index 0000000..887735e --- /dev/null +++ b/debian/changelog @@ -0,0 +1,5 @@ +python3-tldp (0.7.5) UNRELEASED; urgency=low + + * python3-tldp + + -- 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..e9bc979 --- /dev/null +++ b/debian/control @@ -0,0 +1,42 @@ +Source: python3-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..d19de6d --- /dev/null +++ b/debian/copyright @@ -0,0 +1,84 @@ +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+ + +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. + . + Except as contained in this notice, the names of individuals + credited with contribution to this software shall not be used in + advertising or otherwise to promote the sale, use or other + dealings in this Software without prior written authorization + from the individuals in question. + . + Any stylesheet derived from this Software that is publically + distributed will be identified with a different name and the + version strings in any derived Software will be changed so that + no possibility of confusion between the derived package and this + Software will exist. + . + Warranty + -------- + 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 NORMAN WALSH OR ANY OTHER + CONTRIBUTOR 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+ + This program 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 program 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, write to the Free Software Foundation, Inc., + 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. + . + On Debian systems, the complete text of the GPL-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..114cf79 --- /dev/null +++ b/debian/rules @@ -0,0 +1,14 @@ +#!/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 + 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))) From d2bfbf42d7c8827e37bb739ee15baed6a0712acd Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 15:34:34 -0700 Subject: [PATCH 06/16] statically created for inclusion into RPM --- docs/ldptool.1 | 528 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 528 insertions(+) create mode 100644 docs/ldptool.1 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. +. From 034a6caffb31e75c9cff61b102d3cecc85880038 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 15:34:46 -0700 Subject: [PATCH 07/16] include manpage --- contrib/tldp.spec | 1 + 1 file changed, 1 insertion(+) diff --git a/contrib/tldp.spec b/contrib/tldp.spec index 6cb5c19..28563cc 100644 --- a/contrib/tldp.spec +++ b/contrib/tldp.spec @@ -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 doc/ldptool.1 %{buildroot}%{_mandir}/man1/ldptool.1 perl -pi -e 's,(/etc/ldptool/ldptool.ini),%config(noreplace) $1,' INSTALLED_FILES %clean From ae41ac7ec4141a1196778c289491bc9b411c7505 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 15:37:30 -0700 Subject: [PATCH 08/16] include in MANIFEST.in and spell "docs" correctly --- MANIFEST.in | 1 + contrib/tldp.spec | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) 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 28563cc..b2b1482 100644 --- a/contrib/tldp.spec +++ b/contrib/tldp.spec @@ -54,7 +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 doc/ldptool.1 %{buildroot}%{_mandir}/man1/ldptool.1 +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 From 32d5591a735f7a6c00e1cefbee51bcca41ff2a41 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 15:50:24 -0700 Subject: [PATCH 09/16] and put manpage in %files list --- contrib/tldp.spec | 1 + 1 file changed, 1 insertion(+) diff --git a/contrib/tldp.spec b/contrib/tldp.spec index b2b1482..548dd24 100644 --- a/contrib/tldp.spec +++ b/contrib/tldp.spec @@ -62,3 +62,4 @@ rm -rf $RPM_BUILD_ROOT %files -f INSTALLED_FILES %defattr(-,root,root) +%{_mandir}/man1/ldptool.1* From fe3c19722ca72da990e1404d51e37731a808ed9a Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 15:51:53 -0700 Subject: [PATCH 10/16] bumping version to tldp-0.7.6 --- contrib/tldp.spec | 6 +++--- setup.py | 2 +- 2 files changed, 4 insertions(+), 4 deletions(-) diff --git a/contrib/tldp.spec b/contrib/tldp.spec index 548dd24..656d396 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.6 +%define unmangled_version 0.7.6 +%define unmangled_version 0.7.6 %define release 1 Summary: processing tools for Asciidoc, DocBook XML, DocBook SGML and Linuxdoc diff --git a/setup.py b/setup.py index 2c6e1b0..141b57e 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.6', license='MIT', author='Martin A. Brown', author_email='martin@linux-ip.net', From fdf3b15889b67d2006b6939aaf49462ecc5d437d Mon Sep 17 00:00:00 2001 From: mabrown Date: Thu, 21 Apr 2016 12:05:18 -0400 Subject: [PATCH 11/16] bumping version to tldp-0.7.7 --- contrib/tldp.spec | 6 +++--- debian/changelog | 10 ++++++++-- setup.py | 2 +- 3 files changed, 12 insertions(+), 6 deletions(-) diff --git a/contrib/tldp.spec b/contrib/tldp.spec index 656d396..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.6 -%define unmangled_version 0.7.6 -%define unmangled_version 0.7.6 +%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 diff --git a/debian/changelog b/debian/changelog index 887735e..83e2876 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,5 +1,11 @@ -python3-tldp (0.7.5) UNRELEASED; urgency=low +python3-tldp (0.7.7) UNRELEASED; urgency=low - * python3-tldp + * creating a manpage to satisfy Lintian, bumping version + + -- 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/setup.py b/setup.py index 141b57e..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.6', + version='0.7.7', license='MIT', author='Martin A. Brown', author_email='martin@linux-ip.net', From 3393a63c8b7978888664053c6a7bf405ca96fbbe Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 16:10:08 -0400 Subject: [PATCH 12/16] be just a touch cleaner (when cleaning) --- debian/rules | 6 +++++- 1 file changed, 5 insertions(+), 1 deletion(-) diff --git a/debian/rules b/debian/rules index 114cf79..04b008b 100755 --- a/debian/rules +++ b/debian/rules @@ -6,9 +6,13 @@ export PYBUILD_NAME=tldp dh $@ --with=python3 --buildsystem=pybuild override_dh_installman: - (cd docs/ && \ + (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 From cde9cf2632255034feb42b57e7601e2c7562f748 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Thu, 21 Apr 2016 16:14:58 -0400 Subject: [PATCH 13/16] decrease verbosity of pybuild --- debian/rules | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/debian/rules b/debian/rules index 04b008b..1009a1c 100755 --- a/debian/rules +++ b/debian/rules @@ -1,5 +1,5 @@ #!/usr/bin/make -f -export PYBUILD_VERBOSE=1 +# export PYBUILD_VERBOSE=1 export PYBUILD_NAME=tldp %: From 87fd09b351d8aea2ea4e1d0203a7e6c5eddea923 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Fri, 22 Apr 2016 07:03:20 -0400 Subject: [PATCH 14/16] head for "unstable"; mention the ITP bug --- debian/changelog | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/debian/changelog b/debian/changelog index 83e2876..cbe873d 100644 --- a/debian/changelog +++ b/debian/changelog @@ -1,6 +1,8 @@ -python3-tldp (0.7.7) UNRELEASED; urgency=low +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 From a54d0ec47ed0bbaa598713389d1356a9ec2fa604 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Fri, 22 Apr 2016 07:03:48 -0400 Subject: [PATCH 15/16] get closer to expectations/convention on copyright file --- debian/copyright | 66 +++++++++++++++++------------------------------- 1 file changed, 23 insertions(+), 43 deletions(-) diff --git a/debian/copyright b/debian/copyright index d19de6d..d1789a1 100644 --- a/debian/copyright +++ b/debian/copyright @@ -9,7 +9,7 @@ License: MIT Files: extras/dsssl/* extras/css/* Copyright: 2000-2003 - Greg Ferguson (gferg@metalab.unc.edu) -License: GPL-2+ +License: GPL-2.0+ Files: extras/dsssl/* extras/xsl/* extras/css/* Copyright: 2000-2002 - David Horton (dhorton@speakeasy.net) @@ -22,63 +22,43 @@ 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: + 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 above copyright notice and this permission notice shall be included + in all copies or substantial portions of the Software. . - Except as contained in this notice, the names of individuals - credited with contribution to this software shall not be used in - advertising or otherwise to promote the sale, use or other - dealings in this Software without prior written authorization - from the individuals in question. - . - Any stylesheet derived from this Software that is publically - distributed will be identified with a different name and the - version strings in any derived Software will be changed so that - no possibility of confusion between the derived package and this - Software will exist. - . - Warranty - -------- - 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 NORMAN WALSH OR ANY OTHER - CONTRIBUTOR 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. + 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+ - This program is free software; you can redistribute it and/or modify +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 program is distributed in the hope that it will be useful, + 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, write to the Free Software Foundation, Inc., - 51 Franklin St, Fifth Floor, Boston, MA 02110-1301, USA. + along with this program. If not, see . - On Debian systems, the complete text of the GPL-2 can be found in - /usr/share/common-licenses/GPL-2 + 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 - From d78430af84a041e2c64de5fe79a7945ff9fa0804 Mon Sep 17 00:00:00 2001 From: "Martin A. Brown" Date: Fri, 22 Apr 2016 07:04:05 -0400 Subject: [PATCH 16/16] change the name of the source package --- debian/control | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/debian/control b/debian/control index e9bc979..59b703d 100644 --- a/debian/control +++ b/debian/control @@ -1,4 +1,4 @@ -Source: python3-tldp +Source: tldp Maintainer: Martin A. Brown Section: python X-Python3-Version: >= 3.4