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

[Paul Merrell <marbux@...>]

On Fri, Oct 25, 2013 at 2:22 AM, Justin Cormack
<justin@specialbusservice.com> wrote:

> 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.

I agree that benevolent dictators would be needed. But I'll note that
we haven't so far needed all that much moderation on the wiki.

> 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.

Those of that frame of mind would still have the unadorned manual
itself. But looking at the cases of those new to Lua and novices, the
manual itself just isn't that user-friendly. It's great as a reference
for those who are familiar with Lua but it's a dead end for those who
need more detail on some aspect.

An annotated version of the Manual with, for example, well placed
links to a wiki tutorial and relevant FAQ items could make Lua more
inviting for those getting acquainted with the language.

I have in mind mostly one liners with links to the related
information, not a book-length elaboration of the Manual.

Best regards,

Paul

-- 
[Notice not included in the above original message:  The U.S. National
Security Agency neither confirms nor denies that it intercepted this
message.]