/
glscene
/
pasdoc
Обзор
Документация
Войти
/
glscene
/
pasdoc
Код
Запросы
0
Задачи
Вики
Пакеты
0
Релизы
0
Аналитика
Безопасность
dodi
docs/pasdoc.html
1 328 строк
62 KB
Carl Eric Codere
+ updates to output format documentation
20 апр 2004, 06:02
20 апр 2004, 06:02
05af11f
Код
Авторство
О чём код?
<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.01 Transitional//EN" "http://www.w3.org/TR/html4/loose.dtd"> <html > <head><title>Manual for pasdoc 0.8</title> <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1"> <meta name="generator" content="TeX4ht (http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html)"> <meta name="originator" content="TeX4ht (http://www.cis.ohio-state.edu/~gurari/TeX4ht/mn.html)"> <!-- html --> <meta name="src" content="pasdoc.tex"> <meta name="date" content="2004-04-19 22:02:00"> <link rel="stylesheet" type="text/css" href="pasdoc.css"> </head><body > <div class="maketitle"> <h2 class="titleHead">Manual for pasdoc 0.8</h2> <div class="author" ><span class="cmr-12">Marco Schmidt & Carl Eric Cod</span><span class="cmr-12">ère & Johannes Berg</span></div> <br> <div class="date" ><span class="cmr-12">April 19, 2004</span></div> </div> <!--l. 19--><p class="indent"> <h3 class="likesectionHead"><a id="x1-1000"></a>Contents</h3> <div class="tableofcontents"> <span class="sectionToc">1 <a href="#x1-20001" id="QQ2-1-2">Introduction</a></span> <br> <span class="sectionToc">2 <a href="#x1-30002" id="QQ2-1-3">Directives</a></span> <br> <span class="sectionToc">3 <a href="#x1-40003" id="QQ2-1-4">Adding descriptions</a></span> <br> <span class="sectionToc">4 <a href="#x1-50004" id="QQ2-1-5">Formatting your comments</a></span> <br> <span class="subsectionToc">4.1 <a href="#x1-60004.1" id="QQ2-1-6">@</a></span> <br> <span class="subsectionToc">4.2 <a href="#x1-70004.2" id="QQ2-1-7">abstract</a></span> <br> <span class="subsectionToc">4.3 <a href="#x1-80004.3" id="QQ2-1-8">author</a></span> <br> <span class="subsectionToc">4.4 <a href="#x1-90004.4" id="QQ2-1-9">classname, inherited, name</a></span> <br> <span class="subsectionToc">4.5 <a href="#x1-100004.5" id="QQ2-1-10">code</a></span> <br> <span class="subsectionToc">4.6 <a href="#x1-110004.6" id="QQ2-1-11">created</a></span> <br> <span class="subsectionToc">4.7 <a href="#x1-120004.7" id="QQ2-1-12">cvs</a></span> <br> <span class="subsectionToc">4.8 <a href="#x1-130004.8" id="QQ2-1-13">exclude</a></span> <br> <span class="subsectionToc">4.9 <a href="#x1-140004.9" id="QQ2-1-14">false</a></span> <br> <span class="subsectionToc">4.10 <a href="#x1-150004.10" id="QQ2-1-15">html</a></span> <br> <span class="subsectionToc">4.11 <a href="#x1-160004.11" id="QQ2-1-16">lastmod</a></span> <br> <span class="subsectionToc">4.12 <a href="#x1-170004.12" id="QQ2-1-17">link</a></span> <br> <span class="subsectionToc">4.13 <a href="#x1-180004.13" id="QQ2-1-18">longcode</a></span> <br> <span class="subsectionToc">4.14 <a href="#x1-190004.14" id="QQ2-1-19">nil</a></span> <br> <span class="subsectionToc">4.15 <a href="#x1-200004.15" id="QQ2-1-20">param</a></span> <br> <span class="subsectionToc">4.16 <a href="#x1-210004.16" id="QQ2-1-21">raises</a></span> <br> <span class="subsectionToc">4.17 <a href="#x1-220004.17" id="QQ2-1-22">return, returns</a></span> <br> <span class="subsectionToc">4.18 <a href="#x1-230004.18" id="QQ2-1-23">true</a></span> <br> <span class="sectionToc">5 <a href="#x1-240005" id="QQ2-1-24">Switches</a></span> <br> <span class="subsectionToc">5.1 <a href="#x1-250005.1" id="QQ2-1-25">Documentation file format</a></span> <br> <span class="subsubsectionToc">5.1.1 <a href="#x1-260005.1.1" id="QQ2-1-26">HTML</a></span> <br> <span class="subsubsectionToc">5.1.2 <a href="#x1-270005.1.2" id="QQ2-1-27">htmlhelp</a></span> <br> <span class="subsubsectionToc">5.1.3 <a href="#x1-280005.1.3" id="QQ2-1-28"><span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></a></span> <br> <span class="subsubsectionToc">5.1.4 <a href="#x1-290005.1.4" id="QQ2-1-29">LaTeX2rtf</a></span> <br> <span class="subsectionToc">5.2 <a href="#x1-300005.2" id="QQ2-1-30">Format-specific switches</a></span> <br> <span class="subsubsectionToc">5.2.1 <a href="#x1-310005.2.1" id="QQ2-1-31">No generator information</a></span> <br> <span class="subsubsectionToc">5.2.2 <a href="#x1-320005.2.2" id="QQ2-1-32">Specify name of document</a></span> <br> <span class="subsubsectionToc">5.2.3 <a href="#x1-330005.2.3" id="QQ2-1-33">Specify footers and headers to use</a></span> <br> <span class="subsectionToc">5.3 <a href="#x1-340005.3" id="QQ2-1-34">Comment Marker switches</a></span> <br> <span class="subsectionToc">5.4 <a href="#x1-350005.4" id="QQ2-1-35">Output language switches</a></span> <br> <span class="subsectionToc">5.5 <a href="#x1-360005.5" id="QQ2-1-36">Other switches</a></span> <br> <span class="subsubsectionToc">5.5.1 <a href="#x1-370005.5.1" id="QQ2-1-37">Include / Exclude class Members by visiblity</a></span> <br> <span class="subsubsectionToc">5.5.2 <a href="#x1-380005.5.2" id="QQ2-1-38">Output directory</a></span> <br> <span class="subsubsectionToc">5.5.3 <a href="#x1-390005.5.3" id="QQ2-1-39">Read file names from file</a></span> <br> <span class="subsubsectionToc">5.5.4 <a href="#x1-400005.5.4" id="QQ2-1-40">Change verbosity level</a></span> <br> <span class="subsubsectionToc">5.5.5 <a href="#x1-410005.5.5" id="QQ2-1-41">Show help</a></span> <br> <span class="subsubsectionToc">5.5.6 <a href="#x1-420005.5.6" id="QQ2-1-42">Specify a directive</a></span> <br> <span class="subsubsectionToc">5.5.7 <a href="#x1-430005.5.7" id="QQ2-1-43">Specify an include file path</a></span> <br> <span class="subsubsectionToc">5.5.8 <a href="#x1-440005.5.8" id="QQ2-1-44">Specify directive file</a></span> <br> <span class="subsubsectionToc">5.5.9 <a href="#x1-450005.5.9" id="QQ2-1-45">Set title of document</a></span> <br> <span class="subsubsectionToc">5.5.10 <a href="#x1-460005.5.10" id="QQ2-1-46">Include uses list</a></span> <br> <span class="subsubsectionToc">5.5.11 <a href="#x1-470005.5.11" id="QQ2-1-47">Full link output</a></span> <br> <span class="subsubsectionToc">5.5.12 <a href="#x1-480005.5.12" id="QQ2-1-48">Non documented switches</a></span> <br> <span class="sectionToc">6 <a href="#x1-490006" id="QQ2-1-49">Known problems</a></span> <br> <span class="subsectionToc">6.1 <a href="#x1-500006.1" id="QQ2-1-50">Documentation of program files</a></span> <br> <span class="subsectionToc">6.2 <a href="#x1-510006.2" id="QQ2-1-51">Records</a></span> <br> <span class="subsectionToc">6.3 <a href="#x1-520006.3" id="QQ2-1-52">Non-unique identifiers</a></span> <br> <span class="sectionToc">7 <a href="#x1-530007" id="QQ2-1-53">Adding support for another output format</a></span> <br> <span class="sectionToc">8 <a href="#x1-540008" id="QQ2-1-54">Credits</a></span> </div> <!--l. 23--><p class="indent"> <h3 class="sectionHead"><span class="titlemark">1 </span> <a id="x1-20001"></a>Introduction</h3> <!--l. 27--><p class="noindent">Pasdoc creates documentation for Pascal unit files. <!--l. 29--><p class="indent"> Descriptions for variables, constants, types (called ’items’ from now on) are taken from comments stored in the interface sections of unit source code files, each comment must be placed directly before the item’s declaration. <!--l. 33--><p class="indent"> This way, you as a programmer can easily generate reference manuals of your libraries without having to deal with the details of document formats like HTML or <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>. <!--l. 37--><p class="indent"> Moreover, you can edit the source code and its descriptions in one place, no need to add or modify explanations in other files. The rest is done automatically, you should write a script / batch file that does the actual call to pasdoc... Download the latest version from <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> http://pasdoc.sourceforge.net. </div> </td></tr></table> <!--l. 44--><p class="nopar"> For an example of source code that can be used with pasdoc, try the pasdoc sources themselves - type <span class="cmtt-10x-x-109">pasdoc[.exe] --format html *.pas </span>to generate HTML documentation. <!--l. 49--><p class="indent"> You can compile pasdoc with Free Pascal (version 1.0 or higher), as well as with Delphi and Kylix. <!--l. 52--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">2 </span> <a id="x1-30002"></a>Directives</h3> <!--l. 54--><p class="noindent">As you may know, Pascal allows for <span class="cmti-10x-x-109">directives </span>in the source code. These are comments that contain commands for the compiler introduced by the dollar sign. <!--l. 58--><p class="indent"> To distinguish different compilers, libraries or development stages, <span class="cmti-10x-x-109">conditional</span> <span class="cmti-10x-x-109">directives </span>make it possible to make the compiler ignore part of the file. An example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> unit SampleUnit; <br /> <br /> {$ifdef WIN32} <br /> uses Windows, WinProcs; <br /> procedure WindowMove(H: TWindowHandle; DX, DY: Integer); <br /> procedure WindowPrintText(H: TWindowHandle; X, Y: Integer; S: String); <br /> {$else} <br /> procedure ClearConsole; <br /> procedure PrintText(S: String); <br /> {$endif} <br /> <br /> {$define DEBUG} <br /> {$undef OPTIMIZE} </div> </td></tr></table> <!--l. 77--><p class="nopar"> <!--l. 79--><p class="indent"> The <span class="cmtt-10x-x-109">ifdef </span>part checks if a conditional directive called <span class="cmtt-10x-x-109">WIN32 </span>is currently defined (that would be the case for Delphi or FPC/Win32). If this is true, all code until <span class="cmtt-10x-x-109">else </span>or <span class="cmtt-10x-x-109">endif </span>are compiled, everything between <span class="cmtt-10x-x-109">else </span>and <span class="cmtt-10x-x-109">endif </span>is ignored. The contrary would apply if the directive is not defined, e.g. under FPC/DOS or Borland Pascal. These statements can also be nested. Using <span class="cmtt-10x-x-109">define</span> and <span class="cmtt-10x-x-109">undef</span>, a programmer can add and delete directives, in the above example DEBUG and OPTIMIZE. <!--l. 89--><p class="indent"> As pasdoc loads Pascal files in a similar way a compiler does, it must be able to regard conditional directives. All define and undef parts are evaluated by pasdoc, modifying an internal list of directives as source code is parsed. <!--l. 93--><p class="indent"> Different from a real compiler, pasdoc starts with an empty list of conditional directives. To get back to the above example, if you want to write documentation for the <span class="cmtt-10x-x-109">WIN32 </span>code part, you must explicitly tell pasdoc that you want this directive defined. <!--l. 98--><p class="indent"> You can do so using the <span class="cmti-10x-x-109">Specify directive </span>or <span class="cmti-10x-x-109">Add directives from file </span>switch (see sections <a href="#x1-420005.5.6">5.5.6<!--tex4ht:ref: specifydirective --></a> and <a href="#x1-440005.5.8">5.5.8<!--tex4ht:ref: specifydirectives --></a>). <!--l. 101--><p class="indent"> Next to those directives already presented, pasdoc also supports include files: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> type TInteger = Integer; <br /> <br />{$I numbers.inc} <br /> <br />const MAX_FILES = 12; </div> </td></tr></table> <!--l. 110--><p class="nopar"> <!--l. 112--><p class="indent"> In the above code, pasdoc would parse <span class="cmtt-10x-x-109">TInteger</span>, get the include directive and start parsing the include file <span class="cmtt-10x-x-109">numbers.inc</span>. This file could contain other directives, types or whatever. It is treated as it would be treated by any Pascal compiler. <!--l. 117--><p class="indent"> Pascal compilers also know <span class="cmti-10x-x-109">switch directives</span>. These are boolean options, either on or off. They can be checked similar to conditional directives with the <span class="cmtt-10x-x-109">$ifopt </span>directive. Pasdoc does not yet fully support these, but at least does not give up when it encounters one. <!--l. 124--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">3 </span> <a id="x1-40003"></a>Adding descriptions</h3> <!--l. 126--><p class="noindent">You can provide documentation for <ul class="itemize1"> <li class="itemize">types (including enumerations), </li> <li class="itemize">variables, </li> <li class="itemize">constants, </li> <li class="itemize">classes, interfances, objects, </li> <li class="itemize">procedures, functions and </li> <li class="itemize">units.</li></ul> <!--l. 137--><p class="indent"> Providing a description for the different items is fairly easy. You simply need to provide a comment containing the description before the name of the item itself. <!--l. 141--><p class="indent"> For units, the comment declaration must be done before the <span class="cmtt-10x-x-109">unit </span>keyword. Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> type <br /> { This record type stores all information on a customer, including <br /> name, age and gender. } <br /> TCustomer = record <br /> Name: String; <br /> Age: Byte; <br /> Gender: Boolean; <br /> end; <br /> <br />{ Initializes a TCustomer record with the given parameters. } <br />procedure InitCustomer(Name: String; Age: Byte; <br /> Gender: Boolean; var Customer: TCustomer); </div> </td></tr></table> <!--l. 156--><p class="nopar"> <!--l. 158--><p class="indent"> It is possible to specify that items will only be documented when certain comment markers are present at the start of the comment. Please refer to <a href="#x1-340005.3">5.3<!--tex4ht:ref: specifymarkers --></a> for further information. Furthermore, undocumented items may or may not appear in the final document, depending on the output format. <!--l. 164--><p class="indent"> An interesting feature of pasdoc is its ability to link items from within comments. If you are currently writing about an array of integers <span class="cmtt-10x-x-109">TIntArray</span> you’ve declared as a type, you might mention that the number of values it can store is specified in the constant <span class="cmtt-10x-x-109">MAX</span><span class="cmtt-10x-x-109">_INTS</span>. You’ve probably already documented this constant when you declared it earlier in the same or another unit. Now, if you write <span class="cmtt-10x-x-109">@link(MAX</span><span class="cmtt-10x-x-109">_INTS) </span>instead of simply <span class="cmtt-10x-x-109">MAX</span><span class="cmtt-10x-x-109">_INTS</span>, pasdoc knows that you are referring to another item it has found or will find in the list of units you gave to it. After all input files have been parsed, pasdoc will start substituting all occurrences of <span class="cmtt-10x-x-109">@link(something)</span> with ”real” links. Depending on the type of output, these links could be hyperlinks (in HTML) or page references (in <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>). If the current output format is HTML, the description of <span class="cmtt-10x-x-109">TIntArray </span>would contain a link to <span class="cmtt-10x-x-109">MAX</span><span class="cmtt-10x-x-109">_INTS</span>. Viewing <span class="cmtt-10x-x-109">TIntArray</span>’s description in your favourite web browser you’d now be able to click on <span class="cmtt-10x-x-109">MAX</span><span class="cmtt-10x-x-109">_INTS </span>and the browser would jump to the definition of <span class="cmtt-10x-x-109">MAX</span><span class="cmtt-10x-x-109">_INTS</span>, where you’d find more information on it. <!--l. 183--><p class="indent"> If pasdoc cannot resolve a link (for whatever reasons), it will issue a warning to standard output and will write the content of <span class="cmtt-10x-x-109">@link() </span>to the documentation file, not as a link, but in a special font. <!--l. 187--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">4 </span> <a id="x1-50004"></a>Formatting your comments</h3> <!--l. 189--><p class="noindent">All comments recognize special directives that are used for different purposes. Each of these special directives starts with the at character <span class="cmtt-10x-x-109">@</span>, followed by and identifier and optinally followed by text between parentheses. <!--l. 194--><p class="indent"> As an example, lets take the well-known <span class="cmtt-10x-x-109">DOS </span>unit. Its top part could look like this: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> { <br />@abstract(provides access to file and directory operations) <br />@author(John Doe <doe@john-doe.com>) <br />@created(July 12, 1997) <br />@lastmod(June 20, 1999) <br />The DOS unit provides functionality to get information on files and <br />directories and to modify some of this information. <br />This includes disk space (e.g. @link(DiskFree)), access rights, file <br />and directory lists, changing the current directory, deleting files <br />and directories and creating directories. <br />Some of the functions are not available on all operating systems. <br />} <br />unit DOS; </div> </td></tr></table> <!--l. 210--><p class="nopar"> <!--l. 212--><p class="indent"> Pasdoc would read this comment and store it with the unit information. After all Pascal source code files you gave to pasdoc have been read, pasdoc will try to process all tags, i.e., all words introduced by a <span class="cmtt-10x-x-109">@ </span>character. <!--l. 217--><p class="indent"> If you want to use the character <span class="cmtt-10x-x-109">@ </span>itself, you must write it twice so that pasdoc knows you don’t want to specify a tag. <!--l. 220--><p class="indent"> Note in the example above that the character does not need this special treatment within the parentheses, as shown in the author tag at the example of the email address. <!--l. 224--><p class="indent"> Following is a list of all tags that you may use in pasdoc. A tag like <span class="cmtt-10x-x-109">@link</span> must always be followed by an opening and then a closing parenthesis, even if you add nothing between them. <!--l. 228--><p class="indent"> The following tags are supported: <dl class="description"><dt class="description"> <span class="cmbx-10x-x-109">@@</span> </dt><dd class="description">represents the @ character </dd><dt class="description"> <span class="cmbx-10x-x-109">@abstract</span> </dt><dd class="description">This is an abstract of the description (nowadays called ”management summary”) </dd><dt class="description"> <span class="cmbx-10x-x-109">@author</span> </dt><dd class="description">Treat the argument as an author’s name and email address </dd><dt class="description"> <span class="cmbx-10x-x-109">@classname</span> </dt><dd class="description">PasDoc inserts the class name here. </dd><dt class="description"> <span class="cmbx-10x-x-109">@code</span> </dt><dd class="description">Treat argument as code example </dd><dt class="description"> <span class="cmbx-10x-x-109">@created</span> </dt><dd class="description">Creation date of item </dd><dt class="description"> <span class="cmbx-10x-x-109">@cvs</span> </dt><dd class="description">The argument is related to source versioning with e.g. cvs </dd><dt class="description"> <span class="cmbx-10x-x-109">@exclude</span> </dt><dd class="description">The current item is to be excluded from documentation </dd><dt class="description"> <span class="cmbx-10x-x-109">@false</span> </dt><dd class="description">PasDoc inserts the specially formatted text ’false’ here. </dd><dt class="description"> <span class="cmbx-10x-x-109">@html</span> </dt><dd class="description">Inserts html code in the output </dd><dt class="description"> <span class="cmbx-10x-x-109">@inherited</span> </dt><dd class="description">PasDoc inserts the name of the ancestor class here. </dd><dt class="description"> <span class="cmbx-10x-x-109">@lastmod</span> </dt><dd class="description">last modified date of item </dd><dt class="description"> <span class="cmbx-10x-x-109">@link</span> </dt><dd class="description">The argument is the name of another entity, PasDoc will add a link to it here. </dd><dt class="description"> <span class="cmbx-10x-x-109">@longcode</span> </dt><dd class="description">Format the text and output it in fixed width font, with correct formatting. </dd><dt class="description"> <span class="cmbx-10x-x-109">@name</span> </dt><dd class="description">PasDoc inserts the name of the item (class, object, function, variable...) here </dd><dt class="description"> <span class="cmbx-10x-x-109">@nil</span> </dt><dd class="description">PasDoc inserts the specially formatted text ’nil’ here. </dd><dt class="description"> <span class="cmbx-10x-x-109">@param</span> </dt><dd class="description">Treat first argument as parameter name and all following arguments as the description </dd><dt class="description"> <span class="cmbx-10x-x-109">@raises</span> </dt><dd class="description">Treat first argument as exception name and all following arguments as the description </dd><dt class="description"> <span class="cmbx-10x-x-109">@return, @returns</span> </dt><dd class="description">Description of a function’s return value </dd><dt class="description"> <span class="cmbx-10x-x-109">@true</span> </dt><dd class="description">PasDoc inserts the specially formatted text ’true’ here.</dd></dl> <!--l. 258--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.1 </span> <a id="x1-60004.1"></a>@</h4> <!--l. 259--><p class="noindent">Represents the <span class="cmtt-10x-x-109">@ </span>character, for example if you want to use one of the tags literally <!--l. 262--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.2 </span> <a id="x1-70004.2"></a>abstract</h4> <!--l. 264--><p class="noindent">For some item types like classes or units you may write very large descriptions to give an adequate introduction. However, these large texts are not appropriate in an overview list. Use the abstract tag to give a short explanation of what an item is about. One row of text is a good rule of thumb. Of course, there should only be one abstract tag per description. <!--l. 272--><p class="indent"> The abstract text will appear in the overview section of the documentation (if the document format supports this overview section), and will also appear as the first paragraph of the item full documentation. <!--l. 277--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.3 </span> <a id="x1-80004.3"></a>author</h4> <!--l. 279--><p class="noindent">For each author who participated in writing an item, one author tag should be added. The format of the author tag should conform to the following specification : <span class="cmtt-10x-x-109">@author(Name <URI>)</span> <!--l. 283--><p class="indent"> Author tags will only result in documentation output for classes, interfaces, objects and units. <!--l. 286--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> @author(Johannes Berg <email@address.here>) </div> </td></tr></table> <!--l. 289--><p class="nopar"> <!--l. 291--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.4 </span> <a id="x1-90004.4"></a>classname, inherited, name</h4> <!--l. 293--><p class="noindent">PasDoc uses the tags <span class="cmtt-10x-x-109">@inherited</span>, <span class="cmtt-10x-x-109">@classname </span>and <span class="cmtt-10x-x-109">@name </span>as placeholders for the names of the ancestor class, current class and name of the current item respectively. <!--l. 297--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> <br />{ @name is a method of @classname which overrides the method of <br /> @inherited to do something completely different...} </div> </td></tr></table> <!--l. 302--><p class="nopar"> <!--l. 304--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.5 </span> <a id="x1-100004.5"></a>code</h4> <!--l. 306--><p class="noindent">PasDoc uses the tag @code to mark example code which is preformatted and should not be changed in the output. It will usually appear in a teletype font in the final documentation. <!--l. 310--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> {: how to declare a variable. <br />Example: <br />@code( <br />var <br /> SomeVariable: SomeType;) <br />} </div> </td></tr></table> <!--l. 318--><p class="nopar"> <!--l. 321--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.6 </span> <a id="x1-110004.6"></a>created</h4> <!--l. 323--><p class="noindent">This tag should contain the date the item was created. At most one created tag should be in a description. Created tags will only result in documentation output for classes, interfaces, objects and units. There is no special format that must be followed. <!--l. 329--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.7 </span> <a id="x1-120004.7"></a>cvs</h4> <!--l. 331--><p class="noindent">This tag is used to extract the last modification date and authors of the item. The parameter of this tag should conform to the <span class="cmmi-10x-x-109">Author </span>: <span class="cmmi-10x-x-109">ccodere </span>or <span class="cmmi-10x-x-109">Date </span>: 2004<span class="cmmi-10x-x-109">/</span>04<span class="cmmi-10x-x-109">/</span>2002 : 01 : 52 string of cvs or rcs. <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> @cvs($Date$) </div> </td></tr></table> <!--l. 338--><p class="nopar"> <!--l. 340--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.8 </span> <a id="x1-130004.8"></a>exclude</h4> <!--l. 342--><p class="noindent">If an exclude tag is found in a description, the item will not appear in the documentation. As a logical consequence, no information except the exclude tag itself should be written to the description. Whenever high-level items like units or classes are excluded from the documentation process, all items contained in them will not appear as well, e.g. constants or functions in an excluded unit or methods and fields in an excluded class. <!--l. 351--><p class="indent"> The following example will produce no documentation, as the entire unit will be excluded from the documentation process. <!--l. 354--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> {@exclude } <br />unit myunit; <br /> <br />interface <br /> <br />procedure hello; <br /> <br />implementation <br /> <br />procedure hello; <br />begin <br /> WriteLn('Hello'); <br />end; <br /> <br />end. </div> </td></tr></table> <!--l. 371--><p class="nopar"> <!--l. 374--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.9 </span> <a id="x1-140004.9"></a>false</h4> <!--l. 375--><p class="noindent">PasDoc inserts the specially formatted text ’false’ here at the location of the tag. This tag does not have any parameters. <!--l. 379--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.10 </span> <a id="x1-150004.10"></a>html</h4> <!--l. 380--><p class="noindent">Pasdoc directly outputs the text that is between parentheses, without any conversion for the html output format. For other formats, the text is converted to standard text. <!--l. 384--><p class="indent"> There is no syntax checking on the validity of the HTML syntax. <!--l. 386--><p class="indent"> If there are no parentheses, <span class="cmtt-10x-x-109">@HTML </span>is directly written to the output documentation. <!--l. 389--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.11 </span> <a id="x1-160004.11"></a>lastmod</h4> <!--l. 391--><p class="noindent">This tag should contain the date the item was last modified. At most one created tag should be in a description. Lastmod tags will only result in documentation output for classes, interfaces, objects and units. There is no special format that must be followed. <!--l. 397--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.12 </span> <a id="x1-170004.12"></a>link</h4> <!--l. 399--><p class="noindent">Use this tag to make your documentation more convenient to the reader. Whenever you mention another item in the description of an item, enclose the name of the mentioned item in a link tag, e.g. <br class="newline"><span class="cmtt-10x-x-109">@link(GetName)</span>. <br class="newline">This will result in a hyperlink in HTML and a page reference in <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>. <!--l. 406--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.13 </span> <a id="x1-180004.13"></a>longcode</h4> <!--l. 408--><p class="noindent">Use this tag to output code, and pre-formatted text. The output text will closely ressemble the text typed, and will be represented in a fixed width font. In the case of pascal code typed within this tag, it will be pretty-printed first. <!--l. 413--><p class="indent"> To be able to put special characters in this tag, the tag should be followed by a # and finished with a # before the closing parentheses. <!--l. 417--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> @longCode(# <br />procedure TForm1.FormCreate(Sender: TObject); <br />var <br /> i: integer; <br />begin <br /> // Note that your comments are formatted. <br /> {$H+} // You can even include compiler directives. <br /> // reserved words are formatted in bold. <br /> for i := 1 to 10 do <br /> begin <br /> It is OK to include pseudo-code like this line. <br /> // It will be formatted as if it were meaningful pascal code. <br /> end; <br />end; <br /> #) </div> </td></tr></table> <!--l. 434--><p class="nopar"> <!--l. 437--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.14 </span> <a id="x1-190004.14"></a>nil</h4> <!--l. 439--><p class="noindent">PasDoc inserts the specially formatted text ’nil’ here. This tag does not have any parameters. <!--l. 442--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.15 </span> <a id="x1-200004.15"></a>param</h4> <!--l. 444--><p class="noindent">Treats first argument as parameter name and all following text as the description of this parameter. <!--l. 447--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> { A small description <br /> @param(Filepath The file to open) <br />} <br />constructor Init(FilePath : String); </div> </td></tr></table> <!--l. 453--><p class="nopar"> <!--l. 456--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.16 </span> <a id="x1-210004.16"></a>raises</h4> <!--l. 458--><p class="noindent">Treats the first argument as exception name and all following text as the description for this exception. <!--l. 461--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> { A small description <br /> @raises(EMyException Raises this exception) <br />} <br />constructor Init; </div> </td></tr></table> <!--l. 467--><p class="nopar"> <!--l. 469--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.17 </span> <a id="x1-220004.17"></a>return, returns</h4> <!--l. 471--><p class="noindent">Treat the text in the argument as the description of the returns value of this function or method. <!--l. 474--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">4.18 </span> <a id="x1-230004.18"></a>true</h4> <!--l. 476--><p class="noindent">PasDoc inserts the specially formatted text ’true’ here at the location of the tag. This tag does not have any parameters. <!--l. 480--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">5 </span> <a id="x1-240005"></a>Switches</h3> <!--l. 482--><p class="noindent">This is a list of all switches (program parameters) supported by <span class="cmtt-10x-x-109">pasdoc</span>. Enter <span class="cmtt-10x-x-109">pasdoc --help </span>at the command line to get this list. Make sure you keep the exact spelling of the switches, pasdoc is case-sensitive. Most switches exist in two variations, a short one with a single dash and a longer one with two dashes. You can use either switch to get the same effect. <!--l. 489--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">5.1 </span> <a id="x1-250005.1"></a>Documentation file format</h4> <!--l. 491--><p class="noindent">After loading all Pascal source code files, pasdoc will write one or more output files, depending on the output file format. Choose the output format according to your needs - you might want to create several versions for <!--l. 496--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.1.1 </span> <a id="x1-260005.1.1"></a>HTML</h5> <!--l. 498--><p class="noindent"><span class="cmtt-10x-x-109">-O html</span> <br class="newline"><span class="cmtt-10x-x-109">--format html</span> <br class="newline"> <!--l. 501--><p class="indent"> This switch makes pasdoc write HTML (Hypertext Markup Language) output. HTML files are usually displayed in a web browser, which available on all modern computer systems. <!--l. 505--><p class="indent"> It is the default output file format. Several files will be created for this output type, one for each unit, class, interface and object, additionally some overview files with lists of all constants, types etc. <!--l. 509--><p class="indent"> This is the preferred output for online viewing. <!--l. 511--><p class="indent"> It is to note that even undocumented items will appear in the final output file format. <!--l. 514--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.1.2 </span> <a id="x1-270005.1.2"></a>htmlhelp</h5> <!--l. 516--><p class="noindent"><span class="cmtt-10x-x-109">-O htmlhelp</span> <br class="newline"><span class="cmtt-10x-x-109">--format htmlhelp</span> <br class="newline"> <!--l. 519--><p class="indent"> This switch makes pasdoc write HTML (Hypertext Markup Language) output. It also writes additional files that can be used to create Microsoft htmlhelp files. Please consult the htmlhelp Microsoft SDK for more information. <!--l. 524--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.1.3 </span> <a id="x1-280005.1.3"></a><span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span></h5> <!--l. 526--><p class="noindent"><span class="cmtt-10x-x-109">-O latex</span> <br class="newline"><span class="cmtt-10x-x-109">--format latex</span> <br class="newline"> <!--l. 529--><p class="indent"> This switch makes pasdoc write output that can be interpreted using <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>. This is the preferred output format for printing the documentation. <!--l. 533--><p class="indent"> A single output file, either having the name specified with the <span class="cmtt-10x-x-109">-N </span>switch, or the default name <span class="cmtt-10x-x-109">docs.tex </span>will be created. <!--l. 537--><p class="indent"> With <span class="cmtt-10x-x-109">latex </span>you will be able to create a dvi file that can then be converted to a Postscript file using <span class="cmtt-10x-x-109">dvips</span>. Or you can also directly generate a huge HTML file by using <span class="cmtt-10x-x-109">htlatex</span>, or a PDF file by using <span class="cmtt-10x-x-109">pdflatex</span>. <!--l. 543--><p class="indent"> It is to note that the output generated by pasdoc has been optimized for <span class="cmtt-10x-x-109">pdflatex </span>and <span class="cmtt-10x-x-109">htlatex</span>. <!--l. 546--><p class="indent"> It is to note that only documented items will appear in the final output file format. <!--l. 550--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.1.4 </span> <a id="x1-290005.1.4"></a>LaTeX2rtf</h5> <!--l. 552--><p class="noindent"><span class="cmtt-10x-x-109">-O latex2rtf</span> <br class="newline"><span class="cmtt-10x-x-109">--format latex2rtf</span> <br class="newline"> <!--l. 555--><p class="indent"> This switch makes pasdoc write output that can be interpreted using <span class="cmtt-10x-x-109">latex2rtf</span>. This is the preferred output format for adding the documentation to word processor documentation. <!--l. 559--><p class="indent"> A single output file, either having the name specified with the <span class="cmtt-10x-x-109">-N </span>switch, or the default name <span class="cmtt-10x-x-109">docs.tex </span>will be created. This file can then be converted to rtf by using <span class="cmtt-10x-x-109">latex2rtf</span>. <!--l. 564--><p class="indent"> This output will only work with the <span class="cmtt-10x-x-109">latex2rtf </span>tool. Using other tools might not produce the expected results. <!--l. 567--><p class="indent"> It is to note that only documented items will appear in the final output file format. <!--l. 571--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">5.2 </span> <a id="x1-300005.2"></a>Format-specific switches</h4> <!--l. 573--><p class="noindent">The following switches can only be used with one output file format and are useless for the others. <!--l. 576--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.2.1 </span> <a id="x1-310005.2.1"></a>No generator information</h5> <!--l. 578--><p class="noindent"><span class="cmtt-10x-x-109">-X</span> <br class="newline"><span class="cmtt-10x-x-109">--exclude-generator</span> <br class="newline"> <!--l. 581--><p class="indent"> By default, pasdoc includes some information on itself and the document creation time at the bottom of each generated HTML file. This switch keeps pasdoc from adding that information. <!--l. 585--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.2.2 </span> <a id="x1-320005.2.2"></a>Specify name of document</h5> <!--l. 586--><p class="noindent"><span class="cmtt-10x-x-109">-N NAME --name NAME</span> <!--l. 589--><p class="indent"> When the output format of the documentation is not HTML (such as latex, or CHM), this specifies the name of the final name of the documentation. If this is not specified, it uses the default<span class="cmtt-10x-x-109">docs </span>filename. <!--l. 597--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.2.3 </span> <a id="x1-330005.2.3"></a>Specify footers and headers to use</h5> <!--l. 599--><p class="noindent"><span class="cmtt-10x-x-109">-F FILNAME --footer FILENAME -H FILNAME --header FILENAME</span> <!--l. 604--><p class="indent"> You can specify texts files which PasDoc should use as header or footer for all generated html pages. This option is only available for the html output format. <!--l. 608--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc --header myheader.txt --footer myfooter.txt </div> </td></tr></table> <!--l. 611--><p class="nopar"> <!--l. 615--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">5.3 </span> <a id="x1-340005.3"></a>Comment Marker switches</h4> <!--l. 618--><p class="noindent">It is possible for pasdoc to ignore comments that do not start with the correct start markers. By default, all comments are treated as item descriptions. This can be changed using the following switches: <!--l. 623--><p class="indent"> <dl class="description"><dt class="description"> <span class="cmtt-10x-x-109">--staronly</span> </dt><dd class="description">Parse only <span class="cmsy-10x-x-109">{</span>**, (*** and //** style comments </dd><dt class="description"> <span class="cmtt-10x-x-109">--marker</span> </dt><dd class="description">Parse only <span class="cmsy-10x-x-109">{</span><span class="cmmi-10x-x-109"><</span>marker<span class="cmmi-10x-x-109">></span>, (*�marker� and //�marker� comments. Overrides the staronly option, which is a shortcut for ’-marker=**’ </dd><dt class="description"> <span class="cmtt-10x-x-109">--marker-optional</span> </dt><dd class="description">Do not require the markers given in -marker but remove them from the comment if they exist.</dd></dl> <!--l. 632--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">5.4 </span> <a id="x1-350005.4"></a>Output language switches</h4> <!--l. 634--><p class="noindent"><span class="cmtt-10x-x-109">-L lg</span> <br class="newline"><span class="cmtt-10x-x-109">--language lg</span> <br class="newline"> <!--l. 638--><p class="indent"> You can specify the language that will be used for words in the output like <span class="cmti-10x-x-109">Methods </span>or <span class="cmti-10x-x-109">Classes, interfaces and objects</span>. Your choice will not influence the status messages printed by pasdoc to standard output - they will always be in English. Note that you can choose at most one language switch - if you specify none, the default language <span class="cmti-10x-x-109">English </span>will be used. <!--l. 645--><p class="indent"> The <span class="cmtt-10x-x-109">lg </span>parameter can take one of the following values: <dl class="description"><dt class="description"> <span class="cmbx-10x-x-109">ba</span> </dt><dd class="description">Bosnian (Codepage 1250) </dd><dt class="description"> <span class="cmbx-10x-x-109">br</span> </dt><dd class="description">Portugese / Brazilian </dd><dt class="description"> <span class="cmbx-10x-x-109">ct</span> </dt><dd class="description">Catalan </dd><dt class="description"> <span class="cmbx-10x-x-109">dk</span> </dt><dd class="description">Danish </dd><dt class="description"> <span class="cmbx-10x-x-109">en</span> </dt><dd class="description">English </dd><dt class="description"> <span class="cmbx-10x-x-109">fr</span> </dt><dd class="description">French </dd><dt class="description"> <span class="cmbx-10x-x-109">de</span> </dt><dd class="description">German </dd><dt class="description"> <span class="cmbx-10x-x-109">id</span> </dt><dd class="description">Indonesian </dd><dt class="description"> <span class="cmbx-10x-x-109">it</span> </dt><dd class="description">Italian </dd><dt class="description"> <span class="cmbx-10x-x-109">jv</span> </dt><dd class="description">Javanese </dd><dt class="description"> <span class="cmbx-10x-x-109">pl</span> </dt><dd class="description">Polish </dd><dt class="description"> <span class="cmbx-10x-x-109">ru.1251</span> </dt><dd class="description">Russian (Codepage 1251) </dd><dt class="description"> <span class="cmbx-10x-x-109">ru.866</span> </dt><dd class="description">Russian (Codepage 866) </dd><dt class="description"> <span class="cmbx-10x-x-109">ru.KOI8</span> </dt><dd class="description">Russian (KOI-8 </dd><dt class="description"> <span class="cmbx-10x-x-109">sk</span> </dt><dd class="description">Slovak </dd><dt class="description"> <span class="cmbx-10x-x-109">es</span> </dt><dd class="description">Spanish </dd><dt class="description"> <span class="cmbx-10x-x-109">se</span> </dt><dd class="description">Swedish</dd></dl> <!--l. 666--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">5.5 </span> <a id="x1-360005.5"></a>Other switches</h4> <!--l. 670--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.1 </span> <a id="x1-370005.5.1"></a>Include / Exclude class Members by visiblity</h5> <!--l. 672--><p class="noindent"><span class="cmtt-10x-x-109">-M</span> <br class="newline"><span class="cmtt-10x-x-109">--visible-members</span> <br class="newline"> <!--l. 675--><p class="indent"> By default all non-private fields, methods properties are included in the documentation. This switch permits to change which items of the specified visibility will be documented. <!--l. 679--><p class="indent"> The possible arguments, separated by a comma are: <dl class="description"><dt class="description"> <span class="cmtt-10x-x-109">private</span> </dt><dd class="description"> </dd><dt class="description"> <span class="cmtt-10x-x-109">protected</span> </dt><dd class="description"> </dd><dt class="description"> <span class="cmtt-10x-x-109">public</span> </dt><dd class="description"> </dd><dt class="description"> <span class="cmtt-10x-x-109">published</span> </dt><dd class="description"> </dd><dt class="description"> <span class="cmtt-10x-x-109">automated</span> </dt><dd class="description"></dd></dl> <!--l. 688--><p class="indent"> In the following example only the private and protected members will be documented, all others will be ignored. <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc --visible-members private,protected </div> </td></tr></table> <!--l. 693--><p class="nopar"> <!--l. 695--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.2 </span> <a id="x1-380005.5.2"></a>Output directory</h5> <!--l. 697--><p class="noindent"><span class="cmtt-10x-x-109">-E DIRECTORY</span> <br class="newline"><span class="cmtt-10x-x-109">--output DIRECTORY</span> <br class="newline"> <!--l. 700--><p class="indent"> By default, pasdoc writes the output file(s) to the current directory. This switch defines a new output directory - this makes sense especially when you have many units and classes, they should get a subdirectory of their own, e.g. <span class="cmtt-10x-x-109">htmloutput</span>. <!--l. 705--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.3 </span> <a id="x1-390005.5.3"></a>Read file names from file</h5> <!--l. 707--><p class="noindent"><span class="cmtt-10x-x-109">-S FILE</span> <br class="newline"><span class="cmtt-10x-x-109">--source FILE</span> <br class="newline"> <!--l. 710--><p class="indent"> If you want pasdoc to write documentation for a large project involving many unit source code files, you can use this switch to load the file names from a text file. Pasdoc expects this file to have one file name in each row, no additional cleaning is done, so be careful not to include spaces or other whitespace like tabs. <!--l. 717--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.4 </span> <a id="x1-400005.5.4"></a>Change verbosity level</h5> <!--l. 719--><p class="noindent"><span class="cmtt-10x-x-109">-v LEVEL</span> <br class="newline"><span class="cmtt-10x-x-109">--verbosity LEVEL</span> <br class="newline"> <!--l. 722--><p class="indent"> Using this switch in combination with an integer number <span class="cmsy-10x-x-109"><u class="underline">></u> </span>0 lets you define the amount of information pasdoc writes to standard output. The default level is 2, this switch is optional. A level of 0 will result in no output at all. <!--l. 727--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.5 </span> <a id="x1-410005.5.5"></a>Show help</h5> <!--l. 729--><p class="noindent"><span class="cmtt-10x-x-109">-?</span> <br class="newline"><span class="cmtt-10x-x-109">--help</span> <br class="newline"> <!--l. 732--><p class="indent"> This switch makes pasdoc print usage hints and supported switches to standard output (usually the console) and terminates. <!--l. 735--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.6 </span> <a id="x1-420005.5.6"></a>Specify a directive</h5> <!--l. 738--><p class="noindent"><span class="cmtt-10x-x-109">-D DIRECTIVE</span> <br class="newline"><span class="cmtt-10x-x-109">--define DIRECTIVE</span> <br class="newline"> <!--l. 741--><p class="indent"> Adds <span class="cmtt-10x-x-109">DIRECTIVE </span>to the list of conditional directives that are present whenever parsing a unit is started. <!--l. 744--><p class="indent"> The list of directives will be adjusted whenever a directive like <span class="cmtt-10x-x-109">WIN32 </span>or <span class="cmtt-10x-x-109">FPC</span> is defined or undefined in the source code. Each define should be separated by the others by a comma, as shown in the following example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc --define debug,hello,world </div> </td></tr></table> <!--l. 750--><p class="nopar"> <!--l. 752--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.7 </span> <a id="x1-430005.5.7"></a>Specify an include file path</h5> <!--l. 755--><p class="noindent"><span class="cmtt-10x-x-109">-I DIR</span> <br class="newline"><span class="cmtt-10x-x-109">--include DIR</span> <br class="newline"> <!--l. 758--><p class="indent"> Adds <span class="cmtt-10x-x-109">DIR </span>to the list of directories where pasdoc will search for include files. Whenever an include file directive is encountered in the source code, pasdoc first tries to open that include file by the name found in that directive. This will work in all cases where the current directory contains that include file or when the file name contains a valid absolute or relative path. <!--l. 765--><p class="indent"> It is possible to use this switch more than once on the command line. <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc --include c:\mysources\include --include c:\3rdparty\somelib\include </div> </td></tr></table> <!--l. 769--><p class="nopar"> <!--l. 771--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.8 </span> <a id="x1-440005.5.8"></a>Specify directive file</h5> <!--l. 774--><p class="noindent"><span class="cmtt-10x-x-109">-d DIRECTORY</span> <br class="newline"><span class="cmtt-10x-x-109">--conditionals DIRECTORY</span> <br class="newline"> <!--l. 777--><p class="indent"> Adds the defines specified in a file <span class="cmtt-10x-x-109">DIRECTORY </span>to the list of conditional directives that are present whenever parsing a unit is started. <!--l. 780--><p class="indent"> The list of directives will be adjusted whenever a directive like <span class="cmtt-10x-x-109">WIN32 </span>or <span class="cmtt-10x-x-109">FPC</span> is defined or undefined in the source code. There should be one defibe per line in the conditional file. <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc --conditionals /home/me/pascal/myconditionals </div> </td></tr></table> <!--l. 786--><p class="nopar"> <!--l. 788--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.9 </span> <a id="x1-450005.5.9"></a>Set title of document</h5> <!--l. 790--><p class="noindent"><span class="cmtt-10x-x-109">-T "STRING"</span> <br class="newline"><span class="cmtt-10x-x-109">--title "STRING"</span> <br class="newline"> <!--l. 793--><p class="indent"> This option sets the title of the output document. The characters in the title should be enclosed in double quotes. <!--l. 796--><p class="indent"> By default, depending on the documentation format, the document contains either no title, or the name of the unit being documented. <!--l. 799--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc -T "This is my document title" </div> </td></tr></table> <!--l. 802--><p class="nopar"> <!--l. 804--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.10 </span> <a id="x1-460005.5.10"></a>Include uses list</h5> <!--l. 806--><p class="noindent"><span class="cmtt-10x-x-109">--write-uses-list</span> <br class="newline"> <!--l. 808--><p class="indent"> PasDoc can optionally include the list of units in a unit’s uses clause to that unit’s description. <!--l. 811--><p class="indent"> Example: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> pasdoc --write-uses-list </div> </td></tr></table> <!--l. 814--><p class="nopar"> <!--l. 816--><p class="indent"> If a unit in the uses list is part of the documentation, it will be clickable in the output. <!--l. 819--><p class="indent"> By default this option is disabled. <!--l. 821--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.11 </span> <a id="x1-470005.5.11"></a>Full link output</h5> <!--l. 823--><p class="noindent"><span class="cmtt-10x-x-109">--full-link</span> <br class="newline"> <!--l. 825--><p class="indent"> This option controls the behaviour of ”@link(unit.procedure)” type links. If it is set, the output generated will look like this: <!--l. 828--><p class="indent"> <span class="cmtt-10x-x-109">unit.procedure </span>with the ”unit” part linking to the unit and the ”procedure” part linking to the procedure inside the unit. If it is unset, then the output will only be <span class="cmtt-10x-x-109">procedure</span>. <!--l. 832--><p class="noindent"> <h5 class="subsubsectionHead"><span class="titlemark">5.5.12 </span> <a id="x1-480005.5.12"></a>Non documented switches</h5> <!--l. 834--><p class="noindent">This lists the other unusual switches that are recognized by pasdoc: <!--l. 837--><p class="indent"> <dl class="description"><dt class="description"> <span class="cmtt-10x-x-109">-R, --description</span> </dt><dd class="description">read description from this file </dd><dt class="description"> <span class="cmtt-10x-x-109">-C, --content</span> </dt><dd class="description">Read Contents for HtmlHelp from file </dd><dt class="description"> <span class="cmtt-10x-x-109">--numericfilenames</span> </dt><dd class="description">Causes the html generator to create numeric filenames </dd><dt class="description"> <span class="cmtt-10x-x-109">--graphviz-uses</span> </dt><dd class="description">write a GVUses.gviz file that can be used for the <span class="cmtt-10x-x-109">dot</span> program from GraphViz to generate a unit dependency graph. </dd><dt class="description"> <span class="cmtt-10x-x-109">--graphviz-classes</span> </dt><dd class="description">write a GVClasses.gviz file that can be used for the <span class="cmtt-10x-x-109">dot </span>program from GraphViz to generate a class hierarchy graph. </dd><dt class="description"> <span class="cmtt-10x-x-109">--abbreviations</span> </dt><dd class="description">abbreviation file, format is ”[name] value”, value is trimmed, lines that do not start with ’[’ (or whitespace before that) are ignored </dd><dt class="description"> <span class="cmtt-10x-x-109">--aspell</span> </dt><dd class="description">enable aspell, giving language as parameter, currently only done in HTML output </dd><dt class="description"> <span class="cmtt-10x-x-109">--ignore-words</span> </dt><dd class="description">When spell-checking, ignore the words in that file. The file should contain one word on every line, no comments allowed </dd><dt class="description"> <span class="cmtt-10x-x-109">--cache-dir</span> </dt><dd class="description">Cache directory for parsed files (default not set)</dd></dl> <!--l. 853--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">6 </span> <a id="x1-490006"></a>Known problems</h3> <!--l. 855--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">6.1 </span> <a id="x1-500006.1"></a>Documentation of program files</h4> <!--l. 857--><p class="noindent">As was said before, only units are regarded by pasdoc. In an OOP environment for which pasdoc was written, an application is usually a class overriding an abstract application class, so all code that is ever needed in the program file looks like this: <table width="100%" class="verbatim"><tr class="verbatim"><td class="verbatim"><div class="verbatim"> program main; <br /> <br />uses myapp; <br /> <br />var App: TMyApplication; <br /> <br />begin <br /> App := TMyApplication.Create; <br /> App.Run; <br /> App.Destroy; <br />end. </div> </td></tr></table> <!--l. 874--><p class="nopar"> <!--l. 876--><p class="indent"> So there isn’t much to do for documentation. If you’re not using OOP, you could at least try to move as much code as possible out of the main program to make things work with pasdoc. <!--l. 880--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">6.2 </span> <a id="x1-510006.2"></a>Records</h4> <!--l. 882--><p class="noindent">Pasdoc cannot create separate documentation for members of a record. In object-oriented programs, records will not appear most of the time because all encapsulated data will be part of a class or object. However, you can give a single explanation on a record type which could contain a description of all members. <!--l. 888--><p class="noindent"> <h4 class="subsectionHead"><span class="titlemark">6.3 </span> <a id="x1-520006.3"></a>Non-unique identifiers</h4> <!--l. 890--><p class="noindent">In some larger projects, identifiers may be used in different contexts, e.g. as the name for a parameter and as a function name. Pasdoc will not be able to tell these contexts apart and as a result, will create in the above-mentioned example links (at least in HTML) from the argument name of a function to the type of the same name. <!--l. 896--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">7 </span> <a id="x1-530007"></a>Adding support for another output format</h3> <!--l. 898--><p class="noindent">If you want to write a different type of document than those supported, you can create another unit with a new object type that overrides <span class="cmtt-10x-x-109">TDocGenerator </span>from unit <span class="cmtt-10x-x-109">PasDoc</span><span class="cmtt-10x-x-109">_Gen.pas</span>. You’ll have to override several of its methods to implement a new output format. As examples, you can always look at how the HTML and <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>generators work. First of all, you must decide whether your new output format will store the documentation in one (like <span class="LATEX">L<span class="A">A</span><span class="TEX">T<span class="E">E</span>X</span></span>) or multiple files (like HTML). <!--l. 910--><p class="noindent"> <h3 class="sectionHead"><span class="titlemark">8 </span> <a id="x1-540008"></a>Credits</h3> <!--l. 912--><p class="noindent">Thanks to Michael van Canneyt, Marco van de Voort, Dan Damian, Philippe Jean Dit Bailleul, Jeff Wormsley, Johann Glaser, Gudrun Plato, Erwin Scheuch-Hellig, Iván Montes Velencoso, Mike Ravkin, Jean-Pierre Vial, Jon Korty, Martin Krumpolec, André Jager, Samuel Liddicott, Michael Hess, Ivan Tarapcik, Marc Weustink, Pascal Berger, Rolf Offermanns and Rodrigo Urubatan Ferreira Jardim for contributing ideas, bug reports and fixes, help and code! </body></html>