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.