diff options
Diffstat (limited to 'doc/refentry/jw.sgml')
| -rw-r--r-- | doc/refentry/jw.sgml | 643 |
1 files changed, 643 insertions, 0 deletions
diff --git a/doc/refentry/jw.sgml b/doc/refentry/jw.sgml new file mode 100644 index 0000000..d8d7de7 --- /dev/null +++ b/doc/refentry/jw.sgml @@ -0,0 +1,643 @@ +<refentry id="jw"> + <docinfo> + <author> + <firstname>Eric</firstname> <surname>Bischoff</surname> + <affiliation> + <address><email>ebisch@cybercable.tm.fr</email></address> + </affiliation> + </author> + </docinfo> + <refmeta> + <refentrytitle>jw</refentrytitle> + <manvolnum>1</manvolnum> + </refmeta> + + <refnamediv> + <refname>jw</refname> + <refname>docbook2dvi</refname> + <refname>docbook2html</refname> + <refname>docbook2man</refname> + <refname>docbook2pdf</refname> + <refname>docbook2ps</refname> + <refname>docbook2rtf</refname> + <refname>docbook2tex</refname> + <refname>docbook2texi</refname> + <refname>docbook2txt</refname> + <refpurpose>(Jade Wrapper) converts SGML files to other formats</refpurpose> + </refnamediv> + + <refsynopsisdiv> + <cmdsynopsis> + <command>jw</command> + <group choice="opt"><arg><option>-f</option> + <replaceable>frontend</replaceable></arg> + <arg><option>--frontend</option> + <replaceable>frontend</replaceable></arg> + </group><sbr> + + <group choice="opt"><arg><option>-b</option> + <replaceable>backend</replaceable></arg> + <arg><option>--backend</option> <replaceable>backend</replaceable></arg> + </group><sbr> + + <group choice="opt"><arg><option>-c</option> <replaceable>file</replaceable></arg> + <arg><option>--cat</option> <replaceable>file</replaceable></arg> + </group><sbr> + + <group choice="opt"><arg><option>-n</option></arg> + <arg><option>--nostd</option></arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-d</option> + <replaceable>file</replaceable>|default|none</arg> + <arg><option>--dsl</option> + <replaceable>file</replaceable>|default|none</arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-l</option> <replaceable>file</replaceable></arg> + <arg><option>--dcl</option> <replaceable>file</replaceable></arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-s</option> <replaceable>path</replaceable></arg> + <arg><option>--sgmlbase</option> <replaceable>path</replaceable></arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-p</option> <replaceable>program</replaceable></arg> + <arg><option>--parser</option> <replaceable>program</replaceable></arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-o</option> <replaceable>directory</replaceable></arg> + <arg><option>--output</option> <replaceable>directory</replaceable></arg> + </group><sbr> + + <arg choice="opt"><option>-V</option> + <replaceable>variable</replaceable>[=<replaceable>value</replaceable>]</arg><sbr> + + <group choice="opt"> + <arg><option>-u</option></arg> + <arg><option>--nochunks</option></arg> + </group> + + <group choice="opt"> + <arg><option>-i</option> <replaceable>section</replaceable></arg> + <arg><option>--include</option> <replaceable>section</replaceable></arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-w</option> <replaceable>type</replaceable>|list</arg> + <arg><option>--warning</option> <replaceable>type</replaceable>|list</arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-e</option> <replaceable>type</replaceable>|list</arg> + <arg><option>--error</option> <replaceable>type</replaceable>|list</arg> + </group><sbr> + + <group choice="opt"> + <arg><option>-h</option></arg> + <arg><option>--help</option></arg> + </group> + + <group choice="opt"> + <arg><option>-v</option></arg> + <arg><option>--version</option></arg> + </group><sbr> + + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2dvi</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2html</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2man</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2pdf</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2ps</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2rtf</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2tex</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2texi</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + + <cmdsynopsis> + <command>docbook2txt</command> + <arg choice="req"><replaceable>SGML-file</replaceable></arg> + </cmdsynopsis> + </refsynopsisdiv> + + <refsect1> + <title>Description</title> + + <para>The <application>jw</application> shell script allows to + convert a DocBook file (or some other SGML-based format) to + other formats (including HTML, RTF, PS and PDF) with + an easy-to-understand syntax. It hides most of Jade's + or OpenJade complexity and adds comfortable features.</para> + + <para>Other scripts like <application>docbook2html</application>, + <application>docbook2rtf</application> or + <application>docbook2ps</application> provide different ways of + calling <application>jw</application> that might be easier to + remember.</para> + + <para>For the moment, jw does not handle XML, but only SGML.</para> + + <para>This utility assumes that several other components are + installed. The list includes: + <itemizedlist> + <listitem> + <para>the ISO character entities for SGML</para> + </listitem> + <listitem> + <para>James Clark's DSSSL engine, jade, or an equivalent parser + like OpenJade</para> + </listitem> + <listitem> + <para>the DocBook DTD from the OASIS consortium</para> + </listitem> + <listitem> + <para>Norman Walsh's DocBook modular style sheets (or some other + set of DSSSL style sheets)</para> + </listitem> + <listitem> + <para>Sebastian Rahtz's jadetex set of TeX macros for jade + (for backends intended to "printing" formats like PDF, RTF or + PostScript)</para> + </listitem> + <listitem> + <para>A perl interpreter (for backends that use perl)</para> + </listitem> + <listitem> + <para>SGMLSpm from CPAN (for backends that use sgmls)</para> + </listitem> + <listitem> + <para>Lynx HTML browser (for the <filename>txt</filename> + backend)</para> + </listitem> + </itemizedlist> + </para> + + <para>The jw script is basically called like this:</para> + + <screen>jw mydoc.sgml</screen> + + <para>where <filename>mydoc.sgml</filename> is a SGML file.</para> + + <para>The command line above uses default options: it converts + from DocBook (the default frontend) to HTML (the default backend), + does not put the result in a subdirectory (unless specified + otherwise in the style sheets), etc.</para> + + <para>In this example, the "mydoc" file name as well as the ".sgml" + extension can be replaced by anything else. Current extensions + for SGML DocBook files include ".sgml", ".sgm", ".docbook", and + ".db". The processed file <filename>mydoc.sgml</filename> can + be in any other directory than the current one.</para> + + <para>Here we have chosen to generate HTML output. In fact we can + use any of the backends stored in the <filename>backends/</filename> + subdirectory of the DocBook-utils distribution directory (usually + <filename>/usr/share/sgml/docbook/utils-&version;</filename>). + Similarly, you can use any frontend defined in the + <filename>frontends/</filename> subdirectory to convert from another + input format.</para> + + <para>This sample command creates one or many HTML files with + arbitrary file names in the current directory. This default behavior + can be changed through command line options and/or customization + style sheets.</para> + + </refsect1> + + <refsect1> + <title>Options</title> + + <para>The following options apply to the conversion script:</para> + + <variablelist> + <varlistentry> + <term><cmdsynopsis><group><arg><option>-f</option> + <replaceable>frontend</replaceable></arg> + <arg><option>--frontend</option> + <replaceable>frontend</replaceable></arg></group></cmdsynopsis> + </term> + <listitem> + <para>Allows to specify another frontend than default <filename>docbook</filename>. + The list of currently available frontends is: + <variablelist> + <varlistentry> + <term><filename>docbook</filename></term> + <listitem><para>Converts docbook with Norman Walsh's + style sheets. This frontend searches in the + subdirectories of the base SGML directory for a + file named <filename>html/docbook.dsl</filename> or + <filename>print/docbook.dsl</filename> (depending on the + backend's type: html or print).</para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group><arg><option>-b</option> + <replaceable>backend</replaceable></arg> + <arg><option>--backend</option> + <replaceable>backend</replaceable></arg></group></cmdsynopsis> + </term> + <listitem> + <para>Allows to specify another backend than default + <filename>HTML</filename>. The list of currently available + backends is: + <variablelist> + <varlistentry> + <term><filename>dvi</filename></term> + <listitem><para>Converts to DVI (DeVice Independant + files) by calling <application>Jade</application> or + <application>OpenJade</application>.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>html</filename></term> + <listitem><para>Converts to HTML (HyperText Markup + Language) by calling <application>Jade</application> + or <application>OpenJade</application>.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>man</filename></term> + <listitem><para>Converts a refentry to a Unix manual page + by calling docbook2man. Does not work with other SGML + document types than DocBook.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>pdf</filename></term> + <listitem><para>Converts to PDF (Portable Document + Format) by calling <application>Jade</application> or + <application>OpenJade</application>.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>ps</filename></term> + <listitem><para>Converts to PostScript by + calling <application>Jade</application> or + <application>OpenJade</application>.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>rtf</filename></term> + <listitem><para>Converts to RTF (Rich Text Format) + by calling <application>Jade</application> or + <application>OpenJade</application>. The resulting file can + then be inported into <application>MS Word</application> + or one of its Linux replacement programs.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>tex</filename></term> + <listitem><para>Converts to TeX by calling <application>Jade</application> or + <application>OpenJade</application>.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>texi</filename></term> + <listitem><para>Converts to GNU TeXinfo pages by calling + docbook2texi. Does not work with other SGML document types + than DocBook.</para></listitem> + </varlistentry> + <varlistentry> + <term><filename>txt</filename></term> + <listitem><para>Converts to a bare text file + by calling <application>Jade</application> + or <application>OpenJade</application>, then + <application>Lynx</application>.</para></listitem> + </varlistentry> + </variablelist> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-c</option> <replaceable>file</replaceable></arg> + <arg><option>--cat</option> <replaceable>file</replaceable></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Allows to use an extra SGML Open Catalog that will list + other files like customization style sheets, adaptations to the + DocBook Document Type Definition, special character entities, + etc. This catalog is added to the list of catalogs determined + by the script (see option <option>--nostd</option> below)</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-n</option></arg> + <arg><option>--nostd</option></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Do not use the standard SGML Open Catalogs. Normally, + the standard catalogs list is determined like this: + <itemizedlist> + <listitem> + <para>if the centralized catalog exists, then + use it. The centralized catalog is a list of all + catalogs that might be necessary that usually + resides in <filename>/etc/sgml</filename>. Its + name is provided by the frontend, for example + the <filename>docbook</filename> frontend returns + <filename>/etc/sgml/sgml-docbook.cat</filename>.</para> + </listitem> + <listitem> + <para>Otherwise, take all the files + named <filename>catalog</filename> from the + subdirectories of the SGML base directory (usually + <filename>/usr/share/sgml</filename>).</para> + </listitem> + </itemizedlist> + This option is useful in conjunction with the + <option>--cat</option> option to use only the catalogs that + are specified on the command line.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-d</option> + <replaceable>file</replaceable>|default|none</arg> + <arg><option>--dsl</option> + <replaceable>file</replaceable>|default|none</arg> + </group></cmdsynopsis></term> + <listitem> + <para>Allows to use a customized style sheet instead + of the default one.</para> + <para>A "target" starting with a hash mark "#" can be appended + to the file name. As a result, only the corresponding part + of the style sheet is executed (the "style specification" whose + "identificator" is equal to the target's name). A common use of this + mechanism is to define "#html" and "#print" targets to trigger + the corresponding part of a replacement style sheet which is + common for both HTML and printout conversion.</para> + <para>By replacing the file name with "default", the default + style sheet provided with the frontend is used. For example, the + <filename>docbook</filename> frontend returns + <filename>./docbook.dsl#html</filename> (or + <filename>./docbook.dsl#print</filename>) in the SGML base + directory.</para> + <para>By replacing the file name with "none", no replacement + style sheet is used, not even the default style sheet. The style + sheet which is used is also determined by the frontend. For + example, the <filename>docbook</filename> frontend returns + Norman Walsh's <filename>html/docbook.dsl</filename> (or + <filename>print/docbook.dsl</filename>) found somewhere below + the SGML base directory.</para> + <para>If no --dsl option is specified, then "--dsl default" is + used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-l</option> <replaceable>file</replaceable></arg> + <arg><option>--dcl</option> <replaceable>file</replaceable></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Allows to use a customized SGML declaration instead + of the default one. The file name of the default SGML + declaration is not set for SGML files, and is set to + <filename>xml.dcl</filename> in the SGML base directory + for XML files.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-s</option> <replaceable>path</replaceable></arg> + <arg><option>--sgmlbase</option> <replaceable>path</replaceable></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Allows to use another location for the SGML base + directory. This is the directory below which all SGML DTDs, + style sheets, entities, etc are installed. The default value + is <filename>/usr/share/sgml</filename>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-p</option> <replaceable>program</replaceable></arg> + <arg><option>--parser</option> <replaceable>program</replaceable></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Specify the parser to use (<application>Jade</application> + or <application>OpenJade</application>) if several + are installed. If this option is not specified, + the script first tries to use Jade, then it tries + <application>OpenJade</application>.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-o</option> <replaceable>directory</replaceable></arg> + <arg><option>--output</option> <replaceable>directory</replaceable></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Set output directory where all the resulting files will + be stored. If the style sheets define a subdirectory where to + store the resulting files too, the subdirectory defined by the + style sheets will be placed below the subdirectory defined by + this option.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group><arg><option>-V</option> + <replaceable>variable</replaceable>=[<replaceable>value</replaceable>]</arg> + </group></cmdsynopsis></term> + <listitem> + <para>Set a variable (to a value, if one is specified).</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-u</option></arg> + <arg><option>--nochunks</option></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Output only one big file. This option is useful only + when generating HTML, because the output can be split into + several files. This option overrides the setting that may be + done in the style sheets.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-i</option> <replaceable>section</replaceable></arg> + <arg><option>--include</option> <replaceable>section</replaceable></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Declare a SGML marked section as "include". A SGML marked + section is a kind of conditional part of a document. If it is + declared "ignore", it will be left ignored, otherwise it will + be processed. An example of such a marked section would be: + <informalexample><para><literallayout> + <DOCTYPE mydoc [ + <!ENTITY % confidential "ignore"> + ]> + <mydoc> + ... + <![ %confidential [ Some confidential text... ]]> + ... + </mydoc> + </literallayout></para></informalexample> + </para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-w</option> <replaceable>type</replaceable>|list</arg> + <arg><option>--warning</option> <replaceable>type</replaceable>|list</arg> + </group></cmdsynopsis></term> + <listitem> + <para>Enables or disables the display of given types of warnings. + Several -w options might be entered on the command line. + Warning types that start with "no-" disable the corresponding + warnings, the other types enable them.</para> + <para>If the warning type is replaced with "list", then + a list of allowed warning types is displayed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-e</option> <replaceable>type</replaceable>|list</arg> + <arg><option>--error</option> <replaceable>type</replaceable>|list</arg> + </group></cmdsynopsis></term> + <listitem> + <para>Disables given types of errors. + Several -e options might be entered on the command line. + All error types start with "no-".</para> + <para>If the error type is replaced with "list", then + a list of allowed error types is displayed.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-h</option></arg> + <arg><option>--help</option></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Print a short help message and exit</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><cmdsynopsis><group> + <arg><option>-v</option></arg> + <arg><option>--version</option></arg> + </group></cmdsynopsis></term> + <listitem> + <para>Print the version identifier and exit</para> + </listitem> + </varlistentry> + </variablelist> + + </refsect1> + + <refsect1> + <title>Files</title> + + <variablelist> + + <varlistentry> + <term><filename>/etc/sgml/sgml-docbook.cat</filename></term> + <listitem> + <para>Centralized SGML open catalog. This file name might + vary if another frontend than <filename>docbook</filename> + is used.</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/sgml/docbook/utils-&version;/backends</filename></term> + <listitem> + <para>The various backends</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/sgml/docbook/utils-&version;/frontends</filename></term> + <listitem> + <para>The various frontends</para> + </listitem> + </varlistentry> + + <varlistentry> + <term><filename>/usr/share/sgml/docbook/utils-&version;/helpers</filename></term> + <listitem> + <para>The various helper scripts like docbook2man or docbook2texi</para> + </listitem> + </varlistentry> + </variablelist> + </refsect1> + + <refsect1> + <title>Authors</title> + + <para>Eric Bischoff (jw shell script and a few backends), + Jochem Huhmann (the <filename>man</filename> and + <filename>texi</filename> backends)</para> + </refsect1> + + <refsect1> + <title>See Also</title> + + <para><citerefentry><refentrytitle>docbook2man-spec.pl</refentrytitle><manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>docbook2texi-spec.pl</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, + <citerefentry><refentrytitle>install-catalog</refentrytitle> + <manvolnum>8</manvolnum></citerefentry>, + <citerefentry><refentrytitle>nsgmls</refentrytitle> + <manvolnum>1</manvolnum></citerefentry>, <ulink + url="http://sources.redhat.com/docbook-tools/">docbook-utils + homepage</ulink>.</para> + </refsect1> + +</refentry> + +<!-- Local Variables: --> +<!-- sgml-parent-document: "../docbook-utils.sgml" --> +<!-- End: --> |