PREFACE ^^^^^^^ This file documents how to build the GNO documentation. Probably one of the first questions you may ask is "Why is the document source in LaTeX?". It comes down to this: - I wanted to provide a good selection of file formats. - I wanted the results to look as professional as possible in all provided file formats. - I wanted all file formats to originate from the same source. There was some question as to which language should be used for the original source. LaTeX was chosen (rather arbitrarily) as the source language because it, IMHO, gives the optimal results for the three points above. Devin Reade December 1997. $Id: README,v 1.1 1997/12/02 15:38:13 gdr Exp $ WHAT THE FILES ARE ^^^^^^^^^^^^^^^^^^ Makefile Configuration file for use with dmake. README This file. getdate A perl script which extracts the date or version from an RCS "Id" tag, and prints it in a more "normal" fashion. Usage: "getdate outfile" gno.bib The bibliography used in the Overview. This is processed using BibTeX. index.html This is the top-level page for the html version. It contains links to the three books, the generated man pages, the FAQ, et al. intro.tex This is the LaTeX source to the "Overview and Installation Manual". gsh.tex This is the LaTeX source to the "GNO Shell Reference Manual". kern.tex This is the LaTeX source to the "Kernel Reference Manual". mkhtmlman This is a custom script which drives the man2html program. It basically searches for the man pages in the GNO search tree to convert, and adds in some custom info after the conversion has been done. mkmandex This is a custom script which generates the html index pages for each "man page" chapter. newer.c A source file which compiles to a program that compares the modification date of two files. Used by mkhtmlman to avoid unnecessary processing. unaval.html A generic web page that says "the page you requested is not ready yet". WHAT YOU NEED ^^^^^^^^^^^^^ There are quite a few tools that you will need to build the GNO documentation. They are: dmake This is not common on too many UNIX systems, but I needed for certain contructs that gmake as too dumb to handle. It was written by Dennis Vadura, , and is available from ftp://plg.uwaterloo.ca/pub/dmake http://dmake.wticorp.com perl5 Perl5 is needed by some of the translation utilities. LaTeX2e LaTeX is responsible for creating the DVI and Postscript versions of the documentation. bibtex, makeidx These two utilities are required for making the bibliography and index, respectively. They are likely part of your LaTeX distribution. latex2html This utility translates the man pages from nroff source into html. It is available via the CTAN site nearest you. Check in the directory tex-archive/support/latex2html. Three main CTAN sites are: United States: ftp.shsu.edu United Kingdom: ftp.tex.ac.uk Germany: ftp.dante.de hthtml This is a package that provides a cleaner interface for displaying URLs either as footnotes (for printed manuals) or as links (for online manuals). It is available from http://www.cs.tu-bs.de/~krinke/hthtml/index.html man2html This is a program which converts preformatted nroff source to html. It is available at http://www.oac.uci.edu/indiv/ehood/man2html.html WHERE TO BUILD IT ^^^^^^^^^^^^^^^^^ First of all, we cannot build the documentation using GNO itself, as GNO stands today. We probably won't ever be able to, and if we are, we probably won't want to build it under GNO. The reason is simple; I normally build the docs using a 120MHz 686 with 80Meg of memory (running Linux). Doing so takes many minutes, and most of the memory. Building it on a a 16Meg Linux machine absolutely thrashes the machine. That having been said, you should be able to rebuild the documentation on any UNIX box, provided you install (or have installed) the appropriate utilities. HOW TO BUILD IT ^^^^^^^^^^^^^^^ The documentation as it stands now will probably only build on my system. However, should I ever stop maintaining this documentation, it should be fairly simple to reconfigure it to run elsewhere. Most of the site-specific items are in the Makefile. This includes the maintainer name and address, the basenames of the URLs used, and so forth. If the DRAFT macro is set to 'true' then many url links in the html versions will resolve to local files; this is used for testing. Some other dependancies are as follows. Unless trenco is no longer the primary GNO site, the following should not need to be changed: index.html: There are some minor assumptions about the directory structure and file names on the GNO html and ftp servers. intro.tex: There are some explicit references to the trenco ftp in this document. These should not be changed unless trenco is no longer used. mkhtmlman: This script is heavily dependant on the structure of the GNO source tree, and the directory from which it is invoked. On the other hand, there shouldn't be any need to change this. unaval.html: The maintainer's name and address is hard-coded here. Once the above dependancies have been addressed, you can use dmake(1) to build the sources. The primary targets are: dvi: Build the DVI (device independant) files. ps: Build the Postscript files. Implies the dvi target. h: Build the html version of the *.tex files. Because the bibliography gets built by the dvi target, you should have made the dvi target at least once. If your dvi target is out-of-date you will only get a warning. If the bibliography generated from gno.bib does not exist at all, then this target will fail. man: Builds the html versions of the manual pages. all: Build all of the above targets. upload: Builds *.gz and *.Z files which are then used when I do uploads to the http/ftp server. clean: Removes all temporary files. clobber: Removes all generated files and directories. Implies 'clean'.