A summary of the outstanding POD-related work is given below.
But first, some things to try.


Converting Perl's Core Documentation to Plain Text
==================================================

The command is:

  sdf -2txt <path_to_pod_files>/*.pod


Converting Perl's Documentation to HTML
=======================================

To generate the Perl documentation available at
http://www.mincom.com/mtr/perl/catalog.html, the
commands are:

  cd <perl_distribution_directory>
  cp $SDFHOME/perl/catalog.sdf .
  cp $SDFHOME/perl/oracamel.gif .
  mkpldocs all

If you wish, have a look at the perl/perl.sdm file in the
SDF distribution. By making changes in there, you can:

* change the logo in the top right hand corner
  by setting the DOC_LOGO variable

* change the background colour and image by setting the
  HTML_BG_COLOR and HTML_BG_IMAGE variables

* change the footer by editing the HTML_FOOTER macro

* add a header by defining the HTML_HEADER macro

* improve the hypertext generation rules by overriding
  the BuildLinkUrl() routine

* change the L<> phrase expansion rules by setting the
  FORMAT_LINK_* variables

The Perl camel is a trademark of O'Reilly and Associates, so
please mention that in a footer, say, if you use it.


How Does SDF Compare With pod2text/pod2html?
============================================

The HTML generated by SDF arguably looks a bit better
than that produced by pod2html, particularly when the
DOC_LOGO variable is set.

However, pod2html is better than sdf in the areas of:

* hypertext generation
  - pod2html builds a cache of Perl specific items and
    generates hypertext to them whenever it can

* enumerated list presentation
  - when 2 or more items share a common description,
    pod2html uses less whitespace

In Perl 5.004, pod2html has a problem with special characters in
headings (see perlfaq4) which SDF doesn't and pod2text has a
problem with wrapping verbatim paragraphs (see perldebug)
which SDF doesn't.  But those bugs might be fixed by now.

As a general summary, the pod2* programs are much quicker
than SDF, but SDF has more features. So, if you want to
use tables and figures, say, then SDF produces better output.
On the other hand, if you prefer the output from pod2html and/or
pod2text, you can still embed SDF tables and figures in
POD and then use SDF to generate vanilla POD, ready for pod2*.


Converting From POD to SDF and Back Again
=========================================

The command is:

  sdf -2pod <path_to_pod_files>/*.pod

This will create a set of .pod files in the current directory.


Comparing the Generated POD with the Original
=============================================

Firstly, you might want to exclude perltoc.pod from the
comparison by doing something like:

  mv perltoc.pod perltoc.pod.keep

The command is:

  poddiff *.pod <path_to_pod_files> > PODDIFFS

The poddiff program works by comparing files on a
paragraph by paragraph basis. Within a non-verbatim
paragraph, additional whitespace and unneeded E<>
escapes are ignored. The parameter to the over
command is also ignored.

See the PODDIFFS file in the SDF distribution for a
sample output. You may wish to examine that file and
the generated POD files (for 5.004) to confirm the following:

* the differences in perldata.pod and perltoot.pod are
  caused by (unnecessary?) Z<> sequences

* the difference in perlfaq4.pod is due to sdf automatically
  terminating an unterminated C<> phrase (as mentioned above)
  after producing a warning about it

* the differences in perlsubs.pod are due to one list ending
  and another one starting, when it seems unnecessary to
  do this.

As yet, I haven't analysed the differences in perltoc.pod,
but most of them seem to be related to list over/back
commands. In any case, the output from

  sdf -2html -cperl perltoc.pod

seems ok.


Known Bugs
==========

* The pod2sdf and POD::SDF.pm stuff hasn't been documented
  yet. I'll probably do the doco for these in vanilla POD,
  and offer for them to be included in the standard Perl
  distribution. Thoughts?

* The doco hasn't been updated to reflect the new macros,
  phrase styles, etc. In particular, the User Guide,
  Reference and White Paper need to be updated.

* The X phrase style doesn't work yet for any output
  format except POD (and those generated by going via POD).
  If you need a workaround, indexing can be done using the
  index phrase attribute.

* sdf -2latex_pod xxx generates an xxx.out.tex file, rather
  than an xxx.tex file.

* The implementation of BuildLinkUrl() in perl/perl.sdm
  (i.e. the perl configuration library) still needs
  some more intelligence.
  
* The -w option isn't currently passed through to pod2text.
  (I had trouble getting pod2text to accept it.)

* The toraw.pl driver needs to be updated to dump <> style phrases
  rather than {{}} style ones. When this is done, the expected
  output files in the test/*/checked directories will need to
  be updated.


Other Thoughts
==============

At the moment, the pod2* programs are substantially faster
than the sdf program.  The main performance issue with sdf
is the loading of its configuration files. So, a one line
document can take several seconds to convert, but a 100
line document doesn't take much longer. I'm planning to
address configuration file caching as part of the source
code migration to Perl 5.  Note that users can specify
things on the command line and/or top line of a file which
can affect the configuration loading process, so 
configuration caching is non trival.

Some of the nice features in pod2html (e.g. hypertext link
generation for Perl-specific items in general text)
aren't available and I'm not yet sure how to provide them.

A new -e option could be used to specify that SDF
is embedded in source code comments and the appropriate
leading character sequence should be stripped, if found.
That sequence could be derived from the file extension
or explicitly specified as a parameter to the -e option.
Alternatively, SDF could check the file extension and
assume the -e option if it looks like source code.
The intention here is to provide a simple version of
the functionality provided by Brad Appleton's POD::Parser
preprocess_line() routine.

The pod filter could take a select argument ala
Brad Appleton's POD::Parser stuff. In fact, implementing
the POD::SDF module using POD::Parser might be
a good idea. (This wasn't done because the pod2sdf
subroutine is currently pretty trivial.)

POD pretty printing could be added by updating
stdlib/langdefs.sdm. Each of the commands could
be added as a keyword, although I'm not sure
if we can highlight the interior sequences?

Tim MacKenzie's enhancements to the txt output driver
haven't been applied to the pod output driver yet.
When that is done, wrapping of text within table cells
should work.

The POD convention of starting documentation with a =head NAME
and putting the actual title as the next paragraph is a pain.
I wish POD documents started with a =title instead.
Perhaps pod2sdf could do this?

It would be good if pod2sdf had an option to produce
"traditional" SDF, i.e. with tagged lists, rather than
over/item/back lists.

The poddiff program isn't yet useful for comparing POD
generated by sdf -2pod with POD in a .pm file.
This could be changed by teaching Pod::Diff.pm to ignore
lines which have been cut.