Get linuxdoc-sgml-1.5.tar.gz
from one of the following ftp sites:
ftp://sunsite.unc.edu/pub/Linux/utils/text/linuxdoc-sgml-1.5.tar.gz
ftp://tsx-11.mit.edu/pub/linux/docs/linuxdoc-sgml-1.5.tar.gz
ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml/linuxdoc-sgml-1.5.tar.gz
Uptodate patches to version 1.5 can be found at
ftp://ftp.cc.gatech.edu/pub/people/gregh/linuxdoc-sgml
.
You can also get uptodate information from the
Linuxdoc-SGML WWW Page
.
The file linuxdoc-sgml-1.5.tar.gz
contains everything that you need
to write SGML documents and convert them to groff, LaTeX, HTML, GNU info, LyX,
and RTF. In addition to this package, you will need the following
tools - these are not required by the SGML system, but I suggest that you get
them in order to format your documents and verify that they look
all right before distributing them.
groff
. You need version 1.08 or 1.09. Apparently some of
the margin-handling in groff
is in a state of flux from version to
version; they both work, but you get slightly different results
(particularly, with 1.09 the left margin isn't indented two characters as
it is in 1.08. There is a way around it, but it looks terrible on 1.08).
Versions previous to 1.08 will not work. You can get this from
ftp://prep.ai.mit.edu/pub/gnu
. There is a Linux
binary version on
ftp://sunsite.unc.edu/pub/Linux/utils/text
as well. You will need groff
to produce plain text from your SGML documents.
nroff
will not work!
sunsite.unc.edu
). Of course, you only need TeX/LaTeX
if you want to format your SGML documents with LaTeX. So, installing TeX/LaTeX
is optional.
ftp://sunsite.unc.edu/pub/Linux/system/Network/info-systems
.
gawk
and the GNU info tools, for formatting and viewing
info files. These are also available on
ftp://prep.ai.mit.edu/pub/gnu
, or on
ftp://sunsite.unc.edu/pub/Linux/utils/text
(for gawk
) and
ftp://sunsite.unc.edu/pub/Linux/system/Manual-pagers
(for GNU info tools). awk
will not work without hacking.
ftp://ftp.via.ecp.fr
.
The steps needed to install and configure the linuxdoc-sgml
stuff are
as follows:
linuxdoc-sgml-1.5.tar.gz
somewhere.
This will create the directory linuxdoc-sgml-1.5
. It doesn't matter
where you unpack this file; just don't move things around within the
linuxdoc-sgml-1.5
directory.
INSTALL
file - it has detailed installation instructions.
If all went well, you should be ready to use the system.Let's say you have the SGML document foo.sgml
, which you want to format.
Here is a general overview of formatting the document for different output.
For a complete list of options, consult the man pages.
If you want to produce plain text, use the command:
% sgml2txt foo.sgml
Note that I have tailored the groff conversion for plain text output. That is, I've removed page headers, page numbers, changed the margins, and so on. With some hacking you can produce PostScript and DVI from the groff output, but I suggest that you use LaTeX for that instead.
You can also create groff source for man pages, which can be formatted with
groff -man
. To do this, do the following:
% sgml2txt -man foo.sgml
To create a LaTeX documents from the SGML source file, simply run:
% sgml2latex foo.sgml
If you want to produce PostScript output (via dvips
), use the
-p
option:
% sgml2latex -p foo.sgml
Or, you can produce a DVI file using the -d
switch, as so:
% sgml2latex -d foo.sgml
If you want to produce HTML output, do this:
% sgml2html -img foo.sgml
This will produce foo.html
, as well as foo-1.html
,
foo-2.html
, and so on---one file for each section of the document.
Run your WWW browser on foo.html
, which is the top level file.
Also make sure that all of the HTML files corresponding to your document
are in one directory, as they reference each other with local URLs.
The icons referenced in the HTML output are located in
$LINUXDOCLIB/icons
. These will also need to be copied to the
final location of the HTML documents. $LINUXDOCLIB
is defined
at the beginning of the SGML conversion scripts.
If you use sgml2html
without the -img
flag, HTML documents will
have the labels ``Previous'', ``Next'', and ``Table of Contents'' for
navigation. You can override these defaults by creating a file in
$LINUXDOCLIB/rep/html/<filename>
, and substituting your
own words for different languages. The file has the following format:
PrevPage: newvalue
NextPage: newvalue
TOC: newvalue
See deutsch
for an example.
If you want to format your file for the GNU info browser, just run the following command:
% sgml2info foo.sgml
For LyX output, use the the command:
% sgml2lyx foo.sgml
If you want to produce RTF output, run the command:
% sgml2rtf foo.sgml
This will produce foo.rtf
, as well as foo-1.rtf
,
foo-2.rtf
, and so on---one file for each section of the document.
If you just want to capture your errors from the SGML conversion,
use the sgmlcheck
script. For example.
% sgmlcheck foo.sgml
The ISO 8859-1 (latin1) character set may be used for international characters
in plain text, LaTeX, HTML, LyX, and RTF output (GNU info support for
ISO 8859-1 may be possible in the future). To use this feature, give the
formatting scripts the -l
flag, for example:
% sgml2txt -l foo.sgml
You also can use ISO 8859-1 characters in the SGML source, they will
automatically be translated to the proper escape codes for the corresponding
output format.