Mercurial > cpython-lru_cache-weakref

annotate Doc/libsgmllib.tex @ 5817:48b94de85bf3 legacy-trunk

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Extensive changes by AMK.
author Guido van Rossum <guido@python.org>
date Thu, 17 Jul 1997 16:29:42 +0000
parents 77954fe4376c
children 3468ea8645ca
Ignore whitespace changes - Everywhere: Within whitespace: At end of lines:
rev   line source
2576
f47bc5554418 mass changes; fix titles; add examples; correct typos; clarifications;
Guido van Rossum <guido@python.org>
parents: 2491
diff changeset
1 \section{Standard Module \sectcode{sgmllib}}
2449
8eeecd233d56 added WWW sections
Guido van Rossum <guido@python.org>
parents:
diff changeset
2 \stmodindex{sgmllib}
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
3 \index{SGML}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
4
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
5 This module defines a class \code{SGMLParser} which serves as the
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
6 basis for parsing text files formatted in SGML (Standard Generalized
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
7 Mark-up Language). In fact, it does not provide a full SGML parser
4390
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex):
Fred Drake <fdrake@acm.org>
parents: 4380
diff changeset
8 --- it only parses SGML insofar as it is used by HTML, and the module
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex):
Fred Drake <fdrake@acm.org>
parents: 4380
diff changeset
9 only exists as a base for the \code{htmllib} module.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
10 \stmodindex{htmllib}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
11
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
12 In particular, the parser is hardcoded to recognize the following
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
13 constructs:
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
14
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
15 \begin{itemize}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
16
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
17 \item
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
18 Opening and closing tags of the form
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
19 ``\code{<\var{tag} \var{attr}="\var{value}" ...>}'' and
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
20 ``\code{</\var{tag}>}'', respectively.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
21
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
22 \item
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
23 Numeric character references of the form ``\code{\&\#\var{name};}''.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
24
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
25 \item
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
26 Entity references of the form ``\code{\&\var{name};}''.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
27
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
28 \item
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
29 SGML comments of the form ``\code{<!--\var{text}-->}''. Note that
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
30 spaces, tabs, and newlines are allowed between the trailing
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
31 ``\code{>}'' and the immediately preceeding ``\code{--}''.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
32
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
33 \end{itemize}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
34
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
35 The \code{SGMLParser} class must be instantiated without arguments.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
36 It has the following interface methods:
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
37
4390
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex):
Fred Drake <fdrake@acm.org>
parents: 4380
diff changeset
38 \renewcommand{\indexsubitem}{({\tt SGMLParser} method)}
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex):
Fred Drake <fdrake@acm.org>
parents: 4380
diff changeset
39
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
40 \begin{funcdesc}{reset}{}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
41 Reset the instance. Loses all unprocessed data. This is called
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
42 implicitly at instantiation time.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
43 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
44
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
45 \begin{funcdesc}{setnomoretags}{}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
46 Stop processing tags. Treat all following input as literal input
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
47 (CDATA). (This is only provided so the HTML tag \code{<PLAINTEXT>}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
48 can be implemented.)
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
49 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
50
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
51 \begin{funcdesc}{setliteral}{}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
52 Enter literal mode (CDATA mode).
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
53 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
54
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
55 \begin{funcdesc}{feed}{data}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
56 Feed some text to the parser. It is processed insofar as it consists
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
57 of complete elements; incomplete data is buffered until more data is
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
58 fed or \code{close()} is called.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
59 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
60
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
61 \begin{funcdesc}{close}{}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
62 Force processing of all buffered data as if it were followed by an
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
63 end-of-file mark. This method may be redefined by a derived class to
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
64 define additional processing at the end of the input, but the
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
65 redefined version should always call \code{SGMLParser.close()}.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
66 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
67
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
68 \begin{funcdesc}{handle_starttag}{tag\, method\, attributes}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
69 This method is called to handle start tags for which either a
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
70 \code{start_\var{tag}()} or \code{do_\var{tag}()} method has been
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
71 defined. The \code{tag} argument is the name of the tag converted to
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
72 lower case, and the \code{method} argument is the bound method which
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
73 should be used to support semantic interpretation of the start tag.
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
74 The \var{attributes} argument is a list of (\var{name}, \var{value})
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
75 pairs containing the attributes found inside the tag's \code{<>}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
76 brackets. The \var{name} has been translated to lower case and double
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
77 quotes and backslashes in the \var{value} have been interpreted. For
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
78 instance, for the tag \code{<A HREF="http://www.cwi.nl/">}, this
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
79 method would be called as \code{unknown_starttag('a', [('href',
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
80 'http://www.cwi.nl/')])}. The base implementation simply calls
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
81 \code{method} with \code{attributes} as the only argument.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
82 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
83
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
84 \begin{funcdesc}{handle_endtag}{tag\, method}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
85
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
86 This method is called to handle endtags for which an
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
87 \code{end_\var{tag}()} method has been defined. The \code{tag}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
88 argument is the name of the tag converted to lower case, and the
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
89 \code{method} argument is the bound method which should be used to
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
90 support semantic interpretation of the end tag. If no
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
91 \code{end_\var{tag}()} method is defined for the closing element, this
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
92 handler is not called. The base implementation simply calls
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
93 \code{method}.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
94 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
95
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
96 \begin{funcdesc}{handle_data}{data}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
97 This method is called to process arbitrary data. It is intended to be
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
98 overridden by a derived class; the base class implementation does
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
99 nothing.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
100 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
101
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
102 \begin{funcdesc}{handle_charref}{ref}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
103 This method is called to process a character reference of the form
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
104 ``\code{\&\#\var{ref};}''. In the base implementation, \var{ref} must
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
105 be a decimal number in the
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
106 range 0-255. It translates the character to \ASCII{} and calls the
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
107 method \code{handle_data()} with the character as argument. If
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
108 \var{ref} is invalid or out of range, the method
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
109 \code{unknown_charref(\var{ref})} is called to handle the error. A
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
110 subclass must override this method to provide support for named
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
111 character entities.
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
112 \end{funcdesc}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
113
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
114 \begin{funcdesc}{handle_entityref}{ref}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
115 This method is called to process a general entity reference of the form
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
116 ``\code{\&\var{ref};}'' where \var{ref} is an general entity
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
117 reference. It looks for \var{ref} in the instance (or class)
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
118 variable \code{entitydefs} which should be a mapping from entity names
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
119 to corresponding translations.
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
120 If a translation is found, it calls the method \code{handle_data()}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
121 with the translation; otherwise, it calls the method
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
122 \code{unknown_entityref(\var{ref})}. The default \code{entitydefs}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
123 defines translations for \code{\&amp;}, \code{\&apos}, \code{\&gt;},
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
124 \code{\&lt;}, and \code{\&quot;}.
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
125 \end{funcdesc}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
126
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
127 \begin{funcdesc}{handle_comment}{comment}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
128 This method is called when a comment is encountered. The
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
129 \code{comment} argument is a string containing the text between the
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
130 ``\code{<!--}'' and ``\code{-->}'' delimiters, but not the delimiters
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
131 themselves. For example, the comment ``\code{<!--text-->}'' will
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
132 cause this method to be called with the argument \code{'text'}. The
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
133 default method does nothing.
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
134 \end{funcdesc}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
135
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
136 \begin{funcdesc}{report_unbalanced}{tag}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
137 This method is called when an end tag is found which does not
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
138 correspond to any open element.
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
139 \end{funcdesc}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
140
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
141 \begin{funcdesc}{unknown_starttag}{tag\, attributes}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
142 This method is called to process an unknown start tag. It is intended
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
143 to be overridden by a derived class; the base class implementation
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
144 does nothing.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
145 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
146
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
147 \begin{funcdesc}{unknown_endtag}{tag}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
148 This method is called to process an unknown end tag. It is intended
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
149 to be overridden by a derived class; the base class implementation
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
150 does nothing.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
151 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
152
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
153 \begin{funcdesc}{unknown_charref}{ref}
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
154 This method is called to process unresolvable numeric character
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
155 references. It is intended to be overridden by a derived class; the
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
156 base class implementation does nothing.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
157 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
158
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
159 \begin{funcdesc}{unknown_entityref}{ref}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
160 This method is called to process an unknown entity reference. It is
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
161 intended to be overridden by a derived class; the base class
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
162 implementation does nothing.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
163 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
164
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
165 Apart from overriding or extending the methods listed above, derived
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
166 classes may also define methods of the following form to define
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
167 processing of specific tags. Tag names in the input stream are case
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
168 independent; the \var{tag} occurring in method names must be in lower
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
169 case:
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
170
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
171 \begin{funcdesc}{start_\var{tag}}{attributes}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
172 This method is called to process an opening tag \var{tag}. It has
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
173 preference over \code{do_\var{tag}()}. The \var{attributes} argument
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
174 has the same meaning as described for \code{handle_starttag()} above.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
175 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
176
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
177 \begin{funcdesc}{do_\var{tag}}{attributes}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
178 This method is called to process an opening tag \var{tag} that does
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
179 not come with a matching closing tag. The \var{attributes} argument
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
180 has the same meaning as described for \code{handle_starttag()} above.
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
181 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
182
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
183 \begin{funcdesc}{end_\var{tag}}{}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
184 This method is called to process a closing tag \var{tag}.
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
185 \end{funcdesc}
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
186
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
187 Note that the parser maintains a stack of open elements for which no
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
188 end tag has been found yet. Only tags processed by
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
189 \code{start_\var{tag}()} are pushed on this stack. Definition of an
2453
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
190 \code{end_\var{tag}()} method is optional for these tags. For tags
cdd3a721b40e a few typographical changes (e.g. -- => ---) and lots of new stuff in the WWW chapter
Guido van Rossum <guido@python.org>
parents: 2449
diff changeset
191 processed by \code{do_\var{tag}()} or by \code{unknown_tag()}, no
4380
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
192 \code{end_\var{tag}()} method must be defined; if defined, it will not
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
193 be used. If both \code{start_\var{tag}()} and \code{do_\var{tag}()}
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
194 methods exist for a tag, the \code{start_\var{tag}()} method takes
af1bf0f6e2db (libsgmllib.tex): Revised documentation for SGML support.
Fred Drake <fdrake@acm.org>
parents: 2576
diff changeset
195 precedence.