                           podlators To-Do List

This is a somewhat random and unordered list of things I'd like to see
fixed or improved, but which I've not yet had a chance to do.  Patches for
any of the following are very much welcome.

 * The latest version of GNU groff supports both ISO 8859-1 and UTF-8
   characters, but Pod::Man can't deal with them.  It should be possible
   to pass through UTF-8 to the output and let the *roff formatter deal
   with it, including mapping all E<> escapes to the appropriate code
   points.  It would also be good to support ISO 8859-1 in the same way
   because it's widely used.  This probably requires an argument to the
   module specifying the output character set.  Then, the current
   fallbacks should only be used when the output character set is pure
   ASCII.

 * The current handling of high-bit characters by Pod::Man is wrong.  E<>
   escapes should be mapped to the appropriate UTF-8 code point, and then
   a single transformation should be done on each paragraph right before
   output, converting all of the UTF-8 code points to something else if
   the output character set is not UTF-8.  This should probably use
   Pod::Escapes to provide fallbacks.  This would also allow correct
   output of high-bit characters found in verbatim paragraphs.

 * Pod::Man doesn't support the full HTML entity list, which would be
   easier to do once the above two points have been addressed.

 * perlpodspec says that it should be possible to suppress the output of
   errors and instead attach them as a closing section of the document.
   There haven't been any specific requests for this functionality yet,
   but it shouldn't be too hard to add to Pod::Man and Pod::Text.

 * There should be some way to turn off all heuristics when people are
   using POD for some purpose other than Perl or some other programming
   language with similar needs.  The best way to do this would be via a
   new Pod::Guesswork module that acts on parse trees before they're
   expanded, adding additional interior sequences as appropriate.

 * The test suite is still fairly basic, and doesn't test all of the
   options to the various modules, the scripts, =for, =over/=back, or the
   guesswork in Pod::Man.

The following items require changes to the POD specification and are
therefore of broader scope than just this code:

 * Introduce a new interior sequence for metasyntactic variables, probably
   M<>, and reserve I<> exclusively for emphasis.  This resolves a
   significant ambiguity in the current POD specification in a way that
   would make the Pod::Text output much better.  (Metasyntactic variables
   should be surrounded in angle brackets and emphasized text should be
   surrounded by asterisks.)

 * Introduce a new interior sequence for footnotes.  There has been
   extensive discussion of this on pod-people@perl.org.  One proposal is
   to use a new formatting code for footnotes, probably N<>, and just
   in-line the footnote as part of the interior sequence.  This doesn't
   allow multi-paragraph footnotes, however, so a second proposal is to
   have the content of the N<> formatting code be a unique marker that
   matches an =item tag in a new =begin footnotes section processed by
   translators that know how to do footnotes.  (The translator should
   probably number the footnotes and insert some sort of numerical marker
   into the text at the point of the footnote.)  This would require
   translators to formatting languages that do something more interesting
   with footnotes to parse the entire document, extract the footnote
   section, and then stick the footnotes back into the main text at the
   point where they occur, however.

   There are some preliminary patches for Pod::Man and Pod::Text in NOTES.
   It's possible to do footnotes directly in *roff (it's section T4 of the
   troff paper), but that relies on header and footer triggers and for
   terminal display it's becoming common to suppress the headers and
   footers.  For the purposes of Pod::Man, end notes are probably a better
   model and can be handled about the same way as they are for Pod::Text.

The following ideas about guesswork and heuristics were all taken from a
post by Tom Christiansen to pod-people@perl.org:

 * All of the following should be okay to use verbatim in any POD text and
   have the translator do something appropriate:

   FILEHANDLE PackageName
   $variable @variable %variable &function
   $var::iable @vari::able %variab::le &functio::n
   function() fun::ction() fun::ct::ion()
   manpage(3r)
   user@host.com
   http://somewhere.com/stuff/ ftp://somewhere.com/stuff/

   Pod::Man and Pod::Text handle much of this already, but not all of it
   (and I've not checked to see exactly where they break).

 * Something in __ALLCAPS__ should be in code font but perhaps not small,
   and maybe some magic between the unders, as in \f(CW_\|_ALLCAPS_\|_\fP.
   (Pod::Man handles the spaces between the underbars, but not putting
   this into code font.)

 * The module version number should be included in the headers/footers
   where appropriate.  That means that when processing a module, ideally
   one wants to pull out the module's $VERSION to use in the footer rather
   than Perl's version.
