mgTemplate.c - template for test of mangen


      This file illustrates how a source code file should  be  laid  out  in
      order  to  automatically  generate manual pages (and further reference
      pages for user's  guides  and  functional  descriptions).   This  file
      should be processed with the mangen program which generates a properly
      formatted manual page for the file. The  mangen  program  is  able  to
      generate output in two different output formats:

           nroff format
                   Such output files are suited for the manual
                   libraries used by the man command. These
                   files may also be further processed to generate
                   Frame Maker files.

           formatted text
                   Such output files may be displayed with the
                   more command.

      When processing a C or C++ program file (like this file),  mangen  can
      be controlled to generate two manual files, one containing the library
      introduction/summary description and one containing  all  the  routine
      descriptions  (that  are  selected for the manual).  The former manual
      file (library summary file) will contain  a  synopsis  entry  for  the
      library  as  a  whole.   The  latter  file  can later be split up into
      separate manual entry file, one for each routine,  using  the  program

      To generate such library manual files, mangen shall be called with the
      following options:

           mangen -n lib mgTemplate.c  # -n option gives nroff format files


      mangen assumes some certain layout of the file to  be  processed.  The
      source file contains the following main part:

           File Header
           Introduction/Summary Description
           Routine Descriptions

      All text that are intended for the manual files are (normally) written
      within  comment blocks. mangen recognizes the following comment styles
      (in the following examples an exclamation mark (!) indicates the  left
      text margin):
           1       !/*
                   !* First text column may either be after one space
                   !* (after a '*'), or

           2       !/*
                   !*after no spaces, or

           3       !/*
                   !after neither '*' nor space, in c comments

           4       !// C++ comment

           5       !//C++ comment

           6       !# Script comment

           7       !#Script comment

           8       !%MatLab comment

           9       !% MatLab comment

      mangen is also controlled by different key-words that might appear  in
      the  text. A key-word is actually a subheading (see Subheading below),
      thus a word, all in capital  letters.  The  different  key-words  that
      control  mangen  will  be described in the following sections in their
      right context.

      mangen recognizes an end of a description section as either of:

           1       !*/

           2       ! */

           3       !//*/

           4       !#*/

           5       !/*>*/

           6       !//>*/

      (The two last  [5  and  6]  indicates  that  no  function  declaration

      A subheading is designated by a line containing  words  in  upper-case
      letters, and starting in column one or two.  Three styles for entering
      subheadings are accepted:

           1       !SEE ALSO

           2       !EXAMPLE: mangen -n lib mgTemplate.c

           3       ! MANUAL NAME   Mangen Reference Manual

      A text may follow the subheading on the same line,  if  a  colon  (:),
      case  2, or at least two spaces, case 3, separates the subheading from
      the text.

    File Header
      The file header contains information that  will  appear  as  the  NAME
      section,  and in the page headers and footers of the manual. The first
      lines of the file header must contain the module name and a short, one
      sentence, description. It may be entered in two different ways:

           1       ! mgTemplate.c - A template for test of mangen

           2       ! FILE          mgTemplate.c
                   ! DESCRIPTION   A template for test of mangen

      The following optional key-words are recognized  in  the  file  header

           AUTHOR          the author name will be added at the end
                           of the manual page.
           MANUAL NAME     the manual name will appear in the center
                           of the page headers.
           SYSTEM          the system name will appear on the right
                           of the page footers.
                           the company name is extracted from the
                           copyright notice and will appear to the
                           left of the page footers.

    Introduction/Summary Description
      The Introduction/Summary Description part starts, either:

           after the key-word "ABSTRACT"
           after the text section that starts with the text
           "modification history" (i.e. after the first blank line following the
           "modification history" section).

      The subheading DESCRIPTION will automatically be inserted  if  one  is
      not  supplied  at  the top of this section. If the first subheading is
      ABSTRACT it will be replaced by DESCRIPTION.

      Leading spaces in this section are meaningful in  the  following  way:
      nroff  will  fill/justify  everything  except  lines that begin with a
      space.  This is useful since you can easily enter simple displays just
      by indenting:

           -a      some option
           -b      some other option
           -c      the final option

      You can use tabs  fearlessly  because  the  entire  source  module  is
      initially  expanded to spaces before processing.  Tabs are expanded to
      every 8 columns.

      However, remember that the width of the man  page  screen  display  is
      only  60  characters.   If text in an indented display as above should
      exceed this, it will appear ragged and difficult to read.

      Blank lines are preserved in the resulting output.

      Nroff/troff requests and macros are passed through transparently.  The
      macros  used  in  the  final  formatting, tmac.angen and tmac.ref, are
      closely related to the  UNIX  man  macros.   See  the  example  of  an
      itemized list above under Subheading.

    Routine Descriptions
      Routine descriptions are only included in the secondary  manual  file,
      which is generated for library manuals, by:

           mangen lib <file> or
           mangen -l  <file>

      A routine description is recognized as the comment block starting with
      a star-line, either of:

           1       /****************************************

           2       //****************************************

      The first (non-blank) line of a routine description is regarded as the
      title line, like:

           <routine name> - <description>

      This line will appear as the "NAME" entry in the routine manual file.

      After a blank line, the description section follows. If no  subheading
      is supplied, the subheading will be "DESCRIPTION".

      This description block  follows  the  same  formatting  rules  as  the
      Introduction/Summary  description.  (See  above).   Subheadings may be
      entered as appropriate.

      The routine description  comment  block  is  assumed  to  end  at  the
      description  end-mark  (e.g.  '*/'), or at the first found blank, non-
      comment, line.

      After the end of the routine description, the routine declaration must
      follow.  It may be supplied in different styles, either old c-style or
      ANSI-C style; either all parameters in one line or in  several  lines;
      either  with  comments  for  the parameters or without comments.  Here
      follows some examples:

           extern char*  strdup(char* s);

           char*  strcpy(char* s1, const char s2)
             { ... }

           char*  strncpy(
                   char*      s1,          /* destination string */
                   const char s2,          /* source string */
                   int        length)      /* max length of string s1 */
             { ... }

           int   strncmp(s1, s2, length)
             const char* s1;               /* destination string */
             const char* s2;               /* source string */
             int        length;            /* max length of string s1 */
             { ... }

      This routine declaration will appear as  the  SYNOPSIS  section,  just
      after  the NAME section, in the routine manual output.  You can easily
      enter additional synopsis lines, intended to appear before the routine
      declaration,  in  the output. This is typically used to show "#include
      <...>" lines.  Just write a SYNOPSIS section, anywhere in the  comment
      block.  All  the following lines, til the next blank line, will be put
      first in the synopsis section. (If  you  want  to  enter  empty  lines
      within  the section, such can be made by writing a \" at the beginning
      of the line [nroff comment leader]).

      See further the following routine descriptions  in  this  mgTemplate.c

    Type Declaration and Macro Definition Descriptions
      Type  declaration  and  macro  definition  descriptions   are   almost
      identical  to routine descriptions. The only diffeerence is that these
      latter are not followed by  a  routine  declaration,  but  by  a  type
      declaration or a macro definition.

      mangen allows that type declarations are copied transparently from the
      source  code to the synopsis section of the manual output.  Instead of
      ending the routine description with the normal end-mark '*/',  end  it
      with the mark: '<*/'.

      The source lines will then be  copied  transparantly,  til  the  mark:
      '>*/'.   Thus,  the source lines shall be enclosed by the marks, as in
      this example:
           typedef struct
             { int x, y; } XY_coordinates;


      For macro definitions the  same  technique  can  be  used,  or  in  an
      alternative  way,  if only the macro prototype part shall be shown and
      not its implementation.  The macro  prototype  can  be  written  in  a
      SYNOPSIS   section,   just  showing  the  essential  parts.  Then  the
      description block is ended with  the  mark:  '>*/'  (which  means,  no
      function prototype shall be copied).

      Within a sequence of transparently copied source  lines,  it  is  very
      useful  to  use the "HIDE" and UNHIDE" key-words to exclude some lines
      with implementation details from the manual output (e.g.  inline  code
      in C++ class declarations).

      See further the following routine descriptions  in  this  mgTemplate.c


      In the process of generating the manual entry, a few checks are made:

           1       The module name (the 1st word of the title line or
                   the "FILE" entry) must exactly match the source
                   file name.
           2       A module description section (a block comment following
                   the modification history or "ABSTRACT" subheading)
                   must be present.
           3       The subroutine name (the 1st word of the routine title
                   line) must exactly match the actual declared routine


      mangen recognizes the following additional subheading key-words:

           NO MANUAL       Indicates that this routine entry shall
                           not be included in the library
                           manual file. The entire routine description
                           will be excluded.
                           Can also be entered as "NO-MANUAL", "NOMANUAL"
                           or "NO_MANUAL".
           INTERNAL        Indicats that the rest of the current description
                           section, til the end-mark, will be ignored and
                           not included in the manual output.
           HIDE            Indicats that the following lines shall be
                           ignored and not included in the manual output,
                           til the UNHIDE key-word.
           UNHIDE          Indicates that the previous HIDE directive shall
                           be reset.


      What we really want is not "mangen" that generates  the  manual  entry
      from  the program, but rather "pgmgen" that generates the program from
      the manual entry.


      This file serves as a template for writing mangen manual  page  format
      files, and is avaiable under $SDE_HOME/forms/mgTemplate.c


      mangen(1), splitman(1), mgTemplate.c, template(1)


      SEISY/LKSS       Ake Bromo