Commands and Commentary

Commands and Commentary
←	Chapter 10. Documentation Generation	→

The documentation for template commands (messages) is extracted from the header comment of each template procedure.

Processing Commands

The module tcldumper.tcl only deals with the composite part of documenting the command. That is the command is searched inside the source code, the header comment extracted and the analyzed for its validity and additional DocBook tags.
The main function for this operation is the »describe« procedure inside the »dumper::docbook« namespace. describe is called from within the parser for each procedure inside the namespace under scrutiny.
Not every procedure however is an element of the template interface. To determine this is the function of the »isSkipped« procedure. »isSkipped« analyses the parameters of the command and assumes that the first argument must be »path« or »base« to qualify it as a template command.
In addition procedures starting with »get-« or »set-q« are assumed properties and thus skipped.
First »describe« formats the command signature, in particular the parameters.
»isDefaultParameter« is being deployed to test for predefined parameter values.
»isOpenArgumentList« is being used on the last argument, in order to determine whether it is an optional argument list. The term args defines a optional argument list in Tcl/Tk.
»describe« analyzes the commentary right after the processing the parameters. The commentary is broken into multiple paragraphs –using empty lines to separating the paragraphs.
Some DocBook tags are allowed inside the commentary. The tags must be non ambiguous in every part, most important: their end! »allowTags« is being used for parsing DocBook tags. These tags are carried over into the documentation. The implementation of »allowTags« is being given in Example 10.10, “allowTags”.
Example 10.10. allowTags
```
proc allowTags local {
   foreach keyword {
         <citation> </citation>
         <emphasis> </emphasis>
         <filename> </filename>
             <code> </code>
           <remark> </remark>
      <replaceable> </replaceable>
        <indexterm> </indexterm>
          <primary> </primary>
        <secondary> </secondary>
              <see> </see>
          <seealso> </seealso>
   } {
      regsub -all  "<" $keyword  "\\&lt\;" key
      regsub -all  ">" $key      "\\&gt\;" key
      regsub -all $key $local     $keyword local
   }
   return $local
}
```
»describe« preserves common entities . Hence, be careful when using & inside the commentary!
Entities are the easiest and best way to inject alien text into the documentation. For code examples there is an additional, automated reference mechanism.
Referencing examples operates on the DocBook directory or the template sub-directory. These directories are being searched for code files with the extension of the project.
Example 10.11. Referenced Examples
```
# Assume the command is: command1.
# The template is: foo.
< DocBook directory >
        command1.py
        command1.lisp
        command1.tcl
        < foo directory >
              command1.tcl
              command1.rb
              
```
In the Example 10.11, “Referenced Examples”, the foo/command1.tcl is being used for »tcl«-projects. The same example inside inside the DocBook directory is recessive to the more specific version inside the sub-directory foo.
The foo/command1.rb will be used for .rb (Ruby) projects.
The command1.py will be used for .py (Python) projects.
And final command1.lisp will be used for .lisp (Lisp) projects.
»describe« injects the complete example “as is” into the generated documentation. An language attribute is being added according to the return value of: vgfile::docbookLanguage.