summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex')
-rw-r--r--Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex403
1 files changed, 403 insertions, 0 deletions
diff --git a/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex b/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex
new file mode 100644
index 00000000000..c1f5b4f07ff
--- /dev/null
+++ b/Master/texmf-dist/doc/latex/cweb-latex/src/cweave-spec.tex
@@ -0,0 +1,403 @@
+% $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: