Imports, Includes and Examples
Imports and Includes provide a particular challenge for documentation, because an imported document could include another imported document, making for very deep structures. Handling this proved something of a challenge, but the key came when I realized that the display of a page could be handled by converting a matched root template into a named template, then passing the stylesheet as an argument to this named template. By doing this, you can use the XSLT document() function to read the stylesheet given in the href attribute of a <?XML:NAMESPACE PREFIX = XSL /><XSL:IMPORT>or <XSL:INCLUDE>command and apply the named stylesheet to it directly.
One consequence of this is that you turn a linear process into a recursive one-a document will pass its own imports and includes into the same named template, and as a consequence the document that draws the initial page will also be used to draw any subordinate pages. Because the initial calling page may lack some filename context (i.e., unless explicitly given in a <?XML:NAMESPACE PREFIX = DOC /><DOC:FILENAME>element, there is no way for a document to know its own name) the named template that draws the page (displayPage) has a parameter called $isRootPage that is set to "yes" for the primary documentation page, and "no" for any subordinate pages.
If a document contains an imported or included file, initially only the name of the file will be displayed as a header element. If you click on this header, though, you can expand the documentation for the subordinate document (and can likewise expand any subsidiary imports in the first imported document).
Sometimes explicit examples help clarify documentation. The <DOC:EXAMPLE>node serves this purpose. The documentation XSLT template treats the contents of the <DOC:EXAMPLE>node as XHTML for output to the documentation routine. You can thus include both sample code and outputs. Each example will be displayed with an explicit header. </DOC:EXAMPLE></DOC:EXAMPLE>