1LINUXDOC(1)                 General Commands Manual                LINUXDOC(1)
2
3
4

NAME

6       linuxdoc - LinuxDoc DTD SGML converter to other output format
7

SYNOPSIS

9       linuxdoc --backend=format
10       --papersize=size  --language=lang  --charset=char  --style=file --debug
11       --define attribute=value     --include entity      [backend-options...]
12       file(.sgml)
13
14       or (Old, obsoleted usage)
15       sgmlxxxx [generic-options...] [backend-options...]   file(.sgml)
16

DESCRIPTION

18       The linuxdoc suite is a collection of text formatters which understands
19       a LinuxDoc DTD SGML source file. Each formatter (or "back-end") renders
20       the  source file into a variety of output formats, including HTML, TeX,
21       DVI, PostScript, plain text, and groff(1) source in manual-page format.
22       The  linuxdoc  suite  is  provided  for backward compatibility, because
23       there are still many useful documents  written  in  LinuxDoc  DTD  sgml
24       source.
25
26       The markup language(s) accepted by these formatters is described in the
27       Linuxdoc-Tools User's Guide.  They are variants  of  an  SGML  document
28       type  definition originally designed by Matt Welsh for Linux documenta‐
29       tion.
30

GENERIC-OPTIONS

32       Most command-line options are accepted by all  back-ends.   Some  back-
33       ends  have  additional  specific  options to control rendering to their
34       particular output format.  Here are the common options:
35
36       --backend=format, -B
37              Set the backend for specified format. Default  is  none  of  the
38              actual format, but just output the usage of this suites.  Avail‐
39              able formats are: html, info, latex, lyx, rtf, txt, check.
40
41       --papersize=size, -p
42              Set the paper size.  Default is ``letter''.  You may also  spec‐
43              ify ``a4'' size (European 297x210mm paper).
44
45       --language=lang, -l
46              Specify  the  language  of  the  document (this may change which
47              style files are used for formatting by a back end).  The default
48              language is English. Run an LinuxDoc-tools command without argu‐
49              ments to see the list of valid language codes.
50
51       --charset=chars, -c
52              Specify the output character encoding.   Defaults  to  ``ascii''
53              selecting  the ASCII set; you may specify "latin" to specify the
54              ISO 8859-1 (Latin-1) character set.  Also, ``nippon'' and ``euc-
55              kr''  is  required  to handle the euc-jp and euc-kr encoded sgml
56              file.
57
58       --style=file, -S
59              Include  an  auxiliary  DTD  (Document  Type  Definition)   from
60              /usr/share/linuxdoc-tools/dtd.
61
62       --tabsize=n, -t
63              Set  the tab spacing assumed for generating the output document.
64              The default tab spacing is 8.
65
66       --debug, -d
67              Don't delete intermediate files (such as .TeX files generated on
68              the  way  to  a  .dvi, or .man files deleted on the way to plain
69              text).
70
71       --define, -D
72              Pass attribute/value  pairs  to  be  matched  against  "if"  and
73              "unless"  conditionals.   See the User's Guide for extended dis‐
74              cussion of this feature.  This conditionalization are handled by
75              sgmlpre command.  See sgmlpre(1) as well as the User's Guide.
76
77       --include, -i
78              Pass a -i option to nsgmls(1).  This may be used for conditional
79              inclusion.  See the nsgmls(1) manual page for details.
80
81       --pass, -P
82              Pass an option string to the back end.  The exact  semantics  of
83              this  option  are  dependent  on  the  back  end  and  should be
84              explained in the individual manual pages for each.
85
86       file   The SGML source file, named either file or file.sgml.
87
88       Running a back-end with no arguments will cause  it  to  list  all  its
89       options (Error message about "no filenames given" can be ignored safely
90       in this case).  The available back ends include (names in brackets  are
91       old & obsoleted form):
92
93       linuxdoc -B html (sgml2html)
94              translate to HTML
95
96       linuxdoc -B info (sgml2info)
97              translate to GNU info
98
99       linuxdoc -B lyx (sgml2lyx)
100              translate to Lyx macros
101
102       linuxdoc -B latex (sgml2latex)
103              translate to LaTeX 2e
104
105       linuxdoc -B rtf (sgml2rtf)
106              translate to Microsoft Rich Text Format
107
108       linuxdoc -B txt (sgml2txt)
109              translate to plain text or Unix manual-page markup
110
111       There is also a tool linuxdoc-Bcheck
112        (sgmlcheck)  available  for  checking  the Linuxdoc DTD SGML syntax of
113       document sources without actually generating a translated version.
114

BACKEND-DRIVERS

116       Here are the description for each backend drivers:
117
118        ****************************************************
119
120       linuxdoc -B html  (sgml2html) converts a LinuxDoc DTD SGML source  file
121       to HTML output.  Output will appear in the top level file file.html and
122       file-n.html for each section (default action, but  can  be  changed  by
123       option),  where  file  is the name of the SGML source file and n is the
124       section name.
125
126       The attribute/value pair "output=html" is set for conditionals.
127
128       linuxdoc -B html  accepts  the  following  options:  [--split  0|1|2  ]
129       [--dosnames] [--imagebuttons] [--toc 0|1|2 ]
130
131       The meanings of them are:
132
133       --split, -s
134              What  level  to  split  source  documents.  0 = don't split, 1 =
135              split by major sections, 2 = split by subsections.
136
137       --toc, -T
138              What level to generate toc.
139                0 = don't generate toc at all,
140                1 = includes major sections(/chapters/parts),
141                2 = includes subsections.
142
143       --dosnames, -h
144              Use ".htm" rather than ".html" as the extension of
145
146       --imagebuttons, -I
147              Use the "next", "previous", and  "contents"  arrow  image  icons
148              included in /usr/share/linuxdoc-tools as navigation buttons.
149
150       --footer, -F
151              Use the specified file as the footer in each resulted html file.
152              Default footer is just plain
153
154               </BODY>\n </HTML>\n
155
156       --header, -H
157              Use the specified file as the top part of the header in each re‐
158              sulted html file. Note this is not the full part of the header.
159              (i.e. the title and the links (next,previous,contents) in the
160              default header are retained. Default is
161
162               <!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 3.2 Final//EN">\n
163               <HTML>\n <HEAD>\n
164
165        ****************************************************
166
167       linuxdoc -B info  (sgml2info) converts a LinuxDoc DTD SGML source file
168       to GNU info format.  Output will appear in file.info where file is the
169       name of the SGML source file.
170
171       The attribute/value pair "output=info" is set for conditionals.
172
173       linuxdoc -B info has not backend specific options.
174
175        ****************************************************
176
177       linuxdoc -B latex  (sgml2latex) converts a LinuxDoc DTD SGML source
178       file to LaTeX output, using the nsgmls(1) or onsgmls(1) parser, and the
179       sgmlsasp(1) translator.  Using the LaTeX output, and the latex(1) text
180       formatter, you can then create DVI output, and PostScript output using
181       the dvips(1) converter. Output will appear in file.tex for LaTeX out‐
182       put, file.dvi for DVI output, or file.ps for PostScript output, where
183       file is the name of the SGML source file.
184
185       Using  the LaTeX output, and the pdflatex(1) text formatter, you can
186       then create a nice PDF output, suitable for viewing with PDF viewers as
187       xpdf(1), acroread(1) or ghostview(1).
188
189       The attribute/value pair "output=latex2e" is set for conditionals.
190
191       linuxdoc -B latex accepts following backend specific options: [--out‐
192       put=tex|dvi|ps|pdf] [--bibtex] [--makeindex] [--pagenumber=n] --quick
193       [--latex=latex|hlatexp|platex|jlatex] [--dvips=dvips|dvi2ps]
194
195       The meanings of them are:
196
197       --output=fmt, -o
198              Specify the desired output format.  The specifier fmt may be
199              ``tex'', ``dvi'', ``ps'', or ``pdf''.
200
201       Note: This version does not overwrite/remove the intermediate files:
202       tex file for dvi output, or tex/dvi files for ps output.  This is dif‐
203       ferent behavior from the original SGML-Tools 1.0.9, so you are warned
204       here.
205
206       --bibtex, -b
207              Process the generated TeX with bibtex(1).
208
209       --makeindex, -m
210              Generate a TeX index file suitable for processing with makein‐
211              dex(1) from and <idx> and <cdx> tags present in the SGML source.
212
213       --pagenumber, -n
214              Set the starting page number in the output DVI or PS file.
215
216       --quick, -q
217              Do only one pass of LaTeX formatting.  This is often not suffi‐
218              cient to produce final output (because of references, etc.) but
219              is useful for spotting TeX errors and justification problems.
220
221       --pass, -P
222              The argument of the pass option is inserted just after the LaTeX
223              preamble generated by the document-type tag.  Specify the de‐
224              sired output format.  The specifier fmt may be ``tex'', ``dvi'',
225              ``ps'', or ``pdf''.
226
227       --latex=alternate_latex_command, -x
228              This option is currently for Korean and Japanese.  The alter‐
229              nate_latex_command can be ``latex'' (default), ``hlatexp'' (for
230              Korean), ``platex'' or ``jlatex'' (for Japanese).  This option
231              can be used to render Korean document using HLaTeXp, or to ren‐
232              der Japanese document using pLaTeX/jLaTeX.  If not, HLaTeX
233              should be installed to render Korean document.  On the other
234              hand, Japanese document can be rendered with jLaTeX
235               (which is the default when ``-c nippon'' is specified), so if
236              you already have jLaTeX, you may not need to install the pLaTeX.
237
238       --dvips=alternate_dvips_command, -s
239              This option is currently for Japanese.  The alternate_dvips_com‐
240              mand can be ``dvips'' or ``dvi2ps''.  If you don't know this,
241              then you may not need this.
242
243        ****************************************************
244
245       linuxdoc -B lyx  (sgml2lyx) converts a LinuxDoc DTD SGML source file to
246       LyX output.  Output will appear in file.lyx where file is the name of
247       the SGML source file.
248
249       The attribute/value pair "output=lyx" is set for conditionals.
250
251       linuxdoc -B lyx has not backend specific options.
252
253        ****************************************************
254
255       linuxdoc -B rtf  (sgml2rtf) converts a LinuxDoc DTD SGML source file to
256       RTF, the Rich Text Tormat used by the Microsoft Windows help system.
257       Output will appear in the top level file file.rtf and file-n.rtf for
258       each section, where file is the name of the SGML source file.  The RTF
259       output is tailored for compilation by the Windows Help Compiler
260       (hc31.exe).
261
262       The attribute/value pair "output=rtf" is set for conditionals.
263
264       linuxdoc -B rtf accepts [--twosplit] as a backend specific option.
265       Following is the meaning of this option:
266
267       --twosplit, -2
268              Splits files both at n. sections and n.m. subsections
269
270        ****************************************************
271
272       linuxdoc -B txt  (sgml2txt) converts a LinuxDoc DTD SGML source file to
273       ASCII, ISO-8859-1, or EUC-JP output. Output will appear in file.txt
274       where file is the name of the SGML source file.
275
276       The attribute/value pair "output=txt" is set for conditionals.
277
278       linuxdoc -B txt accepts following backend-options: [--manpage] [--fil‐
279       ter] [--blanks=n]
280
281       The meaning of these options are:
282
283       --manpage, -m
284              Outputs a groff source file, suitable for formatting with groff
285              -man for man pages
286
287       --filter, -f
288              Remove backspace-overstrikes from the intermediate form generat‐
289              ed by groff(1).
290
291       --pass, -P
292              The argument of the pass option is added to the command-line op‐
293              tions handed to groff(1).
294
295       --blanks=n, -b
296              Set the limit of continuous blank lines for generating the out‐
297              put document.  The default limit is 3. if 0 (zero) is specified,
298              the result have many continuous blank lines.
299
300        ****************************************************
301
302       linuxdoc -B check  (sgmlcheck) runs an SGML parse on the specified doc‐
303       ument source.  Any errors are reported to standard output.  No format‐
304       ted version of the source is produced.
305
306       Note that linuxdoc -B check preprocesses the LinuxDoc DTD SGML source,
307       doing the conditionalization described by any <#if></#if> and <#un‐
308       less></#unless> tags.  Document sources containing these tags will con‐
309       fuse a standalone SGML parser.  linuxdoc -B check has no backend-spe‐
310       cific options.
311        ****************************************************
312

FILES

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

BUGS

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

MAINTAINER

322       This had been maintained by Cees de Groot <cg@cdegroot.com> in SGML-
323       Tools (v1).  Currently maintained by Taketoshi Sano <sano@debian.org>
324       for Linuxdoc-Tools.
325
326
327
328
329                                  27 Jul 2000                      LINUXDOC(1)
Impressum