Templates

XML file

To create documentation, Pascal Browser first gathers information about the source code and outputs this to an XML file. You can select to keep this XML file, if you check the appropriate option on the Properties - General tab page. The name of the file is <projectname>.xml.

This XML file keeps data about each identifier that is reported in the project. Here follows a short sample for how a module is represented in XML code:

<Item kind="Module" id="106EDC0" modid="106EDC0" link="1">

   <Name>MyModule</Name>

   <Path>C:\PROJEKT\MyProj\MyModule.pas</Path>

   <Modified>2007-02-24 15:15:10</Modified>

   <Size>78</Size>

   <MainFile>1</MainFile>

   <HasMain>1</HasMain>

   <IsForm>0</IsForm>

   <HasIni>0</HasIni>

   <HasFin>0</HasFin>

   <Used>

     <Item id="1527DC0" interface="1"/>

     <Item id="1B2D4B0" interface="1"/>

     <Item id="2171630" interface="1"/>

     <Item id="1E4EC40" interface="1"/>

     <Item id="207AD80" interface="1"/>

   </Used>

 </Item>

The XML code generated for each identifier depends on the kind of identifier that is written. This is a sample for a procedure:

 <Item kind="Procedure" id="1072660" modid="1E4EC40" link="1">

   <Name>AddDataModule</Name>

   <ClaScope>Private</ClaScope>

   <OwnerTypeID>1597A60</OwnerTypeID>

   <Calls>

     <Item id="CBA120"/>

   </Calls>

   <CalledBy>

     <Item id="CD0A40"/>

   </CalledBy>

 </Item>

The XML file also has a general section, describing the project, and a section for the todo items that are found in the project.

XSLT templates

Pascal Browser uses XSLT (XML Stylesheets) template files to create the documentation. XSLT is an XML-based language designed to transform one XML document into another. When Pascal Browser generates documentation, these templates are transformed with the XML information for the source code, producing documents. The documentation that is produced by the default templates has HTML format.

The default templates consist of nine primary templates:

The primary templates are processed first of all, and form the starting point for the rest of the documentation. Each of these templates produces a corresponding output file. This is done by transforming the XSLT stylesheet with the XML file. For example, SubprogIndex.xsl produces a SubprogIndex.htm file. The file extension is a setting that you can select in the Properties|Templates dialog box.

The names and numbers of these files are not fixed. You can create your own set of templates and use as many primary templates as you like.  You can also edit the contents of these templates (but you should work on copies in another folder so the original templates are not damaged).

For each major source code identifier included in a primary template, a new page is created, based on one of the following seven identifier templates:

If, for example, a page is produced for a function or a procedure, the identifier template Subprog.xsl will be applied.

The created document is given a file name on the format <ID>.htm, like 21FE672.htm where the number is a unique hexadecimal number for the identifier that is described in the document. In this document there may be links (URLs) to documents for other identifiers.

The names of the identifier templates are fixed, unlike the primary templates. But you are free to alter the contents of these identifier templates. As mentioned earlier, you should also in this case work on copies in another folder.

There are also some XSLT include files that are used both by the primary and identifier templates. You can also customize these files.

Images

Supplied with Pascal Browser is a collection of custom-tailored images (*.gif) files that you can use in your own documentation projects. Each image is available in three sizes, 16, 24 and 32 pixels. They are used by the default templates, and can be found in the C:\Documents and Settings\<acc>\My Documents\Pascal Browser\Templates\Default\Images folder.

"XX" in the file name should be substituted by "16", "24" or "32", depending on the size of the image.

This is about all you will ever want to know, if you just use Pascal Browser just as it is. But you can create your own set of templates, and produce totally different forms of documentation, like text files, RTF files, or even XML files.

See also:

Customization

Examples

How to use PAB.EXE
Introduction
Main window