Man Linux: Main Page and Category List

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)