GUIDE TO HTML DOCUMENTATION

[Information correct February 1998, but subject to change.]

A plea from the CCP4 staff: Please can developers edit HTML files with a text editor rather than Netscape Composer or similar. The latter introduces spurious changes to the file which hamper our attempts at revision control, and which are sometimes detrimental to the document the user sees.

Introduction


Individual program documentation is now written and distributed in HTML format. All .html files are kept in the directory $CHTML which is defined in ccp4.setup as ${CCP4_MASTER}/ccp4/html Equivalent plain text files are distributed in ${CCP4_MASTER}/ccp4/doc These are generated by the makefile rule:

lynx -dump $< | sed -e 's/file:\/\/localhost\/ccpdisk\/xtal\/ccp4/file: \$$CCP4/' > $@

i.e. by using the browser "lynx" in command line mode.

Currently four files are generated from the set of .html documents:

INDEX.html
List of programs categorised as General, Supported, Unsupported or Library.
FUNCTION.html
List of programs categorised according to function.
REFERENCES.html
Partial compilation of references.
whatis
This file is used by the apropos command (man -k). It must be moved to a suitable directory.

The generation of these files requires certain HTML comment lines to be inserted into each of the .html files (see below). Otherwise, authors are free to do what they wish. However, it makes things less stressful for the user if some things are standardised. This will be described below.

N.B. < and > must be rendered &lt; and &gt; respectively, even within <pre> ... </pre>. This is because < and > have a special function in HTML. [In fact, it is possible to use < and > directly if they have a space on the active side, but this is very bad practice!]

What your html file should contain

The .html file should contain an HTML comment line such as: 


<!-- ::INDEX_INFO::FHSCAL::Supported::Scaling data::Scaling of isomorphous derivative data using Kraut's method::see also SCALEIT:::::: -->
The script for generating INDEX.html, FUNCTION.html and whatis finds the first such line containing the string "INDEX_INFO". The syntax of this line is a sequence of fields separated by "::", containing:
INDEX_INFO
tag to find line
"FHSCAL"
program name
"General","Supported","Unsupported","Library",etc
category for INDEX.html
"Scaling data",etc
a comma-separated list of categories for FUNCTION.html
"Scaling of isomorphous ...."
program description
"see also SCALEIT"
optional additional comments
Existing documents contain two more blank fields for future use. The program name, and the two category fields are case-independent, and have leading and trailing spaces removed. Note that for both INDEX.html and FUNCTION.html, a category is produced for each unique string in fields 3 and 4. So you are free to make up any categories you want, but beware of typos! An empty field in 3 or 4 means that that program will not be listed in that index. Thus, typically an obsolete or unsupported program would not be listed in FUNCTION.html

The script for making REFERENCES.html extracts everything between

<!-- KEEP startreferencelist -->

and

<!-- KEEP endreferencelist -->

If you leave these out, REFERENCES.html will simply not contain this information: undesirable but not drastic.

Examples

We now prefer not to have example scripts embedded in the documentation, as these were getting very out-of-date. Instead, they should be in $CEXAM/unix/runnable where they will be tested before each release. The documentation should include a list of these examples, with links to the files in question. If the program documentation is opened as File rather than Location, then the user should be able to click and bring up the example (conversly, if it is opened as a Location then the server may assume it is an html file, and you will get a mess).

Interaction with GUI

.html files should contain "name" tags for the major sections and for keywords, e.g.

<H2><a name="description">DESCRIPTION</a></H2>

or

<H3><a name="scale">SCALE</a> <scale_fobs> <scale_fcalc> </H3>

The tags are used by the GUI to direct the user to the appropriate part of the documentation. In the .tcl files in the tasks subdirectory of the GUI, there are lines such as:

help "scale" \

The string included here must be the same as the name tag. In general, the strings used are the same as the heading or keyword, but this isn't necessary.

Other links

You should make liberal use of links to other documentation, e.g.

Input data should be prepared with the program <a href="programname.html">programname</a>.

All relevant links should be gathered together in the SEE ALSO section.

A rough template

Apart from the above, there are no restrictions on the contents of a .html document. However, it will make everybody's life easier if all documents follow the same layout. So here is a template that could be used for a new document:

<html>
<head><title>CCP4 Program Suite: programname</title></head>
<body>
<!-- ::INDEX_INFO::PROGRAMNAME::Supported::Function category::program description::additional comment:::::: -->
<H1> PROGRAMNAME (CCP4: Supported Program)</H1>
<H2> NAME</H2>
<b>programname </b>
- program description
<H2> SYNOPSIS</H2>
<b>programname FILIN</b>
<i>foo_in.ext</i>
<b>FILOUT</b>
<i>foo_out.ext</i>
<br>
[Key-worded input]

<H2><a name="description">DESCRIPTION</a></H2>

Brief description of purpose of program.

<H2><a name="files">INPUT AND OUTPUT FILES</a></H2>
<H3> Input</H3>
<dl compact>
<dt> FILIN<dd>
Format and contents of input file.
</dl>
<H3> Output</H3>
<dl compact>
<dt> FILOUT<dd>
Format and contents of output file.
</dl>

<H2><a name="keywords">KEYWORDED INPUT</a></H2>

<H3><a name="keyw">KEYW</a> <argument></H3>

Description of keyword.

<dl><dt>Subkeywords:<dd>
<dl><dt>
<a name="keyw_subkeyw">SUBKEYW</a>
<dd>Description of subkeyword.
</dl>
</dl>

<h2><a name="output">PRINTER OUTPUT</a></h2>

Description of what the program prints out.

<H2><a name="function">PROGRAM FUNCTION</a></H2>

Detailed description of what program does.

<H2><a name="examples">EXAMPLES</a></H2>

<H3>Unix example script found in $CEXAM/unix/runnable/</H3>
<ul>
<li><a href="../examples/unix/runnable/programname.exam"> programname.exam</a>
</ul>

<H3>VMS example script found in $CEXAM/vms/</H3>
<ul>
<li><a href="../examples/vms/programname.com"> programname.com</a>
</ul>

<H2> REFERENCES</H2>
<ol>
<!-- KEEP startreferencelist -->
<li>
A.N.Author, "A very important paper", <i>J. Irrep. Res.</i>, <b>1001</b>, 666-999 (1945)
<!-- KEEP endreferencelist -->
</ol>

<H2> AUTHOR</H2>
Written by Me.

<H2> SEE ALSO</H2>

Other useful programs:
<ul>
<li><A HREF=calctoe.html>calctoe</A>
</ul>

</BODY>
</HTML>