The docs make heavy use of m4 which is a macro processor. The html page
in the source tree will have something like _NIMBUS_HEADER in it
which gets turned into the actual header HTML when the documentation is
built.

The best bet is to start out by copying already created macros. If you want
to create a new page, copy and paste the source contents (with the macros)
of a page that will be next to it. Change the page title by altering the
argument to the _NIMBUS_HEADER macro.

You will see something like "n,n,y,n,n,n,n" as an argument to some of the
macros. This controls which option in a list is shaded/selected (like the
main navigation bar or a subsection sidebar). To see which one to use,
you may need to dip into the macro definitions in the "m4/worksp.lib.m4"
file. This kind of navigation "current" CSS class pattern is handled a lot better by other systems, this is a "bolt on" during the transition time.

... look for examples of the _EXAMPLE_GENERICCMD_BEGIN macro which
must be closed off with the _EXAMPLE_CMD_END macro.

The _NAMELINK macro is useful for long pages, especially technical
documentation. Whenever you make an anchor like so:
<a name="some-section">

... put a _NAMELINK macro with an argument "some-section" like so:
_NAMELINK(some-section)

See an example next to the subsections on this page, it produces a hidden
link that will show up when you hover next to where the anchor takes you.
This lets users and developers quickly find anchors so that specific
sections of the documentation can be referred to over email etc.

After you edit or add pages, preview the change by re-running the
"build-and-serve-locally.sh" script. If it was already running, simply
press CTRL-C and launch it again.

Once satisfied with the changes:

Commit changes to git:

$
cvs commit

Log in to the computer where the live website lives:

$
ssh USERNAME@login.mcs.anl.gov

Make a scratch directory:

$
mkdir /scratch/somedir && cd /scratch/somedir

Get the documentation and scripts from git:

$
git clone git://github.com/nimbusproject/nimbus.git

$
cd nimbus/docs/scripts

$
bash docscripts/push_to_mcs_web.sh X.Y

The "push_to_mcs_web.sh" will push any changes from the scratch directory
to the live directory. The "X.Y" argument controls the target directory, e.g. "2.6" would push the current branch to the 2.6 subdirectory which is symlinked as the 'current' documentation at the time of this writing.

If you need to change something in an older release, you must switch into that branch (using "git checkout"), pull in the necessary changes and invoke that script with the appropriate version target.