 News |
FAQ
|
| Search
|
Home
|
| Getting Started | Documentation | Glish | Learn More | Programming | Contact Us |
|
| Version 1.9 Build 1556 |
|
Good documentation is vital for the success of code contributed to AIPS++. Without documentation, your code will be neglected. In AIPS++, user documentation is written in latex using a set of special purpose macros. These are defined in aips2help.sty. The example for the tableplotter is worth studying.
If at all possible, provide a global function for demonstration that illustrates how the application is to be used. Place the demo function inside the .g file that contains the application code. Try to make the demonstration as self-contained as possible without compromising the demonstration. Here is the demo function for tableplotter:
const tableplotterdemo:=function() {
localtp:=tableplotter();
col1:=tablecreatescalarcoldesc("N",0);
col2:=tablecreatescalarcoldesc("N^2",0);
td := tablecreatedesc (col1, col2);
tb := table('squares', td, 100);
tb.putcol("N", 1:100);
tb.putcol("N^2", (1:100)^2);
print localtp.settable(tb);
print localtp.setx("N")
print localtp.sety("N^2");
print localtp.auto();
localtp.x.label:="N";
localtp.y.label:="N**2";
localtp.title:="Squares";
print localtp.show();
print localtp.getxy();
print localtp.plot();
print tb.delete();
print shell('rm -r squares');
}
Note that it is self-contained, constructing a table specially for the demonstration. Note also that all public functions are invoked. Remember that a good demonstration can often help a user penetrate the fog of confusing or inadequate documentation.
To support writting user based help for AIPS++ in LaTeX, we have developed an aips2help.sty file for generating stylistically proper documentation. While it is not necessary for you to write the documentation using the aips2help.sty we urge you to use it. If you use the aips2help.sty and the help templates, it will be possible to parse the help input files and provide non-html-on-line help.
User help (for scripts and stand-alone commands) is written at three levels:
To see what your .help file will look like in the "AIPS++ User Reference Manual"you need to run help2tex on your .help file. Help2tex translates the .help file into a vanilla LaTeX used in the "AIPS++ User Reference Manual". You may run latex2e or latex2html on your .help file without running it through help2tex, but the output will be different from what appears in the "AIPS++ User Reference Manual".
\begin{ahenvironment} and end the environment block with
\end{ahenvironment}.)
\ahaddarg to identify the aipsrc variables.
\ahdatum to
identify public data members.
\ahdatum to
identify record members.
\ahaddarg to identify the
arguments.
\begin{tex2html_preform}verbatim42#\end{tex2html_preform} block.
\ahlink command to specify what else to look at.
\ahlink{calc the constructor}{images:image.calc.constructor}
for the global calc function
\ahlink{calc the function}{images:image.calc.function}
Used inside the ahseealso environment.
\input{mypackage.help}
This example of module documentation comes from code/trial/apps/table/table.help.
\begin{ahmodule}{table}{Glish interface to table system}
\ahinclude{"table.g"}
\begin{ahdescription}
table allows creation of table objects inside Glish. The resulting
objects can be operated on in various ways:
\begin{itemize}
\item Creation of new tables,
\item Opening, deletion, cloning, copying of existing tables,
\item Set and put of table information strings,
\item Get and put of table cells, columns and keywords,
\item Iteration by subtables,
\item Access via table rows,
\item Browsing of tables,
\item Printing of a summary of a table,
\end{itemize}
In addition this module contains a number of global functions
related to tables.
\end{ahdescription}
\begin{ahexample}
\begin{verbatim}
include "table.g"
vis:=table("3C273XC1.MS", readonly=T);
vis.summary();
uvw:=vis.getcol("UVW");
spw:=table("3C273XC1.MS/SPECTRAL_WINDOW", readonly=T);
freq:=spw.getcell("REFERENCE_FREQUENCY", 1);
uvw*:=(1.420E9/freq);
vis.putcol("UVW", uvw);
vis.close();
\end{verbatim}
\end{ahexample}
\begin{ahseealso}
\ahlink{tablerow}{tablerow.label}
\ahlink{tableiterator}{tableiterator.label}
\end{ahseealso}
\ahobjs{}
\ahfuncs{}
.... Lots of stuff deleted
\end{ahmodule}
This example of object documentation comes from code/trial/apps/table/table.help.
\begin{ahobject}{table}{table object}
\begin{ahconstructor}{table}{Construct table object}
\begin{ahargs}
\ahaddarg{tablename}{Name of table on disk}{F}{Bool}
\ahaddarg{tabledesc}{Table descriptor}{F}{Bool}
\ahaddarg{nrow}{Number of rows}{0}{Int}
\ahaddarg{readonly}{Open Read-only?}{F}{Bool}
\ahaddarg{ack}{Acknowledge creations, etc}{T}{Bool}
\ahaddarg{tablehandler}{Table handler to be used}{gtable}{Any tableserver}
\ahaddarg{tablelogger}{logger to be used}{logger}{Any logger object}
\ahreturns{object}
\end{ahargs}
\ahfuncs{}
\begin{ahexample}
\begin{verbatim}
table1:=table("3C273XC1.MS");
table2:=table("3C273XC1.new.MS", table1.getdesc());
\end{verbatim}
\end{ahexample}
\begin{ahcomments}
The first line opens an existing table 3C273XC1.MS, the second creates another
table using the table description of the first table, but no rows are written.
\end{ahcomments}
\end{ahconstructor}
\begin{ahfunction}{ok}{Is the table object ok?}
\ahreturns{Bool}
\end{ahfunction}
....Lots of stuff deleted....
\end{ahobject}
\begin{ahfunction}{tablecommand}{Execute a tablecommand}
\begin{ahargs}
\ahaddarg{comm}{Command string}{}{Any valid table command}
\end{ahargs}
\begin{ahexample}
\begin{verbatim}
print tablecommand('SELECT FROM table.in WHERE column1*column2$>$10 ORDERBY
column1 GIVING table.out');
\end{verbatim}
\end{ahexample}
\ahreturns{Bool}
\begin{ahcomments}
The grammar for the command string is SQL-like and is defined
in TableGram.l and explained in Tables.h.
Between SELECT and FROM you can give some column names (separated by
commas). Then the output table will contain those columns only.
If no column names are given, all columns will be selected.
E.g.: SELECT column1, column2,column3 FROM table.in GIVING table.out
The WHERE part (like column1*column2$>$10) contains an arbitrary expression.
Functions (like sin, max, ceil) are supported. Only scalar columns
(or keywords) can be used in the expression. Complex numbers must
be given as, for example, 3.4+4i (similar to glish).
With some extra syntax (not explained here) it is even possible
to use keywords from other tables in the expression.
Rows obeying the WHERE expression will be selected.
Sorting can be done with the ORDERBY clause. You can give there any
number of (scalar) columns separated by commas. You can use a mix of
ascending (is default) and descending.
E.g.: ORDERBY column1 DESC, column2, column3 ASC, column4 DESC
The GIVING clause defines the output table containing the
requested rows and columns. It can be used as any other table.
Each part (column selection, expression, sorting, giving) is optional.
\end{ahcomments}
\end{ahfunction}
The .help files are used for two purpose, one generate standard LaTeX for a "printed" reference manual (Refman) and the other to generate glish help atoms for use by the help function in glish.
To generate the LaTeX document, there is a special helpsys target in the code/doc/user makefile. It searches the active code tree, (trial, aips, synthesis, and nrao) for all files ending in a .help, .ps, and .eps extension. Once the documents are collected, help2tex is run on the package helpfiles and .htex files are produced. These .htex files are compared with the existing ones in docs/user/helpfiles and if different updated. The .ps and .eps files are also moved to this directory if necessary. Help atoms file for glish are generated if necessary at this time by help2tex. The standard .latex rules take over after all the copying is done.
We encourage your to check out your help file by doing the following,
gmake myfile.dvi
The gmake runs help2tex on the file myfile.help and then runs latex on the resulting ".htex" file. It's important to make sure your .help file runs through the process clean. If it fails any documentation that follows won't be included in the Refman. If have relative-outside links in your .help file or links to other parts of the Refman, they will be hi-lighted but the hyper-links will fail when built in the "programmer" tree. This happens because of three things: