Re: What manuals should and should not say

[Nagaev Boris <bnagaev@...>]

On Sat, Feb 6, 2016 at 10:53 AM, Ross Berteig <Ross@cheshireeng.com> wrote:
> On 2/5/2016 10:58 PM, Paul Merrell wrote:
>>
>> ....
>> PIL is not a book for novices. They lack the vocabulary to understand
>> it or the manual.
>
>
> Novice programmers, no, not really. But novices in Lua, sure. The pair
> together are a complete course in the Lua language. The wiki, this list, and
> the Gems book provide a significant resource. The Lua tag at Stack Overflow
> is also well tended by experts, including one of Lua's authors.
>
>> As an example, take a look at this excerpt from the
>> v. 5.3 Reference Manual:
>>>>>
>>>>>
>> The following strings denote other tokens:
>>
>>       +     -     *     /     %     ^     #
>>       &     ~     |     <<    >>    //
>>       ==    ~=    <=    >=    <     >     =
>>       (     )     {     }     [     ]     ::
>>       ;     :     ,     .     ..    ...
>> <<<
>> That's the entire explanation of those tokens. I'm 3 or 4 years into
>> working with Lua and I still haven't the slightest glimmer what the
>> ellipsis is for. And unless I've missed it, that explanation is also
>> missing from PIL.
>
>
> That list is from section 3.1. See the rest of chapter three for a detailed
> breakdown that covers all of those tokens, most of which get somewhere
> between a sentence and a whole section in section 3.4. The ellipsis is
> defined in 3.4.11.

I don't know what "ellipsis" stands for. I can't find the word in the manual.

> This is a good example of a property that well written reference manuals
> have. They are terse. They don't repeat themselves. And the author of each
> sentence generally is free to assume that you already have read and
> understood every other sentence in the reference manual. In short, with very
> few exceptions a good reference manual is a horrible textbook.
>
> Similarly, PiL is not a reference manual, nor is it an introductory text in
> programming. Although it is among the best of its breed. Over the many years
> (I began learning C in '82 from the 1st edition of K&R) that I've been
> programming, I have seen some real doozies.
>
> --
> Ross Berteig                               Ross@CheshireEng.com
> Cheshire Engineering Corp.           http://www.CheshireEng.com/
>
>



-- 


Best regards,
Boris Nagaev