Commit | Line | Data |
---|---|---|
920dae64 AT |
1 | .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.32 |
2 | .\" | |
3 | .\" Standard preamble: | |
4 | .\" ======================================================================== | |
5 | .de Sh \" Subsection heading | |
6 | .br | |
7 | .if t .Sp | |
8 | .ne 5 | |
9 | .PP | |
10 | \fB\\$1\fR | |
11 | .PP | |
12 | .. | |
13 | .de Sp \" Vertical space (when we can't use .PP) | |
14 | .if t .sp .5v | |
15 | .if n .sp | |
16 | .. | |
17 | .de Vb \" Begin verbatim text | |
18 | .ft CW | |
19 | .nf | |
20 | .ne \\$1 | |
21 | .. | |
22 | .de Ve \" End verbatim text | |
23 | .ft R | |
24 | .fi | |
25 | .. | |
26 | .\" Set up some character translations and predefined strings. \*(-- will | |
27 | .\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left | |
28 | .\" double quote, and \*(R" will give a right double quote. | will give a | |
29 | .\" real vertical bar. \*(C+ will give a nicer C++. Capital omega is used to | |
30 | .\" do unbreakable dashes and therefore won't be available. \*(C` and \*(C' | |
31 | .\" expand to `' in nroff, nothing in troff, for use with C<>. | |
32 | .tr \(*W-|\(bv\*(Tr | |
33 | .ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p' | |
34 | .ie n \{\ | |
35 | . ds -- \(*W- | |
36 | . ds PI pi | |
37 | . if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch | |
38 | . if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\" diablo 12 pitch | |
39 | . ds L" "" | |
40 | . ds R" "" | |
41 | . ds C` "" | |
42 | . ds C' "" | |
43 | 'br\} | |
44 | .el\{\ | |
45 | . ds -- \|\(em\| | |
46 | . ds PI \(*p | |
47 | . ds L" `` | |
48 | . ds R" '' | |
49 | 'br\} | |
50 | .\" | |
51 | .\" If the F register is turned on, we'll generate index entries on stderr for | |
52 | .\" titles (.TH), headers (.SH), subsections (.Sh), items (.Ip), and index | |
53 | .\" entries marked with X<> in POD. Of course, you'll have to process the | |
54 | .\" output yourself in some meaningful fashion. | |
55 | .if \nF \{\ | |
56 | . de IX | |
57 | . tm Index:\\$1\t\\n%\t"\\$2" | |
58 | .. | |
59 | . nr % 0 | |
60 | . rr F | |
61 | .\} | |
62 | .\" | |
63 | .\" For nroff, turn off justification. Always turn off hyphenation; it makes | |
64 | .\" way too many mistakes in technical documents. | |
65 | .hy 0 | |
66 | .if n .na | |
67 | .\" | |
68 | .\" Accent mark definitions (@(#)ms.acc 1.5 88/02/08 SMI; from UCB 4.2). | |
69 | .\" Fear. Run. Save yourself. No user-serviceable parts. | |
70 | . \" fudge factors for nroff and troff | |
71 | .if n \{\ | |
72 | . ds #H 0 | |
73 | . ds #V .8m | |
74 | . ds #F .3m | |
75 | . ds #[ \f1 | |
76 | . ds #] \fP | |
77 | .\} | |
78 | .if t \{\ | |
79 | . ds #H ((1u-(\\\\n(.fu%2u))*.13m) | |
80 | . ds #V .6m | |
81 | . ds #F 0 | |
82 | . ds #[ \& | |
83 | . ds #] \& | |
84 | .\} | |
85 | . \" simple accents for nroff and troff | |
86 | .if n \{\ | |
87 | . ds ' \& | |
88 | . ds ` \& | |
89 | . ds ^ \& | |
90 | . ds , \& | |
91 | . ds ~ ~ | |
92 | . ds / | |
93 | .\} | |
94 | .if t \{\ | |
95 | . ds ' \\k:\h'-(\\n(.wu*8/10-\*(#H)'\'\h"|\\n:u" | |
96 | . ds ` \\k:\h'-(\\n(.wu*8/10-\*(#H)'\`\h'|\\n:u' | |
97 | . ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'^\h'|\\n:u' | |
98 | . ds , \\k:\h'-(\\n(.wu*8/10)',\h'|\\n:u' | |
99 | . ds ~ \\k:\h'-(\\n(.wu-\*(#H-.1m)'~\h'|\\n:u' | |
100 | . ds / \\k:\h'-(\\n(.wu*8/10-\*(#H)'\z\(sl\h'|\\n:u' | |
101 | .\} | |
102 | . \" troff and (daisy-wheel) nroff accents | |
103 | .ds : \\k:\h'-(\\n(.wu*8/10-\*(#H+.1m+\*(#F)'\v'-\*(#V'\z.\h'.2m+\*(#F'.\h'|\\n:u'\v'\*(#V' | |
104 | .ds 8 \h'\*(#H'\(*b\h'-\*(#H' | |
105 | .ds o \\k:\h'-(\\n(.wu+\w'\(de'u-\*(#H)/2u'\v'-.3n'\*(#[\z\(de\v'.3n'\h'|\\n:u'\*(#] | |
106 | .ds d- \h'\*(#H'\(pd\h'-\w'~'u'\v'-.25m'\f2\(hy\fP\v'.25m'\h'-\*(#H' | |
107 | .ds D- D\\k:\h'-\w'D'u'\v'-.11m'\z\(hy\v'.11m'\h'|\\n:u' | |
108 | .ds th \*(#[\v'.3m'\s+1I\s-1\v'-.3m'\h'-(\w'I'u*2/3)'\s-1o\s+1\*(#] | |
109 | .ds Th \*(#[\s+2I\s-2\h'-\w'I'u*3/5'\v'-.3m'o\v'.3m'\*(#] | |
110 | .ds ae a\h'-(\w'a'u*4/10)'e | |
111 | .ds Ae A\h'-(\w'A'u*4/10)'E | |
112 | . \" corrections for vroff | |
113 | .if v .ds ~ \\k:\h'-(\\n(.wu*9/10-\*(#H)'\s-2\u~\d\s+2\h'|\\n:u' | |
114 | .if v .ds ^ \\k:\h'-(\\n(.wu*10/11-\*(#H)'\v'-.4m'^\v'.4m'\h'|\\n:u' | |
115 | . \" for low resolution devices (crt and lpr) | |
116 | .if \n(.H>23 .if \n(.V>19 \ | |
117 | \{\ | |
118 | . ds : e | |
119 | . ds 8 ss | |
120 | . ds o a | |
121 | . ds d- d\h'-1'\(ga | |
122 | . ds D- D\h'-1'\(hy | |
123 | . ds th \o'bp' | |
124 | . ds Th \o'LP' | |
125 | . ds ae ae | |
126 | . ds Ae AE | |
127 | .\} | |
128 | .rm #[ #] #H #V #F C | |
129 | .\" ======================================================================== | |
130 | .\" | |
131 | .IX Title "Pod::ParseUtils 3" | |
132 | .TH Pod::ParseUtils 3 "2001-09-21" "perl v5.8.8" "Perl Programmers Reference Guide" | |
133 | .SH "NAME" | |
134 | Pod::ParseUtils \- helpers for POD parsing and conversion | |
135 | .SH "SYNOPSIS" | |
136 | .IX Header "SYNOPSIS" | |
137 | .Vb 1 | |
138 | \& use Pod::ParseUtils; | |
139 | .Ve | |
140 | .PP | |
141 | .Vb 2 | |
142 | \& my $list = new Pod::List; | |
143 | \& my $link = Pod::Hyperlink->new('Pod::Parser'); | |
144 | .Ve | |
145 | .SH "DESCRIPTION" | |
146 | .IX Header "DESCRIPTION" | |
147 | \&\fBPod::ParseUtils\fR contains a few object-oriented helper packages for | |
148 | \&\s-1POD\s0 parsing and processing (i.e. in \s-1POD\s0 formatters and translators). | |
149 | .Sh "Pod::List" | |
150 | .IX Subsection "Pod::List" | |
151 | \&\fBPod::List\fR can be used to hold information about \s-1POD\s0 lists | |
152 | (written as =over ... =item ... =back) for further processing. | |
153 | The following methods are available: | |
154 | .IP "Pod::List\->\fInew()\fR" 4 | |
155 | .IX Item "Pod::List->new()" | |
156 | Create a new list object. Properties may be specified through a hash | |
157 | reference like this: | |
158 | .Sp | |
159 | .Vb 1 | |
160 | \& my $list = Pod::List->new({ -start => $., -indent => 4 }); | |
161 | .Ve | |
162 | .Sp | |
163 | See the individual methods/properties for details. | |
164 | .IP "$list\->\fIfile()\fR" 4 | |
165 | .IX Item "$list->file()" | |
166 | Without argument, retrieves the file name the list is in. This must | |
167 | have been set before by either specifying \fB\-file\fR in the \fB\f(BInew()\fB\fR | |
168 | method or by calling the \fB\f(BIfile()\fB\fR method with a scalar argument. | |
169 | .IP "$list\->\fIstart()\fR" 4 | |
170 | .IX Item "$list->start()" | |
171 | Without argument, retrieves the line number where the list started. | |
172 | This must have been set before by either specifying \fB\-start\fR in the | |
173 | \&\fB\f(BInew()\fB\fR method or by calling the \fB\f(BIstart()\fB\fR method with a scalar | |
174 | argument. | |
175 | .IP "$list\->\fIindent()\fR" 4 | |
176 | .IX Item "$list->indent()" | |
177 | Without argument, retrieves the indent level of the list as specified | |
178 | in \f(CW\*(C`=over n\*(C'\fR. This must have been set before by either specifying | |
179 | \&\fB\-indent\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BIindent()\fB\fR method | |
180 | with a scalar argument. | |
181 | .IP "$list\->\fItype()\fR" 4 | |
182 | .IX Item "$list->type()" | |
183 | Without argument, retrieves the list type, which can be an arbitrary value, | |
184 | e.g. \f(CW\*(C`OL\*(C'\fR, \f(CW\*(C`UL\*(C'\fR, ... when thinking the \s-1HTML\s0 way. | |
185 | This must have been set before by either specifying | |
186 | \&\fB\-type\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BItype()\fB\fR method | |
187 | with a scalar argument. | |
188 | .IP "$list\->\fIrx()\fR" 4 | |
189 | .IX Item "$list->rx()" | |
190 | Without argument, retrieves a regular expression for simplifying the | |
191 | individual item strings once the list type has been determined. Usage: | |
192 | E.g. when converting to \s-1HTML\s0, one might strip the leading number in | |
193 | an ordered list as \f(CW\*(C`<OL>\*(C'\fR already prints numbers itself. | |
194 | This must have been set before by either specifying | |
195 | \&\fB\-rx\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BIrx()\fB\fR method | |
196 | with a scalar argument. | |
197 | .IP "$list\->\fIitem()\fR" 4 | |
198 | .IX Item "$list->item()" | |
199 | Without argument, retrieves the array of the items in this list. | |
200 | The items may be represented by any scalar. | |
201 | If an argument has been given, it is pushed on the list of items. | |
202 | .IP "$list\->\fIparent()\fR" 4 | |
203 | .IX Item "$list->parent()" | |
204 | Without argument, retrieves information about the parent holding this | |
205 | list, which is represented as an arbitrary scalar. | |
206 | This must have been set before by either specifying | |
207 | \&\fB\-parent\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BIparent()\fB\fR method | |
208 | with a scalar argument. | |
209 | .IP "$list\->\fItag()\fR" 4 | |
210 | .IX Item "$list->tag()" | |
211 | Without argument, retrieves information about the list tag, which can be | |
212 | any scalar. | |
213 | This must have been set before by either specifying | |
214 | \&\fB\-tag\fR in the \fB\f(BInew()\fB\fR method or by calling the \fB\f(BItag()\fB\fR method | |
215 | with a scalar argument. | |
216 | .Sh "Pod::Hyperlink" | |
217 | .IX Subsection "Pod::Hyperlink" | |
218 | \&\fBPod::Hyperlink\fR is a class for manipulation of \s-1POD\s0 hyperlinks. Usage: | |
219 | .PP | |
220 | .Vb 1 | |
221 | \& my $link = Pod::Hyperlink->new('alternative text|page/"section in page"'); | |
222 | .Ve | |
223 | .PP | |
224 | The \fBPod::Hyperlink\fR class is mainly designed to parse the contents of the | |
225 | \&\f(CW\*(C`L<...>\*(C'\fR sequence, providing a simple interface for accessing the | |
226 | different parts of a \s-1POD\s0 hyperlink for further processing. It can also be | |
227 | used to construct hyperlinks. | |
228 | .IP "Pod::Hyperlink\->\fInew()\fR" 4 | |
229 | .IX Item "Pod::Hyperlink->new()" | |
230 | The \fB\f(BInew()\fB\fR method can either be passed a set of key/value pairs or a single | |
231 | scalar value, namely the contents of a \f(CW\*(C`L<...>\*(C'\fR sequence. An object | |
232 | of the class \f(CW\*(C`Pod::Hyperlink\*(C'\fR is returned. The value \f(CW\*(C`undef\*(C'\fR indicates a | |
233 | failure, the error message is stored in \f(CW$@\fR. | |
234 | .IP "$link\->parse($string)" 4 | |
235 | .IX Item "$link->parse($string)" | |
236 | This method can be used to (re)parse a (new) hyperlink, i.e. the contents | |
237 | of a \f(CW\*(C`L<...>\*(C'\fR sequence. The result is stored in the current object. | |
238 | Warnings are stored in the \fBwarnings\fR property. | |
239 | E.g. sections like \f(CW\*(C`L<open(2)>\*(C'\fR are deprecated, as they do not point | |
240 | to Perl documents. \f(CW\*(C`L<DBI::foo(3p)>\*(C'\fR is wrong as well, the manpage | |
241 | section can simply be dropped. | |
242 | .IP "$link\->markup($string)" 4 | |
243 | .IX Item "$link->markup($string)" | |
244 | Set/retrieve the textual value of the link. This string contains special | |
245 | markers \f(CW\*(C`P<>\*(C'\fR and \f(CW\*(C`Q<>\*(C'\fR that should be expanded by the | |
246 | translator's interior sequence expansion engine to the | |
247 | formatter-specific code to highlight/activate the hyperlink. The details | |
248 | have to be implemented in the translator. | |
249 | .IP "$link\->\fItext()\fR" 4 | |
250 | .IX Item "$link->text()" | |
251 | This method returns the textual representation of the hyperlink as above, | |
252 | but without markers (read only). Depending on the link type this is one of | |
253 | the following alternatives (the + and * denote the portions of the text | |
254 | that are marked up): | |
255 | .Sp | |
256 | .Vb 4 | |
257 | \& +perl+ L<perl> | |
258 | \& *$|* in +perlvar+ L<perlvar/$|> | |
259 | \& *OPTIONS* in +perldoc+ L<perldoc/"OPTIONS"> | |
260 | \& *DESCRIPTION* L<"DESCRIPTION"> | |
261 | .Ve | |
262 | .IP "$link\->\fIwarning()\fR" 4 | |
263 | .IX Item "$link->warning()" | |
264 | After parsing, this method returns any warnings encountered during the | |
265 | parsing process. | |
266 | .IP "$link\->\fIfile()\fR" 4 | |
267 | .IX Item "$link->file()" | |
268 | .PD 0 | |
269 | .IP "$link\->\fIline()\fR" 4 | |
270 | .IX Item "$link->line()" | |
271 | .PD | |
272 | Just simple slots for storing information about the line and the file | |
273 | the link was encountered in. Has to be filled in manually. | |
274 | .IP "$link\->\fIpage()\fR" 4 | |
275 | .IX Item "$link->page()" | |
276 | This method sets or returns the \s-1POD\s0 page this link points to. | |
277 | .IP "$link\->\fInode()\fR" 4 | |
278 | .IX Item "$link->node()" | |
279 | As above, but the destination node text of the link. | |
280 | .IP "$link\->\fIalttext()\fR" 4 | |
281 | .IX Item "$link->alttext()" | |
282 | Sets or returns an alternative text specified in the link. | |
283 | .IP "$link\->\fItype()\fR" 4 | |
284 | .IX Item "$link->type()" | |
285 | The node type, either \f(CW\*(C`section\*(C'\fR or \f(CW\*(C`item\*(C'\fR. As an unofficial type, | |
286 | there is also \f(CW\*(C`hyperlink\*(C'\fR, derived from e.g. \f(CW\*(C`L<http://perl.com>\*(C'\fR | |
287 | .IP "$link\->\fIlink()\fR" 4 | |
288 | .IX Item "$link->link()" | |
289 | Returns the link as contents of \f(CW\*(C`L<>\*(C'\fR. Reciprocal to \fB\f(BIparse()\fB\fR. | |
290 | .Sh "Pod::Cache" | |
291 | .IX Subsection "Pod::Cache" | |
292 | \&\fBPod::Cache\fR holds information about a set of \s-1POD\s0 documents, | |
293 | especially the nodes for hyperlinks. | |
294 | The following methods are available: | |
295 | .IP "Pod::Cache\->\fInew()\fR" 4 | |
296 | .IX Item "Pod::Cache->new()" | |
297 | Create a new cache object. This object can hold an arbitrary number of | |
298 | \&\s-1POD\s0 documents of class Pod::Cache::Item. | |
299 | .IP "$cache\->\fIitem()\fR" 4 | |
300 | .IX Item "$cache->item()" | |
301 | Add a new item to the cache. Without arguments, this method returns a | |
302 | list of all cache elements. | |
303 | .IP "$cache\->find_page($name)" 4 | |
304 | .IX Item "$cache->find_page($name)" | |
305 | Look for a \s-1POD\s0 document named \f(CW$name\fR in the cache. Returns the | |
306 | reference to the corresponding Pod::Cache::Item object or undef if | |
307 | not found. | |
308 | .Sh "Pod::Cache::Item" | |
309 | .IX Subsection "Pod::Cache::Item" | |
310 | \&\fBPod::Cache::Item\fR holds information about individual \s-1POD\s0 documents, | |
311 | that can be grouped in a Pod::Cache object. | |
312 | It is intended to hold information about the hyperlink nodes of \s-1POD\s0 | |
313 | documents. | |
314 | The following methods are available: | |
315 | .IP "Pod::Cache::Item\->\fInew()\fR" 4 | |
316 | .IX Item "Pod::Cache::Item->new()" | |
317 | Create a new object. | |
318 | .IP "$cacheitem\->\fIpage()\fR" 4 | |
319 | .IX Item "$cacheitem->page()" | |
320 | Set/retrieve the \s-1POD\s0 document name (e.g. \*(L"Pod::Parser\*(R"). | |
321 | .IP "$cacheitem\->\fIdescription()\fR" 4 | |
322 | .IX Item "$cacheitem->description()" | |
323 | Set/retrieve the \s-1POD\s0 short description as found in the \f(CW\*(C`=head1 NAME\*(C'\fR | |
324 | section. | |
325 | .IP "$cacheitem\->\fIpath()\fR" 4 | |
326 | .IX Item "$cacheitem->path()" | |
327 | Set/retrieve the \s-1POD\s0 file storage path. | |
328 | .IP "$cacheitem\->\fIfile()\fR" 4 | |
329 | .IX Item "$cacheitem->file()" | |
330 | Set/retrieve the \s-1POD\s0 file name. | |
331 | .IP "$cacheitem\->\fInodes()\fR" 4 | |
332 | .IX Item "$cacheitem->nodes()" | |
333 | Add a node (or a list of nodes) to the document's node list. Note that | |
334 | the order is kept, i.e. start with the first node and end with the last. | |
335 | If no argument is given, the current list of nodes is returned in the | |
336 | same order the nodes have been added. | |
337 | A node can be any scalar, but usually is a pair of node string and | |
338 | unique id for the \f(CW\*(C`find_node\*(C'\fR method to work correctly. | |
339 | .IP "$cacheitem\->find_node($name)" 4 | |
340 | .IX Item "$cacheitem->find_node($name)" | |
341 | Look for a node or index entry named \f(CW$name\fR in the object. | |
342 | Returns the unique id of the node (i.e. the second element of the array | |
343 | stored in the node arry) or undef if not found. | |
344 | .IP "$cacheitem\->\fIidx()\fR" 4 | |
345 | .IX Item "$cacheitem->idx()" | |
346 | Add an index entry (or a list of them) to the document's index list. Note that | |
347 | the order is kept, i.e. start with the first node and end with the last. | |
348 | If no argument is given, the current list of index entries is returned in the | |
349 | same order the entries have been added. | |
350 | An index entry can be any scalar, but usually is a pair of string and | |
351 | unique id. | |
352 | .SH "AUTHOR" | |
353 | .IX Header "AUTHOR" | |
354 | Please report bugs using <http://rt.cpan.org>. | |
355 | .PP | |
356 | Marek Rouchal <marekr@cpan.org>, borrowing | |
357 | a lot of things from pod2man and pod2roff as well as other \s-1POD\s0 | |
358 | processing tools by Tom Christiansen, Brad Appleton and Russ Allbery. | |
359 | .SH "SEE ALSO" | |
360 | .IX Header "SEE ALSO" | |
361 | pod2man, pod2roff, Pod::Parser, Pod::Checker, | |
362 | pod2html |