Unit tests for CWEB

[ohcount] / test / expected_dir / cweb.w / documentation / comment

% Sample CWEB file, excerpts from the libmp source code
@* \[1] Introduction.
A large piece of software like \MP\ has inherent complexity that cannot
be reduced below a certain level of difficulty, although each individual
part is fairly simple by itself. The \.{WEB} language is intended to make
the algorithms as readable as possible, by reflecting the way the
individual program pieces fit together and by providing the
cross-references that connect different parts. Detailed comments about
what is going on, and about why things were done in certain ways, have
been liberally sprinkled throughout the program.  These comments explain
features of the implementation, but they rarely attempt to explain the
\MP\ language itself, since the reader is supposed to be familiar with
{\sl The {\logos METAFONT\/}book} as well as the manual
@.WEB@>
@:METAFONTbook}{\sl The {\logos METAFONT\/}book@>
{\sl A User's Manual for MetaPost}, Computing Science Technical Report 162,
AT\AM T Bell Laboratories.
@ The present implementation is a preliminary version, but the possibilities
for new features are limited by the desire to remain as nearly compatible
with \MF\ as possible.
On the other hand, the \.{WEB} description can be extended without changing
the core of the program, and it has been designed so that such
extensions are not extremely difficult to make.
The |banner| string defined here should be changed whenever \MP\
undergoes any modifications, so that it will be clear which version of
\MP\ might be the guilty party when a problem arises.
@^extensions to \MP@>
@^system dependencies@>
@ The external library header for \MP\ is |mplib.h|. It contains a
few typedefs and the header defintions for the externally used
fuctions.
The most important of the typedefs is the definition of the structure 
|MP_options|, that acts as a small, configurable front-end to the fairly 
large |MP_instance| structure.
@(mplib.h@>=
@<Exported types@>
@<Option variables@>
@<Exported function headers@>
@ The internal header file is much longer: it not only lists the complete
|MP_instance|, but also a lot of functions that have to be available to
the \ps\ backend, that is defined in a separate \.{WEB} file. 
The variables from |MP_options| are included inside the |MP_instance| 
wholesale.
@(mpmp.h@>=
@<Internal library declarations@>
@ @c 
@<Declarations@>
@<Basic printing procedures@>
@<Error handling procedures@>
@ The |__attribute__| pragma is gcc-only.
@<Internal library ... @>=
@ @c
@<Local variables for initialization@>
@<Set initial values of key variables@>
@<Install and test the non-local jump buffer@>;
@<Check the ``constant'' values...@>;
@.Ouch...clobbered@>
@<Run inimpost commands@>;
@<Initialize the output routines@>;
@<Get the first line of input and prepare to start@>;
@ The following system-independent code makes the |xord| array contain a
suitable inverse to the information in |xchr|. Note that if |xchr[i]=xchr[j]|
where |i<j<0177|, the value of |xord[xchr[i]]| will turn out to be
|j| or more; hence, standard ASCII code numbers will be used instead of
codes below 040 in case there is a coincidence.
@<Set initial ...@>=
@* \[3] Input and output.
The bane of portability is the fact that different operating systems treat
input and output quite differently, perhaps because computer scientists
have not given sufficient attention to this problem. People have felt somehow
that input and output are not part of ``real'' programming. Well, it is true
that some kinds of programming are more fun than others. With existing
input/output conventions being so diverse and so messy, the only sources of
joy in such parts of the code are the rare occasions when one can find a
way to make the program a little less bad than it might have been. We have
two choices, either to attack I/O now and get it over with, or to postpone
I/O until near the end. Neither prospect is very attractive, so let's
get it over with.
Different systems have different ways to get started. But regardless of
what conventions are adopted, the routine that initializes the terminal
should satisfy the following specifications:
\yskip\textindent{1)}It should open file |term_in| for input from the
terminal. (The file |term_out| will already be open for output to the
terminal.)
\textindent{2)}If the user has given a command line, this line should be
considered the first line of terminal input. Otherwise the
user should be prompted with `\.{**}', and the first line of input
should be whatever is typed in response.
\textindent{3)}The first line of input, which might or might not be a
command line, should appear in locations |first| to |last-1| of the
|buffer| array.
\textindent{4)}The global variable |loc| should be set so that the
character to be read next by \MP\ is in |buffer[loc]|. This
character should not be blank, and we should have |loc<last|.
\yskip\noindent(It may be necessary to prompt the user several times
before a non-blank line comes in. The prompt is `\.{**}' instead of the
later `\.*' because the meaning is slightly different: `\.{input}' need
not be typed immediately after~`\.{**}'.)
@ The following program does the required initialization
without retrieving a possible command line.
It should be clear how to modify this routine to deal with command lines,
if the system permits them.
@^system dependencies@>
@c 
@.**@>
@.End of file on the terminal@>
@ @<Declarations@>=
@ The symbolic names for internal quantities are put into \MP's hash table
by using a routine called |primitive|, which will be defined later. Let us
enter them now, so that we don't have to list all those names again
anywhere else.
@<Put each of \MP's primitives into the hash table@>=
@:tracingtitles_}{\&{tracingtitles} primitive@>
@:mp_tracing_equations_}{\&{tracingequations} primitive@>
@:mp_tracing_capsules_}{\&{tracingcapsules} primitive@>
@:mp_tracing_choices_}{\&{tracingchoices} primitive@>
@:mp_tracing_specs_}{\&{tracingspecs} primitive@>
@:mp_tracing_commands_}{\&{tracingcommands} primitive@>
@:mp_tracing_restores_}{\&{tracingrestores} primitive@>
@:mp_tracing_macros_}{\&{tracingmacros} primitive@>
@:mp_tracing_output_}{\&{tracingoutput} primitive@>
@:mp_tracing_stats_}{\&{tracingstats} primitive@>
@:mp_tracing_lost_chars_}{\&{tracinglostchars} primitive@>
@:mp_tracing_online_}{\&{tracingonline} primitive@>
@:mp_year_}{\&{year} primitive@>
@:mp_month_}{\&{month} primitive@>
@:mp_day_}{\&{day} primitive@>
@:time_}{\&{time} primitive@>
@:mp_char_code_}{\&{charcode} primitive@>
@:mp_char_ext_}{\&{charext} primitive@>
@:mp_char_wd_}{\&{charwd} primitive@>
@:mp_char_ht_}{\&{charht} primitive@>
@:mp_char_dp_}{\&{chardp} primitive@>
@:mp_char_ic_}{\&{charic} primitive@>
@:mp_design_size_}{\&{designsize} primitive@>
@:mp_pausing_}{\&{pausing} primitive@>
@:mp_showstopping_}{\&{showstopping} primitive@>
@:mp_fontmaking_}{\&{fontmaking} primitive@>
@:mp_linejoin_}{\&{linejoin} primitive@>
@:mp_linecap_}{\&{linecap} primitive@>
@:mp_miterlimit_}{\&{miterlimit} primitive@>
@:mp_warning_check_}{\&{warningcheck} primitive@>
@:mp_boundary_char_}{\&{boundarychar} primitive@>
@:mp_prologues_}{\&{prologues} primitive@>
@:mp_true_corners_}{\&{truecorners} primitive@>
@:mp_procset_}{\&{mpprocset} primitive@>
@:troffmode_}{\&{troffmode} primitive@>
@:mp_default_color_model_}{\&{defaultcolormodel} primitive@>
@:mp_restore_clip_color_}{\&{restoreclipcolor} primitive@>
@* \[47] Debugging.
Once \MP\ is working, you should be able to diagnose most errors with
the \.{show} commands and other diagnostic features. But for the initial
stages of debugging, and for the revelation of really deep mysteries, you
can compile \MP\ with a few more aids. An additional routine called |debug_help|
will also come into play when you type `\.D' after an error message;
|debug_help| also occurs just before a fatal error causes \MP\ to succumb.
@^debugging@>
@^system dependencies@>
The interface to |debug_help| is primitive, but it is good enough when used
with a debugger that allows you to set breakpoints and to read
variables and change their values. After getting the prompt `\.{debug \#}', you
type either a negative number (this exits |debug_help|), or zero (this
goes to a location where you can set a breakpoint, thereby entering into
dialog with the debugger), or a positive number |m| followed by
an argument |n|. The meaning of |m| and |n| will be clear from the
program below. (If |m=13|, there is an additional argument, |l|.)
@.debug \#@>
@<Last-minute...@>=
@.debug \#@>
@<Numbered cases for |debug_help|@>;
@ @<Numbered cases...@>=
@ Saving the filename template
@<Save the filename template@>=
@* \[48] System-dependent changes.
This section should be replaced, if necessary, by any special
modification of the program
that are necessary to make \MP\ work at a particular installation.
It is usually best to design your change file so that all changes to
previous sections preserve the section numbering; then everybody's version
will be consistent with the published program. More extensive changes,
which introduce new sections, can be inserted here; then only the index
itself will get a new section number.
@^system dependencies@>
@* \[49] Index.
Here is where you can find all uses of each identifier in the program,
with underlined entries pointing to where the identifier was defined.
If the identifier is only one letter long, however, you get to see only
the underlined entries. {\sl All references are to section numbers instead of
page numbers.}
This index also lists error messages and other aspects of the program
that you might want to look up some day. For example, the entry
for ``system dependencies'' lists all sections that should receive
special attention from people who are installing \MP\ in a new
operating environment. A list of various things that can't happen appears
under ``this can't happen''.
Approximately 25 sections are listed under ``inner loop''; these account
for more than 60\pct! of \MP's running time, exclusive of input and output.