diff options
Diffstat (limited to 'contrib/perl5/pod/perlpod.pod')
| -rw-r--r-- | contrib/perl5/pod/perlpod.pod | 318 |
1 files changed, 0 insertions, 318 deletions
diff --git a/contrib/perl5/pod/perlpod.pod b/contrib/perl5/pod/perlpod.pod deleted file mode 100644 index 1076ffe..0000000 --- a/contrib/perl5/pod/perlpod.pod +++ /dev/null @@ -1,318 +0,0 @@ -=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. -The unit of indentation is optional. If the unit is not given the natural -indentation of the formatting system applied will be used. 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> Render code in a typewriter font, or give some other - indication that this represents program text - 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 '/' and '|', - and should contain matched '<' 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 > - E<sol> A literal / - E<verbar> 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> - -Most of the time, you will only need a single set of angle brackets to -delimit the beginning and end of interior sequences. However, sometimes -you will want to put a right angle bracket (or greater-than sign '>') -inside of a sequence. This is particularly common when using a sequence -to provide a different font-type for a snippet of code. As with all -things in Perl, there is more than one way to do it. One way is to -simply escape the closing bracket using an C<E> sequence: - - C<$a E<lt>=E<gt> $b> - -This will produce: "C<$a E<lt>=E<gt> $b>" - -A more readable, and perhaps more "plain" way is to use an alternate set of -delimiters that doesn't require a ">" to be escaped. As of perl5.5.660, -doubled angle brackets ("<<" and ">>") may be used I<if and only if there -is whitespace immediately following the opening delimiter and immediately -preceding the closing delimiter!> For example, the following will do the -trick: - - C<< $a <=> $b >> - -In fact, you can use as many repeated angle-brackets as you like so -long as you have the same number of them in the opening and closing -delimiters, and make sure that whitespace immediately follows the last -'<' of the opening delimiter, and immediately precedes the first '>' of -the closing delimiter. So the following will also work: - - C<<< $a <=> $b >>> - C<<<< $a <=> $b >>>> - -This is currently supported by pod2text (Pod::Text), pod2man (Pod::Man), -and any other pod2xxx and Pod::Xxxx translator that uses Pod::Parser -1.093 or later. - - -=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 need 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 B<podchecker> command is provided to check pod syntax -for errors and warnings. For example, it checks for completely -blank lines in pod segments and for unknown escape sequences. -It is still advised 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>, L<perlsyn/"PODs: Embedded Documentation">, -L<podchecker> - -=head1 AUTHOR - -Larry Wall - |
