On Mon, Nov 11, 2002 at 11:47:01PM +0100, Angel Faus wrote:
> Does anyone have any experience with SDF?
I played with it for some in-house documentation a couple years ago.
I'm afraid I wasn't very impressed with it; I found it very difficult
to customize the output to what I wanted, and the syntax is a bit
of a mess.
One of POD's good features is that there is very little syntax to
learn. ("=foo" begins a paragraph; paragraphs end with a blank
line; X<foo> is an interior sequence.) This has resulted in some
ugliness--in particular, lists are terrible, since a simple
three-element list:
- one
- two
- three
must be written as:
=over
=item *
one
=item *
two
=item *
three
=back
16 lines of POD!
POD parsers also go to a fair amount of trouble to infer syntax. For
example, a function name like this() will be rendered differently by
many POD processors. This is a good thing, in that you don't have to
litter your documentation with a lot of C<> directives. This is a bad
thing, in that there aren't any formal rules on what patterns parsers
will match, so you're never quite certain what your document will end
up looking like.
I'd love to see a cleaner POD, with tables, better support for lists,
and the ability to turn syntax inferencing on a per-document basis.
Unfortunately, I don't think SDF is it.
I'd be happy to join in a discussion of how to make a better POD.
I don't think this is an appropriate topic for the perl6 documentation
list, however--consider Knuth, _The Art of Programming_, and TeX
as an example of what can happen if you decide to create the perfect
authoring system before starting to write. :>
- Damien
