Re: How is the Lua manual made?

[Coroutines <coroutines@...>]

On Wed, Jun 25, 2014 at 5:10 PM, Paul Merrell <marbux@gmail.com> wrote:
> On Wed, Jun 25, 2014 at 4:30 PM, Coroutines <coroutines@gmail.com> wrote:

>> would make blocks of documentation go "unreferences" or taint them

unreferended* :(

>> until they've been approved to still be accurate
>>
>> ... along with tagging certain terms and phrases that may need special
>> attention in the future (like, "this function *accepts a sequence*")
>
> I'll resurrect here my idea of a version of the Manual that can be
> annotated by users with comments, links to example code, links to
> definitions, etc. My impetus for the suggestion was the need for a
> Manual that is more easily understandable by new and novice Lua
> scripters but I see no reason it could not also add gloss for advanced
> coders such as you suggest.

I'd love for most of the standard library functions to have docs
generated by ldoc, and maybe keep that pre-generated source on github
so the issue tracker could be used...  sounds like something PUC-Rio
wouldn't be in favor of, though.  A community-led effort could be done
independently but it'd be nice to have the blessing from upstream to
act as a secondary doc source (official link from the manual page?)

Most of the time when I go digging into the source it's because I'm
reading about a function that performs some behavior that sounds like
another function -- so I go digging to see if it calls that other
function or had duplicated code.  Sometimes I'm looking for bugs, like
functions that accept cstrings or Lua strings (which?)

I also get confused if I'm calling a function that must be called like
a Lua function (lua_call()), or if it can just be called directly from
C.    The source helps me with these...  For the most part the doc
answers very well :-)