local-lib5/man/man3/HTML::Tagset.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 "Tagset 3"
 132 .TH Tagset 3 "2008-03-01" "perl v5.8.7" "User Contributed Perl Documentation"
 133 .SH "NAME"
 134 HTML::Tagset \- data tables useful in parsing HTML
 135 .SH "VERSION"
 136 .IX Header "VERSION"
 137 Version 3.20
 138 .SH "SYNOPSIS"
 139 .IX Header "SYNOPSIS"
 140 .Vb 3
 141 \&  use HTML::Tagset;
 142 \&  # Then use any of the items in the HTML::Tagset package
 143 \&  #  as need arises
 144 .Ve
 145 .SH "DESCRIPTION"
 146 .IX Header "DESCRIPTION"
 147 This module contains several data tables useful in various kinds of
 148 \&\s-1HTML\s0 parsing operations.
 149 .PP
 150 Note that all tag names used are lowercase.
 151 .PP
 152 In the following documentation, a \*(L"hashset\*(R" is a hash being used as a
 153 set \*(-- the hash conveys that its keys are there, and the actual values
 154 associated with the keys are not significant.  (But what values are
 155 there, are always true.)
 156 .SH "VARIABLES"
 157 .IX Header "VARIABLES"
 158 Note that none of these variables are exported.
 159 .ie n .Sh "hashset %HTML::Tagset::emptyElement"
 160 .el .Sh "hashset \f(CW%HTML::Tagset::emptyElement\fP"
 161 .IX Subsection "hashset %HTML::Tagset::emptyElement"
 162 This hashset has as values the tag-names (GIs) of elements that cannot
 163 have content.  (For example, \*(L"base\*(R", \*(L"br\*(R", \*(L"hr\*(R".)  So
 164 \&\f(CW$HTML::Tagset::emptyElement{'hr'}\fR exists and is true.
 165 \&\f(CW$HTML::Tagset::emptyElement{'dl'}\fR does not exist, and so is not true.
 166 .ie n .Sh "hashset %HTML::Tagset::optionalEndTag"
 167 .el .Sh "hashset \f(CW%HTML::Tagset::optionalEndTag\fP"
 168 .IX Subsection "hashset %HTML::Tagset::optionalEndTag"
 169 This hashset lists tag-names for elements that can have content, but whose
 170 end-tags are generally, \*(L"safely\*(R", omissible.  Example:
 171 \&\f(CW$HTML::Tagset::emptyElement{'li'}\fR exists and is true.
 172 .ie n .Sh "hash %HTML::Tagset::linkElements"
 173 .el .Sh "hash \f(CW%HTML::Tagset::linkElements\fP"
 174 .IX Subsection "hash %HTML::Tagset::linkElements"
 175 Values in this hash are tagnames for elements that might contain
 176 links, and the value for each is a reference to an array of the names
 177 of attributes whose values can be links.
 178 .ie n .Sh "hash %HTML::Tagset::boolean_attr"
 179 .el .Sh "hash \f(CW%HTML::Tagset::boolean_attr\fP"
 180 .IX Subsection "hash %HTML::Tagset::boolean_attr"
 181 This hash (not hashset) lists what attributes of what elements can be
 182 printed without showing the value (for example, the \*(L"noshade\*(R" attribute
 183 of \*(L"hr\*(R" elements).  For elements with only one such attribute, its value
 184 is simply that attribute name.  For elements with many such attributes,
 185 the value is a reference to a hashset containing all such attributes.
 186 .ie n .Sh "hashset %HTML::Tagset::isPhraseMarkup"
 187 .el .Sh "hashset \f(CW%HTML::Tagset::isPhraseMarkup\fP"
 188 .IX Subsection "hashset %HTML::Tagset::isPhraseMarkup"
 189 This hashset contains all phrasal-level elements.
 190 .ie n .Sh "hashset %HTML::Tagset::is_Possible_Strict_P_Content"
 191 .el .Sh "hashset \f(CW%HTML::Tagset::is_Possible_Strict_P_Content\fP"
 192 .IX Subsection "hashset %HTML::Tagset::is_Possible_Strict_P_Content"
 193 This hashset contains all phrasal-level elements that be content of a
 194 P element, for a strict model of \s-1HTML\s0.
 195 .ie n .Sh "hashset %HTML::Tagset::isHeadElement"
 196 .el .Sh "hashset \f(CW%HTML::Tagset::isHeadElement\fP"
 197 .IX Subsection "hashset %HTML::Tagset::isHeadElement"
 198 This hashset contains all elements that elements that should be
 199 present only in the 'head' element of an \s-1HTML\s0 document.
 200 .ie n .Sh "hashset %HTML::Tagset::isList"
 201 .el .Sh "hashset \f(CW%HTML::Tagset::isList\fP"
 202 .IX Subsection "hashset %HTML::Tagset::isList"
 203 This hashset contains all elements that can contain \*(L"li\*(R" elements.
 204 .ie n .Sh "hashset %HTML::Tagset::isTableElement"
 205 .el .Sh "hashset \f(CW%HTML::Tagset::isTableElement\fP"
 206 .IX Subsection "hashset %HTML::Tagset::isTableElement"
 207 This hashset contains all elements that are to be found only in/under
 208 a \*(L"table\*(R" element.
 209 .ie n .Sh "hashset %HTML::Tagset::isFormElement"
 210 .el .Sh "hashset \f(CW%HTML::Tagset::isFormElement\fP"
 211 .IX Subsection "hashset %HTML::Tagset::isFormElement"
 212 This hashset contains all elements that are to be found only in/under
 213 a \*(L"form\*(R" element.
 214 .ie n .Sh "hashset %HTML::Tagset::isBodyMarkup"
 215 .el .Sh "hashset \f(CW%HTML::Tagset::isBodyMarkup\fP"
 216 .IX Subsection "hashset %HTML::Tagset::isBodyMarkup"
 217 This hashset contains all elements that are to be found only in/under
 218 the \*(L"body\*(R" element of an \s-1HTML\s0 document.
 219 .ie n .Sh "hashset %HTML::Tagset::isHeadOrBodyElement"
 220 .el .Sh "hashset \f(CW%HTML::Tagset::isHeadOrBodyElement\fP"
 221 .IX Subsection "hashset %HTML::Tagset::isHeadOrBodyElement"
 222 This hashset includes all elements that I notice can fall either in
 223 the head or in the body.
 224 .ie n .Sh "hashset %HTML::Tagset::isKnown"
 225 .el .Sh "hashset \f(CW%HTML::Tagset::isKnown\fP"
 226 .IX Subsection "hashset %HTML::Tagset::isKnown"
 227 This hashset lists all known \s-1HTML\s0 elements.
 228 .ie n .Sh "hashset %HTML::Tagset::canTighten"
 229 .el .Sh "hashset \f(CW%HTML::Tagset::canTighten\fP"
 230 .IX Subsection "hashset %HTML::Tagset::canTighten"
 231 This hashset lists elements that might have ignorable whitespace as
 232 children or siblings.
 233 .ie n .Sh "array @HTML::Tagset::p_closure_barriers"
 234 .el .Sh "array \f(CW@HTML::Tagset::p_closure_barriers\fP"
 235 .IX Subsection "array @HTML::Tagset::p_closure_barriers"
 236 This array has a meaning that I have only seen a need for in
 237 \&\f(CW\*(C`HTML::TreeBuilder\*(C'\fR, but I include it here on the off chance that someone
 238 might find it of use:
 239 .PP
 240 When we see a "<p>" token, we go lookup up the lineage for a p
 241 element we might have to minimize.  At first sight, we might say that
 242 if there's a p anywhere in the lineage of this new p, it should be
 243 closed.  But that's wrong.  Consider this document:
 244 .PP
 245 .Vb 17
 246 \&  <html>
 247 \&    <head>
 248 \&      <title>foo</title>
 249 \&    </head>
 250 \&    <body>
 251 \&      <p>foo
 252 \&        <table>
 253 \&          <tr>
 254 \&            <td>
 255 \&               foo
 256 \&               <p>bar
 257 \&            </td>
 258 \&          </tr>
 259 \&        </table>
 260 \&      </p>
 261 \&    </body>
 262 \&  </html>
 263 .Ve
 264 .PP
 265 The second p is quite legally inside a much higher p.
 266 .PP
 267 My formalization of the reason why this is legal, but this:
 268 .PP
 269 .Vb 1
 270 \&  <p>foo<p>bar</p></p>
 271 .Ve
 272 .PP
 273 isn't, is that something about the table constitutes a \*(L"barrier\*(R" to
 274 the application of the rule about what p must minimize.
 275 .PP
 276 So \f(CW@HTML::Tagset::p_closure_barriers\fR is the list of all such
 277 barrier\-tags.
 278 .ie n .Sh "hashset %isCDATA_Parent"
 279 .el .Sh "hashset \f(CW%isCDATA_Parent\fP"
 280 .IX Subsection "hashset %isCDATA_Parent"
 281 This hashset includes all elements whose content is \s-1CDATA\s0.
 282 .SH "CAVEATS"
 283 .IX Header "CAVEATS"
 284 You may find it useful to alter the behavior of modules (like
 285 \&\f(CW\*(C`HTML::Element\*(C'\fR or \f(CW\*(C`HTML::TreeBuilder\*(C'\fR) that use \f(CW\*(C`HTML::Tagset\*(C'\fR's
 286 data tables by altering the data tables themselves.  You are welcome
 287 to try, but be careful; and be aware that different modules may or may
 288 react differently to the data tables being changed.
 289 .PP
 290 Note that it may be inappropriate to use these tables for \fIproducing\fR
 291 \&\s-1HTML\s0 \*(-- for example, \f(CW%isHeadOrBodyElement\fR lists the tagnames
 292 for all elements that can appear either in the head or in the body,
 293 such as \*(L"script\*(R".  That doesn't mean that I am saying your code that
 294 produces \s-1HTML\s0 should feel free to put script elements in either place!
 295 If you are producing programs that spit out \s-1HTML\s0, you should be
 296 \&\fIintimately\fR familiar with the DTDs for \s-1HTML\s0 or \s-1XHTML\s0 (available at
 297 \&\f(CW\*(C`http://www.w3.org/\*(C'\fR), and you should slavishly obey them, not
 298 the data tables in this document.
 299 .SH "SEE ALSO"
 300 .IX Header "SEE ALSO"
 301 HTML::Element, HTML::TreeBuilder, HTML::LinkExtor
 302 .SH "COPYRIGHT & LICENSE"
 303 .IX Header "COPYRIGHT & LICENSE"
 304 Copyright 1995\-2000 Gisle Aas.
 305 .PP
 306 Copyright 2000\-2005 Sean M. Burke.
 307 .PP
 308 Copyright 2005\-2008 Andy Lester.
 309 .PP
 310 This program is free software; you can redistribute it and/or modify it
 311 under the same terms as Perl itself.
 312 .SH "ACKNOWLEDGEMENTS"
 313 .IX Header "ACKNOWLEDGEMENTS"
 314 Most of the code/data in this module was adapted from code written
 315 by Gisle Aas for \f(CW\*(C`HTML::Element\*(C'\fR, \f(CW\*(C`HTML::TreeBuilder\*(C'\fR, and
 316 \&\f(CW\*(C`HTML::LinkExtor\*(C'\fR.  Then it was maintained by Sean M. Burke.
 317 .SH "AUTHOR"
 318 .IX Header "AUTHOR"
 319 Current maintainer: Andy Lester, \f(CW\*(C`<andy at petdance.com>\*(C'\fR
 320 .SH "BUGS"
 321 .IX Header "BUGS"
 322 Please report any bugs or feature requests to
 323 \&\f(CW\*(C`bug\-html\-tagset at rt.cpan.org\*(C'\fR, or through the web interface at
 324 <http://rt.cpan.org/NoAuth/ReportBug.html?Queue=HTML\-Tagset>.  I will
 325 be notified, and then you'll automatically be notified of progress on
 326 your bug as I make changes.