[Thanks to Tim Jenness for pointing me over here]
----- Forwarded message from Rob Napier <[EMAIL PROTECTED]> -----
From: Rob Napier <[EMAIL PROTECTED]>
Date: Tue, 6 Mar 2001 13:52:24 -0500
To: [EMAIL PROTECTED]
Subject: Re: yet more pod questioning
On Sun, Mar 04, 2001 at 11:31:25PM +0000, Michael Stevens wrote:
> On Sun, Mar 04, 2001 at 03:12:11PM -0800, Russ Allbery wrote:
> > Michael Stevens <[EMAIL PROTECTED]> writes:
> > [various questions about L<> and sections]
> > > I'm confused. What's all going on?
> > L<> is badly underspecified and is ambiguous in a lot of cases like this.
> > Ideally someone should start over from scratch and try to come up with an
> > unambiguous way of designating links and then patch perlpod as
> > appropriate. Implementing a consistent set of semantics shouldn't be too
> > hard; I just wasn't sure quite what I should be implementing.
>
> I'll ponder it.
>
> I presume we desire:
>
> a) simple
>
> b) unambiguous
>
> c) the minimal change from current practise and documentation.
>
> My goal here is the simple yet modest "the perl documentation should not
> emit warnings". I've cleaned up a lot, but a lot more make me think
> the whole issue is at the very least not well documented. The L<>
> tag and issues relating to it are by far the biggest problem I've found.
I've been spending a lot of time recently digging into pod since I've
adopted it as the format of choice for most of our documentation
(code-embedded and not). My group is now writing everything from
feature specs to HOWTOs in pod, which has been fairly successful.
The major complaint has been all the magic associated with pod
translators. Most of them make large assumptions about the nature of
the document; in particular, they assume that you're writing a man
page, and generally that you plan to write it immediately to disk.
When you are not, things start to break down. I have personally worked
around this by moving over to Pod::Tree which I have found to be much
less magical and which already includes a low-magic pod2html
translator. That said, I do have several requests for the language
itself and for things to be applied to the "core" pod translators
(assuming that Perl::Parser does in fact represent the future of pod).
Many of us desperately need ways to refer to non-pod pages such as via
a URI. While this has obvious application in html rendering, it also
can be handled by non-hyperlinked formats either via a "text (URI)"
style or via footnoting (which is how "lynx -dump" solves the
problem). I'd like to ask that a link target matching /^\w+:(?!:)/ be
accepted as a URI in the pod definition and rendered appropriately.
As far as unambiguous, one step towards this would be to formalize
rules like =head and =item tags are automatically X<>'ed. It would
also be nice to define whether these are tagged with or without
embedded tags (e.g. is '=head1 C<foo>' linked with L</foo> or
L</C<foo>>). Also whether links are case sensitive.
I recommend removing the auto-C<>ing of things with parenthesis as it
tends to be quite unorthongonal ("foo()" gets a C<>, but "foo( $bar )"
does not). If the author means C<>, let her say so. This is probably
more a pet peeve of mine due to the magic than something that actually
burns people.
If =head1 and =head2 are the only defined headings, then don't render
=head3+, since some parsers do and some parsers don't and then authors
don't know how to write. In my experience, below =head2, you probably
mean =over. Alternatively, put =head<n> directly into the language or
declare it up to 6.
=for/=begin needs to take a list of interpreters (probably | separated
so you won't break old stuff). Part of my goal here is really a
perversion of =begin, so maybe there's a better solution. I want to be
able to say things like '=begin DesignSpec' or '=begin ManPage'. So I
also want to be able to say '=begin DesignSpec|ManPage'. Maybe this
would be better served with =target/=endtarget or similar new tags,
since it's really a hint for a Pod::Select-type tool, not an
interpreter declaration.
Simlarly, I'd really like tools like Pod::Select to just take and
return trees rather than insisting on reading files (which the man
pages imply). Pod::Tree has worked well for this, but there is no
Pod::Tree::Select yet (though I'll probably wind up writing it soon).
Provide a =title command. This would get rid of the "second paragraph"
magic that everyone uses (though you could fall back to that if =title
is missing).
Translators should generally allow for templates and indexes. This is
particularly useful in html and other 'gui-ish' renderings (like
perldoc, docbook, sgml, etc). I have some sample code that shows some
fairly flexible ways to generate indexes and use templates if there's
an appropriate forum for that.
Separating the parsing from rendering really seems to help in making
almost everything better. Per-application magic should be easily added
by subclassing a small number of methods (probably just in the
translator, not in the parser) rather than being put into the core.
I have a strong interest in pod and translators, and have already
started contributing to Pod::Tree. Is there a better alias for
discussing the future of pod?
Thanks,
Rob
----- End forwarded message -----
