diff options
| author | markm <markm@FreeBSD.org> | 1998-09-09 07:00:04 +0000 |
|---|---|---|
| committer | markm <markm@FreeBSD.org> | 1998-09-09 07:00:04 +0000 |
| commit | 4fcbc3669aa997848e15198cc9fb856287a6788c (patch) | |
| tree | 58b20e81687d6d5931f120b50802ed21225bf440 /contrib/perl5/pod/perlpod.pod | |
| download | FreeBSD-src-4fcbc3669aa997848e15198cc9fb856287a6788c.zip FreeBSD-src-4fcbc3669aa997848e15198cc9fb856287a6788c.tar.gz | |
Initial import of Perl5. The king is dead; long live the king!
Diffstat (limited to 'contrib/perl5/pod/perlpod.pod')
| -rw-r--r-- | contrib/perl5/pod/perlpod.pod | 286 |
1 files changed, 286 insertions, 0 deletions
diff --git a/contrib/perl5/pod/perlpod.pod b/contrib/perl5/pod/perlpod.pod new file mode 100644 index 0000000..d20d62d --- /dev/null +++ b/contrib/perl5/pod/perlpod.pod @@ -0,0 +1,286 @@ +=head1 NAME + +perlpod - plain old documentation + +=head1 DESCRIPTION + +A pod-to-whatever translator reads a pod file paragraph by paragraph, +and translates it to the appropriate output format. There are +three kinds of paragraphs: +L<verbatim|/"Verbatim Paragraph">, +L<command|/"Command Paragraph">, and +L<ordinary text|/"Ordinary Block of Text">. + + +=head2 Verbatim Paragraph + +A verbatim paragraph, distinguished by being indented (that is, +it starts with space or tab). It should be reproduced exactly, +with tabs assumed to be on 8-column boundaries. There are no +special formatting escapes, so you can't italicize or anything +like that. A \ means \, and nothing else. + + +=head2 Command Paragraph + +All command paragraphs start with "=", followed by an +identifier, followed by arbitrary text that the command can +use however it pleases. Currently recognized commands are + + =head1 heading + =head2 heading + =item text + =over N + =back + =cut + =pod + =for X + =begin X + =end X + +=over 4 + +=item =pod + +=item =cut + +The "=pod" directive does nothing beyond telling the compiler to lay +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. + +=item =head1 + +=item =head2 + +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 + +=item =back + +=item =item + +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 +the list just runs off the document, and perhaps most importantly, keep the +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 use the first "=item" type to decide how to format the list. + + +=item =for + +=item =begin + +=item =end + +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 empty lines after each command to end its paragraph. + +Some examples of lists include: + + =over 4 + + =item * + + First item + + =item * + + Second item + + =back + + =over 4 + + =item Foo() + + Description of Foo function + + =item Bar() + + Description of Bar function + + =back + + +=back + + +=head2 Ordinary Block of Text + +It will be filled, and maybe even +justified. Certain interior sequences are recognized both +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 + L<name> A link (cross reference) to name + 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 + same as above but only 'text' is used for output. + (Text can not contain the characters '|' or '>') + L<text|name> + L<text|name/ident> + L<text|name/"sec"> + L<text|"sec"> + L<text|/"sec"> + + F<file> Used for filenames + X<index> An index entry + 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> + + +=head2 The Intent + +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 +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. + +In particular, you can leave things like this verbatim in your text: + + Perl + FILEHANDLE + $variable + function() + manpage(3r) + +Doubtless a few other commands or sequences will need to be added along +the way, but I've gotten along surprisingly well with just these. + +Note that I'm not at all claiming this to be sufficient for producing a +book. I'm just trying to make an idiot-proof common source for nroff, +TeX, and other markup languages, as used for online documentation. +Translators exist for B<pod2man> (that's for nroff(1) and troff(1)), +B<pod2text>, B<pod2html>, B<pod2latex>, and B<pod2fm>. + + +=head2 Embedding Pods in Perl Modules + +You can embed pod documentation in your Perl scripts. Start your +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 empty line there, then the translators wouldn't +have seen it. + + +=head2 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. + +If you don need or want total control of the text used for a +link in the output use the form LE<lt>show this text|fooE<gt> +instead. + +=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"> + +=head1 AUTHOR + +Larry Wall + |
