<!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook V4.1//EN">

<refentry>
<!--
  <refentryinfo>
    <author>
      <firstname>Yann</firstname>
      <surname>Dirson</surname>
      <affiliation>
	<orgname>Alcove</orgname>
	<address><email>yann.dirson@fr.alcove.com</email></address>
      </affiliation>
    </author>
  </refentryinfo>
-->

  <refmeta>
    <refentrytitle>sgml2x</refentrytitle>
    <manvolnum>1</manvolnum>
    <refmiscinfo>Alcove documentation tool-chain</refmiscinfo>
  </refmeta>

  <refnamediv>
    <refname>sgml2x</refname>
    <refpurpose>Easily formats SGML/XML documents using DSSSL style-sheets</refpurpose>
  </refnamediv>

  <refsynopsisdiv>
    <cmdsynopsis>
      <command>sgml2x</command>
      <arg><replaceable>options</></arg>
      <arg choice="req" rep="repeat"><group>
	  <arg><replaceable>sgmlfile</></arg>
	  <arg><replaceable>xmlfile</></arg>
	</group></arg>
    </cmdsynopsis>

    <cmdsynopsis>
      <command><replaceable>docclass</>-2-<replaceable>targetformat</></command>
      <arg><replaceable>options</></arg>
      <arg choice="req" rep="repeat"><group>
	  <arg><replaceable>sgmlfile</></arg>
	  <arg><replaceable>xmlfile</></arg>
	</group></arg>
    </cmdsynopsis>
  </refsynopsisdiv>

  <refsect1>
    <title>Description</title>

    <para><application>sgml2x</> allows to easily format a SGML or XML
    document using DSSSL style-sheets, and provides the following
    features:</para>

    <itemizedlist>
      <listitem>
	<para>Multiple possible style-sheets per document class</para>
      </listitem>
      <listitem>
	<para>Easy specification of style-sheets using aliases, with
	support for parameter inheritance</para>
      </listitem>
      <listitem>
	<para>Easy integration of new style-sheets by adding a simple
	new definition file in a configuration directory</para>
      </listitem>
      <listitem>
	<para>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</para>
      </listitem>
      <listitem>
	<para>Automatic selection of a default style-sheet to be
	used, based on assigned priorities</para>
      </listitem>
      <listitem>
	<para>Pass arbitrary options to <citerefentry>
	<refentrytitle>jade</> <manvolnum>1</> </citerefentry></para>
      </listitem>
    </itemizedlist>

    <para>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 <command>docbook-2-pdf</>.</para>

    <para><application>sgml2x</> is a implemented as a shell wrapper
    around <citerefentry> <refentrytitle>jade</> <manvolnum>1</>
    </citerefentry> (or, preferably, <citerefentry>
    <refentrytitle>openjade</> <manvolnum>1</> </citerefentry>, although
    we use the generic name <command>jade</> throughout this
    documentation), <citerefentry> <refentrytitle>jadetex</>
    <manvolnum>1</> </citerefentry> and other tools.</para>

    <para>If there is no <filename>jadetex.cfg</> file near the document,
    a default one is copied, that enables production of PDF bookmarks.</para>
  </refsect1>

  <refsect1>
    <title>Options</title>

    <glosslist>
      <glossentry>
	<glossterm><option>-c</>|<option>--catalog</> <replaceable>catalog</></glossterm>

	<glossdef>
	  <para>Use the specified SGML catalog instead of the system
	  default.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-C</option>|<option>--confdirs</option> <replaceable>dir-list</></glossterm>
	<glossdef>
	  <para>Use (whitespace-separated) list of configuration
	  directories.  This option is cumulative, i.e. you can use
	  several <option>-C</option> options and the lists will be
	  concatenated.</para>

	  <para>The list elements should be ordered from the most
	  generic configuration (e.g. system-wide) to the most
	  specific (e.g. project-wide).</para>

	  <para>If any directory is provided through this option, the
	  default directory list will be ignored.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-h</>|<option>--help</></glossterm>
	<glossdef>
	  <para>Display an help message and exit.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-j</>|<option>--jade</>|<option>--dssslproc</> <replaceable>dsssl-processor</></glossterm>
	<glossdef>
	  <para>Use <replaceable>dsssl-processor</> to apply the
	  style-sheet, instead of the default one.  This processor has
	  to support <command>jade</>-like options, such as
	  <option>-V</>.</para>

	  <para>When this option is not present, the first found in
	  the <filename>dssslproc</> files from confdirs is taken.
	  See <xref linkend="files"> for more details.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-n</option>|<option>--no-act</option></glossterm>
	<glossdef>
	  <para>Print commands instead of running them.  Useful to
	  learn about lower-level tools, and for debugging the
	  command-line.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-o</option>|<option>--openjade</option></glossterm>
	<glossdef>
	  <para><emphasis role="strong">This option is obsolete</>.
	  <command>openjade</> is now the default when available.  Use
	  <option>--jade</> or a <filename>dssslproc</> configuration
	  file to force a specific processor.</para>

	  <para>This option used to use <citerefentry>
	  <refentrytitle>openjade</> <manvolnum>1</> </citerefentry>
	  as a DSSSL processor instead of <citerefentry>
	  <refentrytitle>jade</> <manvolnum>1</>
	  </citerefentry>.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-O</>|<option>--jadeopts</> <replaceable>jade-options</></glossterm>
	<glossdef>
	  <para>Additional options to pass to <citerefentry>
	  <refentrytitle>jade</> <manvolnum>1</> </citerefentry>.
	  This option is cumulative, you can specify several of them,
	  the provided options will be concatenated.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-q</option>|<option>--quiet</option></glossterm>
	<glossdef>
	  <para>Set verbosity to <literal>quiet</></para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-r</>|<option>--remarks</></glossterm>
	<glossdef>
	  <para>Render the content of document remarks in the document
	  (<sgmltag>remark</> elements in DocBook 4,
	  <sgmltag>comment</> elements in DocBook 3), making the
	  produced output an <emphasis>internal-use-only document</>,
	  printing a bold warning on the cover.</para>

	  <para>This is a docclass- and style-sheet-specific feature,
	  and not all style-sheets will use this.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-s</>|<option>--style</> <replaceable>style</></glossterm>
	<glossdef>
	  <para>Select an output style to override the (eventually
	  document-derived) default.</para>

	  <para>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 <option>--help</option> option.</para>

	  <para>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.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-v</option>|<option>--verbose</option></glossterm>
	<glossdef>
	  <para>Increase verbosity.  This option can be specified
	  multiple times.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>--verbosity <replaceable>N</></option></glossterm>
	<glossdef>
	  <para>Set verbosity to <replaceable>N</replaceable>.  The
	  levels of verbosity are defined as follows:</para>

	  <variablelist>
	    <varlistentry>
	      <term><literal>quiet</></term>
	      <listitem>
		<para>Only print errors</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>default</></term>
	      <listitem>
		<para>Only print errors and warnings</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>verbose</></term>
	      <listitem>
		<para>Also print notices</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>trace</></term>
	      <listitem>
		<para>Also print significant commands as
		  they are run (as <option>--no-act</> does).</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term><literal>debug</></term>
	      <listitem>
		<para>Also print debugging messages</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><option>-V</>|<option>--version</></glossterm>
	<glossdef>
	  <para>Print the program version and exit.</para>
	</glossdef>
      </glossentry>

    </glosslist>
  </refsect1>

  <refsect1 id="config">
    <title>Configuration</title>

    <para><application>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.</para>

    <para>Styles hierarchies are located in directories named
    <filename>styles</> in each configuration directory.  Old versions
    of this program used to put those hierarchies directly in the
    configuration directories.</para>

    <para>A configuration directory contains one directory for each
    known document class, named with a document class nickname
    (e.g. <literal>docbook</>).  Those docclass directories contain one
    sub-directory for each class of output-format (currently, only
    <literal>html</> and <literal>print</> are supported).</para>

    <para>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.</para>

    <para>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 <literal>key: value</literal> pattern, with
    the following keys being currently supported:</para>

    <glosslist>
      <glossentry>
	<glossterm><literal>Id</></glossterm>
	<glossdef>
	  <para>The public identifier for the style-sheet</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><literal>Desc</></glossterm>
	<glossdef>
	  <para>A short description of the styles, to be displayed in
	  the help message</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><literal>pdfOverride</>, <literal>psOverride</>,
	<literal>rtfOverride</>, <literal>mifOverride</></glossterm>
	<glossdef>
	  <para>A dsssl symbol from the print style-sheet to be set to
	  <literal>#t</> (or a
	  <replaceable>symbol</>=<replaceable>value</> pair, suitable
	  as argument to <command>jade</>'s <option>-V</>
	  option), to be used for the given print format.</para>

	  <para>Only one symbol per override line is allowed.  To
	  define values for several symbols, use several lines.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><literal>Inherits</></glossterm>
	<glossdef>
	  <para>The nickname of a style-sheet this one inherits from,
	  to avoid needless duplication of style definitions.</para>

	  <para>Currently, this only causes inheritance of the
	  <literal>*Override</> parameters.</para>
	</glossdef>
      </glossentry>

      <glossentry>
	<glossterm><literal>Priority</></glossterm>
	<glossdef>
	  <para>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.</para>

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

	  <variablelist>
	    <varlistentry>
	      <term>10</term>
	      <listitem>
		<para>The base style-sheets, which usually must be
		customized.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>0</term>
	      <listitem>
		<para>Any style-sheet that was written for an
		hyper-specialized purpose (e.g. marketing product
		sheet).</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>1000</term>
	      <listitem>
		<para>A default style for all documents produced by an
		organization.  Usually a light customization,
		featuring layout preferences, the organization's logo,
		or such things.</para>
	      </listitem>
	    </varlistentry>
	    <varlistentry>
	      <term>10-100</term>
	      <listitem>
		<para>Miscellaneous generic customizations of the base
		style-sheets.</para>

		<para>When you write an improved version of a
		style-sheet with priority <replaceable>n</>, you
		usually want to select a higher priority.</para>
	      </listitem>
	    </varlistentry>
	  </variablelist>
	</glossdef>
      </glossentry>
    </glosslist>
  </refsect1>

  <refsect1 id="files">
    <title>Files</title>

    <variablelist>
      <varlistentry>
	<term><filename>/etc/sgml/sgml2x/</filename></term>
	<term><filename>~/.sgml2x/</filename></term>
	<term><filename>./sgml2x/</filename></term>
	<listitem>
	  <para>The default configuration directories, in which the
	  configuration files are searched for.  See documentation for
	  <option>--confdirs</> for more details.</para>
	</listitem>
      </varlistentry>

      <varlistentry>
	<term><filename><replaceable>confdir</>/style/</filename></term>
	<listitem>
	  <para>The hierarchy that defines usable styles.  See <xref
	  linkend="config"> for more details.</para>
	</listitem>
      </varlistentry>

      <varlistentry id="dssslproc">
	<term><filename><replaceable>confdir</>/dssslproc</></term>
	<listitem>
	  <para>A file containing an ordered list of dsssl processors
	  to look for, separated by newlines and/or whitespace.  Lines
	  starting with a <literal>#</> character are treated as
	  comments.  Common values include <literal>openjade</> and
	  <literal>jade</>.</para>

	  <para>DSSSL processors specified here should accept the
	  <option>-V</> and <option>-D</> jade-compatible command-line
	  options.</para>

	  <para>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.</para>

	  <para>The special value <literal>false</> can be used to
	  stop the search and prevent looking into more generic
	  directories.  If for example a project must use the
	  <command>openjade-1.4devel</> command and no other, it can
	  specify <literal>openjade-1.4devel false</> in its
	  <filename>dssslproc</> file.</para>
	</listitem>
      </varlistentry>
    </variablelist>
  </refsect1>

  <refsect1>
    <title>Caveats</title>

    <para>When using <command>openjade-1.4devel</> as DSSSL processor,
    you'll see a complaint about the top-level flow-object generated
    by <filename>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
    <command>openjade-1.4devel</> is too strict, will be appreciated
    :)</para>
  </refsect1>

  <refsect1>
    <title>The future</title>

    <para>Planned features for future releases include:</para>

    <itemizedlist>
      <listitem>
	<para>Integration of an index generator</para>
      </listitem>
      <listitem>
	<para>Integration of a pretty-printing engine for code
	examples</para>
      </listitem>
      <listitem>
	<para>Specification of transformations to be chained</para>
      </listitem>
      <listitem>
	<para>Declaration of subset docclasses to allow the use with
	any docclass of the style-sheets that apply to its superset
	docclasses.</para>
      </listitem>
      <listitem>
	<para>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.</para>
      </listitem>
    </itemizedlist>

    <para>Browse the full TODO list and send us more ideas !</para>
  </refsect1>

  <refsect1>
    <title>Copyright</title>

    <para>Copyright &copy; 2001-2003 Alcove &amp; Yann Dirson.</para>

    <para><application>sgml2x</> is licensed under the GNU General
    Public License, version 2.</para>

    <para>This documentation is licensed under the GNU Free
    Documentation License, version 1.</para>
  </refsect1>

  <refsect1>
    <title>Contact us</title>

    <para><application>sgml2x</> is part of the <ulink
    url="http://www.alcove-labs.org/en/software/alcovebook/">AlcoveBook
    project</>.  Please use the <ulink
    url="https://savannah.gnu.org/mail/?group_id=533">AlcoveBook
    mailing lists</> to get in touch with developers and
    users.</para>

    <para>The list of bugs and feature requests is available <ulink
    url="https://savannah.gnu.org/support/?group_id=533">through a Web
    interface</>.  Please use it to submit problems and ideas.</para>
  </refsect1>

  <refsect1>
    <title>See also</title>
    
    <para><citerefentry> <refentrytitle>openjade</> <manvolnum>1</>
    </citerefentry>, <citerefentry> <refentrytitle>jade</>
    <manvolnum>1</> </citerefentry>, <citerefentry>
    <refentrytitle>jadetex</> <manvolnum>1</> </citerefentry>,
    <citerefentry> <refentrytitle>collateindex.pl</> <manvolnum>1</>
    </citerefentry>.</para>
  </refsect1>
</refentry>
