1%\tracingall 2\documentclass[twoside]{linfoem} 3\c\usepackage[dvipdfm]{hyperref} 4\usepackage{epsf,refman2,tpage} 5\usepackage{../fileinclude} 6\c\documentstyle[epsf,refman2,twoside,tpage,addtensf,latexinfo]{article} 7\c If you have latex2e, then you don't have a complete simulation of LaTeX. 8\c The following detects that and tries to fix it. 9\c Unfortunately, this needs to be done BEFORE loading latexinfo. And since 10\c rawfonts isn't part of LaTeX (only latex2e), we can't use it in the 11\c document style command. 12\c \ifx\tensf\relax\usepackage[only,tensf]{rawfonts}\fi 13\c \documentstyle[epsf,../refman2,twoside,../funclist,tpage,../tools,../../tex/latexinfo]{article} 14\c -*-latexinfo-*- 15\c \anltmtrue 16\anltmfalse 17\c\pagestyle{empty} 18\c 19\c We really need a ``usage'' macro for the routines and macros 20\def\usage#1{} 21\c 22\c the definition of \file should be changed so that it adds an 23\c \penalty 1000\hskip 0pt +1fil \penalty -10000 24\c before the actual text (allowing a line that the file name would stick 25\c out of to instead be raggedright, a not perfect but better approach). 26\c 27\c 28\c See /home/beumer/GROPP/TMS/doctext.tex 29\c 30\let\DOESupport\DefaultSupport 31 32\c\def\tie{\nobreak\ \nobreak} 33\def\bw{{\tt\char`\\}} 34% Give the URL for a document (WWW version makes URL active) 35\def\URL#1{#1} 36 37\textheight=9in 38\textwidth=6.5in 39\oddsidemargin=0in 40\evensidemargin=0in 41\topmargin=-0.5in 42\hsize=\textwidth 43 44\begin{document} 45\c latex2e's compatibility mode wants this 46\c \makeatletter 47\c \global\let \@nodocument \relax 48\c \makeatother 49\c 50\newindex{fn} 51 52\begin{ifinfo} 53\c %**start of header 54\title{Users Manual for doctext:\\ 55Producing Documentation from Source Code} 56\author{William Gropp\\ 57Mathematics and Computer Science Division\\ 58Argonne National Laboratory} 59 60\date{\today} 61 62\c %**end of header 63 64\maketitle 65\end{ifinfo} 66 67\begin{iftex} 68\ANLTMTitle{Users Manual for doctext:\\ 69Producing Documentation from Source Code}{\em William Gropp\\ 70Mathematics and Computer Science Division}{206-Rev 3}{February 1999} 71\c {March 1995} 72\c {Rev 1 April 1997} 73 74\end{iftex} 75 76\clearpage 77 78\c \vskip 0pt plus 1filll 79\c Copyright \copyright{} 1995 Argonne National Laboratory 80\c 81\c \clearpage 82\c \pagenumbering{roman} 83\c \setcounter{page}{3} 84\c \pagestyle{plain} 85\c \tableofcontents 86\c \clearpage 87 88\pagenumbering{arabic} 89\pagestyle{plain} 90\thispagestyle{plain} 91 92\setfilename{../doctext.info} 93 94\node Top, Introduction, (dir), (dir) 95\c nodename, next, previous, up 96 97\c --------------------------------------------------------------------------- 98\begin{iftex} 99 100\pagenumbering{arabic} 101\setcounter{page}{1} 102\c \thispagestyle{empty} 103 104\begin{center} 105{\large\bf Users Manual for doctext:\\ 106Producing Documentation from Source Code\\} 107\vspace{.2in} 108by \\ 109\vspace{.2in} 110{\it 111William Gropp\\ 112} 113\end{center} 114 115\vspace{.2in} 116 117\addcontentsline{toc}{section}{Abstract} 118\begin{abstract} 119\noindent 120One of the major problems that software library writers face, particularly in 121a research environment, is the generation of documentation. 122Producing good, 123professional-quality documentation is tedious and time consuming. 124Often, no documentation is 125produced. For many users, however, much of the need for 126documentation may be satisfied by a brief description of the purpose and use 127of the routines and their arguments. Even for more complete, 128hand-generated documentation, 129this information provides a convenient starting point. We 130describe here a tool that may be used to generate documentation about programs 131written in the C language. It uses a structured comment convention that 132preserves the original C source code and does not require any additional 133files. The markup language is designed to be an almost invisible 134structured comment in the C source code, retaining readability in the 135original source. 136Documentation in a form suitable for the Unix man program (nroff), LaTeX, and 137the World Wide Web can be produced. 138The output format is controlled by easily modified tables, permitting 139customization of the output. 140Support for other languages is also provided, though with fewer features. 141\end{abstract} 142\end{iftex} 143 144 145\clearpage 146\c --------------------------------------------------------------------------- 147 148 149 150\c --------------------------------------------------------------------------- 151 152\node Introduction,doctext,Top,Top 153\section{Introduction} 154\label{chap:intro} 155\c Generating good documentation is a task that requires skill and hard 156\c work. 157The tools described in this report are intended to help you create 158simple man-page-style documentation quickly and easily. 159Specifically, the program \code{doctext} takes C programs 160and generates nroff (Unix man page format), LaTeX \cite{Lamport86}, or HTML 161files. All of the 162information is 163embedded in structured comments, allowing the documentation to be maintained 164along with the code. 165The design of the special markup language commands emphasizes 166readability of the original source code (the structured comment). This 167approach differs from approaches such as \code{web} \cite{web}, where 168special processing must be applied to produce a readable version of the 169source code. Such approaches can do much more than \code{doctext} but 170are really aimed at documenting the source code of a program rather than 171the use of the program. Further, because those approaches are so 172intrusive, users tend to avoid them. The approach in \code{doctext} provides 173an effective comprimise between usability and functionality. 174 175The \code{doctext} approach has been independently adopted by Java; the 176\code{javadoc} 177program provides HTML documentation from Java source. \code{doctext} predates 178Java and provides more formats (LaTeX and nroff as well as HTML) and 179formatting commands. 180 181\node The doctext Program,,,Top 182\section{The doctext Program} 183The \code{doctext} program reads C programs and 184generates documentation. Command-line options provide control over the 185output. Fine tuning of the output can be accomplished by changing files that 186define the output form for each of the commands that \code{doctext} recognizes. 187 188\node Getting Started,,,The doctext Program 189\subsection{Getting Started} 190Using \code{doctext} is easy. For example, the command 191\begin{example} 192doctext foo.c 193\end{example} 194will generate Unix man pages for all of the commented routines in the file 195\file{foo.c}. 196But before this will do you any good, you will need to add some structured 197comments to your file. 198 199\node Structure Comments,,,The doctext Program 200\subsection{Structured Comments} 201The \code{doctext} program searches for C comments of the form \code{/*}{\em c} \code{...} 202{\em c}\code{*/}, where {\em c} is a single character indicating the type of 203documentation. The available types are \code{@} for 204routines, \code{M} for macros, \code{E} for enum definitions, 205\code{S} for struct definitions, and \code{D} for 206other miscellaneous documentation (such as introductions or descriptions of 207programs rather than routines). 208In all cases, the structured comment has this form: 209\begin{example} 210/*@ 211 name - short description 212 213 heading 1: 214 215 heading 2: 216 217 ... 218@*/ 219\end{example} 220The structured comment for a routine must immediately precede the declaration 221of the routine (either K\&R or ANSI-style prototypes). 222Figure \ref{fig:example} shows the structured comment and the routine being 223documented. 224 225\begin{figure} 226\begin{example} 227/*@ 228 Swap - Swaps two pointers 229 230 Parameters: 231. ptr1,ptr2 - Pointers to swap 232@*/ 233void Swap( ptr1, ptr2 ) 234void **ptr1, **ptr2; 235\{ 236void *tmp = *ptr1; 237*ptr1 = *ptr2; 238*ptr2 = tmp; 239\} 240\end{example} 241\caption{C code for a Swap routine with \protect\code{doctext}-style 242structured comment}\label{fig:example} 243\end{figure} 244 245The man (nroff-style) output of this is shown in Figure \ref{fig:swap-man}, 246and the LaTeX output is shown in Figure \ref{fig:swap-latex}. 247 248\begin{figure} 249\fileinclude{swap.man} 250\c \centerline{\epsfysize=3in\epsfbox{swap2.eps}} 251\caption{Unix-style man page for the Swap routine}\label{fig:swap-man} 252\end{figure} 253 254\begin{figure} 255\begin{minipage}{\hsize} 256\input Swap.tex 257\end{minipage} 258\caption{LaTeX page for the Swap routine}\label{fig:swap-latex} 259\end{figure} 260 261The body of the structured comment follows simple rules. Any line that ends 262in a colon (\code{:}) generates a section title with the line as the title. 263In the example of \code{Swap}, the line \code{Parameters:} generates a section 264in the man page with title {\bf Parameters}. To end a line in a colon without 265generating a section heading, precede it with a backslash: 266\begin{example} 267 This is not a new section\bw: 268\end{example} 269 270The first column within a structured comment has a special meaning. A period 271followed by a space indicates that the line 272begins the description of an argument (ended by another argument or a blank 273line). This line has a special format. The first space-separated token is 274taken as the argument. The next character should be a dash (\code{-}). After 275the dash comes the text. The \code{Swap} example shows this for the arguments 276\code{ptr1,ptr2}. 277Other commands are described below in Section \ref{sec-formatting}. 278 279\node C Routines,,,The doctext Program 280\subsection{C Routines} 281C routines are indicated by the structured comment \code{/*@ ... @*/}. 282The \code{doctext} program provides a synopsis automatically by reading the declarations 283of the routine. 284Arguments are specified as described in \xref{Describing Arguments}. 285 286\node C Macros,,,The doctext Program 287\subsection{C Macros} 288C macros are indicated by the structured comment \code{/*M ... M*/}. 289Unlike the case of C routines, macro definitions do not provide any 290information on the types of the arguments. 291Thus, the body of a structured comment 292for a C macro 293should include a {\em synopsis} section, containing a declaration of the 294macro as if it were a C routine. For example, if the \code{Swap} example were 295implemented as a macro, the structured comment for it would look like 296\begin{example} 297/*M 298 Swap - Swaps two pointers 299 300 Parameters: 301. ptr1,ptr2 - Pointers to swap 302 303 Synopsis: 304 void Swap( ptr1, ptr2 ) 305 void **ptr1, **ptr2; 306M*/ 307\end{example} 308It is important that the word {\em Synopsis} be used; \code{doctext} and 309related programs (\code{bfort} and \code{doc2lt}) use this name to find the 310C-like declaration for the macro. 311 312\subsection{Enums and Structs} 313A C enum may be documented using the \code{E} command: 314\begin{example} 315/*E 316 Read_t - Enum for read modes 317E*/ 318typedef enum { Read, ReadBack } Read_t; 319\end{example} 320 321A C struct definition uses the \code{S} command: 322\begin{example} 323/*S 324 File_t - Structure defining a file type 325S*/ 326typedef struct { 327 Read_t mode; 328 int fd; 329 int (*readfn)( int, void *, int ); 330 int (*writefn)( int, void *, int ); 331 } File_t; 332\end{example} 333 334\node Miscellaneous Documentation,,,The doctext Program 335\subsection{Miscellaneous Documentation} 336In addition to routines, a library will often have a few additional manual 337pages, for example, an overview of the members of the library or instructions 338on installing or debugging the library. In order to allow the same tools to 339be used 340for all of the documentation, a comment of the form \code{/*D ... D*/} may 341appear anywhere and will generate a manual page. 342 343\node Indicating Special Limitations,,,The doctext Program 344\subsection{Indicating Special Limitations} 345Two modifiers to the structured comments indicate special 346behavior of the function. The modifiers must come after the character that 347indicates a routine, macro, or documentation. 348The modifier \code{C} indicates that this routine is available only in C (and 349not from Fortran). For example, the \code{Swap} program cannot be used in 350Fortran, so its structured comment should be 351\begin{example} 352/*@C 353 .... 354@*/ 355\end{example} 356 357The modifier \code{X} indicates that the routine requires the 358X11 Window System. This is intended primarily for the program \code{bfort} 359\cite{bfort}, which is used to generate Fortran interfaces for systems that do 360not have X11. 361 362The modifiers \code{C} and \code{X} may be used together and may be specified 363in either order (i.e., \code{CX} or \code{XC}). 364 365\node Indicateing Include Files,,,The doctext Program 366\subsection{Indicating Include Files} 367It is often very important to indicate what include files need to be used with 368a particular routine. This may be accomplished with a special structured 369comment of the form \code{/*I}{\em include-file-name}\code{I*/}. 370For example, to indicate that the routine requires that \file{<sys/time.h>} 371has been included, use 372\begin{example} 373#include <sys/time.h> /*I <sys/time.h> I*/ 374\end{example} 375in the C file. 376A user-include can be specified as 377\begin{example} 378#include "system/nreg.h" /*I "system/nreg.h" I*/ 379\end{example} 380This approach of putting the structured include comment on the same line as 381the include of the file ensures that if the source file is changed by removing 382the include, the documentation will reflect that change. 383Includes are added to the synopsis of all routines in the file that 384contains the include comment. 385 386\node Special Formatting,,,Top 387\section{Special Formatting}\label{sec-formatting} 388The structured comment format for \code{doctext} was designed to have a small 389impact on the appearance of the C source code. As such, it provides minimal 390formatting for the generated manual pages. 391Three important cases 392are provided: describing 393arguments, verbatim output, and common blocks of text. 394In addition, there are some additional formatting controls for things like 395emphasis (italics text) and fixed-width fonts. 396This section describes all of these in more detail. 397 398\node Describing Arguments, , ,Special Formatting 399\subsection{Describing Arguments} 400Arguments to routines and command-line options for programs are described by 401using a plus (\code{+}), period (\code{.}), and minus (\code{-}) 402in the first column, followed by one or more spaces. 403The name of the argument or command line variable is next. 404Several arguments may be placed together, separated with spaces and/or commas. 405To include a hyphen (\code{-}) in the argument, 406prefix it with a backslash (\bw). 407Follow this with one or more spaces, then a dash (\code{-}), optional spaces, 408and finally the 409text of the description. The description may use multiple lines. 410The \code{+} should be used to start an argument list and \code{-} should be 411used to end the list. The period (\code{.}) should be used for all other 412arguments in the list. 413For example, 414\begin{example} 415+ a - Pointer to 416 the data item 417. i, j - Sizes of data item 418. str - Another argument value 419- \bw-arg value - Sample command-line argument 420\end{example} 421The \code{+} and \code{-} are optional but recommended. They permit better 422formatting of lists of arguments. 423 424\node Common Blocks of Text, , ,Special Formatting 425\subsection{Common Blocks of Text} 426In some cases, it is useful to repeat a body of text in many man pages. For 427example, there may be a common argument that has a lengthy description. A 428common block of text is defined with 429\begin{example} 430/*N name 431 text 432N*/ 433\end{example} 434The {\em name} may be any blank-delimited string. 435 436To insert this block of text into a man page, use the \code{.N} format command 437\begin{example} 438/*@ 439 ... 440 441.N name 442 443 ... 444@*/ 445\end{example} 446The definition must precede all uses. Once defined, the definition is 447remembered; if multiple files are processed and the first file contains a 448definition of a named block, all subsequently processed files may refer to 449that named block. 450This feature allows different replacement texts for different situations. For 451example, the replacement text for a man page should contain the entire 452text, whereas the replacement text for a manual (LaTeX) may reference a 453common section. 454 455For example, the MPICH implementation of MPI uses this to define all of the 456error conditions. A file \file{errnotes} contains lines like 457\begin{example} 458/*N Errors 459Errors: 460 461 ... text about MPI errors ... 462 463N*/ 464/*N MPI_SUCCESS 465. MPI_SUCCESS - No error; MPI routine completed successfully. 466N*/ 467/*N MPI_ERR_BUFFER 468. MPI_ERR_BUFFER - Invalid buffer pointer. Usually a null buffer where 469 one is not valid. 470N*/ 471\end{example} 472Each MPI man page ends with references to the name blocks for the errors that 473the particular MPI routine may return. \code{MPI_Send} has the 474following commands at the end of its structured comment: 475\begin{example} 476.N Errors 477.N MPI_SUCCESS 478.N MPI_ERR_COMM 479.N MPI_ERR_COUNT 480.N MPI_ERR_TYPE 481.N MPI_ERR_TAG 482.N MPI_ERR_RANK 483\end{example} 484 485 486\node Line Breaks, , ,Special Formatting 487\subsection{Line Breaks} 488A new line may be begun with the \code{.n } command at the beginning of a 489line. The rest of the line is read. For example, to provide a list of items, 490use 491\begin{example} 492.n This is the first item 493.n This is the second item 494.n This is the third item 495.n 496\end{example} 497Note that a final line containing only \code{.n} is used to ensure that 498the next line of text begins on a new line rather than at the end of the 499third line. 500 501\node Verbatim Blocks of Text, , ,Special Formatting 502\subsection{Verbatim Blocks of Text} 503To display a block of text in a fixed-width font, use the \code{.vb} 504command to begin the block and \code{.ve} command to end the block. 505These commands, like the other dot commands, must begin in the first 506column. For example, to display two lines of shell commands, use this 507text in the structured comment: 508\begin{example} 509.vb 510 cd . 511 echo "I'm here" 512.ve 513\end{example} 514 515\node Emphasis, , ,Special Formatting 516\subsection{Emphasis} 517To emphasize some text, include it between back quotes: \code{`this text 518is emphasized`}. Emphasized text may appear in italics ({\em this text 519is emphasized}) or in bold face ({\bf this text is emphasized}). 520(Whether italics or bold face is used depends on the implementation and the 521output format). 522This effect requires the use of the \code{-quotefmt} command-line option; if 523the option is not used, back quotes are intrepreted as a simple character. 524To get a single back-quote when \code{-quotefmt} is used, double the quote: 525\code{``}. 526 527\node Code and Filename Font, , ,Special Formatting 528\subsection{Code and Filename Font} 529To display some text in a font appropriate for code and filenames, 530include it between single forward quotes: \code{'this text is code'}. 531This will appear in a form such as {\tt this text is code}. 532This effect requires the use of the \code{-quotefmt} command-line option. 533To get a single quote when \code{-quotefmt} is used, double the quote: 534\code{''}. 535 536\node Pictures, , ,Special Formatting 537\subsection{Pictures} 538This section described a proposed feature; comments are welcome. 539 540In the HTML and LaTeX formats, pictures (Postscript files) can be 541included by using the \code{.p} command: 542\begin{example} 543 .p filename 544\end{example} 545The file must be a Postscript file. 546A caption for the picture can be included with the \code{.cb} and 547\code{.ce} command. This caption is not displayed in the Unix man-page 548document but does appear in the LaTeX and HTML versions. For example, 549\begin{example} 550 .p sample-out.ps 551 .cb 552 This image shows the output of the 'foo' command 553 Note particularly ... 554 .ce 555\end{example} 556(not yet implemented) 557 558\node Verbatim, , ,Special Formatting 559\subsection{Verbatim} 560A dollar (\code{$}) in the first column indicates a verbatim line. In most 561situations, this can be used for forcing a line break at the end of the line. 562An example is 563\begin{example} 564$ This is a test 565$ 566$ Here is a sample command line 567$ 568$ And the start of the description about 569 it. 570\end{example} 571This version of verbatim is deprecated and supported for backward 572compatibility. 573 574\node Keywords, , ,Special Formatting 575\subsection{Keywords} 576Keywords may be specified with the command \code{.k}{\em list of keywords}. 577For example, to indicate that keywords {\em test, example, help} belong to the 578current routine or item, use 579\begin{example} 580.k test, example, help 581\end{example} 582To improve the readability of the source, you may use \code{.keywords} instead 583of just \code{.k}. 584 585The command line option \code{-keyword filename} causes the keywords to be 586appended to the specified file; this can be used to produce a keyword list. 587 588\node Other Formatting Options, , ,Special Formatting 589\subsection{Other Formatting Options} 590The program \code{doctext} is designed so that it is easy to add additional 591formatting commands of the form \code{.}{\em command}. 592In fact, you can define your own formatting commands. This is done in two 593steps. First, you add formatting commands using a command definition file 594(See \xref{Customizing the Output Format}) and include those definitions with 595the \code{-defn filename} command-line argument. You can then invoke your 596new commands by using \code{.f<command name>} in the source file. For 597example, if the file \file{indent.def} contains 598\begin{example} 599 in \bw{}begin\{quotation\}%n 600 out \bw{}end\{quotation\}%n 601\end{example} 602you can use 603\begin{example} 604 .fin 605 This text will be within a LaTeX quotation environment 606 .fout 607\end{example} 608in the source file. 609 610Other commands beyond those described in this document may be 611added in the future, so you should not rely on any particular behavior of 612\code{.}{\em character}. For example, \code{.seealso} has been added to 613provide a common reference for related information. 614If you need some particular formatting 615option that you cannot achieve with the \code{.f} approach, please send the 616suggestion to \code{gropp@mcs.anl.gov}. 617 618\node Command Line Arguments,,,Top 619\section{Command Line Arguments} 620To use \code{doctext}, you need only to give it the name of the files 621to process: 622\begin{example} 623doctext *.[ch] 624\end{example} 625Command-line options to \code{doctext} allow you to change the details of 626how 627\code{doctext} generates output. 628 629A complete list of the command line options follows. Some of these will 630be used often (e.g., \code{-ext} and \code{-mpath}); others are 631needed only in special cases (e.g., \code{-outfile}). 632 633The choice of output format is selected with these switches: 634\begin{description} 635\item[-latex] 636Generate LaTeX output rather than man (nroff) format files. 637\item[-html] 638Generate HTML (WWW) output rather than man (nroff) format files. 639\end{description} 640If neither of these is used, the output is in man (nroff) format. 641 642The following options control some aspects of the appearance and content of the 643generated page, as well as the name of the output file. 644\begin{description} 645\item[-mpath path] 646Set the path where the man pages will be written. 647\item[-ext n] 648Set the extension (1-9,l, etc.). The default value is 3. This is the man page 649chapter and is used as the extension on the filename. For example, 650\code{doctext} creates the file \file{Swap.3} for the \code{Swap} routine. 651\item[-heading name] 652Name for the heading (middle of top line). The default value is \code{PETSc}. 653This is used only for Unix man-page (nroff) format. 654\item[-nolocation] 655Suppress the generation of a line that indicates the source file that 656contained the structured comment. 657\item[-quotefmt] 658Enable the use of single quotes and back quotes to use code and emphasis 659fonts. 660\item[-dosnl] 661End every line with return-newline instead of just newline. This makes that 662file easier to read on Windows systems, and is quite helpful for HTML output. 663\item[-defn filename]Load the output definitions in file \file{filename}, in 664 addition to the defaults. 665\item[-I filename] 666\code{filename} contains the public includes needed by these routines; it will 667automatically be added to the synopsis of the routines. The file should 668contain exactly the text to be added to the synopsis. For example, to specify 669that the include \code{<stdio.h>} be included, use a file with only the text 670\code{#include <stdio.h>} in it. 671\end{description} 672 673The following options control the generation of additional data about 674HTML-format 675output that may be used by other programs to automatically generate links to 676the files created by \code{doctext}. 677\begin{description} 678\item[-index filename] 679Generate an index file appropriate for \code{tohtml} \cite{tohtml} (for 680generating WWW files). 681This {\em appends} to any existing file; make sure that you don't add 682duplicate entries. 683\item[-indexdir dirname] 684Set the root directory for the index file entries. This allows you to 685specify an absolute URL for the generated files to be used in the generated 686index, for example, 687\begin{example} 688-index foo.cit -indexdir "http:/www.mcs.anl.gov/home/gropp/man" 689\end{example} 690\item[-mapref filename]Use file \file{filename} as a source of names that 691 should be automatically mapped to URLs. One source of a properly formatted 692 mapref file is the output from \code{doctext} in the file specified with the 693 \code{-index filename} command. 694\c \item[-jumpfile filename] 695\c Generate a jump file appropriate for emacs-19 and the command 696\c lookup-petsc-routine-from-text. 697\end{description} 698 699The following options control the output filenames and the list of files to process. 700\begin{description} 701\item[-outfile filename] 702Put the man pages in the indicated file. Normally, a separate file is 703created for each routine. This may be appropriate for HTML output. 704The output filename is normally made up of the name of the routine, followed 705by the extension (\code{-ext n}) for nroff, \code{.tex} for LaTeX, or 706\code{.html} for HTML files. 707\item[-keyword filename] 708Append the keywords (from \code{.k} commands) to the given file. If the 709filename is \file{-}, use standard output. 710\end{description} 711 712 713The following options control the input format of the file, allowing 714\code{doctext} to be used with documentation in source files for Fortran or 715shell scripts. 716\begin{description} 717\item[-skipprefix name]Set the characters to be skipped at the beginning of 718 each line. The default is the empty string. Use 719\begin{example} 720 -skipprefix C 721\end{example} 722for Fortran 77 programs. You can use \code{-skipprefix \#} for shell scripts 723and \code{-skipprefix \bw!} for Fortran 90 programs. 724 725For example, with \code{-skipprefix C}, a Fortran program can use the D (not 726@) mode: 727\begin{example} 728C/*D 729C fortranfoo - An example of using Fortran with doctext 730C 731C Input Parameters: 732C 733C+ foo - bar 734C. bar - stool 735C- stool - pidgeon 736CD*/ 737 function fortranfoo( foo, bar stool ) 738 integer foo, bar stool 739 end 740\end{example} 741 742This option is new and has not been extensively tested. 743 744\item[-ignore name]Skip over \code{name} when processing a function 745 definition. This is particularly useful when a special (non-standard) 746 keyword is needed to build a dynamic link library (DLL) (e.g., Microsoft 747 C/C++) or 748 to simplify the construction of export lists (IBM's AIX). For example, say 749 that \code{EXPORT} is used to indicate a routine that will be exported as 750 part of a DLL. The source code then looks like 751\begin{example} 752/*@ myroutine - a routine visible as part of a DLL 753 @*/ 754EXPORT void myroutine( int a ) 755\end{example} 756Using the command line option \code{-ignore EXPORT} will cause \code{doctext} 757to skip the \code{EXPORT} keyword; the synopsis will contain only 758\begin{example} 759 void myroutine( int a ) 760\end{example} 761 762\end{description} 763 764After the command-line arguments come the names of the files from which 765documents are to be extracted. 766 767\node Man Pages for Hypertext Documents,,,Top 768\section{Man Pages for Hypertext Documents} 769One of the most difficult tasks in creating extensive hypertext is generating 770the initial documents and providing an easy way to link to them. 771For the the hypertext to be useful, there must be an easy 772way to create links to the generated documents. This section describes how to 773do this. The information produced by \code{doctext} may be used by 774\code{tohtml} \cite{tohtml} to generate documents that have extensive 775cross-links to 776hypertext versions of their man pages. 777Special formatting options for HTML pages are also discussed. 778 779\node Generating Collections of Linked Web Pages,,,Man Pages for Hypertext Documents 780\subsection{Generating Collections of Linked Web Pages} 781To generate HTML man pages for a collection of source files in 782\file{/home/me/foo}, 783do the following: 784\begin{verbatim} 785cd 786mkdir www 787mkdir www/man3 788cd foo 789doctext -html -index ../foo.cit \ 790 -indexdir http://www.mcs.anl.gov/me/foo/www/man3 \ 791 -mpath ../www/man3 *.[ch] 792cd .. 793\end{verbatim} 794This puts the HTML files into the directory \file{www/man3} and the index (in 795the correct format for the \code{-mapman} option of \code{tohtml}) into the 796file 797\file{foo.cit}. 798The \code{-indexdir} option is used to specify the ultimate location for the 799files (in this case, the directory \code{me/foo/www/man3} at the Web site 800\code{www.mcs.anl.gov}). 801Once you are 802sure that the files are correct, you can move them into the Web area with 803\begin{example} 804cp -r www /mcs/www/home/me 805\end{example} 806(assuming that \file{/mcs/www} corresponds to \code{http://www.mcs.anl.gov} in 807the \code{-indexdir} argument). 808 809To generate an HTML listing of the routines, you can execute the following 810script, with, of course, the appropriate changes to the text: 811\begin{verbatim} 812#! /bin/sh 813echo '<TITLE>Web pages for My Routines</TITLE>' >> www/index.html 814echo '<H1>Web pages for My Routines</H1>' >> www/index.html 815echo '<H2>My Routines</H2>' >> www/index.html 816echo '<MENU>' >> www/index.html 817ls -1 www/man3 | \ 818 sed -e 's%^\(.*\).html$%<LI><A HREF="man3/\1.html">\1</A>%g' \ 819 >> www/index.html 820echo '</MENU>' >> www/index.html 821\end{verbatim} 822This example may be found in the file \file{mkhtml.sam} in the source 823directory for \code{doctext}. 824 825If you have only a few routines to document, you can dispense with the second 826directory level above (the \file{man3}). However, you might find it valuable 827to follow (at least loosely) the Unix man page format, with commands and 828installation instructions in \file{man1} and routines spread across 829\file{man2} through \file{man8}. 830 831\node Alternate Formatting for HTML,,,Man Pages for Hypertext Documents 832\subsection{Alternate Formatting for HTML} 833\label{sec:alternatehtml} 834The appearance of arguments can be improved in HTML by using an HTML table. 835The command line argument \code{-defn htmlargtbl.def} will cause a table to be 836used in HTML mode for argument lists that begin with \code{+} and end with 837\code{-}. 838 839You can also completely control the type of HTML that is generated. 840\code{doctext} uses definition files that define what HTML is produced for 841each \code{doctext} command. These files, for HTML, are \file{html.def} in 842the directories specified by \code{TEXTFILT_PATH} (for basic operations) and 843\code{DOCTEXT_PATH} (for doctext-specific operations). These are defined when 844\code{doctext} is built; the defaults are \file{/usr/local/share} and 845\file{/usr/local/share/doctext}. You can override any 846of these definitions by creating your own file and specifying it with the 847\code{-defn filename} argument. In addition, you can prepend or postpend your 848own commands to the predefined commands. For example, to add an index link to 849the bottom of every page, put the following definition in a file: 850\begin{example} 851+eop %n<BR><A HREF="http://www.mcs.anl.gov/myindex">Index</A> 852\end{example} 853This says to prepend (the \code{+} is before the end-of-page command 854\code{eop}) the HTML code given. The \code{%n} generates a newline. 855Placeing a \code{+} after the commands postpends the definition. 856 857\node Making a Reference Manual,,,Top 858\section{Making a Reference Manual} 859With the \code{-latex} option of \code{doctext}, it is easy to create a 860reference manual containing the manual pages produced by \code{doctext}. 861The style file \code{refman.sty} (in \file{share/refman.sty}) provides the 862necessary LaTeX definitions. Below is an example skeleton for a reference 863manual: 864 865\begin{verbatim} 866\documentstyle[refman]{article} 867 868... page size commands ... 869 870\begin{document} 871 872... title page commands ... 873 874\pagenumbering{roman} 875\tableofcontents 876\clearpage 877 878\pagenumbering{arabic} 879\pagestyle{headings} 880 881\section{Introduction} 882... regular text ... 883 884\section{My commands} 885\input ref/ref1 886 887... additional sections ... 888\end{document} 889\end{verbatim} 890 891To generate the LaTeX files for the individual man pages using 892\code{doctext}, you can use the following commands: 893\begin{example} 894doctext -latex -mpath ref/ref1 *.c 895\end{example} 896followed by 897\begin{example} 898cd ref 899ls ref1 | sort | sed 's/^/\bw input /g' > ref1.tex 900\end{example} 901 902If named replacement blocks of text (\code{.N name}) are used, it may be 903appropriate to use a different definition for the manual from that used 904for the man page. For example, if the file \file{common.txt} contains 905\begin{example} 906/*N defs 907 Definitions are described in Section 2. 908N*/ 909\end{example} 910then changing the \code{doctext} command to 911\begin{example} 912doctext -latex -mpath ref/ref1 common.txt *.c 913\end{example} 914will cause each \code{.N defs} command to include the text ``Definitions 915are described in Section 2.'' 916 917\node Making the man Pages Available,,,Top 918\section{Making the man Pages Available} 919In order to make the regular man pages available, a 920directory tree containing directories \file{man}, \file{man/man1}, etc. (for 921all of the man page extensions used) needs to be created. 922In addition, a ``whatis'' database should be built within the primary man 923directory so that \code{man -k topic} 924will find the command or routines with \code{topic} in their description. 925This is done with the program \file{/usr/etc/catman} or \file{makewhatis}. If 926either of these programs is not 927available, the ``whatis'' database cannot be created. 928The following C-shell code will create the database: 929\begin{example} 930unalias cd 931if (-e /usr/etc/catman) then 932 (cd man ; /usr/etc/catman -w -M . ) 933else if (-e `which makewhatis`) then 934 (cd man ; makewhatis -M `pwd`) 935endif 936\end{example} 937 938Some \code{catman} programs may behave erroneously; at least one system, 939instead of using the \code{.SH NAME} entry, looks for \code{.SH NAME ... 940.SH}. What this means is that if the first text after the routine's 941description is not a section title (i.e., a line ending with a colon), the 942\code{catman} program will generate an incorrect whatis database. 943 944It is easy to provide an X11 interface to the man pages by using \code{xman} 945and the \code{MANPATH} variable. Here is a simple shell script that provides 946access to the man pages in \file{/home/me/man}: 947 948\begin{example} 949#! /bin/sh 950MANPATH=/home/me/man 951export MANPATH 952xman -notopbox -helpfile /home/me/man/me.help "$@" & 953\end{example} 954 955In order to get \code{man} and \code{xman} to display the correct names for 956the various sections (corresponding to the directories \file{man/man1}, 957\file{man/man2}, etc.), a file \file{man/mandesc} is required. Here is the 958\file{man/mandesc} for the PETSc package: 959 960\begin{example} 961r(r)Introduction 9621(1)Sparse Matrix Routines 9632(2)Vector Routines 9643(3)Simplified Solvers 9654(4)Iterative Methods 9665(5)High Level Communications 9676(6)Low Level Communications 9687(7)System Calls 9698(8)Miscellaneous 9709(9)Domains and Grids 971b(b)BLAS 972x(x)X Window System Tools 973n(n)Nonlinear Solvers 974no default sections 975\end{example} 976 977Finally, \code{xman} displays a help page when it starts. To change the file, 978use the \code{-helpfile} argument and provide a simple text file (not a man) 979page. 980 981\node Customizing the Output Format,,,Top 982\section{Customizing the Output Format} 983The text formating commands that \code{doctext} uses for its output are 984controlled by several files. For each output format (nroff, html, and latex) 985there are two sets of definitions files. The first set are the ones common to 986all of the tools in the sowing package, and are in the directory 987\file{share}. The files are 988\begin{description} 989\item[html.def]HTML commands 990\item[latex.def]LaTeX commands 991\item[nroff.def]Nroff (man) commands 992\end{description} 993In addition, the directory \file{share/doctext} contains special 994versions of these same files. \code{doctext} uses the files in 995\file{share/doctext} by default (see the file 996\file{sowing/src/doctext/docpath.h}). You can override or add to these 997commands with the \code{-defn filename} argument. The environment variable 998\code{DOCTEXT_PATH} may be used to point to a different set of definition 999files. 1000 1001Small changes can be made by using the \code{-defn filename} switch to load a 1002file that redefines a few of the commands. The file \file{htmlargtbl.def}, 1003mentioned above for using the HTML table commands for arguments, is an 1004example. Similarly, the file \file{latexargtbl.def} can be used to place the 1005argument definitions in a LaTeX \code{tabular} environment. Using the 1006\code{-defn} argument to override a few definitions is usually preferable to 1007replacing all of the definitions. 1008 1009\node The Doctext Commands,,,Customizing the Output Format 1010\subsection{The Doctext Commands} 1011\code{Doctext} uses named commands for all of its output. For each of these 1012commands, there is a definition that tells \code{doctext} what to do 1013for each of these. For example, when \code{doctext} outputs a section 1014(from a line ending in a \code{:}), \code{doctext} uses the 1015\code{section} command. The default definition for this when 1016generating HTML is 1017\begin{example} 1018 section %n<H2>%1</H2>%n 1019\end{example} 1020This instructs \code{doctext} to output a newline if it isn't already 1021at the start of a line (the \code{%n}); followed by standard HTML for 1022a level 2 heading, followed by another newline. The \code{%1} in the 1023argument string stands for the first argument to the \code{section} 1024command. To change the output style, you need only replace the 1025command definitions. The next two sections detail the commands and 1026the command language. 1027 1028\node Commands,,,Customizing the Output Format 1029\subsection{Commands} 1030\label{sec:outputcommands} 1031\begin{description} 1032\item[blank]Generate a blank space. This is usually just a blank space. 1033\item[bof]Beginning of file command. This is called when a new file 1034is created. There is one argument: the name of the directory. 1035\item[bop]Beginning of page command. This is called when starting a 1036new manual page. 1037\item[definition]There is one argument, the one-line description of the 1038 routine. Used only by \code{doc2lt}. 1039\item[em]Begin emphasis (or italic) style text. See the command 1040syntax for the discussion of how font modes like this are exited. 1041\item[em_dash]Generate an em dash (---). 1042\item[end_par]Generate an end-of-paragraph. 1043\item[eof]End of file command. This is called just before 1044\code{doctext} closes a file. 1045\item[eop]End of page command. This is called at the end of a man 1046page. 1047\item[key]There is one argument, the name of the routine that a 1048man page is being generated for. Used only by \code{doc2lt} 1049\item[linebreak]Generate a forced line break. 1050\item[location]Show the location of the file the generated this man 1051page. The argument is the filename. 1052\item[mantitle]Generate the man page title. This takes four string 1053arguments. They are, in order 1054 \begin{description} 1055 \item[name]Name of the routine 1056 \item[level]Man page section (e.g., \code{3}) 1057 \item[date]Date of last change to file 1058 \item[heading]man section name (from the \code{-heading} argument 1059 to \code{doctext}). 1060 \end{description} 1061\item[picture]This command takes the name of a file as argument and 1062will be used in future versions of \code{doctext} to allow the 1063inclusion of graphics in man pages. 1064\item[postamble]Used only by \code{doc2lt} 1065\item[preamble]Used only by \code{doc2lt} 1066\item[rm]Change font style to roman. 1067\item[section]Generate a man page section header. There are two 1068arguments. The string argument is the name of the section; the 1069integer argument is the level of the section. The default section 1070level is two. 1071\item[synopsis]Generate the \code{Synopsis} section of the man page. 1072The argument is the synopsis text. Used only by \code{doc2lt}. 1073\item[tt]Change font style to fixed width. 1074\end{description} 1075In addition to the above commands, there are a number of commands that 1076come in pairs, with a start (\code{s_xxx}) and an end (\code{e_xxx}) 1077term. 1078\begin{description} 1079\item[s_arg]Begin an argument (\code{.} format command). 1080\item[s_defn]Begin the definition of an argument. 1081\item[s_arg_list]Begin a list of argument (the \code{+} format 1082command). This doesn't include the argument itself; that is begun 1083with the \code{s_arg_inlist} command. 1084\item[s_arg_inlist]Begin an argument within an argument list (started 1085with \code{s_arg_list}). 1086\item[s_defn_inlist]Begin the definition of an argument in an argument 1087list. 1088\item[s_caption]Begin the text for a caption. This is intended for 1089use with the \code{picture} command, and is not supported. 1090\item[s_doctext_verbatim]Begin the single-line verbatim mode (the 1091\code{$} command). 1092\item[s_synopsis]Begin the synopsis section. 1093\item[s_verbatim]Begin a multiline verbatim section (\code{.vb}). 1094\end{description} 1095 1096\node The Definition Command Language,,,Customizing the Output Format 1097\subsection{The Definition Command Language} 1098The command language for the definitions is very simple. Each line 1099has the form 1100\begin{example} 1101command-name replacement-text 1102\end{example} 1103The \code{command-name} is any of the names in 1104Section\tie\ref{sec:outputcommands}. 1105Comment lines may be included anywhere and start with \code{#}. 1106The \code{replacement-text} is almost literal text, except for 1107\code{%} escapes. These escapes are almost all single letters; for 1108example, \code{%n} and \code{%1}. The complete list of escapes 1109is 1110\begin{description} 1111\item[\code{%}]Output the \code{%} character 1112\item[1]Insert the first string argument 1113\item[2]Insert the second string argument 1114\item[3]Insert the third string argument 1115\item[4]Insert the fourth string argument 1116\item[i]Insert the first integer argument 1117\item[n]Insert a newline only if not at an newline 1118\item[u1]Insert the first string argument, but in uppercase. 1119Similarly for \code{u2} through \code{u4}. 1120\item[p]Insert end-of-paragraph string only if not at an 1121end-of-paragraph. 1122\item[f]Insert the end of font string. This string is defined by the 1123\code{%e=} command. 1124\item[N="..."]Replace newlines with the string given in quotes. The 1125string can be 32 characters or less. 1126\item[e="..."]Define the end of font string. The string can be 32 1127characters or less. 1128\item[m="..."]Define the output mode. This is a string that is 1129understood by the particular output format. For example, the LaTeX 1130output routines understand the mode \code{verbatim} and use that to 1131change how characters are output. 1132\item[a0="..."]Define the value of string register zero. The string may be up 1133 to 63 characters long. There are 10 registers, commands \code{a1} through 1134 \code{a9} access the other nine. The value of \code{a0} is set to the name 1135 of the function or macro by \code{doctext}, and normally should not be 1136 changed. 1137\item[r1]Insert the value of string register zero. Similarly for \code{r1} 1138 through \code{r9}. 1139\end{description} 1140To continue \code{replacement-text} to another line, end the line with 1141the \bw\ character. A single space at the end of a line may be 1142represented with \bw<blank>. 1143 1144Sometimes you will not want to replace a command; instead, you will 1145want to insert your replacement text either before or after the 1146standard text. You can do this by placing a \code{+} either before or 1147after the \code{command-name}. An example of this is in 1148Section\tie\ref{sec:alternatehtml}. 1149 1150\node Examples of Command Definition,,,Customizing the Output Format 1151\subsection{Examples of Command Definition} 1152This first example shows how to place the argument names and 1153definitions into a table when generating HTML output. This works only 1154with the argument list commands (start a list with \code{+} and end it 1155with \code{-}). Here are the definitions: 1156\begin{example} 1157# You can get this by specifying -defn htmlargtbl.def to doctext. 1158s_arg_list %n<TABLE BORDER=0> 1159s_arg_inlist %n<TR><TD WIDTH=20></TD><TD ALIGN=LEFT VALIGN=TOP><B> 1160e_arg_inlist </B></TD> 1161s_defn_inlist <TD VALIGN=TOP> 1162# The br is used to break the line in the event that the browser doesn't 1163# support tables. It is better than nothing. 1164e_defn_inlist <BR></TD></TR> 1165e_arg_list </TABLE>%n 1166\end{example} 1167This example uses only the \code{%n} escape. The definitions are 1168ordered as they would be used by \code{doctext}. 1169 1170This second example makes \code{tt} text one size larger when 1171generating HTML: 1172\begin{example} 1173tt %f<TT><FONT SIZE=+1>%e="</FONT></TT>" 1174\end{example} 1175The \code{%f} command is used to terminate any previous font style 1176command. The \code{%e} command defines how to terminate this font 1177style. 1178 1179\node Installing doctext,,,Top 1180\section{Installing doctext} 1181The \code{doctext} program is part of the a sowing package. 1182(An earlier version was part of the PETSc package of tools for 1183scientific computing.) 1184The program is available from 1185\URL{ftp://ftp.mcs.anl.gov/pub/sowing/sowing.tar.gz}. 1186Directories and files such as \file{refman.sty} 1187referred to in this manual are provided 1188in this implementation and may be found in the installation. 1189To build, 1190\begin{example} 1191 gunzip -c sowing.tar.gz | tar xf - 1192 cd sowing 1193 ./configure 1194 make 1195\end{example} 1196The \code{doctext} program is in the \file{sowing/src/doctext} directory. 1197 1198\code{doctext} requires a C++ compiler; most testing has been done with 1199\code{gcc}. 1200 1201Please send any comments to \code{gropp@mcs.anl.gov}. 1202 1203\c Currently on the list of requested features are: 1204\c preserve spaces in <PRE> in HTML (nearly impossible) 1205\c comment on erroneous use of ? 1206\c see http://www.hut.fi/~jkorpela/HTML3.2 for why LISTING not used 1207 1208\addcontentsline{toc}{section}{Acknowledgment} 1209\section*{Acknowledgment} 1210The author thanks Lois Curfman McInnes and Barry Smith for their careful 1211reading and vigorous use of the \code{doctext} manual and program and 1212Ewing Lusk for valuable suggestions about additional functionality. 1213 1214\begin{tex} 1215\addcontentsline{toc}{section}{References} 1216\bibliography{tools} 1217\bibliographystyle{plain} 1218\end{tex} 1219 1220\end{document} 1221