[Quoting Autrijus Tang, on March 28 2003, 16:14, in "Re: Module submissio"]
> Well in fact, sure:
>
> =for docbook
> <method name="clone" type="instance">
> <parameters>
> </parameters>
> </method>
Technically, this is true. But is this POD? Would you call this C:
int foo(int bar) {
_asm("...");
_asm("...");
_asm("...");
_asm("...");
}
The =begin, =end and =for directives as recognized by POD parsers[1]
are designed to add specific extensions to POD. However, when you only
use the extensions then POD reduces to the bare mechanism to embed
non-perl information in perl programs.
The 'danger zone' for Mark's idea is to use POD-like stuctures, which
may people trick into thinking they're dealing with POD while in fact
they're not. If running OODF through a POD processor produces anything
useful, people will think it _is_ POD.
Mark writes (http://www.xray.mpe.mpg.de/mailing-lists/modules/2003-03/msg00503.html):
> POD is a visual markup language, and therefore information is lost
> about what is being documented.
Along the same lines, the embedded directives like B<>, I<> are wrong
(or at least dangerous) and should be replaced with more descriptive
directives.
So, I think the bottom line is: either use 100% POD, or make a small
POD-compliant extension to POD, or do not try to POD at all.
If I were Mark, I would leave POD completely and go for something new.
=begin oudf
@FILE Java Call In Implementation |
This file contains functions of Configuration Manager BeanInfo.
@IN_MODULE FF
@LOCAL
Function Description
----------------------------------------------------------------------
@FUNC |
@COPYRIGHT
ACME Corporation <cp> 1998
@OWNER
URB
@HISTORY
Seq Date RefNum Version Who Description
------------------------------------------------------------------------
@PR 0 | 981001 | e03371 | 7.2.04 | wwo | Initial version taken from the prototype
@COMMENTS
Sync with '$Id: ConfigManagerBeanBeanInfo.java,v 1.7 1998-12-02 15:31:01+01 jv Exp
$'
(TAB = 8, INDENT SIZE = 2)
@XREF
=cut
Why not?
-- Johan
[1] I want to emphasize "as recognized by POD parsers", since perl
itself does nothing with any directive.
