-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathPODNOTES
220 lines (157 loc) · 7.2 KB
/
PODNOTES
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
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.