Ubuntu Manpage: sgml2x — Easily formats SGML/XML documents using DSSSL style-sheets

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.