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.
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).