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 L^ATEX commands though, as we know by now, it will be normally processed by pdweave and not by L^ATEX. The general form of the command is:

\sourceinput[options]{ filename}{ tagname}

Like in L^ATEX, 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.
useLongtable DEPRECATED	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.

Footnotes

... on⁵

For more information on choosing the right base font see section B.7 on page