1A summary of the outstanding POD-related work is given below. 2But first, some things to try. 3 4 5Converting Perl's Core Documentation to Plain Text 6================================================== 7 8The command is: 9 10 sdf -2txt <path_to_pod_files>/*.pod 11 12 13Converting Perl's Documentation to HTML 14======================================= 15 16To generate the Perl documentation available at 17http://www.mincom.com/mtr/perl/catalog.html, the 18commands are: 19 20 cd <perl_distribution_directory> 21 cp $SDFHOME/perl/catalog.sdf . 22 cp $SDFHOME/perl/oracamel.gif . 23 mkpldocs all 24 25If you wish, have a look at the perl/perl.sdm file in the 26SDF distribution. By making changes in there, you can: 27 28* change the logo in the top right hand corner 29 by setting the DOC_LOGO variable 30 31* change the background colour and image by setting the 32 HTML_BG_COLOR and HTML_BG_IMAGE variables 33 34* change the footer by editing the HTML_FOOTER macro 35 36* add a header by defining the HTML_HEADER macro 37 38* improve the hypertext generation rules by overriding 39 the BuildLinkUrl() routine 40 41* change the L<> phrase expansion rules by setting the 42 FORMAT_LINK_* variables 43 44The Perl camel is a trademark of O'Reilly and Associates, so 45please mention that in a footer, say, if you use it. 46 47 48How Does SDF Compare With pod2text/pod2html? 49============================================ 50 51The HTML generated by SDF arguably looks a bit better 52than that produced by pod2html, particularly when the 53DOC_LOGO variable is set. 54 55However, pod2html is better than sdf in the areas of: 56 57* hypertext generation 58 - pod2html builds a cache of Perl specific items and 59 generates hypertext to them whenever it can 60 61* enumerated list presentation 62 - when 2 or more items share a common description, 63 pod2html uses less whitespace 64 65In Perl 5.004, pod2html has a problem with special characters in 66headings (see perlfaq4) which SDF doesn't and pod2text has a 67problem with wrapping verbatim paragraphs (see perldebug) 68which SDF doesn't. But those bugs might be fixed by now. 69 70As a general summary, the pod2* programs are much quicker 71than SDF, but SDF has more features. So, if you want to 72use tables and figures, say, then SDF produces better output. 73On the other hand, if you prefer the output from pod2html and/or 74pod2text, you can still embed SDF tables and figures in 75POD and then use SDF to generate vanilla POD, ready for pod2*. 76 77 78Converting From POD to SDF and Back Again 79========================================= 80 81The command is: 82 83 sdf -2pod <path_to_pod_files>/*.pod 84 85This will create a set of .pod files in the current directory. 86 87 88Comparing the Generated POD with the Original 89============================================= 90 91Firstly, you might want to exclude perltoc.pod from the 92comparison by doing something like: 93 94 mv perltoc.pod perltoc.pod.keep 95 96The command is: 97 98 poddiff *.pod <path_to_pod_files> > PODDIFFS 99 100The poddiff program works by comparing files on a 101paragraph by paragraph basis. Within a non-verbatim 102paragraph, additional whitespace and unneeded E<> 103escapes are ignored. The parameter to the over 104command is also ignored. 105 106See the PODDIFFS file in the SDF distribution for a 107sample output. You may wish to examine that file and 108the generated POD files (for 5.004) to confirm the following: 109 110* the differences in perldata.pod and perltoot.pod are 111 caused by (unnecessary?) Z<> sequences 112 113* the difference in perlfaq4.pod is due to sdf automatically 114 terminating an unterminated C<> phrase (as mentioned above) 115 after producing a warning about it 116 117* the differences in perlsubs.pod are due to one list ending 118 and another one starting, when it seems unnecessary to 119 do this. 120 121As yet, I haven't analysed the differences in perltoc.pod, 122but most of them seem to be related to list over/back 123commands. In any case, the output from 124 125 sdf -2html -cperl perltoc.pod 126 127seems ok. 128 129 130Known Bugs 131========== 132 133* The pod2sdf and POD::SDF.pm stuff hasn't been documented 134 yet. I'll probably do the doco for these in vanilla POD, 135 and offer for them to be included in the standard Perl 136 distribution. Thoughts? 137 138* The doco hasn't been updated to reflect the new macros, 139 phrase styles, etc. In particular, the User Guide, 140 Reference and White Paper need to be updated. 141 142* The X phrase style doesn't work yet for any output 143 format except POD (and those generated by going via POD). 144 If you need a workaround, indexing can be done using the 145 index phrase attribute. 146 147* sdf -2latex_pod xxx generates an xxx.out.tex file, rather 148 than an xxx.tex file. 149 150* The implementation of BuildLinkUrl() in perl/perl.sdm 151 (i.e. the perl configuration library) still needs 152 some more intelligence. 153 154* The -w option isn't currently passed through to pod2text. 155 (I had trouble getting pod2text to accept it.) 156 157* The toraw.pl driver needs to be updated to dump <> style phrases 158 rather than {{}} style ones. When this is done, the expected 159 output files in the test/*/checked directories will need to 160 be updated. 161 162 163Other Thoughts 164============== 165 166At the moment, the pod2* programs are substantially faster 167than the sdf program. The main performance issue with sdf 168is the loading of its configuration files. So, a one line 169document can take several seconds to convert, but a 100 170line document doesn't take much longer. I'm planning to 171address configuration file caching as part of the source 172code migration to Perl 5. Note that users can specify 173things on the command line and/or top line of a file which 174can affect the configuration loading process, so 175configuration caching is non trival. 176 177Some of the nice features in pod2html (e.g. hypertext link 178generation for Perl-specific items in general text) 179aren't available and I'm not yet sure how to provide them. 180 181A new -e option could be used to specify that SDF 182is embedded in source code comments and the appropriate 183leading character sequence should be stripped, if found. 184That sequence could be derived from the file extension 185or explicitly specified as a parameter to the -e option. 186Alternatively, SDF could check the file extension and 187assume the -e option if it looks like source code. 188The intention here is to provide a simple version of 189the functionality provided by Brad Appleton's POD::Parser 190preprocess_line() routine. 191 192The pod filter could take a select argument ala 193Brad Appleton's POD::Parser stuff. In fact, implementing 194the POD::SDF module using POD::Parser might be 195a good idea. (This wasn't done because the pod2sdf 196subroutine is currently pretty trivial.) 197 198POD pretty printing could be added by updating 199stdlib/langdefs.sdm. Each of the commands could 200be added as a keyword, although I'm not sure 201if we can highlight the interior sequences? 202 203Tim MacKenzie's enhancements to the txt output driver 204haven't been applied to the pod output driver yet. 205When that is done, wrapping of text within table cells 206should work. 207 208The POD convention of starting documentation with a =head NAME 209and putting the actual title as the next paragraph is a pain. 210I wish POD documents started with a =title instead. 211Perhaps pod2sdf could do this? 212 213It would be good if pod2sdf had an option to produce 214"traditional" SDF, i.e. with tagged lists, rather than 215over/item/back lists. 216 217The poddiff program isn't yet useful for comparing POD 218generated by sdf -2pod with POD in a .pm file. 219This could be changed by teaching Pod::Diff.pm to ignore 220lines which have been cut. 221