2. Installation

Contents of this section

The file linuxdoc-sgml-1.4.tar.gz contains everything that you need to write SGML documents and convert them to LaTeX, groff, HTML and texinfo. 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 docs 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 docs. (TeX/LaTeX will be used to produce nicely-printed PostScript and dvi).
  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 docs 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 texinfo tools, for formatting and viewing texinfo 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 texinfo tools).

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.4.tar.gz somewhere. This will create the directory linuxdoc-sgml-1.4 where all of the SGML files live. It doesn't matter where you unpack this file; just don't move things around within the linuxdoc-sgml-1.4 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 Testing it out

You can now test the system. Let's say you have the SGML document foo.sgml. You can translate it to LaTeX, and produce PostScript output (via dvips) with the command:

% sgml2ps foo.sgml 
Or, you can produce a DVI file using the -d switch with sgml2ps, as so:
% sgml2ps -d foo.sgml 
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. I you want to produce HTML, do this:
% sgml2html foo.html 
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.

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

% sgml2info foo.sgml 

A good way to test this would be to run it on this file, guide.sgml, or example.sgml.

If you just want to capture your errors from the SGML conversion, use the -c flag with one of the conversion scripts. For example.

% sgml2txt -c 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 and HTML output (texinfo support for ISO 8859-1 may be possible in the future). To use this feature give the SGML script 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.


Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter