Thomas Wittek wrote:
> I mean POD uses constructs like headlines, lists, blocks, italic etc.
> which all describe _how it looks like_ and not _what it is_.
I think Damian would take exception to that statement. He worked quite
hard to make sure that POD describes _meaning_ rather than _appearance_.
He even renamed B<> from "bold" to "basis", I<> from "italic" to
"important", and U<> from "underline" to "unusual". All of those are
fairly odd choices, with the possible exception of "important", but they
were clearly made with an eye to backwards compatibility of POD while
changing people's focus from how it looks to what it is.
> A head3 might be the headline of a method documentation as well as one
> introducing the contact information for the author of a module.
> The directive doesn't have much semantics.
> Other people might use head2 for documenting methods, what leads to a
> pretty inconsistent look of the documentation.
Well, I'd argue that head3 has plenty of semantics. It's a level-3
header. How that's rendered is decided elsewhere.
I think the issue is not that head3 is insufficiently semantic, it's
just that you want something that's even more specific. And POD 6 was
designed with exactly that kind of thing in mind. You can, according to
the existing S26, say things like:
=Method the method synopsis goes here....
=begin Parameters
=item foo is the fooiest parameter
=item bar is the barstest parameter
=end Parameters
Furthermore, the Perl parser actually *keeps* the POD chunks, so you can
access all that information in the context of the Perl parse. Damian and
Larry were clearly laying the groundwork for exactly the sort of
javadoc-ish features you are asking for.
=thom
-----
The supreme irony of life is that hardly anyone gets out of it alive.
--Robert A. Heinlein [Job: A Comedy of Justice]
