NAME
sgml2x — Easily formats SGML/XML documents using DSSSL style-sheets
SYNOPSIS
sgml2x [options] [sgmlfile | xmlfile ]
docclass-2-targetformat [options] [sgmlfile | xmlfile ]
Description
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
· Pass arbitrary options to jade(1)
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|--catalog catalog
Use the specified SGML catalog instead of the system default.
-C|--confdirs dir-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|--dssslproc dsssl-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|--jade dsssl-processor
Obsolete synonym for --dssslproc.
--jadetexfilter perl-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|--jadeopts jade-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|--style style
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 !
Copyright
Copyright © 2001-2003 Alcove & Yann Dirson.
sgml2x is licensed under the GNU General Public License, version 2.
This documentation is licensed under the GNU Free Documentation
License, version 1.
Contact us
sgml2x is part of the AlcoveBook project (link to URL
http://www.alcove-labs.org/en/software/alcovebook/) . Please use the
AlcoveBook mailing lists (link to URL
https://savannah.gnu.org/mail/?group_id=533) to get in touch with
developers and users.
The list of bugs and feature requests is available through a Web
interface (link to URL https://savannah.gnu.org/support/?group_id=533)
. Please use it to submit problems and ideas.
See also
openjade(1), jade(1), jadetex(1), collateindex.pl(1).
sgml2x(1)