Using InterSystems Documentation
Extending the Documentation
[Back] [Next]
   
Server:docs2
Instance:LATEST
User:UnknownUser
 
-
Go to:
Search:    

This chapter describes how to extend the online documentation system. There are two approaches:

Extending the Class Reference
You have the opportunity to add Class Reference comments each time you create a new item (such as a class, method, property, or query) using a Studio wizard. If you enter a block of text in the Description field of the wizard dialog, when you save your changes this text appears in the class in the lines immediately preceding the Class, Method, Property, or Query label. Studio inserts three slashes (///) at the far left of each line to indicate that it is a Class Reference comment.
Once you compile the class, you can view its generated class documentation the next time you open the Class Reference documentation. If you add no Class Reference comments, items that you add to a class or package appear appropriately in the lists of class or package contents, but without any explanatory text.
You can extend any existing Class Reference comments from within Studio, either by editing the Description field for a class in the Studio Inspector window, or by adding specially formatted lines to the class code. The syntax rules for Class Reference comments are strict:
If you add Class Reference comments using the Description field with a Studio wizard or in the Studio Inspector window, Studio handles these details for you. If you add Class Reference comments directly into the code, Studio alerts you to some Class Reference syntax errors: for example, if you insert a blank line between the comments and the declaration, or if you use an insufficient number of slashes at the beginning of a line within a Class Reference text block. However, Studio does not alert you to any other types of bad syntax within Class Reference comments.
Class Reference comments allow plain text, plus any standard HTML element and a small number of specialized elements, as shown in the following code sample:
/// <p>Transforms <i>Star</i> order messages for <i>ChartScript</i>. <br/>
/// Developed Nov 2004 by <b>MT Engineering Team</b>. <br/>
/// See also <class>StarADTtoChartScript</class> and
/// <class>StarMRGtoChartScript</class> </p>
/// <p>Only Orders for these Departments pass: </p>
/// <ul><li>CP</li><li>NS</li><li>URO</li><li>NIV</li></ul>
/// <p>As long as they are one of the following:</p>
/// <ol>
/// <li>New Child Order</li>
/// <li>Child Order Status Change</li>
/// <li>Order Cancellation</li>
/// </ol>
/// <p>Data Transformation sets "T" in MSH 11 for Test environment.</p>
Class MT.dt.StarORMtoChartScript
      Extends Ens.DataTransformDTL [ ProcedureBlock ]

{
  // The data transformation class code goes here.
}
The previous example formats the Class Reference entry for the class as follows:
With regard to the allowed HTML elements, adhere to as strict an HTML standard as you can, for example XHTML. This ensures that your comments can be interpreted by any browser. For a description of specialized Class Reference elements, such as <class>, <method>, <property>, <query>, <parameter>, <example>, and <link>, see the Class Reference for %CSP.Documatic.
Extending the Online Documentation
You can supplement the InterSystems online documentation system by adding technical articles to it. After you add them, readers can find these articles in any of the following ways:
Caution:
The DocBook database is replaced at each system upgrade. Therefore, any supplementary material you add must be reloaded each time the system is upgraded.
The DocBook Application
The DocBook application consists of a database (DOCBOOK), installed as part of the InterSystems product installation. The DOCBOOK database contains the executable code for the application as well as the product documentation stored as a set of persistent objects. The following diagram summarizes how DocBook application formats and displays this documentation.
Note the XML documents in this diagram. Members of the InterSystems Documentation department edit XML documents that conform to the DocBook v4.0 standard. These files serve as the input for the Caché XML DocBook Loader, which transforms the files into HTML that is visible using a Web browser. To add a technical article that can be referenced by the InterSystems online documentation system, you must simulate the InterSystems Documentation department work process by creating your own XML documents that conform to the DocBook v4.0 standard.
The DocBook Standard
DocBook is an OASIS standard that defines an XML-based markup language for technical documentation. The installation of any InterSystems server includes a copy of the DocBook v4.0 XML DTD. For details about DocBook v4.0 refer to:
Adding an Article to the Technical Articles
With a text editor, some knowledge, and something to say, you can easily create additional technical articles for inclusion within the InterSystems online documentation system. A specialized XML editor is helpful, but not necessary. Here is an XML document that defines an extremely simple article:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//Arbortext//DTD DocBook XML V4.0//EN"
"c:\cachesys\csp\docbook\doctypes\docbook\docbookx.dtd">
<article id="UMFA_MyFirstArticle" arch="intersystems">
  <title>My First Article</title>
  <subtitle>This document contains my first article.</subtitle>
  <para>This is my first article.</para>
</article>
This document contains the following:
  1. A required XML header.
  2. A required DTD specification indicating that this document is an article and identifying the location of the DTD file. Use the exact DOCTYPE statement shown in the example. The corresponding file need not exist on your system.
  3. An <article> element delimiting the contents of the article. Note the attributes provided in the example:
  4. A <title> and <subtitle> describing the article.
  5. A <para> (paragraph) containing the content of the article. A real article would probably have more than one paragraph.
  6. When you save this document, save it to a file with the same name as the article’s id. In this case: UMFA_MyFirstArticle.xml
To load a new document into the database, do the following:
  1. Create a new DocBook article, such as the one described in the previous section.
  2. Start the Terminal.
  3. Switch to the DOCBOOK namespace where the DocBook database application is located:
     ZN "DOCBOOK"
  4. Invoke the Load() method of the DocBook.Utils class using the full path and file name of your XML document. For example:
     Do ##class(DocBook.Utils).Load("C:\myDir\UMFA_MyFirstArticle.xml")
  5. Add your article to the global that the documentation home page uses to track names:
    Set ^DocBook.BookList("UMFA_MyFirstArticle", "book", "Articles") = ""
  6. Start the main Documentation page. From the array of topics, choose Articles. Your article is now included in the list.
UTF-8 Encoding Preferred
The DocBook application checks whether or not the source XML documents are encoded as UTF-8. That is, it looks at the XML header for the encoding attribute:
<?xml version="1.0" encoding="utf-8"?>
If the UTF-8 declaration is not present in the XML header, the application raises an assertion violation. This warning is not fatal; assuming there are no other, fatal errors, the document contents are properly loaded.
You can easily transform document sources that are not already in UTF-8 to that format using XSL.
Content Size Limitation
The text contents of any single DocBook element cannot consist of more than 30,000 characters.
If you use XML entities such as &amp; then each character in the entity reference counts toward the total. That is, &amp; contributes 5 characters, even though it is only visible in the display as one & character.
If you use inline elements for styling, the characters required for the inline element count as well. So, for example, the following <para> content consumes 46 characters:
<para>This is <emphasis>really</emphasis> important.</para>
Whereas in the displayed output it appears to consume only 25 characters, as in:
This is really important.
Removing an Article
To remove an article from the DOCBOOK database, start the Terminal, switch to the DOCBOOK namespace, and enter the following command:
 Do ##class(DocBook.Utils).RemoveArticle("DocBookId")
Where DocBookId is the id value for this article; see the previous section.
For example:
 Do ##class(DocBook.Utils).RemoveArticle("UMFA_MyFirstArticle")
Using DocBook Elements
If you would like to create an article that is more useful than the simple example in the previous section, you can use more DocBook elements within the body of the article. The following topics describe some of the more commonly used elements:
For a list of all the DocBook elements that you can use when adding an article to the InterSystems online documentation, see All Supported DocBook Elements at the end of this section.
Sections
You can include sections and subsections using the <sect1>, <sect2>, <sect3>, and <sect4> elements. These must be nested correctly. Indentation is optional, but helps to show the nesting relationships between elements:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//Arbortext//DTD DocBook XML V4.0//EN"
"c:\cachesys\csp\docbook\doctypes\docbook\docbookx.dtd">
<article id="UMFA_MyFirstArticle" arch="intersystems">
  <title>My First Article</title>
  <subtitle>This document contains my first article.</subtitle>
  <para>This is my first article.</para>
  <sect1>
    <title>This is Section 1</title>
    <sect2>
      <title>This is SubSection 1-A</title>
      <para>Text</para>
    </sect2>
  </sect1>
  <sect1>
    <title>This is Section 2</title>
    <sect2>
      <title>This is SubSection 2-A</title>
      <para>Text</para>
    </sect2>
  </sect1>
</article>
You can simply avoid assigning id values to any section element other than the top level <article> element. However, if you are an experienced DocBook user and wish to use a more advanced element such as <link> to provide internal cross-references to sections within your article, you can do so by establishing an id value for the section and using this as the linkend value in the <link> element.
Keep in mind that the DocBook application requires all id values within the same <article> to stem from the <article> id value. This stem must be identical to the XML source file name. To pull all of these requirements together, consider the following sample article.
Because of its <article> id value, this example must reside in the file UMFA.xml. Note the <article> id value, the <sect2> id value, and the <link> linkend value:
<?xml version="1.0" encoding="utf-8"?>
<!DOCTYPE article PUBLIC "-//Arbortext//DTD DocBook XML V4.0//EN"
"c:\cachesys\csp\docbook\doctypes\docbook\docbookx.dtd">
<article id="UMFA" arch="intersystems">
  <title>My First Article</title>
  <subtitle>This document contains my first article.</subtitle>
  <para>This is my first article.</para>
  <sect1>
    <title>This is Section 1</title>
    <sect2 id="UMFA_Critical_Info">
      <title>This is SubSection 1-A</title>
      <para>Text</para>
    </sect2>
  </sect1>
  <sect1>
    <title>This is Section 2</title>
    <sect2>
      <title>This is SubSection 2-A</title>
      <para>Text</para>
      <para>
        Also see <link linkend="UMFA_Critical_Info">SubSection 1-A</link>
      </para>
    </sect2>
  </sect1>
</article>
Lists
You can create ordered lists:
<orderedlist>
  <listitem><para>Item</para></listitem>
  <listitem><para>Another Item</para></listitem>
</orderedlist>
As well as unordered (itemized) lists:
<itemizedlist>
  <listitem><para>Item</para></listitem>
  <listitem><para>Another Item</para></listitem>
</itemizedlist>
Note that you must place a <para> (or other block) element within the <listitem> element. You can include multiple blocks within a <listitem> if you like.
Program Listings
You can use a program listing block if you want to display sample code:
<programlisting> Write "Hello"</programlisting>
The DocBook application renders this as a code listing.
You can syntax check and colorize your example by setting the lang attribute:
<programlisting lang="COS"> Write "Hello"</programlisting>
The available lang attribute values for <programlisting> include:
lang Value Language
BAS Caché Basic
CLS Caché Class Definition Syntax
CLS!MEMBER A member (property, method, etc.) of a Caché Class Definition
COS Caché ObjectScript. ObjectScript examples need at least one space character at the beginning of each line to be syntactically correct.
CSP CSP text
JAVA A complete Java class definition.
JAVA!SCRIPT JavaScript. No syntax checking or colorization is done.
NONE This indicates that no syntax checking should be done on the example. Either the material has a deliberate error in it to illustrate a point, or it is incomplete as a program unit.
SQL An SQL statement
XML XML
XML!FRAGMENT A well-formed, but not necessarily complete, piece of XML
The maximum length for any single line inside any <programlisting> block is 81 characters. This count includes the characters that comprise the <programlisting> and </programlisting> elements. To reduce the character count in the first or last lines of your example, you can place these elements on lines by themselves, as in the following example:
<programlisting lang="COS">
 Write "Hello! This maximum length includes one leading space for ObjectScript."
</programlisting>
Tables
The DocBook application supports simple tables defined using either <table> or <informaltable>. The only difference is that <informaltable> has no title.
<informaltable frame="all">
  <tgroup cols="2">
    <colspec colnum="1" colname="Param" />
    <colspec colnum="2" colname="Descrip" />
    <thead>
      <row>
        <entry colname="Param">Parameter</entry>
        <entry colname="Descrip">Description</entry>
      </row>
    </thead>
    <tbody>
      <row>
        <entry>X</entry>
        <entry>The X location.</entry>
      </row>
      <row>
        <entry>Y</entry>
        <entry>The Y location.</entry>
      </row>
    </tbody>
  </tgroup>
</informaltable>
Inline Elements
Inside a paragraph or table entry, you can highlight words or phrases using a variety of inline elements. Those most common of these include:
Element Description Example
<classname> The name of a class The %CSP.Page class
<command> The name of a program or other operating system command The UNIX® rm command
<emphasis> Italicized text This is really important
<filename> The name of a file The Main.html file
<function> The name of a function Use the $Data function
<guibutton> A button within a GUI Press the OK button
<guilabel> A label within a GUI Enter this in the Name field
<guimenu> A menu within a GUI Available within the File menu
<guimenuitem> An item within a menu Within this menu, use the Save command
<methodname> A method name The Print method
<property> A property name The Name property
<quote> A quotation This documentation is “easy” to understand
<superscript> A superscript ab
<systemitem> A security-related item such as the name of a privilege You need %DB_DOCBOOK:Read to access DocBook
<varname> A variable or argument name count specifies the number of iterations
<userinput> User input Enter Hang 100 from the command line
All Supported DocBook Elements
The following table lists all the DocBook elements that you could possibly use when adding an article to the InterSystems online documentation. For ease of reading, this table omits the surrounding angle brackets for each element: <abstract>, <anchor>, etc.
The following list is more than ample for writing technical articles. For the limited set of truly useful elements, return to the overview at the beginning of Using DocBook Elements.”
Index Supported Elements
A abstract, anchor, answer, appendix, application, article
B book, bookinfo
C caution, chapter, citation, citetitle, classname, colspec, command
D  
E emphasis, entry, envar, errorcode, errorname, example
F figure, filename, firstterm, formalpara, function
G glossary, glossdef, glossentry, glosslist, glosssee, glossterm, graphic, guibutton, guiicon, guilabel, guimenu, guimenuitem, guisubmenu
H  
I important, indexterm, informaltable, inlinegraphic, itemizedlist
J  
K keycap, keycode
L link, listitem, literal, literallayout
M methodname
N note
O orderedlist
P para, part, partintro, preface, primary, productname, programlisting, prompt, property
Q qandadiv, qandaentry, qandaset, question, quote
R refdescriptor, refentry, refentrytitle, reference, refmeta, refname, refnamediv, refpurpose, refsect1, refsect2, refsect3, refsect4, refsynopsisdiv, remark, row
S secondary, sect1, sect2, sect3, sect4, see, seealso, set, subscript, subtitle, superscript, synopsis, systemitem
T table, tbody, term, tertiary, tgroup, thead, tip, title, type
U ulink, userinput
V varname
W warning
X  
Y  
Z  
Troubleshooting DocBook Syntax
The DocBook DTD is strict. If your DocBook documents are not valid, you will get long error messages from the Caché XML (SAX) validator. Fortunately, these error messages include a line number and column offset within the original source file to help you to find the source of the problem.
Interpreting Error Messages from the Parser
To illustrate the kind of information generated, suppose we modify a valid XML document by inserting the tag <AnErroneousTag SomeAttribute="AValue"> just prior to a closing </para> tag, with each of these modified tags now appearing on a line by itself:
<para>
I have quite a lot to say.
<AnErroneousTag SomeAttribute="AValue">
</para>
The attempt to load this document into the database fails and generates the following error messages. Each error message actually appears as a single line of output, but this display introduces line breaks to improve readability:
SAX Error (a document could not be loaded):
Unknown element 'AnErroneousTag'
in A:\Parser\Example\source.xml at line 357 offset 16
SAX Error (a document could not be loaded):
Attribute 'SomeAttribute' is not declared for element 'AnErroneousTag'
in A:\Parser\Example\source.xml at line 357 offset 31
DocBook Parser Assertion Failure:
Unsupported tag: <AnErroneousTag>
at line 357 offset 40
SAX Fatal Error (a document could not be loaded):
Expected end of tag 'AnErroneousTag'
in A:\Parser\Example\source.xml at line 359 offset 7
ERROR #6301: SAX XML Parser Error:
Expected end of tag 'AnErroneousTag'
in A:\Parser\Example\source.xml at line 359 offset 7
This single error has generated multiple messages to the log. This is not uncommon. The format of an XML document is strictly specified by its document type description, in this case, the DocBook DTD. An error that invalidates the document often runs afoul of multiple constraints in the DTD. Each of these is reported, along with descriptive information about the error and its location, in order of occurrence. The previous set of messages indicates the following problems:
Remember that the location reported in the error message is the place where the error is detected. This may not be the place where the error actually occurred. Sometimes a missing end-element tag is not detected until much later in the parsing operation, because the markup which would have followed the closing element could also logically be permitted within the element itself. A working knowledge of the DocBook DTD and the intended structure of the document are indispensable to quickly identify this class of mistakes.
Enabling the DocBookParser Trace Capability
The DocBook.DocBookParser class provide trace information to the Terminal log about what happens during the analysis of the document. To enable tracing, set the global ^DocBook.Config("TRACE") to a nonzero value in the DOCBOOK namespace. For example:
USER>znspace "DOCBOOK"

DOCBOOK>set ^DocBook.Config("TRACE")=23

DOCBOOK>zwrite ^DocBook.Config("TRACE")
^DocBook.Config("TRACE")=23

DOCBOOK>
The value is interpreted as a bit mask indicating the actions for which actions to produce trace output. The bit values and their associated actions are:
Bit Value Associated Action
1 Trace the occurrence of start elements; that is, <StartElement>.
2 Trace the occurrence of end elements; that is, </StartElement>.
4 Produce information when an entity is recognized.
8 Indicate when the parser has finished scanning an entity.
16 Display markup and text information which is ignored during the parse.
32 Show the text scanned for block element content.
64 Display progress bars during certain internal operations.
Thus, a value of 23 for ^DocBook.Config("TRACE") indicates 1+2+4+16=23. That means to trace output for beginning (1) and ending (2) elements, for entities found (4), and for any material in the document which is ignored (16).