[erlang-questions] Learning from the Manual

[Richard A. O'Keefe]

On 20/09/16 6:34 PM, Peter J Etheridge wrote:
> Dear List,
> I assume the Manual is clear to those who understand it.

I've been reading programming language manuals since oh, 1974.
The first thing to say is that there are traditionally three
quite separate books:

  - Language Reference Manual
    (Overview, lexical structure, syntax, pragmatics, core library).
    For a rather bloated example of this, see the Java definition.
  - User's Guide
    How to use the compiler, linker, debugger; how to interface
    to data bases, other languages, networks.
  - Books for beginners, generally written by 3rd parties.

and there will also be

  - Documentation for major libraries.

And by the way, it really really helps if these things are available
on paper or in PDF form so that you don't have to go clickety clickety
OH MY CARPAL TUNNEL to get from one paragraph to the next.  Especially
with PDF or single-page HTML it is really nice to search for things
that the authors didn't think to index or link.

I did not say ONLY available in such forms.  If you look at the
Learn You Some Erlang for Great Good! web site you'll notice additional
material (like the stuff about maps and time measurement) in the on-line
version.  LYSE not being the Nugganite scriptures (from Pratchett's
"Monstrous Regiment"), new material doesn't magically turn up in paper
copies.

Any rate, the *point* is that from that long experience of reading
language reference manuals, I expect that *I* will be able to learn
a language from its reference manual, but that most others will find
it hard.  *Learning* Erlang is best done from the Erlang books listed
on the documentation page.

The rôle of the reference manual is to let you look up the details.
This is why it is so important to have it as a single file you can
search.  And it is important that all the details should be there.
(For example, I am not happy that the Erlang Reference Manual does
not include a formal grammar.)

In the case of programming languages, ANSI used to have a practice
of supplying separate "Standard" (WHAT) and "Rationale" (WHY)
material.  The C89 rationale is still worth reading.  ISO defenestrated
that.

All in all, I don't think the documentation is in *terrible* shape.
I've seen worse.

Hmm.  I have to get the next draft of a paper ready.  I was supposed
to get it done last week (sigh).  When I've done that, I might try my
hand at writing a chapter of an Erlang Reference Manual (NRSV) and
put it up for comments.