Re: Lua at ONLamp - POD for documenting Lua modules

[David Manura <dm.lua@...>]

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

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
nor "=over/=back":

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

  =head2 D<next>
  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
environment.

(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
>    http://www.xs4all.nl/~rfsber/Robo

It has the language independence and is rudimentary (maybe too much so), though
I haven't used it in practice.