% Document: ./SingleDocLatex/singledoc
% Source: ./ROBODocSource/
% Generated with ROBODoc Version 4.99.40 (Feb  6 2011)
\documentclass{article}
\usepackage{makeidx}
\usepackage{graphicx}
\oddsidemargin 0 cm
\evensidemargin 0 cm
\topmargin 0 cm
\textwidth 16 cm
\textheight 22 cm
\setlength{\parindent}{0in}
\setlength{\parskip}{.08in}

\pagestyle{headings}
\title{API Reference}
\author{Generated with ROBODoc Version 4.99.40 (Feb  6 2011)
}
\makeindex
\begin{document}
\maketitle
\newpage
\tableofcontents

\newpage
\section{Docuwala/ROBODoc}
\textsl{[ Modules ]}

\label{ch:robo0}
\label{ch:Docuwala_ROBODoc}
\index{unsorted!ROBODoc}\index{Modules!ROBODoc}
\textbf{FUNCTION}

   ROBODoc is intended to be a replacement for the original AutoDocs
   program.  ROBODoc will extract the comment headers from a source
   file, and put them into a separate documentation file.
   General Flow


\begin{verbatim}
      Sourcecode  ---> [ROBODoc] ---> Document.
\end{verbatim}


   The whole ROBODoc process consists of three steps: scanning,
   analysing, generating.



   Scanning 



   ROBODoc scans the source directory tree. This collects the names of
   all the source files.



   Analysing



   ROBODOc analyses all the sourcefiles. This reads the content of all
   source files and collects all the headers.



   Generating



   In this step the headers are written to one or more documentation files.
   In addition 




   The data collected during scanning and analysing is stored in a
   number of structures.



   RB\_Directory (\ref{ch:robo67}), it stores the names of the sourcefiles and directories in
   the source direcory tree.  File names are stored in a RB\_Filename (\ref{ch:robo93})
   structure, directory names in a RB\_Path (\ref{ch:robo194}) structure.  Each RB\_Filename (\ref{ch:robo93})
   contains a pointer (path) to a RB\_Path (\ref{ch:robo194}) structure that tells in which
   directory a file is located.  Each RB\_Path (\ref{ch:robo194}) has a pointer (parent) to
   another RB\_Path (\ref{ch:robo194}) structure that tells in which directory is a directory
   located (of which directory it is a subdirectory).  The only exception
   is the root directory.

   

   Besides the name of the sourcefile, the RB\_Filename (\ref{ch:robo93}) also stores the
   name of the documentation file.

   

   For each sourcefile there is an RB\_Part (\ref{ch:robo191}) structure.  It contains a
   pointer (filename) to the RB\_Filename (\ref{ch:robo93}) and a list (headers) of
   RB\_Header structure containing the headers found in the sourcefile.

   

   Every RB\_Header structure contains a pointer (owner) to the RB\_Part (\ref{ch:robo191})
   structure to which it belongs.  Headers (\ref{ch:robo9}) can form a hierarchy that is
   used to create sections and subsections in the documentation.  To
   store this hierarchy every RB\_header (\ref{ch:robo144}) structure contains a pointer
   (parent) to its parent header.  For instance, given the following two
   headers, SubModule is the parent of SubSubModule.

\begin{verbatim}
     ****h* TopModule/SubModule
     *
     **** 
\end{verbatim}

   

\begin{verbatim}
     ****h* SubModule/SubSubModule
     *
     **** 
\end{verbatim}

   
   In the documentation this creates the sections

\begin{verbatim}
      1.TopModule
      1.1 SubModule
      1.1.1 SubSubModule
\end{verbatim}

   
   The RB\_Directory (\ref{ch:robo67}) and the linked list of RB\_Part (\ref{ch:robo191}) structures are
   stored in a RB\_Document (\ref{ch:robo82}) structure.

   

   During the generation of the documentation ROBODoc tries to create
   cross links between the mention of a header's name (an object) and the
   documentation generated from that header (the documentation for the
   object).

   

   To aid this proces there is an array of RB\_link (\ref{ch:robo187}) structures.  This
   array is sorted for quick searching.  RB\_link (\ref{ch:robo187}) structures the name
   of a header and the name of the label under which the documentation
   can be found in the documentation file.

\textbf{AUTHOR}

   See AUTHORS in the archive.

\textbf{CREATION DATE}

   20-Dec-94  Jacco van Weert.

\textbf{MODIFICATION HISTORY}

   See ChangeLog in the archive. Latest version can be found on:

\begin{itemize}
  \item    http://www.xs4all.nl/$\sim$rfsber/Robo/
\end{itemize}


\textbf{BUGS}

   Other bugs? Catch them in a jar and send them to rfsber -(at)- xs4all.nl

\newpage
\subsection{ROBODoc/Analyser}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo1}
\label{ch:ROBODoc_Analyser}
\index{unsorted!Analyser}\index{Modules!Analyser}
\textbf{NAME}

   Analyser -- Functions to scan source and collect headers

\textbf{FUNCTION}

   This module provides the functions to scan a sourcefile and
   collect all the headers.

\newpage
\subsubsection{Analyser/Analyse\_Indentation}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo19}
\label{ch:Analyser_Analyse_Indentation}
\index{unsorted!Analyse\_Indentation}\index{Functions!Analyse\_Indentation}
\textbf{FUNCTION}

  Figure out how text is indented. 
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item -- the item to be analysed.
\end{itemize}


\newpage
\subsubsection{Analyser/Analyse\_Item\_Format}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo20}
\label{ch:Analyser_Analyse_Item_Format}
\index{unsorted!Analyse\_Item\_Format}\index{Functions!Analyse\_Item\_Format}
\textbf{FUNCTION}

   Try to determine the formatting of an item.
   An empty line generates a new paragraph
   Things that are indented more that the rest of the text
   are preformatted.
   Things that start with a '*' or '-' create list items
   unless they are indented more that the rest of the text.
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item -- the item to be analysed.
\end{itemize}


\newpage
\subsubsection{Analyser/Analyse\_List}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo21}
\label{ch:Analyser_Analyse_List}
\index{unsorted!Analyse\_List}\index{Functions!Analyse\_List}
\textbf{FUNCTION}

   Parse the item text to see if there are any lists.
   A list is either case I:

\begin{verbatim}
      ITEMNAME
         o bla bla
         o bla bla
\end{verbatim}

   or case II:

\begin{verbatim}
      some text:     <-- begin of a list
      o bla bla      <-- list item
        bla bla bla  <-- continuation of list item.
      o bla bla      <-- list item
                     <-- end of a list 
      bla bla        <-- this can also be the end of a list.
\end{verbatim}

 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item  -- the item to be parsed.
  \item    indent    -- the indent of this item.
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    arg\_item  -- the itemlines will contain formatting information 
                  for all the lists that were found.
\end{itemize}


\newpage
\subsubsection{Analyser/Analyse\_ListBody}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo22}
\label{ch:Analyser_Analyse_ListBody}
\index{unsorted!Analyse\_ListBody}\index{Functions!Analyse\_ListBody}
\textbf{FUNCTION}

   Analyse... (TODO) 
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item    -- the item to be analysed.
  \item    start\_index --
  \item    arg\_index   --
\end{itemize}


\newpage
\subsubsection{Analyser/Analyse\_Paragraphs}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo23}
\label{ch:Analyser_Analyse_Paragraphs}
\index{unsorted!Analyse\_Paragraphs}\index{Functions!Analyse\_Paragraphs}
\textbf{FUNCTION}

   Analyse paragraphs... (TODO) 
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item -- the item to be analysed.
\end{itemize}


\newpage
\subsubsection{Analyser/Analyse\_Preformatted}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo24}
\label{ch:Analyser_Analyse_Preformatted}
\index{unsorted!Analyse\_Preformatted}\index{Functions!Analyse\_Preformatted}
\textbf{FUNCTION}

   Analyse preformatted text ... (TODO) 
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item -- the item to be analysed.
  \item    indent   -- 
\end{itemize}


\newpage
\subsubsection{Analyser/AnalyseHeaderType}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo25}
\label{ch:Analyser_AnalyseHeaderType}
\index{unsorted!AnalyseHeaderType}\index{Functions!AnalyseHeaderType}
\textbf{FUNCTION}

   Determine the type of the header.

\textbf{INPUTS}
\begin{itemize}
  \item    cur\_char -- pointer to the header type character
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    is\_internal -- indicates if it is an internal header or not.*
  \item    cur\_char -- points to the header type character
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    pointer to a RB\_HeaderType (\ref{ch:robo145})
\end{itemize}


\newpage
\subsubsection{Analyser/Find\_End\_Marker}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo26}
\label{ch:Analyser_Find_End_Marker}
\index{unsorted!Find\_End\_Marker}\index{Functions!Find\_End\_Marker}
\textbf{FUNCTION}

   Scan and store all lines from a source file until
   an end marker is found.

\textbf{INPUTS}
\begin{itemize}
  \item    document -- a pointer to an opened source file.
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    new\_header -- the lines of source code will be added
                   here.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    TRUE  -- an end marker was found.
  \item    FALSE -- no end marker was found while scanning the
              source file.
\end{itemize}


\newpage
\subsubsection{Analyser/Function\_Name}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo27}
\label{ch:Analyser_Function_Name}
\index{unsorted!Function\_Name}\index{Functions!Function\_Name}
\textbf{FUNCTION}

   A header name is consists of two parts. The module name and
   the function name. This returns a pointer to the function name.
   The name "function name" is a bit obsolete. It is really the name
   of any of objects that can be documented; classes, methods,
   variables, functions, projects, etc.

\newpage
\subsubsection{Analyser/Get\_Indent}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo28}
\label{ch:Analyser_Get_Indent}
\index{unsorted!Get\_Indent}\index{Functions!Get\_Indent}
\textbf{INPUTS}
\begin{itemize}
  \item    line -- the line
\end{itemize}


\textbf{RESULT}

   The indentation.

\newpage
\subsubsection{Analyser/Grab\_Header}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo29}
\label{ch:Analyser_Grab_Header}
\index{unsorted!Grab\_Header}\index{Functions!Grab\_Header}
\textbf{FUNCTION}

   Grab a header from a source file, that is scan a source file
   until the start of a header is found.  Then search for the end
   of a header and store all the lines in between.
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    sourcehandle -- an opened source file.
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    sourcehandle -- will point to the line following the end marker.
\end{itemize}


\textbf{RESULT}

   0 if no header was found, or a pointer to a new header otherwise.

\newpage
\subsubsection{Analyser/Is\_Empty\_Line}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo30}
\label{ch:Analyser_Is_Empty_Line}
\index{unsorted!Is\_Empty\_Line}\index{Functions!Is\_Empty\_Line}
\textbf{FUNCTION}

   Check if line is empty. This assumes that 
   Copy\_Lines\_To\_Item has been run on the item.

\textbf{INPUTS}
\begin{itemize}
  \item    line -- the string to be analysed.
\end{itemize}


\newpage
\subsubsection{Analyser/Is\_List\_Item\_Continuation}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo31}
\label{ch:Analyser_Is_List_Item_Continuation}
\index{unsorted!Is\_List\_Item\_Continuation}\index{Functions!Is\_List\_Item\_Continuation}
\textbf{FUNCTION}

   Is it like the second line in something like:

\begin{verbatim}
     * this is a list item
       that continues 
\end{verbatim}

 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_line  -- the current line
  \item    indent    -- the indent of the current item.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    TRUE  -- it is.
  \item    FALSE -- it is not.
\end{itemize}


\newpage
\subsubsection{Analyser/Is\_ListItem\_Start}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo32}
\label{ch:Analyser_Is_ListItem_Start}
\index{unsorted!Is\_ListItem\_Start}\index{Functions!Is\_ListItem\_Start}
\textbf{FUNCTION}

   Test if a line starts with something that indicates a list item.
   List items start with '*', '-', or 'o'.
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    line -- the line
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    TRUE  -- it did start with one of those characters
  \item    FALSE -- it did not.
\end{itemize}


\newpage
\subsubsection{Analyser/Is\_Pipe\_Marker}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo33}
\label{ch:Analyser_Is_Pipe_Marker}
\index{unsorted!Is\_Pipe\_Marker}\index{Functions!Is\_Pipe\_Marker}
\textbf{NAME}

   Is\_Pipe\_Marker

\textbf{FUNCTION}

   Check for "pipe" markers e.g. "$|$html ". 

\textbf{RESULT}

   Pointer to the data to be piped to document or in case no pointers
   are found.

\textbf{SEE ALSO}

   RB\_Check\_Pipe

\newpage
\subsubsection{Analyser/Is\_Start\_List}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo34}
\label{ch:Analyser_Is_Start_List}
\index{unsorted!Is\_Start\_List}\index{Functions!Is\_Start\_List}
\textbf{FUNCTION}

   Check... (TODO) 

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_line --
  \item    indent  --
\end{itemize}


\newpage
\subsubsection{Analyser/Is\_Tool}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo35}
\label{ch:Analyser_Is_Tool}
\index{unsorted!Is\_Tool}\index{Functions!Is\_Tool}
\textbf{FUNCTION}

   Checks for tool start and end markers

\newpage
\subsubsection{Analyser/Module\_Name}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo36}
\label{ch:Analyser_Module_Name}
\index{unsorted!Module\_Name}\index{Functions!Module\_Name}
\textbf{FUNCTION}

   Get the module name from the header name.  The header name will be
   something like


\begin{verbatim}
     module/functionname.
\end{verbatim}


 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    header\_name -- a pointer to a nul terminated string.
\end{itemize}


\textbf{RESULT}

   Pointer to the modulename.  You're responsible for freeing it.

\textbf{SEE ALSO}

   Function\_Name (\ref{ch:robo27})()

\newpage
\subsubsection{Analyser/Preformat\_All}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo37}
\label{ch:Analyser_Preformat_All}
\index{unsorted!Preformat\_All}\index{Functions!Preformat\_All}
\textbf{FUNCTION}

   Process... (TODO) 
 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item -- the item to be pre-formatted.
  \item    source   -- is it a source item ?
\end{itemize}


\newpage
\subsubsection{Analyser/RB\_Analyse\_Document}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo38}
\label{ch:Analyser_RB_Analyse_Document}
\index{unsorted!RB\_Analyse\_Document}\index{Functions!RB\_Analyse\_Document}
\textbf{FUNCTION}

   Scan all the sourcefiles of all parts of a document for
   headers.  Store these headers in each part (RB\_Part (\ref{ch:robo191})).

\textbf{INPUTS}
\begin{itemize}
  \item    document -- document to be analysed.
\end{itemize}


\textbf{RESULT}

   Each part will contain the headers that were found in the
   sourcefile of the part.

\newpage
\subsubsection{Analyser/RB\_Analyse\_Items}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo39}
\label{ch:Analyser_RB_Analyse_Items}
\index{unsorted!RB\_Analyse\_Items}\index{Functions!RB\_Analyse\_Items}
\textbf{FUNCTION}

   Locate the items in the header and create RB\_Item (\ref{ch:robo180}) structures for
   them.
 SYNPOPSIS

\newpage
\subsubsection{Analyser/RB\_Find\_Marker}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo40}
\label{ch:Analyser_RB_Find_Marker}
\index{unsorted!RB\_Find\_Marker}\index{Functions!RB\_Find\_Marker}
\textbf{NAME}

   RB\_Find\_Marker -- Search for header marker in document.

\textbf{FUNCTION}

   Read document file line by line, and search each line for 
   any of the headers defined in the array  header\_markers (\ref{ch:robo142}) (OR
   if using the -rh switch, robo\_head)

\textbf{INPUTS}

   document - pointer to the file to be searched.
   the gobal buffer line\_buffer (\ref{ch:robo133}).

\textbf{OUTPUT}
\begin{itemize}
  \item    document will point to the line after the line with 
     the header marker.
  \item    is\_internal will be TRUE if the header is an internal
     header.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    header type
\end{itemize}


\textbf{BUGS}

   Bad use (\ref{ch:robo221}) of feof(), fgets().

\textbf{SEE ALSO}

   Find\_End\_Marker (\ref{ch:robo26})

\newpage
\subsubsection{Analyser/RB\_GetCurrentFile}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo41}
\label{ch:Analyser_RB_GetCurrentFile}
\index{unsorted!RB\_GetCurrentFile}\index{Functions!RB\_GetCurrentFile}
\textbf{NAME}

   Get a copy of the name of the current file.
   Allocates memory.

\newpage
\subsubsection{Analyser/RB\_Warning}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo42}
\label{ch:Analyser_RB_Warning}
\index{unsorted!RB\_Warning}\index{Functions!RB\_Warning}
\textbf{NAME}

   RB\_Warning

\textbf{FUNCTION}

   Print warning to stdout. (stderr better?)

\textbf{INPUTS}
\begin{itemize}
  \item    format --
  \item    ...    --
\end{itemize}


\newpage
\subsubsection{Analyser/RB\_Warning\_Full}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo43}
\label{ch:Analyser_RB_Warning_Full}
\index{unsorted!RB\_Warning\_Full}\index{Functions!RB\_Warning\_Full}
\textbf{NAME}

   RB\_Warning\_Full

\textbf{FUNCTION}

   Print warning to stdout.

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_filename    --
  \item    arg\_line\_number --
  \item    arg\_format      --
  \item    ...
\end{itemize}


\newpage
\subsubsection{Analyser/Remove\_List\_Char}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo44}
\label{ch:Analyser_Remove_List_Char}
\index{unsorted!Remove\_List\_Char}\index{Functions!Remove\_List\_Char}
\textbf{FUNCTION}

   Remove... (TODO) 

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_item    -- the item to be analysed.
  \item    start\_index -- 
\end{itemize}


\newpage
\subsubsection{Analyser/ToBeAdded}
\textsl{[ Analyser ]}
\textsl{[ Functions ]}

\label{ch:robo45}
\label{ch:Analyser_ToBeAdded}
\index{unsorted!ToBeAdded}\index{Functions!ToBeAdded}
\textbf{FUNCTION}

   Test whether or not a header needs to be added to the
   list of headers. This implements the options 

\begin{verbatim}
      --internal 
\end{verbatim}

   and

\begin{verbatim}
      --internalonly
\end{verbatim}

 SYNPOPSIS

\textbf{INPUTS}
\begin{itemize}
  \item    document  -- a document (to determine the options)
  \item    header    -- a header
\end{itemize}


\textbf{RESULT}

   TRUE  -- Add header
   FALSE -- Don't add header

\newpage
\subsection{ROBODoc/ASCII\_Generator}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo2}
\label{ch:ROBODoc_ASCII_Generator}
\index{unsorted!ASCII\_Generator}\index{Modules!ASCII\_Generator}
\textbf{NAME}

   ASCII\_Generator -- Generator (\ref{ch:robo7}) for ASCII output

\textbf{FUNCTION}

   Plain ascii output, no formatting.

\textbf{MODIFICATION HISTORY}

   2003-06-17  Frans Slothouber V1.0

\newpage
\subsubsection{ASCII\_Generator/RB\_ASCII\_Generate\_Item\_Line\_Number}
\textsl{[ ASCII\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo46}
\label{ch:ASCII_Generator_RB_ASCII_Generate_Item_Line_Number}
\index{unsorted!RB\_ASCII\_Generate\_Item\_Line\_Number}\index{Functions!RB\_ASCII\_Generate\_Item\_Line\_Number}
\textbf{FUNCTION}

   Generate line numbers for SOURCE like items

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc           -- the file to write to.
  \item    line\_number\_string -- the line number as string.
\end{itemize}


\newpage
\subsection{ROBODoc/Configuration}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo3}
\label{ch:ROBODoc_Configuration}
\index{unsorted!Configuration}\index{Modules!Configuration}
\textbf{FUNCTION}

   Functions to access the ROBODoc (\ref{ch:robo0}) configuration (\ref{ch:robo51}) and configuration (\ref{ch:robo51})
   file (robodoc.rc) or the file specified with the --rc option.



   The robodoc.rc file consists of a number of blocks.  Each
   block starts with a line of the form


\begin{verbatim}
     <block name>:
\end{verbatim}


   This is followed by a number of lines of data.  Each line starts
   with at least one space followed by the actual data.



   This module parses this data and stores it in the global
   configuration (\ref{ch:robo51}).

\textbf{NOTES}

   Is missing a lot of documentation.



   You can not use (\ref{ch:robo221}) RB\_Say (\ref{ch:robo243})() in this module since the --tell flag
   won't be parsed until after this module has finished.

\newpage
\subsubsection{Configuration/add\_keywords\_to\_hash\_table}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo47}
\label{ch:Configuration_add_keywords_to_hash_table}
\index{unsorted!add\_keywords\_to\_hash\_table}\index{Functions!add\_keywords\_to\_hash\_table}
\textbf{FUNCTION}

   Initalize hash table and add all keywords from configuration (\ref{ch:robo51}).keywords
   to the hash table

\newpage
\subsubsection{Configuration/add\_to\_keywords\_hash\_table}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo48}
\label{ch:Configuration_add_to_keywords_hash_table}
\index{unsorted!add\_to\_keywords\_hash\_table}\index{Functions!add\_to\_keywords\_hash\_table}
\textbf{FUNCTION}

   Add a keyword to the hash table

\textbf{INPUTS}

   keyword -- The keyword string

\newpage
\subsubsection{Configuration/allocate\_keywords\_hash\_table}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo49}
\label{ch:Configuration_allocate_keywords_hash_table}
\index{unsorted!allocate\_keywords\_hash\_table}\index{Functions!allocate\_keywords\_hash\_table}
\textbf{FUNCTION}

   Allocates space for the keyword hash table.



   The size of the table depends on the number of keywords rounded up to the
   next power of two.

\newpage
\subsubsection{Configuration/c\_keywords}
\textsl{[ Configuration ]}
\textsl{[ Variables ]}

\label{ch:robo50}
\label{ch:Configuration_c_keywords}
\index{unsorted!c\_keywords}\index{Variables!c\_keywords}
\textbf{FUNCTION}

   The default C keywords.

\newpage
\subsubsection{Configuration/configuration}
\textsl{[ Configuration ]}
\textsl{[ Variables ]}

\label{ch:robo51}
\label{ch:Configuration_configuration}
\index{unsorted!configuration}\index{Variables!configuration}
\textbf{FUNCTION}

   This global stores all the configuration parameters specified on
   the command line and in the robodoc.rc file.

\newpage
\subsubsection{Configuration/default\_item\_names}
\textsl{[ Configuration ]}
\textsl{[ Variables ]}

\label{ch:robo52}
\label{ch:Configuration_default_item_names}
\index{unsorted!default\_item\_names}\index{Variables!default\_item\_names}
\textbf{FUNCTION}

   Defines the names of items that ROBODoc (\ref{ch:robo0}) recognized as
   items by default if none are specified in the
   robodoc.rc file.

\newpage
\subsubsection{Configuration/Find\_Keyword}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo53}
\label{ch:Configuration_Find_Keyword}
\index{unsorted!Find\_Keyword}\index{Functions!Find\_Keyword}
\textbf{FUNCTION}

   Find a keyword in the hash table

\textbf{INPUTS}
\begin{itemize}
  \item    keyword -- The keyword string
  \item    len     -- The length of the keyword string
\end{itemize}


\textbf{RETURN VALUE}
\begin{itemize}
  \item    pointer to the found keyword string in hash table or
  \item    NULL if the keyword is not found
\end{itemize}


\newpage
\subsubsection{Configuration/Find\_Parameter\_Char}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo54}
\label{ch:Configuration_Find_Parameter_Char}
\index{unsorted!Find\_Parameter\_Char}\index{Functions!Find\_Parameter\_Char}
\textbf{FUNCTION}

   Checks for the existence of a given configuration (\ref{ch:robo51}) parameter
   (Character match)

\newpage
\subsubsection{Configuration/Find\_Parameter\_Exact}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo55}
\label{ch:Configuration_Find_Parameter_Exact}
\index{unsorted!Find\_Parameter\_Exact}\index{Functions!Find\_Parameter\_Exact}
\textbf{FUNCTION}

   Checks for the existence of a given configuration (\ref{ch:robo51}) parameter
   (exact string match)

\newpage
\subsubsection{Configuration/Find\_Parameter\_Partial}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo56}
\label{ch:Configuration_Find_Parameter_Partial}
\index{unsorted!Find\_Parameter\_Partial}\index{Functions!Find\_Parameter\_Partial}
\textbf{FUNCTION}

   Checks for the existence of a given configuration (\ref{ch:robo51}) parameter
   (partial string match)

\newpage
\subsubsection{Configuration/GetParameters}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo57}
\label{ch:Configuration_GetParameters}
\index{unsorted!GetParameters}\index{Functions!GetParameters}
\textbf{FUNCTION}

   Parse a line of text and store the individual words in
   a Parameters (\ref{ch:robo63}) structure.  Words are seperated by spaces,
   the exception are words surrounded by quotes. So:

\begin{verbatim}
      aap noot mies "back to the future"
\end{verbatim}

   contains four words.

\textbf{INPUTS}
\begin{itemize}
  \item    line -- the line of text.
  \item    parameters  -- the set of parameters
\end{itemize}


\newpage
\subsubsection{Configuration/Hash\_Keyword}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo58}
\label{ch:Configuration_Hash_Keyword}
\index{unsorted!Hash\_Keyword}\index{Functions!Hash\_Keyword}
\textbf{FUNCTION}

   Calculate the hash value for a string



   The hash value is a 32 bit integer based on the hash function written by
   Bob Jenkins. It is then reduced by an AND operation to the actual size of
   the hash table.

\textbf{INPUTS}
\begin{itemize}
  \item    key    -- The keyword string
  \item    keylen -- The length of the keyword string
\end{itemize}


\textbf{RETURN VALUE}

   The hash value for the keyword.

\newpage
\subsubsection{Hash\_Keyword/HASH\_MIX}
\textsl{[ Hash\_Keyword ]}
\textsl{[ Functions ]}

\label{ch:robo138}
\label{ch:Hash_Keyword_HASH_MIX}
\index{unsorted!HASH\_MIX}\index{Functions!HASH\_MIX}
\textbf{FUNCTION}

   Helper macro for the function Hash\_Keyword (\ref{ch:robo58})( )

\newpage
\subsubsection{Configuration/Install\_C\_Syntax}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo59}
\label{ch:Configuration_Install_C_Syntax}
\index{unsorted!Install\_C\_Syntax}\index{Functions!Install\_C\_Syntax}
\textbf{FUNCTION}

   Install default C keywords and comments

\newpage
\subsubsection{Configuration/keywords\_hash}
\textsl{[ Configuration ]}
\textsl{[ Variables ]}

\label{ch:robo60}
\label{ch:Configuration_keywords_hash}
\index{unsorted!keywords\_hash}\index{Variables!keywords\_hash}
\textbf{FUNCTION}

   This is the hash table for the keywords.
   See keywords\_hash\_s (\ref{ch:robo62}).

\newpage
\subsubsection{Configuration/keywords\_hash\_mask}
\textsl{[ Configuration ]}
\textsl{[ Variables ]}

\label{ch:robo61}
\label{ch:Configuration_keywords_hash_mask}
\index{unsorted!keywords\_hash\_mask}\index{Variables!keywords\_hash\_mask}
\textbf{FUNCTION}

   Mask for keyword hash function.
   This mask reduces the hash value for the actual hash table size.
   Also the size of the hash table can be derived from this mask:

\begin{verbatim}
     hash table size = keywords_hash_mask + 1
\end{verbatim}


\newpage
\subsubsection{Configuration/keywords\_hash\_s}
\textsl{[ Configuration ]}
\textsl{[ Structures ]}

\label{ch:robo62}
\label{ch:Configuration_keywords_hash_s}
\index{unsorted!keywords\_hash\_s}\index{Structures!keywords\_hash\_s}
\textbf{FUNCTION}

    Structure for a keyword hash table row.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item     keyword -- pointer to the keyword
  \item     next    -- pointer to next entry in the row
\end{itemize}


\newpage
\subsubsection{Configuration/Parameters}
\textsl{[ Configuration ]}
\textsl{[ Structures ]}

\label{ch:robo63}
\label{ch:Configuration_Parameters}
\index{unsorted!Parameters}\index{Structures!Parameters}
\textbf{FUNCTION}

    Structure to store all the paramters found in a block in the
    robodoc configuation file.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item     number -- the number of parameters found.
  \item     size   -- the maximum size of the names array.
  \item     names  -- an array with the values of the parameters.
\end{itemize}


\textbf{NOTES}

    Find a better name for the attribute 'names'

\newpage
\subsubsection{Configuration/RB\_Configuration}
\textsl{[ Configuration ]}
\textsl{[ Structures ]}

\label{ch:robo64}
\label{ch:Configuration_RB_Configuration}
\index{unsorted!RB\_Configuration}\index{Structures!RB\_Configuration}
\textbf{FUNCTION}

   All the data from the robodoc.rc file is stored in this
   structure.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item    items                 -- an array with names that robodoc recognizes as
                              items.  Alsways includes the name "SOURCE" as
                              the first element.
  \item    ignore\_items          -- an array with the names of items that ROBODoc (\ref{ch:robo0})
                              should ignore.
  \item    source\_items          -- an array with the names of items that work
                              similar to the built-in SOURCE item.
  \item    preformatted\_items    -- item names that will be automatically
                              preformatted
  \item    format\_items          -- item names that should be formatted by the
                              browser
  \item    item\_order            -- an array with item names that
                              indicates which items should be displayed first.
  \item    options               -- Array with all options specified both on the
                              commandline as well as in the robodoc.rc file.
  \item    custom\_headertypes    -- list with custom header types.
  \item    ignore\_files          -- list with wildcard expressions that specifies
                              files and directories that robodoc should skip
                              while scanning the source tree.
  \item    header\_markers (\ref{ch:robo142})        -- list with markers that mark the begin of a
                              header.
  \item    remark\_markers (\ref{ch:robo148})        -- list with markers that mark a remark.
  \item    end\_markers (\ref{ch:robo139})           -- list with markers that markt the end of a
                              header.
  \item    remark\_begin\_markers  -- list of markers that mark the begin of
                              a remark.  For instance (*
  \item    remakr\_end\_markers    -- list of markers that mark the end of a
                              remark.  For instance   *)
  \item    keywords              -- source keywords to recognise (and colorise)
  \item    source\_line\_comments  -- comment markers that span until the end of line
  \item    header\_ignore\_chars   -- characters for beginning of header remarks
  \item    header\_separate\_chars -- characters that separates header artifacts
\end{itemize}


\newpage
\subsubsection{Configuration/ReadConfiguration}
\textsl{[ Configuration ]}
\textsl{[ Functions ]}

\label{ch:robo65}
\label{ch:Configuration_ReadConfiguration}
\index{unsorted!ReadConfiguration}\index{Functions!ReadConfiguration}
\textbf{FUNCTION}

   Read the robodoc configuration (\ref{ch:robo51}) file, and create
   a RB\_Configuration (\ref{ch:robo64}) structure.

\textbf{INPUTS}
\begin{itemize}
  \item    argc -- the arg count as received by main (\ref{ch:robo211})()
  \item    argv -- the arg valules as received by main (\ref{ch:robo211})()
  \item    filename -- an optional filename.  If none is given,
               "robodoc.rc" is used.
\end{itemize}


\textbf{RESULT}

   An initialized configuration (\ref{ch:robo51}) (a global).

\newpage
\subsection{ROBODoc/Directory}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo4}
\label{ch:ROBODoc_Directory}
\index{unsorted!Directory}\index{Modules!Directory}
\textbf{NAME}

   This module contains function to scan a directory tree and to
   create a RB\_Directory (\ref{ch:robo67}) structure.  Most of the OS dependend parts
   of ROBODoc (\ref{ch:robo0}) can be found in this module..



   This module currently works under:

\begin{itemize}
  \item    Cygwin   http://cygwin.com 
  \item    Redhad 7.3 Linux
  \item    VC++ under Windows NT 
  \item    MINGW    http://www.mingw.org/ 
  \item    OS/X
\end{itemize}


\textbf{AUTHOR}

   Frans Slothouber

\newpage
\subsubsection{Directory/content\_buffer}
\textsl{[ Directory ]}
\textsl{[ Variables ]}

\label{ch:robo66}
\label{ch:Directory_content_buffer}
\index{unsorted!content\_buffer}\index{Variables!content\_buffer}
\textbf{FUNCTION}

   Temporary buffer file file content and filenames.

\newpage
\subsubsection{Directory/RB\_Directory}
\textsl{[ Directory ]}
\textsl{[ Structures ]}

\label{ch:robo67}
\label{ch:Directory_RB_Directory}
\index{unsorted!RB\_Directory}\index{Structures!RB\_Directory}
\textbf{NAME}

   RB\_Directory -- the directory tree with the source files.

\textbf{FUNCTION}

   Stores information about files in a directory tree.
   The whole structure consist of two linked lists.  One for
   directory paths, and one for filenames.

\textbf{EXAMPLE}

   The following show an example structure.

\begin{verbatim}
     RB_Directory             RB_Path
     +-------+   +------+    +-------+   +-----------+
     |       +-->| .    |--->| ./sub |-->| ./sub/sub |
     |       |   +------+    +-------+   +-----------+
     |       |      ^              ^            ^
     |       |      |              |            |
     |       |      |-----------+  +------+     +------+
     |       |      |           |         |            |
     |       |      |           |         |            |
     |       |   +------+    +------+   +------+    +-------+
     |       +-->|  a.c |--->| b.c  |-->| sa.c  |-->| ssb.c |
     +-------+   +------+    +------+   +------+    +-------+
                  RB_Filename
\end{verbatim}


\textbf{ATTRIBUTES}
\begin{itemize}
  \item    first    --  first RB\_Filename (\ref{ch:robo93}) in the list of files
  \item    current  --  the last file that was returned in
                  RB\_Get\_Next\_Filename.
  \item    last     --  the last RB\_Filename (\ref{ch:robo93}) in the list of files
                   used for the insert operation
  \item    first\_path -- first RB\_Path (\ref{ch:robo194}) in the list of paths.
\end{itemize}


\newpage
\subsubsection{Directory/RB\_Directory\_Insert\_RB\_File}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo68}
\label{ch:Directory_RB_Directory_Insert_RB_File}
\index{unsorted!RB\_Directory\_Insert\_RB\_File}\index{Functions!RB\_Directory\_Insert\_RB\_File}
\textbf{FUNCTION}

   Insert an RB\_File structure into a RB\_Directory (\ref{ch:robo67}) structure.
   The RB\_File is added at the end of the list.

\newpage
\subsubsection{Directory/RB\_Directory\_Insert\_RB\_Path}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo69}
\label{ch:Directory_RB_Directory_Insert_RB_Path}
\index{unsorted!RB\_Directory\_Insert\_RB\_Path}\index{Functions!RB\_Directory\_Insert\_RB\_Path}
\textbf{FUNCTION}

  Insert a RB\_Path (\ref{ch:robo194}) into a RB\_Directory (\ref{ch:robo67}).
  The RB\_Path (\ref{ch:robo194}) is added at the beginning of the list.

\newpage
\subsubsection{Directory/RB\_FileType}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo70}
\label{ch:Directory_RB_FileType}
\index{unsorted!RB\_FileType}\index{Functions!RB\_FileType}
\textbf{FUNCTION}

   Determine the type of the file.  This function is used for all
   compilers except VC++.



   If \_DIRENT\_HAVE\_D\_TYPE is defined we can find the filetype
   directly in the a\_direntry.  If not we have to stat the file to
   find out.

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_pathname -- the path leading up to this file
  \item    a\_direntry -- a directory entry read by readdir()
\end{itemize}


\textbf{RESULT}

   The type of the file.

\newpage
\subsubsection{Directory/RB\_Fill\_Directory}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo71}
\label{ch:Directory_RB_Fill_Directory}
\index{unsorted!RB\_Fill\_Directory}\index{Functions!RB\_Fill\_Directory}
\textbf{NAME}

   RB\_Fill\_Directory -- fill a RB\_Directory (\ref{ch:robo67}) structure

\textbf{FUNCTION}

   Walks through all the files in the directory pointed to
   by arg\_path and adds all the files to arg\_rb\_directory.
   This is a recursive function.

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_rb\_directory  -- the result.
  \item    arg\_path          -- the current path that is scanned.
  \item    arg\_doc\_path      -- the path to the documentation files.
\end{itemize}


\textbf{RESULT}

   a RB\_Directory (\ref{ch:robo67}) structure filled with all sourcefiles and 
   subdirectories in arg\_path.

\textbf{NOTE}

   This a is a recursive function.

\newpage
\subsubsection{Directory/RB\_Free\_RB\_Directory}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo72}
\label{ch:Directory_RB_Free_RB_Directory}
\index{unsorted!RB\_Free\_RB\_Directory}\index{Functions!RB\_Free\_RB\_Directory}
\textbf{FUNCTION}

   Free all the memory use (\ref{ch:robo221}) by the RB\_Directory (\ref{ch:robo67}) structure.

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_directory -- the thing to be freed.
\end{itemize}


\newpage
\subsubsection{Directory/RB\_Get\_FileName}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo73}
\label{ch:Directory_RB_Get_FileName}
\index{unsorted!RB\_Get\_FileName}\index{Functions!RB\_Get\_FileName}
\textbf{NAME}

   RB\_Get\_PathName (\ref{ch:robo74}) -- extract the file name 

\textbf{FUNCTION}

   Given a full path to a file, that is a filename, or a filename
   prefixed with a pathname, return the filename.
   So

\begin{verbatim}
      "./filename"           returns "filename"
      "/home/et/filename"    returns "filename"
      "filename"             return  "filename"
\end{verbatim}


\textbf{INPUTS}

   arg\_fullpath -- a full path to a file, with or without a path.

\textbf{RESULT}

   0  -- The full path did not contain a filename
   pointer to the filename -- otherwise.

\textbf{NOTES}

   You are responsible for deallocating it.

\newpage
\subsubsection{Directory/RB\_Get\_PathName}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo74}
\label{ch:Directory_RB_Get_PathName}
\index{unsorted!RB\_Get\_PathName}\index{Functions!RB\_Get\_PathName}
\textbf{NAME}

   RB\_Get\_PathName -- extract the path name 

\textbf{FUNCTION}

   Given a full path to a file, that is a filename, or a filename
   prefixed with a pathname, return the pathname.
   So

\begin{verbatim}
      "./filename"           returns "./"
      "/home/et/filename"    returns "/home/et/"
      "filename"             return  ""
\end{verbatim}


\textbf{INPUTS}

   arg\_fullpath -- a full path to a file, with or without a path.

\textbf{RESULT}

   0  -- The full path did not contain a path
   pointer to the pathname -- otherwise.

\textbf{NOTES}

   You are responsible for deallocating it.

\newpage
\subsubsection{Directory/RB\_Get\_RB\_Directory}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo75}
\label{ch:Directory_RB_Get_RB_Directory}
\index{unsorted!RB\_Get\_RB\_Directory}\index{Functions!RB\_Get\_RB\_Directory}
\textbf{NAME}

   RB\_Get\_RB\_Directory -- get a RB\_Directory (\ref{ch:robo67}) structure

\textbf{FUNCTION}

   Returns a RB\_Directory (\ref{ch:robo67}) structure to the give directory,
   specified by the path.
   This structure can then be uses to walk through all the
   files in the directory and it's subdirectories.

\textbf{INPUTS}

   arg\_rootpath -- the name a the directory to get,

\begin{verbatim}
                   a nul terminated string.
\end{verbatim}

   arg\_docroot\_name -- the name of the directory the documentation

\begin{verbatim}
                       file are stored in.  This directory is
                       skipped while scanning for sourcefiles.
                       It can be NULL.
\end{verbatim}


\textbf{RESULT}

   A freshly allocated RB\_Directory (\ref{ch:robo67}) filled with source files.

\newpage
\subsubsection{Directory/RB\_Get\_RB\_SingleFileDirectory}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo76}
\label{ch:Directory_RB_Get_RB_SingleFileDirectory}
\index{unsorted!RB\_Get\_RB\_SingleFileDirectory}\index{Functions!RB\_Get\_RB\_SingleFileDirectory}
\textbf{NAME}

   RB\_Get\_RB\_SingleFileDirectory -- get a RB\_Directory (\ref{ch:robo67}) structure

\textbf{FUNCTION}

   Returns a RB\_Directory (\ref{ch:robo67}) structure to the give directory,
   specified by the path that contains only a single file.
   This is used for the --singlefile option.

\textbf{INPUT}
\begin{itemize}
  \item    filename -- a filename.  This may include the path.
\end{itemize}


\textbf{RESULT}

   a freshly allocated RB\_Directory (\ref{ch:robo67}) that contains only
   a single file.

\newpage
\subsubsection{Directory/RB\_Is\_PathCharacter}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo77}
\label{ch:Directory_RB_Is_PathCharacter}
\index{unsorted!RB\_Is\_PathCharacter}\index{Functions!RB\_Is\_PathCharacter}
\textbf{FUNCTION}

   Test if a character is part of the group of
   characters that you would normally find in 
   a path.

\textbf{INPUTS}

   c -- the character to be tested.

\textbf{RESULT}

   TRUE  -- it is a path character.
   FALSE -- it is not.

\newpage
\subsubsection{Directory/RB\_Is\_Source\_File}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo78}
\label{ch:Directory_RB_Is_Source_File}
\index{unsorted!RB\_Is\_Source\_File}\index{Functions!RB\_Is\_Source\_File}
\textbf{NAME}

   RB\_Is\_Source\_File -- Is a file a sourcefile?

\textbf{FUNCTION}

   This functions examines the content of a file to
   see whether or not it is a sourcefile.



   Currently it checks if there are no nul characters
   in the first 8191 characters of the file.

\newpage
\subsubsection{Directory/RB\_Not\_Accepted}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo79}
\label{ch:Directory_RB_Not_Accepted}
\index{unsorted!RB\_Not\_Accepted}\index{Functions!RB\_Not\_Accepted}
\textbf{FUNCTION}

   Test if a file should be skipped, 
   because it does not match a pattern in "accept files:"



   This test is done based on the wildcard expressions specified
   in configuration (\ref{ch:robo51}).accept\_files.

\textbf{INPUTS}
\begin{itemize}
  \item    filename -- the name of the file
\end{itemize}


\newpage
\subsubsection{Directory/RB\_To\_Be\_Skipped}
\textsl{[ Directory ]}
\textsl{[ Functions ]}

\label{ch:robo80}
\label{ch:Directory_RB_To_Be_Skipped}
\index{unsorted!RB\_To\_Be\_Skipped}\index{Functions!RB\_To\_Be\_Skipped}
\textbf{FUNCTION}

   Test if a file should not be included in the list of source files
   that are scanned for documentation. 



   This test is done based on the wildcard expressions specified
   in configuration (\ref{ch:robo51}).ignore\_files.

\textbf{INPUTS}
\begin{itemize}
  \item    filename -- the name of the file
\end{itemize}


\newpage
\subsubsection{Directory/T\_RB\_FileType}
\textsl{[ Directory ]}
\textsl{[ Types ]}

\label{ch:robo81}
\label{ch:Directory_T_RB_FileType}
\index{unsorted!T\_RB\_FileType}\index{Types!T\_RB\_FileType}
\textbf{FUNCTION}

   Constants for the two different filetypes that
   ROBODoc (\ref{ch:robo0}) recognizes.

\newpage
\subsection{ROBODoc/Document}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo5}
\label{ch:ROBODoc_Document}
\index{unsorted!Document}\index{Modules!Document}
\textbf{FUNCTION}

   This module contains functions to manipulate the central data
   structure (RB\_Document (\ref{ch:robo82})) that contains information about the
   source files, and documentation files, and headers.



   The name is a bit confusing because it sort of implies that
   it contains the documentation extracted from the sourcefiles.



   For each run a RB\_Document (\ref{ch:robo82}) structure is created, it is filled
   by the analyser and directory module and then used by the
   generator module to create the documentation.

\textbf{MODIFICATION HISTORY}
\begin{itemize}
  \item    ????-??-??   Frans Slothouber  V1.0
  \item    2003-02-03   Frans Slothouber  Refactoring
  \item    2003-10-30   David White       Removed unistd.h for Borland
\end{itemize}


\newpage
\subsubsection{Document/RB\_Document}
\textsl{[ Document ]}
\textsl{[ Structures ]}

\label{ch:robo82}
\label{ch:Document_RB_Document}
\index{unsorted!RB\_Document}\index{Structures!RB\_Document}
\textbf{NAME}

   RB\_Document -- Information store.

\textbf{FUNCTION}

   A document is a collection of source files and documentation
   files.  Depending on the mode that is used there is either a
   single documentation file or there is one documentation file for
   each source file.  This mapping is stored in RB\_Document.  For
   each source file there is an RB\_Part (\ref{ch:robo191}). It points to the source
   file, the documentation file, and contains all the headers that
   were found in the source file.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item    links    -- linked list of all links.
  \item    parts    -- linked list of all parts.
  \item    no\_headers -- total number of headers
  \item    headers  -- array of pointers to all the headers.
  \item    srctree  -- the list of all sourcefiles in the srcroot.
  \item    doctype  -- the kind of documentation to be generated.
  \item    actions  -- what to de while analysing en generating.
  \item    srcroot  -- root dir for the sourcecode.
  \item    docroot  -- root dir for the documentation.
  \item    charset  -- the character set used for HTML and XML
               documentation.
  \item    first\_section\_level -- level of the first section, 
                            Defaults to 1 so the first section will
                            be 1.
                            If set to 2 the first section will be 1.1
  \item    extension -- the extension used for the documentation
                files.
  \item    css      -- the cascading style sheet to be used.
  \item    cur\_part -- unused   TODO remove.
\end{itemize}


\newpage
\subsubsection{Document/RB\_Document\_Add\_Part}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo83}
\label{ch:Document_RB_Document_Add_Part}
\index{unsorted!RB\_Document\_Add\_Part}\index{Functions!RB\_Document\_Add\_Part}
\textbf{FUNCTION}

   Add a new part to the document.

\textbf{INPUTS}
\begin{itemize}
  \item    document  -- the document the part is to be added to.
  \item    part      -- the part to be added
\end{itemize}


\newpage
\subsubsection{Document/RB\_Document\_Collect\_Headers}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo84}
\label{ch:Document_RB_Document_Collect_Headers}
\index{unsorted!RB\_Document\_Collect\_Headers}\index{Functions!RB\_Document\_Collect\_Headers}
\textbf{FUNCTION}

   Create a table of pointers to all headers.  This is done to
   have easy access to all heades without having to scan all
   RB\_Parts.

\textbf{INPUTS}
\begin{itemize}
  \item    document -- the document for which the table is created.
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    document-$>$headers
  \item    document-$>$no\_headers
\end{itemize}


\newpage
\subsubsection{Document/RB\_Document\_Create\_DocFilePaths}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo85}
\label{ch:Document_RB_Document_Create_DocFilePaths}
\index{unsorted!RB\_Document\_Create\_DocFilePaths}\index{Functions!RB\_Document\_Create\_DocFilePaths}
\textbf{FUNCTION}

   This function creates the whole document directory
   tree.  It tests if the directories exist and if they
   do not the directory is created.

\textbf{INPUTS}
\begin{itemize}
  \item    document -- the document for which the tree is created.
\end{itemize}


\newpage
\subsubsection{Document/RB\_Document\_Create\_Parts}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo86}
\label{ch:Document_RB_Document_Create_Parts}
\index{unsorted!RB\_Document\_Create\_Parts}\index{Functions!RB\_Document\_Create\_Parts}
\textbf{FUNCTION}

   Create all the parts of a document based on the sourcefiles in
   the source tree.  This creates a new RB\_Part (\ref{ch:robo191}) for each file in
   the source tree.

\textbf{INPUTS}
\begin{itemize}
  \item     document -- the document for which the parts are generated.
\end{itemize}


\newpage
\subsubsection{Document/RB\_Document\_Determine\_DocFilePaths}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo87}
\label{ch:Document_RB_Document_Determine_DocFilePaths}
\index{unsorted!RB\_Document\_Determine\_DocFilePaths}\index{Functions!RB\_Document\_Determine\_DocFilePaths}
\textbf{FUNCTION}

   Determine the path of each of the documentation files based on
   the path of the source file and the documentation root path and
   the source root path.

\textbf{EXAMPLE}

   srcpath = ./test/mysrc/sub1/sub2
   srcroot = ./test/mysrc/
   docroot = ./test/mydoc/

\begin{verbatim}
     ==>
\end{verbatim}

   docpath = ./test/mydoc/sub1/sub2

\newpage
\subsubsection{Document/RB\_Fill\_Header\_Filename}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo88}
\label{ch:Document_RB_Fill_Header_Filename}
\index{unsorted!RB\_Fill\_Header\_Filename}\index{Functions!RB\_Fill\_Header\_Filename}
\textbf{FUNCTION}

   Fill the file\_name attribute of all headers based either on the
   part or the singledoc name.   The file\_name tells in which file
   the documentation for the header is to be stored.

\newpage
\subsubsection{Document/RB\_Get\_RB\_Document}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo89}
\label{ch:Document_RB_Get_RB_Document}
\index{unsorted!RB\_Get\_RB\_Document}\index{Functions!RB\_Get\_RB\_Document}
\textbf{FUNCTION}

   Allocate and initialize an RB\_Document (\ref{ch:robo82}) structure.

\textbf{RESULT}

   An initialized document structure.

\newpage
\subsubsection{Document/RB\_Loop\_Check}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo90}
\label{ch:Document_RB_Loop_Check}
\index{unsorted!RB\_Loop\_Check}\index{Functions!RB\_Loop\_Check}
\textbf{FUNCTION}

   This function checks for loops in the headersr; that is
   by mistake the following relation between headers
   can be specified.

\begin{verbatim}
     y.parent -> x.parent -> z.parent -+
     ^                                 |
     |---------------------------------+
\end{verbatim}

   This functions detects these loops, prints a warning
   and breaks the loop.



   If left unbroken ROBODoc (\ref{ch:robo0}) can hang.

\newpage
\subsubsection{Document/RB\_Open\_SingleDocumentation}
\textsl{[ Document ]}
\textsl{[ Functions ]}

\label{ch:robo91}
\label{ch:Document_RB_Open_SingleDocumentation}
\index{unsorted!RB\_Open\_SingleDocumentation}\index{Functions!RB\_Open\_SingleDocumentation}
\textbf{FUNCTION}

   Open the file that will contain the documentation in
   case we create a single document.

\textbf{RESULT}

   An opened file.

\newpage
\subsection{ROBODoc/Filename}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo6}
\label{ch:ROBODoc_Filename}
\index{unsorted!Filename}\index{Modules!Filename}
\textbf{NAME}

   Functions to deal with keeping track
   of filenames and directory names.

\newpage
\subsubsection{Filename/Get\_Fullname}
\textsl{[ Filename ]}
\textsl{[ Functions ]}

\label{ch:robo92}
\label{ch:Filename_Get_Fullname}
\index{unsorted!Get\_Fullname}\index{Functions!Get\_Fullname}
\textbf{NAME}

   Get\_Fullname --

\textbf{FUNCTION}

   Give the full name of the file, that is the name of
   the file including the extension and the path.
   The path can be relative or absolute.

\textbf{NOTE}

   The string returned is owned by this function
   so don't change it.

\newpage
\subsubsection{Filename/RB\_Filename}
\textsl{[ Filename ]}
\textsl{[ Structures ]}

\label{ch:robo93}
\label{ch:Filename_RB_Filename}
\index{unsorted!RB\_Filename}\index{Structures!RB\_Filename}
\textbf{NAME}

   RB\_Filename --

\textbf{ATTRIBUTES}
\begin{itemize}
  \item    next   pointer to the next RB\_File.
  \item    name   null terminated string with the name of the file,
            (Without the path, but including the extension).
  \item    fullname 
  \item    path   pointer to a RB\_Path (\ref{ch:robo194}) structure that holds
            the path for this file.
  \item    link   The link used to represent this file while in multidoc
            mode.
\end{itemize}


\newpage
\subsubsection{Filename/RB\_Get\_Extension}
\textsl{[ Filename ]}
\textsl{[ Functions ]}

\label{ch:robo94}
\label{ch:Filename_RB_Get_Extension}
\index{unsorted!RB\_Get\_Extension}\index{Functions!RB\_Get\_Extension}
\textbf{NAME}

   RB\_Get\_Extension --

\textbf{FUNCTION}

   Give the extension of this file. That is the part after
   the last '.' if there is any.

\textbf{RESULT}

   pointer to the extension
   pointer to a '$\backslash$0' if no extension was found.

\textbf{NOTE}

   The string returned is owned by this function
   so don't change it.

\newpage
\subsubsection{Filename/RB\_Get\_Filename}
\textsl{[ Filename ]}
\textsl{[ Functions ]}

\label{ch:robo95}
\label{ch:Filename_RB_Get_Filename}
\index{unsorted!RB\_Get\_Filename}\index{Functions!RB\_Get\_Filename}
\textbf{NAME}

   RB\_Get\_Filename --

\textbf{FUNCTION}

   Give the name of this file. That is the name
   of the file without its path but with the
   extension.

\textbf{RESULT}

   pointer to the extension
   pointer to a '$\backslash$0' if no extension was found.

\textbf{NOTE}

   The string returned is owned by this function
   so don't change it.

\newpage
\subsubsection{Filename/RB\_Get\_Path}
\textsl{[ Filename ]}
\textsl{[ Functions ]}

\label{ch:robo96}
\label{ch:Filename_RB_Get_Path}
\index{unsorted!RB\_Get\_Path}\index{Functions!RB\_Get\_Path}
\textbf{FUNCTION}

   Give the path for this file.

\textbf{NOTE}

   The string returned is owned by this function
   so don't change it.

\newpage
\subsubsection{Filename/RB\_Get\_RB\_Filename}
\textsl{[ Filename ]}
\textsl{[ Functions ]}

\label{ch:robo97}
\label{ch:Filename_RB_Get_RB_Filename}
\index{unsorted!RB\_Get\_RB\_Filename}\index{Functions!RB\_Get\_RB\_Filename}
\textbf{NAME}

   RB\_Get\_RB\_Filename

\textbf{INPUTS}
\begin{itemize}
  \item    arg\_rb\_filename --
  \item    arg\_rb\_path --
\end{itemize}


\textbf{FUNCTION}

   Create a new RB\_Filename (\ref{ch:robo93}) structure based on arg\_filename and
   arg\_rb\_path.

\newpage
\subsection{ROBODoc/Generator}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo7}
\label{ch:ROBODoc_Generator}
\index{unsorted!Generator}\index{Modules!Generator}
\textbf{FUNCTION}

   This contains routines to generate the documentation from the
   headers collected from the source code.   It contains
   functionality common for all document types (HTML, RTF etc).
   The specifics are handled in the modules for each of the several
   document types.



   The behaviour of many of the functions in this module are
   modified by the global output\_mode (\ref{ch:robo136}).



   The general call sequence is as follows:

\begin{verbatim}
     RB_Generate_Documentation
     +> RB_Generate_SingleDoc
        +> RB_Generate_Part
           +> Generate_Header
                 +> Generate_Item_Line
                    +> Generate_Char
\end{verbatim}


\textbf{BUGS}
\begin{itemize}
  \item    Confusing use (\ref{ch:robo221}) of doctype and output mode.
\end{itemize}


\textbf{NOTES}

   Might be a good idea to replace all the switch statements with
   function pointers.
   So instead of:

\begin{verbatim}
     switch (output_mode)
     {
         case HTML:
             RB_HTML_Generate_Doc_Start(dest_doc, src_name, name, toc);
             break;
         case LATEX:
             RB_LaTeX_Generate_Doc_Start(dest_doc, src_name, name, toc);
             break;
         case RTF:
             RB_RTF_Generate_Doc_Start(dest_doc, src_name, name, toc);
             break;
         case ASCII:
             RB_ASCII_Generate_Doc_Start(dest_doc, src_name, name, toc);
             break;
         case TROFF:
             RB_TROFF_Generate_Doc_Start(dest_doc, src_name, name, toc);
             break;
         default:
             break;
     }
\end{verbatim}

   we will have

\begin{verbatim}
     (*rb_generate_doc_start)(dest_doc, src_name, name, toc);
\end{verbatim}


   were the function pointers are initialized at program start based
   on the output mode.

\newpage
\subsubsection{Generator/Generate\_Char}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo98}
\label{ch:Generator_Generate_Char}
\index{unsorted!Generate\_Char}\index{Functions!Generate\_Char}
\textbf{FUNCTION}

   Generate a single character in the current output mode.
   The individual generators will make sure that special
   characters are escaped.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- destination file.
  \item    cur\_char -- character to be generated.
\end{itemize}


\newpage
\subsubsection{Generator/Generate\_Header}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo99}
\label{ch:Generator_Generate_Header}
\index{unsorted!Generate\_Header}\index{Functions!Generate\_Header}
\textbf{FUNCTION}

   Generate the documentation for all the items found in
   a header except for any items specified in
   configuration (\ref{ch:robo51}).ignore\_items.

\textbf{INPUTS}
\begin{itemize}
  \item    f -- destination file
  \item    header -- header to be searched.
  \item    srcname -- name of the source file the header was found in.
  \item    docname -- name of the documentation file.
\end{itemize}


\textbf{BUGS}

   This skips the first item body if the first item name was
   not correctly spelled.

\newpage
\subsubsection{Generator/Generate\_Index}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo100}
\label{ch:Generator_Generate_Index}
\index{unsorted!Generate\_Index}\index{Functions!Generate\_Index}
\textbf{NAME}

   Generate\_Index -- generate index file based on xref files.

\textbf{FUNCTION}

   Create a master index file. It contains pointers to the
   documentation generated for each source file, as well as all
   "objects" found in the source files.

\newpage
\subsubsection{Generator/Generate\_Item}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo101}
\label{ch:Generator_Generate_Item}
\index{unsorted!Generate\_Item}\index{Functions!Generate\_Item}
\textbf{FUNCTION}

   Generate the documentation for a single item.

\textbf{NOTE}

   This function is way too long...

\newpage
\subsubsection{Generator/Generate\_Item\_Name}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo102}
\label{ch:Generator_Generate_Item_Name}
\index{unsorted!Generate\_Item\_Name}\index{Functions!Generate\_Item\_Name}
\textbf{NAME}

   Generate\_Item\_Name -- fast\&easy

\textbf{FUNCTION}

   write the item's name to the doc

\textbf{INPUTS}
\begin{itemize}
  \item    FILE* dest\_doc      -- destination file
  \item    int item\_type       -- the type of item
\end{itemize}


\textbf{AUTHOR}

   Koessi

\textbf{NOTES}

   uses globals: output\_mode (\ref{ch:robo136})

\newpage
\subsubsection{Generator/Generate\_Label}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo103}
\label{ch:Generator_Generate_Label}
\index{unsorted!Generate\_Label}\index{Functions!Generate\_Label}
\textbf{FUNCTION}

   Generate a label that can be used for a link.
   For instance in HTML this is $<$a name="label"$>$

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- file to be written to
  \item    name -- the label's name.
  \item    output\_mode (\ref{ch:robo136}) -- global with the current output mode
\end{itemize}


\newpage
\subsubsection{Generator/Generate\_Link}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo104}
\label{ch:Generator_Generate_Link}
\index{unsorted!Generate\_Link}\index{Functions!Generate\_Link}
\textbf{FUNCTION}

   Generate a link to another headers documentation.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc      -- the output file
  \item    docname       -- the name of the output file
  \item    file\_name     -- the name of the file that contains the link's body
  \item    label\_name    -- the label for the link
  \item    function\_name -- the name that is shown for the link in the
                      documentation
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Add\_Extension}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo105}
\label{ch:Generator_RB_Add_Extension}
\index{unsorted!RB\_Add\_Extension}\index{Functions!RB\_Add\_Extension}
\textbf{FUNCTION}

   Add an extension to the filename base based on on the current
   output mode.

\textbf{INPUTS}
\begin{itemize}
  \item    doctype -- output mode
  \item    name    -- the name of the file without extension and with
              enough room left to add the extension.
\end{itemize}


\textbf{OUTPUT}

   name    -- the name of the file including the extension.

\newpage
\subsubsection{Generator/RB\_Generate\_BeginSection}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo106}
\label{ch:Generator_RB_Generate_BeginSection}
\index{unsorted!RB\_Generate\_BeginSection}\index{Functions!RB\_Generate\_BeginSection}
\textbf{FUNCTION}

   Generate a section of level depth in the current output mode.
   This is used for the --sections option.  Where each header is
   placed in a section based on the header hierarchy.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc    -- the destination file.
  \item    doctype     -- document type
  \item    depth       -- the level of the section
  \item    name        -- the name of the section
  \item    header      -- pointer to the header structure
  \item    output\_mode (\ref{ch:robo136}) -- global with the current output mode.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_Doc\_End}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo107}
\label{ch:Generator_RB_Generate_Doc_End}
\index{unsorted!RB\_Generate\_Doc\_End}\index{Functions!RB\_Generate\_Doc\_End}
\textbf{NAME}

   RB\_Generate\_Doc\_End -- generate document trailer.

\textbf{FUNCTION}

   Generates for depending on the output\_mode (\ref{ch:robo136}) the text that
   will be at the end of a document.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc - pointer to the file to which the output will
                be written.
  \item    name     - the name of this file.
  \item    output\_mode (\ref{ch:robo136}) - global variable that indicates the output
                   mode.
\end{itemize}


\textbf{NOTES}

   Doesn't do anything with its arguments, but that might
   change in the future.

\textbf{BUGS}
\newpage
\subsubsection{Generator/RB\_Generate\_Doc\_Start}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo108}
\label{ch:Generator_RB_Generate_Doc_Start}
\index{unsorted!RB\_Generate\_Doc\_Start}\index{Functions!RB\_Generate\_Doc\_Start}
\textbf{NAME}

   RB\_Generate\_Doc\_Start -- Generate document header.

\textbf{FUNCTION}

   Generates for depending on the output\_mode (\ref{ch:robo136}) the text that
   will be at the start of a document.
   Including the table of contents.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc - pointer to the file to which the output will
                be written.
  \item    src\_name - the name of the source file or directory.
  \item    name     - the name of this file.
  \item    output\_mode (\ref{ch:robo136}) - global variable that indicates the output
                   mode.
  \item    toc      - generate table of contens
\end{itemize}


\textbf{SEE ALSO}

   RB\_Generate\_Doc\_End (\ref{ch:robo107})

\newpage
\subsubsection{Generator/RB\_Generate\_Documentation}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo109}
\label{ch:Generator_RB_Generate_Documentation}
\index{unsorted!RB\_Generate\_Documentation}\index{Functions!RB\_Generate\_Documentation}
\textbf{FUNCTION}

   Generate the documentation for all the information contained in a
   RB\_Document (\ref{ch:robo82}) structure.

\textbf{INPUTS}

   document -- pointer to the RB\_Document (\ref{ch:robo82}) structure.

\newpage
\subsubsection{Generator/RB\_Generate\_DOT\_Image\_Link}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo110}
\label{ch:Generator_RB_Generate_DOT_Image_Link}
\index{unsorted!RB\_Generate\_DOT\_Image\_Link}\index{Functions!RB\_Generate\_DOT\_Image\_Link}
\textbf{FUNCTION}

   Generates the image link for the created dot graphics

\newpage
\subsubsection{Generator/RB\_Generate\_EndSection}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo111}
\label{ch:Generator_RB_Generate_EndSection}
\index{unsorted!RB\_Generate\_EndSection}\index{Functions!RB\_Generate\_EndSection}
\textbf{FUNCTION}

   Generate the end of a section base on the current output mode.
   The functions is used for the --section option.
   It closes a section in the current output mode.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- the destination file.
  \item    doctype  --
  \item    depth    -- the level of the section
  \item    name     -- the name of the section
  \item    output\_mode (\ref{ch:robo136}) -- global with the current output mode.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_Header\_End}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo112}
\label{ch:Generator_RB_Generate_Header_End}
\index{unsorted!RB\_Generate\_Header\_End}\index{Functions!RB\_Generate\_Header\_End}
\textbf{NAME}

   RB\_Generate\_Header\_End

\textbf{FUNCTION}

   Generates for depending on the output\_mode (\ref{ch:robo136}) the text that
   will be at the end of a header.
   This function is used if the option --section is \_not\_
   used.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc - pointer to the file to which the output will
              be written.
  \item    cur\_header - pointer to a RB\_header (\ref{ch:robo144}) structure.
\end{itemize}


\textbf{SEE ALSO}

   RB\_Generate\_Header\_Start (\ref{ch:robo113}), RB\_Generate\_EndSection (\ref{ch:robo111}),
   RB\_Generate\_BeginSection (\ref{ch:robo106})

\newpage
\subsubsection{Generator/RB\_Generate\_Header\_Start}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo113}
\label{ch:Generator_RB_Generate_Header_Start}
\index{unsorted!RB\_Generate\_Header\_Start}\index{Functions!RB\_Generate\_Header\_Start}
\textbf{NAME}

   RB\_Generate\_Header\_Start -- generate header start text.

\textbf{FUNCTION}

   Generates depending on the output\_mode (\ref{ch:robo136}) the text that
   will be at the end of each header.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc - pointer to the file to which the output will
                be written.
  \item    cur\_header - pointer to a RB\_header (\ref{ch:robo144}) structure.
\end{itemize}


\textbf{SEE ALSO}

   RB\_Generate\_Header\_End (\ref{ch:robo112})

\newpage
\subsubsection{Generator/RB\_Generate\_Index\_Entry}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo114}
\label{ch:Generator_RB_Generate_Index_Entry}
\index{unsorted!RB\_Generate\_Index\_Entry}\index{Functions!RB\_Generate\_Index\_Entry}
\textbf{FUNCTION}

   Generate an entry for an auto generated index.  This works only
   for output modes that support this, LaTeX for instance.   This
   has nothting to do with the master index.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- the destination file.
  \item    header   -- pointer to the header the index entry is for.
  \item    output\_mode (\ref{ch:robo136}) -- global with the current output mode.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_Item\_Begin}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo115}
\label{ch:Generator_RB_Generate_Item_Begin}
\index{unsorted!RB\_Generate\_Item\_Begin}\index{Functions!RB\_Generate\_Item\_Begin}
\textbf{FUNCTION}

   Generate the begin of an item.  This should switch to some
   preformatted output mode, similar to HTML's $<$PRE$>$.

\textbf{INPUTS}

   dest\_doc -- file to be written to
   output\_mode (\ref{ch:robo136}) -- global with the current output mode

\newpage
\subsubsection{Generator/RB\_Generate\_Item\_End}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo116}
\label{ch:Generator_RB_Generate_Item_End}
\index{unsorted!RB\_Generate\_Item\_End}\index{Functions!RB\_Generate\_Item\_End}
\textbf{FUNCTION}

   Generate the end of an item.  This should switch back from the
   preformatted mode.  So in HTML it generates the $<$/PRE$>$ of a $<$PRE$>$
   $<$/PRE$>$ pair.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- file to be written to
  \item    output\_mode (\ref{ch:robo136}) -- global with the current output mode
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_Item\_Line\_Number}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo117}
\label{ch:Generator_RB_Generate_Item_Line_Number}
\index{unsorted!RB\_Generate\_Item\_Line\_Number}\index{Functions!RB\_Generate\_Item\_Line\_Number}
\textbf{FUNCTION}

   Generate line numbers for SOURCE like items

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc    -- the file to write to.
  \item    line\_number (\ref{ch:robo134}) -- the actual line number.
  \item    max\_lines   -- the maximal line number in this item.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_MultiDoc}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo118}
\label{ch:Generator_RB_Generate_MultiDoc}
\index{unsorted!RB\_Generate\_MultiDoc}\index{Functions!RB\_Generate\_MultiDoc}
\textbf{FUNCTION}

   Create documentation by creating a file for each
   individual source file that was scanned.

\textbf{INPUTS}

   document -- pointer to the RB\_Document (\ref{ch:robo82}) structure.

\newpage
\subsubsection{Generator/RB\_Generate\_Part}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo119}
\label{ch:Generator_RB_Generate_Part}
\index{unsorted!RB\_Generate\_Part}\index{Functions!RB\_Generate\_Part}
\textbf{FUNCTION}

   Generate the documention for all the headers found in a single
   source file.

\textbf{INPUTS}
\begin{itemize}
  \item    document\_file -- The file were it stored.
  \item    document      -- All the documentation.
  \item    part          -- pointer to a RB\_Part (\ref{ch:robo191}) that contains all the headers found
                    in a single source file.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_Section}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo120}
\label{ch:Generator_RB_Generate_Section}
\index{unsorted!RB\_Generate\_Section}\index{Functions!RB\_Generate\_Section}
\textbf{FUNCTION}

   Generate the documentation for a header and all
   its childern.

\textbf{INPUTS}
\begin{itemize}
  \item    document\_file -- destination file
  \item    parent -- the parent of the header for which the documentation
               is to be generated.
  \item    document -- pointer to the RB\_Document (\ref{ch:robo82}) structure.
  \item    depth -- level of sectioning ( 1  1.1  1.1.1  etc)
\end{itemize}


\textbf{NOTE}

   This is a recursive function.

\textbf{SEE ALSO}

    RB\_Generate\_Sections (\ref{ch:robo121})

\newpage
\subsubsection{Generator/RB\_Generate\_Sections}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo121}
\label{ch:Generator_RB_Generate_Sections}
\index{unsorted!RB\_Generate\_Sections}\index{Functions!RB\_Generate\_Sections}
\textbf{FUNCTION}

   Creates the documentation for all headers found in all source
   files.  The order in which they are generated depends on the
   header hierarchy.  First the top level header's documentation
   is generated then, the documentation for all it's childern, then
   the next top level header's documentation is generated.
   This is a recursive proces.
   The idea is to create something like:

\begin{verbatim}
     1. Parentheader1
     1.1 Child1
     1.2 Child2
     1.2.1 Child's child1
     2. Parentheader2
\end{verbatim}

   etc

\textbf{INPUTS}
\begin{itemize}
  \item    document\_file -- destination file.
  \item    document -- pointer to the RB\_Document (\ref{ch:robo82}) structure.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Generate\_SingleDoc}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo122}
\label{ch:Generator_RB_Generate_SingleDoc}
\index{unsorted!RB\_Generate\_SingleDoc}\index{Functions!RB\_Generate\_SingleDoc}
\textbf{FUNCTION}

   Create documentation by creating a single file for all individual
   source file that were scanned.



   This function is called when the option --singledoc is used.
   Based on whether the option --sections is used this function then
   calls RB\_Generate\_Sections (\ref{ch:robo121}) or RB\_Generate\_Part (\ref{ch:robo119})

\textbf{INPUTS}

   document -- pointer to the RB\_Document (\ref{ch:robo82}) structure.

\newpage
\subsubsection{Generator/RB\_Generate\_TOC\_2}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo123}
\label{ch:Generator_RB_Generate_TOC_2}
\index{unsorted!RB\_Generate\_TOC\_2}\index{Functions!RB\_Generate\_TOC\_2}
\textbf{FUNCTION}

   Create a Table of Contents based on the headers found in
   \_all\_ source files.   There is also a function to create
   a table of contents based on the headers found in a single
   source file RB\_Generate\_TOC\_1

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- the destination file.
  \item    headers  -- an array of pointers to all the headers.
  \item    count    -- the number of pointers in the array.
  \item    output\_mode (\ref{ch:robo136}) -- global with the current output mode.
  \item    owner    -- The owner of the TOC. Only the headers that are owned
               by this owner are included in the TOC.  Can be NULL,
               in which case all headers are included.
\end{itemize}


\newpage
\subsubsection{Generator/RB\_Get\_DOT\_Type}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo124}
\label{ch:Generator_RB_Get_DOT_Type}
\index{unsorted!RB\_Get\_DOT\_Type}\index{Functions!RB\_Get\_DOT\_Type}
\textbf{FUNCTION}

   Returns the type of the DOT file for the given output mode

\newpage
\subsubsection{Generator/RB\_Get\_SubIndex\_FileName}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo125}
\label{ch:Generator_RB_Get_SubIndex_FileName}
\index{unsorted!RB\_Get\_SubIndex\_FileName}\index{Functions!RB\_Get\_SubIndex\_FileName}
\textbf{FUNCTION}

   Get the name of the master index file for a specific
   header\_type.

\textbf{INPUTS}
\begin{itemize}
  \item    docroot      -- the path to the documentation directory.
  \item    extension    -- the extension for the file
  \item    header\_type  -- the header type
\end{itemize}


\textbf{RESULT}

   a pointer to a freshly allocated string.

\textbf{NOTES}

   Has too many parameters.

\newpage
\subsubsection{Generator/RB\_Name\_Headers}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo126}
\label{ch:Generator_RB_Name_Headers}
\index{unsorted!RB\_Name\_Headers}\index{Functions!RB\_Name\_Headers}
\textbf{FUNCTION}

   Give all headers a unique name. This makes sure that if
   two headers have the same name linking to one of the headers
   still works.

\newpage
\subsubsection{Generator/RB\_Sort\_Items}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo127}
\label{ch:Generator_RB_Sort_Items}
\index{unsorted!RB\_Sort\_Items}\index{Functions!RB\_Sort\_Items}
\textbf{FUNCTION}

   Sort the items in all the headers according to the order
   specified in the 'item order' block in the robodoc.rc
   file.

\newpage
\subsubsection{Generator/RB\_TEST\_Generate\_Char}
\textsl{[ Generator ]}
\textsl{[ Functions ]}

\label{ch:robo128}
\label{ch:Generator_RB_TEST_Generate_Char}
\index{unsorted!RB\_TEST\_Generate\_Char}\index{Functions!RB\_TEST\_Generate\_Char}
\textbf{NAME}

   RB\_TEST\_Generate\_Char

\textbf{FUNCTION}

   Switchboard to RB\_TEST\_Generate\_Char

\newpage
\subsubsection{Generator/T\_RB\_DocType}
\textsl{[ Generator ]}
\textsl{[ Types ]}

\label{ch:robo129}
\label{ch:Generator_T_RB_DocType}
\index{unsorted!T\_RB\_DocType}\index{Types!T\_RB\_DocType}
\textbf{FUNCTION}

   Enumeration for the various output formats that are
   supported by ROBODoc (\ref{ch:robo0}).

\textbf{NOTES}

   These should be prefixed with RB\_ 

\newpage
\subsection{ROBODoc/Globals}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo8}
\label{ch:ROBODoc_Globals}
\index{unsorted!Globals}\index{Modules!Globals}
\textbf{FUNCTION}

   A number of global variables.

\textbf{TODO}

   Documentation.

\newpage
\subsubsection{Globals/course\_of\_action}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo130}
\label{ch:Globals_course_of_action}
\index{unsorted!course\_of\_action}\index{Variables!course\_of\_action}
\textbf{NAME}

   course\_of\_action

\textbf{FUNCTION}

   Global Variable that defines the course of action.

\newpage
\subsubsection{Globals/debugmode}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo131}
\label{ch:Globals_debugmode}
\index{unsorted!debugmode}\index{Variables!debugmode}
\textbf{NAME}

   debugmode

\textbf{FUNCTION}

   A bitfield determining the output levels

\newpage
\subsubsection{Globals/document\_title}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo132}
\label{ch:Globals_document_title}
\index{unsorted!document\_title}\index{Variables!document\_title}
\textbf{NAME}

   documentat\_title -- title for the documentation.

\textbf{PURPOSE}

   Used as the title for master index files or for latex documentation.

\newpage
\subsubsection{Globals/line\_buffer}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo133}
\label{ch:Globals_line_buffer}
\index{unsorted!line\_buffer}\index{Variables!line\_buffer}
\textbf{NAME}

   line\_buffer -- global line buffer

\textbf{FUNCTION}

   Temporary storage area for lines
   that are read from an input file.

\newpage
\subsubsection{Globals/line\_number}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo134}
\label{ch:Globals_line_number}
\index{unsorted!line\_number}\index{Variables!line\_number}
\textbf{NAME}

   line\_number -- global line counter

\textbf{PURPOSE}

   Keeps track of the number of lines that are read from the source file.

\textbf{AUTHOR}

   Koessi

\newpage
\subsubsection{Globals/myLine}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo135}
\label{ch:Globals_myLine}
\index{unsorted!myLine}\index{Variables!myLine}
\textbf{NAME}

   myLine -- dynamic buffer for current line

\textbf{FUNCTION}

   Temporary storage area for lines
   that are read from an input file.

\newpage
\subsubsection{Globals/output\_mode}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo136}
\label{ch:Globals_output_mode}
\index{unsorted!output\_mode}\index{Variables!output\_mode}
\textbf{NAME}

   output\_mode -- the mode of output

\textbf{FUNCTION}

   Controls which type of output will be generated.

\newpage
\subsubsection{Globals/readChars}
\textsl{[ Globals ]}
\textsl{[ Variables ]}

\label{ch:robo137}
\label{ch:Globals_readChars}
\index{unsorted!readChars}\index{Variables!readChars}
\textbf{NAME}

   readChars -- number of characters in the currently bufferd line

\textbf{FUNCTION}

   Temporary storage area for lines
   that are read from an input file.

\newpage
\subsection{ROBODoc/Headers}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo9}
\label{ch:ROBODoc_Headers}
\index{unsorted!Headers}\index{Modules!Headers}
\textbf{FUNCTION}

   This module contains a set of variables that define how headers
   start and how they end in various programming languages.

\textbf{NOTES}

   Added C++/ACM header option (David White)
   Enables documentation only comments (//!) to be extracted from C++ 
   and ACM files, rather than all comments.

\newpage
\subsubsection{Headers/end\_markers}
\textsl{[ Headers ]}
\textsl{[ Variables ]}

\label{ch:robo139}
\label{ch:Headers_end_markers}
\index{unsorted!end\_markers}\index{Variables!end\_markers}
\textbf{NAME}

   end\_markers -- strings that mark the end of a header.

\textbf{FUNCTION}

   These specify what robodoc recognizes as the end of a 
   documentation header. In most cases this will be
   "***" or " ***". If the header contains a SOURCE item
   then the end of the source has to be marked, which
   is when the other strings in this array are used.

\textbf{NOTE}

   The numbers at the beginning of the lines make it easier
   to find a special index-number.

\newpage
\subsubsection{Headers/end\_remark\_constants}
\textsl{[ Headers ]}
\textsl{[ Definitions ]}

\label{ch:robo140}
\label{ch:Headers_end_remark_constants}
\index{unsorted!end\_remark\_constants}\index{Definitions!end\_remark\_constants}
\textbf{NAME}

   end\_remark\_constants -- numerals for end\_markers (\ref{ch:robo139})

\textbf{NOTE}

   Most of them seem to be unused at the moment.  But it's better to
   keep it up to date for the eventuality of a later use (\ref{ch:robo221}) by
   robohdrs.

\newpage
\subsubsection{Headers/end\_remark\_markers}
\textsl{[ Headers ]}
\textsl{[ Variables ]}

\label{ch:robo141}
\label{ch:Headers_end_remark_markers}
\index{unsorted!end\_remark\_markers}\index{Variables!end\_remark\_markers}
\textbf{NAME}

   end\_remark\_markers -- strings that mark the end of a comment.

\textbf{NOTE}

   The numbers at the beginning of the lines make it easier
   to keep them in sync with the end\_remark\_constants (\ref{ch:robo140})

\newpage
\subsubsection{Headers/header\_markers}
\textsl{[ Headers ]}
\textsl{[ Variables ]}

\label{ch:robo142}
\label{ch:Headers_header_markers}
\index{unsorted!header\_markers}\index{Variables!header\_markers}
\textbf{NAME}

   header\_markers -- strings that mark the begin of a header.

\textbf{FUNCTION}

   These specify what robodoc recognizes as the beginning

\textbf{NOTE}

   The numbers at the beginning of the lines make it easier to keep
   them in sync with the src\_constants (\ref{ch:robo151}) of a header.

\newpage
\subsubsection{Headers/RB\_Has\_Remark\_Marker}
\textsl{[ Headers ]}
\textsl{[ Functions ]}

\label{ch:robo143}
\label{ch:Headers_RB_Has_Remark_Marker}
\index{unsorted!RB\_Has\_Remark\_Marker}\index{Functions!RB\_Has\_Remark\_Marker}
\textbf{FUNCTION}

   Check if a line starts with a remark marker.  This function
   assumes that the remark marker starts on the first character of
   the line.

\textbf{INPUTS}
\begin{itemize}
  \item    lline\_buffer -- the line of text.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    TRUE -- it starts with a remark marker
  \item    FALSE -- it does not.
\end{itemize}


\newpage
\subsubsection{Headers/RB\_header}
\textsl{[ Headers ]}
\textsl{[ Structures ]}

\label{ch:robo144}
\label{ch:Headers_RB_header}
\index{unsorted!RB\_header}\index{Structures!RB\_header}
\textbf{FUNCTION}

    This structure is used to store the headers that are extracted
    from the source files.

\textbf{MODIFICATION HISTORY}
\begin{itemize}
  \item     8. August 1995: Koessi changed int version to char *version
  \item     5. December 2007: Budai changed the type of lines from char to
      struct RB\_header\_lines
\end{itemize}


\textbf{ATTRIBUTES}
\begin{itemize}
  \item     next          -- used to store RB\_headers in a RB\_Part (\ref{ch:robo191}) as
                       a linked list.
  \item     parent        -- the parent of this header
  \item     name          -- the full name of the header
                       modulename/functionname [versioninfo]
  \item     owner         -- the Part (\ref{ch:robo14}) that owns this header.
  \item     htype         -- the type of this header.
  \item     items         -- pointers to the items in this header.
  \item     version       -- unused
  \item     function\_name -- the functionname ( a better name would
                       be objectname or  thingy name,
                       it is the name of the thing that is
                       being documented ).
  \item     module\_name   -- the modulename
  \item     unique\_name   -- unique name used for labels.
  \item     file\_name     -- documentation file of this header.
  \item     lines         -- content of the header with line numbers
  \item     no\_lines      -- number of lines in the content.
  \item     line\_number (\ref{ch:robo134})   -- the line number at which the header was
                       found in the source file.
\end{itemize}


\newpage
\subsubsection{RB\_header/RB\_header\_line}
\textsl{[ RB\_header ]}
\textsl{[ Structures ]}

\label{ch:robo192}
\label{ch:RB_header_RB_header_line}
\index{unsorted!RB\_header\_line}\index{Structures!RB\_header\_line}
\textbf{FUNCTION}

    This structure holds the content of one header line and the original
    source line number of it.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item     line\_number (\ref{ch:robo134}) -- The original source file line number for this line
  \item     line        -- The content of the source file line
\end{itemize}


\newpage
\subsubsection{Headers/RB\_HeaderType}
\textsl{[ Headers ]}
\textsl{[ Structures ]}

\label{ch:robo145}
\label{ch:Headers_RB_HeaderType}
\index{unsorted!RB\_HeaderType}\index{Structures!RB\_HeaderType}
\textbf{NAME}

   RB\_HeaderType -- Information about a header type

\textbf{ATTRIBUTES}
\begin{itemize}
  \item    typeCharacter -- The character used to indicate it 
  \item    indexName     -- The name used for the master index 
  \item    fileName      -- The name of the file use (\ref{ch:robo221}) to store 
                      the master index for this type of headers.
  \item    priority      -- The sorting priority of this header.
                      Higher priorities appear first
\end{itemize}


\newpage
\subsubsection{Headers/RB\_Is\_End\_Marker}
\textsl{[ Headers ]}
\textsl{[ Functions ]}

\label{ch:robo146}
\label{ch:Headers_RB_Is_End_Marker}
\index{unsorted!RB\_Is\_End\_Marker}\index{Functions!RB\_Is\_End\_Marker}
\textbf{FUNCTION}

   Scan a line and see if any of the end of a header markers 
   defined in header\_markers (\ref{ch:robo142}) can be found.

\textbf{INPUTS}

   cur\_line -- line to be searched.

\textbf{OUTPUT}

   none

\textbf{RESULT}

   TRUE  -- an end header was found
   FALSE -- none was found.

\newpage
\subsubsection{Headers/RB\_Skip\_Remark\_Marker}
\textsl{[ Headers ]}
\textsl{[ Functions ]}

\label{ch:robo147}
\label{ch:Headers_RB_Skip_Remark_Marker}
\index{unsorted!RB\_Skip\_Remark\_Marker}\index{Functions!RB\_Skip\_Remark\_Marker}
\textbf{NAME}

    RB\_Skip\_Remark\_Marker

\textbf{FUNCTION}

    Scan and search for a recognized remark marker; skip past the
    marker to the body of the text

\newpage
\subsubsection{Headers/remark\_markers}
\textsl{[ Headers ]}
\textsl{[ Variables ]}

\label{ch:robo148}
\label{ch:Headers_remark_markers}
\index{unsorted!remark\_markers}\index{Variables!remark\_markers}
\textbf{NAME}

   remark\_markers

\textbf{FUNCTION}

   These specify what robodoc recognizes as a comment marker.

\textbf{TODO}

   (1) All the markers that start with one or more spaces are
   never recognized, and should be removed.
   (2) The numbers at the beginning of the lines make it easier
   to keep them in sync with the src\_remark\_constants (\ref{ch:robo152})

\newpage
\subsubsection{Headers/robo\_end}
\textsl{[ Headers ]}
\textsl{[ Variables ]}

\label{ch:robo149}
\label{ch:Headers_robo_end}
\index{unsorted!robo\_end}\index{Variables!robo\_end}
\textbf{NAME}

   robo\_end[] -- the distinct robodoc end marker - 

\begin{verbatim}
                 alternative to using end_markers
\end{verbatim}


\textbf{FUNCTION}

   This is an alternative to using end\_markers (\ref{ch:robo139}) - sometimes ROBODOC
   confuses asterisks commonly used in comments as an end marker. To
   use (\ref{ch:robo221}) this footer instead of end\_markers (\ref{ch:robo139}) use (\ref{ch:robo221}) the -rh switch.

\textbf{NOTE}

   Added by David Druffner.

\newpage
\subsubsection{Headers/robo\_header}
\textsl{[ Headers ]}
\textsl{[ Variables ]}

\label{ch:robo150}
\label{ch:Headers_robo_header}
\index{unsorted!robo\_header}\index{Variables!robo\_header}
\textbf{NAME}

   robo\_header -- the distinct robodoc header - 

\begin{verbatim}
                  alternative to using header_markers
\end{verbatim}


\textbf{FUNCTION}

   This is an alternative to using header\_markers (\ref{ch:robo142}) - sometimes
   ROBODOC confuses asterisks commonly used in comments as a header.
   To use (\ref{ch:robo221}) this header instead of header\_markers (\ref{ch:robo142}) use (\ref{ch:robo221}) the -rh switch.

\textbf{NOTE}

   Added by David Druffner.   OBSOLETE

\newpage
\subsubsection{Headers/src\_constants}
\textsl{[ Headers ]}
\textsl{[ Definitions ]}

\label{ch:robo151}
\label{ch:Headers_src_constants}
\index{unsorted!src\_constants}\index{Definitions!src\_constants}
\textbf{NAME}

   src\_constants -- numerals for header\_markers (\ref{ch:robo142})

\textbf{NOTE}

   Most of them seem to be unused at the moment.
   But it's better to keep it up to date for the
   eventuality of a later use (\ref{ch:robo221}) by robohdrs.

\newpage
\subsubsection{Headers/src\_remark\_constants}
\textsl{[ Headers ]}
\textsl{[ Definitions ]}

\label{ch:robo152}
\label{ch:Headers_src_remark_constants}
\index{unsorted!src\_remark\_constants}\index{Definitions!src\_remark\_constants}
\textbf{NAME}

   src\_remark\_constants -- numerals for remark\_markers (\ref{ch:robo148})

\textbf{NOTE}

   Most of them seem to be unused at the moment.
   But it's better to keep it up to date for the
   eventuality of a later use (\ref{ch:robo221}) by robohdrs.

\newpage
\subsection{ROBODoc/HeaderTypes}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo10}
\label{ch:ROBODoc_HeaderTypes}
\index{unsorted!HeaderTypes}\index{Modules!HeaderTypes}
\textbf{FUNCTION}

    Headers (\ref{ch:robo9}) come in different types.  This module defines what kind
    of headertypes ROBODoc (\ref{ch:robo0}) recognizes, and contains functions to add
    new headertypes and to compare headertypes.  All the headertypes
    are stored in an array, header\_type\_lookup\_table (\ref{ch:robo153}).

\newpage
\subsubsection{HeaderTypes/header\_type\_lookup\_table}
\textsl{[ HeaderTypes ]}
\textsl{[ Variables ]}

\label{ch:robo153}
\label{ch:HeaderTypes_header_type_lookup_table}
\index{unsorted!header\_type\_lookup\_table}\index{Variables!header\_type\_lookup\_table}
\textbf{FUNCTION}

   A lookup table for all the header types that ROBODoc (\ref{ch:robo0}) recognizes.
   At the moment is has about 127 entries.  About as many as there
   are characters in the standard ASCII set.  The first 32 entries
   can be used for special purposes.



   Two of them are use (\ref{ch:robo221}):

\begin{verbatim}
     HT_MASTERINDEXTYPE
\end{verbatim}

   and

\begin{verbatim}
     HT_SOURCEHEADERTYPE
\end{verbatim}


   HT\_MASTERINDEXTYPE is a wildcard type. All headertypes match this
   type.  This is used to collect all the headers for the
   masterindex.



   HT\_SOURCEHEADERTYPE is used to pretend that the name of
   a sourcefile is a kind of header.  This makes it possible to
   include the names of the source files in the master index.

\newpage
\subsubsection{HeaderTypes/Is\_Format\_Item}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo154}
\label{ch:HeaderTypes_Is_Format_Item}
\index{unsorted!Is\_Format\_Item}\index{Functions!Is\_Format\_Item}
\textbf{FUNCTION}

   Tells wether this item should be formatted by the browser
 SYNPOPSIS

\textbf{INPUTS}

   item\_type -- Type of item (also the index to the item name)

\textbf{RESULT}

   TRUE  -- Item should be formatted by the browser
   FALSE -- Item should be left alone

\newpage
\subsubsection{HeaderTypes/Is\_Preformatted\_Item}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo155}
\label{ch:HeaderTypes_Is_Preformatted_Item}
\index{unsorted!Is\_Preformatted\_Item}\index{Functions!Is\_Preformatted\_Item}
\textbf{FUNCTION}

   Tells wether this item should be automatically preformatted in the
   output.
 SYNPOPSIS

\textbf{INPUTS}

   item\_type -- Type of item (also the index to the item name)

\textbf{RESULT}

   TRUE  -- Item should be automatically preformatted
   FALSE -- Item should NOT be automatically preformatted

\newpage
\subsubsection{HeaderTypes/RB\_AddHeaderType}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo156}
\label{ch:HeaderTypes_RB_AddHeaderType}
\index{unsorted!RB\_AddHeaderType}\index{Functions!RB\_AddHeaderType}
\textbf{FUNCTION}

   Add a new headertype to the list of header type
   that robodoc recognizes.

\textbf{RESULT}
\begin{itemize}
  \item    FALSE -- it is a new header type.
  \item    TRUE  -- header type already existed.
\end{itemize}


\newpage
\subsubsection{HeaderTypes/RB\_CompareHeaderTypes}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo157}
\label{ch:HeaderTypes_RB_CompareHeaderTypes}
\index{unsorted!RB\_CompareHeaderTypes}\index{Functions!RB\_CompareHeaderTypes}
\textbf{FUNCTION}

   Compare two header types and check if they are equal.  If one of
   the header types is a HT\_MASTERINDEXTYPE the comparison is always
   TRUE.  (This to make sure that all headers appear in the Index.)

\textbf{INPUTS}
\begin{itemize}
  \item     ht1 and ht2 -- the header types to compare.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item     0     -- header types are not equal
  \item     != 0  -- header type are equal
\end{itemize}


\newpage
\subsubsection{HeaderTypes/RB\_FindHeaderType}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo158}
\label{ch:HeaderTypes_RB_FindHeaderType}
\index{unsorted!RB\_FindHeaderType}\index{Functions!RB\_FindHeaderType}
\textbf{FUNCTION}

   Return the header type that corresponds to the type character.

\textbf{RESULT}
\begin{itemize}
  \item    0  -- there is no such header type
  \item    pointer to the header type otherwise.
\end{itemize}


\newpage
\subsubsection{HeaderTypes/RB\_IsInternalHeader}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo159}
\label{ch:HeaderTypes_RB_IsInternalHeader}
\index{unsorted!RB\_IsInternalHeader}\index{Functions!RB\_IsInternalHeader}
\textbf{FUNCTION}

   Given the typeCharacter is this an internal header?

\textbf{RESULT}
\begin{itemize}
  \item    TRUE  -- yes it is
  \item    FALSE -- no it is not
\end{itemize}


\newpage
\subsubsection{HeaderTypes/Works\_Like\_SourceItem}
\textsl{[ HeaderTypes ]}
\textsl{[ Functions ]}

\label{ch:robo160}
\label{ch:HeaderTypes_Works_Like_SourceItem}
\index{unsorted!Works\_Like\_SourceItem}\index{Functions!Works\_Like\_SourceItem}
\textbf{FUNCTION}

   Tells wether this item works similar to the
   source item, that is weather it copies it's
   content verbatim to the output document.
 SYNPOPSIS

\textbf{INPUTS}

   item\_type -- Type of item (also the index to the item name)

\textbf{RESULT}

   TRUE  -- Item works like a SOURCE item
   FALSE -- Item does NOT work like a SOURCE item

\newpage
\subsection{ROBODoc/HTML\_Generator}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo11}
\label{ch:ROBODoc_HTML_Generator}
\index{unsorted!HTML\_Generator}\index{Modules!HTML\_Generator}
\textbf{FUNCTION}

   The generator for HTML output.



   The generator supports sections upto 7 levels deep.  It supports
   a Table of Contents based on all headers.  A masterindex for
   all headertypes and seperate masterindexes for each headertype.

\textbf{MODIFICATION HISTORY}

   2003-02-03   Frans Slothouber  Refactoring
   ????-??-??   Frans Slothouber  V1.0

\newpage
\subsubsection{HTML\_Generator/RB\_Create\_CSS}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo161}
\label{ch:HTML_Generator_RB_Create_CSS}
\index{unsorted!RB\_Create\_CSS}\index{Functions!RB\_Create\_CSS}
\textbf{FUNCTION}

   Create the .css file.  Unless the user specified it's own css
   file robodoc creates a default one.



   For multidoc mode the name of the .css file is

\begin{verbatim}
      robodoc.css
\end{verbatim}

   For singledoc mode the name of the .css file is equal
   to the name of the documentation file.

\textbf{INPUTS}
\begin{itemize}
  \item    document -- the document for which to create the file.
\end{itemize}


\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Color\_String}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo162}
\label{ch:HTML_Generator_RB_HTML_Color_String}
\index{unsorted!RB\_HTML\_Color\_String}\index{Functions!RB\_HTML\_Color\_String}
\textbf{FUNCTION}

   Generates various colored strings

\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Char}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo163}
\label{ch:HTML_Generator_RB_HTML_Generate_Char}
\index{unsorted!RB\_HTML\_Generate\_Char}\index{Functions!RB\_HTML\_Generate\_Char}
\textbf{NAME}

   RB\_HTML\_Generate\_Char -- generate a single character for an item.

\textbf{FUNCTION}

   This function is called for every character that goes
   into an item's body.  This escapes all the reserved
   HTML characters such as '\&', '$<$', '$>$', '"'.

\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Doc\_Start}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo164}
\label{ch:HTML_Generator_RB_HTML_Generate_Doc_Start}
\index{unsorted!RB\_HTML\_Generate\_Doc\_Start}\index{Functions!RB\_HTML\_Generate\_Doc\_Start}
\textbf{NAME}

   RB\_HTML\_Generate\_Doc\_Start --

\textbf{FUNCTION}

   Generate the first part of a HTML document.
   As far as ROBODoc (\ref{ch:robo0}) is concerned a HTML document
   consists of three parts:

\begin{itemize}
  \item    The start of a document
  \item    The body of a document
  \item    The end of a document
\end{itemize}


\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc  --  the output file.
  \item    src\_name  --  The file or directoryname from which 
                   this document is generated.
  \item    name      --  The title for this document
  \item    dest\_name --  the name of the output file.
  \item    charset   --  the charset to be used for the file.
\end{itemize}


\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Extra}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo165}
\label{ch:HTML_Generator_RB_HTML_Generate_Extra}
\index{unsorted!RB\_HTML\_Generate\_Extra}\index{Functions!RB\_HTML\_Generate\_Extra}
\textbf{FUNCTION}

   Do some additional processing to detect HTML extra's like
   file references and other kind of links for the documentation
   body of an item.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc  -- the file to write to.
  \item    item\_type -- the kind of item the body belongs to.
  \item    cur\_char  -- pointer to a substring of the item's body
  \item    prev\_char -- the character just before cur char (zero if none)
\end{itemize}


\textbf{RESULTS}

   Number of characters produced.

\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Index\_Page}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo166}
\label{ch:HTML_Generator_RB_HTML_Generate_Index_Page}
\index{unsorted!RB\_HTML\_Generate\_Index\_Page}\index{Functions!RB\_HTML\_Generate\_Index\_Page}
\textbf{FUNCTION}

   Generate a single file with a index table for headers
   of one specific type of headers

\textbf{INPUTS}
\begin{itemize}
  \item    document    -- the document
  \item    header\_type -- the type for which the table is to
                    be generated.
\end{itemize}


\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_IndexMenu}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo167}
\label{ch:HTML_Generator_RB_HTML_Generate_IndexMenu}
\index{unsorted!RB\_HTML\_Generate\_IndexMenu}\index{Functions!RB\_HTML\_Generate\_IndexMenu}
\textbf{FUNCTION}

   Generates a menu to jump to the various master index files for
   the various header types.  The menu is generated for each of the
   master index files.  The current header type is highlighted.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc       -- the output file.
  \item    filename       -- the name of the output file
  \item    document       -- the gathered documention.
  \item    cur\_headertype -- the header type that is to be highlighted.
\end{itemize}


\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Item\_Line\_Number}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo168}
\label{ch:HTML_Generator_RB_HTML_Generate_Item_Line_Number}
\index{unsorted!RB\_HTML\_Generate\_Item\_Line\_Number}\index{Functions!RB\_HTML\_Generate\_Item\_Line\_Number}
\textbf{FUNCTION}

   Generate line numbers for SOURCE like items

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc           -- the file to write to.
  \item    line\_number\_string -- the line number as string.
\end{itemize}


\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Label}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo169}
\label{ch:HTML_Generator_RB_HTML_Generate_Label}
\index{unsorted!RB\_HTML\_Generate\_Label}\index{Functions!RB\_HTML\_Generate\_Label}
\textbf{FUNCTION}

   Generate a label (name) that can be refered too.
   A label should consist of only alphanumeric characters so
   all 'odd' characters are replaced with their ASCII code in
   hex format.

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc -- the file to write it to.
  \item    name     -- the name of the label.
\end{itemize}


\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Line\_Comment\_End}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo170}
\label{ch:HTML_Generator_RB_HTML_Generate_Line_Comment_End}
\index{unsorted!RB\_HTML\_Generate\_Line\_Comment\_End}\index{Functions!RB\_HTML\_Generate\_Line\_Comment\_End}
\textbf{FUNCTION}

   Check if a line comment is active and generate ending sequence for it.
   Should be called at the end of each SOURCE line.

\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_Link}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo171}
\label{ch:HTML_Generator_RB_HTML_Generate_Link}
\index{unsorted!RB\_HTML\_Generate\_Link}\index{Functions!RB\_HTML\_Generate\_Link}
\textbf{NAME}

   RB\_HTML\_Generate\_Link --

\textbf{INPUTS}

   cur\_doc  --  the file to which the text is written
   cur\_name --  the name of the destination file

\begin{verbatim}
                (the file from which we link)
\end{verbatim}

   filename --  the name of the file that contains the link

\begin{verbatim}
                (the file we link to)
\end{verbatim}

   labelname--  the name of the unique label of the link.
   linkname --  the name of the link as shown to the user.

\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_Generate\_TOC\_Section}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo172}
\label{ch:HTML_Generator_RB_HTML_Generate_TOC_Section}
\index{unsorted!RB\_HTML\_Generate\_TOC\_Section}\index{Functions!RB\_HTML\_Generate\_TOC\_Section}
\textbf{FUNCTION}

   Create a table of contents based on the hierarchy of
   the headers starting for a particular point in this
   hierarchy (the parent).

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc  -- the file to write to.
  \item    dest\_name -- the name of this file.
  \item    parent    -- the parent of the headers for which the the
                  current level(depth) of TOC is created.
  \item    headers   -- an array of headers for which the TOC is created
  \item    count     -- the number of headers in this array
  \item    depth     -- the current depth of the TOC
\end{itemize}


\textbf{NOTES}

   This is a recursive function and tricky stuff.

\newpage
\subsubsection{HTML\_Generator/RB\_HTML\_RelativeAddress}
\textsl{[ HTML\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo173}
\label{ch:HTML_Generator_RB_HTML_RelativeAddress}
\index{unsorted!RB\_HTML\_RelativeAddress}\index{Functions!RB\_HTML\_RelativeAddress}
\textbf{FUNCTION}

   Link to 'that' from 'this' computing the relative path.  Here
   'this' and 'that' are both paths.  This function is used to
   create links from one document to another document that might be
   in a completely different directory.

\textbf{EXAMPLE}

   The following two

\begin{verbatim}
     this /sub1/sub2/sub3/f.html
     that /sub1/sub2/g.html
\end{verbatim}

   result in 

\begin{verbatim}
     ../g.html
\end{verbatim}



\begin{verbatim}
     this /sub1/f.html
     that /sub1/sub2/g.html
     ==
     ./sub2/g.html
\end{verbatim}



\begin{verbatim}
     this /sub1/f.html
     that /sub1/g.html
     ==
     ./g.html
\end{verbatim}



\begin{verbatim}
     this /sub1/doc3/doc1/tt.html
     that /sub1/doc5/doc2/qq.html
     ==
     ../../doc5/doc2/qq.html
\end{verbatim}


\textbf{NOTES}

   Notice the execelent docmentation.

\newpage
\subsection{ROBODoc/Items}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo12}
\label{ch:ROBODoc_Items}
\index{unsorted!Items}\index{Modules!Items}
\textbf{FUNCTION}

   This module contains functions that deal with items.  The
   documentation consists of headers, and headers contains one of
   more items.  Each item has a name and a body.  All possible items
   are listed in configuration (\ref{ch:robo51}).items.  A uses can specify that
   certain items are not to be added to the documentation.  These
   items are listed in configuration (\ref{ch:robo51}).ignore\_items.

\textbf{AUTHOR}

   Frans Slothouber

\newpage
\subsubsection{Items/item\_name\_buffer}
\textsl{[ Items ]}
\textsl{[ Variables ]}

\label{ch:robo174}
\label{ch:Items_item_name_buffer}
\index{unsorted!item\_name\_buffer}\index{Variables!item\_name\_buffer}
\textbf{FUNCTION}

   Stores the name of the last item that was found.

\newpage
\subsubsection{Items/ItemLineKind}
\textsl{[ Items ]}
\textsl{[ Structures ]}

\label{ch:robo175}
\label{ch:Items_ItemLineKind}
\index{unsorted!ItemLineKind}\index{Structures!ItemLineKind}
\textbf{FUNCTION}

   Holds the type of an item line

\newpage
\subsubsection{Items/ItemTypes}
\textsl{[ Items ]}
\textsl{[ Types ]}

\label{ch:robo176}
\label{ch:Items_ItemTypes}
\index{unsorted!ItemTypes}\index{Types!ItemTypes}
\textbf{NAME}

   ItemTypes -- enumeration of item types

\textbf{FUNCTION}

   Defines a number of item types. There are two kind of items:

\begin{itemize}
  \item    the SOURCE item which is always available,
  \item    and items defined by the user (or through the default items).
\end{itemize}


\textbf{NOTES}

   Never check an item type against SOURCECODE\_ITEM directily!
   Use Works\_Like\_SourceItem (\ref{ch:robo160})() function instead.

\newpage
\subsubsection{Items/RB\_Create\_Item}
\textsl{[ Items ]}
\textsl{[ Functions ]}

\label{ch:robo177}
\label{ch:Items_RB_Create_Item}
\index{unsorted!RB\_Create\_Item}\index{Functions!RB\_Create\_Item}
\newpage
\subsubsection{Items/RB\_Get\_Item\_Type}
\textsl{[ Items ]}
\textsl{[ Functions ]}

\label{ch:robo178}
\label{ch:Items_RB_Get_Item_Type}
\index{unsorted!RB\_Get\_Item\_Type}\index{Functions!RB\_Get\_Item\_Type}
\textbf{FUNCTION}

   return the item\_type represented by the given string.

\textbf{INPUTS}

   char *cmp\_name -- item\_name to evaluate

\textbf{RESULT}

   int            -- the right item\_type or NO\_ITEM

\newpage
\subsubsection{Items/RB\_Is\_ItemName}
\textsl{[ Items ]}
\textsl{[ Functions ]}

\label{ch:robo179}
\label{ch:Items_RB_Is_ItemName}
\index{unsorted!RB\_Is\_ItemName}\index{Functions!RB\_Is\_ItemName}
\textbf{FUNCTION}

   Is there an itemname in the line.  Ignores leading spaces and
   remark markers.

\textbf{INPUTS}

   line -- line to be searched.

\textbf{RESULT}

   The kind of item that was found or NO\_ITEM if no item could be found.
   The name of the item will be stored in item\_name\_buffer (\ref{ch:robo174}).

\textbf{NOTES}

   We used to check for misspelled items names by testing if
   the item name buffer consists of only upper case characters.
   However checking for a misspelled item name this way results in
   many false positives. For instance many warnings are given for
   FORTRAN code as all the keywords are in uppercase.  We need to
   find a better method for this.

\newpage
\subsubsection{Items/RB\_Item}
\textsl{[ Items ]}
\textsl{[ Structures ]}

\label{ch:robo180}
\label{ch:Items_RB_Item}
\index{unsorted!RB\_Item}\index{Structures!RB\_Item}
\textbf{FUNCTION}

   Keeps track of where items start end end in the header.
   The index numbers point to the lines array in
   RB\_header (\ref{ch:robo144}).

\newpage
\subsubsection{Items/RB\_Item\_Line}
\textsl{[ Items ]}
\textsl{[ Structures ]}

\label{ch:robo181}
\label{ch:Items_RB_Item_Line}
\index{unsorted!RB\_Item\_Line}\index{Structures!RB\_Item\_Line}
\textbf{FUNCTION}

   Holds the attributes and the content of an item line

\textbf{ATTRIBUTES}
\begin{itemize}
  \item     line        -- The contents of the item line
  \item     kind        -- The type of the line (see: ItemLineKind (\ref{ch:robo175}))
  \item     format      -- Formatting attributes for the line
  \item     pipe\_mode   -- The output mode
  \item     line\_number (\ref{ch:robo134}) -- The original source line number of the line
\end{itemize}


\newpage
\subsection{ROBODoc/Links}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo13}
\label{ch:ROBODoc_Links}
\index{unsorted!Links}\index{Modules!Links}
\textbf{FUNCTION}

   This module contains functions to manipulate links.
   Links are derived from headers.  They are used to create
   links in the documentation between a word and the part of
   the documentation that explains something about that word.
   (For instance a function name or variable name).
   In addition to the links derived from the headers links are
   also derived from the names of all the sourcefiles.

\textbf{MODIFICATION HISTORY}

   ????-??-??   Frans Slothouber  V1.0 
   2003-02-03   Frans Slothouber  Refactoring

\newpage
\subsubsection{Links/Find\_Link}
\textsl{[ Links ]}
\textsl{[ Functions ]}

\label{ch:robo182}
\label{ch:Links_Find_Link}
\index{unsorted!Find\_Link}\index{Functions!Find\_Link}
\textbf{NAME}

   Find\_Link -- try to match word with a link

\textbf{FUNCTION}

   Searches for the given word in the list of links and
   headers.  There are three passes (or four, when the C option
   is selected). Each pass uses a different definition of "word":

\begin{itemize}
  \item    In the first pass it is any thing that ends with a 'space', a '.' 
     or a ','.
  \item    In the second pass it is any string that consists of alpha
     numerics, '\_', ':', '.', or '-'.  
  \item    In the third pass (for C) it is any string that consists 
     of alpha numerics or '\_'.
\end{itemize}


\textbf{INPUTS}
\begin{itemize}
  \item    word\_begin  - pointer to a word (a string).
  \item    object\_name  - pointer to a pointer to a string
  \item    file\_name   - pointer to a pointer to a string
\end{itemize}


\textbf{SIDE EFFECTS}

   label\_name \& file\_name are modified

\textbf{RESULT}
\begin{itemize}
  \item    object\_name   -- points to the object if a match was found,
                      NULL otherwise.
  \item    file\_name     -- points to the file name if a match was found,
                      NULL otherwise.
  \item    label\_name    -- points to the labelname if a match was found,
  \item    TRUE          -- a match was found.
  \item    FALSE         -- no match was found.
\end{itemize}


\textbf{NOTES}

   This is a rather sensitive algorithm. Don't mess with it
   too much.

\newpage
\subsubsection{Links/RB\_Alloc\_Link}
\textsl{[ Links ]}
\textsl{[ Functions ]}

\label{ch:robo183}
\label{ch:Links_RB_Alloc_Link}
\index{unsorted!RB\_Alloc\_Link}\index{Functions!RB\_Alloc\_Link}
\textbf{NAME}

   RB\_Alloc\_Link              -- oop

\textbf{FUNCTION}

   allocate struct + strings

\textbf{INPUTS}

   char *label\_name -- strings to copy into the link
   char *file\_name

\textbf{RESULT}

   struct RB\_link (\ref{ch:robo187}) *  -- ready-to-use (\ref{ch:robo221})

\textbf{AUTHOR}

   Koessi

\textbf{SEE ALSO}

   RB\_StrDup(), RB\_Free\_Link (\ref{ch:robo185})()

\newpage
\subsubsection{Links/RB\_CollectLinks}
\textsl{[ Links ]}
\textsl{[ Functions ]}

\label{ch:robo184}
\label{ch:Links_RB_CollectLinks}
\index{unsorted!RB\_CollectLinks}\index{Functions!RB\_CollectLinks}
\textbf{FUNCTION}

   Convert header information into link information.

\begin{verbatim}
      RB_header -> RB_link conversion
\end{verbatim}


\textbf{INPUTS}
\begin{itemize}
  \item    document -- 
  \item    headers  -- the array with headers.
  \item    count    -- number of headers in the array
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    link\_index -- an array with links
  \item    link\_index\_size -- the number of links in the array.
\end{itemize}


\newpage
\subsubsection{Links/RB\_Free\_Link}
\textsl{[ Links ]}
\textsl{[ Functions ]}

\label{ch:robo185}
\label{ch:Links_RB_Free_Link}
\index{unsorted!RB\_Free\_Link}\index{Functions!RB\_Free\_Link}
\textbf{NAME}

   RB\_Free\_Link               -- oop

\textbf{FUNCTION}

   free struct + strings

\textbf{INPUTS}

   struct RB\_link (\ref{ch:robo187}) *link

\textbf{AUTHOR}

   Koessi

\textbf{SEE ALSO}

   RB\_Alloc\_Link (\ref{ch:robo183})(), RB\_Close\_The\_Shop()

\newpage
\subsubsection{Links/RB\_Free\_Links}
\textsl{[ Links ]}
\textsl{[ Functions ]}

\label{ch:robo186}
\label{ch:Links_RB_Free_Links}
\index{unsorted!RB\_Free\_Links}\index{Functions!RB\_Free\_Links}
\textbf{FUNCTION}

   Deallocate all the memory used to store the links.

\textbf{INPUTS}
\begin{itemize}
  \item    link\_index\_size
  \item    link\_index[]
\end{itemize}


\textbf{BUGS}

   Should use (\ref{ch:robo221}) RB\_Free\_Link (\ref{ch:robo185}) instead of doing
   everything by it self.

\newpage
\subsubsection{Links/RB\_link}
\textsl{[ Links ]}
\textsl{[ Structures ]}

\label{ch:robo187}
\label{ch:Links_RB_link}
\index{unsorted!RB\_link}\index{Structures!RB\_link}
\textbf{NAME}

    RB\_link -- link data structure

\textbf{PURPOSE}

    Structure to store links to the documentation of an component.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item     label\_name  -- the label under which the component can be found.
                     this should be a unique name.
  \item     object\_name -- the proper name of the object
  \item     file\_name   -- the file the component can be found in.
  \item     type        -- the type of component (the header type).
  \item     is\_internal -- is the header an internal header?
\end{itemize}


\newpage
\subsection{ROBODoc/Part}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo14}
\label{ch:ROBODoc_Part}
\index{unsorted!Part}\index{Modules!Part}
\textbf{FUNCTION}

   Structures and functions that deal with documentation parts.  A
   part links a sourcefile to the documentation file and contains
   all the headers found in a sourcefile.  Parts (in the form of
   struct RB\_Part (\ref{ch:robo191})) are stored in a RB\_Document (\ref{ch:robo82}) structure.

\newpage
\subsubsection{Part/RB\_Free\_RB\_Part}
\textsl{[ Part ]}
\textsl{[ Functions ]}

\label{ch:robo188}
\label{ch:Part_RB_Free_RB_Part}
\index{unsorted!RB\_Free\_RB\_Part}\index{Functions!RB\_Free\_RB\_Part}
\textbf{FUNCTION}

   Free the memory used by an RB\_Part (\ref{ch:robo191}).  Most of this is handled in
   other functions.

\textbf{INPUTS}
\begin{itemize}
  \item    part  -- the part to be freed.
\end{itemize}


\newpage
\subsubsection{Part/RB\_Get\_RB\_Part}
\textsl{[ Part ]}
\textsl{[ Functions ]}

\label{ch:robo189}
\label{ch:Part_RB_Get_RB_Part}
\index{unsorted!RB\_Get\_RB\_Part}\index{Functions!RB\_Get\_RB\_Part}
\textbf{FUNCTION}

   Create a new RB\_Part (\ref{ch:robo191}) and initialize it.

\textbf{RESULT}

   A freshly allocated and initializedand RB\_Part (\ref{ch:robo191}).

\newpage
\subsubsection{Part/RB\_Open\_Source}
\textsl{[ Part ]}
\textsl{[ Functions ]}

\label{ch:robo190}
\label{ch:Part_RB_Open_Source}
\index{unsorted!RB\_Open\_Source}\index{Functions!RB\_Open\_Source}
\textbf{FUNCTION}

   Open the sourcefile of this part.

\textbf{INPUTS}
\begin{itemize}
  \item    part -- the part for which the file is opened.
\end{itemize}


\newpage
\subsubsection{Part/RB\_Part}
\textsl{[ Part ]}
\textsl{[ Structures ]}

\label{ch:robo191}
\label{ch:Part_RB_Part}
\index{unsorted!RB\_Part}\index{Structures!RB\_Part}
\textbf{NAME}

   RB\_Part -- a part of the total documentation

\textbf{FUNCTION}

   RB\_Parts are stored in RB\_Document (\ref{ch:robo82}).  For each source file there
   is an RB\_Part. It points to the source file, the documentation
   file, and contains all the headers that were found in the source
   file.

\textbf{ATTRIBUTES}
\begin{itemize}
  \item    next                   -- pointer to the next part
                             (to form a linked list).
  \item    filename               -- Information over the path to the
                             sourcefile and the correcsponding 
                             documentation file.
  \item    headers                -- All the headers that were
                             found in the sourcefile.
  \item    last\_header            -- pointer to the last element in the
                             list of headers.
                             This is used to make it possible
                             to add the the heades in the 
                             same order as they were found in
                             the source file.
\end{itemize}


\newpage
\subsection{ROBODoc/RTF\_Generator}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo15}
\label{ch:ROBODoc_RTF_Generator}
\index{unsorted!RTF\_Generator}\index{Modules!RTF\_Generator}
\textbf{FUNCTION}

   A collection of functions to generate output in RTF format.
   Supports sections upto 7 levels deep.

\textbf{TODO}

   Documentation

\textbf{MODIFICATION HISTORY}

   ????-??-??   Anthon Pang       V1.0
   2003-02-03   Frans Slothouber  Refactoring
   Anthon Pang

\newpage
\subsubsection{RTF\_Generator/RB\_RTF\_Generate\_Item\_Line\_Number}
\textsl{[ RTF\_Generator ]}
\textsl{[ Functions ]}

\label{ch:robo195}
\label{ch:RTF_Generator_RB_RTF_Generate_Item_Line_Number}
\index{unsorted!RB\_RTF\_Generate\_Item\_Line\_Number}\index{Functions!RB\_RTF\_Generate\_Item\_Line\_Number}
\textbf{FUNCTION}

   Generate line numbers for SOURCE like items

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc           -- the file to write to.
  \item    line\_number\_string -- the line number as string.
\end{itemize}


\newpage
\subsection{ROBODoc/Test\_Generator}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo16}
\label{ch:ROBODoc_Test_Generator}
\index{unsorted!Test\_Generator}\index{Modules!Test\_Generator}
\textbf{FUNCTION}

   The generator for test output.



   The purpose of this generator is to create output that is easily
   scanable by the system test scripts.  This to make it easier to
   write tests for ROBODoc (\ref{ch:robo0}).



   This generator produces output in utf-8 encoding.



   This generator is experimental.

\newpage
\subsection{ROBODoc/UserInterface}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo17}
\label{ch:ROBODoc_UserInterface}
\index{unsorted!UserInterface}\index{Modules!UserInterface}
\textbf{FUNCTION}

   This module contains functions to parse the
   command line and inform the user about any errors.

\newpage
\subsubsection{UserInterface/Add\_Option\_Name}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo196}
\label{ch:UserInterface_Add_Option_Name}
\index{unsorted!Add\_Option\_Name}\index{Functions!Add\_Option\_Name}
\textbf{FUNCTION}

   Add the name of an option to the group of option names an option
   test applies to.

\textbf{INPUTS}

   option\_test -- the option test
   name -- the name of the option

\newpage
\subsubsection{UserInterface/Add\_Option\_Test}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo197}
\label{ch:UserInterface_Add_Option_Test}
\index{unsorted!Add\_Option\_Test}\index{Functions!Add\_Option\_Test}
\textbf{FUNCTION}

   Add a test to the linked list of options tests.

\textbf{INPUTS}

   option\_test -- the test to be added.

\newpage
\subsubsection{UserInterface/Check\_Item\_Options}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo198}
\label{ch:UserInterface_Check_Item_Options}
\index{unsorted!Check\_Item\_Options}\index{Functions!Check\_Item\_Options}
\textbf{FUNCTION}

   Check the validity of the item options.  Users can specify their
   own items, item order, and items that ar to be ignored.  This all
   should be consistent.

\textbf{RESULT}
\begin{itemize}
  \item    EXIT\_SUCCESS -- all options are correct.
  \item    EXIT\_FAILURE -- one of more options incorrect.
\end{itemize}


\newpage
\subsubsection{UserInterface/Check\_Option\_Spelling}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo199}
\label{ch:UserInterface_Check_Option_Spelling}
\index{unsorted!Check\_Option\_Spelling}\index{Functions!Check\_Option\_Spelling}
\textbf{FUNCTION}

   Check for misspelled options specified by the user.

\textbf{RESULT}
\begin{itemize}
  \item    EXIT\_SUCCESS -- all options are correctly spelled.
  \item    EXIT\_FAILURE -- one of more options are misspelled.
\end{itemize}


\newpage
\subsubsection{UserInterface/Check\_Options}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo200}
\label{ch:UserInterface_Check_Options}
\index{unsorted!Check\_Options}\index{Functions!Check\_Options}
\textbf{FUNCTION}

   Check the validity of all the options in configuration (\ref{ch:robo51}).options[].
   This runs a number of checks.

\textbf{RESULT}
\begin{itemize}
  \item    EXIT\_SUCCESS -- all options are correct.
  \item    EXIT\_FAILURE -- one of more options incorrect.
\end{itemize}


\newpage
\subsubsection{UserInterface/copying}
\textsl{[ UserInterface ]}
\textsl{[ Variables ]}

\label{ch:robo201}
\label{ch:UserInterface_copying}
\index{unsorted!copying}\index{Variables!copying}
\textbf{FUNCTION}

   Information about the ROBODoc (\ref{ch:robo0}) licence.

\textbf{AUTHOR}

   Frans

\newpage
\subsubsection{UserInterface/Create\_New\_Option\_Test}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo202}
\label{ch:UserInterface_Create_New_Option_Test}
\index{unsorted!Create\_New\_Option\_Test}\index{Functions!Create\_New\_Option\_Test}
\textbf{FUNCTION}

   Allocate and initialize a new option test.

\textbf{INPUTS}

   kind -- the kind of test that has to be created.

\newpage
\subsubsection{UserInterface/Create\_Test\_Data}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo203}
\label{ch:UserInterface_Create_Test_Data}
\index{unsorted!Create\_Test\_Data}\index{Functions!Create\_Test\_Data}
\textbf{FUNCTION}

   Create a linked list of tests.

\textbf{TODO}

   Generate this code automatically from a set
   of high-level specifications.

\newpage
\subsubsection{UserInterface/Do\_Mutual\_Exlcude\_Test}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo204}
\label{ch:UserInterface_Do_Mutual_Exlcude_Test}
\index{unsorted!Do\_Mutual\_Exlcude\_Test}\index{Functions!Do\_Mutual\_Exlcude\_Test}
\textbf{FUNCTION}

   Check all the options to see if combinations of options
   are used that mutually exclude each other, such as
   --singledoc and --multidoc.

\textbf{INPUTS}
\begin{itemize}
  \item    cur\_option\_test -- the test to be carried out.
\end{itemize}


\newpage
\subsubsection{UserInterface/Do\_Option\_Tests}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo205}
\label{ch:UserInterface_Do_Option_Tests}
\index{unsorted!Do\_Option\_Tests}\index{Functions!Do\_Option\_Tests}
\textbf{FUNCTION}

   Run a series of tests on the options that the user
   specified.  These tests are specified in 
   option\_tests (\ref{ch:robo214}).

\textbf{RESULT}
\begin{itemize}
  \item    EXIT\_FAILURE -- one of the tests failed.
  \item    EXIT\_SUCCESS -- all test completed successfully
\end{itemize}


\newpage
\subsubsection{UserInterface/Find\_And\_Fix\_Path}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo206}
\label{ch:UserInterface_Find_And_Fix_Path}
\index{unsorted!Find\_And\_Fix\_Path}\index{Functions!Find\_And\_Fix\_Path}
\textbf{FUNCTION}

   Searches through the options to find a path.
   This path is converted to a propper path
   if it contains errors such as the use (\ref{ch:robo221}) of
   '$\backslash$' or when it does not start with ./ or a
   drive name.
   The option must exist.

\textbf{INPUTS}
\begin{itemize}
  \item    option\_name -- the option name for the path
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    path -- the path.
\end{itemize}


\newpage
\subsubsection{UserInterface/Find\_Option}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo207}
\label{ch:UserInterface_Find_Option}
\index{unsorted!Find\_Option}\index{Functions!Find\_Option}
\textbf{FUNCTION}

   Search configuration (\ref{ch:robo51}).options for a specific option.

\textbf{RESULT}
\begin{itemize}
  \item    TRUE  -- option does exist
  \item    FALSE -- option does not exist
\end{itemize}


\newpage
\subsubsection{UserInterface/Find\_Parameterized\_Option}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo208}
\label{ch:UserInterface_Find_Parameterized_Option}
\index{unsorted!Find\_Parameterized\_Option}\index{Functions!Find\_Parameterized\_Option}
\textbf{FUNCTION}

   Search for an option of the form

\begin{verbatim}
     --a_option_name a_value
\end{verbatim}

   in configuration (\ref{ch:robo51}).options.

\textbf{INPUTS}

   optionname -- the name of the option to search for.

\textbf{RESULT}

   NULL if the option is not found, a pointer to the value
   otherwise.

\textbf{NOTES}

   Results in a Panic if the option is found but
   no value is specified.

\newpage
\subsubsection{UserInterface/Fix\_Path}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo209}
\label{ch:UserInterface_Fix_Path}
\index{unsorted!Fix\_Path}\index{Functions!Fix\_Path}
\textbf{FUNCTION}

   Add a "./" to a path if it does not start with a "./" or does not
   contain a ":".  If the path was "." just add a "/".  Adding a
   "./" simplifies the creating of relative links during the
   generation process.

\textbf{INPUTS}
\begin{itemize}
  \item    path -- the path to be fixed.
\end{itemize}


\textbf{RESULT}

   A pointer to a newly allocated string containing the path.

\newpage
\subsubsection{UserInterface/General\_Find\_Parameterized\_Option}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo210}
\label{ch:UserInterface_General_Find_Parameterized_Option}
\index{unsorted!General\_Find\_Parameterized\_Option}\index{Functions!General\_Find\_Parameterized\_Option}
\textbf{FUNCTION}

   Search for an option of the form

\begin{verbatim}
     --a_option_name a_value
\end{verbatim}


\textbf{INPUTS}
\begin{itemize}
  \item    n -- the number of options in the options array.
  \item    options -- the options array
  \item    optionname -- the name of the option to search for.
\end{itemize}


\textbf{RESULT}

   NULL if the option is not found, a pointer to the value
   otherwise.

\textbf{NOTES}

   Results in a Panic if the option is found but
   no value is specified.

\newpage
\subsubsection{UserInterface/main}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo211}
\label{ch:UserInterface_main}
\index{unsorted!main}\index{Functions!main}
\textbf{FUNCTION}

   Get and parse the arguments.  Analyse document and generate the
   documentation. Everything starts from here.

\textbf{TODO}

   This function is too long.

\newpage
\subsubsection{UserInterface/ok\_options}
\textsl{[ UserInterface ]}
\textsl{[ Variables ]}

\label{ch:robo212}
\label{ch:UserInterface_ok_options}
\index{unsorted!ok\_options}\index{Variables!ok\_options}
\textbf{FUNCTION}

   An list of all allowed command-line options.  If you add any
   options add its name here too.  This list is used to verify
   the options specified by the user.

\newpage
\subsubsection{UserInterface/Option\_Test\_Kind}
\textsl{[ UserInterface ]}
\textsl{[ Types ]}

\label{ch:robo213}
\label{ch:UserInterface_Option_Test_Kind}
\index{unsorted!Option\_Test\_Kind}\index{Types!Option\_Test\_Kind}
\textbf{FUNCTION}

   Enumeration for the kind of tests that are carried out on the 
   options that the user specifies.

\newpage
\subsubsection{UserInterface/option\_tests}
\textsl{[ UserInterface ]}
\textsl{[ Variables ]}

\label{ch:robo214}
\label{ch:UserInterface_option_tests}
\index{unsorted!option\_tests}\index{Variables!option\_tests}
\textbf{FUNCTION}

   A linked lists of tests that check the options specified
   by the user.

\newpage
\subsubsection{UserInterface/Path\_Check}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo215}
\label{ch:UserInterface_Path_Check}
\index{unsorted!Path\_Check}\index{Functions!Path\_Check}
\textbf{FUNCTION}

   Test the validity of the doc and source path. The doc path should
   not be a sub directory of the source path otherwise the generated
   documentation will be part of the generated documentation if
   robodoc is run more than once.

\textbf{INPUTS}
\begin{itemize}
  \item    sourcepath -- the path to the source files.
  \item    docpath    -- the path to the documentation files.
\end{itemize}


\textbf{OUTPUT}
\begin{itemize}
  \item    error messages
\end{itemize}


\newpage
\subsubsection{UserInterface/Path\_Convert\_Win32\_to\_Unix}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo216}
\label{ch:UserInterface_Path_Convert_Win32_to_Unix}
\index{unsorted!Path\_Convert\_Win32\_to\_Unix}\index{Functions!Path\_Convert\_Win32\_to\_Unix}
\textbf{FUNCTION}

   Although people are supposed to specify all paths
   with a '/' as seperator, sometimes people on Win32
   use (\ref{ch:robo221}) '$\backslash$', this causes problems later on in some
   other function of robodoc that expect a '/'.
   So to prevent this we replace all the '$\backslash$' in a path
   with '/'

\begin{verbatim}
    
\end{verbatim}

   In addition people sometimes add a '/' at the
   end of the path. We remove it.

\textbf{INPUTS}
\begin{itemize}
  \item    path -- the path.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    path -- the converted path (in a newly allocated
             block of memory).
\end{itemize}


\newpage
\subsubsection{UserInterface/PathBegin\_Check}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo217}
\label{ch:UserInterface_PathBegin_Check}
\index{unsorted!PathBegin\_Check}\index{Functions!PathBegin\_Check}
\textbf{FUNCTION}

   Checks the validity of a path.
   A path should start with

\begin{verbatim}
     ./
\end{verbatim}

   or

\begin{verbatim}
     /
\end{verbatim}

   or

\begin{verbatim}
     have a ':' some where
\end{verbatim}


\textbf{INPUTS}
\begin{itemize}
  \item    path -- the path to be cheked.
\end{itemize}


\textbf{RESULT}
\begin{itemize}
  \item    FALSE -- path is not OK.
  \item    TRUE  -- path is OK.
\end{itemize}


\newpage
\subsubsection{UserInterface/RB\_Find\_In\_Argv\_Parameterized\_Option}
\textsl{[ UserInterface ]}
\textsl{[ Functions ]}

\label{ch:robo218}
\label{ch:UserInterface_RB_Find_In_Argv_Parameterized_Option}
\index{unsorted!RB\_Find\_In\_Argv\_Parameterized\_Option}\index{Functions!RB\_Find\_In\_Argv\_Parameterized\_Option}
\textbf{FUNCTION}

   Search for an option of the form

\begin{verbatim}
     --a_option_name a_value
\end{verbatim}

   in argv.   The function is used to look for the

\begin{verbatim}
     --rc  
\end{verbatim}

   option that can be used to specify an 
   alternate robodoc configuration (\ref{ch:robo51}) file.

\textbf{INPUTS}
\begin{itemize}
  \item    argc -- the argument count as received by main (\ref{ch:robo211})().
  \item    argv -- the array of argument values as received by main (\ref{ch:robo211})()
  \item    optionname -- the name of the option to search for.
\end{itemize}


\textbf{RESULT}

   NULL if the option is not found, a pointer to the value
   otherwise.

\textbf{NOTES}

   Results in a Panic if the option is found but
   no value is specified.

\newpage
\subsubsection{UserInterface/RB\_Option\_Name}
\textsl{[ UserInterface ]}
\textsl{[ Structures ]}

\label{ch:robo219}
\label{ch:UserInterface_RB_Option_Name}
\index{unsorted!RB\_Option\_Name}\index{Structures!RB\_Option\_Name}
\textbf{FUNCTION}

   Element in a list of option names.
   Used in a RB\_Option\_Test (\ref{ch:robo220}) to specify to what
   options a test applies.

\newpage
\subsubsection{UserInterface/RB\_Option\_Test}
\textsl{[ UserInterface ]}
\textsl{[ Structures ]}

\label{ch:robo220}
\label{ch:UserInterface_RB_Option_Test}
\index{unsorted!RB\_Option\_Test}\index{Structures!RB\_Option\_Test}
\textbf{FUNCTION}

   A test specification for options. This
   stores information about the kind of test and
   the options it applies to, and the message that
   is given to the user.

\newpage
\subsubsection{UserInterface/use}
\textsl{[ UserInterface ]}
\textsl{[ Variables ]}

\label{ch:robo221}
\label{ch:UserInterface_use}
\index{unsorted!use}\index{Variables!use}
\textbf{NAME}

   use -- usage string

\textbf{FUNCTION}

   Inform the user how to use ROBODoc (\ref{ch:robo0}).

\textbf{AUTHOR}

   Koessi

\newpage
\subsection{ROBODoc/Utilities}
\textsl{[ ROBODoc ]}
\textsl{[ Modules ]}

\label{ch:robo18}
\label{ch:ROBODoc_Utilities}
\index{unsorted!Utilities}\index{Modules!Utilities}
\textbf{FUNCTION}

   Set of general purpose utility functions that are used
   in more than one module.

\newpage
\subsubsection{Utilities/CR\_LF\_Conversion}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo222}
\label{ch:Utilities_CR_LF_Conversion}
\index{unsorted!CR\_LF\_Conversion}\index{Functions!CR\_LF\_Conversion}
\textbf{FUNCTION}

   Fix CR/LF problems.



   If ROBODoc (\ref{ch:robo0}) reads a text file that was created on another OS
   line-endings might not be what ROBODoc (\ref{ch:robo0}) expects of the current OS.
   This function tries to detect and fix this.

\textbf{INPUTS}
\begin{itemize}
  \item    line -- a line of text
\end{itemize}


\textbf{RETURN VALUE}
\begin{itemize}
  \item    number of characters that were removed.
\end{itemize}


\newpage
\subsubsection{Utilities/cwd}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo223}
\label{ch:Utilities_cwd}
\index{unsorted!cwd}\index{Functions!cwd}
\textbf{FUNCTION}

   Holds current working directory

\newpage
\subsubsection{Utilities/ExpandTab}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo224}
\label{ch:Utilities_ExpandTab}
\index{unsorted!ExpandTab}\index{Functions!ExpandTab}
\textbf{FUNCTION}

   Expand the tabs in a line of text.

\textbf{INPUTS}

   line -- the line to be expanded
   tab\_size    -- global.
 RETURN
   pointer to the expanded line.

\textbf{NOTE}

   This function is not reentrant.

\newpage
\subsubsection{Utilities/RB\_Alloc\_Header}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo225}
\label{ch:Utilities_RB_Alloc_Header}
\index{unsorted!RB\_Alloc\_Header}\index{Functions!RB\_Alloc\_Header}
\textbf{FUNCTION}

   allocate the struct RB\_header (\ref{ch:robo144})

\textbf{RESULT}

   struct RB\_header (\ref{ch:robo144}) *      -- all attributes/pointers set to zero

\textbf{AUTHOR}

   Koessi

\textbf{SEE ALSO}

   RB\_Free\_Header (\ref{ch:robo233})()

\newpage
\subsubsection{Utilities/RB\_Change\_Back\_To\_CWD}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo226}
\label{ch:Utilities_RB_Change_Back_To_CWD}
\index{unsorted!RB\_Change\_Back\_To\_CWD}\index{Functions!RB\_Change\_Back\_To\_CWD}
\textbf{FUNCTION}

   Changes back to saved working directory and frees cwd (\ref{ch:robo223}) string

\newpage
\subsubsection{Utilities/RB\_Change\_To\_Docdir}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo227}
\label{ch:Utilities_RB_Change_To_Docdir}
\index{unsorted!RB\_Change\_To\_Docdir}\index{Functions!RB\_Change\_To\_Docdir}
\textbf{FUNCTION}

   Saves current working directory and then changes to document dir

\newpage
\subsubsection{Utilities/RB\_Close\_File}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo228}
\label{ch:Utilities_RB_Close_File}
\index{unsorted!RB\_Close\_File}\index{Functions!RB\_Close\_File}
\textbf{FUNCTION}

   Closes a given file

\newpage
\subsubsection{Utilities/RB\_Close\_Pipe}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo229}
\label{ch:Utilities_RB_Close_Pipe}
\index{unsorted!RB\_Close\_Pipe}\index{Functions!RB\_Close\_Pipe}
\textbf{FUNCTION}

   Closes a given pipe

\newpage
\subsubsection{Utilities/RB\_ContainsNL}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo230}
\label{ch:Utilities_RB_ContainsNL}
\index{unsorted!RB\_ContainsNL}\index{Functions!RB\_ContainsNL}
\textbf{FUNCTION}

   Check whether the provided line buffer contains
   a new line (NL) character.

\textbf{INPUTS}
\begin{itemize}
  \item    line -- line string to process
\end{itemize}


\textbf{RETURN VALUE}
\begin{itemize}
  \item    TRUE  -- the line contains a NL character
  \item    FALSE -- the line does not contain a NL character
\end{itemize}


\newpage
\subsubsection{Utilities/RB\_CopyFile}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo231}
\label{ch:Utilities_RB_CopyFile}
\index{unsorted!RB\_CopyFile}\index{Functions!RB\_CopyFile}
\textbf{NAME}

   RB\_CopyFile -- copy a file to another file

\textbf{RESULT}

   Program Exit if one of the specified files did not open.

\newpage
\subsubsection{Utilities/RB\_FputcLatin1ToUtf8}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo232}
\label{ch:Utilities_RB_FputcLatin1ToUtf8}
\index{unsorted!RB\_FputcLatin1ToUtf8}\index{Functions!RB\_FputcLatin1ToUtf8}
\textbf{NAME}

   RB\_FputcLatin1ToUtf8

\textbf{BUGS}

   This wrongly assumes that input is always Latin-1.

\newpage
\subsubsection{Utilities/RB\_Free\_Header}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo233}
\label{ch:Utilities_RB_Free_Header}
\index{unsorted!RB\_Free\_Header}\index{Functions!RB\_Free\_Header}
\textbf{NAME}

   RB\_Free\_Header             -- oop

\textbf{FUNCTION}

   free struct RB\_header (\ref{ch:robo144}) and associated strings

\textbf{INPUTS}

   struct RB\_header (\ref{ch:robo144}) *header -- this one

\textbf{AUTHOR}

   Koessi

\textbf{SEE ALSO}

   RB\_Alloc\_Header (\ref{ch:robo225})(), RB\_Close\_The\_Shop()

\newpage
\subsubsection{Utilities/RB\_FreeLineBuffer}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo234}
\label{ch:Utilities_RB_FreeLineBuffer}
\index{unsorted!RB\_FreeLineBuffer}\index{Functions!RB\_FreeLineBuffer}
\textbf{FUNCTION}

   Free the dynamically allocated line-buffer

\textbf{INPUTS}
\begin{itemize}
  \item    works on the globals line\_buffer (\ref{ch:robo133}), readChars (\ref{ch:robo137}), myLine (\ref{ch:robo135})
\end{itemize}


\newpage
\subsubsection{Utilities/RB\_malloc}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo235}
\label{ch:Utilities_RB_malloc}
\index{unsorted!RB\_malloc}\index{Functions!RB\_malloc}
\textbf{FUNCTION}

   like malloc, but exit if malloc failed

\textbf{RETURN VALUE}

   See malloc

\newpage
\subsubsection{Utilities/RB\_Match}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo236}
\label{ch:Utilities_RB_Match}
\index{unsorted!RB\_Match}\index{Functions!RB\_Match}
\textbf{FUNCTION}

   See if a wildcard expression matches a target string.  The wildcard
   expression can consists of any literal character and the two
   wildcards characters '*' and '?'.  '*' matches the longest string
   of zero or more characters that fit.  '?' matches any single
   character.



   Examples:

\begin{verbatim}
      "*aap"   matches "aapaapaapaap"
      "?inux"  matches "linux"
      "lin*ux" matches "linux"
      "linux*" matches "linux"
\end{verbatim}


\textbf{NOTES}

   This is a recursive function.

\textbf{INPUTS}
\begin{itemize}
  \item    target -- the string to be matched agains the
               wildcard\_expression.
  \item    wildcard\_expression -- the wildcard expression
\end{itemize}


\textbf{RETURN VALUE}

   TRUE  -- the target matches the wildcard expression
   FALSE -- it does not match.

\newpage
\subsubsection{Utilities/RB\_Mem\_Check}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo237}
\label{ch:Utilities_RB_Mem_Check}
\index{unsorted!RB\_Mem\_Check}\index{Functions!RB\_Mem\_Check}
\textbf{FUNCTION}

   Check for memory allocation failures.

\newpage
\subsubsection{Utilities/RB\_Open\_File}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo238}
\label{ch:Utilities_RB_Open_File}
\index{unsorted!RB\_Open\_File}\index{Functions!RB\_Open\_File}
\textbf{FUNCTION}

   Opens a file and returns its handler

\newpage
\subsubsection{Utilities/RB\_Open\_Pipe}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo239}
\label{ch:Utilities_RB_Open_Pipe}
\index{unsorted!RB\_Open\_Pipe}\index{Functions!RB\_Open\_Pipe}
\textbf{FUNCTION}

   Opens a pipe and returns its handler

\newpage
\subsubsection{Utilities/RB\_Panic}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo240}
\label{ch:Utilities_RB_Panic}
\index{unsorted!RB\_Panic}\index{Functions!RB\_Panic}
\textbf{NAME}

   RB\_Panic -- free resources and shut down

\textbf{FUNCTION}

   Print error message.  Frees all resources used by robodoc.
   Terminates program.  Output goes to stderr

\textbf{INPUTS}

   char *format            -- formatstring
   ...                     -- parameters

\textbf{AUTHOR}

   Koessi

\newpage
\subsubsection{Utilities/RB\_QuickSort}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo241}
\label{ch:Utilities_RB_QuickSort}
\index{unsorted!RB\_QuickSort}\index{Functions!RB\_QuickSort}
\textbf{FUNCTION}

   Sort an array of pointers according to the lexical order
   of the elements the pointers point to.
   This is based on the quicksort routine in
   "The C programming language" by B Kerninghan en D Ritchie.

\textbf{INPUTS}
\begin{itemize}
  \item    array -- the array of pointers.
  \item    left  -- the most left element in the array.
  \item    right -- the most right element in the array.
  \item    f     -- pointer to a function that can compare
              the objects two elements of the array
              point to.
\end{itemize}


\textbf{RESULT}

   array -- A sorted array of pointers.

\textbf{EXAMPLE}

   The following is an example program that shows
   the use (\ref{ch:robo221})

\begin{verbatim}
    #define TEST_SIZE 10
\end{verbatim}



\begin{verbatim}
    char* test[ TEST_SIZE ] = { "ape", "zebra",
       "duck", "goofbal", "dodo", "rabit",
       "crow", "cow", "pig", "goat" };
\end{verbatim}



\begin{verbatim}
    int string_compare( void* p1, void* p2 )
    {
       char *cp1 = p1;
       char *cp2 = p2;
       return strcmp( cp1, cp2 );
    }
\end{verbatim}



\begin{verbatim}
    RB_QuickSort( test, 0, TEST_SIZE - 1, string_compare );
\end{verbatim}


\newpage
\subsubsection{Utilities/RB\_ReadWholeLine}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo242}
\label{ch:Utilities_RB_ReadWholeLine}
\index{unsorted!RB\_ReadWholeLine}\index{Functions!RB\_ReadWholeLine}
\textbf{FUNCTION}

   Read a single line from the file using the provided buffer.

\textbf{INPUTS}
\begin{itemize}
  \item    file -- file to read from
  \item    buf -- buffer of length MAX\_LINE\_LEN to read chunks of the line to
  \item    arg\_readChars -- reference to the variable to store the read characters in
\end{itemize}


\textbf{RETURN VALUE}
\begin{itemize}
  \item    returns a dynamically allocated buffer containing the complete line
     read
\end{itemize}


\textbf{NOTES}

   If the line did not end in a new line (NL) character one is added.

\newpage
\subsubsection{Utilities/RB\_Say}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo243}
\label{ch:Utilities_RB_Say}
\index{unsorted!RB\_Say}\index{Functions!RB\_Say}
\textbf{NAME}

   RB\_Say                     -- varargs

\textbf{FUNCTION}

   Say what's going on.  Goes to stdout.

\textbf{INPUTS}
\begin{itemize}
  \item    char *format    -- formatstring
  \item    long mode       -- SAY\_INFO $|$ SAY\_DEBUG
  \item    ...             -- parameters
\end{itemize}


\textbf{AUTHOR}

   Koessi

\newpage
\subsubsection{Utilities/RB\_Skip\_Whitespace}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo244}
\label{ch:Utilities_RB_Skip_Whitespace}
\index{unsorted!RB\_Skip\_Whitespace}\index{Functions!RB\_Skip\_Whitespace}
\textbf{FUNCTION}

   Skip space and tab chars from the start *buf. This is needed when
   searching for indented headers and items.

\textbf{NOTES}

   We should extract some info about indentation level and save it to
   global variable in order to write out source items (that originate from
   indented headers) neatly.

\textbf{SEE ALSO}

   RB\_Find\_Marker (\ref{ch:robo40}), RB\_Find\_End\_Marker, RB\_Find\_Item, RB\_Generate\_Item\_Body

\newpage
\subsubsection{Utilities/RB\_Str\_Case\_Cmp}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo245}
\label{ch:Utilities_RB_Str_Case_Cmp}
\index{unsorted!RB\_Str\_Case\_Cmp}\index{Functions!RB\_Str\_Case\_Cmp}
\textbf{FUNCTION}

   Compare two strings, regardless of the case of the characters.

\textbf{RESULT}

    0  s == t
   -1  s $<$ t
    1  s $>$ t

\newpage
\subsubsection{Utilities/RB\_StripCR}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo246}
\label{ch:Utilities_RB_StripCR}
\index{unsorted!RB\_StripCR}\index{Functions!RB\_StripCR}
\textbf{FUNCTION}

   Strip carriage return (CR) from line.

\textbf{INPUTS}
\begin{itemize}
  \item    line -- line string to process
\end{itemize}


\newpage
\subsubsection{Utilities/RB\_Swap}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo247}
\label{ch:Utilities_RB_Swap}
\index{unsorted!RB\_Swap}\index{Functions!RB\_Swap}
\textbf{FUNCTION}

   Swap two elements in a array of pointers.  This function is used
   by RB\_QuickSort (\ref{ch:robo241})().

\newpage
\subsubsection{Utilities/RB\_TimeStamp}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo248}
\label{ch:Utilities_RB_TimeStamp}
\index{unsorted!RB\_TimeStamp}\index{Functions!RB\_TimeStamp}
\textbf{NAME}

   RB\_TimeStamp -- print a time stamp

\newpage
\subsubsection{Utilities/snprintf}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo249}
\label{ch:Utilities_snprintf}
\index{unsorted!snprintf}\index{Functions!snprintf}
\textbf{FUNCTION}

   Mimic the library function snprintf using sprintf if it is absent.

\newpage
\subsubsection{Utilities/Stat\_Path}
\textsl{[ Utilities ]}
\textsl{[ Functions ]}

\label{ch:robo250}
\label{ch:Utilities_Stat_Path}
\index{unsorted!Stat\_Path}\index{Functions!Stat\_Path}
\textbf{FUNCTION}

   Check the given path against required type.
   d -- directory, f -- file, e -- exists

\textbf{RETURN VALUE}

   TRUE if path is of the given type, otherwise FALSE.

\textbf{BUGS}

   Should check if symbolic link points to a directory or to a file.

\newpage
\subsection{ROBODoc/Lua\_Generator}
\textsl{[ ROBODoc ]}
\textsl{[ Methods ]}

\label{ch:robo193}
\label{ch:ROBODoc_Lua_Generator}
\index{unsorted!Lua\_Generator}\index{Methods!Lua\_Generator}
\textbf{FUNCTION}

   Shell generator that actually gives data to a Lua script.
   Supports singledoc mode.

\textbf{AUTHOR}

   Jeremy Cowgar $<$jc@cowgar.com$>$

\textbf{NOTES}

   No code defined yet. This is just a shell.

\newpage
\subsection{ROBODoc/RB\_Path}
\textsl{[ ROBODoc ]}
\textsl{[ Structures ]}

\label{ch:robo194}
\label{ch:ROBODoc_RB_Path}
\index{unsorted!RB\_Path}\index{Structures!RB\_Path}
\textbf{NAME}

   RB\_Path -- Path to a file

\textbf{ATTRIBUTES}
\begin{itemize}
  \item    next  -- pointer to the next RB\_Path structure.
  \item    parent -- the parent path (one directory up).
  \item    name  -- null terminated string with the name of the path.
               (Path names can be relative)
  \item    docname -- the corresponding docpath.
\end{itemize}


\newpage
\section{XMLDB\_Generator/RB\_XMLDB\_Generate\_Char}
\textsl{[ Functions ]}

\label{ch:robo251}
\label{ch:XMLDB_Generator_RB_XMLDB_Generate_Char}
\index{unsorted!RB\_XMLDB\_Generate\_Char}\index{Functions!RB\_XMLDB\_Generate\_Char}
\textbf{NAME}

   RB\_XMLDB\_Generate\_Char

\textbf{FUNCTION}

   Switchboard to RB\_XMLDB\_Generate\_Char

\newpage
\section{XMLDB\_Generator/RB\_XMLDB\_Generate\_Item\_Line\_Number}
\textsl{[ Functions ]}

\label{ch:robo252}
\label{ch:XMLDB_Generator_RB_XMLDB_Generate_Item_Line_Number}
\index{unsorted!RB\_XMLDB\_Generate\_Item\_Line\_Number}\index{Functions!RB\_XMLDB\_Generate\_Item\_Line\_Number}
\textbf{FUNCTION}

   Generate line numbers for SOURCE like items

\textbf{INPUTS}
\begin{itemize}
  \item    dest\_doc           -- the file to write to.
  \item    line\_number\_string -- the line number as string.
\end{itemize}


\printindex
\end{document}
