linuxdoc



LINUXDOC(1)                                                        LINUXDOC(1)




NAME

       linuxdoc - LinuxDoc DTD SGML converter to other output format


SYNOPSIS

       linuxdoc --backend=format
       --papersize=size  --language=lang  --charset=char  --style=file --debug
       --define attribute=value     --include entity      [backend-options...]
       file(.sgml)

       or (Old, obsoleted usage)
       sgmlxxxx [generic-options...] [backend-options...]   file(.sgml)


DESCRIPTION

       The linuxdoc suite is a collection of text formatters which understands
       a LinuxDoc DTD SGML source file. Each formatter (or "back-end") renders
       the  source file into a variety of output formats, including HTML, TeX,
       DVI, PostScript, plain text, and groff(1) source in manual-page format.
       The  linuxdoc  suite  is  provided  for backward compatibility, because
       there are still many useful documents  written  in  LinuxDoc  DTD  sgml
       source.

       The markup language(s) accepted by these formatters is described in the
       Linuxdoc-Tools User’s Guide.  They are variants  of  an  SGML  document
       type  definition originally designed by Matt Welsh for Linux documenta-
       tion.


GENERIC-OPTIONS

       Most command-line options are accepted by all  back-ends.   Some  back-
       ends  have  additional  specific  options to control rendering to their
       particular output format.  Here are the common options:

       --backend=format, -B
              Set the backend for specified format. Default  is  none  of  the
              actual format, but just output the usage of this suites.  Avail-
              able formats are: html, info, latex, lyx, rtf, txt, check.

       --papersize=size, -p
              Set the paper size.  Default is ‘‘letter’’.  You may also  spec-
              ify ‘‘a4’’ size (European 297x210mm paper).

       --language=lang, -l
              Specify  the  language  of  the  document (this may change which
              style files are used for formatting by a back end).  The default
              language is English. Run an LinuxDoc-tools command without argu-
              ments to see the list of valid language codes.

       --charset=chars, -c
              Specify the output character encoding.   Defaults  to  ‘‘ascii’’
              selecting  the ASCII set; you may specify "latin" to specify the
              ISO 8859-1 (Latin-1) character set.  Also, ‘‘nippon’’ and ‘‘euc-
              kr’’  is  required  to handle the euc-jp and euc-kr encoded sgml
              file.

       --style=file, -S
              Include  an  auxiliary  DTD  (Document  Type  Definition)   from
              /usr/share/linuxdoc-tools/dtd.

       --tabsize=n, -t
              Set  the tab spacing assumed for generating the output document.
              The default tab spacing is 8.

       --debug, -d
              Don’t delete intermediate files (such as .TeX files generated on
              the  way  to  a  .dvi, or .man files deleted on the way to plain
              text).

       --define, -D
              Pass attribute/value  pairs  to  be  matched  against  "if"  and
              "unless"  conditionals.   See the User’s Guide for extended dis-
              cussion of this feature.  This conditionalization are handled by
              sgmlpre command.  See sgmlpre(1) as well as the User’s Guide.

       --include, -i
              Pass a -i option to nsgmls(1).  This may be used for conditional
              inclusion.  See the nsgmls(1) manual page for details.

       --pass, -P
              Pass an option string to the back end.  The exact  semantics  of
              this  option  are  dependent  on  the  back  end  and  should be
              explained in the individual manual pages for each.

       file   The SGML source file, named either file or file.sgml.

       Running a back-end with no arguments will cause  it  to  list  all  its
       options (Error message about "no filenames given" can be ignored safely
       in this case).  The available back ends include (names in brackets  are
       old & obsoleted form):

       linuxdoc -B html (sgml2html)
              translate to HTML

       linuxdoc -B info (sgml2info)
              translate to GNU info

       linuxdoc -B lyx (sgml2lyx)
              translate to Lyx macros

       linuxdoc -B latex (sgml2latex)
              translate to LaTeX 2e

       linuxdoc -B rtf (sgml2rtf)
              translate to Microsoft Rich Text Format

       linuxdoc -B txt (sgml2txt)
              translate to plain text or Unix manual-page markup

       There is also a tool linuxdoc-Bcheck
        (sgmlcheck)  available  for  checking  the Linuxdoc DTD SGML syntax of
       document sources without actually generating a translated version.


BACKEND-DRIVERS

       Here are the description for each backend drivers:

        ****************************************************

       linuxdoc -B html  (sgml2html) converts a LinuxDoc DTD SGML source  file
       to HTML output.  Output will appear in the top level file file.html and
       file-n.html for each section (default action, but  can  be  changed  by
       option),  where  file  is the name of the SGML source file and n is the
       section name.

       The attribute/value pair "output=html" is set for conditionals.

       linuxdoc -B html  accepts  the  following  options:  [--split  0|1|2  ]
       [--dosnames] [--imagebuttons] [--toc 0|1|2 ]

       The meanings of them are:

       --split, -s
              What  level  to  split  source  documents.  0 = don’t split, 1 =
              split by major sections, 2 = split by subsections.

       --toc, -T
              What level to generate toc.
                0 = don’t generate toc at all,
                1 = includes major sections(/chapters/parts),
                2 = includes subsections.

       --dosnames, -h
              Use ".htm" rather than ".html" as the extension of

       --imagebuttons, -I
              Use the "next", "previous", and  "contents"  arrow  image  icons
              included in /usr/share/linuxdoc-tools as navigation buttons.

       --footer, -F
              Use the specified file as the footer in each resulted html file.
              Default footer is just plain

               </BODY>\n </HTML>\n

       --header, -H
              Use the specified file as the top part of the header in each re-
              sulted html file. Note this is not the full part of the header.
              (i.e. the title and the links (next,previous,contents) in the
              default header are retained. Default is

               <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n
               <HTML>\n <HEAD>\n

        ****************************************************

       linuxdoc -B info  (sgml2info) converts a LinuxDoc DTD SGML source file
       to GNU info format.  Output will appear in file.info where file is the
       name of the SGML source file.

       The attribute/value pair "output=info" is set for conditionals.

       linuxdoc -B info has not backend specific options.

        ****************************************************

       linuxdoc -B latex  (sgml2latex) converts a LinuxDoc DTD SGML source
       file to LaTeX output, using the nsgmls(1) or onsgmls(1) parser, and the
       sgmlsasp(1) translator.  Using the LaTeX output, and the latex(1) text
       formatter, you can then create DVI output, and PostScript output using
       the dvips(1) converter. Output will appear in file.tex for LaTeX out-
       put, file.dvi for DVI output, or file.ps for PostScript output, where
       file is the name of the SGML source file.

       Using  the LaTeX output, and the pdflatex(1) text formatter, you can
       then create a nice PDF output, suitable for viewing with PDF viewers as
       xpdf(1), acroread(1) or ghostview(1).

       The attribute/value pair "output=latex2e" is set for conditionals.

       linuxdoc -B latex accepts following backend specific options: [--out-
       put=tex|dvi|ps|pdf] [--bibtex] [--makeindex] [--pagenumber=n] --quick
       [--latex=latex|hlatexp|platex|jlatex] [--dvips=dvips|dvi2ps]

       The meanings of them are:

       --output=fmt, -o
              Specify the desired output format.  The specifier fmt may be
              ‘‘tex’’, ‘‘dvi’’, ‘‘ps’’, or ‘‘pdf’’.

       Note: This version does not overwrite/remove the intermediate files:
       tex file for dvi output, or tex/dvi files for ps output.  This is dif-
       ferent behavior from the original SGML-Tools 1.0.9, so you are warned
       here.

       --bibtex, -b
              Process the generated TeX with bibtex(1).

       --makeindex, -m
              Generate a TeX index file suitable for processing with makein-
              dex(1) from and <idx> and <cdx> tags present in the SGML source.

       --pagenumber, -n
              Set the starting page number in the output DVI or PS file.

       --quick, -q
              Do only one pass of LaTeX formatting.  This is often not suffi-
              cient to produce final output (because of references, etc.) but
              is useful for spotting TeX errors and justification problems.

       --pass, -P
              The argument of the pass option is inserted just after the LaTeX
              preamble generated by the document-type tag.  Specify the de-
              sired output format.  The specifier fmt may be ‘‘tex’’, ‘‘dvi’’,
              ‘‘ps’’, or ‘‘pdf’’.

       --latex=alternate_latex_command, -x
              This option is currently for Korean and Japanese.  The alter-
              nate_latex_command can be ‘‘latex’’ (default), ‘‘hlatexp’’ (for
              Korean), ‘‘platex’’ or ‘‘jlatex’’ (for Japanese).  This option
              can be used to render Korean document using HLaTeXp, or to ren-
              der Japanese document using pLaTeX/jLaTeX.  If not, HLaTeX
              should be installed to render Korean document.  On the other
              hand, Japanese document can be rendered with jLaTeX
               (which is the default when ‘‘-c nippon’’ is specified), so if
              you already have jLaTeX, you may not need to install the pLaTeX.

       --dvips=alternate_dvips_command, -s
              This option is currently for Japanese.  The alternate_dvips_com-
              mand can be ‘‘dvips’’ or ‘‘dvi2ps’’.  If you don’t know this,
              then you may not need this.

        ****************************************************

       linuxdoc -B lyx  (sgml2lyx) converts a LinuxDoc DTD SGML source file to
       LyX output.  Output will appear in file.lyx where file is the name of
       the SGML source file.

       The attribute/value pair "output=lyx" is set for conditionals.

       linuxdoc -B lyx has not backend specific options.

        ****************************************************

       linuxdoc -B rtf  (sgml2rtf) converts a LinuxDoc DTD SGML source file to
       RTF, the Rich Text Tormat used by the Microsoft Windows help system.
       Output will appear in the top level file file.rtf and file-n.rtf for
       each section, where file is the name of the SGML source file.  The RTF
       output is tailored for compilation by the Windows Help Compiler
       (hc31.exe).

       The attribute/value pair "output=rtf" is set for conditionals.

       linuxdoc -B rtf accepts [--twosplit] as a backend specific option.
       Following is the meaning of this option:

       --twosplit, -2
              Splits files both at n. sections and n.m. subsections

        ****************************************************

       linuxdoc -B txt  (sgml2txt) converts a LinuxDoc DTD SGML source file to
       ASCII, ISO-8859-1, or EUC-JP output. Output will appear in file.txt
       where file is the name of the SGML source file.

       The attribute/value pair "output=txt" is set for conditionals.

       linuxdoc -B txt accepts following backend-options: [--manpage] [--fil-
       ter] [--blanks=n]

       The meaning of these options are:

       --manpage, -m
              Outputs a groff source file, suitable for formatting with groff
              -man for man pages

       --filter, -f
              Remove backspace-overstrikes from the intermediate form generat-
              ed by groff(1).

       --pass, -P
              The argument of the pass option is added to the command-line op-
              tions handed to groff(1).

       --blanks=n, -b
              Set the limit of continuous blank lines for generating the out-
              put document.  The default limit is 3. if 0 (zero) is specified,
              the result have many continuous blank lines.

        ****************************************************

       linuxdoc -B check  (sgmlcheck) runs an SGML parse on the specified doc-
       ument source.  Any errors are reported to standard output.  No format-
       ted version of the source is produced.

       Note that linuxdoc -B check preprocesses the LinuxDoc DTD SGML source,
       doing the conditionalization described by any <#if></#if> and <#un-
       less></#unless> tags.  Document sources containing these tags will con-
       fuse a standalone SGML parser.  linuxdoc -B check has no backend-spe-
       cific options.
        ****************************************************


FILES

       Many files and executables in /usr/share/linuxdoc-tools and /usr/bin
       are used.


BUGS

       Maybe some are left.  Feel free to send your report to the current
       maintainer.


MAINTAINER

       This had been maintained by Cees de Groot <cg@cdegroot.com> in SGML-
       Tools (v1).  Currently maintained by Taketoshi Sano <sano@debian.org>
       for Linuxdoc-Tools.




                                  27 Jul 2000                      LINUXDOC(1)

Man(1) output converted with man2html