tepam_doc_gen(3)



tepam::doc_gen(3tTcl's Enhanced Procedure and Argument Mantepam::doc_gen(3tcl)

______________________________________________________________________________

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 gen-
       erated 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  addi-
       tional 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  proce-
              dure  (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 re-
              turned 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 place-
              holders which are matching the pattern of ?search_pattern?.  The
              existing master document is either provided as data to the argu-
              ment (?src_string?) or via a file (?src_file?). The final  docu-
              ment  is  returned  by  patch  if no destination file is defined
              (?dest_file?). Otherwise, the document is stored in  the  speci-
              fied  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 in-
              sertion will be restricted to a particular procedure.

ARGUMENTS
       ?-format format?
              Specifies the documentation format. TEPAM Doc Gen provides  sup-
              port for the following formats:

              o      TXT - Text format (default)

              o      HTML

              o      POD - Perl Plain Old Documentation format (PerlPOD)

              o      DT - TclLib DocTool format

              Section  ADDING  SUPPORT FOR NEW DOCUMENT FORMATS shows how sup-
              port 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  inser-
              tion  placeholder used in a document. It is a regular expression
              accepted by regexp and needs to contain a parenthesized  sub-ex-
              pression that contains the procedure name for which the documen-
              tation 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 posi-
              tion).

   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  for-
       matting. 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:

       o      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).

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

       o      p.tepam_section_title - Section title (e.g. Name, Synopsis,  De-
              scription, ...)

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

       o      p.tepam_name - Name section

       o      p.tepam_synopsis - Synopsis section

       o      p.tepam_description - Single description paragraph

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

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

       o      p.tepam_argument_description - Argument description paragraph

       o      p.tepam_argument_attribute - Argument attribute line

       o      pre.tepam_example - Example section

   POD - PERL DOCUMENT FORMAT
       The documentation is generated in the Perl Plain Old Documentation for-
       mat (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 differ-
       ent 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 pa-
              rameter

       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 de-
              scription  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 de-
              scription 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  automati-
              cally the synopsis section. The section text provided as parame-
              ter 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 usu-
              ally 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 com-
              mand 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 in-
                     dicated  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  ar-
                     gument/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 documenta-
       tion 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 documenta-
       tions 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  documen-
       tation  placeholders  ({*<ProcedureName>*}). There placeholders are re-
       placed by patch with the generated documentation of the referred proce-
       dures. 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

tcllib                               0.5.0                tepam::doc_gen(3tcl)

Man(1) output converted with man2html
list of all man pages