X-Git-Url: http://git.shadowcat.co.uk/gitweb/gitweb.cgi?a=blobdiff_plain;f=pod%2Fperlpod.pod;h=731a0fbd3d9205745fc451130ccc940a7e944696;hb=9741dab02becad0550bba7d5ca9e59f8ac608b2d;hp=dcf615daa33ebfd4514df6c1e43e2b472ef605a7;hpb=0135f10892ed8a21c4dbd1fca21fbcc365df99dd;p=p5sagit%2Fp5-mst-13.2.git diff --git a/pod/perlpod.pod b/pod/perlpod.pod index dcf615d..731a0fb 100644 --- a/pod/perlpod.pod +++ b/pod/perlpod.pod @@ -7,10 +7,11 @@ perlpod - plain old documentation 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, +L, and +L. -=over 4 - -=item * +=head2 Verbatim Paragraph A verbatim paragraph, distinguished by being indented (that is, it starts with space or tab). It should be reproduced exactly, @@ -18,9 +19,9 @@ 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. -=item * +=head2 Command Paragraph -A command. All command paragraphs start with "=", followed by an +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 @@ -31,18 +32,37 @@ use however it pleases. Currently recognized commands are =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 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. + +=item =head1 -Head1 and head2 produce first and second level headings, with the text on -the same paragraph as "=headn" forming the heading description. +=item =head2 -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. +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 @@ -51,11 +71,54 @@ 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. +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: -And don't forget, when using any command, that that command lasts up until + =for html
+

This is a raw HTML paragraph

+ +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 + +
Figure 1.
+ + =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, not the line. Hence in the examples below, you -can see the blank lines after each command to end its paragraph. +can see the empty lines after each command to end its paragraph. Some examples of lists include: @@ -83,16 +146,18 @@ Some examples of lists include: =back -=item * +=back + +=head2 Ordinary Block of Text -An ordinary block of text. It will be filled, and maybe even +It will be filled, and maybe even justified. Certain interior sequences are recognized both here and in commands: I italicize text, used for emphasis or variables B embolden text, used for switches and programs S text contains non-breaking spaces - C literal code + C literal code L A link (cross reference) to name L manual page L item in manual page @@ -100,17 +165,30 @@ here and in commands: L<"sec"> section in this manual page (the quotes are optional) L ditto + same as above but only 'text' is used for output. + (Text can not contain the characters '/' and '|', + and should contain matched '<' or '>') + L + L + L + L + L + F Used for filenames X An index entry - Z<> A zero-width character - E An HTML escape + Z<> A zero-width character + E A named character (very similar to HTML escapes) E A literal < E A literal > + E A literal / + E A literal | (these are optional except in other interior sequences and when preceded by a capital letter) - E Character number nnn. + E Character number n (probably in ASCII) + E Some non-numeric HTML entity, such + as E -=back +=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 @@ -137,17 +215,17 @@ 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 (that's for nroff(1) and troff(1)), -B, B, and B. +B, B, B, and B. -=head1 Embedding Pods in Perl Modules +=head2 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__ @@ -155,17 +233,17 @@ the first pod directive. 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 +=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 blank line with +completely empty lines. If you have an apparently empty line with some spaces on it, this can cause odd formatting. =item * @@ -176,10 +254,14 @@ B for details). Thus, you shouldn't write things like CfooE 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 LEshow this text|fooE +instead. + =item * The script F in the Perl source distribution -provides skeletal checking for lines that look blank but aren't +provides skeletal checking for lines that look empty but aren't B, 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