6. Editing the Documentation

6.1. Getting the Docs and Code

The first step towards editing the documentation is to checkout a copy of code, docs, and build scripts from the CVS server using:

  $ export CVS_RSH=ssh
  $ export CVSROOT=':ext:NAME@mitgcm.org:/u/gcmpack'
  $ mkdir scratch
  $ cvs co -P MITgcm manual mitgcm.org

These commands extract the necessary information from the CVS server and create a temporary (called scratch) directory for the storage of the HTML and other files that will be created. Please note that you must either create scratch as shown or edit the various Makefiles and scripts used to create the documentation.

6.2. Editing the Documentation

The documentation is contained in the manual directory in a raw LaTeX format. The main document is manual.tex and it uses \input{}s to include the chapters and subsections.

Since the same LaTeX source is used to produce PostScript, PDF, and HTML output, care should be taken to follow certain conventions. Two of the most important are the usage of the \filelink{}{} and \varlink{}{} commands. Both of these commands have been defined to simplify the connection between the automatically generated ("code browser") HTML and the HTML version of the manual produced by LaTeX2HTML. They each take two arguments (corresponding to the contents of the two sets of curly braces) which are the text that the author wishes to be "wrapped" within the link, and a specially formatted link thats relative to the MITgcm directory within the CVS tree.

The result is a command that resembles either

1. a reference to a variable or subroutine name such as \varlink{tRef}{tRef}, or

2. a reference to a file such as \varlink{tRef}{path-to-the-file_name.F} where the absolute path to the file is of the form /foo/MITgcm/path/to/the/file_name.F

   (please note how the leading "/foo/MITgcm" component of the path is dropped leaving the path relative to the head of the code directory and each directory separator "/" is turned into a "-")

6.3. Building the Documentation

Given the directory structure of Section 6.1, the entire documentation for the web site can be built using:

  $ cd mitgcm.org/devel/buildweb
  $ make All

Which builds the PDF from the LaTeX source, creates the HTML output from the LaTeX source, parses the FORTRAN code base to produce a hyperlinked HTML version of the source, and then determines the cross-linking between the various HTML components.

If there are no errors, the result of the build process (which can take 30+ minutes on a P4/2.5Ghz) will be contained within a single directory called scratch/dev_docs. This is a freshly built version of the entire on-line users manual. If you have the correct permissions, it can be directly copied to the web server area:

  $ mv scratch/dev_docs /u/u0/httpd/html

and the update is complete.