Post by Simon Clubley Post by Stephen Hoffman
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
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.
²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