2 Installation

Contents of this section

The file linuxdoc-sgml.tar.gz contains everything that you need to write SGML documents and convert them to LaTeX, nroff, and HTML. In addition to this package, you will need one or both of the following:

  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 prep.ai.mit.edu in /pub/gnu. There is a Linux binary version on sunsite as well. You will need groff to produce plain ASCII 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). Of course, you only need TeX/LaTeX if you want to format your SGML docs with LaTeX. So, installing TeX/LaTeX is optional. See the section on the Linux HOWTO project below for how we'll manage this vis-a-vis the Linux HOWTOs.
  3. If you want to view the generated HTML, I suggest getting NCSA Mosaic 2.2 or later.
Neither of these are required by the SGML system, but I suggest that you get one or the other in order to format your docs and verify that they look all right before distributing them.

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.tar.gz somewhere. This will create the directory linuxdoc-sgml 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 directory.
  2. Next, you need to compile the sgmls parser. In the linuxdoc-sgml/sgmls-1.1 directory, issue the commands: 
    $ make config.h
$ make
$ make install
$ make install.man
    This should compile the parser and translator, and place the binaries sgmls, sgmlsasp, and rast in linuxdoc-sgml/bin. I suggest that you don't move those binaries from that location; instead, make symlinks to them from /usr/local/bin or place linuxdoc-sgml/bin on your path. (If you move things around within the linuxdoc-sgml tree you'll have to edit a number of files to get everything to cooperate again. Best to leave things as-is.) If things don't work try editing the Makefile in the sgmls-1.1 directory. I have it set to use gcc as the compiler, and use rather malignant options. Compiles fine on Linux and sun-4 systems. This will also install man pages for the three binaries in linuxdoc-sgml/man. You can move those or link them to your regular man page tree, should you need them.
  3. Edit the variables at the top of the scripts format, qroff, preroff, prehtml, and qtex in linuxdoc-sgml/bin. All you really need to edit is the value of the LINUXDOC shell variable which gives the full pathname of the linuxdoc-sgml directory.
  4. In the html-fix directory, issue the commands: 
    $ make
$ make install
    This will build fixref and html2html, which are post processors for the HTML conversion, and place them in the bin directory.

If all went well, you should be ready to use the system. Just be sure that linuxdoc-sgml/bin is on your path or you've linked the files therein to your standard binary directories. Again, don't just copy them somewhere else; the scripts expect to find each other in that directory.

2.2 Testing it out

You can now test the system. The format script takes an SGML document as input and translates it to a given format. The qtex script will process the output of format using LaTeX, and qroff will process it using nroff.

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: 

$ format -Tlatex foo | qtex > foo.ps
Or, you can produce a DVI file using the -d switch with qtex, as so: 
$ format -Tlatex foo | qtex -d > foo.dvi

If you want to produce plain ASCII, through groff, use the command: 

$ format -Tnroff foo | qroff > foo.txt
Note that I have tailored the groff conversion for plain ASCII 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 resulting from format, but I suggest that you use LaTeX for that instead.

If you want to produce HTML, the procedure is a bit more complicated, because of cross-references. Here's an example: 

$ format -Thtml foo.sgml | prehtml | fixref > tmp.html
$ format -Thtml foo.sgml | prehtml >> tmp.html
$ cat tmp.html | html2html foo > foo.html
$ rm tmp.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 client on foo.html, which is the toplevel 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.

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

If you just want to capture your errors from the SGML conversion, use something like 

$ format -Tnroff foo > /dev/null

2.3 Development note

The HTML conversion is, at this time, rudimentary but adequate. In the future there will be support for cross-references, navigation buttons, external URLs, and the like. Something is better than nothing. :)

Also, if you'd like to help me implement a texinfo (or plain Info) conversion for Linuxdoc-SGML, let me know! As with HTML we'll have to do some pre- and post-processing (which you supposedly shouldn't need with SGML, ah well), but that's not a big issue.

Next Chapter, Previous Chapter

Table of contents of this chapter, General table of contents

Top of the document, Beginning of this Chapter