sgml2x allows to easily format a SGML or XML
document using DSSSL style-sheets, and provides the following
features:
•
Multiple possible style-sheets per document class
•
Easy specification of style-sheets using aliases, with
support for parameter inheritance
•
Easy integration of new style-sheets by adding a simple
new definition file in a configuration directory
•
The caller can specify a PATH-like list of configuration
directories, defaulting to a system-wide, a per-user, and a
per-project configuration directories
•
Automatic selection of a default style-sheet to be
used, based on assigned priorities
The document-class used to look for the style-sheets, and the
output format, is for now only derived from the name with which
the program is called, so you will want to call this program
through symbolic links like docbook-2-pdf.
sgml2x is a implemented as a shell wrapper
around jade(1) (or, preferably, openjade(1), although
we use the generic name jade throughout this
documentation), jadetex(1) and other tools.
If there is no jadetex.cfg file near the document,
a default one is copied, that enables production of PDF bookmarks.
Options
-c|--catalogcatalog
Use the specified SGML catalog instead of the system
default.
-C|--confdirsdir-list
Use (whitespace-separated) list of configuration
directories. This option is cumulative, i.e. you can use
several -C options and the lists will be
concatenated.
The list elements should be ordered from the most
generic configuration (e.g. system-wide) to the most
specific (e.g. project-wide).
If any directory is provided through this option, the
default directory list will be ignored.
-D|--dssslprocdsssl-processor
Use dsssl-processor to apply the
style-sheet, instead of the default one. This processor has
to support jade-like options, such as
-V.
When this option is not present, the first found in
the dssslproc files from confdirs is taken.
See "Files" for more details.
-h|--help
Display an help message and exit.
-j|--jadedsssl-processor
Obsolete synonym for --dssslproc.
--jadetexfilterperl-filter
Post-process the jadetex output using a perl filter.
This can be useful to force pagebreaks at some
specific places to overcome stylesheet problems, or to force
hyphenations where TeX does not have enough patterns, or do
any other clever transformation you'd think about.
See the examples/command-lines file for possible uses.
-n|--no-act
Print commands instead of running them. Useful to
learn about lower-level tools, and for debugging the
command-line.
-o|--openjade
This option is obsolete.
openjade is now the default when available. Use
--dssslproc or a dssslproc configuration
file to force a specific processor.
This option used to use openjade(1) as a DSSSL processor instead of jade(1).
-O|--jadeoptsjade-options
Additional options to pass to jade(1).
This option is cumulative, you can specify several of them,
the provided options will be concatenated.
-q|--quiet
Set verbosity to quiet
-r|--remarks
Render the content of document remarks in the document
(remark elements in DocBook 4,
comment elements in DocBook 3), making the
produced output an internal-use-only document,
printing a bold warning on the cover.
This is a docclass- and style-sheet-specific feature,
and not all style-sheets will use this.
-s|--stylestyle
Select an output style to override the (eventually
document-derived) default.
Styles currently available for a specific document
class and for each output format are dependent on the
contents of the configuration directories, and can be
displayed with the --help option.
Note that it is good practice to specify this option
in a build procedure, so that you get reproducible results
regardless of the available style-sheets.
-v|--verbose
Increase verbosity. This option can be specified
multiple times.
--verbosity N
Set verbosity to N. The
levels of verbosity are defined as follows:
quiet
Only print errors
default
Only print errors and warnings
verbose
Also print notices
trace
Also print significant commands as
they are run (as --no-act does).
debug
Also print debugging messages
-V|--version
Print the program version and exit.
Configuration
sgml2x uses a configuration directory
tree instead of a configuration file, so that it is easy for other
packages to plug in with a low risk of breaking an existing
setup.
Styles hierarchies are located in directories named
styles in each configuration directory. Old versions
of this program used to put those hierarchies directly in the
configuration directories.
A configuration directory contains one directory for each
known document class, named with a document class nickname
(e.g. docbook). Those docclass directories contain one
sub-directory for each class of output-format (currently, only
html and print are supported).
Currently, implementation issues enforce a limitation on
nicknames for document classes and style-sheets: they can only
contain alphanumeric and underscore characters. This limitation
may be dropped in a future release, but that's not going to happen
before this script gets rewritten in another language.
Each of those directory contain one file per available
style. The names of these files may only contain alphanumeric
characters, and are used as nicknames for the styles. This file
contains lines with a key: value pattern, with
the following keys being currently supported:
Id
The public identifier for the style-sheet
Desc
A short description of the styles, to be displayed in
the help message
pdfOverride, psOverride,
rtfOverride, mifOverride" 10
A dsssl symbol from the print style-sheet to be set to
#t (or a
symbol=value pair, suitable
as argument to jade's -V option), to be used for the given print format.
Only one symbol per override line is allowed. To
define values for several symbols, use several lines.
Inherits
The nickname of a style-sheet this one inherits from,
to avoid needless duplication of style definitions.
Currently, this only causes inheritance of the
*Override parameters.
Priority
An positive integer to help selecting the default
style when one cannot be derived from the document. Higher
values get higher chance of being taken as default. Take
care of using low priorities for hyper-specialized styles
for a generic document-type, so that it does not get used by
error.
For example, the current recommended policy for the
DocBook style-sheets derived from Norman Walsh's is as
follows (and may change if experience proves it to be
inadequate).
10
The base style-sheets, which usually must be
customized.
0
Any style-sheet that was written for an
hyper-specialized purpose (e.g. marketing product
sheet).
1000
A default style for all documents produced by an
organization. Usually a light customization,
featuring layout preferences, the organization's logo,
or such things.
10-100
Miscellaneous generic customizations of the base
style-sheets.
When you write an improved version of a
style-sheet with priority n, you
usually want to select a higher priority.
Files
/etc/sgml/sgml2x/
~/.sgml2x/
./sgml2x/
The default configuration directories, in which the
configuration files are searched for. See documentation for
--confdirs for more details.
confdir/style/
The hierarchy that defines usable styles. See "Configuration" for more details.
confdir/dssslproc
A file containing an ordered list of dsssl processors
to look for, separated by newlines and/or whitespace. Lines
starting with a # character are treated as
comments. Common values include openjade and
jade.
DSSSL processors specified here should accept the
-V and -D jade-compatible command-line
options.
The configuration directories are looked for starting
with the most specific one, so that, with the default
confdirs, the project settings may override user
settings, which in turn may override system settings.
The special value false can be used to
stop the search and prevent looking into more generic
directories. If for example a project must use the
openjade-1.4devel command and no other, it can
specify openjade-1.4devel false in its
dssslproc file.
Caveats
When using openjade-1.4devel as DSSSL processor,
you'll see a complaint about the top-level flow-object generated
by doctype.dsl, and automatic determination of the
document-type will fail. This error is otherwise harmless. Ideas
of how to deal with this, or confirmation that
openjade-1.4devel is too strict, will be appreciated
:)
The future
Planned features for future releases include:
•
Integration of an index generator
•
Integration of a pretty-printing engine for code
examples
•
Specification of transformations to be chained
•
Declaration of subset docclasses to allow the use with
any docclass of the style-sheets that apply to its superset
docclasses.
•
Work in a temporary location so as not to pollute the
working directory with temporary files. This is not as easy
as it sounds, because it breaks a document refers to image
files using relative paths. That may be seen as a jade bug,
however.
Browse the full TODO list and send us more ideas !