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

[Paige DePol <lual@...>]

Hello list,

I think the annotated manual is a good idea, if done properly.

Another idea I think could be immensely helpful would be annotations of the actual Lua source-code, for people like myself who would love to learn more about the internals of Lua.

I have been tinkering with the code and have produced some patches to tweak things a little and to gain some experience, however, I would have to say the code is probably fairly daunting to newcomers.

I say this due to the significant amount of very short variable names (single letter even), and while there are a lot of comments there is not a lot of detail of how the whole system works. I would think if we could annotate the source to help explain what all the data structures are and so forth it could be a great benefit to new Lua hackers.

Just my musings, oh and this is my first post, so hello everyone! :)

~pmd



On Oct 25, 2013, at 6:49 AM, Paul Merrell <marbux@gmail.com> wrote:

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