[Info-vax] callable BACKUP example

[Arne Vajhøj]

On 7/8/2021 8:48 PM, Dave Froble wrote:
> On 7/8/2021 7:11 PM, Chris Townley wrote:
>> On 08/07/2021 23:53, Arne Vajhøj wrote:
>>> On 7/8/2021 5:42 PM, Chris Townley wrote:
>>>> On 08/07/2021 18:49, Arne Vajhøj wrote:
>>>>> On 7/8/2021 12:22 PM, VAXman- at SendSpamHere.ORG wrote:
>>>>>> Does anybody have the callable BACKUP example in compilable format?
>>>>>>
>>>>>> Trying to select and copy it from the PDF manual gives me garbage.
>>>>>>
>>>>>> FWIW, that's the ugliest bit of VMS documentation I have read in a
>>>>>> very long while.
>>>>>
>>>>> I rewrote the example in the manual and ended up with:
>>>
>>>>> BACKUP/LIST look OK on the result.
>>>>>
>>>> Always beware of copying/pasting from Word or PDF - it usually does
>>>> strange things - especially with quotes!
>>>
>>> It was more than copy/paste problems.
>>>
>>> The example in the manual declared a function:
>>>
>>> unsigned int subtest(void *);
>>>
>>> without using it.
>>>
>>> It did:
>>>
>>> static char input_str[] = "[.wrk]";
>>> ...
>>> input_dsc.dsc$w_length = sizeof(input_str);
>>>
>>> which I believe must be off by 1.
>>>
>>> It did not declare return type of main and it made all variables
>>> global instead of local in main, which is valid C but not very
>>> good C.
>>
>> Ouch!
> 
> "Cut-n-Paste" usually means the user didn't bother to understand the 
> example/source.  That isn't a good idea at any time.  The doc examples 
> are to help one understand, not to be blindly copied.


It is fair enough and in some cases even beneficial to just show
code snippets instead of complete code.

And it is obviously the copy pasters mistake if he copy paste code
that does something else than what he need.

But whatever is chosen to be shown should be OK code for a
purpose.

If they had not shown the descriptor initialization then it would
have been OK. The example intend to show BACKUP$ routines not
use of descriptors in C.

But they chose to show the code. And then the code should be correct.

Arne