diff options
Diffstat (limited to 'pod/perlpod.pod')
| -rw-r--r-- | pod/perlpod.pod | 131 |
1 files changed, 106 insertions, 25 deletions
diff --git a/pod/perlpod.pod b/pod/perlpod.pod index 6566ffb357..6a578caec3 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -31,18 +31,21 @@ use however it pleases. Currently recognized commands are =back =cut =pod + =for X + =begin X + =end X The "=pod" directive does nothing beyond telling the compiler to lay -off of through the next "=cut". It's useful for adding another -paragraph to the doc if you're mixing up code and pod a lot. +off parsing code through the next "=cut". It's useful for adding +another paragraph to the doc if you're mixing up code and pod a lot. -Head1 and head2 produce first and second level headings, with the text on -the same paragraph as "=headn" forming the heading description. +Head1 and head2 produce first and second level headings, with the text in +the same paragraph as the "=headn" directive forming the heading description. -Item, over, and back require a little more explanation: Over starts a -section specifically for the generation of a list using =item commands. At -the end of your list, use =back to end it. You will probably want to give -"4" as the number to =over, as some formatters will use this for indention. +Item, over, and back require a little more explanation: "=over" starts a +section specifically for the generation of a list using "=item" commands. At +the end of your list, use "=back" to end it. You will probably want to give +"4" as the number to "=over", as some formatters will use this for indentation. This should probably be a default. Note also that there are some basic rules to using =item: don't use them outside of an =over/=back block, use at least one inside an =over/=back block, you don't _have_ to include the =back if @@ -51,11 +54,48 @@ items consistent: either use "=item *" for all of them, to produce bullets, or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets or numbers. If you start with bullets or numbers, stick with them, as many -formatters you the first =item type to decide how to format the list. +formatters use the first "=item" type to decide how to format the list. -And don't forget, when using any command, that that command lasts up until +For, begin, and end let you include sections that are not interpreted +as pod text, but passed directly to particular formatters. A formatter +that can utilize that format will use the section, otherwise it will be +completely ignored. The directive "=for" specifies that the entire next +paragraph is in the format indicated by the first word after +"=for", like this: + + =for html <br> + <p> This is a raw HTML paragraph </p> + +The paired commands "=begin" and "=end" work very similarly to "=for", but +instead of only accepting a single paragraph, all text from "=begin" to a +paragraph with a matching "=end" are treated as a particular format. + +Here are some examples of how to use these: + + =begin html + + <br>Figure 1.<IMG SRC="figure1.png"><br> + + =end html + + =begin text + + --------------- + | foo | + | bar | + --------------- + + ^^^^ Figure 1. ^^^^ + + =end text + +Some format names that formatters currently are known to accept include +"roff", "man", "latex", "tex", "text", and "html". (Some formatters will +treat some of these as synonyms.) + +And don't forget, when using any command, that the command lasts up until the end of the B<paragraph>, not the line. Hence in the examples below, you -can see the blank lines after each command to end it's paragraph. +can see the empty lines after each command to end its paragraph. Some examples of lists include: @@ -92,24 +132,34 @@ here and in commands: I<text> italicize text, used for emphasis or variables B<text> embolden text, used for switches and programs S<text> text contains non-breaking spaces - C<code> literal code + C<code> literal code L<name> A link (cross reference) to name - L<name> manpage - L<name/ident> item in manpage - L<name/"sec"> section in other manpage - L<"sec"> section in this manpage + L<name> manual page + L<name/ident> item in manual page + L<name/"sec"> section in other manual page + L<"sec"> section in this manual page (the quotes are optional) L</"sec"> ditto F<file> Used for filenames X<index> An index entry - Z<> A zero-width character + Z<> A zero-width character + E<escape> A named character (very similar to HTML escapes) + E<lt> A literal < + E<gt> A literal > + (these are optional except in other interior + sequences and when preceded by a capital letter) + E<n> Character number n (probably in ASCII) + E<html> Some non-numeric HTML entity, such + as E<Agrave> + +=back That's it. The intent is simplicity, not power. I wanted paragraphs to look like paragraphs (block format), so that they stand out visually, and so that I could run them through fmt easily to reformat them (that's F7 in my version of B<vi>). I wanted the translator (and not me) to worry about whether " or ' is a left quote or a right quote -within filled text, and I wanted it to leave the quotes alone dammit in +within filled text, and I wanted it to leave the quotes alone, dammit, in verbatim mode, so I could slurp in a working program, shift it over 4 spaces, and have it print out, er, verbatim. And presumably in a constant width font. @@ -134,22 +184,53 @@ B<pod2html>, B<pod2latex>, and B<pod2fm>. =head1 Embedding Pods in Perl Modules You can embed pod documentation in your Perl scripts. Start your -documentation with a =head1 command at the beg, and end it with -an =cut command. Perl will ignore the pod text. See any of the -supplied library modules for examples. If you're going to put -your pods at the end of the file, and you're using an __END__ -or __DATA__ cut mark, make sure to put a blank line there before -the first pod directive. +documentation with a "=head1" command at the beginning, and end it +with a "=cut" command. Perl will ignore the pod text. See any of the +supplied library modules for examples. If you're going to put your +pods at the end of the file, and you're using an __END__ or __DATA__ +cut mark, make sure to put an empty line there before the first pod +directive. __END__ + =head1 NAME modern - I am a modern module -If you had not had that blank line there, then the translators wouldn't +If you had not had that empty 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 empty 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 empty 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"> |