[erlang-questions] How to return all records in dets

[Aaron J. Seigo]

On Sunday, June 1, 2014 13:18:30 lloyd@REDACTED wrote:
> Great gains would be come, in my view, by backing up man pages with
> authoritative noobie-friendly tutorials. By authoritative I mean dated,
> 100% functional, expressing best practices

as YAEN (yet another erlang newbie ;) this would be really quite valuable. i 
spent a fair amount of time looking at various sources of examples.

tl;dr -> there is actually a fair number of examples lurking out there, but 
nothing that is stand-alone, authoritative and well structured (as Lloyd 
describes it, anyways) and such a thing would be pretty fantastic.

a reasonably well-maintained git repo with examples would be simply fantastic 
for people learning the ropes, and making it easy to contribute to would 
simply be icing on the cake.


verbose -> i did find various sources for examples inc:

 *  http://www.erlang.org/examples -> a wiki is not the best medium imho (if 
only because you can't load them directly into the erlang vm from the command 
line; there is very little structure to the examples;  the documentation page 
warns they are out of date (scary! :)
 * http://erlangcentral.org/wiki/index.php?title=Category:CookBook -> fair 
number of interesting snippets, though not much structure
* Learn You Some Erlang (LYSE)

the true gold mine imho are the examples that come with LYSE. they were 
immensely helpful in getting me up and running in minimal time. of course, the  
examples make sense only when paired with the book itself. there is no 
indication in the examples archive as to which order the examples are to be 
read or what each example program demonstrates. the book itself provides that, 
of course, so this isn't a critical flaw by any means, it just means that these 
examples are not overly useful on their own.

(aside: a 2nd edition of LYSE that folds in the postscript on maps, has a bit 
more on binary comprehensions along with a general proof-reading sweep would 
be utterly fantastic. i wonder what would be required to make that happen?)

On Sunday, June 1, 2014 13:00:01 Garrett Smith wrote:
> As to moderation, if the docs were under a separate commit policy
> (separate repo?) members of the community could pitch in directly,
> saving the OTP time some hassle.

i actually did not even realize that the docs were in the OTP repo. *blush* i 
didn't see it mentioned on http://www.erlang.org/doc/ and had to dig for a bit 
before finding them in otp/system/doc/. having docs under system/ instead of a 
top-level directory is unusual and serves to hide them pretty well. ;)

things that occurred to me as "would be helpful..." while navigating through 
the sources:

* move docs to a top-level dir in the OTP repo to make them more discoverable

* document how to contribute to them on http://erlang.org/doc/ .. besiddes the 
whole github push request workflow, there are many non-self-evident details 
such as how book.xml is the top level file for each doc module

* with the OTP git repo cloned, one can not simply `cd system/doc; make` since 
the make depends on the top-level OTP build system. you have to configure (and 
autogen, if using a git checkout .. which is pretty much a requirement for 
push requests) and build from the top-level. `make docs` triggers a build of 
the actual OTP sources which is pretty irrelevant when i just want to 
contribute some improved docs and would like to see the results before doing a 
push request. :/ a pure-erlang system that uses a pre-existing erl in the 
user's path would be, comparatively, rather nice.

* it would be nice if the source tree reflect the generated HTML index a bit 
more clearly.  at http://www.erlang.org/doc/, navigating "System Documentation 
-> Erlang Reference Manual -> Introduction" gets one to the content found in 
reference_manual/introduction.xml. this is evident by looking at the URL on 
the website, but unclear by just looking at the source tree. another example: 
the system/doc/tutorial dir is not actually a generic tutorial but the 
tutorial on interoperability. (true story: i actually went into that dir 
looking for an erlang tutorial :)

* navigating the index on the left side of http://www.erlang.org/doc/ is 
pretty tedious (and lacks a search function). contributing improvements to 
that is fairly non-trivial due to the tooling for generating documentation. i 
found myself wishing that a clear, simple, "modern" template system was used 
for those parts ....

* the  erlang code in system/doc/top along the templates in 
system/doc/top/templates is (ironically? :) underdocumented; some 
documentation on what it does and how/where they are used would be helpful (if 
only to know that one can safely ignore it when wanting to contribute to the 
docs ;)

-- 
Aaron J. Seigo
-------------- next part --------------
A non-text attachment was scrubbed...
Name: signature.asc
Type: application/pgp-signature
Size: 198 bytes
Desc: This is a digitally signed message part.
URL: <http://erlang.org/pipermail/erlang-questions/attachments/20140602/b7f420cd/attachment.bin>