Re: Lua at ONLamp - POD for documenting Lua modules

["Adriano Ferreira" <a.r.ferreira@...>]

On 7/19/07, David Manura <dm.lua@math2.org> wrote:
> Adriano Ferreira <a.r.ferreira <at> gmail.com> writes:
> > I just mentioned Lua at a blog entry at O'Reilly ONLamp site:
> > http://www.oreillynet.com/onlamp/blog/2007/07/all_together_now_lua_pod_lpeg.html
>
> I saw LuaPOD recently too, which was something I was considering writing myself
> for rendering POD-based Lua module docs in http://lua-users.org/wiki/LuaSearch .
>  Unfortunately, the suggestion of standardizing Lua module docs in terms of POD
> hadn't since caught on much like it has with Perl.  Still, I believe Lua modules
> are really in need of some suitable documentation standard practice, possibly in
> conjunction with LuaRocks, so that documentation for multiple independent Lua
> modules can be combined and cross-referenced, such as for Lua distributions,
> i.e. letting *documentation be modular*.  This should be an obvious progression.
>  POD offers this.  Javadoc offers this.  UNIX manpages offer this.  HTML and the
> assortment of current Lua documentation practices do not offer it.
>
> I can't say I like all things about POD syntax.  Maybe the rules could be more
> obvious, the syntax for lists shorter, and the syntax more extensible.  Still,
> it works well in practice for 95%-99% of things.

Thanks for your reply and throrough discussion, David. You summarised
very important points on the issue of documenting Lua code (that I
would not be able to).

Maybe the current limitations of POD could be overcome by adopting the
newly created POD 6 (http://search.cpan.org/dist/Perl6-Perldoc/) which
is going to supersede POD in Perl 6 -- it approaches the points you
mentioned like shorter syntax for some constructions and
extensibility. I will give it a try and, if promising, will take
something to the appreciation of the list subscribers.

> It is also not (like Doxygen)
> dependent upon any particular language because the documentation is independent
> from the code structure.  I think that is very important for a dynamic scripting
> language, especially one that is metaprogrammed, in which static code structure
> tells you fairly little beyond the obvious.  Still, something compatible with
> the *runtime* docstring concept would also be advantageous.  I've looked at
> Natural Docs as a POD alternative; the syntax is natural and output great but
> (like Perl5) it's not defined according a strict language specification,

Not really a strict language specification, but perlpodspec
(http://perldoc.perl.org/perlpodspec.html) gets close to it.

> thereby
> limiting the use and development of third-party tools to process it in new ways.
>  Perhaps Lua documentation could be written in Lua.  Lua may be good for data
> definition, but it is not a markup language.  There's also the desire to avoid
> reinventing yet another documentation syntax and building a completely new
> toolchain to process it, but if it is needed then the ability to convert to a
> more common intermediate format (e.g. POD, Javadoc, DocBook, etc.) for
> subsequent processing (e.g. PDF/HTML/WinHelp rendering) is useful.

Regards,
Adriano Ferreira