sgml2docs - Generate HTML or LaTeX files from an SGM or XML source file, marked up using one of the Starlink DTDs.

Description

Given a single argument, specifying an SGML source file, this uses the Starlink DSSSL stylesheets to process this into a collection of HTML files and GIFs, or LaTeX and EPS files places them in a subdirectory named after the source file, and then creates a tarball in the source directory holding the generated files.

Argument list

arg1 = filename (Given)

SGML or XML file to be processed. The input file is taken to be SGML or XML depending on whether its file extension is .sgml or .xml. There is not, at present, any other way of forcing this. If there's no extension, or the script doesn't recognise the extension, it takes a guess at SGML; if that was a bad move, you'll soon know about it.

Examples

Example 1:

sgml2docs --html --tarball=mydocs.tar docfile.sgml

This converts the document docfile.sgml to a set of HTML files, bundling the result into a tarball mydocs.tar, rather than the default based on the source file's name.

Example 2:

sgml2docs --latex --options=cts-sect,cts-appx docfile.sgml

Converts the document to a bundle of files which may be LaTeXed. The page breaks between sections are suppressed.

Authors

• Norman Gray

Options

--html

generate HTML (the default).

--htmlsingle

generate HTML in a single file. Not really supported, so not often tested.

--latex

generate LaTeX.

--packagedir=my-dir

package up the generated files into a directory called `my-dir'. The default directory is based on the input filename.

--tarball=my.tar

bundle the package-dir into a tarball named `my.tar'. The default tarball name is based on the input filename.

--jadeflags=flags

add the given flags to the invocation of Jade. See the Jade documentation for details.

--ignore-manifest

Do not use the generated manifest when bundling up files, but instead just bundle everything in sight. You will need to use this only if there is some bug in the mechanism which generates the manifest.

--quiet

Don't chatter (not completely silent, since it doesn't suppress output from TeX).

--options=opt,opt,...

set format-specific options.

With --latex: options are cts-sect and cts-appx, which suppresses any page-break between sections in the main text and appendices; and onepass-latex, which generates LaTeX which should need only a single pass to produce a table of contents.

With --html: options are nonorm, simplenorm and sgmlnorm. These control how much the generated HTML files are normalised. In the first case, no normalisation is done: this is fine if you simply want to display the resulting HTML, but the resulting output confuses the HTX system something rotten. The simple normalisation (done using sed) is at least more readable, but still isn't enough for HTX; the full normalisation, using the sgmlnorm application should indeed be bulletproof, but is also rather slow. the default is currently sgmlnorm, but this is subject to change.

--help

display usage and exit.

--version

display version and exit.

--debug

do some debugging. Specifically, don't tidy up at end.

-n

don't actually run anything, just show what would happen.

Environment

Requires that dvi2bitmap is in the PATH The script is currently rather sensitive to the available version of dvi2bitmap, and does a rather cautious check.

The script creates a work directory and does its processing there. If it is necessary to run BibTeX, the directory containing the source file is prepended to the BIBINPUTS environment variable.