[Date Prev][Date Next][Thread Prev][Thread Next]
- Subject: Re: Lua at ONLamp - POD for documenting Lua modules
- From: David Manura <dm.lua@...>
- Date: Fri, 20 Jul 2007 03:08:05 +0000 (UTC)
Adriano Ferreira <a.r.ferreira <at> gmail.com> writes:
> 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
That seems so. There is now a POD6 version of the "luafunc" Lua standard
libraries basic functions doc on LuaSearch ( http://lua-users.org/wiki/LuaSearch
). The number of changes required from the POD version was fairly small, and
they were generally good:
(1) Lists definitions and some other things no longer require extra blank lines
=item basic library;
=item package library;
=item string manipulation;
Term list items do seem a bit verbose:
=for item :term<C<"stop">>
stops the garbage collector.
but you could just use regular list items if desired:
=item C<"stop"> - stops the garbage collector.
(2) Links are more sane. A term is defined with D<...>
Allows a program to traverse all fields of a table...
and referenced with a L<...> with a defn scheme:
See L<defn:next> for the caveats of modifying the table
during its traversal.
(3) POD6 allows some formatting (e.g. boldface) to be enabled inside a verbatim
(4) Errors display as line numbers rather than paragraph numbers (however, this
is more a comment of the perldoc2xhtml tool than the POD language itself).
The need now is a POD6 parser in Lua and a better HTML converter. I see the
Perl POD6 parser is a reasonable ~2000 lines. (There currently seems to be a
dearth of POD6 examples outside the Perl6-Perldoc distribution though; I only
found one in Pugs.)
> Not really a strict language specification, but perlpodspec
> (http://perldoc.perl.org/perlpodspec.html) gets close to it.
Yes, POD syntax is fairly explicit. There are even external tools to perform
various types of validation on POD such as
http://search.cpan.org/dist/Pod-Coverage/ . My criticism was mainly about
Natural Docs syntax, which is largely defined in an DWIM implementation, making
it difficult, for example, to reliably reimplement a Natural Docs parser in Lua
or automatically translate some other syntax to Natural Docs syntax.
Frans Slothouber <frans.slothouber <at> gmail.com> writes:
> You might want to have a look at ROBODoc
It has the language independence and is rudimentary (maybe too much so), though
I haven't used it in practice.