[Info-vax] VMS documentation, was: Re: Special deals on Tape Drives

[Stephen Hoffman]

On 2022-03-13 01:12:37 +0000, chris said:

> It's a while since I used the grey wall, but to be fair, all the info 
> was there, it's just wasn't organised in a way that made things easy to 
> find. I remember doing some serial comms work years ago and needed to 
> consult 3 or 4 volumes to find the info, bits of which were distributed 
> across all of them. System service calls can be a bit arcane as well, 
> though that's probably just a matter of familiarity.

Descriptors and system services are arcane, and with lots of glue code 
in languages without built-in support. And often with glue code, even 
in those languages with better support.

Navigation in the current OpenVMS documentation needs help, and the 
availability of recipes—what used to be in TIMA/STARS and what was once 
accessible via AskQ and ilk—are lacking. The OpenVMS doc is old, 
piecemeal, and in need of an overhaul and updates.

As examples of gaps in the current OpenVMS documentation: writing 
secure apps, data security, and network security applications. There 
are others. VSI is aware of these gaps, and has a support database 
replacement presently being populated. When the product support team 
can't find an existing recipe or existing example to send to a 
customer, they presumably write one anew, and add it to the database. 
This all takes time and effort. Substantive other work here awaits, too.

One longer-term downside of providing these source code examples is 
that any bugs or issues or limits tend to spread widely, should those 
arise in any examples. And these are easy mistakes to make, whether 
around error handling or data security, or otherwise. Which means 
abstracting this code can be preferable (remove the glue code, and 
improve the APIs), whether it's moving descriptors into objects, or 
providing better-abstracted APIs for the most commonly employed source 
code recipe sequences. The existing SYS$EXAMPLES and related code 
examples have (or had) source build issues, too.

Examples of gaps here include networking (IP, DNS, TLS, etc) and the 
network security APIs, and pretty much all of ACME—ACME is a massively 
flexible design, but also sometimes subtle and difficult to correctly 
use for common operations. There are others. All of this really needs 
to be better abstracted, and incorporated into the platform.

Descriptors were a nice idea in 1978 too, but expectations have 
changed. C and C++ could have used better abstractions for dealing with 
descriptors too, but C and C++ extensions for descriptors seems rather 
less than worthwhile in 2025. And the typical replacement of adding 
message-passing enhancements is a far investment in the run-time and in 
the compilers generally, and well beyond the existing and required 
compiler work that is already critical path development work for VSI.

> Compare that to the unix approach. Originally just a set of runoff 
> pages, very much on your own, but the methodology, ways and means of 
> accessing information, have changed. For example, plugin fopen() to a 
> search engine and you get dozens of the basic man page descriptions,
> but also a range of pages with code snippets illustrating usage. Much 
> faster way to get productive. Solve the problem, not get bogged down 
> trying to find the information...

With apps such as Dash, too. https://kapeli.com/dash

Getting system services and other OpenVMS reference materials into 
formats available for inclusion into these or similar tools is another 
project.

The built-in documentation tags increasingly available in various 
tooling is making source code easier to document, as well. This isn't a 
new idea, what with Doxygen, and as OpenVMS itself generates some 
documentation from source code.  (For generating error messages and 
recovery documentation, see GNM on the OpenVMS freeware.)

But for now and for the next year or three, VSI is occupied getting 
OpenVMS x86-64 stable and working and shipping. Which can and is and 
should be the priority.




-- 
Pure Personal Opinion | HoffmanLabs LLC