Customization

You can customize how the resulting documentation is generated. There are different levels of customization possible, ranging from very easy to advanced. It helps if you have some knowledge in these areas:

The customization levels are:

Level 1

Change the CSS style sheet that is used for the default HTML documentation. This file is in the templates folder. By editing this file you can change fonts, background colors and similar items. This is the easiest form of customization.

Level 2

Edit the XSLT parimary and identifier template files (medium difficult)

Level 3

Create your own set of XSLT files as primary templates (most difficult)

Pascal Browser creates the documentation files, normally a set of HTML files, by following this process:

1. The source code is parsed, interpreted, and information is collected about all identifiers.

2. An XML structure is created from this information.

3. For every primary template, Pascal Browser produces a corresponding file. For example, Index.xsl leads to the new file Index.htm. The new file is created by XSLT transformation, where the XSLT template is ”merged” with the XML data producing some output.

4. The resulting output file may contain links to other HTML pages. For example if the Start.htm files contain links to the units MyUnitA and MyUnitB, two new pages are created for these units. The identifier template Module.xsl is applied to create these pages, which will get names like 1EF25.htm and 33EA28.htm. This numeric name is used to ensure that two pages get unique names. These pages can themselves contain references to other identifiers, and so, pages are created for these identifiers as well. This process continues until all pages have been created.

Remember, if you plan to create your own templates, a recommended practice is to first make a copy of the default templates. Place these templates in your own template folder and start editing and/or create your own files.

In case you should damage the contents of the default templates, you will have to rerun the installation program to restore them.

Pascal Browser also applies some special processing before and after the XSLT transformation. Some special magic words are substituted with actual values. Most of the contents for the documentation is loaded directly from the XML structure, but some is generated “on-the-fly”. The reason is that it is not practical to store everything in the XML structure, like source-code listings.

PAB achieves this with so-called “magic words”. Those magic words are written in the XSL files on the format

{#MagicWord}

For example, the magic word {#AllModCallsHier} will be substituted with a module call hierarchy list.

You can use these magic words in your own templates. One category of these magic words start with the string “self”, like

{#selfID}

These magic words all refer to the active object that the template is currently applied to. At runtime these magic words will be substituted with values for the active object.

This is a list of all valid magic words (non-case-sensitive) in alphabetical order, and a description of their actions.

{#AllModCallsHier}

This word is substituted for a complete module call hierarchy, showing all modules. This word can be used in any template page.

Sample:

{#CallsHier}

This word is substituted for a call hierarchy for the current subprogram.

The word can only be used in Subprog.xsl.

Sample:

{#CalledByHier}

This word is substituted for a called-by hierarchy for the current subprogram.

The word can only be used in Subprog.xsl.

Sample:

{#DfmHier}

This word is substituted for a hierarchical listing of the DFM objects for the current form class. The word can only be used in Class.xsl.

Sample:

{#DocName}

This word is substituted for the current document file name, e.g. “342877.htm”

{#DocPath}

This word is substituted for the complete path to the document file, e.g. “C:\Output\MyProj\342877.htm”

{#DownHier}

This word is substituted for a downward class hierarchy for the current class. The word can only be used in Class.xsl.

{#Fin}

This word is substituted for the source code for the finalization section of the unit, and can only be used in Module.xsl

{#FullUpHier}

This word is substituted for a full upward class hierarchy for the current class. The word can only be used in Class.xsl.

{#IdName}

This word is substituted for the name of the current identifier.

{#Init}

This word is substituted for the source code for the initialization section of the unit, and can only be used n Module.xsl.

{#MainCode}

This word is substituted for the source code for the main code of the unit, and can only be used in Module.xsl

{#ModCalledByHier[x]}

where x is a number 0-9.

This word is substituted for a module call hierarchy for the current module, which shows the modules that call the current module.

The keyword can only be used in Module.xsl. If x=0, then the entire complete hierarchy is shown, otherwise only the number of levels given by x.    

Sample:

{#ModCallsHier[x]}

where x is a number 0-9.

This word is substituted for a module call hierarchy for the current module, which shows the modules called by the current module.

The keyword can only be used in Module.xsl. If x=0, then the entire complete hierarchy is shown, otherwise only the number of levels given by x.  

Sample:

{#selfHasSource}

This returns “1” or “0” depending on if the current identifier has any source code or not.

{#selfID}

This word is substituted with the ID for the current object.

{#Template}

This word is substituted for the name of the template file that is used for the document file, e.g. "Module.xsl".

{#TotalHier}

This word is substituted for a class hierarchy for all classes. The word can be used in any page.

Sample:

{#UpHier}

This word is substituted for an upward class hierarchy for the current class. The word can only be used in Class.xsl.

{#UpDownHier}

This word is substituted for an upward and downward class hierarchy for the current class. The word can only be used in Class.xsl.

Sample:

Special tags for comments

Comments in source code can also be used with special tags:

<#IMG> Insert an image

Example:

 // <#IMG>"Images/PAB_16.gif" ALT="bla" TITLE="MyTitle"</#IMG>

Result:

The image will be inserted in the resulting HTML code

<#CODE> Format a code block

Example:

 // <#CODE>

 // procedure TheProc;

 // var

 //   I : integer;

 // begin

 //   MyProc(I);

 // end;

 // </#CODE>

Result:

The code block will be syntax formatted in the HTML page

<#URLA>/<#URLB> Insert a hyperlink (URL)

Example:

 // <#URLA>"http://www.peganza.com" TARGET="_blank"</#URLA><#URLB>Peganza</#URLB>

Result:

The URL will be inserted as a hyperlink in the HTML page

See also:

Templates

Examples

How to use PAB.EXE
Introduction
Main window