path: root/web/webfiles/cweave-f-spec.tex

\iffalse
% specification of CWEAVE/TeX interface for use in the documentation 
% of the cwebfiles style option
%        =========
%
% Based on cweave-spec.tex by Joachim Schrod.
% [LaTeX]
\fi

	\chap The interface between \cweave{} and \TeX{}.
	\label{sec:cweave-spec}



Here we present all tags output by \cweave{}\footnote{This information
	refers to \cweb{} 3.0.}
in an ordered fashion. First we look at those
tags which are part of the `protected interface,' ie, they are
visible to a \cweb{} user, but he must not use them. Then we consider
the private tags, some are used in the documentation part, others
are needed to typeset program code, and there are a few tags for
typesetting special characters in strings.


\sect Some tags output by \cweave{} are part of the protected
interface even though they are not prefixed by |cweb|. We'll present
them in the order they'll arrive in the document instance.

The following table specifies in the second column if this tag takes
arguments. If the entry is non-empty, it's either a number listing
just how many arguments are expected; then usual argument passing is
used. Or it displays the context required.
 %
\begin{cseqtab}
|\ATL| & \verb*|#1 #2 | & \cweb{} operator: |@l|
	&& (how to output non-ASCII chars in \ctangle{})
	&& \arg1 hex code of mapped character
	&& \arg2 string output by \ctangle{}
|\M| & 1 & \cweb{} structure tag: start of a section
	&& \arg1 section number
|\N| & |#1#2#3.| & \cweb{} structure tag: start of a section group
	&& \arg1 group depth, $0 \le |#1|$
	&& \arg2 section number
	&& \arg3 section group name
|\PB| & 1 & restricted program mode material
	&& \arg1 program code
|\Y| & & between major pieces of a program part
|\B| & & start program material
|\fi| & & \cweb{} structure tag: end of a section
|\9| & 1 & index entry, user defined layout
	&& \arg1 text of index entry
\end{cseqtab}

|\ATL| does only appear in front of the very first section. The
section number is an explicit \TeX{} number which might be followed
by a `changed flag' (see section~\ref{sec:text-tag.priv}). Note the
usage of |\fi|, ie, each section must open an according |\if|. |\PB|
might appear within its own argument (created by restricted program
mode material in a refinement name within restricted program mode).

|\9| deserves a further explanation: It is expected, though not
defined, that it expands to an empty token list. The parameter will
be a sort key, actually; the real key to be typeset will appear
afterwards. So a \cweb{} user might index \TeX{} as
`|@:TeX}{\TeX@>|', the index will feature it in the ``T''~section,
not in the ``|\|''~section.

With the exception of |\PB| the tags above will not appear in math mode.


\sect The following tags might appear to be public ones, but they
are, in fact, never used. That's because they will be placed after
the |\fi| which terminates the last section.
The tags are given with their respective meaning in the Plain version:
 %
\begin{cseqtab}
|\ch| & |#1.| & Note which sections are changed
	&& \arg1 list of section numbers, like in |\U| and such.
|\inx| & & Create index
|\fin| & & Create the table of refinement names
|\con| & & Create the table of contents
|\vfill\end| & & output if index and all lists were suppressed
\end{cseqtab}



\sect \label{sec:text-tag.priv}
 Some tags appear only in special circumstances and may therefore be
considered as private tags. The largest part of them concern the tagging of
program code, we'll have a look at them later. First we present the
tags used in other areas.

Lists of section numbers occurs on several places: At the section
start (where the list has actually only one element), within
refinement names, in the identifier index, and for cross reference
purposes. Cross references can be made at the end of a section, and
in the refinement name list at the very end. Everywhere where a
section number can occur it can be followed by a tag which shows that
this section was changed by the changefile.
 %
\begin{cseqtab}
|\*| &  & tag after section number: this section is changed.
\end{cseqtab}

Within the identifier index we have also special tags. The identifiers
are tagged like in the program mode, ie, with |\\| and |\&|. Remember
that |\9|, listed above, appears also in the index.
 %
\begin{cseqtab}
|\I| & \verb*|#1, | & start of an index entry
	&& \arg1 index entry
|\[| & |#1]| & underlined section number in index
	&& \arg1 section number
|\.| & 1 & |@.| index entry
	&& \arg1 index entry
\end{cseqtab}

In the list of refinement names the entries are marked similar to
the index entries. But note that |\I| has no arg here.
 %
\begin{cseqtab}
|\I| & & start of a new refinement name
\end{cseqtab}


\sect \label{sec:prog-tag}
 OK, now we can have a look at the large amount of tags used
for tagging program code. First, we have those which represent
directly C or \C++ tokens.
 %
\begin{cseqtab}
|\?| &  & C operator: conditional expression
|\AND| &  & C operator: logical and
|\CM| &  & C operator: binary complement
|\DC| &  & \C++ operator: scope resolution
|\E| &  & C operator: equivalence
	&& and equivalence sign after refinement name on it's definition
|\G| &  & C operator: greater or equal
|\GG| &  & C operator: shift right
|\I| &  & C operator: not equal
|\K| &  & C operator: assignment
|\LL| &  & C operator: shift left
|\MG| &  & C operator: pointer to struct component
|\MGA| &  & \C++ operator: pointer to pointer to member
|\MM| &  & C operator: decrement
|\MOD| &  & C operator: modulo (actually, remainder)
|\NULL| &  & `quoted' identifier
|\OR| &  & C operator: binary or
|\PA| &  & \C++ operator: pointer to member
|\PP| &  & C operator: increment
|\R| &  & C operator: logical negation
|\this| &  & `quoted' identifier
|\TeX| &  & `customized' identifier
|\V| &  & C operator: logical or
|\W| &  & C operator: logical and
|\XOR| &  & C operator: binary exclusive or
|\Z| & & C operator: less or equal
\end{cseqtab}

\def\vbar{\char"7C}
Other tokens have variable parts, passed as arguments.
 %
\begin{cseqtab}
|\.| & 1 & C string
	&& \arg1 string
|\)| &  & discretionary break between string parts
|\&| & 1 & reserved identifier
	&& \arg1 identifier
|\\| & 1 & ``normal'' identifier with more than one chars
	&& \arg1 identifier
|\|{\tt\vbar} & 1 & ``normal'' identifier with one char
	&& \arg1 character
|\C| & 1 & C comment
	&& \arg1 comment text
|\MRL| & 1 & C operator: combined binary operators
	&& \arg1 operators, |\K| must print as `$=$'
|\SHC| & 1 & \C++ comment
	&& \arg1 comment text
|\T| & 1 & numeric constants
	&& \arg1 constant
|\X| & |#1: #2\X| & refinement name
	&& \arg1 section number
	&& \arg2 refinement name
\end{cseqtab}
 %
The refinement name (second argument of |\X|) may be a file name
tagged by `|\.|'. Then the name must be set like a C~string.

\cweb{} itself introduces its own operators:
 %
\begin{cseqtab}
|\ATH| &  & |@h| (place the preprocessor definitions here)
|\D| &  & |@d| (define macro)
|\F| &  & |@f| (format identifier like another one)
|\J| &  & |@&| (join)
|\vb| & 1 & |@=| (pass arg verbatim by \ctangle{})
	&& \arg1 string
\end{cseqtab}

And we have some tags used for cross referencing. Section
cross-referencing (actually, for program parts) is started with some
tag, then follows a list of section numbers.
 %
\begingroup
 \hfuzz=22pt
\begin{cseqtab}
|\A| &  & one add-on definition (``See also section'')
|\As| &  & more than one add-on definition (``See also sections'')
|\ET| &  & separator between the last two numbers if there are only two
|\ETs| &  & separator between the last two numbers if there are more than two
|\Q| &  & the section where it is cited (``This code is cited in section'')
|\Qs| &  & more than one section where it is cited (``This code is cited in section'')
|\U| &  & used in one section (``This code is used in section'')
|\Us| &  & used in more than one section (``This code is used in sections'')
\end{cseqtab}
\endgroup

Program code must be indented according to its structure. Each
``larger'' statement is typeset as one paragraph, usually only one
line long. The basic indentation of the next statement may be
incremented and decremented in given units. If a statement has to be
broken in more than one line nevertheless, a hanging indentation is
added to the basic indentation for the subsequent lines. One can mark
an `optional' statement start, ie, some kind of optional paragraph
start. If a line break must be inserted it should be inserted here and
no hanging indentation should be added to the basic indentation.
 %
\begin{cseqtab}
|\1| &  & future stmts indented one more unit
|\2| &  & future stmts indented one less unit
|\3| & 1 & optional line break within a statement
	&& \arg1 digit, penalty for line break
|\4| &  & backspace one indentation unit
|\5| &  & optional line break or small space (between run-in statements)
|\6| &  & line break
|\7| &  & line break and additional vertical space
|\8| &  & line is a preprocessor directive (must be issued at start of line)
\end{cseqtab}


\sect Some args are designated as strings above. Within these args the
following tags are used to represent special characters:
 %
\begin{cseqtab}
\verb*|\ | &  & space
|\&| &  & ampersand
|\\| &  & backslash
|\^| &  & hat
|\_| &  & underscore
|\{| &  & left brace
|\}| &  & right brace
|\~| &  & tilde
\end{cseqtab}


\sect Last, we have tags which are used in their ``standard''
\LaTeX{} meaning. We don't have much work with them:
 %
\begin{cseqtab}
|\#| &  & hash mark in program or in string
|\$| &  & dollar
|\%| &  & percent
|\{| &  & block start (is set in math mode)
|\}| &  & block end (is set in math mode)
|\,| &  & thin space (like the \LaTeX{} default)
|\langle| &  & left delimiter in include directives, or in templates
|\le| &  & C operator: less or equal
|\ldots| &  & Function protoypes: Variable number of arguments
|\rangle| &  & right delimiter in include directives, or in templates
\end{cseqtab}