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

[Arne Vajhøj]

On 3/12/2022 1:53 PM, Simon Clubley wrote:
> I don't know what Bill found to be confusing, but I can see some people
> being confused by all the VMS-specific stuff such as a way over-complex
> descriptor system,

The use of descriptors is hidden for those programming in enough high
level languages: Pascal, Fortran, Cobol, Basic etc.. It can hardly
get any simpler than that.

Those programming in and Macro-32 need to know that they are sending
over type, length and address. Not particular complex. If they can't
grasp that concept then I don't think they will get far on those
languages.

OK. There is an ugly side to descriptors - when one goes outside
simple fixed length or variable length strings, then it can become
tricky. But that is extremely rare and usually only happens
for some advanced language interop problems.

>                     as well as the fact the documentation needs to be
> written at a lower level than with the Unix documentation to deal with
> all the exposed structures that in Unix are hidden behind call interfaces,
> C structs, etc.

There is nothing low level in sending over complex structures instead
of simple data types. Almost all modern API's does that (it is just
called an object!).

> There's a strong argument for using a clean and simple descriptor setup
> instead of null terminated strings. Unfortunately, the VMS descriptor
> setup is neither clean or simple.

I can't see what can be omitted in descriptors for single strings.

> I can also only imagine what a newcomer to VMS would think if you have
> to get them up to speed on the combined 32-bit/64-bit program executables
> and how that compares to how cleaner what they are used to is.

Co-existance of 32 and 64 bit pointers can be a hassle.

But hopefully not that many newcomers to VMS will have to deal with that.

> There are also full searchable reference manuals for all the GNU components
> (and some other components) shipped as part of Linux.

It could be useful to supplement the tree structure of VMS help with a
search capability.

> I can also find full public documentation for Linux for the things I am
> not allowed to know about in VMS or cannot implement easily (such as how
> to add a new filesystem to VMS or how to write a new CLI).

There are way more documentation available for Linux than for VMS.

Because there are simply way more developers of Linux.

That is how the world is.

Arne