manual.html

DelphiDoc is a program for automatic generation of documentation on a Delphi-Project. At the momen

       parameter like for example:<br>
       <code>-pdgFro dd.ddp .\_doc TICWinHelpDoc
                     AutoLaunchDocumentation=true</code><br>
       Long options can be abbreviated as long as their meaning is not
       ambiguous, for instance "<code>--so=FILE</code>" can also be used
       instead of "<code>--<strong>so</strong>urceproject=FILE</code>".</p>

    <p>The list of parameters follows. On Windows "/" can also be used instead
       of "-" for short options. When loading project files the name "-" can
       also be specified in the command line version to load the file from
       <code>stdin</code>/<code>Input</code>. "<code>[-]</code>" on a line on
       its own (i.e. an initialization section with the name "-") is treated as
       the end of the file, in case several files should be read from the
       standard input stream of the program.</p>

    <p>Additionally to the parameters listed here, the command line version
       checks whether the first parameter is "<code>-auto</code>". If this is
       not the case it will wait for the user to press the enter key when it
       has finished parsing all parameters.</p>

    <dl>
      <dt>-h, -?, --help</dt>
      <dd>Shows a help text about the command line switches of the program
          and aborts any further parsing of the command line. But beware that
          any parameters before it will be executed.</dd>

      <dt>-p FILE, --sourceproject=FILE</dt>
      <dd>Loads a project file defining lists of sources files to be parsed and
          with which options they should be parsed. After loading these
          information the current generator objects try to read their options
          from the file and localized versions of the texts are also loaded if
          available. Due to this, the generator objects should be selected
          before loading the project file. After that the source files are
          automatically parsed.</dd>

      <dt>-e FILE, --executable=FILE</dt>
      <dd>Tries to select source files to be parsed by the executable file
          specified after the option. If a project file exists with the same
          name (but different extension) it is loaded like with the
          <code>-p</code> option. If not either the <code>.dpr</code> file
          with the same name is added to the list of files to be parsed or, if
          it does not exist, the directory containing the executable file. Then
          the selected files are parsed.<br>
          By adding <em>DelphiDoc</em> to the Tools-menue of Delphi and
          entering the parameters "<code>$SAVEALL $SAVE -e $EXENAME</code>"
          (and others) it's relatively easy to generate documentation for the
          current project.</dd>

      <dt>-P FILE, --loadparseddata=FILE</dt>
      <dd>Loads previously parsed data from a file.</dd>

      <dt><strike>-k</strike></dt>
      <dd>The <code>-k</code> switch is no longer supported. It is not
          necessary anymore as options no longer have to be in sets.</dd>

      <dt>-g NAME, --generator=NAME</dt>
      <dd>Selects a generator object to be used to generate documentation.
          Either the idenfication or the name of the class can be used to
          specify a generator, the idenfication is recommended.</dd>


      <dt>-d PATH, --docpath=PATH</dt>
      <dd>Specifies the directory to generate the documentation to. It will be
          created if it does not exist. If it exists it should be noted that
          all files in it will be overwritten if they share the same name as a
          file of the documentation.</dd>

      <dt>--docfilename=FILE</dt>
      <dd>Specifies the name of the file the documentation should be generated
          to. This option is ignored if the generator has no option
          "FileName" and is in the other case equivalent to
          <code>--genoption=FileName=FILE</code>.</dd>

      <dt>-o NAME=VALUE, --genoption=NAME=VALUE</dt>
      <dd>Sets the value of an option of one of the generator objects. The
          option to be set is specified by its name, after a separating equals
          sign "=" follows the string representation of its new value. Remember
          to quote the value if it contains any whitespaces.</dd>

      <dt>-l NAME=VALUE, --localize=NAME=VALUE</dt>
      <dd>Sets a localized version of a text to be used in the documentation to
          be generated. The text is specified by its name, after a separating
          equals sign "=" follows the its new value. Remember to quote the
          text if it contains any spaces.</dd>

      <dt>-L FILE, --loadlocalization=FILE</dt>
      <dd>Loads localized versions of the texts to be used in the documentation
          to be generated from a file. The texts have to be defined in an
          initialization section of the name "TEditDocumentationTexts". The
          names are the names of the texts to be localized and their values the
          corresponding localized versions. The texts should probably be quoted
          to ensure leading and trailing spaces are not lost.<br>
          If the file does not exists and the short option <code>-L</code> is
          used it will instead be interpreted as the option
          <code>--uselanguage</code>.</dd>

      <dt>--uselanguage=NAME</dt>
      <dd>Uses the localized texts of a predefined language when generating the
          documentation. Currently only "English" and "German"/"Deutsch" are
          predefined, unknown values will be ignored.</dd>

      <dt>-u FILE, --userdoc=FILE</dt>
      <dd>Adds a file with additional user documentation to the list of files.
          Generally only one or a few files should be added, other files should
          be included with them with the inline command
          <code>~[<a href="comments.html#icuserdoc">userdoc</a> ]</code>.</dd>

      <dt>-U, --clearuserdocumentation</dt>
      <dd>Clears the list of files with additional user documentation. After
          that new files can be added with the option "<code>-u</code>" or
          "<code>--userdoc</code>".</dd>

      <dt>-f FILTERDEF, --messagefilter=FILTERDEF</dt>
      <dd>Changes the filter for messages of the generator objects, filtered
          messages will not be shown after generating the documentation. This
          option is only relevant for the command line version.<br>
          FILTERDEF can be one or more sets of messages to filter, they
          are separated by the path separator of the current platform, this
          means semicolon ";" for Windows and colon ":" for Unix. Each set is
          defined as:<br>
          <code>Filter ::= GroupName=<strong>(</strong>[01][01]*<strong>|</strong>(+|-)number[,number]*<strong>|</strong>-<strong>)</strong></code><br>
          The group name is generally the class the message is defined in. As
          can be seen there are three different possibilities to set the filter
          for the group. In the first version each message is represented by a
          binary digit, it will be filtered if its digit is "1". In the
          middle version the first plus or minus sign defines whether the
          messages, identified by their indices within the group and following
          as a comma separated list, should either be filtered "+" or not "-".
          When only a minus sign "-" is specified, all messages from the group
          will be shown. An example:<br>
          <code>-f TFormatCommentDoc=+0,1,2,3,4,5,6,7;TJADDCommentEvaluator=-</code></dd>
      <dt>-F, --clearmessagefilter</dt>
      <dd>Clears the filter for messages of the generator objects, so all
          messages will be shown. This option is only relevant for the command
          line version.</dd>

      <dt>-v TOPICS, --verbose=TOPICS</dt>
      <dd>Specifies what topics the command line version should be verbose
          about, this option is ignored for the GUI version. If TOPICS is empty
          all topics are implied. Currently only three topics are available
          represented by the tree letters "P", "I" and "G". If a letter is in
          the value of TOPICS, the program will be verbose about its topic.
          The usage of the short option is recommended, as the long option will
          probably be changed to use longer names of the topics at some point
          in the future.<br>
          "P" indicates that the messages of the parser should be shown after
          parsing source files. "I" indicates that the list of "unknown"
          identifiers within the parsed source files should be shown after
          parsing. "G" finally indicates that the messages of the generator
          should be shown after generating the documentation. Please notice,
          that these can also be filtered on a per-message basis with the
          <code>-f</code> option.
      </dd>
      <dt>-V TOPICS, --quiet[=TOPICS]</dt>
      <dd>Specifies what topics the command line versions should remain quiet
          about, it is ignored in the GUI version. This option is the
          counterpart to <code>-v/--verbose</code>, it has the same meaning,
          only that the final list of topics to be verbose about will be
          inverted.</dd>


      <dt>-r, --showprogress[=true|false]</dt>
      <dd>Specifies that (whether) the progress of the parsing of source files
          and generating of documentation should be shown in the command line
          version, ignored for the GUI version.</dd>
      <dt>-R, --hideprogress</dt>
      <dd>Specifies that the progress of the parsing of source files and
          generating of documentation should not be shown in the command line
          version, the option is ignored for the GUI version. This can be handy
          when the output of the program is redirected into a file and it
          shouldn't be cluttered up with the progress bars.</dd>

      <dt><strike>-a</strike></dt>
      <dd>The <code>-a</code> switch is no longer supported. It has been
          superseded by the option <code>-A/--generate</code>.</dd>

      <dt>-i FILE, --guilogfile=FILE</dt>
      <dd>Adds a log file of a GUI to generate documentation as a help about
          or a directory containing such log files to the internal list of log
          files.</dd>

      <dt>-I, --clearguilogfiles</dt>
      <dd>Clears the list of log files of GUIs of which help can be generated.
          After that new files can be added with the option "<code>-i</code>"
          or "<code>--guilogfile</code>".</dd>

      <dt>-H FILE, --guihelpproject=FILE</dt>
      <dd>Loads a GUI help project file defining the list of log files of GUIs
          to generate the help about and the alternative content of the main
          index for the help. After loading these information the current
          generator objects try to read their options from the file and
          localized versions of the texts are also loaded if available. Due to
          this, the generator objects should be selected before loading the
          project file.</dd>

      <dt>-A, --generate[=MODE]</dt>
      <dd>Generates documentation with the currently available data. The mode
          defines what kind of documentation should be generated.<br>
          "Source" is the default and will generate documentation about the
          parsed source code and include the additional user documentation.
          "UserDoc" will only use the files of user documentation when
          generating.
          "GUIHelp" will generate the documentation as a help on the GUI whose
          log files have been added and also include the additional user
          documentation.<br>
          When no mode is specified the most recently used mode will be used
          again, initially always documentation about source code is
          selected. In the command line version this switch is always implied
          as the last option when new data has been read or options been
          changed since the last generation.</dd>
    </dl>




    <h2><a name="Format">Documentation Formats</a></h2>

    <p>At the moment there are five different formats to choose from: HTML,
       Windows Help file, HTML Help,
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X and PDF.</p>

    <p>The HTML-Format is the first and thus it is the oldest generator. It was
       the simplest format to generate but under Windows perhaps not the most
       comfortable to use. So there may be some things, that could be optimized
       or better formatted.<br>
       The Windows Help Format is really comfortable to use, if it is
       integrated in the help of Delphi, so you get help via pressing F1
       directly in the IDE.<br>
       The HTML Help Format is the new help format in Windows. It is similar to
       the old format but raises its limits greatly so it can also be used for
       really big projects.<br>
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X can be used to
       generate documents in many different formats. Created PDFs for example
       are linked (like HTML) and easy to use. The makros for these links can
       be changed to produce texts usable in printed versions.<br>
       PDF files
       (<a href="http://www.adobe.com/products/acrobat/adobepdf.html">Portable
       Document Format</a>, copyrighted by
       <a href="http://www.adobe.com/">Adobe</a>) look quite similar to the PDF
       files generated by the
       L<small><sup>A</sup></small>T<small><sub>E</sub></small>X files but you
       save the compiling with T<small><sub>E</sub></small>X and, well, you
       don't have to have T<small><sub>E</sub></small>X installed.<p>

    <p>Each generator creates also a few Xfig- (*<code>.fig</code>),
       WMF (*<code>.wmf</code>) and SVG-files (*<code>.svg</code>). These show
       the relations between files and classes/interfaces.
       XFig-Files are vector graphics, their format is textual not binary in
       contrast to WMF-files. The format originated from the Unix-world, but
       there are <a href="http://www.xfig.org/">programs</a> to view and edit
       these files for Windows. WMF-files should be insertable into most
       office-programs. SVG - <a href="http://www.w3.org/TR/SVG/">Scalable
       Vector Graphics</a> - is a open textual graphic format based on XML, it
       is an official W3C standard, most internet browsers should be able to
       show them without any problems.
       There are also lots of <a href="http://www.svgi.org/">programs</a>
       supporting the format, and for the Internet Explorer
       <a href="http://wiki.svg.org/Viewer_Implementations#Browser_Plug-Ins">plug-ins</a>
       are available to enabled also that browser to view SVG images.</p>