[Info-vax] callable BACKUP example

[Arne Vajhøj]

On 7/10/2021 2:26 PM, Stephen Hoffman wrote:
> This OpenVMS doc is poor, and this source code example is weak, and the 
> whole concept that folks won't be incorporating source code examples 
> into production code is just, well, wrong.
> 
> This source code incorporation happens ~everywhere. I'd expect there are 
> OpenVMS source code examples that have found their way back into OpenVMS 
> itself. And elsewhere.

Yep.

> Example source code needs to be complete and correct and with functional 
> error handling, needs to build correctly, and with a copyright amenable 
> to its incorporation into customer apps.

I don't think it is that simple.

A complete example makes it easy to copy paste and show some of the
extra stuff that need to be done in final code.

But a complete example also tend to be much bigger and taking
much more time to read than a snippet that only show the the
specific stuff the example need to illustrate.

So there are pros and cons of both. The copy paste people
prefer the complete example, but the read and understand
people probably prefer the short example.

And there are in between: code that is compilable but are still
not complete.

I am really fine with all flavors.

As long as it is clearly indicated what it is.

It is really bad to present example code as complete if it is
not complete.

And it is really bad to provide example code that does not work
without clearly explaining that it is really pseudo code.

But as long as the "label" match the "content" then it is up
to the reader to read.

Arne