From mboxrd@z Thu Jan  1 00:00:00 1970
X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on polar.synack.me
X-Spam-Level: 
X-Spam-Status: No, score=0.2 required=5.0 tests=BAYES_00,INVALID_MSGID,
	REPLYTO_WITHOUT_TO_CC autolearn=no autolearn_force=no version=3.4.4
X-Google-Language: ENGLISH,ASCII-7-bit
X-Google-Thread: 103376,17bf1dfc43abe4f6,start
X-Google-Attributes: gid103376,public
From: William A Whitaker <whitaker@erols.com>
Subject: Redocumenting Ada 83 code to 95 - in wordprocessor files
Date: 1997/10/16
Message-ID: <3446DE57.3D45@erols.com>#1/1
X-Deja-AN: 281117494
Organization: Erol's Internet Services
X-Received-On: 17 Oct 1997 03:42:44 GMT
Reply-To: whitaker@erols.com
Newsgroups: comp.lang.ada
Date: 1997-10-16T00:00:00+00:00
List-Id: <comp.lang.ada>


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