12. DOCUMENTATION

12.1 On-Line Help
12.2 Reference Guide

12.1 On Line Help

OrgC++ has an intelligent help function, which allows you to query about the organizations and functions that are in the library. This function automatically includes organizations/features added by the user.

On-line help uses a free format, and has no fixed syntax or menu. You simply enter, from the main OrgC directory:

zzhelp <string>

The program lists the OrgC++ features that best match the given string, and allows you to select commands for which you would like to see more documentation. The program retrieves the selected documentation, and places it into the file zzinfo, which you can browse using a standard editor or the UNIX more utility.

The query must be presented as a single string, even if it combines several words. For example: ADDRING, add_RING, and ringADD, will all produce the same result.

Each line on the screen shows: long name, short name, and the file in which the information is stored.

Under UNIX, the file zzinfo is automatically nroff-ed. Under DOS, the file has the raw nroff format, with typesetting instructions in it (format-me).

Using on-line documentation for the C++ version of the library requires a slightly different approach. You always start with the file that contains the ZZ_HYPER_ declaration. Let us assume, for example, that you are looking for details on how to delete an object from the DOUBLE_TREE. You proceed in these steps:

Example: zzhelp ADD_RING

Best match found:

select numbers:

Example zzhelp ringADDS

Best match found:

select numbers:

Example: zzhelp 1_TO_N

Best match found:
organization=1_TO_N

select numbers: 0 7 9
view file zzinfo ...

Example: zhelp NewYorkCity
nothing meaningful found

Find out which file contains ZZ_HYPER_DOUBLE_TREE. That can be done in two ways:

Method A:

cd orgC
zzhelp DOUBLE_TREE

This will give you a list of all the commands for this organization, including the file name in the most right hand column. In this case, the name will be hypdtree.

Method B:

You will get a list of about 30 files with names that are a bit cryptic but still meaningful. You will see that hypdtree clearly resembles the organization you are looking for.

The next step is to view (using your favourite editor) the file orgC/macro/hypdtree. The file contains the declaration of the interface class, iterator, and all the methods. You will see that the function del() is indeed there, and how it must be called. The big advantage of C++ is that all things related to one object are neatly kept together.

When you are looking into this file, you will also see that the actual code that deletes the object from the tree is hidden under a macro, in this case ZZ_DELETE_DOUBLE_TREE(). This has two reasons: (a) it makes the C and C++ code perform identically, (b) it saves a lot of coding.

If you followed Method A above, you already know the name of the file, where this macro is located (deldtree). You could easily have guessed it (the naming of all files follows the same convention; the only restriction is that they must be not more than 8 characters in order to make the whole system compatible with DOS). Another possibility is to call the interactive help again:

zzhelp DELETE_DOUBLE_TREE

The last step is to view (using your editor again) the file deldtree. This file contains all the technical information available about the algorithm, its behaviour, possible errors, etc. Each file also contains a short example which is, at the present time, mostly in C. We are gradually adding C++ related documentation to all of the files, but this is a long term process.

Note that there is a direct mapping of calling parameters between C macros and C++ methods. You can either look in the tables shown in Appendix A, or remember these rules:

• If the call does not return any values, parameters are the same, except for the organization id which, in C++, is used differently: ZZ_DELETE(id,par,obj); translates into void id.del(par,obj); ZZ_SAVE(file,n,v,t); translates into util.save(file,n,v,t); because there is no UTILITY class in C (save and allocation utilities are simply global).
• If the call returns a parameter (and it never returns more than one, usually the last one), the parameter moves ahead of the function: ZZ_CHILD(id,par,ch); translates into ch=id.child(par); ZZ_FORWARD(id,obj,next); translates into next=id.fwd(obj);

If you find this system a little bit too complex for the beginning, remember that you don't have to use it until you start to add or modify the library. The printed Users' Guide contains all the information you need to use the libraries.

12.2 Reference Guide

OrgC++ documentation consists of three documents:

• User's Guide;
• Reference Guide (this chapter describes details);
• On-line help (explained in Chap.12.1).

The User's Guide is shipped with the software, and is available in printed form only.

You can generate the Reference Guide automatically from within the orgC/docum directory, by typing: zzdocum <mFile>

If you don't specify any mFile, the program creates a complete Reference Guide, if you give an mFile, it generates only an update for commands/macros specified in the file. For C++, provide ZZ_HYPER_declaration names, plus corresponding C-command names (see Appendix A). In either case, the generated document includes an index by organization/function name, and one UNIX-like page for each function or macro. Documentation for every feature includes an example, and is identical to the information you obtain when calling zzhelp.

The text of the Reference Guide will be stored in the file orgC/docum/ZZrefer and will be in nroff -me format. If you run under DOS or do not have nroff -me available on your UNIX system, you can call orgC/zzroff, which will format the text for the printer. Assuming that you are in the orgC/docum directory, you have to type:

..\zzroff ZZrefer temp
print temp

Note that OrgC is using an advanced concept of creating documentation directly from the source code. OrgC macros and functions are stored in the orgC/macro directory, with the source code and the documentation together in each file. The documentation program retrieves the Reference Guide directly from these files, while the zzcomb program (see Chap.16), retrieves the source code stripped of comments and generates orgC/zzcomb.h.

If you require only the Reference Guide update, list only those macros/functions for which you want documentation.

Example of mFile:

ZZ_ADD
ZZ_DELETE_SINGLE_TREE
ZZpar1T

WARNING: A zzdocum run always overwrites the old file ZZrefer. If you want to generate update pages only, rename ZZrefer before calling zzdocum.

Chapter 11: Available Organizations

Chapter 13: Memory Management