summaryrefslogtreecommitdiff
path: root/web/webfiles/cweave-f-spec.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
committerNorbert Preining <norbert@preining.info>2019-09-02 13:46:59 +0900
commite0c6872cf40896c7be36b11dcc744620f10adf1d (patch)
tree60335e10d2f4354b0674ec22d7b53f0f8abee672 /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.tex273
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}
+
+
+