Redocumenting Ada 83 code to 95 - in wordprocessor files

Redocumenting Ada 83 code to 95 - in wordprocessor files

[William A Whitaker]

I would like to pass on a observation that I have found very useful. 

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.

The key to it being useful was that a number (<100) fragments were
identified as properly being caps, code stuff like IO, ID, general text
like ISO, IEC, DARPA, MIL, STD, ..., and a bunch of applications
specific identifiers like TACAN, ATC, ILS, IFF, ... 

It was a matter of looking at the document and picking out those special
words, but I suspect that this document had many more than usual, and it
was still less than 100, and they mostly were well known ahead of time. 
The whole process for about 300 pages should take a couple of hours,
inculding writing the code.  (I have code I will send to anyone
interested, but hold no brief for my coding skills.) I believe this is a
substantial saving over doing it by hand, and the saving would be
greater on longer documents.

Of course you still have to do the editing for the changes made to the
code, but doing the reformat in place in the wordprocessing file
maintains all the section numbering and font codes.

I have only done it with the WordPerfect file, but it probably will work
with any other wordprocessor.

I offer this as an idea which might be useful if you have a similiar
problem in converting documentation, backed by the experience of
actually having done it on an interesting sized example.

Whitaker

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

[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