A selection of tools, mostly taken out of larger applications

Unix

Over shar, shark has a number of advantages:

• it produces code that creates all the necessary subdirectories
• it produces code that restores links existing at shark time
• it handles exec permissions
• allows to specify multiple "autoexec" and "plugin" scripts
• has two file names of special significance
  • entry
  • readme
  entry can be used to produce a custom entry message; readme to give the user last minute info at the end of the unshark process. Both files can be placed in any subdir in the argument list. Note that there can be only be entry, and it is NOT unsharked. By contrast, more than one readme is allowed.

4glWorks

Requires: 4glWorks 2.0b10 or above

Requires: 4glWorks 2.0b13 or above

Requires: 4glWorks 2.0b13 or above

SQSL

Informix-4gl

• it tries to preserve as much as possible line numbers. In particular, #define and comments only #include files will not alter the line count of the resulting 4gl file.
• has directory search capabilities, so you can place globals & #include files in different directories from your source code
• directives can be included in, and are applied to globals files as well, allowing you, for instance, to have application-wide arrays whose size depends on the application being compiled, or have a primitive user defined type declaration
• as a bonus, it simulates multiple globals files, if your 4gl doesn't support them

A word of caution: to speed up execution, fglpp uses pattern matching for substituting definitions. This is not totally secure, and, for poorly named #defines, it could lead to the wrong token being substituted (this usually leads to compile time errors - so fear not incomprehensible bugs, at least if you don't name a definition like a substring of another).
Also, no attempt has been made to avoid substitutions within comments or quoted strings.
One of these centuries, I'll write a similar tool in c. For now this is what I have to offer.

Scriba is a set of awk and shell scripts written to quickly gather and format documentation info straight from 4gl source code, much like java's javadoc tool.

I tried to put the accent on the ability to automatically update documentation whenever the code changes. The documentation extractor can keep track of the functions that have already been documented, and extracts only info from those that haven't.
Other tools can subsequently be used to merge HTML documentation files, preserving possible headers and footers, and sorting the resulting file by function name; generate a TOC from this sorted HTML file, and insert (or update) the TOC itself back in the documentation or in a main TOC file.

The core of the tool, create_man_entries, scans 4gl source files extracting FUNCTION and REPORT declarations, complete with parameter DEFINEs, as well as comments (purged from decorative lines - those full of #,=,-_+,*) found right before the declarations themselves and all the RETURNed values, the idea behind this being that such comments will give a description of the function purposes, while the RETURNed values will prove useful when manually polishing the documentation.
The tool output is, of course, already formatted and provides a pointer to the source file, the already mentioned "declaration", "purpose" and "returns" sections, as well as a "notes" and "example" section, which will have to be filled in by hand.
I have tested it against a variety of coding habits, using code mostly coming from the IIUG software archives, and except for one author (who simply doesn't put comments on top of functions or reports) it has always extracted the correct code and comments.

Perl