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