Commit | Line | Data |
---|---|---|
a0d0e21e LW |
1 | =head1 NAME |
2 | ||
cb1a09d0 | 3 | perlpod - plain old documentation |
a0d0e21e LW |
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 AD |
33 | =pod |
34 | ||
35 | The "=pod" directive does nothing beyond telling the compiler to lay | |
36 | off of through the next "=cut". It's useful for adding another | |
37 | paragraph to the doc if you're mixing up code and pod a lot. | |
38 | ||
39 | Head1 and head2 produce first and second level headings, with the text on | |
40 | the same paragraph as "=headn" forming the heading description. | |
41 | ||
42 | Item, over, and back require a little more explanation: Over starts a | |
43 | section specifically for the generation of a list using =item commands. At | |
44 | the end of your list, use =back to end it. You will probably want to give | |
184e9718 | 45 | "4" as the number to =over, as some formatters will use this for indentation. |
cb1a09d0 AD |
46 | This should probably be a default. Note also that there are some basic rules |
47 | to using =item: don't use them outside of an =over/=back block, use at least | |
48 | one inside an =over/=back block, you don't _have_ to include the =back if | |
49 | the list just runs off the document, and perhaps most importantly, keep the | |
50 | items consistent: either use "=item *" for all of them, to produce bullets, | |
51 | or use "=item 1.", "=item 2.", etc., to produce numbered lists, or use | |
52 | "=item foo", "=item bar", etc., i.e., things that looks nothing like bullets | |
53 | or numbers. If you start with bullets or numbers, stick with them, as many | |
184e9718 | 54 | formatters use the first =item type to decide how to format the list. |
cb1a09d0 AD |
55 | |
56 | And don't forget, when using any command, that that command lasts up until | |
57 | the end of the B<paragraph>, not the line. Hence in the examples below, you | |
184e9718 | 58 | can see the blank lines after each command to end its paragraph. |
cb1a09d0 AD |
59 | |
60 | Some examples of lists include: | |
61 | ||
62 | =over 4 | |
63 | ||
64 | =item * | |
65 | ||
66 | First item | |
67 | ||
68 | =item * | |
69 | ||
70 | Second item | |
71 | ||
72 | =back | |
73 | ||
74 | =over 4 | |
75 | ||
76 | =item Foo() | |
77 | ||
78 | Description of Foo function | |
79 | ||
80 | =item Bar() | |
81 | ||
82 | Description of Bar function | |
83 | ||
84 | =back | |
a0d0e21e LW |
85 | |
86 | =item * | |
87 | ||
88 | An ordinary block of text. It will be filled, and maybe even | |
89 | justified. Certain interior sequences are recognized both | |
90 | here and in commands: | |
91 | ||
92 | I<text> italicize text, used for emphasis or variables | |
93 | B<text> embolden text, used for switches and programs | |
94 | S<text> text contains non-breaking spaces | |
95 | C<code> literal code | |
96 | L<name> A link (cross reference) to name | |
97 | L<name> manpage | |
98 | L<name/ident> item in manpage | |
99 | L<name/"sec"> section in other manpage | |
100 | L<"sec"> section in this manpage | |
101 | (the quotes are optional) | |
cb1a09d0 | 102 | L</"sec"> ditto |
a0d0e21e | 103 | F<file> Used for filenames |
cb1a09d0 | 104 | X<index> An index entry |
a0d0e21e LW |
105 | Z<> A zero-width character |
106 | ||
3141265f | 107 | =back |
108 | ||
a0d0e21e LW |
109 | That's it. The intent is simplicity, not power. I wanted paragraphs |
110 | to look like paragraphs (block format), so that they stand out | |
111 | visually, and so that I could run them through fmt easily to reformat | |
112 | them (that's F7 in my version of B<vi>). I wanted the translator (and not | |
113 | me) to worry about whether " or ' is a left quote or a right quote | |
114 | within filled text, and I wanted it to leave the quotes alone dammit in | |
115 | verbatim mode, so I could slurp in a working program, shift it over 4 | |
116 | spaces, and have it print out, er, verbatim. And presumably in a | |
117 | constant width font. | |
118 | ||
119 | In particular, you can leave things like this verbatim in your text: | |
120 | ||
121 | Perl | |
122 | FILEHANDLE | |
123 | $variable | |
124 | function() | |
125 | manpage(3r) | |
126 | ||
127 | Doubtless a few other commands or sequences will need to be added along | |
128 | the way, but I've gotten along surprisingly well with just these. | |
129 | ||
130 | Note that I'm not at all claiming this to be sufficient for producing a | |
131 | book. I'm just trying to make an idiot-proof common source for nroff, | |
132 | TeX, and other markup languages, as used for online documentation. | |
cb1a09d0 AD |
133 | Translators exist for B<pod2man> (that's for nroff(1) and troff(1)), |
134 | B<pod2html>, B<pod2latex>, and B<pod2fm>. | |
a0d0e21e | 135 | |
4633a7c4 LW |
136 | =head1 Embedding Pods in Perl Modules |
137 | ||
138 | You can embed pod documentation in your Perl scripts. Start your | |
139 | documentation with a =head1 command at the beg, and end it with | |
140 | an =cut command. Perl will ignore the pod text. See any of the | |
cb1a09d0 AD |
141 | supplied library modules for examples. If you're going to put |
142 | your pods at the end of the file, and you're using an __END__ | |
143 | or __DATA__ cut mark, make sure to put a blank line there before | |
144 | the first pod directive. | |
145 | ||
146 | __END__ | |
147 | ||
148 | =head1 NAME | |
149 | ||
150 | modern - I am a modern module | |
151 | ||
152 | If you had not had that blank line there, then the translators wouldn't | |
153 | have seen it. | |
154 | ||
155 | =head1 SEE ALSO | |
156 | ||
157 | L<pod2man> and L<perlsyn/"PODs: Embedded Documentation"> | |
4633a7c4 | 158 | |
cb1a09d0 | 159 | =head1 AUTHOR |
a0d0e21e LW |
160 | |
161 | Larry Wall | |
162 |