Re: file:read("*n") reference manual entry improvement

[Justin Cormack <justin@...>]

On Fri, Oct 25, 2013 at 10:17 AM, Paul Merrell <marbux@gmail.com> wrote:
> On Fri, Oct 25, 2013 at 1:28 AM, Roberto Ierusalimschy
> <roberto@inf.puc-rio.br> wrote:
>
>> Anyway, it seems we both agree the C documentation is quite convoluted
>> about this topic.  So, the question remains whether it is worth trying
>> to explain something similar in the Lua manual, versus leaving it open
>> to the user's imagination or own tests...
>
> I'll revive my suggestion from about a year ago that we aim to create
> a web version of the manual that can be user-annotated, for example,
> one numbered section per web page with the ability to add comments.
> That would allow us to deal with such issues, link to relevant pages
> on the wiki, add detail for those new to Lua, etc.

This can work, but you need it to be heavily curated to be useful, or
you may end up like the PHP manuals, which are full of incorrect and
unhelpful comments.

The issue here is that some users of Lua may not be familiar with the
darker corners of the C spec, or indeed they may have come to Lua to
flee form such things. I would think that trying to explain it in too
much detail is not that productive though in the end.

Justin