local-lib5/man/man3/Pod::Simple::XHTML.3pm

   1 .\" Automatically generated by Pod::Man v1.37, Pod::Parser v1.3
   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::Simple::XHTML 3"
 132 .TH Pod::Simple::XHTML 3 "2009-11-12" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 Pod::Simple::XHTML \-\- format Pod as validating XHTML
 135 .SH "SYNOPSIS"
 136 .IX Header "SYNOPSIS"
 137 .Vb 1
 138 \&  use Pod::Simple::XHTML;
 139 .Ve
 140 .PP
 141 .Vb 1
 142 \&  my $parser = Pod::Simple::XHTML\->new();
 143 .Ve
 144 .PP
 145 .Vb 1
 146 \&  ...
 147 .Ve
 148 .PP
 149 .Vb 1
 150 \&  $parser\->parse_file('path/to/file.pod');
 151 .Ve
 152 .SH "DESCRIPTION"
 153 .IX Header "DESCRIPTION"
 154 This class is a formatter that takes Pod and renders it as \s-1XHTML\s0
 155 validating \s-1HTML\s0.
 156 .PP
 157 This is a subclass of Pod::Simple::Methody and inherits all its
 158 methods. The implementation is entirely different than
 159 Pod::Simple::HTML, but it largely preserves the same interface.
 160 .SH "METHODS"
 161 .IX Header "METHODS"
 162 Pod::Simple::XHTML offers a number of methods that modify the format of
 163 the \s-1HTML\s0 output. Call these after creating the parser object, but before
 164 the call to \f(CW\*(C`parse_file\*(C'\fR:
 165 .PP
 166 .Vb 3
 167 \&  my $parser = Pod::PseudoPod::HTML\->new();
 168 \&  $parser\->set_optional_param("value");
 169 \&  $parser\->parse_file($file);
 170 .Ve
 171 .Sh "perldoc_url_prefix"
 172 .IX Subsection "perldoc_url_prefix"
 173 In turning Foo::Bar into http://whatever/Foo%3a%3aBar, what
 174 to put before the \*(L"Foo%3a%3aBar\*(R". The default value is
 175 \&\*(L"http://search.cpan.org/perldoc?\*(R".
 176 .Sh "perldoc_url_postfix"
 177 .IX Subsection "perldoc_url_postfix"
 178 What to put after \*(L"Foo%3a%3aBar\*(R" in the \s-1URL\s0. This option is not set by
 179 default.
 180 .Sh "title_prefix, title_postfix"
 181 .IX Subsection "title_prefix, title_postfix"
 182 What to put before and after the title in the head. The values should
 183 already be &\-escaped.
 184 .Sh "html_css"
 185 .IX Subsection "html_css"
 186 .Vb 1
 187 \&  $parser\->html_css('path/to/style.css');
 188 .Ve
 189 .PP
 190 The \s-1URL\s0 or relative path of a \s-1CSS\s0 file to include. This option is not
 191 set by default.
 192 .Sh "html_javascript"
 193 .IX Subsection "html_javascript"
 194 The \s-1URL\s0 or relative path of a JavaScript file to pull in. This option is
 195 not set by default.
 196 .Sh "html_doctype"
 197 .IX Subsection "html_doctype"
 198 A document type tag for the file. This option is not set by default.
 199 .Sh "html_header_tags"
 200 .IX Subsection "html_header_tags"
 201 Additional arbitrary \s-1HTML\s0 tags for the header of the document. The
 202 default value is just a content type header tag:
 203 .PP
 204 .Vb 1
 205 \&  <meta http\-equiv="Content\-Type" content="text/html; charset=ISO\-8859\-1">
 206 .Ve
 207 .PP
 208 Add additional meta tags here, or blocks of inline \s-1CSS\s0 or JavaScript
 209 (wrapped in the appropriate tags).
 210 .Sh "default_title"
 211 .IX Subsection "default_title"
 212 Set a default title for the page if no title can be determined from the
 213 content. The value of this string should already be &\-escaped.
 214 .Sh "force_title"
 215 .IX Subsection "force_title"
 216 Force a title for the page (don't try to determine it from the content).
 217 The value of this string should already be &\-escaped.
 218 .Sh "html_header, html_footer"
 219 .IX Subsection "html_header, html_footer"
 220 Set the \s-1HTML\s0 output at the beginning and end of each file. The default
 221 header includes a title, a doctype tag (if \f(CW\*(C`html_doctype\*(C'\fR is set), a
 222 content tag (customized by \f(CW\*(C`html_header_tags\*(C'\fR), a tag for a \s-1CSS\s0 file
 223 (if \f(CW\*(C`html_css\*(C'\fR is set), and a tag for a Javascript file (if
 224 \&\f(CW\*(C`html_javascript\*(C'\fR is set). The default footer simply closes the \f(CW\*(C`html\*(C'\fR
 225 and \f(CW\*(C`body\*(C'\fR tags.
 226 .PP
 227 The options listed above customize parts of the default header, but
 228 setting \f(CW\*(C`html_header\*(C'\fR or \f(CW\*(C`html_footer\*(C'\fR completely overrides the
 229 built-in header or footer. These may be useful if you want to use
 230 template tags instead of literal \s-1HTML\s0 headers and footers or are
 231 integrating converted \s-1POD\s0 pages in a larger website.
 232 .PP
 233 If you want no headers or footers output in the \s-1HTML\s0, set these options
 234 to the empty string.
 235 .Sh "index"
 236 .IX Subsection "index"
 237 Whether to add a table-of-contents at the top of each page (called an
 238 index for the sake of tradition).
 239 .SH "SUBCLASSING"
 240 .IX Header "SUBCLASSING"
 241 If the standard options aren't enough, you may want to subclass
 242 Pod::Simple::XHMTL. These are the most likely candidates for methods
 243 you'll want to override when subclassing.
 244 .Sh "handle_text"
 245 .IX Subsection "handle_text"
 246 This method handles the body of text within any element: it's the body
 247 of a paragraph, or everything between a \*(L"=begin\*(R" tag and the
 248 corresponding \*(L"=end\*(R" tag, or the text within an L entity, etc. You would
 249 want to override this if you are adding a custom element type that does
 250 more than just display formatted text. Perhaps adding a way to generate
 251 \&\s-1HTML\s0 tables from an extended version of \s-1POD\s0.
 252 .PP
 253 So, let's say you want add a custom element called 'foo'. In your
 254 subclass's \f(CW\*(C`new\*(C'\fR method, after calling \f(CW\*(C`SUPER::new\*(C'\fR you'd call:
 255 .PP
 256 .Vb 1
 257 \&  $new\->accept_targets_as_text( 'foo' );
 258 .Ve
 259 .PP
 260 Then override the \f(CW\*(C`start_for\*(C'\fR method in the subclass to check for when
 261 \&\*(L"$flags\->{'target'}\*(R" is equal to 'foo' and set a flag that marks that
 262 you're in a foo block (maybe \*(L"$self\->{'in_foo'} = 1\*(R"). Then override the
 263 \&\f(CW\*(C`handle_text\*(C'\fR method to check for the flag, and pass \f(CW$text\fR to your
 264 custom subroutine to construct the \s-1HTML\s0 output for 'foo' elements,
 265 something like:
 266 .PP
 267 .Vb 8
 268 \&  sub handle_text {
 269 \&      my ($self, $text) = @_;
 270 \&      if ($self\->{'in_foo'}) {
 271 \&          $self\->{'scratch'} .= build_foo_html($text);
 272 \&      } else {
 273 \&          $self\->{'scratch'} .= $text;
 274 \&      }
 275 \&  }
 276 .Ve
 277 .Sh "idify"
 278 .IX Subsection "idify"
 279 .Vb 2
 280 \&  my $id   = $pod\->idify($text);
 281 \&  my $hash = $pod\->idify($text, 1);
 282 .Ve
 283 .PP
 284 This method turns an arbitrary string into a valid \s-1XHTML\s0 \s-1ID\s0 attribute value.
 285 The rules enforced, following
 286 <http://webdesign.about.com/od/htmltags/a/aa031707.htm>, are:
 287 .IP "\(bu" 4
 288 The id must start with a letter (a\-z or A\-Z)
 289 .IP "\(bu" 4
 290 All subsequent characters can be letters, numbers (0\-9), hyphens (\-),
 291 underscores (_), colons (:), and periods (.).
 292 .IP "\(bu" 4
 293 Each id must be unique within the document.
 294 .PP
 295 In addition, the returned value will be unique within the context of the
 296 Pod::Simple::XHTML object unless a second argument is passed a true value. \s-1ID\s0
 297 attributes should always be unique within a single \s-1XHTML\s0 document, but pass
 298 the true value if you are creating not an \s-1ID\s0 but a \s-1URL\s0 hash to point to
 299 an \s-1ID\s0 (i.e., if you need to put the \*(L"#foo\*(R" in \f(CW\*(C`<a href="#foo">foo</a>\*(C'\fR.
 300 .SH "SEE ALSO"
 301 .IX Header "SEE ALSO"
 302 Pod::Simple, Pod::Simple::Methody
 303 .SH "COPYRIGHT"
 304 .IX Header "COPYRIGHT"
 305 Copyright (c) 2003\-2005 Allison Randal.
 306 .PP
 307 This library is free software; you can redistribute it and/or modify
 308 it under the same terms as Perl itself.
 309 .PP
 310 This library is distributed in the hope that it will be useful, but
 311 without any warranty; without even the implied warranty of
 312 merchantability or fitness for a particular purpose.
 313 .SH "AUTHOR"
 314 .IX Header "AUTHOR"
 315 Allison Randal <allison@perl.org>