Re: Google Summer of Code 2013

[steve donovan <steve.j.donovan@...>]

On Tue, Feb 26, 2013 at 12:41 PM, Peter Drahoš <drahosp@gmail.com> wrote:
> - Package names should reflect the modules installed by it

It would be rather cool if a person encountering 'lpeg' and 'lfs'
could just say 'install lpeg lfs'.  But as you say this needs some
cooperation in the form of metadata, which the package distributor
would probably end up inputting.

> - No documentation standard

Well, the best we can have is some HTML, really. There are advantages
to standard markup (e.g. luadoc) since then automatic tools can help.
For instance, ldoc can output help on the console using existing
luadoc markup in a file:[1]

$ ldoc -m pl.utils
----
module: pl.utils        Generally useful routines.
 See  @{01-introduction.md.Generally_useful_functions|the Guide}.
* quit(code, ...) - end this program gracefully.
* printf(fmt, ...) - print an arbitrary number of arguments using a format.
....

But the challenge is getting _any_ documentation.  The Go language
does not use any fancy formatting, its godoc tool merely requires that
functions and types have a comment preceding them.  And yet people
still can't get even this together. I think the authors believed that
their test suites were clearly a superior form of documentation, but
often they tested on such a micro level that the source was usually
the clearest form of information.

Testing is another exercise in individuality.  For luabuild I wanted
an integrated test suite for the modules, and it involved an effort to
package existing test suites so they would cooperate with this simple
need.  There's no way that can scale to a big distribution!

steve d.

[1] ldoc is bit heavyweight for such a simple task; perhaps I should
play with -M which would open the docs in a browser.