diff options
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.tex | 403 |
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: |