At 03:53 PM 10/2/00 +0200, Bart Lateur wrote:
>On Mon, 2 Oct 2000 08:29:09 -0500, Jonathan Scott Duff wrote:
>
> >But, why not suggest SDF instead of XML? SDF addresses most of POD's
> >deficiencies whill still retaining readability. (I don't have a URL
> >for SDF handy, but I'm sure a quick search on google.com would turn it
> >up)
>
> http://www.mincom.com/mtr/sdf/
>
>
>It is based upon POD, which might help in lowering the entry threshold.
Agreed. Let's not throw out the baby with the bathwater on this RFC;
there's much to commend a proposal that allows enhanced documentation
formatting within a script. I know that for 90% of the stuff we write,
it's so short that simply-formatted comments and POD will do, but there's a
whole world of software that uses things like cascading requirements
documents, design and delivery reviews, white papers, etc, i.e., "large
systems," of the type that are seldom written in Perl but which in
principle could be.
As long as we're designing something to stand the test of time for maybe
five years or more, we can think a little bigger than usual. I don't use
an IDE - unless you count Emacs - but the one feature that I've been
panting for in my editor for a good 15 years that might induce me to do so
would be the ability to independently collapse comment blocks of arbitrary
size within my code to small labelled icons. Click on an icon, and it
expands into comments explaining the code at hand; click again, and it
collapses so you can see the code. Or it might pop up another window with
a technical paper explaining the algorithm. People have suggested Emacs
outline mode for this but it doesn't come close.
Oops, got a bit carried away by the fantasy there. Anyway, a sufficiently
extensible POD could allow the creation of such a thing. Granted, if your
tool is a text editor that doesn't understand such comments, you might not
like receiving one from someone unless they ran it through some kind of
converter, but that shouldn't preclude the ability to construct the technology.
How about just standardizing a syntax for embedding different languages and
ensuring that perl can find where the block ends, he asked with some
trepidation. Eg,
... perl ...
=pod language=SDF boundary=VERYLONGSTRINGYOUGETTHEIDEA
... SDF ...
VERYLONGSTRINGYOUGETTHEIDEA
... perl ...
Not that this should stop us from improving POD as well...
--
Peter Scott
Pacific Systems Design Technologies
