path: root/macros/latex/contrib/cweb/src/cweave-spec.tex

% $DocId: cweave-spec.tex,v 1.8 1995/09/12 22:56:02 schrod Exp $
%------------------------------------------------------------

%
% specification of CWEAVE/TeX interface
%
% [LaTeX]
% (history at end)


% This file is either a subdocument of the style doc or a document on
% its own. In the former case it's a chapter, in the latter it's a
% ``normal'' LaTeX progltx document.
%     If it's a subdocument, this file will be included after
% \begin{document}. We can detect this: \document redefines
% \documentclass to be \@twoclasseserror. Then we also have to define
% how this document is ended: Either by \endinput or by an additional
% revision log.
% Of course, this test works only if LaTeX 2e is used for processing.

\expandafter\ifx \csname @twoclasseserror\endcsname \documentclass

        \let\endSubDocument=\endinput

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

\else

        \let\endSubDocument=\relax

        \documentclass{progltx}

        \usepackage{cweb-doc}           % additional document-specific markup
        \usepackage{a4-9}               % Tschichold's A4 layout


        \begin{document}

        \title{The Interface between \cweave{} and \TeX{}}
        \author{Joachim Schrod%
            \thanks{Email: \texttt{schrod@iti.informatik.th-darmstadt.de}}%
            }
        \RCSdate $DocDate: 1995/09/12 22:56:02 $

        \maketitle

        \sect

\fi




Here we present all tags output by \cweave{}%
    \footnote{This information refers to \cweb{}~3.4. Differences to
    other 3.x versions of \cweave{} are minor and can be ignored in
    our context. See the revision log of the complete interface specs
    document for more information.}
in an ordered fashion. First we look at those
tags which are part of the `protected interface,' i.e., 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 chunk
        && \arg1 chunk number
|\N| & |#1#2#3.| & \cweb{} structure tag: start of a section
        && \arg1 section rank, $0 \le |#1| \le 10$
        && \arg2 chunk number
        && \arg3 section title
|\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 chunk
|\9| & 1 & index entry, user defined layout
        && \arg1 text of index entry
\end{cseqtab}

|\ATL| does only appear in front of the very first chunk. The
chunk number is an explicit \TeX{} number which might be followed
by a `changed flag' (see chunk~\ref{sec:text-tag.priv}). Note the
usage of |\fi|, ie, each chunk 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''~chunk,
not in the ``|\|''~chunk.

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 chunk. Our problem is that we
have to produce the information which were produced by these tags in
the Plain macros. Namely the optional lists poses us the problems. We
must read behind the document end to gather the information which
lists to produce.

%% This label is used in cweb.doc
\label{spec:sec:docend}

We can depend on the following rules.
 %
\begin{enumerate}

\item If |\end| is found, there will be no other of these tags.

\item |\ch| comes first, but is optional.

\item |\inx\fin| come next, they are mandatory.

\item |\con| is optional again; if it is found it's the very last
token to look at in this document.

\end{enumerate}
 %
\begin{fixme}

Perhaps |\inx| should be defined as |\end{document}|, and both |\ch|
and |\inx| should be added to the protected interface. Then the user
may simply omit |\end{document}|. But we should take care of a
possible occurence anyhow.

\end{fixme}

Here are the tags mentioned in this chunk, and their respective
meaning in the Plain version:
 %
\begin{cseqtab}
|\ch| & |#1.| & Note which chunks are changed
        && \arg1 list of chunk numbers, like in |\U| and such.
|\inx| & & Create index
|\fin| & & Create the table of refinement names
|\con| & & Create the table of contents
|\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 chunk numbers occurs on several places: At the chunk
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 chunk, and
in the refinement name list at the very end. Everywhere where a
chunk number can occur it can be followed by a tag which shows that
this chunk was changed by the changefile.
 %
\begin{cseqtab}
|\*| &  & tag after chunk number: this chunk 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 chunk number in index
        && \arg1 chunk 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}

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
\verb"\|" & 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 chunk 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. Chunk
cross-referencing (actually, for program parts) is started with some
tag, then follows a list of chunk numbers.
 %
\begingroup
 \hfuzz=22pt    % 21.76602pt too wide (with a4-9.sty)
\begin{cseqtab}
|\A| &  & one add-on definition (``See also chunk'')
|\As| &  & more than one add-on definition (``See also chunks'')
|\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 chunk where it is cited (``This code is cited in chunk'')
|\Qs| &  & more than one chunk where it is cited (``This code is cited in chunk'')
|\U| &  & used in one chunk (``This code is used in chunk'')
|\Us| &  & used in more than one chunk (``This code is used in chunks'')
\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}




\endSubDocument


%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%

\vskip \PltxPreSectSkip

\begin{rcslog}
$DocLog: cweave-spec.tex,v $
\Revision 1.8 1995/09/12 22:56:02 schrod
|cweave -x| doesn't output |\vfill| in front of |\end| any more.
Change noticed in \cweb{} 3.4.

\Revision 1.7 1995/08/29 01:40:24 schrod
Checked the interface description for \cweb{}~3.4.

\Revision 1.6 1995/08/25 19:09:57 schrod
Cleaned up terminology: Chunks are not named sections any more.
Explicate possible range of section ranks.

\Revision 1.5 1995/08/08 00:14:26 schrod
Updated to \LaTeXe{}, the |cweb| style is now a document class. Used
my standard templates for that, no changes in functionality.

\Revision 1.4  1993/06/17  15:09:28  schrod
\cweb{} 3.0 was released officially on June 16, 1993. Mentioned in
the documentation that this version is needed for the |cweb| style.

\Revision 1.3  1993/06/14  17:50:14  schrod
Clarify the occurence pattern of the lists after the last section:
which are optional, the expected order, etc.

Changed `cseq' to `tag'. On this level of abstraction (that's the
specification!), we're still not considering \TeX{}nical details.

\Revision 1.2  1993/06/14  15:40:02  schrod
Adapted to April 93 changes to \cweave{}: |\N| has three parameters
(added group level), |\M| param is no data-tag any more, |\Z| and
|\MRL| are new.

Added further explanation of |\9| and |\X|.

Replaced `program part name' by `refinement name'.

\Revision 1.1  1993/04/09  15:00:37  schrod
Initial revision

\end{rcslog}



\end{document}

% LocalWords: