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

[Aaron J. Seigo]

On Monday, June 2, 2014 14:25:29 you wrote:
> Le 2 juin 2014 à 13:45, Aaron J. Seigo <aseigo@REDACTED> a écrit :
> > 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.
> 
> OTP is a reasonably well-maintained Git repository. It is now using GitHub’s
> pull requests, which makes it easy to contribute to, at least according to
> the persons who wanted OTP to depend on GitHub.

great, so there's a destination repo. :) there's some examples in there, even, 
in the various lib/*/examples/ dirs. some questions:

* where should (non-OTP lib using) Erlang examples go? (stdlib/examples?)

* should _every_ lib get an examples/ subdir? (i notice some don't, e.g. edoc)

* should there be a recommended/standardized manner of documenting the 
examples? e.g. what each example does? the order to look at the examples in, 
if any? i notice, for instance that the gs lib, has a relatively large # of 
examples and most of the files are numbered giving an implied order ..

* where would be a reasonable place to publish the extracted set of examples? 
(it probably doesn't make much sense to ask people to grab the entire OTP git 
repo and explore around in it to get them when a simple archive could be 
offered for download...)

> > * move docs to a top-level dir in the OTP repo to make them more
> > discoverable
> Great, let’s move things for the sake of moving things.

 not for the sake of the moving things: for the sake of making the docs more 
discoverable. perhaps i'm an idiot, but when i looked in the OTP repo the last 
place i thought to look was in system/. fortunately find(1) saved me ;)

> > * 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
> 
> http://www.erlang.org/doc/apps/erl_docgen/users_guide.html

is this linked anywhere in the index tree on the left side of 
http://www.erlang.org/doc/? (i couldn't find it ... and one place i did look 
before writing my email was under the Documentation entry .. maybe i just 
missed it). it would be very nice imho to find a link on the main page along 
with the "Some hints that may get you started faster"

i mentioned book.xml specifically, as it seems to be a convention, and i did 
not find a single mention of it in system/doc/. where are OTP documentation 
conventions documented?

and of course, the users_guide still misses things like how to contribute new 
docs to OTP itself ...

> > * 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.
> 
> True, `make docs` should work, but not going through autotools and whatnot
> is asking for problems. Rewriting things to only use Erlang is asking for
> problems too, why reinvent the wheel?

if the goal is to make contributing to documentation attractive and easy, 
asking potential contributors to set up and build the entire OTP repo build is 
a hurdle.

if i want to correct something in the documentation, or add a clarifying 
phrase / sentence / paragraph, should i really need to not only check out the 
OTP git repo but also build it?

> > * 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 ….
> 
> On http://www.erlang.org/doc.html, we can read: "Online documentation for
> the latest version of the run-time system as well as all the libraries.
> Searchable in the right column". If Erlang’s own documentation is not a
> good place to tell where the searchable documentation is, what is a good
> place?

http://www.erlang.org/doc/ 

that is where one often ends up, and there is no way to trigger the search 
there. the actual point i was attempting to make was that contributing 
improvements to http://www.erlang.org/doc/ as generated from otp/system/doc/ 
is not clear and easy. it should, indeed, be simple to provide a link to the 
already-provided search capabilities.

(that said ... should perhaps the "Erlang/OTP documentation" link on 
http://www.erlang.org/doc.html link to http://www.erlang.org/erldoc? rather 
than http://www.erlang.org/doc/?  apologies in advance if that's a 'newbie' 
question and there is an 'obvious' answer why it is the way it is ... :)

-- 
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/8e3e98eb/attachment.bin>