[Info-vax] Suggested DCL enhancement

[Stephen Hoffman]

On 2020-11-03 18:34:35 +0000, Simon Clubley said:

> On 2020-11-03, Stephen Hoffman <seaohveh at hoffmanlabs.invalid> wrote:
>> 
>> How this mechanism might differentiate documented from undocumented  
>> qualifiers—yes, there are undocumented qualifiers—is fodder for another 
>> discussion or three.
> 
> If it's in the command definition, it's documented as far as my 
> suggestion is concerned and it would show up in the output if eligible 
> to be used at that point.
> 
> Since VERB became available, anything in a command definition should 
> now be considered to be public knowledge. Sticking something sensitive 
> in the command definition and hoping someone does not find it is not 
> exactly a viable long-term strategy.

VSI gets to decide this one.

Under the Ancien Régime, there was a difference between what was 
considered public, and what was considered documented¹ and supported.

What was considered supported was that listed in the SPD and in the 
documentation².

What wasn't, well, wasn't.

What was latent in the CLDs, or the comments in the help files², or in 
the various API definitions and behaviors³, was not considered an 
indication of support or stability.

There's a whole pile of stuff that's considered semi-stable (at best) 
included in the LIB definitions, too.


🦶🏼🎶

¹That the obsolete features manual is now itself considered obsolete is 
its own doc-ouroboros. And that the doc for the new features shipped 
with some of the V8.4 UPDATE kits was sometimes not incorporated adds 
to the mess. And one of the few examples of SYS$CLI API documentation 
is in some long-gone release notes. 
ftp://bitsavers.informatik.uni-stuttgart.de/www.computer.museum.uq.edu.au/pdf/AA-D015B-TE%20VAX-VMS%20Release%20Notes.pdf 


²Yes, OpenVMS help files do support comments. Those comments were and 
can be used as a means to disable viewing some some help text. Some 
experienced system managers became aware of certain undocumented and 
unsupported changes by exploring there. Extracting the entirety of the 
help libraries and then looking for any comments was common practice 
for some of us. DECnet proxies were "announced" this way.

³Hyrum's Law applies. https://xkcd.com/1172/ Various of the behaviors 
of even documented OpenVMS APIs are (were) considered undocumented, 
whether due to timing or undocumented extensions or bugs or hooks or 
otherwise. That undocumented assumption has backfired badly on 
occasion, such as at VAX/VMS V5.0 with asynchronous I/O completion, and 
the OpenVMS I/O change there was backed out.

-- 
Pure Personal Opinion | HoffmanLabs LLC