diff options
author | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2019-09-02 13:46:59 +0900 |
commit | e0c6872cf40896c7be36b11dcc744620f10adf1d (patch) | |
tree | 60335e10d2f4354b0674ec22d7b53f0f8abee672 /web/webfiles/cweave-f-spec.tex |
Initial commit
Diffstat (limited to 'web/webfiles/cweave-f-spec.tex')
-rw-r--r-- | web/webfiles/cweave-f-spec.tex | 273 |
1 files changed, 273 insertions, 0 deletions
diff --git a/web/webfiles/cweave-f-spec.tex b/web/webfiles/cweave-f-spec.tex new file mode 100644 index 0000000000..c9063e5585 --- /dev/null +++ b/web/webfiles/cweave-f-spec.tex @@ -0,0 +1,273 @@ +\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} + + + |