Creating Documents
← Chapter 9. Documentation →

Creating Documents

Standard Properties
Specific Properties
Commands (Messages)
Modules
Packages

A Runtime Library based template is defined through its window hierarchy, messages and properties.

The template interface is constituted by properties and commands –messages send to the window. A Refentry is a collection of lists, describing the interface. There is a »variablelist« for standard properties, the common properties in Tk-windows. There is a »variablelist« for template specific properties, and a »variablelist« describing the commands, provided by a template window.

All these interface elements, have their distinct implementation. A property is just an entry inside the attributes variable. While a command is commonly implemented through a Tcl/Tk procedure.

Consequently, the documentation for a property cannot be done inside the Tcl-source code. Whereas a comment may suffice to document a command.

Form-Feed in Emacs

There is an often repeated key-sequence in this document ^L. This is Emacs representation for »form-feed«. It is a single white space character created by the keyboard sequence Control-Q+ Control-L.

This document uses »-« to construct separator lines. The original character is: »―« HORIZONTAL BAR, unicode 2015 (a single byte unicode character) producing a smooth line.

Standard Properties

Standard properties occur frequently in an interface. The standard properties are listed inside the Tcl/Tk »options« man page. Jeszra recognizes standard properties and generates the documentation accordingly.

Specific Properties

Specific properties are unique for the template. For example Example 9.5, “Property activestyle.xml” is unique for a »listbox« window. Every specific property must be documented.

When a XML-file named like the specific property, was located inside the DocBook directory or a sub-directory thereof –the sub-directory must be named after the template–, then Jeszra assumes that these file contains the description for the specific property.

Example 9.5. Property activestyle.xml

               
  <varlistentry>
    <term>Command-Line Name:
      <emphasis>-activeStyle</emphasis></term>
    <term>Database Name:
      <emphasis>activeStyle</emphasis></term>
                <term>Database Class;
      <emphasis>ActiveStyle</emphasis></term>
    <listitem>
      
      <!-- Taken from the Tk-manpage: listbox -->
      
      <para>
        Specifies the style in which to draw the
        active element. This must be one of dotbox
        (show a focus ring around the active
        element), none (no special indication of
        active element) or underline (underline
        the active element). The default is
        underline.
      </para>
    </listitem>
  </varlistentry>

Example 9.6. ... XAE activestyle.xml Comments

               <!-- 
Local Variables:
mode: xae
coding: utf-8-unix
sgml-indent-step: 2
sgml-indent-data: t
sgml-set-face: t
sgml-parent-document: ("refeygistbox.xml"
                       "variablelist" )
sgml-insert-missing-element-comment: nil
End:
-->

The »varlistentry« inside of Example 9.5, “Property activestyle.xml” is then referenced as an »entity« from the generated gistbox refentry document. Gistbox contains a specific property activeStyle and activeStyle is a common property shared by all listbox-type windows.

Example 9.7. Emacs Skeleton for »activeStyle«

(define-skeleton x-manual-property 
  "man property expansion"
  "Property Name :"
  > "<varlistentry>" \n
  > "<term>Command-Line Name: <emphasis>-" str 
    "</emphasis></term>" \n
  > "<term>Database Name:  <emphasis>" str 
    "</emphasis></term>" \n
  > "<term>Database Class; "
    "<emphasis>-</emphasis></term>" \n
  > "<listitem><para>" \n
  >     _ "</para></listitem>" \n
  > "</varlistentry>" \n
"<!--" \n
"Local Variables:" \n
"mode: xae" \n
"fill-column: 62" \n
"coding: utf-8-unix" \n
"sgml-indent-step: 2" \n
"sgml-indent-data: t" \n
"sgml-set-face: t" \n
"sgml-parent-document: (\"" 
( "Parent Document : " str 
    (signal 'quit 'recursive) ) 
resume: 
".xml\" \"variablelist\" )" \n
"sgml-insert-missing-element-comment: nil" \n
"End:" \n
"-->")

A property definition inside the DocBook directory is globally visible. The same definition inside a sub-directory named identical with the template is only visible for documenting this particular template.

The global definition is recessive to the template specific one.

Parts of the template interface are directly definable in Jeszra.

Figure 9.1. Template Interface Page


Jeszra DocBook Preferences

Jeszra only asks for property descriptions, after activating the DocBook editor in the Figure 9.2, “Advanced Preferences” page.

Figure 9.2. Advanced Preferences


Figure 9.1, “Template Interface Page” displays a filtered excerpt from the Gistbox template. The displayed properties originate from the »base« window and are mapped into the Gistbox template interface. The modifiable part (right side) receives the template specifc name, under which the property will be accessed through the interface.

Inspector Filters

Figure 9.3. Local Filter


The screen-shot Figure 9.1, “Template Interface Page” is locally filtered. The »Local Filter« dialog is available from the Inspector menu to the right side.

The filters preferences are being used in addition to the local filter dialog!

There is an advanced setting inside the second preference page (under Working, Advanced), which tells Jeszra to query for a DocBook description for every new property. A dialog may be displayed asking for the description after activating this checkbutton.

Figure 9.4. Interface DocBook Editor


The description is then stored under the indicated DocBook directory. Jeszra detects the prior storerd description while creating a refentry in the same directory.

Figure 9.5. DocBook Browser


Jeszra reuses the last selected DocBook directory to localize other descriptions. Jeszra prompts a dialog to ask for a new description, when no previous description were found.

Commands are documented from the Tcl-source code. The header comment from the implementing proc will be used to document that command.

Each header comment must have the same structure, to allow its extraction.

Example 9.8. Proc Commentary

^L
# Function    : template::sample
# ----
# Returns     : 
# Parameters  : base -
#               para - 
#               parb - 
#               
# Description : 
# Written     : 07/02/2008, Roger
# ----
proc template::sample { base para parb } {}

These Example 9.8, “Proc Commentary” is generated within Emacs through a Example 9.9, “Emacs Skeleton for »proc«”.

Example 9.9. Emacs Skeleton for »proc«

(define-skeleton t-proc 
  "proc expansion" "proc name: " "^L\n"
  "# Function    : " str \n
  "# ----\n"
  "# Returns     : \n# Parameters  : "
	("Parameter, %s: " str 
   '(setq v1 (concat v1 " " str)) 
  " - \n#               ")
	"\n# Description : \n# Written     : "
  (format-time-string "%m/%d/%Y" 
        (current-time))
  ", " (getenv "USER") ?\n
  "# ----\n"
  "proc " str " {" v1 " } {" _ "}")

;; The abbreviation for Tcl-Mode
(define-abbrev tcl-mode-abbrev-table
  "proc" "" 't-proc)

I frequently use skeletons in Emacs : Here is the skeleton to create Example 9.10, “Emacs Skeleton for DocBook »example«”.

Example 9.10. Emacs Skeleton for DocBook »example«

(define-skeleton x-example "Example expansion"
  "Title :"
  > "<example>" \n
  > "<title>" str "</title>" \n
  > "<programlisting>" _ "</programlisting>" \n
  > "</example>")

;; And the abbreviation for the XAE Mode
(define-abbrev xae-mode-abbrev-table "ex" "" 
  'x-example)

These skeleton generates an DocBook example node, as shown in Example 9.11, “»example« used in DocBook”:

Example 9.11. »example« used in DocBook

<example id="headercomment">
   <title>Header Comment</title>
   <programlisting></programlisting>
</example>

Jeszra extracts a module description from the template file. The module description follows the general DocBook generation rules and works similar to the documentation of commands.

Example 9.12. Template Description

...
# Description : 
# The »rtl_combobox« command
# creates a »rtl_combobox« window.
...

^L

In Example 9.12, “Template Description” the term »Description: « is searched for and every text till the first empty line or »^L« treated as documentation.

Example 9.13. Generated XML

    <!-- Window description -->
    <refsect1>
      <title>Description</title>
    ...

      <!-- Special description, not universal -->
      <para>
The »rtl_combobox« command
creates a »rtl_combobox« window.
</para>

Most likely the module documentation, extracted from the source code, will not suffice. Jeszra looks inside the general DocBook directory for a sub-directory, dedicated to the template, and inside of this sub-directory for the module description.

The external module description is dominant to the one inside the source code.

Example 9.14. rtl_tree module Description

DocBook directory
  rtl_tree
     rtl_tree.xml

Example 9.14, “rtl_tree module Description” shows the referenced rtl_tree description. The contents of this description is a slightly modified version extracted from the source code. The main changes are screen-shots, and better formatted lists.

Alternative, hand-written DocBook elements can be introduced into the source code, which are recognized by the document extraction . This can be accomplished through entities inside the source code comment. Be aware, that the entity must have been defined inside the master DocBook document. The same mechanism can be used for commands, too.

Example 9.15. Injecting DocBook during Extraction

# Description : 
# This is a simple comment,
# which contains an entity:
# &entitychapter;.

Example 9.16. Entity Definition

...
<!-- Referenced parts. -->
<!ENTITY entitychapter SYSTEM  "my-hand-written.xml">
...

Be aware: that the entity in Example 9.15, “Injecting DocBook during Extraction” will be enclosed in a »para« block: 

<para>...
&entitychapter;
.</para>

The module will be parsed for »package require« statements, and all found packages are listed inside the dependencies section.

Example 9.17. Dependencies

<!-- Generated by Jeszra,
     based on package require * -->
<refsect1>
   <title>Dependencies</title>
   <itemizedlist>

   <listitem><para>rtl</para></listitem>
   <listitem><para>rtl_images</para></listitem>
   <listitem><para>rtl_gridwin</para></listitem>
   </itemizedlist>
</refsect1>

Example 9.17, “Dependencies” will look like:

  • rtl

  • rtl_images

  • rtl_gridwin

← ↖ →
DocBook ↑ Multi Language Documentation
SourceForge Logo

Copyright © 2009–2010 Arndt Roger Schneider