Re: Redocumenting Ada 83 code to 95 - in wordprocessor files

[munck@Mill-Creek-Systems.com (Robert Munck)]

On Thu, 16 Oct 1997 23:41:11 -0400, William A Whitaker
<whitaker@erols.com> wrote:

>I had to redo several hundred pages of documentation for a system in Ada
>83.  The code and the text was well 83 formatted (capital letters for
>identifiers).  The documentation was in WordPerfect 5.1.
>
>I wrote a little program to skip the 30 KB that wordproecssors load onto
>the front of their files and then pick out all the all-caps words, in
>both the text and the code examples.  These were reformatted to Ada 95.

I'd suggest that in these days of modern times the better
approach would be to convert to HTML and then use things
like style sheets (including text-transform) to do the
appropriate things to the Ada code and text.  Of course,
once you're in hypertext, links can be added to
requirements specs, tests, relevant standards, etc.
I find that using multiple fonts, weights, slants, sizes,
colors, etc can make code much more readable, not to
mention using dynamic HTML functions to do things like
expanding and contracting blocks with mouseclicks.

My normal practice now is to use Visio to build structure and
block diagrams of various kinds and create links from various
blocks, arrows, etc to the appropriate code and requirements.
I deliver the entire product as a single complex hypertext.

Bob Munck
Mill Creek Systems LC