Russ,
all of your TODOs seem to be more than sensible to me. Concerning pulling
up code to Pod::Parser or some other more general place is sensible, on
the other hand it may come with a performance penalty that may be crucial
as you once said. You may want to have a look at Pod::Compiler (available
on CPAN); it is an additional layer around Pod::Parser that does a number
of things you mention below. It may however not be fast enough for online
execution e.g. by "perldoc".
See also some comments below.
All the best,
Marek
On 9 Feb 2001, Russ Allbery wrote:
RA>This is the TODO file for podlators, collected from various discussions in
RA>pod-people over the past year or so along with various other things I've
RA>encountered. I have a very limited amount of time to work on POD-related
RA>issues right now, but I'm quite happy to continue to serve as coordinator
RA>of changes to the podlators package and the Pod::Man and Pod::Text modules
RA>in Perl core. Patches for the stuff listed below are welcome and I'll try
RA>to integrate them, although it may take me a month or two to get to
RA>things.
RA>
RA>This is a somewhat random and unordered list of things I'd like to see
RA>fixed or improved, but which I've not yet had a chance to do. Patches for
RA>any of the following are very much welcome.
RA>
RA> * Do something about the other high-bit characters that aren't supported
RA> currently by Pod::Man. Do some versions of groff support Unicode?
RA> We'd definitely need help from the *roff implementation here for a
RA> general solution.
RA>
RA> * Do something about high-bit characters directly in the text (including
RA> verbatim paragraphs) in Pod::Man. Many versions of *roff choke on them
RA> badly unless we do the same sort of processing that we would if they
RA> were E<> escapes.
This could be added easily in Pod::Compiler: The strings would be strictly
ASCII (no high bit set), the rest would be turned into the corresponding
E<>.
RA> * Add a heuristic so that if you have "C<text>" or C<"text">, C<> doesn't
RA> add additional quotes in nroff mode.
RA>
RA> * Make use of a more generic parsing layer above the translators that
RA> handles such things as command dispatch and tracking the nesting level
RA> of lists to cut down on the amount of code one has to repeat between
RA> translators. The best line of division between a translator and a
RA> generic parsing layer is unclear.
Done in Pod::Compiler.
RA> * There should be some way to turn off all heuristics when people are
RA> using POD for some purpose other than Perl or some other programming
RA> language with similar needs.
RA>
RA> * Pod::Man is still blessing already-formatted strings to work around an
RA> old limitation in Pod::Parser. We should be able to drop the bless and
RA> just use references to indicate an already-formatted string, but
RA> someone needs to track down what version of Pod::Parser in which that
RA> limitation was actually finally removed (there were several
RA> unsuccessful attempts at it) and require that version as a prereq
RA> before that can be done.
RA>
RA>The following items require changes to the POD specification and are
RA>therefore of broader scope than just this code:
RA>
RA> * Introduce a new interior sequence for metasyntactic variables, probably
RA> M<>, and reserve I<> exclusively for emphasis. This resolves a
RA> significant ambiguity in the current POD specification in a way that
RA> would make the Pod::Text output much better. (Metasyntactic variables
RA> should be surrounded in angle brackets and emphasized text should be
RA> surrounded by asterisks.)
Good idea!
RA> * Introduce a new interior sequence for footnotes. (Tom Christiansen is
RA> currently using [FOOTNOTE: ...], but I think an interior sequence would
RA> be better; F<> is already taken, though.) This is lower priority,
RA> since it's unclear how to do a footnote in text or *roff output anyway,
RA> but it's useful in other contexts.
What about N<> for foot_N_ote? Another extension of POD I would personally
like to see are tables:
=begin table blah blah (headline)
<TAB>column2head<TAB>column3head
row2head<TAB>cell22<TAB>cell23
row3head<TAB>cell32<TAB>cell33
=end table
The formatters would scan the =begin table/=end block for rows/columns
and output a nicely formatted table. Suggestion: Nested tables are
forbidden, only plain strings (with whitespace) allowed in cells.
RA> * Ideally, all of guesswork() in Pod::Man should be pulled up a level
RA> into a parsing layer that converts such things into E<> escapes (for
RA> stuff like long dashes) or interior sequences (for things like small
RA> caps). It's unclear the best way to do this; some of the
RA> transformations are very specific to a translator.
Good idea for Pod::Compiler.
RA> * Add a =verbatim command that outputs text exactly as it appears without
RA> any indentation or other changes. (This is mostly useful inside a
RA> =begin/=end pair but may be useful elsewhere.)
I don't understand this completely: =verbatim for having non-indented
verbatim paragraphs is fine (could also be implemented with =begin
verbatim ... =end), but what does that have to do with =begin/=end?
I always thought (maybe this is wrong) that =begin sth/=end contains
sth that is specific to the formatter, e.g. ...
=begin html
<IMG SRC="lala.jpg">
<TABLE>
...
</TABLE>
=end
... but NOT POD code! See also perlpod:
=for
=begin
=end
For, begin, and end let you include sections that are
not interpreted as pod text, but passed directly to
particular formatters.
RA> * Lots of people seem to think that translating POD into a canonical XML
RA> form and then generating output from that instead of directly from POD
RA> is a good idea. Pod::Man and Pod::Text should actually be able to do
RA> that without too many major changes, since they already don't process
RA> POD directly but instead deal with the objects returned by Pod::Parser.
RA> No one seems to be actually working on this, though, and the concrete
RA> efforts that have been made in this direction have been met by almost
RA> complete silence.
See Pod::Compiler: It is a very simple exercise to dump the object tree in
a XML representation.
RA>The following ideas about guesswork and heuristics were all taken from a
RA>post by Tom Christiansen to [EMAIL PROTECTED]:
RA>
RA> * All of the following should be okay to use verbatim in any POD text and
RA> have the translator do something appropriate:
RA>
RA> FILEHANDLE PackageName
RA> $variable @variable %variable &function
RA> $var::iable @vari::able %variab::le &functio::n
RA> function() fun::ction() fun::ct::ion()
RA> manpage(3r)
RA> [EMAIL PROTECTED]
RA> http://somewhere.com/stuff/ ftp://somewhere.com/stuff/
RA>
RA> Pod::Man and Pod::Text handle much of this already, but not all of it
RA> (and I've not checked to see exactly where they break).
I see a lot of problems here. Of course it is nice to have some automatic
highlighting, in terms of typesetting e.g. $variable in a fixed-width
typewriter font. But what shall a formatter like pod2html do with
[EMAIL PROTECTED]? Should it really create a mailto:[EMAIL PROTECTED]
hyperlink? Is this sensible? IMHO it is up to the POD author to tag valid
hyperlinks (to URLs and manpages especially) by putting them in L<>,
rather than having a POD formatter hyperlink everything that just looks
like a link, resulting in a lot of misleading links. My suggestion
is: Pod::Compiler could be given an option to detect and tag strings of
the above form (optionally), and it is up to the formatter how this is
expressed in typography. But I am strongly against auto-hyperlinking
non-marked-up text. Or at least the formatter has to check whether the
link resolves, which holds e.g. for $| when the Perl manuals are converted
(including perlvar which contains the definition of $|).
RA> * A better way to deal with the many L<> things in the SEE ALSO would be
RA> good.
RA>
RA> * Something ALLCAPS should be in small caps. I [Tom] usually use
RA> \s-1ALLCAPS\s0 but \s-2ALLCAPS\s0 might be better. (Pod::Man already
RA> does this.)
RA>
RA> * Something in __ALLCAPS__ should be in code font but perhaps not small,
RA> and maybe some magic between the unders, as in \f(CW_\|_ALLCAPS_\|_\fP.
RA> (I don't believe Pod::Man currently handles this correctly.)
RA>
RA> * An area for further work is headers and footers. You should include
RA> the module version number and the file's last modification date in
RA> headers/footers where appropriate. That means that when processing a
RA> module, ideally one wants to pull out the module's $VERSION to use in
RA> the footer rather than Perl's version.
