API Documentation

Table of Contents

1. Docuwala/ROBODoc
1.1. ROBODoc/Analyser
1.2. ROBODoc/ASCII_Generator
1.3. ROBODoc/Configuration
1.4. ROBODoc/Directory
1.5. ROBODoc/Document
1.6. ROBODoc/Filename
1.7. ROBODoc/Folds
1.8. ROBODoc/Generator
1.9. ROBODoc/Globals
1.10. ROBODoc/Headers
1.11. ROBODoc/HeaderTypes
1.12. ROBODoc/HTML_Generator
1.13. ROBODoc/Items
1.14. ROBODoc/LaTeX_Generator
1.15. ROBODoc/Links
1.16. ROBODoc/makefile.mingw-cygwin
1.17. ROBODoc/Part
1.18. ROBODoc/RTF_Generator
1.19. ROBODoc/Test_Generator
1.20. ROBODoc/TROFF_Generator
1.21. ROBODoc/UserInterface
1.22. ROBODoc/Utilities
1.23. ROBODoc/Lua_Generator
1.24. ROBODoc/RB_Path
2. Docuwala/ROBOhdrs
2.1. ROBOhdrs/addList
2.2. ROBOhdrs/arrangeCtags
2.3. ROBOhdrs/cleanUp
2.4. ROBOhdrs/cmdLine
2.5. ROBOhdrs/ctags
2.6. ROBOhdrs/ctagsBin
2.7. ROBOhdrs/custhdrs
2.8. ROBOhdrs/doCtagsExec
2.9. ROBOhdrs/doFile
2.10. ROBOhdrs/incSrc
2.11. ROBOhdrs/initMe
2.12. ROBOhdrs/insertHeaders
2.13. ROBOhdrs/insertSrcEnd
2.14. ROBOhdrs/linenumCompare
2.15. ROBOhdrs/main
2.16. ROBOhdrs/MAXLINE
2.17. ROBOhdrs/MAXNAME
2.18. ROBOhdrs/myctags
2.19. ROBOhdrs/parseCtagsX
2.20. ROBOhdrs/parseCtagsXLine
2.21. ROBOhdrs/PROGNAME
2.22. ROBOhdrs/PROGVERSION
2.23. ROBOhdrs/projName
2.24. ROBOhdrs/roboFileHeader
2.25. ROBOhdrs/roboHeader
2.26. ROBOhdrs/srcSta
2.27. ROBOhdrs/typeOk
2.28. ROBOhdrs/usage
2.29. ROBOhdrs/vcTag

1. Docuwala/ROBODoc

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

      Sourcecode  ---> [ROBODoc] ---> Document.

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, it stores the names of the sourcefiles and directories in the source direcory tree. File names are stored in a RB_Filename structure, directory names in a RB_Path structure. Each RB_Filename contains a pointer (path) to a RB_Path structure that tells in which directory a file is located. Each RB_Path has a pointer (parent) to another RB_Path 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 also stores the name of the documentation file.

For each sourcefile there is an RB_Part structure. It contains a pointer (filename) to the RB_Filename 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 structure to which it belongs. Headers can form a hierarchy that is used to create sections and subsections in the documentation. To store this hierarchy every RB_header structure contains a pointer (parent) to its parent header. For instance, given the following two headers, SubModule is the parent of SubSubModule.

     ****h* TopModule/SubModule
     *
     ****

     ****h* SubModule/SubSubModule
     *
     ****

In the documentation this creates the sections

      1.TopModule
      1.1 SubModule
      1.1.1 SubSubModule

The RB_Directory and the linked list of RB_Part structures are stored in a RB_Document 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 structures. This array is sorted for quick searching. RB_link structures the name of a header and the name of the label under which the documentation can be found in the documentation file.

COPYRIGHT.

Copyright (C) 1994-2006 Frans Slothouber, Petteri Kettunen, and Jacco van Weert.

This program is free software; you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation; either version 2 of the License, or (at your option) any later version.

This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

You should have received a copy of the GNU General Public License along with this program; if not, write to the Free Software Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA

AUTHOR.

See AUTHORS in the archive.

CREATION DATE.

20-Dec-94 Jacco van Weert.

MODIFICATION HISTORY.

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

  • http://www.xs4all.nl/~rfsber/Robo/

BUGS.

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

1.1. ROBODoc/Analyser

NAME.

Analyser -- Functions to scan source and collect headers

FUNCTION.

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

1.1.1. Analyser/Analyse_Indentation

FUNCTION.

Figure out how text is indented. SYNPOPSIS

INPUTS.

  • arg_item -- the item to be analysed.

1.1.2. Analyser/Analyse_Item_Format

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

INPUTS.

  • arg_item -- the item to be analysed.

1.1.3. Analyser/Analyse_List

FUNCTION.

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

      ITEMNAME
         o bla bla
         o bla bla

or case II:

      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.

SYNPOPSIS

INPUTS.

  • arg_item -- the item to be parsed.

  • indent -- the indent of this item.

OUTPUT.

  • arg_item -- the itemlines will contain formatting information for all the lists that were found.

1.1.4. Analyser/Analyse_ListBody

FUNCTION.

Analyse... (TODO) SYNPOPSIS

INPUTS.

  • arg_item -- the item to be analysed.

  • start_index --

  • arg_index --

1.1.5. Analyser/Analyse_Paragraphs

FUNCTION.

Analyse paragraphs... (TODO) SYNPOPSIS

INPUTS.

  • arg_item -- the item to be analysed.

1.1.6. Analyser/Analyse_Preformatted

FUNCTION.

Analyse preformatted text ... (TODO) SYNPOPSIS

INPUTS.

  • arg_item -- the item to be analysed.

  • indent --

1.1.7. Analyser/AnalyseHeaderType

FUNCTION.

Determine the type of the header.

INPUTS.

  • cur_char -- pointer to the header type character

OUTPUT.

  • is_internal -- indicates if it is an internal header or not.*

  • cur_char -- points to the header type character

RESULT.

  • pointer to a RB_HeaderType

1.1.8. Analyser/Check_Header_Start

INPUTS.

  • arg_header -- the header to be checked.

  • first -- the line on which the first item was found

RESULT.

A warning is given if the condition occured.

1.1.9. Analyser/Dump_Item

FUNCTION.

Print debug information.

INPUTS.

  • arg_item -- the item to be pretty-printed.

1.1.10. Analyser/Find_End_Marker

FUNCTION.

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

INPUTS.

  • document -- a pointer to an opened source file.

OUTPUT.

  • new_header -- the lines of source code will be added here.

RESULT.

  • TRUE -- an end marker was found.

  • FALSE -- no end marker was found while scanning the source file.

1.1.11. Analyser/Function_Name

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.

1.1.12. Analyser/Get_Indent

INPUTS.

  • line -- the line

RESULT.

The indentation.

1.1.13. Analyser/Grab_Header

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

INPUTS.

  • sourcehandle -- an opened source file.

OUTPUT.

  • sourcehandle -- will point to the line following the end marker.

RESULT.

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

1.1.14. Analyser/Is_Empty_Line

FUNCTION.

Check if line is empty. This assumes that Copy_Lines_To_Item has been run on the item.

INPUTS.

  • line -- the string to be analysed.

1.1.15. Analyser/Is_End_of_List

FUNCTION.

Check... (TODO)

INPUTS.

  • arg_line --

  • indent --

1.1.16. Analyser/Is_List_Item_Continuation

FUNCTION.

Is it like the second line in something like:

     * this is a list item
       that continues

SYNPOPSIS

INPUTS.

  • arg_line -- the current line

  • indent -- the indent of the current item.

RESULT.

  • TRUE -- it is.

  • FALSE -- it is not.

1.1.17. Analyser/Is_ListItem_Start

FUNCTION.

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

INPUTS.

  • line -- the line

RESULT.

  • TRUE -- it did start with one of those characters

  • FALSE -- it did not.

1.1.18. Analyser/Is_Pipe_Marker

NAME.

Is_Pipe_Marker

FUNCTION.

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

RESULT.

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

SEE ALSO.

RB_Check_Pipe

1.1.19. Analyser/Is_Start_List

FUNCTION.

Check... (TODO)

INPUTS.

  • arg_line --

  • indent --

1.1.20. Analyser/Is_Tool

FUNCTION.

Checks for tool start and end markers

1.1.21. Analyser/Module_Name

FUNCTION.

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

     module/functionname.

SYNPOPSIS

INPUTS.

  • header_name -- a pointer to a nul terminated string.

RESULT.

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

SEE ALSO.

Function_Name()

1.1.22. Analyser/Preformat_All

FUNCTION.

Process... (TODO) SYNPOPSIS

INPUTS.

  • arg_item -- the item to be pre-formatted.

1.1.23. Analyser/RB_Analyse_Document

FUNCTION.

Scan all the sourcefiles of all parts of a document for headers. Store these headers in each part (RB_Part).

INPUTS.

  • document -- document to be analysed.

RESULT.

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

1.1.24. Analyser/RB_Analyse_Items

FUNCTION.

Locate the items in the header and create RB_Item structures for them. SYNPOPSIS

1.1.25. Analyser/RB_Find_Marker

NAME.

RB_Find_Marker -- Search for header marker in document.

FUNCTION.

Read document file line by line, and search each line for any of the headers defined in the array header_markers (OR if using the -rh switch, robo_head)

INPUTS.

document - pointer to the file to be searched. the gobal buffer line_buffer.

OUTPUT.

  • document will point to the line after the line with the header marker.

  • is_internal will be TRUE if the header is an internal header.

RESULT.

  • header type

BUGS.

Bad use of feof(), fgets().

SEE ALSO.

Find_End_Marker

1.1.26. Analyser/RB_GetCurrentFile

NAME.

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

1.1.27. Analyser/RB_SetCurrentFile

NAME.

RB_SetCurrentFile

FUNCTION.

Set... (TODO Documentation)

INPUTS.

  • filename --

1.1.28. Analyser/RB_Warning

NAME.

RB_Warning

FUNCTION.

Print warning to stdout. (stderr better?)

INPUTS.

  • format --

  • ... --

1.1.29. Analyser/RB_Warning_Full

NAME.

RB_Warning_Full

FUNCTION.

Print warning to stdout.

INPUTS.

  • arg_filename --

  • arg_line_number --

  • arg_format --

  • ...

1.1.30. Analyser/Remove_List_Char

FUNCTION.

Remove... (TODO)

INPUTS.

  • arg_item -- the item to be analysed.

  • start_index --

1.1.31. Analyser/ToBeAdded

FUNCTION.

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

      --internal

and

      --internalonly

SYNPOPSIS

INPUTS.

  • document -- a document (to determine the options)

  • header -- a header

RESULT.

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

1.2. ROBODoc/ASCII_Generator

NAME.

ASCII_Generator -- Generator for ASCII output

FUNCTION.

Plain ascii output, no formatting.

MODIFICATION HISTORY.

2003-06-17 Frans Slothouber V1.0

1.3. ROBODoc/Configuration

FUNCTION.

Functions to access the ROBODoc configuration and configuration 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

     <block name>:

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.

NOTES.

Is missing a lot of documentation.

You can not use RB_Say() in this module since the --tell flag won't be parsed until after this module has finished.

1.3.1. Configuration/add_keywords_to_hash_table

FUNCTION.

Initalize hash table and add all keywords from configuration.keywords to the hash table

1.3.2. Configuration/add_to_keywords_hash_table

FUNCTION.

Add a keyword to the hash table

INPUTS.

keyword -- The keyword string

1.3.3. Configuration/allocate_keywords_hash_table

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.

1.3.4. Configuration/c_keywords

FUNCTION.

The default C keywords.

1.3.5. Configuration/configuration

FUNCTION.

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

1.3.6. Configuration/default_item_names

FUNCTION.

Defines the names of items that ROBODoc recognized as items by default if none are specified in the robodoc.rc file.

1.3.7. Configuration/Find_Keyword

FUNCTION.

Find a keyword in the hash table

INPUTS.

  • keyword -- The keyword string

  • len -- The length of the keyword string

RETURN VALUE.

  • pointer to the found keyword string in hash table or

  • NULL if the keyword is not found

1.3.8. Configuration/GetParameters

FUNCTION.

Parse a line of text and store the individual words in a Parameters structure. Words are seperated by spaces, the exception are words surrounded by quotes. So:

      aap noot mies "back to the future"

contains four words.

INPUTS.

  • line -- the line of text.

  • parameters -- the set of parameters

1.3.9. Configuration/Hash_Keyword

FUNCTION.

Calculate the hash value for a string

The hash value is based on the CRC32 hash function. It is then reduced by an AND operation to the actual size of the hash table.

INPUTS.

  • keyword -- The keyword string

  • len -- The length of the keyword string

RETURN VALUE.

The hash value for the keyword.

1.3.10. Configuration/Install_C_Keywords

FUNCTION.

Install default C keywords

1.3.11. Configuration/keywords_hash

FUNCTION.

This is the hash table for the keywords. See keywords_hash_s.

1.3.12. Configuration/keywords_hash_mask

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:

     hash table size = keywords_hash_mask + 1

1.3.13. Configuration/keywords_hash_s

FUNCTION.

Structure for a keyword hash table row.

ATTRIBUTES.

  • keyword -- pointer to the keyword

  • next -- pointer to next entry in the row

1.3.14. Configuration/Parameters

FUNCTION.

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

ATTRIBUTES.

  • number -- the number of parameters found.

  • size -- the maximum size of the names array.

  • names -- an array with the values of the parameters.

NOTES.

Find a better name for the attribute 'names'

1.3.15. Configuration/RB_Configuration

FUNCTION.

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

ATTRIBUTES.

  • items -- an array with names that robodoc recognizes as items. Alsways includes the name "SOURCE" as the first element.

  • ignore_items -- an array with the names of items that ROBODoc should ignore.

  • source_items -- an array with the names of items that work similar to the built-in SOURCE item.

  • options -- Array with all options specified both on the commandline as well as in the robodoc.rc file.

  • custom_headertypes -- list with custom header types.

  • ignore_files -- list with wildcard expressions that specifies files and directories that robodoc should skip while scanning the source tree.

  • header_markers -- list with markers that mark the begin of a header.

  • remark_markers -- list with markers that mark a remark.

  • end_markers -- list with markers that markt the end of a header.

  • remark_begin_markers -- list of markers that mark the begin of a remark. For instance (*

  • remakr_end_markers -- list of markers that mark the end of a remark. For instance *)

  • keywords -- source keywords to recognise (and colorise)

  • source_line_comments -- comment markers that span until the end of line

1.3.16. Configuration/ReadConfiguration

FUNCTION.

Read the robodoc configuration file, and create a RB_Configuration structure.

INPUTS.

  • argc -- the arg count as received by main()

  • argv -- the arg valules as received by main()

  • filename -- an optional filename. If none is given, "robodoc.rc" is used.

RESULT.

An initialized configuration (a global).

1.4. ROBODoc/Directory

NAME.

This module contains function to scan a directory tree and to create a RB_Directory structure. Most of the OS dependend parts of ROBODoc can be found in this module..

This module currently works under:

  • Cygwin http://cygwin.com

  • Redhad 7.3 Linux

  • VC++ under Windows NT

  • MINGW http://www.mingw.org/

  • OS/X

AUTHOR.

Frans Slothouber

1.4.1. Directory/content_buffer

FUNCTION.

Temporary buffer file file content and filenames.

1.4.2. Directory/RB_Directory

NAME.

RB_Directory -- the directory tree with the source files.

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.

EXAMPLE.

The following show an example structure.

     RB_Directory             RB_Path
     +-------+   +------+    +-------+   +-----------+
     |       +-->| .    |--->| ./sub |-->| ./sub/sub |
     |       |   +------+    +-------+   +-----------+
     |       |      ^              ^            ^
     |       |      |              |            |
     |       |      |-----------+  +------+     +------+
     |       |      |           |         |            |
     |       |      |           |         |            |
     |       |   +------+    +------+   +------+    +-------+
     |       +-->|  a.c |--->| b.c  |-->| sa.c  |-->| ssb.c |
     +-------+   +------+    +------+   +------+    +-------+
                  RB_Filename

ATTRIBUTES.

  • first -- first RB_Filename in the list of files

  • current -- the last file that was returned in RB_Get_Next_Filename.

  • last -- the last RB_Filename in the list of files used for the insert operation

  • first_path -- first RB_Path in the list of paths.

1.4.3. Directory/RB_Directory_Insert_RB_File

FUNCTION.

Insert an RB_File structure into a RB_Directory structure. The RB_File is added at the end of the list.

1.4.4. Directory/RB_Directory_Insert_RB_Path

FUNCTION.

Insert a RB_Path into a RB_Directory. The RB_Path is added at the beginning of the list.

1.4.5. Directory/RB_FileType

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.

INPUTS.

  • arg_pathname -- the path leading up to this file

  • a_direntry -- a directory entry read by readdir()

RESULT.

The type of the file.

1.4.6. Directory/RB_Fill_Directory

NAME.

RB_Fill_Directory -- fill a RB_Directory structure

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.

INPUTS.

  • arg_rb_directory -- the result.

  • arg_path -- the current path that is scanned.

  • arg_doc_path -- the path to the documentation files.

RESULT.

a RB_Directory structure filled with all sourcefiles and subdirectories in arg_path.

NOTE.

This a is a recursive function.

1.4.7. Directory/RB_Free_RB_Directory

FUNCTION.

Free all the memory use by the RB_Directory structure.

INPUTS.

  • arg_directory -- the thing to be freed.

1.4.8. Directory/RB_Get_FileName

NAME.

RB_Get_PathName -- extract the file name

FUNCTION.

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

      "./filename"           returns "filename"
      "/home/et/filename"    returns "filename"
      "filename"             return  "filename"

INPUTS.

arg_fullpath -- a full path to a file, with or without a path.

RESULT.

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

NOTES.

You are responsible for deallocating it.

1.4.9. Directory/RB_Get_PathName

NAME.

RB_Get_PathName -- extract the path name

FUNCTION.

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

      "./filename"           returns "./"
      "/home/et/filename"    returns "/home/et/"
      "filename"             return  ""

INPUTS.

arg_fullpath -- a full path to a file, with or without a path.

RESULT.

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

NOTES.

You are responsible for deallocating it.

1.4.10. Directory/RB_Get_RB_Directory

NAME.

RB_Get_RB_Directory -- get a RB_Directory structure

FUNCTION.

Returns a RB_Directory 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.

INPUTS.

arg_rootpath -- the name a the directory to get,

                   a nul terminated string.

arg_docroot_name -- the name of the directory the documentation

                       file are stored in.  This directory is
                       skipped while scanning for sourcefiles.
                       It can be NULL.

RESULT.

A freshly allocated RB_Directory filled with source files.

1.4.11. Directory/RB_Get_RB_SingleFileDirectory

NAME.

RB_Get_RB_SingleFileDirectory -- get a RB_Directory structure

FUNCTION.

Returns a RB_Directory structure to the give directory, specified by the path that contains only a single file. This is used for the --singlefile option.

INPUT.

  • filename -- a filename. This may include the path.

RESULT.

a freshly allocated RB_Directory that contains only a single file.

1.4.12. Directory/RB_Is_PathCharacter

FUNCTION.

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

INPUTS.

c -- the character to be tested.

RESULT.

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

1.4.13. Directory/RB_Is_Source_File

NAME.

RB_Is_Source_File -- Is a file a sourcefile?

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.

1.4.14. Directory/RB_Not_Accepted

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.accept_files.

INPUTS.

  • filename -- the name of the file

1.4.15. Directory/RB_To_Be_Skipped

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.ignore_files.

INPUTS.

  • filename -- the name of the file

1.4.16. Directory/T_RB_FileType

FUNCTION.

Constants for the two different filetypes that ROBODoc recognizes.

1.5. ROBODoc/Document

FUNCTION.

This module contains functions to manipulate the central data structure (RB_Document) 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 structure is created, it is filled by the analyser and directory module and then used by the generator module to create the documentation.

MODIFICATION HISTORY.

  • ????-??-?? Frans Slothouber V1.0

  • 2003-02-03 Frans Slothouber Refactoring

  • 2003-10-30 David White Removed unistd.h for Borland

1.5.1. Document/RB_Document

NAME.

RB_Document -- Information store.

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. It points to the source file, the documentation file, and contains all the headers that were found in the source file.

ATTRIBUTES.

  • links -- linked list of all links.

  • parts -- linked list of all parts.

  • no_headers -- total number of headers

  • headers -- array of pointers to all the headers.

  • srctree -- the list of all sourcefiles in the srcroot.

  • doctype -- the kind of documentation to be generated.

  • actions -- what to de while analysing en generating.

  • srcroot -- root dir for the sourcecode.

  • docroot -- root dir for the documentation.

  • charset -- the character set used for HTML and XML documentation.

  • extension -- the extension used for the documentation files.

  • css -- the cascading style sheet to be used.

  • cur_part -- unused

1.5.2. Document/RB_Document_Add_Part

FUNCTION.

Add a new part to the document.

INPUTS.

  • document -- the document the part is to be added to.

  • part -- the part to be added

1.5.3. Document/RB_Document_Collect_Headers

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.

INPUTS.

  • document -- the document for which the table is created.

OUTPUT.

  • document->headers

  • document->no_headers

1.5.4. Document/RB_Document_Create_DocFilePaths

FUNCTION.

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

INPUTS.

  • document -- the document for which the tree is created.

1.5.5. Document/RB_Document_Create_Parts

FUNCTION.

Create all the parts of a document based on the sourcefiles in the source tree. This creates a new RB_Part for each file in the source tree.

INPUTS.

  • document -- the document for which the parts are generated.

1.5.6. Document/RB_Document_Determine_DocFilePaths

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.

EXAMPLE.

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

     ==>

docpath = ./test/mydoc/sub1/sub2

1.5.7. Document/RB_Fill_Header_Filename

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.

1.5.8. Document/RB_Get_RB_Document

FUNCTION.

Allocate and initialize an RB_Document structure.

RESULT.

An initialized document structure.

1.5.9. Document/RB_Open_SingleDocumentation

FUNCTION.

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

RESULT.

An opened file.

1.6. ROBODoc/Filename

NAME.

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

1.6.1. Filename/Get_Fullname

NAME.

Get_Fullname --

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.

NOTE.

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

1.6.2. Filename/RB_Filename

NAME.

RB_Filename --

ATTRIBUTES.

  • next pointer to the next RB_File.

  • name null terminated string with the name of the file, (Without the path, but including the extension).

  • fullname

  • path pointer to a RB_Path structure that holds the path for this file.

  • link The link used to represent this file while in multidoc mode.

1.6.3. Filename/RB_Get_Extension

NAME.

RB_Get_Extension --

FUNCTION.

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

RESULT.

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

NOTE.

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

1.6.4. Filename/RB_Get_Filename

NAME.

RB_Get_Filename --

FUNCTION.

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

RESULT.

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

NOTE.

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

1.6.5. Filename/RB_Get_Path

FUNCTION.

Give the path for this file.

NOTE.

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

1.6.6. Filename/RB_Get_RB_Filename

NAME.

RB_Get_RB_Filename

INPUTS.

  • arg_rb_filename --

  • arg_rb_path --

FUNCTION.

Create a new RB_Filename structure based on arg_filename and arg_rb_path.

1.7. ROBODoc/Folds

FUNCTION.

Folds make it possible to divide a large document in smaller sections. The divisions can be indicated by the user with the aid of fold markers.

AUTHOR.

PetteriK

1.7.1. Folds/extra_flags

NAME.

extra_flags

AUTHOR.

PetteriK

FUNCTION.

Bitflags for extra controls.

1.7.2. Folds/fold

NAME.

fold

FUNCTION.

Fold counter - true global.

1.7.3. Folds/fold_document_name_stack

FUNCTION.

Keeps track all the filenames of the nested folds.

1.7.4. Folds/fold_end_markers

NAME.

fold_start_end

FUNCTION.

Strings for fold end.

1.7.5. Folds/fold_mark_t

NAME.

fold_mark_t

FUNCTION.

Handy structure for fold start/end markers.

1.7.6. Folds/fold_start_markers

NAME.

fold_start_markers

FUNCTION.

Strings for fold start.

1.7.7. Folds/inside_fold

NAME.

in_fold

FUNCTION.

Boolean fold indicator. True if processing inside a fold (or nested folds).

1.7.8. Folds/RB_Check_Fold_End

NAME.

RB_Check_Fold_End

AUTHOR.

PetteriK

FUNCTION.

See if a fold end is found.

RETURN VALUE.

1 if end mark is found

1.7.9. Folds/RB_Check_Fold_Start

NAME.

RB_Check_Fold_Start

AUTHOR.

PetteriK

FUNCTION.

Check if a fold start is found.

RETURN VALUE.

1 fold mark found 0 fold mark not found

SIDE EFFECTS.

Fold name is copied to *foldname.

1.7.10. Folds/RB_Enter_Fold

NAME.

RB_Enter_Fold

1.7.11. Folds/RB_Exit_Fold

NAME.

RB_Exit_Fold

1.7.12. Folds/RB_Fold

FUNCTION.

Test if we are entering or leaving a fold.

1.7.13. Folds/RB_Inside_Fold

NAME.

RB_Inside_Fold

AUTHOR.

PetteriK

FUNCTION.

Check if processing currently inside a fold.

RETURN VALUE.

1 if inside, otherwise 0

1.8. ROBODoc/Generator

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.

The general call sequence is as follows:

     RB_Generate_Documentation
     +> RB_Generate_SingleDoc
        +> RB_Generate_Part
           +> Generate_Header
                 +> Generate_Item_Line
                    +> Generate_Char

BUGS.

  • Confusing use of doctype and output mode.

NOTES.

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

     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;
     }

we will have

     (*rb_generate_doc_start)(dest_doc, src_name, name, toc);

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

1.8.1. Generator/Generate_Char

FUNCTION.

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

INPUTS.

  • dest_doc -- destination file.

  • cur_char -- character to be generated.

1.8.2. Generator/Generate_Header

FUNCTION.

Generate the documentation for all the items found in a header except for any items specified in configuration.ignore_items.

INPUTS.

  • f -- destination file

  • header -- header to be searched.

  • srcname -- name of the source file the header was found in.

  • document -- name of the documentation file.

BUGS.

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

1.8.3. Generator/Generate_Header_Type

NAME.

Generate_Header_Type

FUNCTION.

Generates header type entry in sectioning mode

INPUTS.

  • FILE* dest_doc -- destination file

  • char *name -- the type of item

AUTHOR.

Thuffir

TODO.

Implement all document types...

1.8.4. Generator/Generate_Index

NAME.

Generate_Index -- generate index file based on xref files.

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.

1.8.5. Generator/Generate_Item_Name

NAME.

Generate_Item_Name -- fast&easy

FUNCTION.

write the item's name to the doc

INPUTS.

  • FILE* dest_doc -- destination file

  • int item_type -- the type of item

AUTHOR.

Koessi

NOTES.

uses globals: output_mode

1.8.6. Generator/Generate_Label

FUNCTION.

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

INPUTS.

  • dest_doc -- file to be written to

  • name -- the label's name.

  • output_mode -- global with the current output mode

1.8.7. Generator/Generate_Link

FUNCTION.

Generate a link to another headers documentation.

INPUTS.

  • dest_doc -- the output file

  • docname -- the name of the output file

  • file_name -- the name of the file that contains the link's body

  • label_name -- the label for the link

  • function_name -- the name that is shown for the link in the documentation

1.8.8. Generator/RB_Add_Extension

FUNCTION.

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

INPUTS.

  • doctype -- output mode

  • name -- the name of the file without extension and with enough room left to add the extension.

OUTPUT.

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

1.8.9. Generator/RB_Generate_BeginSection

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.

INPUTS.

  • dest_doc -- the destination file.

  • doctype --

  • depth -- the level of the section

  • name -- the name of the section

  • output_mode -- global with the current output mode.

1.8.10. Generator/RB_Generate_Doc_End

NAME.

RB_Generate_Doc_End -- generate document trailer.

FUNCTION.

Generates for depending on the output_mode the text that will be at the end of a document.

INPUTS.

  • dest_doc - pointer to the file to which the output will be written.

  • name - the name of this file.

  • output_mode - global variable that indicates the output mode.

NOTES.

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

BUGS.

1.8.11. Generator/RB_Generate_Doc_Start

NAME.

RB_Generate_Doc_Start -- Generate document header.

FUNCTION.

Generates for depending on the output_mode the text that will be at the start of a document. Including the table of contents.

INPUTS.

  • dest_doc - pointer to the file to which the output will be written.

  • src_name - the name of the source file or directory.

  • name - the name of this file.

  • output_mode - global variable that indicates the output mode.

  • toc - generate table of contens

SEE ALSO.

RB_Generate_Doc_End

1.8.12. Generator/RB_Generate_Documentation

FUNCTION.

Generate the documentation for all the information contained in a RB_Document structure.

INPUTS.

document -- pointer to the RB_Document structure.

1.8.13. Generator/RB_Generate_DOT_Image_Link

FUNCTION.

Generates the image link for the created dot graphics

1.8.14. Generator/RB_Generate_EndSection

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.

INPUTS.

  • dest_doc -- the destination file.

  • doctype --

  • depth -- the level of the section

  • name -- the name of the section

  • output_mode -- global with the current output mode.

1.8.15. Generator/RB_Generate_Header_End

NAME.

RB_Generate_Header_End

FUNCTION.

Generates for depending on the output_mode the text that will be at the end of a header. This function is used if the option --section is _not_ used.

INPUTS.

  • dest_doc - pointer to the file to which the output will be written.

  • cur_header - pointer to a RB_header structure.

SEE ALSO.

RB_Generate_Header_Start, RB_Generate_EndSection, RB_Generate_BeginSection

1.8.16. Generator/RB_Generate_Header_Start

NAME.

RB_Generate_Header_Start -- generate header start text.

FUNCTION.

Generates depending on the output_mode the text that will be at the end of each header.

INPUTS.

  • dest_doc - pointer to the file to which the output will be written.

  • cur_header - pointer to a RB_header structure.

SEE ALSO.

RB_Generate_Header_End

1.8.17. Generator/RB_Generate_Index_Entry

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.

INPUTS.

  • dest_doc -- the destination file.

  • header -- pointer to the header the index entry is for.

  • output_mode -- global with the current output mode.

1.8.18. Generator/RB_Generate_Item_Begin

FUNCTION.

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

INPUTS.

dest_doc -- file to be written to output_mode -- global with the current output mode

1.8.19. Generator/RB_Generate_Item_End

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.

INPUTS.

  • dest_doc -- file to be written to

  • output_mode -- global with the current output mode

1.8.20. Generator/RB_Generate_MultiDoc

FUNCTION.

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

INPUTS.

document -- pointer to the RB_Document structure.

1.8.21. Generator/RB_Generate_Part

FUNCTION.

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

INPUTS.

  • document_file -- The file were it stored.

  • document -- All the documentation.

  • part -- pointer to a RB_Part that contains all the headers found in a single source file.

1.8.22. Generator/RB_Generate_Section

FUNCTION.

Generate the documentation for a header and all its childern.

INPUTS.

  • document_file -- destination file

  • parent -- the parent of the header for which the documentation is to be generated.

  • document -- pointer to the RB_Document structure.

  • depth -- level of sectioning ( 1 1.1 1.1.1 etc)

NOTE.

This is a recursive function.

SEE ALSO.

RB_Generate_Sections

1.8.23. Generator/RB_Generate_Sections

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:

     1. Parentheader1
     1.1 Child1
     1.2 Child2
     1.2.1 Child's child1
     2. Parentheader2

etc

INPUTS.

  • document_file -- destination file.

  • document -- pointer to the RB_Document structure.

1.8.24. Generator/RB_Generate_SingleDoc

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 or RB_Generate_Part

INPUTS.

document -- pointer to the RB_Document structure.

1.8.25. Generator/RB_Generate_TOC_2

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

INPUTS.

  • dest_doc -- the destination file.

  • headers -- an array of pointers to all the headers.

  • count -- the number of pointers in the array.

  • output_mode -- global with the current output mode.

  • 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.

1.8.26. Generator/RB_Get_DOT_Type

FUNCTION.

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

1.8.27. Generator/RB_Get_SubIndex_FileName

FUNCTION.

Get the name of the master index file for a specific header_type.

INPUTS.

  • docroot -- the path to the documentation directory.

  • extension -- the extension for the file

  • header_type -- the header type

RESULT.

a pointer to a freshly allocated string.

NOTES.

Has too many parameters.

1.8.28. Generator/RB_Name_Headers

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.

1.8.29. Generator/RB_TEST_Generate_Char

NAME.

RB_TEST_Generate_Char

FUNCTION.

Switchboard to RB_TEST_Generate_Char

1.8.30. Generator/RB_XMLDB_Generate_Char

NAME.

RB_XMLDB_Generate_Char

FUNCTION.

Switchboard to RB_XMLDB_Generate_Char

1.8.31. Generator/T_RB_DocType

FUNCTION.

Enumeration for the various output formats that are supported by ROBODoc.

NOTES.

These should be prefixed with RB_

1.9. ROBODoc/Globals

FUNCTION.

A number of global variables.

TODO.

Documentation.

1.9.1. Globals/course_of_action

NAME.

course_of_action

FUNCTION.

Global Variable that defines the course of action.

1.9.2. Globals/debugmode

NAME.

debugmode

FUNCTION.

A bitfield determining the output levels

1.9.3. Globals/document_title

NAME.

documentat_title -- title for the documentation.

PURPOSE.

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

1.9.4. Globals/line_buffer

NAME.

line_buffer -- global line buffer

FUNCTION.

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

1.9.5. Globals/line_number

NAME.

line_number -- global line counter

PURPOSE.

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

AUTHOR.

Koessi

1.9.6. Globals/myLine

NAME.

myLine -- dynamic buffer for current line

FUNCTION.

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

1.9.7. Globals/output_mode

NAME.

output_mode -- the mode of output

FUNCTION.

Controls which type of output will be generated.

1.9.8. Globals/readChars

NAME.

readChars -- number of characters in the currently bufferd line

FUNCTION.

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

1.10. ROBODoc/Headers

FUNCTION.

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

NOTES.

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

1.10.1. Headers/end_markers

NAME.

end_markers -- strings that mark the end of a header.

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.

NOTE.

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

1.10.2. Headers/end_remark_constants

NAME.

end_remark_constants -- numerals for end_markers

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 by robohdrs.

1.10.3. Headers/end_remark_markers

NAME.

end_remark_markers -- strings that mark the end of a comment.

NOTE.

The numbers at the beginning of the lines make it easier to keep them in sync with the end_remark_constants

1.10.4. Headers/header_markers

NAME.

header_markers -- strings that mark the begin of a header.

FUNCTION.

These specify what robodoc recognizes as the beginning

NOTE.

The numbers at the beginning of the lines make it easier to keep them in sync with the src_constants of a header.

1.10.5. Headers/RB_Has_Remark_Marker

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.

INPUTS.

  • lline_buffer -- the line of text.

RESULT.

  • TRUE -- it starts with a remark marker

  • FALSE -- it does not.

1.10.6. Headers/RB_header

FUNCTION.

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

MODIFICATION HISTORY.

  • 8. August 1995: Koessi changed int version to char *version

ATTRIBUTES.

  • next -- used to store RB_headers in a RB_Part as a linked list.

  • parent -- the parent of this header

  • name -- the full name of the header modulename/functionname [versioninfo]

  • owner -- the Part that owns this header.

  • htype -- the type of this header.

  • items -- pointers to the items in this header.

  • version -- unused

  • function_name -- the functionname ( a better name would be objectname or thingy name, it is the name of the thing that is being documented ).

  • module_name -- the modulename

  • unique_name -- unique name used for labels.

  • file_name -- documentation file of this header.

  • lines -- content of the header

  • no_lines -- number of lines in the content.

  • line_number -- the line number at which the header was found in the source file.

1.10.7. Headers/RB_HeaderType

NAME.

RB_HeaderType -- Information about a header type

ATTRIBUTES.

  • typeCharacter -- The character used to indicate it

  • indexName -- The name used for the master index

  • fileName -- The name of the file use to store the master index for this type of headers.

1.10.8. Headers/RB_Is_End_Marker

FUNCTION.

Scan a line and see if any of the end of a header markers defined in header_markers can be found.

INPUTS.

cur_line -- line to be searched.

OUTPUT.

none

RESULT.

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

1.10.9. Headers/RB_Skip_Remark_Marker

NAME.

RB_Skip_Remark_Marker

FUNCTION.

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

1.10.10. Headers/remark_markers

NAME.

remark_markers

FUNCTION.

These specify what robodoc recognizes as a comment marker.

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

1.10.11. Headers/robo_end

NAME.

robo_end[] -- the distinct robodoc end marker -

                 alternative to using end_markers

FUNCTION.

This is an alternative to using end_markers - sometimes ROBODOC confuses asterisks commonly used in comments as an end marker. To use this footer instead of end_markers use the -rh switch.

NOTE.

Added by David Druffner.

1.10.12. Headers/robo_header

NAME.

robo_header -- the distinct robodoc header -

                  alternative to using header_markers

FUNCTION.

This is an alternative to using header_markers - sometimes ROBODOC confuses asterisks commonly used in comments as a header. To use this header instead of header_markers use the -rh switch.

NOTE.

Added by David Druffner. OBSOLETE

1.10.13. Headers/src_constants

NAME.

src_constants -- numerals for header_markers

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 by robohdrs.

1.10.14. Headers/src_remark_constants

NAME.

src_remark_constants -- numerals for remark_markers

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 by robohdrs.

1.11. ROBODoc/HeaderTypes

FUNCTION.

Headers come in different types. This module defines what kind of headertypes ROBODoc recognizes, and contains functions to add new headertypes and to compare headertypes. All the headertypes are stored in an array, header_type_lookup_table.

1.11.1. HeaderTypes/header_type_lookup_table

FUNCTION.

A lookup table for all the header types that ROBODoc 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:

     HT_MASTERINDEXTYPE

and

     HT_SOURCEHEADERTYPE

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.

1.11.2. HeaderTypes/RB_AddHeaderType

FUNCTION.

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

RESULT.

  • FALSE -- it is a new header type.

  • TRUE -- header type already existed.

1.11.3. HeaderTypes/RB_CompareHeaderTypes

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

INPUTS.

  • ht1 and ht2 -- the header types to compare.

RESULT.

  • 0 -- header types are not equal

  • != 0 -- header type are equal

1.11.4. HeaderTypes/RB_FindHeaderType

FUNCTION.

Return the header type that corresponds to the type character.

RESULT.

  • 0 -- there is no such header type

  • pointer to the header type otherwise.

1.11.5. HeaderTypes/RB_IsInternalHeader

FUNCTION.

Given the typeCharacter is this an internal header?

RESULT.

  • TRUE -- yes it is

  • FALSE -- no it is not

1.11.6. HeaderTypes/Works_Like_SourceItem

FUNCTION.

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

1.12. ROBODoc/HTML_Generator

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.

MODIFICATION HISTORY.

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

1.12.1. HTML_Generator/RB_Create_CSS

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

      robodoc.css

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

INPUTS.

  • document -- the document for which to create the file.

1.12.2. HTML_Generator/RB_HTML_Color_String

FUNCTION.

Creates einter an opening or closing color sequence

1.12.3. HTML_Generator/RB_HTML_Generate_Char

NAME.

RB_HTML_Generate_Char -- generate a single character for an item.

FUNCTION.

This function is called for every character that goes into an item's body. This escapes all the reserved HTML characters such as '&', '<', '>', '"'. It also escapes all characters above ASCII 160. See http://www.w3.org/TR/xhtml1/dtds.html#dtdentry_xhtml-lat1.ent_HTMLlat1

1.12.4. HTML_Generator/RB_HTML_Generate_Doc_Start

NAME.

RB_HTML_Generate_Doc_Start --

FUNCTION.

Generate the first part of a HTML document. As far as ROBODoc is concerned a HTML document consists of three parts:

  • The start of a document

  • The body of a document

  • The end of a document

INPUTS.

  • dest_doc -- the output file.

  • src_name -- The file or directoryname from which this document is generated.

  • name -- The title for this document

  • dest_name -- the name of the output file.

  • charset -- the charset to be used for the file.

1.12.5. HTML_Generator/RB_HTML_Generate_Extra

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.

INPUTS.

  • dest_doc -- the file to write to.

  • item_type -- the kind of item the body belongs to.

  • cur_char -- pointer to a substring of the item's body

  • prev_char -- the character just before cur char (zero if none)

RESULTS.

Number of characters produced.

1.12.6. HTML_Generator/RB_HTML_Generate_Header_Type

NAME.

RB_HTML_Generate_Header_Type

FUNCTION.

Generates header type entry in sectioning mode

INPUTS.

  • FILE* dest_doc -- destination file

  • char *name -- the type of item

AUTHOR.

Thuffir

1.12.7. HTML_Generator/RB_HTML_Generate_Index_Page

FUNCTION.

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

INPUTS.

  • document -- the document

  • header_type -- the type for which the table is to be generated.

1.12.8. HTML_Generator/RB_HTML_Generate_IndexMenu

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.

INPUTS.

  • dest_doc -- the output file.

  • filename -- the name of the output file

  • document -- the gathered documention.

  • cur_headertype -- the header type that is to be highlighted.

1.12.9. HTML_Generator/RB_HTML_Generate_Label

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.

INPUTS.

  • dest_doc -- the file to write it to.

  • name -- the name of the label.

1.12.10. HTML_Generator/RB_HTML_Generate_Link

NAME.

RB_HTML_Generate_Link --

INPUTS.

cur_doc -- the file to which the text is written cur_name -- the name of the destination file

                (the file from which we link)

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

                (the file we link to)

labelname-- the name of the unique label of the link. linkname -- the name of the link as shown to the user. in_fold -- are we inside a fold.

1.12.11. HTML_Generator/RB_HTML_Generate_TOC_Section

FUNCTION.

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

INPUTS.

  • dest_doc -- the file to write to.

  • dest_name -- the name of this file.

  • parent -- the parent of the headers for which the the current level(depth) of TOC is created.

  • headers -- an array of headers for which the TOC is created

  • count -- the number of headers in this array

  • depth -- the current depth of the TOC

NOTES.

This is a recursive function and tricky stuff.

1.12.12. HTML_Generator/RB_HTML_RelativeAddress

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.

EXAMPLE.

The following two

     this /sub1/sub2/sub3/f.html
     that /sub1/sub2/g.html

result in

     ../g.html

     this /sub1/f.html
     that /sub1/sub2/g.html
     ==
     ./sub2/g.html

     this /sub1/f.html
     that /sub1/g.html
     ==
     ./g.html

     this /sub1/doc3/doc1/tt.html
     that /sub1/doc5/doc2/qq.html
     ==
     ../../doc5/doc2/qq.html

NOTES.

Notice the execelent docmentation.

1.13. ROBODoc/Items

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.items. A uses can specify that certain items are not to be added to the documentation. These items are listed in configuration.ignore_items.

AUTHOR.

Frans Slothouber

1.13.1. Items/item_name_buffer

FUNCTION.

Stores the name of the last item that was found.

1.13.2. Items/ItemTypes

NAME.

ItemTypes -- enumeration of item types

FUNCTION.

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

  • the SOURCE item which is always available,

  • and items defined by the user (or through the default items).

1.13.3. Items/RB_Create_Item

1.13.4. Items/RB_Get_Item_Type

FUNCTION.

return the item_type represented by the given string.

INPUTS.

char *cmp_name -- item_name to evaluate

RESULT.

int -- the right item_type or NO_ITEM

1.13.5. Items/RB_Is_ItemName

FUNCTION.

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

INPUTS.

line -- line to be searched.

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.

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.

1.13.6. Items/RB_Item

FUNCTION.

Keeps track of where items start end end in the header. The index numbers point to the lines array in RB_header.

1.14. ROBODoc/LaTeX_Generator

FUNCTION.

Generator for LaTeX output. Supports singledoc mode.

1.14.1. LaTeX_Generator/Generate_LaTeX_Includes

NAME.

Generate_LaTeX_Includes -- generate include commands

FUNCTION.

Generates a series of \include commands to include the documentation generated for each source file into one big file.

1.14.2. LaTeX_Generator/RB_LaTeX_Generate_Char

FUNCTION.

Generate a single character. These characters are generated within a begin{verbatim} end{verbatim} block So no escaping is necessary.

1.14.3. LaTeX_Generator/RB_LaTeX_Generate_Doc_End

NAME.

RB_LaTeX_Generate_Doc_End --

1.14.4. LaTeX_Generator/RB_LaTeX_Generate_Doc_Start

NAME.

RB_LaTeX_Generate_Doc_Start --

1.14.5. LaTeX_Generator/RB_LaTeX_Generate_Empty_Item

NAME.

RB_LaTeX_Generate_Empty_Item --

1.14.6. LaTeX_Generator/RB_LaTeX_Generate_EscapedChar

FUNCTION.

Generate a single character. These characters are outside a begin{verbatim} end{verbatim} block. So we need to escape is special characters. These are

       _  =>  \_
       %  =>  \%
       $  =>  \$
       <  =>  \textless
       >  =>  \textgreater
       \  =>  $\backslash$

SEE ALSO.

RB_LaTeX_Generate_Char()

1.14.7. LaTeX_Generator/RB_LaTeX_Generate_Header_End

NAME.

RB_LaTeX_Generate_Header_End --

1.14.8. LaTeX_Generator/RB_LaTeX_Generate_Header_Start

NAME.

RB_LaTeX_Generate_Header_Start --

1.14.9. LaTeX_Generator/RB_LaTeX_Generate_Header_Type

NAME.

RB_LaTeX_Generate_Header_Type --

FUNCTION.

Generate Header Type entry

INPUTS.

dest_doc -- the file to which the text is written name -- the type of header

AUTHOR.

Thuffir

1.14.10. LaTeX_Generator/RB_LaTeX_Generate_Index_Entry

FUNCTION.

Creates a entry for the index.

1.14.11. LaTeX_Generator/RB_LaTeX_Generate_Index_Table

NAME.

RB_LaTeX_Generate_Index_Table --

1.14.12. LaTeX_Generator/RB_LaTeX_Generate_Label

NAME.

RB_LaTeX_Generate_Label --

INPUTS.

dest_doc -- the file to which the text is written name -- the unique name of the label to create

1.14.13. LaTeX_Generator/RB_LaTeX_Generate_Link

NAME.

RB_LaTeX_Generate_Link --

INPUTS.

cur_doc -- the file to which the text is written cur_name -- the name of the destination file (unused)

                (the file from which we link)

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

                (the file we link to) (unused)

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

1.14.14. LaTeX_Generator/RB_LaTeX_Generate_String

FUNCTION.

Write a string to the destination document, escaping characters where necessary.

1.15. ROBODoc/Links

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.

MODIFICATION HISTORY.

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

1.15.1. Links/Find_Link

NAME.

Find_Link -- try to match word with a link

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

  • In the first pass it is any thing that ends with a 'space', a '.' or a ','.

  • In the second pass it is any string that consists of alpha numerics, '_', ':', '.', or '-'.

  • In the third pass (for C) it is any string that consists of alpha numerics or '_'.

INPUTS.

  • word_begin - pointer to a word (a string).

  • object_name - pointer to a pointer to a string

  • file_name - pointer to a pointer to a string

SIDE EFFECTS.

label_name & file_name are modified

RESULT.

  • object_name -- points to the object if a match was found, NULL otherwise.

  • file_name -- points to the file name if a match was found, NULL otherwise.

  • label_name -- points to the labelname if a match was found,

  • TRUE -- a match was found.

  • FALSE -- no match was found.

NOTES.

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

1.15.2. Links/RB_Alloc_Link

NAME.

RB_Alloc_Link -- oop

FUNCTION.

allocate struct + strings

INPUTS.

char *label_name -- strings to copy into the link char *file_name

RESULT.

struct RB_link * -- ready-to-use

AUTHOR.

Koessi

SEE ALSO.

RB_StrDup(), RB_Free_Link()

1.15.3. Links/RB_CollectLinks

FUNCTION.

Convert header information into link information.

      RB_header -> RB_link conversion

INPUTS.

  • document --

  • headers -- the array with headers.

  • count -- number of headers in the array

OUTPUT.

  • link_index -- an array with links

  • link_index_size -- the number of links in the array.

1.15.4. Links/RB_Free_Link

NAME.

RB_Free_Link -- oop

FUNCTION.

free struct + strings

INPUTS.

struct RB_link *link

AUTHOR.

Koessi

SEE ALSO.

RB_Alloc_Link(), RB_Close_The_Shop()

1.15.5. Links/RB_Free_Links

FUNCTION.

Deallocate all the memory used to store the links.

INPUTS.

  • link_index_size

  • link_index[]

BUGS.

Should use RB_Free_Link instead of doing everything by it self.

1.15.6. Links/RB_link

NAME.

RB_link -- link data structure

PURPOSE.

Structure to store links to the documentation of an component.

ATTRIBUTES.

  • label_name -- the label under which the component can be found. this should be a unique name.

  • object_name -- the proper name of the object

  • file_name -- the file the component can be found in.

  • type -- the type of component (the header type).

  • is_internal -- is the header an internal header?

1.16. ROBODoc/makefile.mingw-cygwin

NAME.

makefile.mingw-cygwin -- Plain makefile that does not need autoconf

PURPOSE.

The makefile for MingW Minimalist GNU for Windows under the Cygwin environment, See:

  • http://www.mingw.org,

  • http://www.cygwin.com

You can use it if you are on a win32 system.

The following targets are the most useful for the user:

  • robodoc - makes the robodoc executable.

Developers might try:

  • test - run system tests

  • clean - clean all results.

EXAMPLES make -f makefile.mingw-cygwin robodoc make -f makefile.mingw-cygwin test make -f makefile.mingw-cygwin clean

1.16.1. makefile.mingw-cygwin/CFLAGS

FUNCTION.

Defined the flags used for the C compiler:

  • -W, -Wall and -std=gnu99 -- This turns on all warnings based on the C99 standard. Making the source warning free for an earlier standard is not necessary as this code is compiled on Unix, Windows, and Mac systems that all have C99 compliant C compilers. It also allows some gnu extensions. Using -std=c99 gives some spurious warnings about popen()

  • -O3 -- optimize, turning optimization on finds more errors and warnings.

  • -mno-cygwin -- Tells gcc not to link with cygwin1.dll but use the windows standard C library. (make mingw windows native executable under cygwin)

  • -s -- Strip debug info out from objects, making the executable smaller

1.16.2. makefile.mingw-cygwin/clean

NAME.

clean -- Clean up the mess we made.

FUNCTION.

Cleans up the mess we made.

1.16.3. makefile.mingw-cygwin/robodoc

NAME.

robodoc --

NOTE.

This assumes that your version of make knows how to make an .o file out of an .c file.

1.16.4. makefile.mingw-cygwin/robohdrs

NAME.

robohdrs --

1.16.5. makefile.mingw-cygwin/SOURCES

FUNCTION.

All source files needed to compile ROBODoc

1.16.6. makefile.mingw-cygwin/test

NAME.

test -- run some tests

FUNCTION.

Runs robodoc on file with a number of different headers.

1.17. ROBODoc/Part

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) are stored in a RB_Document structure.

1.17.1. Part/RB_Free_RB_Part

FUNCTION.

Free the memory used by an RB_Part. Most of this is handled in other functions.

INPUTS.

  • part -- the part to be freed.

1.17.2. Part/RB_Get_RB_Part

FUNCTION.

Create a new RB_Part and initialize it.

RESULT.

A freshly allocated and initializedand RB_Part.

1.17.3. Part/RB_Open_Source

FUNCTION.

Open the sourcefile of this part.

INPUTS.

  • part -- the part for which the file is opened.

1.17.4. Part/RB_Part

NAME.

RB_Part -- a part of the total documentation

FUNCTION.

RB_Parts are stored in RB_Document. 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.

ATTRIBUTES.

  • next -- pointer to the next part (to form a linked list).

  • filename -- Information over the path to the sourcefile and the correcsponding documentation file.

  • headers -- All the headers that were found in the sourcefile.

  • 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.

1.18. ROBODoc/RTF_Generator

FUNCTION.

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

TODO.

Documentation

MODIFICATION HISTORY.

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

1.19. ROBODoc/Test_Generator

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.

MODIFICATION HISTORY.

  • 2004-05-20 Frans Slothouber V1.0

1.20. ROBODoc/TROFF_Generator

FUNCTION.

Generator for TROFF output.

NOTE.

Almost finished.

1.20.1. TROFF_Generator/RB_TROFF_Generate_Doc_End

NAME.

RB_TROFF_Generate_Doc_End --

1.20.2. TROFF_Generator/RB_TROFF_Generate_Header_End

NAME.

RB_TROFF_Generate_Header_End --

1.20.3. TROFF_Generator/RB_TROFF_Generate_Header_Start

NAME.

RB_TROFF_Generate_Header_Start

1.21. ROBODoc/UserInterface

FUNCTION.

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

1.21.1. UserInterface/Add_Option_Name

FUNCTION.

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

INPUTS.

option_test -- the option test name -- the name of the option

1.21.2. UserInterface/Add_Option_Test

FUNCTION.

Add a test to the linked list of options tests.

INPUTS.

option_test -- the test to be added.

1.21.3. UserInterface/Check_Option_Spelling

FUNCTION.

Check for misspelled options specified by the user.

RESULT.

  • EXIT_SUCCESS -- all options are correctly spelled.

  • EXIT_FAILURE -- one of more options are misspelled.

1.21.4. UserInterface/Check_Options

FUNCTION.

Check the validity of all the options in configuration.options[]. This runs a number of checks.

RESULT.

  • EXIT_SUCCESS -- all options are correct.

  • EXIT_FAILURE -- one of more options incorrect.

1.21.5. UserInterface/copying

FUNCTION.

Information about the ROBODoc licence.

AUTHOR.

Frans

1.21.6. UserInterface/Create_New_Option_Test

FUNCTION.

Allocate and initialize a new option test.

INPUTS.

kind -- the kind of test that has to be created.

1.21.7. UserInterface/Create_Test_Data

FUNCTION.

Create a linked list of tests.

TODO.

Generate this code automatically from a set of high-level specifications.

1.21.8. UserInterface/Do_Mutual_Exlcude_Test

FUNCTION.

Check all the options to see if combinations of options are used that mutually exclude each other, such as --singledoc and --multidoc.

INPUTS.

  • cur_option_test -- the test to be carried out.

1.21.9. UserInterface/Do_Option_Tests

FUNCTION.

Run a series of tests on the options that the user specified. These tests are specified in option_tests.

RESULT.

  • EXIT_FAILURE -- one of the tests failed.

  • EXIT_SUCCESS -- all test completed successfully

1.21.10. UserInterface/Find_And_Fix_Path

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 of '\' or when it does not start with ./ or a drive name. The option must exist.

INPUTS.

  • option_name -- the option name for the path

RESULT.

  • path -- the path.

1.21.11. UserInterface/Find_Option

FUNCTION.

Search configuration.options for a specific option.

RESULT.

  • TRUE -- option does exist

  • FALSE -- option does not exist

1.21.12. UserInterface/Find_Parameterized_Option

FUNCTION.

Search for an option of the form

     --a_option_name a_value

in configuration.options.

INPUTS.

optionname -- the name of the option to search for.

RESULT.

NULL if the option is not found, a pointer to the value otherwise.

NOTES.

Results in a Panic if the option is found but no value is specified.

1.21.13. UserInterface/Fix_Path

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.

INPUTS.

  • path -- the path to be fixed.

RESULT.

A pointer to a newly allocated string containing the path.

1.21.14. UserInterface/General_Find_Parameterized_Option

FUNCTION.

Search for an option of the form

     --a_option_name a_value

INPUTS.

  • n -- the number of options in the options array.

  • options -- the options array

  • optionname -- the name of the option to search for.

RESULT.

NULL if the option is not found, a pointer to the value otherwise.

NOTES.

Results in a Panic if the option is found but no value is specified.

1.21.15. UserInterface/main

FUNCTION.

Get and parse the arguments. Analyse document and generate the documentation. Everything starts from here.

1.21.16. UserInterface/ok_options

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.

1.21.17. UserInterface/Option_Test_Kind

FUNCTION.

Enumeration for the kind of tests that are carried out on the options that the user specifies.

1.21.18. UserInterface/option_tests

FUNCTION.

A linked lists of tests that check the options specified by the user.

1.21.19. UserInterface/Path_Check

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.

INPUTS.

  • sourcepath -- the path to the source files.

  • docpath -- the path to the documentation files.

OUTPUT.

  • error messages

1.21.20. UserInterface/Path_Convert_Win32_to_Unix

FUNCTION.

Although people are supposed to specify all paths with a '/' as seperator, sometimes people on Win32 use '\', this causes problems later on in some other function of robodoc that expect a '/'. So to prevent this we replace all the '\' in a path with '/'

In addition people sometimes add a '/' at the end of the path. We remove it.

INPUTS.

  • path -- the path.

RESULT.

  • path -- the converted path (in a newly allocated block of memory).

1.21.21. UserInterface/PathBegin_Check

FUNCTION.

Checks the validity of a path. A path should start with

     ./

or

     /

or

     have a ':' some where

INPUTS.

  • path -- the path to be cheked.

RESULT.

  • FALSE -- path is not OK.

  • TRUE -- path is OK.

1.21.22. UserInterface/RB_Find_In_Argv_Parameterized_Option

FUNCTION.

Search for an option of the form

     --a_option_name a_value

in argv. The function is used to look for the

     --rc

option that can be used to specify an alternate robodoc configuration file.

INPUTS.

  • argc -- the argument count as received by main().

  • argv -- the array of argument values as received by main()

  • optionname -- the name of the option to search for.

RESULT.

NULL if the option is not found, a pointer to the value otherwise.

NOTES.

Results in a Panic if the option is found but no value is specified.

1.21.23. UserInterface/RB_Option_Name

FUNCTION.

Element in a list of option names. Used in a RB_Option_Test to specify to what options a test applies.

1.21.24. UserInterface/RB_Option_Test

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.

1.21.25. UserInterface/use

NAME.

use -- usage string

FUNCTION.

Inform the user how to use ROBODoc.

AUTHOR.

Koessi

1.22. ROBODoc/Utilities

FUNCTION.

Set of general purpose utility functions that are used in more than one module.

1.22.1. Utilities/Close_Pipe

FUNCTION.

Closes a given pipe

1.22.2. Utilities/cwd

FUNCTION.

Holds current working directory

1.22.3. Utilities/ExpandTab

FUNCTION.

Expand the tabs in a line of text.

INPUTS.

line -- the line to be expanded tab_size -- global. RETURN pointer to the expanded line.

NOTE.

This function is not reentrant.

1.22.4. Utilities/Make_crc32_table

FUNCTION.

Builds up crc32 lookup table for crc32 function. Call this before calling to RB_crc32()

1.22.5. Utilities/Open_Pipe

FUNCTION.

Opens a pipe and returns its handler

1.22.6. Utilities/Path2Win32Path

1.22.7. Utilities/RB_Alloc_Header

FUNCTION.

allocate the struct RB_header

RESULT.

struct RB_header * -- all attributes/pointers set to zero

AUTHOR.

Koessi

SEE ALSO.

RB_Free_Header()

1.22.8. Utilities/RB_Change_Back_To_CWD

FUNCTION.

Changes back to saved working directory and frees cwd string

1.22.9. Utilities/RB_Change_To_Docdir

FUNCTION.

Saves current working directory and then changes to document dir

1.22.10. Utilities/RB_ContainsNL

FUNCTION.

Check whether the provided line buffer contains a new line (NL) character.

INPUTS.

  • line -- line string to process

RETURN VALUE.

  • TRUE -- the line contains a NL character

  • FALSE -- the line does not contain a NL character

1.22.11. Utilities/RB_CopyFile

NAME.

RB_CopyFile -- copy a file to another file

RESULT.

Program Exit if one of the specified files did not open.

1.22.12. Utilities/RB_crc32

FUNCTION.

calcualtes crc32 value for a given buffer

INPUTS.

  • buf: input buffer to calculate

  • len: length of buffer

  • crc32: CRC32 init value

RETURN VALUE.

CRC32 value

1.22.13. Utilities/RB_crc32_table

FUNCTION.

CRC32 lookup table for crc32 functions

1.22.14. Utilities/RB_FputcLatin1ToUtf8

NAME.

RB_FputcLatin1ToUtf8

BUGS.

This wrongly assumes that input is always Latin-1.

1.22.15. Utilities/RB_Free_Header

NAME.

RB_Free_Header -- oop

FUNCTION.

free struct RB_header and associated strings

INPUTS.

struct RB_header *header -- this one

AUTHOR.

Koessi

SEE ALSO.

RB_Alloc_Header(), RB_Close_The_Shop()

1.22.16. Utilities/RB_FreeLineBuffer

FUNCTION.

Free the dynamically allocated line-buffer

INPUTS.

  • works on the globals line_buffer, readChars, myLine

1.22.17. Utilities/RB_Get_Saved_CWD

FUNCTION.

Changes back to saved working directory and frees cwd string

1.22.18. Utilities/RB_malloc

FUNCTION.

like malloc, but exit if malloc failed

RETURN VALUE.

See malloc

1.22.19. Utilities/RB_Match

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:

      "*aap"   matches "aapaapaapaap"
      "?inux"  matches "linux"
      "lin*ux" matches "linux"
      "linux*" matches "linux"

NOTES.

This is a recursive function.

INPUTS.

  • target -- the string to be matched agains the wildcard_expression.

  • wildcard_expression -- the wildcard expression

RETURN VALUE.

TRUE -- the target matches the wildcard expression FALSE -- it does not match.

1.22.20. Utilities/RB_Mem_Check

FUNCTION.

Check for memory allocation failures.

1.22.21. Utilities/RB_Panic

NAME.

RB_Panic -- free resources and shut down

FUNCTION.

Print error message. Frees all resources used by robodoc. Terminates program. Output goes to stderr

INPUTS.

char *format -- formatstring ... -- parameters

AUTHOR.

Koessi

1.22.22. Utilities/RB_QuickSort

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.

INPUTS.

array -- the array of pointers. left -- the most left element in the array. right -- the most right element in the array. f -- pointer to a function that can compare

            the objects two elements of the array
            point to.

RESULT.

array -- A sorted array of pointers.

EXAMPLE.

The following is an example program that shows the use

    #define TEST_SIZE 10

    char* test[ TEST_SIZE ] = { "ape", "zebra",
       "duck", "goofbal", "dodo", "rabit",
       "crow", "cow", "pig", "goat" };

    int string_compare( void* p1, void* p2 )
    {
       char *cp1 = p1;
       char *cp2 = p2;
       return strcmp( cp1, cp2 );
    }

    RB_QuickSort( test, 0, TEST_SIZE - 1, string_compare );

1.22.23. Utilities/RB_ReadWholeLine

FUNCTION.

Read a line from the file using the provided buffer.

INPUTS.

  • file -- file to read from

  • buf -- buffer of length MAX_LINE_LEN to read chunks of the line to

  • readChars -- reference to the variable to store the read characters in

RETURN VALUE.

  • returns a dynamically allocated buffer containing the complete line read

NOTES.

If the line did not end in a new line (NL) character one is added.

1.22.24. Utilities/RB_Say

NAME.

RB_Say -- varargs

FUNCTION.

Say what's going on. Goes to stdout.

INPUTS.

char *format -- formatstring long mode -- SAY_INFO | SAY_DEBUG

    ...                    -- parameters

AUTHOR.

Koessi

1.22.25. Utilities/RB_Skip_Whitespace

FUNCTION.

Skip space and tab chars from the start *buf. This is needed when searching for indented headers and items.

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.

SEE ALSO.

RB_Find_Marker, RB_Find_End_Marker, RB_Find_Item, RB_Generate_Item_Body

1.22.26. Utilities/RB_Str_Case_Cmp

FUNCTION.

Compare two strings, regardless of the case of the characters.

RESULT.

0 s == t -1 s < t 1 s > t

1.22.27. Utilities/RB_StripCR

FUNCTION.

Strip carriage return (CR) from line.

INPUTS.

  • line -- line string to process

1.22.28. Utilities/RB_Swap

FUNCTION.

Swap two elements in a array of pointers. This function is used by RB_QuickSort().

1.22.29. Utilities/RB_TimeStamp

NAME.

RB_TimeStamp -- print a time stamp

1.22.30. Utilities/Stat_Path

FUNCTION.

Check the given path against required type. d -- directory, f -- file, e -- exists

RETURN VALUE.

TRUE if path is of the given type, otherwise FALSE.

BUGS.

Should check if symbolic link points to a directory or to a file.

1.23. ROBODoc/Lua_Generator

FUNCTION.

Shell generator that actually gives data to a Lua script. Supports singledoc mode.

AUTHOR.

Jeremy Cowgar <jc@cowgar.com>

NOTES.

No code defined yet. This is just a shell.

1.24. ROBODoc/RB_Path

NAME.

RB_Path -- Path to a file

ATTRIBUTES.

  • next -- pointer to the next RB_Path structure.

  • parent -- the parent path (one directory up).

  • name -- null terminated string with the name of the path. (Path names can be relative)

  • docname -- the corresponding docpath.


2. Docuwala/ROBOhdrs

NAME.

robohdrs

DESCRIPTION.

Standalone program to insert ROBODoc headers to source code files. This program processes one source file at the time. Existing ROBODoc headers, if any, are not checked for. Beware since this may result in double headers. Current working directory should be the same as where the source file is located.

USES.

Exuberant Ctags 5.3.1 or newer required

USAGE.

robohdrs [options] <source file>

EXAMPLE.

robohdrs -p myproj test1.c robohdrs -s -p myproj -i "MODIFICATION HISTORY" -i IDEAS test2.c

Type `robohdrs -h' to see all command line options.

TODO.

  • garbage collection

  • support for other languages which ctags program supports

SEE ALSO.

ROBODoc https://sourceforge.net/projects/robodoc/ Exuberant Ctags http://ctags.sourceforge.net/

COPYRIGHT.

(c) 2003 Frans Slothouber and Petteri Kettunen Copying policy: GPL

2.1. ROBOhdrs/addList

NAME.

addList

2.2. ROBOhdrs/arrangeCtags

NAME.

arrangeCtags

2.3. ROBOhdrs/cleanUp

NAME.

cleanUp

2.4. ROBOhdrs/cmdLine

NAME.

cmdLine

2.5. ROBOhdrs/ctags

NAME.

ctags

2.6. ROBOhdrs/ctagsBin

NAME.

ctagsBin

2.7. ROBOhdrs/custhdrs

NAME.

custhdrs

2.8. ROBOhdrs/doCtagsExec

NAME.

doCtagsExec

2.9. ROBOhdrs/doFile

NAME.

doFile

2.10. ROBOhdrs/incSrc

NAME.

incSrc

2.11. ROBOhdrs/initMe

NAME.

initMe

2.12. ROBOhdrs/insertHeaders

NAME.

insertHeaders

2.13. ROBOhdrs/insertSrcEnd

NAME.

insertSrcEnd

2.14. ROBOhdrs/linenumCompare

NAME.

linenumCompare

2.15. ROBOhdrs/main

NAME.

main

2.16. ROBOhdrs/MAXLINE

NAME.

MAXLINE

2.17. ROBOhdrs/MAXNAME

NAME.

MAXNAME

2.18. ROBOhdrs/myctags

NAME.

myctags

2.19. ROBOhdrs/parseCtagsX

NAME.

parseCtagsX

2.20. ROBOhdrs/parseCtagsXLine

NAME.

parseCtagsXLine

2.21. ROBOhdrs/PROGNAME

NAME.

PROGNAME

2.22. ROBOhdrs/PROGVERSION

NAME.

PROGVERSION

2.23. ROBOhdrs/projName

NAME.

projName

2.24. ROBOhdrs/roboFileHeader

NAME.

roboFileHeader

FUNCTION.

Insert source file header.

2.25. ROBOhdrs/roboHeader

NAME.

roboHeader

2.26. ROBOhdrs/srcSta

NAME.

srcSta

SEE ALSO.

src_constants

2.27. ROBOhdrs/typeOk

NAME.

typeOk

2.28. ROBOhdrs/usage

NAME.

usage

2.29. ROBOhdrs/vcTag

NAME.

vcTag

DESCRIPTION.

Version control tag string. This is always specified by the user.