",," substitutes ''
Guide for writing and maintaining NEWSTAR documents
For quick reference use the following list of special LaTeX commands available in the NEWSTAR documentation system:
ascref
Ascref
caption
chapter
eqref
Eqref
fig
figref
Figref
label
ps
psref
Psref
ref: Not to be used
tableofcontents
textref
Textref
whichref
The NEWSTAR documentation system provides documentation in two forms: An on-line hypertext system based on the public-domain program "xmosaic" and standard LATeX documents. Both forms are derived from a single set of LaTeX source files; for the hypertext form, the public-domain translator latex2html is used. Broadly speaking, authors are free to use the standard LaTeX constructs. In particular, latex2html handles tabular material, mathematical formulas and the inclusion of diagrams very well. Writers should be aware, however, that every bit of math-mode text is translated into a little bitmap that must be loaded separately for display. This considerably slows down both the processing by ndoc Cook and the display by xmosaic. Simple macros defined through \newcommand can be used freely, but complicated nesting of macros should be avoided. To satisfy the specific needs of the NEWSTAR system and circumvent some deficiencies of latex2html , the guidelines given below should be followed.
The document compiler ndoc automatically inserts a preamble including the \begin{document} and also appends the \end{document}. The source of a document may add private preamble elements such as \newcommand definitions. Apart from that, the first document line is the \chapter line:
The chapter is the basic documentation unit. ndoc formats the argument <text> as a hypertext or printed document title.
This creates a standard table of the chapter's contents in the printed document and an equivalent unnumbered table with links to the (sub)(sub)sections in the hypertext display.
These commands produce standard section headings, numbered in the printed document, unnumbered in the hypertext display.
In writing documents, the placeholder \whichref{text}{} can be used for references whose target is not yet known.
For most referencing commands, a companion with the leading character capitalised is available; these work the same way except that the text argument is printed in boldface. This feature is intended for use in the documentation home-page document, hb_contents.tex.
Cross-references must work in both the printed and hypertext versions of a document. For this reason, the standard LaTeX \ref command is unsuitable and the rules given below must be followed instead.
A label name must start in a dot as shown. LaTeX forbids the use of underscores in labels, even if they are escaped by a backslash; it is recommended to use dots instead.
This is translated for the printed document as <text> (sec. <section number>). In the hypertext display, <text> becomes a hypertext link to <label>. <text> may have a local format of its own, e.g. {\em <text>} or {\bf <text>}.
This is the form for a reference to a label in an external file. In the printed document it becomes <text> with a numbered footnote showing the directory and name of the target file's source and the target label.
<file name> is the name of a .tex file (without the .tex extension!) in directory \$n\_doc/latex; the name may contain neither dots nor uppercase characters, but underscores are allowed (and need not to be quotes with a backslash).
can be used as a placeholder for a \textref whose target is as yet unknown.
The documentation system also contains ASCII documents and PostScript documents imported from elswehere. Such documents may be referred to through the following commands:
<file name> is the name (without extension!) of a .txt file in directory \$n\_doc/txt or of a .ps file in directory \$n\_hlp; the name may contain neither dots nor uppercase characters, but underscores are allowed (and need not to be quotes with a backslash).
This command is used to refer to program code or WNTINC table definitions (.dsc files). directory must be specified relative to n_src and the file extension must be included.
The commands \Eqref{.<label>} and \eqref{.<label>} are entirely analogous to the figure references \Figref and \figref.
Figures with their captions reside in the directory \$n\_doc/fig. A figure consists of two components:
A figure with its caption is included in a document source file through the command
\input{../fig/<name>.cap
In the printed document, figure and caption are included in the standard way. In the hypertext display the word FIGURE is included, followed by the caption text, with a hypertext link from FIGURE to a postscript file. ndoc generates that file automatically from the .fig file.
The purpose of the caption file (as opposed to spelling out the caption text in the document source) is to enable the figure with its caption to exist as an independent unit that can be included in more than one document and also exist outside the context of any document.
The caption file must not only provide the caption, but also the title under which the figure may be listed in the Handbook Overview. It is therefore important to adhere strictly to the following format:
\begin{figure}[htbp]
\fig{<name>}
\caption[]{<optional LaTeX commands, e.g. \it>
<title>
<optional LaTeX commands, e.g. \> <optional remainder of caption>
}
\label{.<label>}
\end{figure}
Examples can be found in the /\$n\_doc/fig directory.
You are free to choose the label; the recommended choice, however, is the file name with underscores replaced by dots. (Remember that underscores are illegal in labels and that labels must start with a dot.)
Comment lines (but no empty lines!) may be arbitrarily added, except that the <title> line must immediately follow the \caption command.
.fig files may be created without any restrictions with the public-domain program xfig. It is not necessary to produce a postscript file with this program. ndoc/ will take the .fig file and convert it automatically.
Often, figures drawn on a convenient scale on a workstation screen will not fit on a standard A4 page. ndoc/ may be instructed to automatically reduce its scale by including in the figure a text line
<file name>.fig <nn> It is best to put this text in an inconspicuous corner and a small font (e.g. 10pt as opposed to a standard 20pt).
It is also possible to include Postscript figures produced in other ways than through xfig: Use the command \ps{<filename>} instead of \fig and place the postscript file <filename>.ps in the directory /\$n\_doc/bin with a soft link to it in \$n\_hlp. If it can not be easily recovered, it is advisable to protect it against accidental deletion!
For references to figures, use
\figref{.<label>} and \Figref{.<label>}
These commands translate to hypertext links figure or Figure in the hypertext document, and to a standard reference figure <n> or Figure <n> in the printed document.
Verbatim transcripts of pieces of terminal dialogue controlling program execution are an important ingredient to documentation. Such transcripts are easily produced through the command ndoc S[cript] <file name> This starts a cshell script session in which you execute the program of which you want a transcript. After exit from the script session, the collected script is automatically formatted into a LaTeX file <file name>.trs; what remains for you to do is to cut out the irrelevant parts and perhaps add some comments. A sample section of such a file is shown below
%
\spbegin %
\skeyword{USE\_SCN\_NODE} \sprompt{(input node name)} \sdefault{= *:}
\suser{?} %
\svbegin \begin{verbatim}
Specify the node name from which the corrections should be calculated.
* indicates the same as the output node name.
\end{verbatim}\svend
\spend
%
%
\spbegin %
\skeyword{USE\_SCN\_NODE} \sprompt{(input node name)} \sdefault{= *:}
\suser{*} \sinline{Use the same SCN file} \spend
%
%
\spbegin %
\skeyword{USE\_SCN\_SETS} \sprompt{(Set(s) of input uv-data Sectors:
g.o.f.c.s)} \sdefault{= "":} \suser{2.0.0.0.0} \sinline{Sets in job 2}
\spend %
%
\spbegin %
\skeyword{HA\_RANGE} \sprompt{(DEG) (HA range)} \sdefault{= *:}
\suser{\scr} \sinline{Use all scans in these sets} %
\svbegin \begin{verbatim}
0123456789ABCD
0 -+++++++++++++
1 -++++++++++++
2 -+++++++++++
3 -++++++++++
4 -+++++++++
5 -++++++++
6 -+++++++
7 -++++++
8 -+++++
9 -++++
A -+++
B -++
C -+
D -
\end{verbatim}\svend
\spend%
The file consists of sections delimited by \spbegin and \spend, each consisting of a prompt with its reply and the ensuing output from the computer. LaTeX will treat these sections as blocks in which a page break can not occur. The following LaTeX commands are used:
It is necessary to check these scripts with some care. The system does occasionally get confused by the way the parameter interface splits long input and output lines. The errors are usually easily corrected.
On-line Help files in the NEWSTAR
FIGURE
.] documentation system and their origins.
Files shown in boldface are the documentation and program sources, those
shown in regular print are the derived Help files.
The full-drawn arrows indicate hypertext links for diagrams. The links to
the other files types are not shown. The dotted arrow indicate links to in-line
picture files that contain formulas and tables.
The dashed arrows indicate the relations between the files: Straight arrows
represent a direct derivation, merging arrows a source-file inclusion. The
capital letters on the arrows show in which procedure the derivation is
implemented:
C= ndoc Cook; F= ndoc Fig; T= ndoc Test; P= ndoc Print.
Printable documents in the NEWSTAR
FIGURE
.] documentation system and their origins.
Files shown in boldface are the documentation and program sources, those
shown in regular print are the derived printable files in the Help system.
The dashed arrows indicate the relations between the files: Straight arrows
represent a direct derivation, merging arrows a source-file inclusion. The
capital letters on the arrows show in which procedure the derivation is
implemented: F= ndoc Fig; T= ndoc Test; P= ndoc Print.
The documentation system encompasses three classes of files. The document source files reside in subdirectories of $n_doc; the code source files which may also be referenced reside in subdirectories of $n_src. All hypertext files reside in a tree of subdirectories rooted in \$n\_hlp. The interrelations of all these files are shown in figure.
The following types of source texts are used:
In processing, temporary files are created in the current directory; their names either contain the string \_tmp. or end in .tmp. ndoc normally deletes them when exiting.
latex2html, invoked by ndoc Cook, translates each file <name>.tex into a file \$n\_hlp/<name>/<name>.html. A large number of .html files are therefore in subdirectories of \$n\_hlp.
ndoc Print creates .ps PostScript text files in \$n\_hlp. ndoc Fig creates .fps PostScript diagram files in \$n\_hlp.
The commands are of the form ndoc <operation> [-<option>] <file> <file> is the full file name including the extension, and it must be in the current directory. Wildcards may be used. The <operation> and -<option> arguments may be abbreviated and are case-insensitive. The following operations and options are available:
Print uses the LaTeX program. It attempts to suppress the verbose output of this program by filtering out everything except essential error messages. If you encounter a problem that you can not solve, submit your source file to the NEWSTAR group for diagnosis.
ndoc checks the dates of its input and output files. If the output is newer than the date, ndoc emits a message and proceeds with the next input file. This check is incomplete in that it does not check the status of \input files such as figure captions.
There are two ways of bypassing this check:
When working in a shadow system, ndoc makes no difference between hard copies and soft links to the master system: Both are unconditionally compiled.
To recompile the entire documentation collection from its sources, one uses the command ndoc All ndoc will ask which parts of the system to recompile, the default being 'yes' for all subsystems. In this mode of operation ndoc bypasses the check for an up-to-date output file.
One of the actions available in ndoc All is a systematic check of the correspondence between source and output files. This is a very useful action because it clears up leftovers of obsolete documents and pinpoints areas of trouble.
ndoc goes a long way in filtering from the verbiage that LaTeX spews out the essential diagnostics. It shows the essential section of LaTeX output where the error is reported (including a line number) plus five lines of text in the middle of which the error was found. Very often this information suffices to pinpoint the error. If it does not, you may have to take a better look either at your source or at the <file name>_tmp.tex file that is the file LaTeX was actually processing. Note that the line number reported refers to this latter file!
Specific errors that have been encountered and are not covered by this diagnosis mechanism are described below.
Both ndoc Print and ndoc Cook make use of LaTeX and may therefore be affected by LaTeX bugs. For cases not covered here, refer to "The LaTex Book", which is probably the best informed source about that program.
This is an obscure problem. One situation in which it has been observed is when a \figure environment is put at the very start of a document, i.e. without any preceding text. (This condition will not occur for regular documents but may occur in test situations.) It has also been seen in a case where a tabular environment was nested inside a table, in which case the solution was to remove the table environment.
This may happen when the optional argument in square brackets is omitted. As of 940914, this argument is automatically provided for by doc_preprocess.csh.
This happens when the \label directive in a figure declaration is placed before the \caption command.!
This has been seen to happen when a \section title argument is too complicated, e.g. because it contains italicised text.
This may happen when the expansion of a command defined through \newcommand contains a referencing command. Fix the problem by including escape charaters in the \newcommand definition.
The \caption environment appears to be sensitive to formatting. In particular new paragraphs (i.e. blank lines) and \indent commands have been noted to produce this nasty error. In some cases it was found necessary to put the \label before the \caption.
When LaTeX reports an error to ndoc, ndoc displays a five-line text section in the middle of which the error occurred. This is not from the original input text, but from the preprocessed text as it was eventually presented tp LaTeX. Most errors are easily recognised and traced back to the input .tex file.
This may very well be an error in the algorithm used by ndoc to merge paragraphs into single long lines. It is not necessarily clear why LaTeX does not accept the long line. An any rate, the recommended action is to check with the NEWSTAR manager.
In preprocessing documents, ndoc formats paragraphs into single lines to make it easier to identify LaTeX command sequences. Find the offending paragraph in you documents and insert <newline><blank> at some appropriate place. The leading paragraph will inhibit the merger of the two parts of the paragraph, yet LaTeX will format the two parts into one paragraph.
The program latex2html on which ndoc Cook is based is rather lax on checking LaTeX syntax but may stumble over the consequences of an error missed. It is therefore strongly recommended to first check the syntactical correctness of the .tex file through ndoc P.
latex2html runs LaTeX on a selection from the .tex file consisting of formulas, tabular material and diagrams. This run failed to produce a .dvi file, but latex2html gobbled up all the error information. This error may be due to improper configuration of your system, e.g. a misplaced .sty file. It is virtually impossible to diagnose except by using a modified version of latex2html .
The nplot_descr.aux file was not found, so sections will not be numbered and cross-references will be shown as icons.
Your .tex file contains a \ref directive. Convert al \refs to \textrefs.
This is likely to be the result of a syntax error. (For example, a missing \end{itemize} will cause \item to be reported as unknown.) Check your input file by running ndoc Print on it.
Note the file name appearing at the bottom of the xmosaic window when you point at the reference. This reference should be in either of the forms:
<file name>/<file name>.html \indent \verb../<file name>/<file name>.html
If it starts in a /, you have to replace your latex2html by the modified version.
The precise nature of this error is not understood, but it seems to indicate that something is wrong in a cross-reference. (e.g. a LaTeX \ref command). It has been seen to occur when a \ref with a label name containing dots is used (cf. the section on cross references).
latex2html is a public-domain perl script created by Nikos Drakos at Leeds University, England (Email: nikos@cbl.leeds.ac.uk) and available through anonymous ftp. It has been found to be a reliable and highly capable program. Apart from configuring it to the local environment, two changes were found necessary:
system("$LATEX $$_images.tex");
insert the lines
if (!-e "20756_images.dvi")
{system("cat 20756_images.log"); die "Failure to process formulas"; }
LaTeX allows many constructs, such as formulas, tables etc., for which there is no HTML counterpart (yet). latex2html converts each single occurrence of these into a little picture file that is linked in-line into the .html document. The pictures are stored in .png files in the same directory as the .html file.
Since building these pictures is a very time-consuming process, latex2html seeks to reuse them as much as possible whenever it recompiles a .tex file. To this end, it maintains an administration in the file images.pl in the .html file's directory. Therefore, to insure the integrity of the .html document, both the .png files and images.pl must be left in place. As of May 1996, doc_cook.csh contains a section of code that finds all in-line picture references in the renewed .html file, reports any referred-to files that are missing and deletes unreferenced .png files.
In cases a .png file is reported missing, the way to get it rebuilt is to delete images.pl in order to force latex2html to rebuild all the picture files from scratch.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.
.