User's Guide to WebWeb ver 2.6

Contents

1 Command options

2 Output File Options

3 Tags
3.1 Tags valid in the Documentation Sections
3.2 Tags Valid in the Scrap Header
3.3 Tags Valid in the Scraps

4 The formatting strings
4.1 The default settings for HTML
4.2 The default settings for LaTeX

5 Differences between nuweb and WebWeb



This is the user's guide to WebWeb.
It mainly consists of a tabulated reference manual.
For all users who are familiar with nuweb we list the differences between nuweb and WebWeb in the last chapter of this guide.

1 Command options

 The usage is: 
webweb [-h] 
       [-i] [-f] 
       [-d] [-o] 
       [-s] 
       [-N docfileName] 
       filename


The command options have the following meaning:

-h help prints a list of command line options.
-i interactive asks for each output file as well as for the documentation whether to write it or not.
-f force forces the (over-)writing of all generated files.
-d no documentation suppresses the generation of the documentation.
-o no output file suppresses the generation of any program file with the exception of the documentation.
-s ssilent suppresses the printing of the version of WebWeb, which is done by default.
-N docfileName Name writes the documentation to docfilename.
filename the name of the source file. Must have extension .ww.

2 Output File Options

 There are some options you can attach to each output file that will be created:

-i no indent suppresses the indentation of macros
-l line writes the #line directive at the beginning of each scrap to the file


3 Tags

 There are several tags you can use in a WebWeb source file.
Some of them can only be used in the documentation section. Others are only valid in a scrap, and some tags can be used anywhere.

3.1 Tags valid in the Documentation Sections

 Following tags, listed in the table, can be used in the documentation section:

@l language sets the documentation language to language. Must be set to HTML or LaTeX if a default formatting is wanted.
@i filename includes the file filename.
@@ causes a single at-sign to be printed.
@f prints list of output files.
@m prints list of macros.
@u prints user-defined index.
@| text @| text will be displayed in the same font as the scraps.
@<scrapname@> macro call to scrapname. Scrap scrapname will be expanded here. Note that the scrap to be expanded must be defined as a hidden scrap.

Writing WebWeb you can use the following meta-signs to define a scrap: Note that they can only be called within the documentation section.

@d scrapname define defines the scrap scrapname. Must be followed by @{.
@o filename output defines the output file filename. Must be followed by @{.
@h scrapname hide defines the scrap scrapname. This defines a hidden scrap. That means that this definition will not be written to the documentation. Must be followed by @{.


3.2 Tags Valid in the Scrap Header

 In a scrap header only one tag is allowed. It is the one the body starts with. Therefore, the header automatically ends with the tag starting the body.

@{ starts the body of a scrap. Use only after a scrap header.


3.3 Tags Valid in the Scraps

 Within the body of a scrap, the following tags are valid:

@@ causes a single at-sign to be copied to the output file.
@<scrapname@> macro call to scrapname. Scrap scrapname will be expanded in the program files but not in the documentation.
@$ text @$ text will be displayed in the same font as the documentation sections.
@+ string puts string in the user-defined index. Must be followed by another @+ or by @} at the end of a scrap.
@} terminates the body of a scrap.


4 The formatting strings


As we described in the documentation of WebWeb, we gave the user the possibility to change some layout details. Some examples:
To do so you just have to use some of the following tags. Note, that they may only be used in the documentation section. To print one or more of them, you start the formatting string definition environment with @s indicating that a scrap will follow which holds the formatting strings.
As all the other scraps are these scraps enclosed in @{ and @}, too. Everything written between the @s and the @{ will be ignored. We recommend to put them together at the beginning or at the end of the web file.

@S{ formatting string string which is copied at the very beginning of each scrap
@S} formatting string string which written at the end of each scrap
@H| formatting string string to format the header of a scrap
@B{ formatting string this string is printed between the header and the body of a scrap.
@B} formatting string this string is printed between the body of a scrap and the defining strings appended to it.
@M{ formatting string string for the special formatting of a macro call inside a scrap.
@M| formatting string string to format the list of numbers listed after a macro call inside a scrap.
@M} formatting string string to end the special formatting of a macro call inside a scrap.
@D| formatting string string to format the line which is attached to each scrap and holds the numbers of scraps defining the current macro. (Includes the string: Also defined in:)
@R| formatting string string to format the line which is attached to each scrap and holds the number of scraps referencing the current macro. (Includes the string: Scrap is referenced in:)
@N| formatting string string to format each scrap number in a list of numbers. Used if a list of scrap numbers in the strings @R| and @D| are wanted.
@K| formatting string character (string) to separate each number in a list of numbers. Usually a comma.
@L{ formatting string this string is printed at the beginning of each list indicated by @f, @m, or @u.
@L| formatting string the format for each list entry consisting of the appropriate name and the accompanying list of scrap numbers.
@L} formatting string this string is printed at the end of each list indicated by @f, @m, or @u .
@lt formatting string this string contains the special character "<" in the format it should be displayed inside a scrap. It is also used to mark the beginning of a macro call.
@gt formatting string this contains the special character ">" in the format it should be displayed inside a scrap. It is also used to end a macro call.

4.1 The default settings for HTML

 We now list the default settings for the formatting strings as they are used by WebWeb. Note, that the words scrapnumber and scrapname and also the string list of numbers are meta strings which will be replaced by the appropriate values computed by WebWeb.
empty means that this string is empty by default.

@S{ <P CLASS="clsScrpStrt"> </P>
@S} <P CLASS="clsScrpEnd"> </P>
@H| <H4 CLASS="clsScrpHd"><A CLASS="clsScrpHdA" NAME="scrap scrapnumber">&laquo; scrapname &raquo; scrapnumber</A></H4>
@B{ empty
@B} </PRE>
@M{ &lt;<CODE CLASS="clsMcrCll">
@M| :</CODE>list of numbers
@M} &gt;
@D| <P CLASS="clsScrpDf">Also defined in: list of numbers </P>
@R| <P CLASS="clsScrpRf">Scrap referenced in: list of numbers </P>
@N| <A CLASS="clsScrpNumHrf" HREF="#scrap scrapnumber">scrapnumber</A>
@K| ,
@L{ <TABLE CLASS="clsTbl">
@L| <TR><TD CLASS="clsTblNm">scrapname : <TD CLASS="clsTblEntry">list of numbers
@L} </TABLE>
@lt &lt;
@gt &gt;


4.2 The default settings for LaTeX


@S{ {\vspace*{-1ex} \begin{flushleft}
@S} \end{flushleft} }
@H| {\bf $\langle$ scrapname scrapnumber $\rangle$ }
@B{ \vspace*{-2ex} \begin{quote}
@B} \end{quote} \vspace*{-6ex} $\diamond$ \newline
@M{ @ $\langle$ {\bf
@M| } : {\small list of numbers}
@M} $\rangle$ \verb@
@D| {\small \it Also defined in: list of numbers }\\
@R| {\small \it Scrap referenced in: list of numbers }\\
@N| scrapnumber
@K| ,
@L{ \begin{description}
@L| \item[scrapname: ] list of numbers \vspace{-2ex}
@L} \vspace*{2ex} \end{description}
@lt $\langle$
@gt $\rangle$






5 Differences between nuweb and WebWeb