Commit | Line | Data |
a0d0e21e |
1 | =head1 NAME |
2 | |
3 | pod - plain old documentation |
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 |
32 | |
33 | =item * |
34 | |
35 | An ordinary block of text. It will be filled, and maybe even |
36 | justified. Certain interior sequences are recognized both |
37 | here and in commands: |
38 | |
39 | I<text> italicize text, used for emphasis or variables |
40 | B<text> embolden text, used for switches and programs |
41 | S<text> text contains non-breaking spaces |
42 | C<code> literal code |
43 | L<name> A link (cross reference) to name |
44 | L<name> manpage |
45 | L<name/ident> item in manpage |
46 | L<name/"sec"> section in other manpage |
47 | L<"sec"> section in this manpage |
48 | (the quotes are optional) |
49 | F<file> Used for filenames |
50 | Z<> A zero-width character |
51 | |
52 | That's it. The intent is simplicity, not power. I wanted paragraphs |
53 | to look like paragraphs (block format), so that they stand out |
54 | visually, and so that I could run them through fmt easily to reformat |
55 | them (that's F7 in my version of B<vi>). I wanted the translator (and not |
56 | me) to worry about whether " or ' is a left quote or a right quote |
57 | within filled text, and I wanted it to leave the quotes alone dammit in |
58 | verbatim mode, so I could slurp in a working program, shift it over 4 |
59 | spaces, and have it print out, er, verbatim. And presumably in a |
60 | constant width font. |
61 | |
62 | In particular, you can leave things like this verbatim in your text: |
63 | |
64 | Perl |
65 | FILEHANDLE |
66 | $variable |
67 | function() |
68 | manpage(3r) |
69 | |
70 | Doubtless a few other commands or sequences will need to be added along |
71 | the way, but I've gotten along surprisingly well with just these. |
72 | |
73 | Note that I'm not at all claiming this to be sufficient for producing a |
74 | book. I'm just trying to make an idiot-proof common source for nroff, |
75 | TeX, and other markup languages, as used for online documentation. |
76 | Both B<pod2html> and B<pod2man> translators exist. |
77 | |
78 | =head1 Author |
79 | |
80 | Larry Wall |
81 | |