files.html

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

    <p>There is another feature of initialization files that is important for
       <em>DelphiDoc</em>: Initialization files can be merged. As long as they
       don't have sections with the same name, it is no problem so save several
       settings in just one file or even copy files together.</p>



    <h3><a name="INIDelphiDoc">DelphiDoc.ini</a></h3>

    <p>This file saves the general settings of the program, this means mainly
       the GUI version. Generally each form and some pages have a sections on
       their own to save their settings. The name of the section is generally
       the same name as their class. The framework for this is implemented in
       the unit <code>USettingsKeeper</code>, but most forms also implement a
       specialized class to save, set and load their settings.</p>

    <p>Additional to the <i>visual</i> settings the ini file also contains the
       section "JADDState" containing the general state of the program, which
       is also read by the command line version. It includes the version of
       Delphi to emulate when parsing source code and the generator and helper
       objects to use when generating documentation.</p>

    <p>Even more interestingly and as mentioned above other data can be merged
       into the initialization file. So localized texts and options of the
       generator objects can also be saved within this main file, which will
       then be read at program start-up and each change of the selected
       generator. For the format of these settings see below.</p>


    <h3><a name="INIProject">Project Files</a></h3>

    <p>A <em>DelphiDoc</em> Project File consists of several sections which
       contain the files to be parsed and the compiler options to use when
       parsing them.<br>
       As can be seen in the GUI version there are actually three lists of
       files, each is saved in an own section with the same format. The list
       of files to be parsed is saved in the section "ToParse", the list not to
       be parsed in the section "NotToParse" and the list of library files in
       "Libs".</p>

    <p>Each list has a field "Count" with the number of entries in the list
       and then for each entry two values with the prefixes "Item" and
       "Recurse" followed by the number between 0 and Count - 1. The item
       specifies the file in the list and the other boolean flag specifies
       whether the item is checked, i.e. whether for Delphi project files all
       files within the project should also be parsed or for directories
       whether files in sub-directory should be parsed.</p>

    <p>For the additional compiler options some general settings are saved in
       the section "PreDefines". These include the list of defined symbols, the
       settings of the compiler switches and unit aliases. It specifies also
       whether the .cfg file of Delphi projects should be read and options
       which may be set after parsing it. Then there are two lists, they are
       saved in the same format as the lists of files to parse, but without
       the additional flag. One is the list of "SearchPaths", which should
       contain directories. The other is a list of constants for expressions
       for conditional compiling in "CondCompilingConstants", each entry is a
       declaration of an untyped constant (without the <code>const</code>
       before it).</p>


    <h3><a name="INIGUIProject">GUI Help Project Files</a></h3>

    <p>These files contain the list of log files of GUIs to read and generate
       documentation about and the alternative content for the main index of
       the documentation, each in its own section. The list of log files are
       written in the section "GUILogFiles" in the same format as used for the
       source project files for list of files.</p>

    <p>The content of the main index is written in a recursive format. Each
       entry consists of three comma-separated values within a field. The first
       one defines the link (commas are replaced with %44, as they could only
       appear in external links, and commas can be quoted that way in HTTP) and
       the third one defines the text for the entry. And the value in the
       middle is either empty or defines the prefix for the child entries of
       the entry. The prefix for the top-level entries is the empty string.<br>
       Each list of entries consists of the "Count" field with the number of
       entries and each entry is saved in a field whose name is just the number
       of the entry, between 1 and Count. The field name is always appended to
       the prefix of the name. While the prefix itself does not contain a real
       meaning, it just has to be unique, it is by default generated by taking
       the whole field name of the parent entry and appending a dot ".".</p>



    <h3><a name="INIDiagram">Saved Diagram Lay-Outs</a></h3>

    <p>These files are a bit different, and maybe they shouldn't be
       initialization files. There are no special sections, each section is
       interpreted as a separate diagram lay-out. The only constraint about the
       section name is of course, that it has to be unique, this is achieved by
       adding a random number to the prefix "Diagram_". Each section consists
       of two kinds of values, settings about the diagram and its content.</p>

    <p>All settings have a dot "." as prefix. They define the options of the
       diagram in a similar format as in <a href="comments.html#icdiagram">the
       inline command to create diagrams</a>, but the names are more verbose.
       The rest of the entries define the files or classes that are in the
       diagram. The name of the field is always the name of the unit, or for
       class diagrams the name of the class prefixed with the name of the unit
       it is declared in separated by a dot ".". Its value is the position of
       the box inside the diagram as a comma-separated pair of numbers, first
       the x- then the y-coordinate.</p>



    <h3><a name="INIGenerator">Generator Options</a></h3>

    <p>There are no special files for the options of the objects to generate
        the documentation. Any ini file can be used to save the options. This
        means they can be saved in extra files, in the default ini file
        "DelphiDoc.ini" or in one of the project files (source or GUI
        help).</p>

    <p>The options are saved as simple "Name=Value" pairs, with the name being
       the name of the option and the value being the string representation of
       the value to be set. More interesting are the sections the options
       are saved in. As the generators (and most helper objects) are declared
       in a class hierarchy, the options can be saved either in a section with
       the name of the class of the generator, or all options can be saved in
       the corresponding section of the class they are defined in.</p>

    <p>When loading the options from a file, first all options are read from
       the base class, then of all other ancestor classes and finally from the
       section with the name of the class itself. This allows to define option
       values for all generators in their common base class, but also to
       override values for some generators in their own section.</p>

    <p>When a new generator object is selected, it will automatically be
       initialized from the options in the default ini file
       "DelphiDoc.ini".</p>



    <h3><a name="INILocalizing">Localized Texts for the Documentation</a></h3>

    <p>The localized texts are written and loaded just like the options of the
       generator objects. The values also consist of "Name=Value" pairs with
       the name being the name of the text to be localized and the value being
       the text to be used for it, it will generally be quoted with single
       quotes "'", just like in Pascal. This is necessary to keep trailing
       spaces within the values, normally they would be stripped. The texts
       will be read from the section with the name
       "TEditDocumentationTexts".</p>

    <p>When the program starts, it will automatically read the localized texts
       from the default ini file "DelphiDoc.ini".</p>


  </body>
</html>