Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
cb1a09d0 |
3 | perlpod - plain old documentation |
a0d0e21e |
4 | |
5 | =head1 DESCRIPTION |
6 | |
7 | A pod-to-whatever translator reads a pod file paragraph by paragraph, |
8 | and translates it to the appropriate output format. There are |
9 | three kinds of paragraphs: |
10 | |
11 | =over 4 |
12 | |
13 | =item * |
14 | |
15 | A verbatim paragraph, distinguished by being indented (that is, |
16 | it starts with space or tab). It should be reproduced exactly, |
17 | with tabs assumed to be on 8-column boundaries. There are no |
18 | special formatting escapes, so you can't italicize or anything |
19 | like that. A \ means \, and nothing else. |
20 | |
21 | =item * |
22 | |
23 | A command. All command paragraphs start with "=", followed by an |
24 | identifier, followed by arbitrary text that the command can |
25 | use however it pleases. Currently recognized commands are |
26 | |
27 | =head1 heading |
28 | =head2 heading |
29 | =item text |
30 | =over N |
31 | =back |
4633a7c4 |
32 | =cut |
cb1a09d0 |
33 | =pod |
c7c9f956 |
34 | =for X |
35 | =begin X |
36 | =end X |
cb1a09d0 |
37 | |
38 | The "=pod" directive does nothing beyond telling the compiler to lay |
116160e3 |
39 | off parsing code through the next "=cut". It's useful for adding |
40 | another paragraph to the doc if you're mixing up code and pod a lot. |
cb1a09d0 |
41 | |
116160e3 |
42 | Head1 and head2 produce first and second level headings, with the text in |
43 | the same paragraph as the "=headn" directive forming the heading description. |
cb1a09d0 |
44 | |
116160e3 |
45 | Item, over, and back require a little more explanation: "=over" starts a |
46 | section specifically for the generation of a list using "=item" commands. At |
47 | the end of your list, use "=back" to end it. You will probably want to give |
48 | "4" as the number to "=over", as some formatters will use this for indentation. |
cb1a09d0 |
49 | This should probably be a default. Note also that there are some basic rules |
50 | to using =item: don't use them outside of an =over/=back block, use at least |
51 | one inside an =over/=back block, you don't _have_ to include the =back if |
52 | the list just runs off the document, and perhaps most importantly, keep the |
53 | items consistent: either use "=item *" for all of them, to produce bullets, |
54 | or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use |
55 | "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets |
56 | or numbers. If you start with bullets or numbers, stick with them, as many |
54310121 |
57 | formatters use the first "=item" type to decide how to format the list. |
cb1a09d0 |
58 | |
116160e3 |
59 | For, begin, and end let you include sections that are not interpreted |
60 | as pod text, but passed directly to particular formatters. A formatter |
61 | that can utilize that format will use the section, otherwise it will be |
62 | completely ignored. The directive "=for" specifies that the entire next |
63 | paragraph is in the format indicated by the first word after |
64 | "=for", like this: |
c7c9f956 |
65 | |
54310121 |
66 | =for html <br> |
c7c9f956 |
67 | <p> This is a raw HTML paragraph </p> |
68 | |
116160e3 |
69 | The paired commands "=begin" and "=end" work very similarly to "=for", but |
70 | instead of only accepting a single paragraph, all text from "=begin" to a |
54310121 |
71 | paragraph with a matching "=end" are treated as a particular format. |
c7c9f956 |
72 | |
73 | Here are some examples of how to use these: |
74 | |
75 | =begin html |
a6006777 |
76 | |
c7c9f956 |
77 | <br>Figure 1.<IMG SRC="figure1.png"><br> |
a6006777 |
78 | |
c7c9f956 |
79 | =end html |
a6006777 |
80 | |
c7c9f956 |
81 | =begin text |
a6006777 |
82 | |
c7c9f956 |
83 | --------------- |
84 | | foo | |
85 | | bar | |
86 | --------------- |
a6006777 |
87 | |
c7c9f956 |
88 | ^^^^ Figure 1. ^^^^ |
a6006777 |
89 | |
c7c9f956 |
90 | =end text |
91 | |
92 | Some format names that formatters currently are known to accept include |
93 | "roff", "man", "latex", "tex", "text", and "html". (Some formatters will |
94 | treat some of these as synonyms.) |
95 | |
116160e3 |
96 | And don't forget, when using any command, that the command lasts up until |
cb1a09d0 |
97 | the end of the B<paragraph>, not the line. Hence in the examples below, you |
3fe9a6f1 |
98 | can see the empty lines after each command to end its paragraph. |
cb1a09d0 |
99 | |
100 | Some examples of lists include: |
101 | |
102 | =over 4 |
103 | |
104 | =item * |
105 | |
106 | First item |
107 | |
108 | =item * |
109 | |
110 | Second item |
111 | |
112 | =back |
113 | |
114 | =over 4 |
115 | |
116 | =item Foo() |
117 | |
118 | Description of Foo function |
119 | |
120 | =item Bar() |
121 | |
122 | Description of Bar function |
123 | |
124 | =back |
a0d0e21e |
125 | |
126 | =item * |
127 | |
128 | An ordinary block of text. It will be filled, and maybe even |
129 | justified. Certain interior sequences are recognized both |
130 | here and in commands: |
131 | |
132 | I<text> italicize text, used for emphasis or variables |
133 | B<text> embolden text, used for switches and programs |
134 | S<text> text contains non-breaking spaces |
54310121 |
135 | C<code> literal code |
a0d0e21e |
136 | L<name> A link (cross reference) to name |
5f05dabc |
137 | L<name> manual page |
138 | L<name/ident> item in manual page |
139 | L<name/"sec"> section in other manual page |
140 | L<"sec"> section in this manual page |
a0d0e21e |
141 | (the quotes are optional) |
cb1a09d0 |
142 | L</"sec"> ditto |
a0d0e21e |
143 | F<file> Used for filenames |
cb1a09d0 |
144 | X<index> An index entry |
fa859636 |
145 | Z<> A zero-width character |
c7c9f956 |
146 | E<escape> A named character (very similar to HTML escapes) |
1294c5d8 |
147 | E<lt> A literal < |
148 | E<gt> A literal > |
149 | (these are optional except in other interior |
150 | sequences and when preceded by a capital letter) |
c7c9f956 |
151 | E<n> Character number n (probably in ASCII) |
7f3dfc00 |
152 | E<html> Some non-numeric HTML entity, such |
153 | as E<Agrave> |
a0d0e21e |
154 | |
3141265f |
155 | =back |
156 | |
a0d0e21e |
157 | That's it. The intent is simplicity, not power. I wanted paragraphs |
158 | to look like paragraphs (block format), so that they stand out |
159 | visually, and so that I could run them through fmt easily to reformat |
160 | them (that's F7 in my version of B<vi>). I wanted the translator (and not |
161 | me) to worry about whether " or ' is a left quote or a right quote |
5f05dabc |
162 | within filled text, and I wanted it to leave the quotes alone, dammit, in |
a0d0e21e |
163 | verbatim mode, so I could slurp in a working program, shift it over 4 |
164 | spaces, and have it print out, er, verbatim. And presumably in a |
165 | constant width font. |
166 | |
167 | In particular, you can leave things like this verbatim in your text: |
168 | |
169 | Perl |
170 | FILEHANDLE |
171 | $variable |
172 | function() |
173 | manpage(3r) |
174 | |
175 | Doubtless a few other commands or sequences will need to be added along |
176 | the way, but I've gotten along surprisingly well with just these. |
177 | |
178 | Note that I'm not at all claiming this to be sufficient for producing a |
179 | book. I'm just trying to make an idiot-proof common source for nroff, |
180 | TeX, and other markup languages, as used for online documentation. |
cb1a09d0 |
181 | Translators exist for B<pod2man> (that's for nroff(1) and troff(1)), |
182 | B<pod2html>, B<pod2latex>, and B<pod2fm>. |
a0d0e21e |
183 | |
4633a7c4 |
184 | =head1 Embedding Pods in Perl Modules |
185 | |
186 | You can embed pod documentation in your Perl scripts. Start your |
116160e3 |
187 | documentation with a "=head1" command at the beginning, and end it |
188 | with a "=cut" command. Perl will ignore the pod text. See any of the |
189 | supplied library modules for examples. If you're going to put your |
190 | pods at the end of the file, and you're using an __END__ or __DATA__ |
3fe9a6f1 |
191 | cut mark, make sure to put an empty line there before the first pod |
116160e3 |
192 | directive. |
cb1a09d0 |
193 | |
194 | __END__ |
195 | |
116160e3 |
196 | |
cb1a09d0 |
197 | =head1 NAME |
198 | |
199 | modern - I am a modern module |
200 | |
3fe9a6f1 |
201 | If you had not had that empty line there, then the translators wouldn't |
cb1a09d0 |
202 | have seen it. |
203 | |
1294c5d8 |
204 | =head1 Common Pod Pitfalls |
205 | |
206 | =over 4 |
207 | |
208 | =item * |
209 | |
210 | Pod translators usually will require paragraphs to be separated by |
3fe9a6f1 |
211 | completely empty lines. If you have an apparently empty line with |
1294c5d8 |
212 | some spaces on it, this can cause odd formatting. |
213 | |
214 | =item * |
215 | |
216 | Translators will mostly add wording around a LE<lt>E<gt> link, so that |
217 | C<LE<lt>foo(1)E<gt>> becomes "the I<foo>(1) manpage", for example (see |
218 | B<pod2man> for details). Thus, you shouldn't write things like C<the |
219 | LE<lt>fooE<gt> manpage>, if you want the translated document to read |
220 | sensibly. |
221 | |
222 | =item * |
223 | |
224 | The script F<pod/checkpods.PL> in the Perl source distribution |
3fe9a6f1 |
225 | provides skeletal checking for lines that look empty but aren't |
1294c5d8 |
226 | B<only>, but is there as a placeholder until someone writes |
227 | Pod::Checker. The best way to check your pod is to pass it through |
228 | one or more translators and proofread the result, or print out the |
229 | result and proofread that. Some of the problems found may be bugs in |
230 | the translators, which you may or may not wish to work around. |
231 | |
232 | =back |
233 | |
cb1a09d0 |
234 | =head1 SEE ALSO |
235 | |
236 | L<pod2man> and L<perlsyn/"PODs: Embedded Documentation"> |
4633a7c4 |
237 | |
cb1a09d0 |
238 | =head1 AUTHOR |
a0d0e21e |
239 | |
240 | Larry Wall |
241 | |