3 The \sourceinput command

Now that we have an idea of the general mechanism of the ProgDoc system, let's have a closer look on the \sourceinput command. Its syntax is similar to that of other LATEX commands though, as we know by now, it will be normally processed by pdweave and not by LATEX. The general form of the command is:

\sourceinput[options]{ filename}{ tagname}

Like in LATEX, arguments in { }-brackets are required whereas the ones in []-brackets are optional.

\sourceinput Arguments
filename Absolute or relative pathname of the source file. This may be internally preceded by a base path if the command \sourceinputbase{ filename} (see section 7) has been used.
tagname This is an arbitrary string which uniquely identifies a part of source code in the file specified by filename. A special tagname ``ALL'' is available, which includes a whole file.
(See section 8 for a detailed description of the comment format in the source files).
\sourceinput Options
label=name An ordinary LATEX label name which will be declared inside of the produced source listing and which can be used subsequently as parameter for the \ref command.
fontname=name The name of the base font used for highlighting the source listing. It is desirable here to specify a mono spaced font of which italic, bold and bold italic versions exist, since they are used to emphasize keywords, comments, string constants and so on5. (The default is the initial setting for \ttdefault, usually cmtt)
fontenc=encoding The encoding of the font chosen with the fontname option above. (The default is OT1.)
fontsize=pt The fontsize in point used for highlighting the listings. Since mono spaced fonts are usually some wider compared to proportional counterparts, a somewhat smaller size is recommended here. (The default is 8pt.)
linesep=length The line separation used for the source listings. (The default is 2.5ex.)
type=language This option controls the type of language assumed for the source file. The language argument will be handed over to the actual highlighter (see the option highlighter). Currently the default highlighter pdhighlight supports the values c, cpp, java, xml, scm, el or text. If not set, the default language is cpp. If type is set to text no syntax highlighting will be done at all.
Notice that this option also affects the way in which comments are recognized in the source files (see also the option comment and chapter 8 about the source file format 8 on page [*]).
comment='string' If you use one of the supported languages listed in the table on page [*], the tag names will be recognized automatically. If you however include parts of a file in an unsupported language, it may be necessary to set the string which denotes the beginning a comment in that language with this option.
tab=value The value of tab indicates the number of space characters used to replace a tab character ('\t'). The dafault is 8.
listing[=noUnderline] If the listing option is present, a heading will be printed above the listing, which contains at least the running number of the listing and the name of the file it was extracted from. By default, this heading will be underlined. You can change this behavior by using the optional noUnderline argument
linenr If the linenr option is set, the heading additionally will contain the line numbers of the code fragment in its source file.
The special tagname ``ALL'' always turns line numbers off.
center With this option set, the listing will appear centered, without it will be left justified.
underline If this option is set, pdhighlight will underline keywords instead of setting them in bold face. This is useful for fonts for which there exists no bold version (e.g. cmtt).
caption='captiontext' If this option is set, then the caption produced by the listing option will contain captiontext instead of the file name and possibly the line numbers. Notice that captiontext must be enclosed between apostrophe signs `` ' ''.
wrap=column With this option, you can instruct pdweave to wrap the lines of the source code you include at the specified column. pdweave uses a heuristics in order to find a ``good'' break position, so the column argument supplied with column is just a maximum value which will be not exceeded. Lines broken by pdweave, will be marked by an arrow (`` $\hookleftarrow$'') at the breaking point. This option is especially useful in two-column mode. For en example see the Listings 10 to 14 on page [*].
highlighter=program This option controls which program is used to highlight the source code. The default highlighter is pdhighlight. Currently the only additional highlighter is pdlsthighlight. Refer to section 5 for further information.
This is a compatibility option which forces the default highlighter pdhighlight to arrange the source listings in a longtable environment. Because of layout problems which resulted from the interaction of longtables with other float objects, the use of the longtable environment has been abandoned. This option is only for people who want to typeset a document in exactly the same way it was done with older versions of ProgDoc.

Apart from whitespace, the \sourceinput command must be the first to appear in a line and it must end in a line of its own. However the command itself can be split over up to five different lines. (This number can be adjusted by setting the variable DELTA in the script pdweave.awk.). It may also be necessary to quote some option arguments between apostrophe signs `` ' '', if they contain white space or special characters like angle or curly brackets.

Some of this options like fontname or fontsize can be redefined globally in the '.pd' file. See section 9 on page [*] for more information.


... on5
For more information on choosing the right base font see section B.7 on page [*]
Volker Simonis 2003-03-05