[erlang-questions] Learning from the Manual

[Fred Hebert]

On 09/21, Richard A. O'Keefe wrote:
>On 20/09/16 10:18 PM, Matthias Lang wrote:
>>   http://learnyousomeerlang.com/content
>>
>>I took a look at his "datatype" section to see how he dealt with the
>>"there aren't actually any strings" problem. And it turns out there is
>>no string section!  Perfect.
>
>The *paper* version has "strings" in the index, with
> - as binaries
> - a lists
> - to a number
>as subtopics.
>

Someone used the index! It's not anything special, but I'm glad to see 
there was something useful in there -- I tried my hand at the craft of 
indexing for the first time in the print copy of LYSE and dear lord 
there's a lot of stuff in there nobody suspects exists. The Chicago 
manual of style's pages on it were a revelation in terms of the 
unexpected complexity of things I usually just skip over.

In any case, Matthias Lang does have a point where even though I mention 
strings, it is mostly done in passing. There's a mention of regular 
expressions (318, 325, 329-330), but topics having to do with the string 
module, the binary module (which I'm not even sure existed back then?) 
and topics having to do with Unicode are not discussed at all.

Someone looking for common functionality such as title-casing text 
cannot find that information in LYSE (nor find out it isn't supported 
anywhere else than in community libraries [1]).

LYSE was started around OTP-R13B. As we're nearing OTP-20, and within a 
very different community landscape than back then, there's more and more 
stuff that I feel is either missing, or no longer as important to show 
in the book as it was back then.

I'd love to have time to work on a re-edition where stuff like releases 
could be made 50 pages shorter by using tools like relx, add material 
about the zen of erlang[2] and supervisor restarts[3], introduce maps 
within the normal text flow, get people more hands-on time with dialyzer 
and possibly property-based testing, make the FSM examples simpler, 
possibly using gen_statem instead of gen_fsm, and possibly replace stuff 
people use little of like distributed OTP releases and Mnesia to replace 
them with a crash course in using tools and libraries from rebar3 and 
the overall Erlang ecosystem for more common day-to-day tasks.  That's 
without mentioning stuff like explaining how to get a proper SSL/TLS 
configuration going (the defaults are *not* safe), time handling (which 
could very well remain an annex), and so on.

The website's also due for a facelift, fresher documentation links, and 
so on. I'd be interested to see what could be done with a more 
interactive version, where the website asks to contact a local Erlang 
server you run on your machine and lets you try snippets in JS (and 
therefore circumventing the need to sanitize Erlang on a server, which 
has proven hard and sometimes limitting before[4][5]).

So far there's not enough time. Plenty busy at work, open source 
projects currently in flight (particularly rebar3) are fairly time 
consuming, and No Starch hasn't been showing much initiative in pushing 
for a new edition, but even then I'd probably want to get started on my 
own so I can easily control the rights to a free online version.

There's also a bit of paralysis since I believe on of the reasons why 
LYSE went so well the first time around is that I was writing it as I 
was learning, and modifying it now would have me remove that perspective 
from it. The expert's eye is quite different from the newcomer's and 
manuals like Erlang in Anger[6] give a totally different experience. I'd 
like to maintain the current perspective in LYSE as much as possible, 
which could make it hard to accomplish some tasks such as say, move 
Dialyzer content earlier, or think of a new chapter flow that moves the 
user much closer to the action (although I can imagine using rebar3 and 
its shell to get the readers in a better place to explore on their own 
much earlier).

[1]: https://github.com/erlang-unicode
[2]: http://ferd.ca/the-zen-of-erlang.html
[3]: http://ferd.ca/it-s-about-the-guarantees.html
[4]: http://www.tryerlang.org/
[5]: http://erlangonxen.org/zerg is interesting though, but not quite 
sure how good isolation would be there
[6]: https://www.erlang-in-anger.com