Provided by: tcllib_1.21+dfsg-1_all bug

NAME

       tepam::doc_gen - TEPAM DOC Generation, reference manual

SYNOPSIS

       package require Tcl  8.3

       package require tepam  0.5

       package require tepam::doc_gen  ?0.1?

       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:

       tepam::doc_gen::generate  ?-format  format?  ?-style  style?  ?-header_footer? ?-dest_file
       dest_file? name
              This command generates the documentation for a specified procedure (name) in one of
              the  supported  formats  (TXT,  HTML,  POD (Perl Doc), DT (TclLib DocTool), or in a
              custom  specific  format.  The  format  is  specified  via   ?format?.   The   flag
              ?-header_footer?  adds  to the documentation file header and footer. If ?dest_file?
              is specified the documentation is stored in a file (the file header and footer  are
              added  automatically  in  this  case)  and the file name is returned. Otherwise the
              documentation string is returned by generate.

       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?
              This  command  inserts procedure documentations into an existing master document at
              the locations indicated by insertion placeholders which are matching the pattern of
              ?search_pattern?.  The  existing  master document is either provided as data to the
              argument (?src_string?) or via a file (?src_file?). The final document is  returned
              by  patch  if no destination file is defined (?dest_file?). Otherwise, the document
              is stored in the specified file, and the  number  of  insertion  placeholders  that
              could be handled successfully is returned.

              Any  insertion  placeholders  of  the  master  document  are handled by default. By
              defining the argument ?name? the documentation insertion will be  restricted  to  a
              particular procedure.

ARGUMENTS

       ?-format format?
              Specifies  the  documentation  format.  TEPAM  Doc  Gen  provides  support  for the
              following formats:

              •      TXT - Text format (default)

              •      HTML

              •      POD - Perl Plain Old Documentation format (PerlPOD)

              •      DT - TclLib DocTool format

              Section ADDING SUPPORT FOR NEW DOCUMENT FORMATS shows how  support  for  additional
              formats can be added.

       ?-style style?
              The  documentation  is  by  default  generated in Tcl style (e.g. command arg1 arg2
              ...). C-style documentation can be generated by setting this argument to 'C'  (e.g.
              command(arg1,arg2,...)).

       ?-dest_file dest_file?
              If  ?dest_file?  is  defined  the  documentation  is  written  into  the  specified
              destination file. Otherwise the documentation string is returned  by  the  commands
              generate and patch.

       name / ?name?
              This  is the name of the procedure for which the documentation has to be generated.
              This is a mandatory argument for generate, but an optional argument for patch.

       ?-header_footer?
              Generate adds to the generated procedure documentation the file header  and  footer
              only  if a file is generated. By selecting the flag ?-header_footer? the header and
              footer are also generated if the documentation is returned as string by generate.

       ?-src_string src_string | -src_file src_file?
              Patch inserts procedure documentations into an existing  document  that  is  either
              provided as string to the argument (?src_string?) or as a file (?src_file?). One of
              these two arguments need to be specified.

       ?-search_pattern search_pattern?
              The argument ?search_pattern? defines the documentation insertion placeholder  used
              in a document. It is a regular expression accepted by regexp and needs to contain a
              parenthesized sub-expression  that  contains  the  procedure  name  for  which  the
              documentation needs to be inserted.

              The  default  insertion  placeholder  pattern  is \{!(.*?)!\}, which means that the
              procedure name will be embedded between {! and !}. The section EXAMPLES contains  a
              custom insertion placeholder pattern example.

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:

       tepam::doc_gen::Option(TXT,MaxLineLength)
              Default: 80

              This variable defines the line wrapping limit (character position).

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

       tepam::doc_gen::Option(HTML,CssFile)
              Default: "tepam_doc_stylesheet.css"

              This  variable  specifies the CSS stylesheet file that is referred by the generated
              HTML files.

       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:

       •      h1.tepam_page_title  -  Document  page  title.  Only  used by generate if a file is
              created or if the header and footer are built (flag ?-header_footer? selected).

       •      div.tepam_command_help   -   Documentation   container.   The   entire    procedure
              documentation is placed inside this container.

       •      p.tepam_section_title - Section title (e.g. Name, Synopsis, Description, ...)

       •      p.tepam_sub_section_title  -  Sub-section title (used to separate the documentation
              of multiple sub-procedures)

       •      p.tepam_name - Name section

       •      p.tepam_synopsis - Synopsis section

       •      p.tepam_description - Single description paragraph

       •      ul.tepam_description_list - Item of  a  HTML  bulleted/unordered  list  inside  the
              description section

       •      dt.tepam_argument  -  Item  of  a  HTML description list used to list the procedure
              arguments

       •      p.tepam_argument_description - Argument description paragraph

       •      p.tepam_argument_attribute - Argument attribute line

       •      pre.tepam_example - Example section

   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 <mtype>] <text><40e>
                    <20s>   DESCRIPTION<20e>
                    <21s>     message_box<21e>
                    <54s>       message_box [-mtype <mtype>] <text><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 <mtype>]<62e>
               <63> <65s>          Message type<65e>
                    <66s>          Default: "Warning"<66e>
                    <66s>          Multiple: yes<66e>
                    <66s>          Choices: Info, Warning, Error<66e>                  <64>
                    <62s>       <text><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:

       Content generation procedures (e.g. <40s>...<40e>)
              These  procedures generate some document content based on the text that is provided
              as procedure argument. The listing above shows two tokens for these  procedures  to
              indicate the beginning and the end of the generated content.

       Control generation procedures (e.g. <03>)
              These  procedures  generate  control constructs, for example to generate the prolog
              code and epilog code for lists, sections, etc. These procedures have no argument.

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

       01 - gen($Format,Header) {Text}
              Only  called  if  doc_gen  generates  a  file  or  if  it  is  called with the flag
              ?-header_footer?. The procedure creates the file header. The provided parameter  is
              the procedure name for which the documentation has to be generated.

       02 - gen($Format,Footer) {Text}
              Only  called  if  doc_gen  generates  a  file  or  if  it  is  called with the flag
              ?-header_footer?. The procedure creates the file footer.

       03 - gen($Format,Begin) {}
              Generates the documentation prolog (preamble)

       04 - gen($Format,End) {}
              Generates the documentation epilog

       20 - gen($Format,SectionTitle) {Text}
              Generates a section title (e.g. Name, Synopsis, Description, ...).  The  raw  title
              text is provided as parameter

       21 - gen($Format,SubSectionTitle) {Text}
              Generates  a  sub-section title. Sub-sections are used if a single documentation is
              generated for multiple sub-commands to make a  separation  between  them.  The  raw
              title text is provided as parameter

       30 - gen($Format,Name) {Text}
              Generates  the  name  section  (without title). The raw section text is provided as
              parameter.

       40 - gen($Format,Synopsis) {Text}
              Generates the synopsis section  (without  title).  The  section  text  provided  as
              parameter    is    pre-formatted   (the   argument   strings   are   generated   by
              gen($Format,ArgumentString)).

       50 - gen($Format,Description) {Text}
              Generates a description paragraph. The raw paragraph text is provided as parameter.

       51 - gen($Format,DescriptionListBegin) {}
              Generates the prolog of a bulleted/unordered list inside the  description  section.
              This prolog is usually the start code of a list structure.

       52 - gen($Format,DescriptionListEnd) {}
              Generates  the  epilog of a bulleted/unordered list inside the description section.
              This epilog is usually the end code of a list structure.

       53 - gen($Format,DescriptionListItem) {Text}
              Generates a text item in a bulleted/unordered description list. The raw  item  text
              is provided as parameter.

       54 - gen($Format,DescriptionSynopsis) {Text}
              Generates  the  synopsis  line  on  the  beginning  of the description section. The
              command can return an empty string if no synopsys line is required at this place.

              Some formats (e.g. Tcl DocTools) require that the synopsis line is defined  in  the
              description  section, to build then automatically the synopsis section. The section
              text provided as parameter is pre-formatted (the argument strings are generated  by
              gen($Format,ArgumentString)).

       60 - gen($Format,ArgumentListBegin) {}
              Generates  the  prolog of argument list (definition/non-bulleted list). This prolog
              is usually the start code of a definition list.

       61 - gen($Format,ArgumentListEnd) {}
              Generates the epilog of the argument list. This epilog is usually the end string of
              a list structure.

       62 - gen($Format,ArgumentListItem) {Name IsOptional IsNamed Type}
              Generates  an argument item line inside the argument list. This command can rely on
              gen($Format,ArgumentDetailBegin) since the parameters are identical.

       63 - gen($Format,ArgumentDetailBegin) {}
              Generates the argument details prolog (preamble).

       64 - gen($Format,ArgumentDetailEnd) {}
              Generates the argument details epilog

       65 - gen($Format,ArgumentDescription) {Text}
              Generates the argument description (single paragraph).

       66 - gen($Format,ArgumentAttribute) {Text}
              Generates a single argument attribute string. The command  is  called  individually
              for each attribute.

       70 - gen($Format,ExampleBegin) {}
              Generates the example section prolog (preamble)

       71 - gen($Format,ExampleEnd) {}
              Generates the example section epilog

       72 - gen($Format,ExampleCommandLine) {Text}
              Generates  a  single command line in the example section. The command is called for
              each individual command line.

       73 - gen($Format,ExampleResultLine) {Text}
              Generates a command result line

       80 - gen($Format,ArgumentString) {Name IsOptional IsNamed Type}
              Generates the part of the command line or the  synopsis  that  is  specific  to  an
              argument.  The  generated  string has to indicate if an argument is optional, named
              and if it is a flag.

              The following parameters are provided to this procedure:

              Name   Name of the argument

              IsOptional
                     If true (=1) the argument is optional  which  should  be  indicated  by  the
                     generated  string (for example by putting the argument into brackets {[]} or
                     into question marks '?'):

                     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 <mtype>"

                     Named arguments can also be optional:

                     gen(TXT,ArgumentString) mtype 1 1 string -> "[-mtype <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
       ({*<ProcedureName>*}).  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 {\
              <html>
                <head>
                  <title>tepam::doc_gen</title>
                  <link rel="stylesheet" href="tepam_doc_stylesheet.css">
                  <meta content="documentation" name="keywords"></meta>
                </head>
                <body>
                  <h1>tepam::doc_gen</h1>
                    <h2>Generate</h2>
              {*tepam::doc_gen::generate*}
                    <h2>Patch</h2>
              {*tepam::doc_gen::patch*}
                </body>
              <html>\
              }
              # 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(3tcl), tepam::procedure(3tcl)

KEYWORDS

       automatic documentation, documentation, procedure documentation

CATEGORY

       Documentation tools

COPYRIGHT

       Copyright (c) 2013, Andreas Drollinger