diff options
| author | Joseph S. Myers <jsm28@cam.ac.uk> | 1996-11-20 23:54:41 +0000 |
|---|---|---|
| committer | Chip Salzenberg <chip@atlantic.net> | 1996-11-26 20:48:00 +1200 |
| commit | 1294c5d8aacbdf3e788f97f257074bdd2bf02fd9 (patch) | |
| tree | ebb5e67afda6c1f3be65cdf4d9f137d8cc91674f /pod/perlpod.pod | |
| parent | 161d563a18e80d3ad960c62fc04d928fc43afee5 (diff) | |
| download | perl-1294c5d8aacbdf3e788f97f257074bdd2bf02fd9.tar.gz | |
Patch for pod/perlpod.pod
This patch documents the E<lt> and E<gt> pod escapes, and adds a section
on common pod pitfalls (in particular the text that translators add around
L<> links, since these seem very commonly to be used incorrectly).
p5p-msgid: <Pine.LNX.3.95.961120235016.6666A-100000@hammer.chu.cam.ac.uk>
private-msgid: <Pine.LNX.3.95.961120235016.6666A-100000@hammer.chu.cam.ac.uk
Diffstat (limited to 'pod/perlpod.pod')
| -rw-r--r-- | pod/perlpod.pod | 36 |
1 files changed, 36 insertions, 0 deletions
diff --git a/pod/perlpod.pod b/pod/perlpod.pod index ce02970013..3722e2c36c 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -103,6 +103,12 @@ here and in commands: F<file> Used for filenames X<index> An index entry Z<> A zero-width character + E<escape> An HTML escape + E<lt> A literal < + E<gt> A literal > + (these are optional except in other interior + sequences and when preceded by a capital letter) + E<nnn> Character number nnn. =back @@ -152,6 +158,36 @@ the first pod directive. If you had not had that blank line there, then the translators wouldn't have seen it. +=head1 Common Pod Pitfalls + +=over 4 + +=item * + +Pod translators usually will require paragraphs to be separated by +completely empty lines. If you have an apparently blank line with +some spaces on it, this can cause odd formatting. + +=item * + +Translators will mostly add wording around a LE<lt>E<gt> link, so that +C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see +B<pod2man> for details). Thus, you shouldn't write things like C<the +LE<lt>fooE<gt> manpage>, if you want the translated document to read +sensibly. + +=item * + +The script F<pod/checkpods.PL> in the Perl source distribution +provides skeletal checking for lines that look blank but aren't +B<only>, but is there as a placeholder until someone writes +Pod::Checker. The best way to check your pod is to pass it through +one or more translators and proofread the result, or print out the +result and proofread that. Some of the problems found may be bugs in +the translators, which you may or may not wish to work around. + +=back + =head1 SEE ALSO L<pod2man> and L<perlsyn/"PODs: Embedded Documentation"> |