| 1 |
.\" -*- mode: troff; coding: utf-8 -*- |
| 2 |
.\" Automatically generated by Pod::Man 5.0102 (Pod::Simple 3.45) |
| 3 |
.\" |
| 4 |
.\" Standard preamble: |
| 5 |
.\" ======================================================================== |
| 6 |
.de Sp \" Vertical space (when we can't use .PP) |
| 7 |
.if t .sp .5v |
| 8 |
.if n .sp |
| 9 |
.. |
| 10 |
.de Vb \" Begin verbatim text |
| 11 |
.ft CW |
| 12 |
.nf |
| 13 |
.ne \\$1 |
| 14 |
.. |
| 15 |
.de Ve \" End verbatim text |
| 16 |
.ft R |
| 17 |
.fi |
| 18 |
.. |
| 19 |
.\" \*(C` and \*(C' are quotes in nroff, nothing in troff, for use with C<>. |
| 20 |
.ie n \{\ |
| 21 |
. ds C` "" |
| 22 |
. ds C' "" |
| 23 |
'br\} |
| 24 |
.el\{\ |
| 25 |
. ds C` |
| 26 |
. ds C' |
| 27 |
'br\} |
| 28 |
.\" |
| 29 |
.\" Escape single quotes in literal strings from groff's Unicode transform. |
| 30 |
.ie \n(.g .ds Aq \(aq |
| 31 |
.el .ds Aq ' |
| 32 |
.\" |
| 33 |
.\" If the F register is >0, we'll generate index entries on stderr for |
| 34 |
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index |
| 35 |
.\" entries marked with X<> in POD. Of course, you'll have to process the |
| 36 |
.\" output yourself in some meaningful fashion. |
| 37 |
.\" |
| 38 |
.\" Avoid warning from groff about undefined register 'F'. |
| 39 |
.de IX |
| 40 |
.. |
| 41 |
.nr rF 0 |
| 42 |
.if \n(.g .if rF .nr rF 1 |
| 43 |
.if (\n(rF:(\n(.g==0)) \{\ |
| 44 |
. if \nF \{\ |
| 45 |
. de IX |
| 46 |
. tm Index:\\$1\t\\n%\t"\\$2" |
| 47 |
.. |
| 48 |
. if !\nF==2 \{\ |
| 49 |
. nr % 0 |
| 50 |
. nr F 2 |
| 51 |
. \} |
| 52 |
. \} |
| 53 |
.\} |
| 54 |
.rr rF |
| 55 |
.\" ======================================================================== |
| 56 |
.\" |
| 57 |
.IX Title "Pod::Simple::Subclassing 3perl" |
| 58 |
.TH Pod::Simple::Subclassing 3perl 2025-11-16 "perl v5.40.1" "Perl Programmers Reference Guide" |
| 59 |
.\" For nroff, turn off justification. Always turn off hyphenation; it makes |
| 60 |
.\" way too many mistakes in technical documents. |
| 61 |
.if n .ad l |
| 62 |
.nh |
| 63 |
.SH NAME |
| 64 |
Pod::Simple::Subclassing \-\- write a formatter as a Pod::Simple subclass |
| 65 |
.SH SYNOPSIS |
| 66 |
.IX Header "SYNOPSIS" |
| 67 |
.Vb 5 |
| 68 |
\& package Pod::SomeFormatter; |
| 69 |
\& use Pod::Simple; |
| 70 |
\& @ISA = qw(Pod::Simple); |
| 71 |
\& $VERSION = \*(Aq1.01\*(Aq; |
| 72 |
\& use strict; |
| 73 |
\& |
| 74 |
\& sub _handle_element_start { |
| 75 |
\& my($parser, $element_name, $attr_hash_r) = @_; |
| 76 |
\& ... |
| 77 |
\& } |
| 78 |
\& |
| 79 |
\& sub _handle_element_end { |
| 80 |
\& my($parser, $element_name, $attr_hash_r) = @_; |
| 81 |
\& # NOTE: $attr_hash_r is only present when $element_name is "over" or "begin" |
| 82 |
\& # The remaining code excerpts will mostly ignore this $attr_hash_r, as it is |
| 83 |
\& # mostly useless. It is documented where "over\-*" and "begin" events are |
| 84 |
\& # documented. |
| 85 |
\& ... |
| 86 |
\& } |
| 87 |
\& |
| 88 |
\& sub _handle_text { |
| 89 |
\& my($parser, $text) = @_; |
| 90 |
\& ... |
| 91 |
\& } |
| 92 |
\& 1; |
| 93 |
.Ve |
| 94 |
.SH DESCRIPTION |
| 95 |
.IX Header "DESCRIPTION" |
| 96 |
This document is about using Pod::Simple to write a Pod processor, |
| 97 |
generally a Pod formatter. If you just want to know about using an |
| 98 |
existing Pod formatter, instead see its documentation and see also the |
| 99 |
docs in Pod::Simple. |
| 100 |
.PP |
| 101 |
\&\fBThe zeroeth step\fR in writing a Pod formatter is to make sure that there |
| 102 |
isn't already a decent one in CPAN. See <http://search.cpan.org/>, and |
| 103 |
run a search on the name of the format you want to render to. Also |
| 104 |
consider joining the Pod People list |
| 105 |
<http://lists.perl.org/showlist.cgi?name=pod\-people> and asking whether |
| 106 |
anyone has a formatter for that format \-\- maybe someone cobbled one |
| 107 |
together but just hasn't released it. |
| 108 |
.PP |
| 109 |
\&\fBThe first step\fR in writing a Pod processor is to read perlpodspec, |
| 110 |
which contains information on writing a Pod parser (which has been |
| 111 |
largely taken care of by Pod::Simple), but also a lot of requirements |
| 112 |
and recommendations for writing a formatter. |
| 113 |
.PP |
| 114 |
\&\fBThe second step\fR is to actually learn the format you're planning to |
| 115 |
format to \-\- or at least as much as you need to know to represent Pod, |
| 116 |
which probably isn't much. |
| 117 |
.PP |
| 118 |
\&\fBThe third step\fR is to pick which of Pod::Simple's interfaces you want to |
| 119 |
use: |
| 120 |
.IP Pod::Simple 4 |
| 121 |
.IX Item "Pod::Simple" |
| 122 |
The basic Pod::Simple interface that uses \f(CW_handle_element_start()\fR, |
| 123 |
\&\f(CW_handle_element_end()\fR and \f(CW_handle_text()\fR. |
| 124 |
.IP Pod::Simple::Methody 4 |
| 125 |
.IX Item "Pod::Simple::Methody" |
| 126 |
The Pod::Simple::Methody interface is event-based, similar to that of |
| 127 |
HTML::Parser or XML::Parser's "Handlers". |
| 128 |
.IP Pod::Simple::PullParser 4 |
| 129 |
.IX Item "Pod::Simple::PullParser" |
| 130 |
Pod::Simple::PullParser provides a token-stream interface, sort of |
| 131 |
like HTML::TokeParser's interface. |
| 132 |
.IP Pod::Simple::SimpleTree 4 |
| 133 |
.IX Item "Pod::Simple::SimpleTree" |
| 134 |
Pod::Simple::SimpleTree provides a simple tree interface, rather like |
| 135 |
XML::Parser's "Tree" interface. Users familiar with XML handling will |
| 136 |
be comfortable with this interface. Users interested in outputting XML, |
| 137 |
should look into the modules that produce an XML representation of the |
| 138 |
Pod stream, notably Pod::Simple::XMLOutStream; you can feed the output |
| 139 |
of such a class to whatever XML parsing system you are most at home with. |
| 140 |
.PP |
| 141 |
\&\fBThe last step\fR is to write your code based on how the events (or tokens, |
| 142 |
or tree-nodes, or the XML, or however you're parsing) will map to |
| 143 |
constructs in the output format. Also be sure to consider how to escape |
| 144 |
text nodes containing arbitrary text, and what to do with text |
| 145 |
nodes that represent preformatted text (from verbatim sections). |
| 146 |
.SH Events |
| 147 |
.IX Header "Events" |
| 148 |
TODO intro... mention that events are supplied for implicits, like for |
| 149 |
missing >'s |
| 150 |
.PP |
| 151 |
In the following section, we use XML to represent the event structure |
| 152 |
associated with a particular construct. That is, an opening tag |
| 153 |
represents the element start, the attributes of that opening tag are |
| 154 |
the attributes given to the callback, and the closing tag represents |
| 155 |
the end element. |
| 156 |
.PP |
| 157 |
Three callback methods must be supplied by a class extending |
| 158 |
Pod::Simple to receive the corresponding event: |
| 159 |
.ie n .IP """$parser\->_handle_element_start( \fIelement_name\fR, \fIattr_hashref\fR )""" 4 |
| 160 |
.el .IP "\f(CW$parser\->_handle_element_start( \fR\f(CIelement_name\fR\f(CW, \fR\f(CIattr_hashref\fR\f(CW )\fR" 4 |
| 161 |
.IX Item "$parser->_handle_element_start( element_name, attr_hashref )" |
| 162 |
.PD 0 |
| 163 |
.ie n .IP """$parser\->_handle_element_end( \fIelement_name\fR )""" 4 |
| 164 |
.el .IP "\f(CW$parser\->_handle_element_end( \fR\f(CIelement_name\fR\f(CW )\fR" 4 |
| 165 |
.IX Item "$parser->_handle_element_end( element_name )" |
| 166 |
.ie n .IP """$parser\->_handle_text( \fItext_string\fR )""" 4 |
| 167 |
.el .IP "\f(CW$parser\->_handle_text( \fR\f(CItext_string\fR\f(CW )\fR" 4 |
| 168 |
.IX Item "$parser->_handle_text( text_string )" |
| 169 |
.PD |
| 170 |
.PP |
| 171 |
Here's the comprehensive list of values you can expect as |
| 172 |
\&\fIelement_name\fR in your implementation of \f(CW\*(C`_handle_element_start\*(C'\fR |
| 173 |
and \f(CW\*(C`_handle_element_end\*(C'\fR:: |
| 174 |
.IP "events with an element_name of Document" 4 |
| 175 |
.IX Item "events with an element_name of Document" |
| 176 |
Parsing a document produces this event structure: |
| 177 |
.Sp |
| 178 |
.Vb 3 |
| 179 |
\& <Document start_line="543"> |
| 180 |
\& ...all events... |
| 181 |
\& </Document> |
| 182 |
.Ve |
| 183 |
.Sp |
| 184 |
The value of the \fIstart_line\fR attribute will be the line number of the first |
| 185 |
Pod directive in the document. |
| 186 |
.Sp |
| 187 |
If there is no Pod in the given document, then the |
| 188 |
event structure will be this: |
| 189 |
.Sp |
| 190 |
.Vb 2 |
| 191 |
\& <Document contentless="1" start_line="543"> |
| 192 |
\& </Document> |
| 193 |
.Ve |
| 194 |
.Sp |
| 195 |
In that case, the value of the \fIstart_line\fR attribute will not be meaningful; |
| 196 |
under current implementations, it will probably be the line number of the |
| 197 |
last line in the file. |
| 198 |
.IP "events with an element_name of Para" 4 |
| 199 |
.IX Item "events with an element_name of Para" |
| 200 |
Parsing a plain (non-verbatim, non-directive, non-data) paragraph in |
| 201 |
a Pod document produces this event structure: |
| 202 |
.Sp |
| 203 |
.Vb 3 |
| 204 |
\& <Para start_line="543"> |
| 205 |
\& ...all events in this paragraph... |
| 206 |
\& </Para> |
| 207 |
.Ve |
| 208 |
.Sp |
| 209 |
The value of the \fIstart_line\fR attribute will be the line number of the start |
| 210 |
of the paragraph. |
| 211 |
.Sp |
| 212 |
For example, parsing this paragraph of Pod: |
| 213 |
.Sp |
| 214 |
.Vb 2 |
| 215 |
\& The value of the I<start_line> attribute will be the |
| 216 |
\& line number of the start of the paragraph. |
| 217 |
.Ve |
| 218 |
.Sp |
| 219 |
produces this event structure: |
| 220 |
.Sp |
| 221 |
.Vb 8 |
| 222 |
\& <Para start_line="129"> |
| 223 |
\& The value of the |
| 224 |
\& <I> |
| 225 |
\& start_line |
| 226 |
\& </I> |
| 227 |
\& attribute will be the line number of the first Pod directive |
| 228 |
\& in the document. |
| 229 |
\& </Para> |
| 230 |
.Ve |
| 231 |
.IP "events with an element_name of B, C, F, or I." 4 |
| 232 |
.IX Item "events with an element_name of B, C, F, or I." |
| 233 |
Parsing a B<...> formatting code (or of course any of its |
| 234 |
semantically identical syntactic variants |
| 235 |
B<<\ ...\ >>, |
| 236 |
or B<<<<\ ...\ >>>>, etc.) |
| 237 |
produces this event structure: |
| 238 |
.Sp |
| 239 |
.Vb 3 |
| 240 |
\& <B> |
| 241 |
\& ...stuff... |
| 242 |
\& </B> |
| 243 |
.Ve |
| 244 |
.Sp |
| 245 |
Currently, there are no attributes conveyed. |
| 246 |
.Sp |
| 247 |
Parsing C, F, or I codes produce the same structure, with only a |
| 248 |
different element name. |
| 249 |
.Sp |
| 250 |
If your parser object has been set to accept other formatting codes, |
| 251 |
then they will be presented like these B/C/F/I codes \-\- i.e., without |
| 252 |
any attributes. |
| 253 |
.IP "events with an element_name of S" 4 |
| 254 |
.IX Item "events with an element_name of S" |
| 255 |
Normally, parsing an S<...> sequence produces this event |
| 256 |
structure, just as if it were a B/C/F/I code: |
| 257 |
.Sp |
| 258 |
.Vb 3 |
| 259 |
\& <S> |
| 260 |
\& ...stuff... |
| 261 |
\& </S> |
| 262 |
.Ve |
| 263 |
.Sp |
| 264 |
However, Pod::Simple (and presumably all derived parsers) offers the |
| 265 |
\&\f(CW\*(C`nbsp_for_S\*(C'\fR option which, if enabled, will suppress all S events, and |
| 266 |
instead change all spaces in the content to non-breaking spaces. This is |
| 267 |
intended for formatters that output to a format that has no code that |
| 268 |
means the same as S<...>, but which has a code/character that |
| 269 |
means non-breaking space. |
| 270 |
.IP "events with an element_name of X" 4 |
| 271 |
.IX Item "events with an element_name of X" |
| 272 |
Normally, parsing an X<...> sequence produces this event |
| 273 |
structure, just as if it were a B/C/F/I code: |
| 274 |
.Sp |
| 275 |
.Vb 3 |
| 276 |
\& <X> |
| 277 |
\& ...stuff... |
| 278 |
\& </X> |
| 279 |
.Ve |
| 280 |
.Sp |
| 281 |
However, Pod::Simple (and presumably all derived parsers) offers the |
| 282 |
\&\f(CW\*(C`nix_X_codes\*(C'\fR option which, if enabled, will suppress all X events |
| 283 |
and ignore their content. For formatters/processors that don't use |
| 284 |
X events, this is presumably quite useful. |
| 285 |
.IP "events with an element_name of L" 4 |
| 286 |
.IX Item "events with an element_name of L" |
| 287 |
Because the L<...> is the most complex construct in the |
| 288 |
language, it should not surprise you that the events it generates are |
| 289 |
the most complex in the language. Most of complexity is hidden away in |
| 290 |
the attribute values, so for those of you writing a Pod formatter that |
| 291 |
produces a non-hypertextual format, you can just ignore the attributes |
| 292 |
and treat an L event structure like a formatting element that |
| 293 |
(presumably) doesn't actually produce a change in formatting. That is, |
| 294 |
the content of the L event structure (as opposed to its |
| 295 |
attributes) is always what text should be displayed. |
| 296 |
.Sp |
| 297 |
There are, at first glance, three kinds of L links: URL, man, and pod. |
| 298 |
.Sp |
| 299 |
When a L<\fIsome_url\fR> code is parsed, it produces this event |
| 300 |
structure: |
| 301 |
.Sp |
| 302 |
.Vb 3 |
| 303 |
\& <L content\-implicit="yes" raw="that_url" to="that_url" type="url"> |
| 304 |
\& that_url |
| 305 |
\& </L> |
| 306 |
.Ve |
| 307 |
.Sp |
| 308 |
The \f(CW\*(C`type="url"\*(C'\fR attribute is always specified for this type of |
| 309 |
L code. |
| 310 |
.Sp |
| 311 |
For example, this Pod source: |
| 312 |
.Sp |
| 313 |
.Vb 1 |
| 314 |
\& L<http://www.perl.com/CPAN/authors/> |
| 315 |
.Ve |
| 316 |
.Sp |
| 317 |
produces this event structure: |
| 318 |
.Sp |
| 319 |
.Vb 3 |
| 320 |
\& <L content\-implicit="yes" raw="http://www.perl.com/CPAN/authors/" to="http://www.perl.com/CPAN/authors/" type="url"> |
| 321 |
\& http://www.perl.com/CPAN/authors/ |
| 322 |
\& </L> |
| 323 |
.Ve |
| 324 |
.Sp |
| 325 |
When a L<\fImanpage(section)\fR> code is parsed (and these are |
| 326 |
fairly rare and not terribly useful), it produces this event structure: |
| 327 |
.Sp |
| 328 |
.Vb 3 |
| 329 |
\& <L content\-implicit="yes" raw="manpage(section)" to="manpage(section)" type="man"> |
| 330 |
\& manpage(section) |
| 331 |
\& </L> |
| 332 |
.Ve |
| 333 |
.Sp |
| 334 |
The \f(CW\*(C`type="man"\*(C'\fR attribute is always specified for this type of |
| 335 |
L code. |
| 336 |
.Sp |
| 337 |
For example, this Pod source: |
| 338 |
.Sp |
| 339 |
.Vb 1 |
| 340 |
\& L<crontab(5)> |
| 341 |
.Ve |
| 342 |
.Sp |
| 343 |
produces this event structure: |
| 344 |
.Sp |
| 345 |
.Vb 3 |
| 346 |
\& <L content\-implicit="yes" raw="crontab(5)" to="crontab(5)" type="man"> |
| 347 |
\& crontab(5) |
| 348 |
\& </L> |
| 349 |
.Ve |
| 350 |
.Sp |
| 351 |
In the rare cases where a man page link has a section specified, that text appears |
| 352 |
in a \fIsection\fR attribute. For example, this Pod source: |
| 353 |
.Sp |
| 354 |
.Vb 1 |
| 355 |
\& L<crontab(5)/"ENVIRONMENT"> |
| 356 |
.Ve |
| 357 |
.Sp |
| 358 |
will produce this event structure: |
| 359 |
.Sp |
| 360 |
.Vb 3 |
| 361 |
\& <L content\-implicit="yes" raw="crontab(5)/"ENVIRONMENT"" section="ENVIRONMENT" to="crontab(5)" type="man"> |
| 362 |
\& "ENVIRONMENT" in crontab(5) |
| 363 |
\& </L> |
| 364 |
.Ve |
| 365 |
.Sp |
| 366 |
In the rare case where the Pod document has code like |
| 367 |
L<\fIsometext\fR|\fImanpage(section)\fR>, then the \fIsometext\fR will appear |
| 368 |
as the content of the element, the \fImanpage(section)\fR text will appear |
| 369 |
only as the value of the \fIto\fR attribute, and there will be no |
| 370 |
\&\f(CW\*(C`content\-implicit="yes"\*(C'\fR attribute (whose presence means that the Pod parser |
| 371 |
had to infer what text should appear as the link text \-\- as opposed to |
| 372 |
cases where that attribute is absent, which means that the Pod parser did |
| 373 |
\&\fInot\fR have to infer the link text, because that L code explicitly specified |
| 374 |
some link text.) |
| 375 |
.Sp |
| 376 |
For example, this Pod source: |
| 377 |
.Sp |
| 378 |
.Vb 1 |
| 379 |
\& L<hell itself!|crontab(5)> |
| 380 |
.Ve |
| 381 |
.Sp |
| 382 |
will produce this event structure: |
| 383 |
.Sp |
| 384 |
.Vb 3 |
| 385 |
\& <L raw="hell itself!|crontab(5)" to="crontab(5)" type="man"> |
| 386 |
\& hell itself! |
| 387 |
\& </L> |
| 388 |
.Ve |
| 389 |
.Sp |
| 390 |
The last type of L structure is for links to/within Pod documents. It is |
| 391 |
the most complex because it can have a \fIto\fR attribute, \fIor\fR a |
| 392 |
\&\fIsection\fR attribute, or both. The \f(CW\*(C`type="pod"\*(C'\fR attribute is always |
| 393 |
specified for this type of L code. |
| 394 |
.Sp |
| 395 |
In the most common case, the simple case of a L<podpage> code |
| 396 |
produces this event structure: |
| 397 |
.Sp |
| 398 |
.Vb 3 |
| 399 |
\& <L content\-implicit="yes" raw="podpage" to="podpage" type="pod"> |
| 400 |
\& podpage |
| 401 |
\& </L> |
| 402 |
.Ve |
| 403 |
.Sp |
| 404 |
For example, this Pod source: |
| 405 |
.Sp |
| 406 |
.Vb 1 |
| 407 |
\& L<Net::Ping> |
| 408 |
.Ve |
| 409 |
.Sp |
| 410 |
produces this event structure: |
| 411 |
.Sp |
| 412 |
.Vb 3 |
| 413 |
\& <L content\-implicit="yes" raw="Net::Ping" to="Net::Ping" type="pod"> |
| 414 |
\& Net::Ping |
| 415 |
\& </L> |
| 416 |
.Ve |
| 417 |
.Sp |
| 418 |
In cases where there is link-text explicitly specified, it |
| 419 |
is to be found in the content of the element (and not the |
| 420 |
attributes), just as with the L<\fIsometext\fR|\fImanpage(section)\fR> |
| 421 |
case discussed above. For example, this Pod source: |
| 422 |
.Sp |
| 423 |
.Vb 1 |
| 424 |
\& L<Perl Error Messages|perldiag> |
| 425 |
.Ve |
| 426 |
.Sp |
| 427 |
produces this event structure: |
| 428 |
.Sp |
| 429 |
.Vb 3 |
| 430 |
\& <L raw="Perl Error Messages|perldiag" to="perldiag" type="pod"> |
| 431 |
\& Perl Error Messages |
| 432 |
\& </L> |
| 433 |
.Ve |
| 434 |
.Sp |
| 435 |
In cases of links to a section in the current Pod document, |
| 436 |
there is a \fIsection\fR attribute instead of a \fIto\fR attribute. |
| 437 |
For example, this Pod source: |
| 438 |
.Sp |
| 439 |
.Vb 1 |
| 440 |
\& L</"Member Data"> |
| 441 |
.Ve |
| 442 |
.Sp |
| 443 |
produces this event structure: |
| 444 |
.Sp |
| 445 |
.Vb 3 |
| 446 |
\& <L content\-implicit="yes" raw="/"Member Data"" section="Member Data" type="pod"> |
| 447 |
\& "Member Data" |
| 448 |
\& </L> |
| 449 |
.Ve |
| 450 |
.Sp |
| 451 |
As another example, this Pod source: |
| 452 |
.Sp |
| 453 |
.Vb 1 |
| 454 |
\& L<the various attributes|/"Member Data"> |
| 455 |
.Ve |
| 456 |
.Sp |
| 457 |
produces this event structure: |
| 458 |
.Sp |
| 459 |
.Vb 3 |
| 460 |
\& <L raw="the various attributes|/"Member Data"" section="Member Data" type="pod"> |
| 461 |
\& the various attributes |
| 462 |
\& </L> |
| 463 |
.Ve |
| 464 |
.Sp |
| 465 |
In cases of links to a section in a different Pod document, |
| 466 |
there are both a \fIsection\fR attribute and a to attribute. |
| 467 |
For example, this Pod source: |
| 468 |
.Sp |
| 469 |
.Vb 1 |
| 470 |
\& L<perlsyn/"Basic BLOCKs and Switch Statements"> |
| 471 |
.Ve |
| 472 |
.Sp |
| 473 |
produces this event structure: |
| 474 |
.Sp |
| 475 |
.Vb 3 |
| 476 |
\& <L content\-implicit="yes" raw="perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> |
| 477 |
\& "Basic BLOCKs and Switch Statements" in perlsyn |
| 478 |
\& </L> |
| 479 |
.Ve |
| 480 |
.Sp |
| 481 |
As another example, this Pod source: |
| 482 |
.Sp |
| 483 |
.Vb 1 |
| 484 |
\& L<SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"> |
| 485 |
.Ve |
| 486 |
.Sp |
| 487 |
produces this event structure: |
| 488 |
.Sp |
| 489 |
.Vb 3 |
| 490 |
\& <L raw="SWITCH statements|perlsyn/"Basic BLOCKs and Switch Statements"" section="Basic BLOCKs and Switch Statements" to="perlsyn" type="pod"> |
| 491 |
\& SWITCH statements |
| 492 |
\& </L> |
| 493 |
.Ve |
| 494 |
.Sp |
| 495 |
Incidentally, note that we do not distinguish between these syntaxes: |
| 496 |
.Sp |
| 497 |
.Vb 4 |
| 498 |
\& L</"Member Data"> |
| 499 |
\& L<"Member Data"> |
| 500 |
\& L</Member Data> |
| 501 |
\& L<Member Data> [deprecated syntax] |
| 502 |
.Ve |
| 503 |
.Sp |
| 504 |
That is, they all produce the same event structure (for the most part), namely: |
| 505 |
.Sp |
| 506 |
.Vb 3 |
| 507 |
\& <L content\-implicit="yes" raw="$depends_on_syntax" section="Member Data" type="pod"> |
| 508 |
\& "Member Data" |
| 509 |
\& </L> |
| 510 |
.Ve |
| 511 |
.Sp |
| 512 |
The \fIraw\fR attribute depends on what the raw content of the \f(CW\*(C`L<>\*(C'\fR is, |
| 513 |
so that is why the event structure is the same "for the most part". |
| 514 |
.Sp |
| 515 |
If you have not guessed it yet, the \fIraw\fR attribute contains the raw, |
| 516 |
original, unescaped content of the \f(CW\*(C`L<>\*(C'\fR formatting code. In addition |
| 517 |
to the examples above, take notice of the following event structure produced |
| 518 |
by the following \f(CW\*(C`L<>\*(C'\fR formatting code. |
| 519 |
.Sp |
| 520 |
.Vb 1 |
| 521 |
\& L<click B<here>|page/About the C<\-M> switch> |
| 522 |
\& |
| 523 |
\& <L raw="click B<here>|page/About the C<\-M> switch" section="About the \-M switch" to="page" type="pod"> |
| 524 |
\& click B<here> |
| 525 |
\& </L> |
| 526 |
.Ve |
| 527 |
.Sp |
| 528 |
Specifically, notice that the formatting codes are present and unescaped |
| 529 |
in \fIraw\fR. |
| 530 |
.Sp |
| 531 |
There is a known bug in the \fIraw\fR attribute where any surrounding whitespace |
| 532 |
is condensed into a single ' '. For example, given L< link>, \fIraw\fR |
| 533 |
will be " link". |
| 534 |
.IP "events with an element_name of E or Z" 4 |
| 535 |
.IX Item "events with an element_name of E or Z" |
| 536 |
While there are Pod codes E<...> and Z<>, these |
| 537 |
\&\fIdo not\fR produce any E or Z events \-\- that is, there are no such |
| 538 |
events as E or Z. |
| 539 |
.IP "events with an element_name of Verbatim" 4 |
| 540 |
.IX Item "events with an element_name of Verbatim" |
| 541 |
When a Pod verbatim paragraph (AKA "codeblock") is parsed, it |
| 542 |
produces this event structure: |
| 543 |
.Sp |
| 544 |
.Vb 3 |
| 545 |
\& <Verbatim start_line="543" xml:space="preserve"> |
| 546 |
\& ...text... |
| 547 |
\& </Verbatim> |
| 548 |
.Ve |
| 549 |
.Sp |
| 550 |
The value of the \fIstart_line\fR attribute will be the line number of the |
| 551 |
first line of this verbatim block. The \fIxml:space\fR attribute is always |
| 552 |
present, and always has the value "preserve". |
| 553 |
.Sp |
| 554 |
The text content will have tabs already expanded. |
| 555 |
.IP "events with an element_name of head1 .. head4" 4 |
| 556 |
.IX Item "events with an element_name of head1 .. head4" |
| 557 |
When a "=head1 ..." directive is parsed, it produces this event |
| 558 |
structure: |
| 559 |
.Sp |
| 560 |
.Vb 3 |
| 561 |
\& <head1> |
| 562 |
\& ...stuff... |
| 563 |
\& </head1> |
| 564 |
.Ve |
| 565 |
.Sp |
| 566 |
For example, a directive consisting of this: |
| 567 |
.Sp |
| 568 |
.Vb 1 |
| 569 |
\& =head1 Options to C<new> et al. |
| 570 |
.Ve |
| 571 |
.Sp |
| 572 |
will produce this event structure: |
| 573 |
.Sp |
| 574 |
.Vb 7 |
| 575 |
\& <head1 start_line="543"> |
| 576 |
\& Options to |
| 577 |
\& <C> |
| 578 |
\& new |
| 579 |
\& </C> |
| 580 |
\& et al. |
| 581 |
\& </head1> |
| 582 |
.Ve |
| 583 |
.Sp |
| 584 |
"=head2" through "=head4" directives are the same, except for the element |
| 585 |
names in the event structure. |
| 586 |
.IP "events with an element_name of encoding" 4 |
| 587 |
.IX Item "events with an element_name of encoding" |
| 588 |
In the default case, the events corresponding to \f(CW\*(C`=encoding\*(C'\fR directives |
| 589 |
are not emitted. They are emitted if \f(CW\*(C`keep_encoding_directive\*(C'\fR is true. |
| 590 |
In that case they produce event structures like |
| 591 |
"events with an element_name of head1 .. head4" above. |
| 592 |
.IP "events with an element_name of over-bullet" 4 |
| 593 |
.IX Item "events with an element_name of over-bullet" |
| 594 |
When an "=over ... =back" block is parsed where the items are |
| 595 |
a bulleted list, it will produce this event structure: |
| 596 |
.Sp |
| 597 |
.Vb 6 |
| 598 |
\& <over\-bullet indent="4" start_line="543"> |
| 599 |
\& <item\-bullet start_line="545"> |
| 600 |
\& ...Stuff... |
| 601 |
\& </item\-bullet> |
| 602 |
\& ...more item\-bullets... |
| 603 |
\& </over\-bullet fake\-closer="1"> |
| 604 |
.Ve |
| 605 |
.Sp |
| 606 |
The attribute \fIfake-closer\fR is only present if it is a true value; it is not |
| 607 |
present if it is a false value. It is shown in the above example to illustrate |
| 608 |
where the attribute is (in the \fBclosing\fR tag). It signifies that the \f(CW\*(C`=over\*(C'\fR |
| 609 |
did not have a matching \f(CW\*(C`=back\*(C'\fR, and thus Pod::Simple had to create a fake |
| 610 |
closer. |
| 611 |
.Sp |
| 612 |
For example, this Pod source: |
| 613 |
.Sp |
| 614 |
.Vb 1 |
| 615 |
\& =over |
| 616 |
\& |
| 617 |
\& =item * |
| 618 |
\& |
| 619 |
\& Something |
| 620 |
\& |
| 621 |
\& =back |
| 622 |
.Ve |
| 623 |
.Sp |
| 624 |
Would produce an event structure that does \fBnot\fR have the \fIfake-closer\fR |
| 625 |
attribute, whereas this Pod source: |
| 626 |
.Sp |
| 627 |
.Vb 1 |
| 628 |
\& =over |
| 629 |
\& |
| 630 |
\& =item * |
| 631 |
\& |
| 632 |
\& Gasp! An unclosed =over block! |
| 633 |
.Ve |
| 634 |
.Sp |
| 635 |
would. The rest of the over\-* examples will not demonstrate this attribute, |
| 636 |
but they all can have it. See Pod::Checker's source for an example of this |
| 637 |
attribute being used. |
| 638 |
.Sp |
| 639 |
The value of the \fIindent\fR attribute is whatever value is after the |
| 640 |
"=over" directive, as in "=over 8". If no such value is specified |
| 641 |
in the directive, then the \fIindent\fR attribute has the value "4". |
| 642 |
.Sp |
| 643 |
For example, this Pod source: |
| 644 |
.Sp |
| 645 |
.Vb 1 |
| 646 |
\& =over |
| 647 |
\& |
| 648 |
\& =item * |
| 649 |
\& |
| 650 |
\& Stuff |
| 651 |
\& |
| 652 |
\& =item * |
| 653 |
\& |
| 654 |
\& Bar I<baz>! |
| 655 |
\& |
| 656 |
\& =back |
| 657 |
.Ve |
| 658 |
.Sp |
| 659 |
produces this event structure: |
| 660 |
.Sp |
| 661 |
.Vb 8 |
| 662 |
\& <over\-bullet indent="4" start_line="10"> |
| 663 |
\& <item\-bullet start_line="12"> |
| 664 |
\& Stuff |
| 665 |
\& </item\-bullet> |
| 666 |
\& <item\-bullet start_line="14"> |
| 667 |
\& Bar <I>baz</I>! |
| 668 |
\& </item\-bullet> |
| 669 |
\& </over\-bullet> |
| 670 |
.Ve |
| 671 |
.IP "events with an element_name of over-number" 4 |
| 672 |
.IX Item "events with an element_name of over-number" |
| 673 |
When an "=over ... =back" block is parsed where the items are |
| 674 |
a numbered list, it will produce this event structure: |
| 675 |
.Sp |
| 676 |
.Vb 6 |
| 677 |
\& <over\-number indent="4" start_line="543"> |
| 678 |
\& <item\-number number="1" start_line="545"> |
| 679 |
\& ...Stuff... |
| 680 |
\& </item\-number> |
| 681 |
\& ...more item\-number... |
| 682 |
\& </over\-bullet> |
| 683 |
.Ve |
| 684 |
.Sp |
| 685 |
This is like the "over-bullet" event structure; but note that the contents |
| 686 |
are "item-number" instead of "item-bullet", and note that they will have |
| 687 |
a "number" attribute, which some formatters/processors may ignore |
| 688 |
(since, for example, there's no need for it in HTML when producing |
| 689 |
an "<UL><LI>...</LI>...</UL>" structure), but which any processor may use. |
| 690 |
.Sp |
| 691 |
Note that the values for the \fInumber\fR attributes of "item-number" |
| 692 |
elements in a given "over-number" area \fIwill\fR start at 1 and go up by |
| 693 |
one each time. If the Pod source doesn't follow that order (even though |
| 694 |
it really should!), whatever numbers it has will be ignored (with |
| 695 |
the correct values being put in the \fInumber\fR attributes), and an error |
| 696 |
message might be issued to the user. |
| 697 |
.IP "events with an element_name of over-text" 4 |
| 698 |
.IX Item "events with an element_name of over-text" |
| 699 |
These events are somewhat unlike the other over\-* |
| 700 |
structures, as far as what their contents are. When |
| 701 |
an "=over ... =back" block is parsed where the items are |
| 702 |
a list of text "subheadings", it will produce this event structure: |
| 703 |
.Sp |
| 704 |
.Vb 8 |
| 705 |
\& <over\-text indent="4" start_line="543"> |
| 706 |
\& <item\-text> |
| 707 |
\& ...stuff... |
| 708 |
\& </item\-text> |
| 709 |
\& ...stuff (generally Para or Verbatim elements)... |
| 710 |
\& <item\-text> |
| 711 |
\& ...more item\-text and/or stuff... |
| 712 |
\& </over\-text> |
| 713 |
.Ve |
| 714 |
.Sp |
| 715 |
The \fIindent\fR and \fIfake-closer\fR attributes are as with the other over\-* events. |
| 716 |
.Sp |
| 717 |
For example, this Pod source: |
| 718 |
.Sp |
| 719 |
.Vb 1 |
| 720 |
\& =over |
| 721 |
\& |
| 722 |
\& =item Foo |
| 723 |
\& |
| 724 |
\& Stuff |
| 725 |
\& |
| 726 |
\& =item Bar I<baz>! |
| 727 |
\& |
| 728 |
\& Quux |
| 729 |
\& |
| 730 |
\& =back |
| 731 |
.Ve |
| 732 |
.Sp |
| 733 |
produces this event structure: |
| 734 |
.Sp |
| 735 |
.Vb 10 |
| 736 |
\& <over\-text indent="4" start_line="20"> |
| 737 |
\& <item\-text start_line="22"> |
| 738 |
\& Foo |
| 739 |
\& </item\-text> |
| 740 |
\& <Para start_line="24"> |
| 741 |
\& Stuff |
| 742 |
\& </Para> |
| 743 |
\& <item\-text start_line="26"> |
| 744 |
\& Bar |
| 745 |
\& <I> |
| 746 |
\& baz |
| 747 |
\& </I> |
| 748 |
\& ! |
| 749 |
\& </item\-text> |
| 750 |
\& <Para start_line="28"> |
| 751 |
\& Quux |
| 752 |
\& </Para> |
| 753 |
\& </over\-text> |
| 754 |
.Ve |
| 755 |
.IP "events with an element_name of over-block" 4 |
| 756 |
.IX Item "events with an element_name of over-block" |
| 757 |
These events are somewhat unlike the other over\-* |
| 758 |
structures, as far as what their contents are. When |
| 759 |
an "=over ... =back" block is parsed where there are no items, |
| 760 |
it will produce this event structure: |
| 761 |
.Sp |
| 762 |
.Vb 3 |
| 763 |
\& <over\-block indent="4" start_line="543"> |
| 764 |
\& ...stuff (generally Para or Verbatim elements)... |
| 765 |
\& </over\-block> |
| 766 |
.Ve |
| 767 |
.Sp |
| 768 |
The \fIindent\fR and \fIfake-closer\fR attributes are as with the other over\-* events. |
| 769 |
.Sp |
| 770 |
For example, this Pod source: |
| 771 |
.Sp |
| 772 |
.Vb 1 |
| 773 |
\& =over |
| 774 |
\& |
| 775 |
\& For cutting off our trade with all parts of the world |
| 776 |
\& |
| 777 |
\& For transporting us beyond seas to be tried for pretended offenses |
| 778 |
\& |
| 779 |
\& He is at this time transporting large armies of foreign mercenaries to |
| 780 |
\& complete the works of death, desolation and tyranny, already begun with |
| 781 |
\& circumstances of cruelty and perfidy scarcely paralleled in the most |
| 782 |
\& barbarous ages, and totally unworthy the head of a civilized nation. |
| 783 |
\& |
| 784 |
\& =back |
| 785 |
.Ve |
| 786 |
.Sp |
| 787 |
will produce this event structure: |
| 788 |
.Sp |
| 789 |
.Vb 11 |
| 790 |
\& <over\-block indent="4" start_line="2"> |
| 791 |
\& <Para start_line="4"> |
| 792 |
\& For cutting off our trade with all parts of the world |
| 793 |
\& </Para> |
| 794 |
\& <Para start_line="6"> |
| 795 |
\& For transporting us beyond seas to be tried for pretended offenses |
| 796 |
\& </Para> |
| 797 |
\& <Para start_line="8"> |
| 798 |
\& He is at this time transporting large armies of [...more text...] |
| 799 |
\& </Para> |
| 800 |
\& </over\-block> |
| 801 |
.Ve |
| 802 |
.IP "events with an element_name of over-empty" 4 |
| 803 |
.IX Item "events with an element_name of over-empty" |
| 804 |
\&\fBNote: These events are only triggered if \fR\f(CBparse_empty_lists()\fR\fB is set to a |
| 805 |
true value.\fR |
| 806 |
.Sp |
| 807 |
These events are somewhat unlike the other over\-* structures, as far as what |
| 808 |
their contents are. When an "=over ... =back" block is parsed where there |
| 809 |
is no content, it will produce this event structure: |
| 810 |
.Sp |
| 811 |
.Vb 2 |
| 812 |
\& <over\-empty indent="4" start_line="543"> |
| 813 |
\& </over\-empty> |
| 814 |
.Ve |
| 815 |
.Sp |
| 816 |
The \fIindent\fR and \fIfake-closer\fR attributes are as with the other over\-* events. |
| 817 |
.Sp |
| 818 |
For example, this Pod source: |
| 819 |
.Sp |
| 820 |
.Vb 1 |
| 821 |
\& =over |
| 822 |
\& |
| 823 |
\& =over |
| 824 |
\& |
| 825 |
\& =back |
| 826 |
\& |
| 827 |
\& =back |
| 828 |
.Ve |
| 829 |
.Sp |
| 830 |
will produce this event structure: |
| 831 |
.Sp |
| 832 |
.Vb 4 |
| 833 |
\& <over\-block indent="4" start_line="1"> |
| 834 |
\& <over\-empty indent="4" start_line="3"> |
| 835 |
\& </over\-empty> |
| 836 |
\& </over\-block> |
| 837 |
.Ve |
| 838 |
.Sp |
| 839 |
Note that the outer \f(CW\*(C`=over\*(C'\fR is a block because it has no \f(CW\*(C`=item\*(C'\fRs but still |
| 840 |
has content: the inner \f(CW\*(C`=over\*(C'\fR. The inner \f(CW\*(C`=over\*(C'\fR, in turn, is completely |
| 841 |
empty, and is treated as such. |
| 842 |
.IP "events with an element_name of item-bullet" 4 |
| 843 |
.IX Item "events with an element_name of item-bullet" |
| 844 |
See "events with an element_name of over-bullet", above. |
| 845 |
.IP "events with an element_name of item-number" 4 |
| 846 |
.IX Item "events with an element_name of item-number" |
| 847 |
See "events with an element_name of over-number", above. |
| 848 |
.IP "events with an element_name of item-text" 4 |
| 849 |
.IX Item "events with an element_name of item-text" |
| 850 |
See "events with an element_name of over-text", above. |
| 851 |
.IP "events with an element_name of for" 4 |
| 852 |
.IX Item "events with an element_name of for" |
| 853 |
TODO... |
| 854 |
.IP "events with an element_name of Data" 4 |
| 855 |
.IX Item "events with an element_name of Data" |
| 856 |
TODO... |
| 857 |
.SH "More Pod::Simple Methods" |
| 858 |
.IX Header "More Pod::Simple Methods" |
| 859 |
Pod::Simple provides a lot of methods that aren't generally interesting |
| 860 |
to the end user of an existing Pod formatter, but some of which you |
| 861 |
might find useful in writing a Pod formatter. They are listed below. The |
| 862 |
first several methods (the accept_* methods) are for declaring the |
| 863 |
capabilities of your parser, notably what \f(CW\*(C`=for \fR\f(CItargetname\fR\f(CW\*(C'\fR sections |
| 864 |
it's interested in, what extra N<...> codes it accepts beyond |
| 865 |
the ones described in the \fIperlpod\fR. |
| 866 |
.ie n .IP """$parser\->accept_targets( \fISOMEVALUE\fR )""" 4 |
| 867 |
.el .IP "\f(CW$parser\->accept_targets( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 868 |
.IX Item "$parser->accept_targets( SOMEVALUE )" |
| 869 |
As the parser sees sections like: |
| 870 |
.Sp |
| 871 |
.Vb 1 |
| 872 |
\& =for html <img src="fig1.jpg"> |
| 873 |
.Ve |
| 874 |
.Sp |
| 875 |
or |
| 876 |
.Sp |
| 877 |
.Vb 1 |
| 878 |
\& =begin html |
| 879 |
\& |
| 880 |
\& <img src="fig1.jpg"> |
| 881 |
\& |
| 882 |
\& =end html |
| 883 |
.Ve |
| 884 |
.Sp |
| 885 |
\&...the parser will ignore these sections unless your subclass has |
| 886 |
specified that it wants to see sections targeted to "html" (or whatever |
| 887 |
the formatter name is). |
| 888 |
.Sp |
| 889 |
If you want to process all sections, even if they're not targeted for you, |
| 890 |
call this before you start parsing: |
| 891 |
.Sp |
| 892 |
.Vb 1 |
| 893 |
\& $parser\->accept_targets(\*(Aq*\*(Aq); |
| 894 |
.Ve |
| 895 |
.ie n .IP """$parser\->accept_targets_as_text( \fISOMEVALUE\fR )""" 4 |
| 896 |
.el .IP "\f(CW$parser\->accept_targets_as_text( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 897 |
.IX Item "$parser->accept_targets_as_text( SOMEVALUE )" |
| 898 |
This is like accept_targets, except that it specifies also that the |
| 899 |
content of sections for this target should be treated as Pod text even |
| 900 |
if the target name in "=for \fItargetname\fR" doesn't start with a ":". |
| 901 |
.Sp |
| 902 |
At time of writing, I don't think you'll need to use this. |
| 903 |
.ie n .IP """$parser\->accept_codes( \fICodename\fR, \fICodename\fR... )""" 4 |
| 904 |
.el .IP "\f(CW$parser\->accept_codes( \fR\f(CICodename\fR\f(CW, \fR\f(CICodename\fR\f(CW... )\fR" 4 |
| 905 |
.IX Item "$parser->accept_codes( Codename, Codename... )" |
| 906 |
This tells the parser that you accept additional formatting codes, |
| 907 |
beyond just the standard ones (I B C L F S X, plus the two weird ones |
| 908 |
you don't actually see in the parse tree, Z and E). For example, to also |
| 909 |
accept codes "N", "R", and "W": |
| 910 |
.Sp |
| 911 |
.Vb 1 |
| 912 |
\& $parser\->accept_codes( qw( N R W ) ); |
| 913 |
.Ve |
| 914 |
.Sp |
| 915 |
\&\fBTODO: document how this interacts with =extend, and long element names\fR |
| 916 |
.ie n .IP """$parser\->accept_directive_as_data( \fIdirective_name\fR )""" 4 |
| 917 |
.el .IP "\f(CW$parser\->accept_directive_as_data( \fR\f(CIdirective_name\fR\f(CW )\fR" 4 |
| 918 |
.IX Item "$parser->accept_directive_as_data( directive_name )" |
| 919 |
.PD 0 |
| 920 |
.ie n .IP """$parser\->accept_directive_as_verbatim( \fIdirective_name\fR )""" 4 |
| 921 |
.el .IP "\f(CW$parser\->accept_directive_as_verbatim( \fR\f(CIdirective_name\fR\f(CW )\fR" 4 |
| 922 |
.IX Item "$parser->accept_directive_as_verbatim( directive_name )" |
| 923 |
.ie n .IP """$parser\->accept_directive_as_processed( \fIdirective_name\fR )""" 4 |
| 924 |
.el .IP "\f(CW$parser\->accept_directive_as_processed( \fR\f(CIdirective_name\fR\f(CW )\fR" 4 |
| 925 |
.IX Item "$parser->accept_directive_as_processed( directive_name )" |
| 926 |
.PD |
| 927 |
In the unlikely situation that you need to tell the parser that you will |
| 928 |
accept additional directives ("=foo" things), you need to first set the |
| 929 |
parser to treat its content as data (i.e., not really processed at |
| 930 |
all), or as verbatim (mostly just expanding tabs), or as processed text |
| 931 |
(parsing formatting codes like B<...>). |
| 932 |
.Sp |
| 933 |
For example, to accept a new directive "=method", you'd presumably |
| 934 |
use: |
| 935 |
.Sp |
| 936 |
.Vb 1 |
| 937 |
\& $parser\->accept_directive_as_processed("method"); |
| 938 |
.Ve |
| 939 |
.Sp |
| 940 |
so that you could have Pod lines like: |
| 941 |
.Sp |
| 942 |
.Vb 1 |
| 943 |
\& =method I<$whatever> thing B<um> |
| 944 |
.Ve |
| 945 |
.Sp |
| 946 |
Making up your own directives breaks compatibility with other Pod |
| 947 |
formatters, in a way that using "=for \fItarget\fR ..." lines doesn't; |
| 948 |
however, you may find this useful if you're making a Pod superset |
| 949 |
format where you don't need to worry about compatibility. |
| 950 |
.ie n .IP """$parser\->nbsp_for_S( \fIBOOLEAN\fR );""" 4 |
| 951 |
.el .IP "\f(CW$parser\->nbsp_for_S( \fR\f(CIBOOLEAN\fR\f(CW );\fR" 4 |
| 952 |
.IX Item "$parser->nbsp_for_S( BOOLEAN );" |
| 953 |
Setting this attribute to a true value (and by default it is false) will |
| 954 |
turn "S<...>" sequences into sequences of words separated by |
| 955 |
\&\f(CW\*(C`\exA0\*(C'\fR (non-breaking space) characters. For example, it will take this: |
| 956 |
.Sp |
| 957 |
.Vb 1 |
| 958 |
\& I like S<Dutch apple pie>, don\*(Aqt you? |
| 959 |
.Ve |
| 960 |
.Sp |
| 961 |
and treat it as if it were: |
| 962 |
.Sp |
| 963 |
.Vb 1 |
| 964 |
\& I like DutchE<nbsp>appleE<nbsp>pie, don\*(Aqt you? |
| 965 |
.Ve |
| 966 |
.Sp |
| 967 |
This is handy for output formats that don't have anything quite like an |
| 968 |
"S<...>" code, but which do have a code for non-breaking space. |
| 969 |
.Sp |
| 970 |
There is currently no method for going the other way; but I can |
| 971 |
probably provide one upon request. |
| 972 |
.ie n .IP """$parser\->version_report()""" 4 |
| 973 |
.el .IP \f(CW$parser\->version_report()\fR 4 |
| 974 |
.IX Item "$parser->version_report()" |
| 975 |
This returns a string reporting the \f(CW$VERSION\fR value from your module (and |
| 976 |
its classname) as well as the \f(CW$VERSION\fR value of Pod::Simple. Note that |
| 977 |
perlpodspec requires output formats (wherever possible) to note |
| 978 |
this detail in a comment in the output format. For example, for |
| 979 |
some kind of SGML output format: |
| 980 |
.Sp |
| 981 |
.Vb 1 |
| 982 |
\& print OUT "<!\-\- \en", $parser\->version_report, "\en \-\->"; |
| 983 |
.Ve |
| 984 |
.ie n .IP """$parser\->pod_para_count()""" 4 |
| 985 |
.el .IP \f(CW$parser\->pod_para_count()\fR 4 |
| 986 |
.IX Item "$parser->pod_para_count()" |
| 987 |
This returns the count of Pod paragraphs seen so far. |
| 988 |
.ie n .IP """$parser\->line_count()""" 4 |
| 989 |
.el .IP \f(CW$parser\->line_count()\fR 4 |
| 990 |
.IX Item "$parser->line_count()" |
| 991 |
This is the current line number being parsed. But you might find the |
| 992 |
"line_number" event attribute more accurate, when it is present. |
| 993 |
.ie n .IP """$parser\->nix_X_codes( \fISOMEVALUE\fR )""" 4 |
| 994 |
.el .IP "\f(CW$parser\->nix_X_codes( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 995 |
.IX Item "$parser->nix_X_codes( SOMEVALUE )" |
| 996 |
This attribute, when set to a true value (and it is false by default) |
| 997 |
ignores any "X<...>" sequences in the document being parsed. |
| 998 |
Many formats don't actually use the content of these codes, so have |
| 999 |
no reason to process them. |
| 1000 |
.ie n .IP """$parser\->keep_encoding_directive( \fISOMEVALUE\fR )""" 4 |
| 1001 |
.el .IP "\f(CW$parser\->keep_encoding_directive( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1002 |
.IX Item "$parser->keep_encoding_directive( SOMEVALUE )" |
| 1003 |
This attribute, when set to a true value (it is false by default) |
| 1004 |
will keep \f(CW\*(C`=encoding\*(C'\fR and its content in the event structure. Most |
| 1005 |
formats don't actually need to process the content of an \f(CW\*(C`=encoding\*(C'\fR |
| 1006 |
directive, even when this directive sets the encoding and the |
| 1007 |
processor makes use of the encoding information. Indeed, it is |
| 1008 |
possible to know the encoding without processing the directive |
| 1009 |
content. |
| 1010 |
.ie n .IP """$parser\->merge_text( \fISOMEVALUE\fR )""" 4 |
| 1011 |
.el .IP "\f(CW$parser\->merge_text( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1012 |
.IX Item "$parser->merge_text( SOMEVALUE )" |
| 1013 |
This attribute, when set to a true value (and it is false by default) |
| 1014 |
makes sure that only one event (or token, or node) will be created |
| 1015 |
for any single contiguous sequence of text. For example, consider |
| 1016 |
this somewhat contrived example: |
| 1017 |
.Sp |
| 1018 |
.Vb 1 |
| 1019 |
\& I just LOVE Z<>hotE<32>apple pie! |
| 1020 |
.Ve |
| 1021 |
.Sp |
| 1022 |
When that is parsed and events are about to be called on it, it may |
| 1023 |
actually seem to be four different text events, one right after another: |
| 1024 |
one event for "I just LOVE ", one for "hot", one for " ", and one for |
| 1025 |
"apple pie!". But if you have merge_text on, then you're guaranteed |
| 1026 |
that it will be fired as one text event: "I just LOVE hot apple pie!". |
| 1027 |
.ie n .IP """$parser\->code_handler( \fICODE_REF\fR )""" 4 |
| 1028 |
.el .IP "\f(CW$parser\->code_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 |
| 1029 |
.IX Item "$parser->code_handler( CODE_REF )" |
| 1030 |
This specifies code that should be called when a code line is seen |
| 1031 |
(i.e., a line outside of the Pod). Normally this is undef, meaning |
| 1032 |
that no code should be called. If you provide a routine, it should |
| 1033 |
start out like this: |
| 1034 |
.Sp |
| 1035 |
.Vb 4 |
| 1036 |
\& sub get_code_line { # or whatever you\*(Aqll call it |
| 1037 |
\& my($line, $line_number, $parser) = @_; |
| 1038 |
\& ... |
| 1039 |
\& } |
| 1040 |
.Ve |
| 1041 |
.Sp |
| 1042 |
Note, however, that sometimes the Pod events aren't processed in exactly |
| 1043 |
the same order as the code lines are \-\- i.e., if you have a file with |
| 1044 |
Pod, then code, then more Pod, sometimes the code will be processed (via |
| 1045 |
whatever you have code_handler call) before the all of the preceding Pod |
| 1046 |
has been processed. |
| 1047 |
.ie n .IP """$parser\->cut_handler( \fICODE_REF\fR )""" 4 |
| 1048 |
.el .IP "\f(CW$parser\->cut_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 |
| 1049 |
.IX Item "$parser->cut_handler( CODE_REF )" |
| 1050 |
This is just like the code_handler attribute, except that it's for |
| 1051 |
"=cut" lines, not code lines. The same caveats apply. "=cut" lines are |
| 1052 |
unlikely to be interesting, but this is included for completeness. |
| 1053 |
.ie n .IP """$parser\->pod_handler( \fICODE_REF\fR )""" 4 |
| 1054 |
.el .IP "\f(CW$parser\->pod_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 |
| 1055 |
.IX Item "$parser->pod_handler( CODE_REF )" |
| 1056 |
This is just like the code_handler attribute, except that it's for |
| 1057 |
"=pod" lines, not code lines. The same caveats apply. "=pod" lines are |
| 1058 |
unlikely to be interesting, but this is included for completeness. |
| 1059 |
.ie n .IP """$parser\->whiteline_handler( \fICODE_REF\fR )""" 4 |
| 1060 |
.el .IP "\f(CW$parser\->whiteline_handler( \fR\f(CICODE_REF\fR\f(CW )\fR" 4 |
| 1061 |
.IX Item "$parser->whiteline_handler( CODE_REF )" |
| 1062 |
This is just like the code_handler attribute, except that it's for |
| 1063 |
lines that are seemingly blank but have whitespace (" " and/or "\et") on them, |
| 1064 |
not code lines. The same caveats apply. These lines are unlikely to be |
| 1065 |
interesting, but this is included for completeness. |
| 1066 |
.ie n .IP """$parser\->whine( \fIlinenumber\fR, \fIcomplaint string\fR )""" 4 |
| 1067 |
.el .IP "\f(CW$parser\->whine( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\fR" 4 |
| 1068 |
.IX Item "$parser->whine( linenumber, complaint string )" |
| 1069 |
This notes a problem in the Pod, which will be reported in the "Pod |
| 1070 |
Errors" section of the document and/or sent to STDERR, depending on the |
| 1071 |
values of the attributes \f(CW\*(C`no_whining\*(C'\fR, \f(CW\*(C`no_errata_section\*(C'\fR, and |
| 1072 |
\&\f(CW\*(C`complain_stderr\*(C'\fR. |
| 1073 |
.ie n .IP """$parser\->scream( \fIlinenumber\fR, \fIcomplaint string\fR )""" 4 |
| 1074 |
.el .IP "\f(CW$parser\->scream( \fR\f(CIlinenumber\fR\f(CW, \fR\f(CIcomplaint string\fR\f(CW )\fR" 4 |
| 1075 |
.IX Item "$parser->scream( linenumber, complaint string )" |
| 1076 |
This notes an error like \f(CW\*(C`whine\*(C'\fR does, except that it is not |
| 1077 |
suppressible with \f(CW\*(C`no_whining\*(C'\fR. This should be used only for very |
| 1078 |
serious errors. |
| 1079 |
.ie n .IP """$parser\->source_dead(1)""" 4 |
| 1080 |
.el .IP \f(CW$parser\->source_dead(1)\fR 4 |
| 1081 |
.IX Item "$parser->source_dead(1)" |
| 1082 |
This aborts parsing of the current document, by switching on the flag |
| 1083 |
that indicates that EOF has been seen. In particularly drastic cases, |
| 1084 |
you might want to do this. It's rather nicer than just calling |
| 1085 |
\&\f(CW\*(C`die\*(C'\fR! |
| 1086 |
.ie n .IP """$parser\->hide_line_numbers( \fISOMEVALUE\fR )""" 4 |
| 1087 |
.el .IP "\f(CW$parser\->hide_line_numbers( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1088 |
.IX Item "$parser->hide_line_numbers( SOMEVALUE )" |
| 1089 |
Some subclasses that indiscriminately dump event attributes (well, |
| 1090 |
except for ones beginning with "~") can use this object attribute for |
| 1091 |
refraining to dump the "start_line" attribute. |
| 1092 |
.ie n .IP """$parser\->no_whining( \fISOMEVALUE\fR )""" 4 |
| 1093 |
.el .IP "\f(CW$parser\->no_whining( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1094 |
.IX Item "$parser->no_whining( SOMEVALUE )" |
| 1095 |
This attribute, if set to true, will suppress reports of non-fatal |
| 1096 |
error messages. The default value is false, meaning that complaints |
| 1097 |
\&\fIare\fR reported. How they get reported depends on the values of |
| 1098 |
the attributes \f(CW\*(C`no_errata_section\*(C'\fR and \f(CW\*(C`complain_stderr\*(C'\fR. |
| 1099 |
.ie n .IP """$parser\->no_errata_section( \fISOMEVALUE\fR )""" 4 |
| 1100 |
.el .IP "\f(CW$parser\->no_errata_section( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1101 |
.IX Item "$parser->no_errata_section( SOMEVALUE )" |
| 1102 |
This attribute, if set to true, will suppress generation of an errata |
| 1103 |
section. The default value is false \-\- i.e., an errata section will be |
| 1104 |
generated. |
| 1105 |
.ie n .IP """$parser\->complain_stderr( \fISOMEVALUE\fR )""" 4 |
| 1106 |
.el .IP "\f(CW$parser\->complain_stderr( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1107 |
.IX Item "$parser->complain_stderr( SOMEVALUE )" |
| 1108 |
This attribute, if set to true will send complaints to STDERR. The |
| 1109 |
default value is false \-\- i.e., complaints do not go to STDERR. |
| 1110 |
.ie n .IP """$parser\->bare_output( \fISOMEVALUE\fR )""" 4 |
| 1111 |
.el .IP "\f(CW$parser\->bare_output( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1112 |
.IX Item "$parser->bare_output( SOMEVALUE )" |
| 1113 |
Some formatter subclasses use this as a flag for whether output should |
| 1114 |
have prologue and epilogue code omitted. For example, setting this to |
| 1115 |
true for an HTML formatter class should omit the |
| 1116 |
"<html><head><title>...</title><body>..." prologue and the |
| 1117 |
"</body></html>" epilogue. |
| 1118 |
.Sp |
| 1119 |
If you want to set this to true, you should probably also set |
| 1120 |
\&\f(CW\*(C`no_whining\*(C'\fR or at least \f(CW\*(C`no_errata_section\*(C'\fR to true. |
| 1121 |
.ie n .IP """$parser\->preserve_whitespace( \fISOMEVALUE\fR )""" 4 |
| 1122 |
.el .IP "\f(CW$parser\->preserve_whitespace( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1123 |
.IX Item "$parser->preserve_whitespace( SOMEVALUE )" |
| 1124 |
If you set this attribute to a true value, the parser will try to |
| 1125 |
preserve whitespace in the output. This means that such formatting |
| 1126 |
conventions as two spaces after periods will be preserved by the parser. |
| 1127 |
This is primarily useful for output formats that treat whitespace as |
| 1128 |
significant (such as text or *roff, but not HTML). |
| 1129 |
.ie n .IP """$parser\->parse_empty_lists( \fISOMEVALUE\fR )""" 4 |
| 1130 |
.el .IP "\f(CW$parser\->parse_empty_lists( \fR\f(CISOMEVALUE\fR\f(CW )\fR" 4 |
| 1131 |
.IX Item "$parser->parse_empty_lists( SOMEVALUE )" |
| 1132 |
If this attribute is set to true, the parser will not ignore empty |
| 1133 |
\&\f(CW\*(C`=over\*(C'\fR/\f(CW\*(C`=back\*(C'\fR blocks. The type of \f(CW\*(C`=over\*(C'\fR will be \fIempty\fR, documented |
| 1134 |
above, "events with an element_name of over-empty". |
| 1135 |
.SH "SEE ALSO" |
| 1136 |
.IX Header "SEE ALSO" |
| 1137 |
Pod::Simple \-\- event-based Pod-parsing framework |
| 1138 |
.PP |
| 1139 |
Pod::Simple::Methody \-\- like Pod::Simple, but each sort of event |
| 1140 |
calls its own method (like \f(CW\*(C`start_head3\*(C'\fR) |
| 1141 |
.PP |
| 1142 |
Pod::Simple::PullParser \-\- a Pod-parsing framework like Pod::Simple, |
| 1143 |
but with a token-stream interface |
| 1144 |
.PP |
| 1145 |
Pod::Simple::SimpleTree \-\- a Pod-parsing framework like Pod::Simple, |
| 1146 |
but with a tree interface |
| 1147 |
.PP |
| 1148 |
Pod::Simple::Checker \-\- a simple Pod::Simple subclass that reads |
| 1149 |
documents, and then makes a plaintext report of any errors found in the |
| 1150 |
document |
| 1151 |
.PP |
| 1152 |
Pod::Simple::DumpAsXML \-\- for dumping Pod documents as tidily |
| 1153 |
indented XML, showing each event on its own line |
| 1154 |
.PP |
| 1155 |
Pod::Simple::XMLOutStream \-\- dumps a Pod document as XML (without |
| 1156 |
introducing extra whitespace as Pod::Simple::DumpAsXML does). |
| 1157 |
.PP |
| 1158 |
Pod::Simple::DumpAsText \-\- for dumping Pod documents as tidily |
| 1159 |
indented text, showing each event on its own line |
| 1160 |
.PP |
| 1161 |
Pod::Simple::LinkSection \-\- class for objects representing the values |
| 1162 |
of the TODO and TODO attributes of L<...> elements |
| 1163 |
.PP |
| 1164 |
Pod::Escapes \-\- the module that Pod::Simple uses for evaluating |
| 1165 |
E<...> content |
| 1166 |
.PP |
| 1167 |
Pod::Simple::Text \-\- a simple plaintext formatter for Pod |
| 1168 |
.PP |
| 1169 |
Pod::Simple::TextContent \-\- like Pod::Simple::Text, but |
| 1170 |
makes no effort for indent or wrap the text being formatted |
| 1171 |
.PP |
| 1172 |
Pod::Simple::HTML \-\- a simple HTML formatter for Pod |
| 1173 |
.PP |
| 1174 |
perlpod |
| 1175 |
.PP |
| 1176 |
perlpodspec |
| 1177 |
.PP |
| 1178 |
perldoc |
| 1179 |
.SH SUPPORT |
| 1180 |
.IX Header "SUPPORT" |
| 1181 |
Questions or discussion about POD and Pod::Simple should be sent to the |
| 1182 |
pod\[email protected] mail list. Send an empty email to |
| 1183 |
pod\-people\[email protected] to subscribe. |
| 1184 |
.PP |
| 1185 |
This module is managed in an open GitHub repository, |
| 1186 |
<https://github.com/perl\-pod/pod\-simple/>. Feel free to fork and contribute, or |
| 1187 |
to clone <https://github.com/perl\-pod/pod\-simple.git> and send patches! |
| 1188 |
.PP |
| 1189 |
Patches against Pod::Simple are welcome. Please send bug reports to |
| 1190 |
<bug\-pod\[email protected]>. |
| 1191 |
.SH "COPYRIGHT AND DISCLAIMERS" |
| 1192 |
.IX Header "COPYRIGHT AND DISCLAIMERS" |
| 1193 |
Copyright (c) 2002 Sean M. Burke. |
| 1194 |
.PP |
| 1195 |
This library is free software; you can redistribute it and/or modify it |
| 1196 |
under the same terms as Perl itself. |
| 1197 |
.PP |
| 1198 |
This program is distributed in the hope that it will be useful, but |
| 1199 |
without any warranty; without even the implied warranty of |
| 1200 |
merchantability or fitness for a particular purpose. |
| 1201 |
.SH AUTHOR |
| 1202 |
.IX Header "AUTHOR" |
| 1203 |
Pod::Simple was created by Sean M. Burke <[email protected]>. |
| 1204 |
But don't bother him, he's retired. |
| 1205 |
.PP |
| 1206 |
Pod::Simple is maintained by: |
| 1207 |
.IP \(bu 4 |
| 1208 |
Allison Randal \f(CW\*(C`[email protected]\*(C'\fR |
| 1209 |
.IP \(bu 4 |
| 1210 |
Hans Dieter Pearcey \f(CW\*(C`[email protected]\*(C'\fR |
| 1211 |
.IP \(bu 4 |
| 1212 |
David E. Wheeler \f(CW\*(C`[email protected]\*(C'\fR |