Tcl Library Source Code

Documentation
Login
EuroTcl/OpenACS 11 - 12 JULY 2024, VIENNA


[ Main Table Of Contents | Table Of Contents | Keyword Index | Categories | Modules | Applications ]

NAME

tepam::doc_gen - TEPAM DOC Generation, reference manual

Table Of Contents

SYNOPSIS

package require Tcl 8.5 9
package require tepam 0.5
package require tepam::doc_gen ?0.1.2?

tepam::doc_gen::generate ?-format format? ?-style style? ?-header_footer? ?-dest_file dest_file? name
tepam::doc_gen::patch ?-format format? ?-style style? ?-search_pattern search_pattern? ?-src_string src_string | -src_file src_file? ?-dest_file dest_file? ?name?

DESCRIPTION

This package generates documentations of TEPAM procedures (procedures that have been declared with tepam::procedure). The documents are generated in the classic UNIX document style using the following document sections: Name, Synopsis, Description, Arguments and Example. TEPAM Doc Gen provides support for various document formats. Support for additional formats can be added if necessary.

The TEPAM Doc Gen package provides the following commands:

ARGUMENTS

PREDEFINED DOCUMENT FORMATS

TEPAM Doc Gen pre-defines the following document formats:

TXT - Text format

The documentation will be generated in a simple text format if this format is selected. The format can be customized via the following variable:

HTML - HTML format

TEPAM Doc Gen generates CSS styled HTML files. The HTML documentation can be customized via the following variable:

The CSS stylesheet can be customized to change the documentation formatting. A good starting point to create a customized CSS stylesheet is to use the CSS file provided by the TEPAM Doc Gen example/demo. The HTML documentation uses the following CSS class styles:

POD - Perl document format

The documentation is generated in the Perl Plain Old Documentation format (PerlPOD) if this format is selected.

DT - TclLib DocTools format

The documentation is generated in the Tcllib DocTools format if this format is selected.

ADDING SUPPORT FOR NEW DOCUMENT FORMATS

Support for a new document format can be added by defining in the tepam::doc_gen namespace a set of procedures that generate the different document components.

The following documentation listing contains tokens that refer to the different document generation procedures:

      <01>
 <03> <20s> NAME*<20e>*
      <30s> message_box - Displays text in a message box*<30e>*
      <20s> SYNOPSYS*<20e>*
      <40s> message_box [-mtype ] <40e>
      <20s> DESCRIPTION*<20e>*
      <21s> message_box<21e>
      <54s> message_box [-mtype ] <54e>
      <50s> This procedure allows displaying a text in an message box. The following
           ** message types are supported:<50e>
 <51> <53s> * Info*<53e>*
      <53s> * Warning*<53e>*
      <53s> * Error*<53e>* <52>
      <50s> If the text parameter is use multiple times the different texts are
           ** concatenated to create the message text.<50e>
      <20s> ARGUMENTS*<20e>*
 <60> <62s> [-mtype ]<62e>
 <63> <65s> Message type*<65e>*
      <66s> Default: "Warning"<66e>
      <66s> Multiple: yes*<66e>*
      <66s> Choices: Info, Warning, Error*<66e>* <64>
      <62s> <62e>
 <63> <65s> One or multiple text lines to display*<65e>*
      <66s> Type: string*<66e>*
      <66s> Multiple: yes*<66e>* <64><61>
      <20s> EXAMPLE*<20e>*
 <70> <72s> message_box "Please save first the document"<72e>
      <73s> -> 1*<73e>* <71><04>
      <02>

There are 2 types of document generation procedures:

The following set of procedures needs to be defined to provide support for a new document format:

gen(TXT,ArgumentString) mtype 1 0 string -> "[mtype]"

  * *IsNamed*

    If true \(=__1__\) an argument is a named argument \(option\)\. The
    generated string should in this case contain the argument/option name,
    followed by the argument itself:

gen(TXT,ArgumentString) mtype 0 1 string -> "-mtype "

    Named arguments can also be optional:

gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype ]"

  * *Type*

    Indicates the type of the argument\. If the type is set to __none__
    the argument is a flag, which needs to be indicated by the generated
    string\. Example:

gen(TXT,ArgumentString) close 1 1 none -> "[-close]"

EXAMPLES

tepam::doc_gen::generate

The TEPAM Doc Gen package can be explored by generating the documentation of the command tepam::doc_gen::generate. The following example generates the document in text format (default format):

tepam::doc_gen::generate tepam::doc_gen::generate

The next example generates the documentation in HTML format:

tepam::doc_gen::generate -format HTML tepam::doc_gen::generate

The flag ?header_footer? adds also the file header and footer:

tepam::doc_gen::generate -format HTML -header_footer tepam::doc_gen::generate

The documentation can directly be stored in a file. The file header and footer are automatically generated in this way:

tepam::doc_gen::generate -format HTML -dest_file doc_gen.html tepam::doc_gen::generate

The generated HTML file refers a CSS stylesheet file (default: tepam_doc_stylesheet.css). To display the HTML file correctly this CSS stylesheet file needs to be copied into the directory of the generated HTML file.

The Tcl DOC Tools format can be used as intermediate format to generate other formats, for example HTML:

# Generate the documentation in Tcl Doc Tool format
set dt [tepam::doc_gen::generate -format DT -header_footer tepam::doc_gen::generate]
**
# Create a new doc tools object (HTML format)
package require doctools
::doctools::new myDoc -format html
**
# Open the HTML file, and write the HTML formatted documentation
set fHtml [open doc_gen.dt.html w]
puts $fHtml [myDoc format $dt]
close $fHtml

tepam::doc_gen::patch

While generate provides a limited number of possibilities to vary the document structure, patch offers more flexibility. Multiple documentations for different procedures and meta information can for example be added.

The following listing shows how the patch command works. It defines first a HTML master document string that contains 2 procedure documentation placeholders ({**}). There placeholders are replaced by patch with the generated documentation of the referred procedures. Since nonstandard placeholders are used, patch is called with an explicit placeholder pattern definition (argument search_pattern).

# Define the HTML master document
set HtmlMasterDoc {\

  
    tepam::doc_gen
    
    
  
  
    

tepam::doc_gen


      

Generate


{*tepam::doc_gen::generate*}
      

Patch


{*tepam::doc_gen::patch*}
  
\
}
**
# Patch the master document: This will replace the placeholders by the *
*# procedure documentation divisions:

tepam::doc_gen::patch -format HTML -search_pattern {\{\*(.*?)\*\}} \
                      -src_string $HtmlMasterDoc -dest_file tepam_doc_gen.html

SEE ALSO

tepam(n), tepam::procedure(n)

KEYWORDS

automatic documentation, documentation, procedure documentation

CATEGORY

Documentation tools

COPYRIGHT

Copyright © 2013, Andreas Drollinger