Templates

Top  Previous  Next

 

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:

 

Home.xsl
Contents.xsl
Index.xsl
Overview.xsl
ClassIndex.xsl
IdentifierIndex.xsl
ModuleIndex.xsl
SubprogIndex.xsl
Settings.xsl

 

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:

 

Class.xsl
Constant.xsl
Interface.xsl
Module.xsl
Subprog.xsl
Type.xsl
Variable.xsl

 

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.

 

FooterInc.xsl
HeaderInc.xsl
ImageInc.xsl
InfoInc.xsl
TodoInc.xsl
ToolsInc.xsl

 

 

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.

 

 

Image

File name

Class_24        

Class_XX.gif

CodeBlock_24

Codeblock_XX.gif

Constant_24

Constant_XX.gif

Constructor_24

Constructor_XX.gif

Destructor_24

Destructor_XX.gif

Field_24

Field_XX.gif

Function_24

Function_XX.gif

Interface_24

Interface_XX.gif

Module_24

Module_XX.gif

Procedure_24

Procedure_XX.gif

Property_24

Property_XX.gif

Type_24

Type_XX.gif

Typed_Constant_24

Typed_Constant_XX.gif

Variable_24

Variable_XX.gif

 

"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: