2. Installation

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.

1. 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!
2. TeX and LaTeX. This is available more or less everywhere; you should have no problem getting it and installing it (there is a Linux binary distribution on 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.
3. If you want to view the generated HTML, I suggest getting NCSA Mosaic 2.6 or later, available on ftp://sunsite.unc.edu/pub/Linux/system/Network/info-systems.
4. 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.
5. LyX (a quasi-WYSIWYG interface to LaTeX, with SGML layouts), is available on ftp://ftp.via.ecp.fr.

2.1 Installing The Software

The steps needed to install and configure the linuxdoc-sgml stuff are as follows:

1. First, unpack the tar file 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.
2. Read the INSTALL file - it has detailed installation instructions. If all went well, you should be ready to use the system.

2.2 Formatting SGML Documents

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.

Creating Plain Text Output

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 

Creating LaTeX, DVI or PostScript Output

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 

Creating HTML Output

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

Creating GNU Info Output

If you want to format your file for the GNU info browser, just run the following command:

% sgml2info foo.sgml 

Creating LyX Output

For LyX output, use the the command:

% sgml2lyx foo.sgml 

Creating RTF Output

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.

Checking SGML Syntax

If you just want to capture your errors from the SGML conversion, use the sgmlcheck script. For example.

% sgmlcheck foo.sgml 

2.3 ISO 8859-1 Character Set

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