Provided by: sgml2x_1.0.0-11.4_all bug

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)