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

[zxq9]

On Monday 02 June 2014 09:49:17 Vlad Dumitrescu wrote:
> Hi,
> 
> On Mon, Jun 2, 2014 at 9:36 AM, Joe Armstrong <erlang@REDACTED> wrote:
> > On Mon, Jun 2, 2014 at 12:06 AM, Evgeny M <donpedrothird@REDACTED> wrote:
> >> The docs are not horrible, far from it, but having more examples would be
> >> really helpful.
> > 
> > I agree - two thoughts occur to me.
> > 
> > Firstly, some kind of "reduced" manual pages might be helpful.
> > Many modules export a heck of a lot of functions, of which possible half a
> > dozen are the most used and
> > most useful. It might be nice to document the "best of" some module.
> > Secondly the "best of" section should have a lot
> > of simple examples.
> 
> Another option would be to group functions in a module (in the docs)
> by area of usage. This is especially useful for a module like 'erlang'
> that covers many distinct areas of functionality.

My feeling is that there are really two issues to address in the docs, one of 
which isn't being done much service (and when it is, it seems incidental):
1- Erlang the language (quick and easy to understand, provided the reader has 
his functional bases covered)
2- Erlang the system

A lot of Erlang documentation focuses on the language and specific functions 
in libraries, very little time is spent being explicit about the fact that 
Erlang is a guest operating system. This is mentioned in a peripheral way, of 
course, but very rarely is layout out just how Erlang works as a system.

I could write a new language that targets the Erlang runtime, for example, and 
compiles to Erlang bytecode. Let's say its a clone of Clojure we'll call 
Clerlang. Porting a program between Clojure and Clerlang won't be difficult 
just because the Java libraries and OTP use different names for similar 
functions, it will be difficult because writing something that targets the JVM 
is just like writing anything else that targets a typical machine or VM, 
whereas writing something that targets the Erlang system must be re-figured to 
work in a way that plays to the system's advantages.

It would be, of course, possible to simply write phrase-for-phrase an 
idiomatic Clojure program in Clerlang, but this would not be idiomatic use of 
the Erlang system and would probably perform horribly. Consider, however, that 
an idiomatic Clerlang program would be nearly impossible to port to Clojure.

My point is that the system is what is important, not the details of the 
language per se, and this separates great Erlang code from mediocre Erlang 
code, and nearly any non-trivial Erlang code from code in almost any other 
language I can think of.

Docs need to treat the system, not just the language. And this is, from my 
perspective, what is mostly lacking.

-Craig

PS: I'm working on an expanded essay about this particular subject and have a 
mind to force myself into learning the system better by writing some tutorial 
paths. If anyone happens to think this is a good idea I'd love to work up some 
material, get it cut to pieces by the experts here, and eventually create an 
Erlang Tutorial path analogous to the (outstanding) Python Tutorial. It would 
be less ambitious than the (wonderful) LYSE book, more ambitious than the 
four-day class already available, and specifically focused on treating the 
system and only incidentally on treating the language.