Historic Ada Project Management

... or more whimsically, "how to defeat the Warsaw Pact by writing software".

I've been skimming the contents of the Public Ada Library ISO images mentioned in my previous post. It's definitely a product of the Cold War.

Public Ada Library

A lot of these assets are also catalogued in the "Ada and Software Engineering Library", but I haven't found my way around there yet.

Ada and Software Engineering Library

The "ada/asr" subtree on PAL disk 2 is an archive of the "Ada Software Repository" (ASR) which I find interesting because there seems to be a coherent vision of how software should be developed, and tools to back it up. A lot of the credit for this is due to Richard Conn, whose name I see popping up over the place. I hope he's doing well. I've resurrected some old projects and submitted them to Alire:

• pager2, a text file archiver/unarchiver
• ptf, a nroff clone. This is from a family tree including the "Software Tools" and "Software Tools in Pascal" books, which are quite good.
• x1804, a primitive doc generator, like Doxygen

Resurrecting Old Projects

• A typical PAL project will be a Zip archive containing some .src files. These need to be processed by pager2, usually to generate .ada files.
• In turn, Gnat requires that you run gnatchop on these .ada files to get the source code into its final .ads and .adb form.
• I prefer the Fossil SCM tool personally, so create a new repo on chiselapp.com, then clone and open it locally.
• You can run "alr init" on this empty directory to add the initial skeleton. You'll need to research the original software license (anything I looked at was Public Domain, YMMV) to answer a question here.
• Copy the generated .ads & .adb files to the "src" directory of the new project, and add them.
• If there is any documentation (probably in ptf format), put it in a "doc" subdirectory.
• I put any other files, like the .pro that is supposed to be a prologue, into the project root. I aim to not lose anything from the original archive (even if the format changes, e.g. to .ads/.adb).
• You should update the version in alire.toml.
• After committing, copy the "latest tarball" URL from chiselapp.com
• Run "alr publish <url>", and follow the prompts.
• Approve the PR for review on github

You can run "alr build --release" and "alr install" in your local clone to install the tool to ~/.alire/bin for your own use.

Software Documentation for the ASR

This is driven by the then-current DoD-STD-2167A software process standard. There is a set of templates in the ada/asr/std2167a directory of disk 2 of the PAL.

The subset used by the projects I was looking at are:

• Software Requirements Specification (SRS)
• Software Design Document (SDD). Some of this can be generated using x1804.
• Version Description Document (VDD). This might be a ChangeLog nowadays.
• Software User's Manual (SUM). This might be a man page or TexInfo nowadays.

Like I said, the thing I find interesting about these is the fact that the contributors to the ASR could come to an agreement (given what I know of the egos of good software engineers). This enabled investment in tool support, and reduced cognitive load e.g. when ptf was picked as the format for all ASR documentation.

So how would you use this in practice?

• Once my PRs are merged, you should be able to "alr install" ptf and x1804.
• Then you can copy templates from the std2167a archive, I'd recommend the 4 above doc types to start.
• The paragraphs you have to fill in are enclosed in square brackets.
• You can mark up some .ads files with the X1804 tags, then extract this to .ptf format.
• When you format the documents using ptf the output is just plain text, but I'm writing on Gemini so assume that is fine.

Successors

DOD-STD-2167A is quite old, it was for developing weapons to counter the Soviet Union. The immediate successor was MIL-STD-498, which still seems somewhat popular but the easiest way to use this is with Microsoft Word or LibreOffice templates. If you're interested, these templates are in ada/docs/498_dids on disk 1 of the PAL. But I find DoD-STD-2167A more interesting because it was the foundation of an Ada ecosystem/culture, at least for a time.

Recommendations for tailoring MIL-STD-498 for projects in $CURRENT_YEAR

Conclusion

Unless you're being paid for it, you won't want to write a full DoD-STD-2167A doc set. However, I find the tool support and the choice of a useful subset of documents to be interesting. It looks worth a try at least, provided you use your judgement to avoid unnecessary work.

Back to my gemlog