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

[chris]

On 03/14/22 17:37, Stephen Hoffman wrote:
> 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.
>
>

Thanks, more or less what I suspected. No longer a vms user, but would
like to see it succeed. Problem is that it's so far behind the
mainstream now, it will take a lot of effort to catch up. As I said,
porting cups or other mainstream printing system would fix the printing
issue for good, but even that would require effort from people
familiar with both unix and vms.

What might be just as important is the head in sand attitude of some,
as the song goes, you ain't gonna learn what you don't want to know. In
computing, I always expected to have to keep up with developments and
in fact, that's one of the main attractions of tech, lifelong learning
and always a student...

Chris






>
>