Hi,
POD is Plain Old Document format, and I know about the ever lasting
debates about alternative formats. Well, it doesn't bother me too much
wether a text is written in POD, LaTeX, or XML. What does bother me
is that POD is visual markup instead of logical markup; the difference
between HTML's <I> and <EM>, <B> and <STRONG>
On this moment, I am owner of seven CPAN modules. The largest is
Mail::Box, which has about 90 packages, each describing one class:
it is object-oriented Perl.
Of course, many of the classes are related, for instance:
Mail::Box::Mbox::Message (a message in an mbox folder)
is a Mail::Box::File::Message (a message in a file-organized folder)
is a Mail::Box::Message (a message in any folder)
is a Mail::Message (any message, even outside a folder)
is a Mail::Reporter (the common base class)
If you write the documentation with POD (as I did first), it is
extremely complicated for any object user to find-out which methods and
which options to the methods are available for a specific object. In the
above example, having an mbox message means you have to scan through
5 manual pages before you know what you can do with it.
Copying descriptions from a lower level to each of its sub-classes is very
error prone (I've been there!) So that is certainly not a solution.
Conclusion: POD is not sufficient to produce documentation for OO programs.
So... I wrote a (2000 lines) program which takes all the 90 packages,
separates the code from the documentation, reorganizes (merge, sort, etc)
the documentation, and then creates POD. The produced POD is just like
standard POD. To be able to do that, I had to extend the pod syntax
with logical tags.
A fabricated extract of a package:
package Mail::Box::Mbox::Message;
use base 'Mail::Box::File::Message';
=head1 NAME
Mail::Box::Mbox::Message - one message in a Mbox folder
=head1 SYNOPSIS
my $folder = new Mail::Box::Mbox folder => $ENV{MAIL}, ...;
my $message = $folder->message(0);
=head1 DESCRIPTION
Maintain one message in an Mbox folder.
=head1 METHODS
=cut
#--------------
=c_method new OPTIONS
Messages in file-based folders use the following options for creation:
=option from_line STRING
=default from_line undef
The line which begins each message in the file. Some people detest
this line, but this is just how things were invented...
=examples
my $msg = Mail::Box::Mbox::Message->new;
=error Illegal from_line for mbox message
The line which separates messages in a folder should start with C<'From '>
and contain the year in four digits.
=cut
sub new() {...}
As you see here: method new is a class method (c_method). On this level of
inheritance, we add an option from_line, which extends the list on a lower
level. We have some examples, descriptions on error and warning messages
produced. This framework is easy to extend.
With currently 90 packages, 647 methods documented, and 128 diagnostics, the
whole collection of produced POD manual-pages is huge! man-pages get so large
that it is hard to grasp. Therefore, I have been trying to give access to the
data in a different way.
Have a look at http://perl.overmeer.net/mailbox/html/ what kind of HTML can
be produced from the same data. This is version 0.2 of the website
generation tool, so there are improvements to be made. Also look at the
generated class relations and the indexes (which need some improvements).
My questions:
1) Is this kind of logical markup useful for you as well? Do you already
help your pods with scripts?
2) If I extend my concept into a usable module, would the "community"
accept it as alternative to plain POD?
3) What name-space should my module take?
NPND not-so-plain new document format?
OODF object oriented document format
OOPOD
PODOO
POD::OO
POD::Logical
POD6
something else?
--
Thanks for reading,
MarkOv %-]
------------------------------------------------------------------------
drs Mark A.C.J. Overmeer MARKOV Solutions
[EMAIL PROTECTED] [EMAIL PROTECTED]
http://Mark.Overmeer.net http://solutions.overmeer.net
