Blame - Doc/libhtmllib.tex - platform/external/python/cpython3

blob: aeb4ce9c568b31a0c161b14111483776601b9f12 [file] [log] [blame]

Guido van Rossum	470be14	1995-03-17 16:07:09 +0000	[diff] [blame]	1	\section{Standard Module \sectcode{htmllib}}
Guido van Rossum	a12ef94	1995-02-27 17:53:25 +0000	[diff] [blame]	2	\stmodindex{htmllib}
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	3	\index{HTML}
				4	\index{hypertext}
				5
				6	\renewcommand{\indexsubitem}{(in module htmllib)}
				7
				8	This module defines a number of classes which can serve as a basis for
				9	parsing text files formatted in HTML (HyperText Mark-up Language).
				10	The classes are not directly concerned with I/O --- the have to be fed
				11	their input in string form, and will make calls to methods of a
				12	``formatter'' object in order to produce output. The classes are
				13	designed to be used as base classes for other classes in order to add
				14	functionality, and allow most of their methods to be extended or
				15	overridden. In turn, the classes are derived from and extend the
				16	class \code{SGMLParser} defined in module \code{sgmllib}.
				17	\index{SGML}
				18	\stmodindex{sgmllib}
				19	\ttindex{SGMLParser}
				20	\index{formatter}
				21
				22	The following is a summary of the interface defined by
				23	\code{sgmllib.SGMLParser}:
				24
				25	\begin{itemize}
				26
				27	\item
				28	The interface to feed data to an instance is through the \code{feed()}
				29	method, which takes a string argument. This can be called with as
Guido van Rossum	470be14	1995-03-17 16:07:09 +0000	[diff] [blame]	30	little or as much text at a time as desired;
				31	\code{p.feed(a); p.feed(b)} has the same effect as \code{p.feed(a+b)}.
				32	When the data contains complete
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	33	HTML elements, these are processed immediately; incomplete elements
				34	are saved in a buffer. To force processing of all unprocessed data,
				35	call the \code{close()} method.
				36
Guido van Rossum	470be14	1995-03-17 16:07:09 +0000	[diff] [blame]	37	Example: to parse the entire contents of a file, do\\
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	38	\code{parser.feed(open(file).read()); parser.close()}.
				39
				40	\item
				41	The interface to define semantics for HTML tags is very simple: derive
				42	a class and define methods called \code{start_\var{tag}()},
				43	\code{end_\var{tag}()}, or \code{do_\var{tag}()}. The parser will
				44	call these at appropriate moments: \code{start_\var{tag}} or
				45	\code{do_\var{tag}} is called when an opening tag of the form
				46	\code{<\var{tag} ...>} is encountered; \code{end_\var{tag}} is called
				47	when a closing tag of the form \code{<\var{tag}>} is encountered. If
				48	an opening tag requires a corresponding closing tag, like \code{<H1>}
				49	... \code{</H1>}, the class should define the \code{start_\var{tag}}
				50	method; if a tag requires no closing tag, like \code{<P>}, the class
				51	should define the \code{do_\var{tag}} method.
				52
				53	\end{itemize}
				54
				55	The module defines the following classes:
				56
				57	\begin{funcdesc}{HTMLParser}{}
				58	This is the most basic HTML parser class. It defines one additional
				59	entity name over the names defined by the \code{SGMLParser} base
				60	class, \code{\&bullet;}. It also defines handlers for the following
				61	tags: \code{<LISTING>...</LISTING>}, \code{<XMP>...</XMP>}, and
				62	\code{<PLAINTEXT>} (the latter is terminated only by end of file).
				63	\end{funcdesc}
				64
				65	\begin{funcdesc}{CollectingParser}{}
				66	This class, derived from \code{HTMLParser}, collects various useful
				67	bits of information from the HTML text. To this end it defines
				68	additional handlers for the following tags: \code{<A>...</A>},
				69	\code{<HEAD>...</HEAD>}, \code{<BODY>...</BODY>},
				70	\code{<TITLE>...</TITLE>}, \code{<NEXTID>}, and \code{<ISINDEX>}.
				71	\end{funcdesc}
				72
				73	\begin{funcdesc}{FormattingParser}{formatter\, stylesheet}
				74	This class, derived from \code{CollectingParser}, interprets a wide
				75	selection of HTML tags so it can produce formatted output from the
				76	parsed data. It is initialized with two objects, a \var{formatter}
				77	which should define a number of methods to format text into
				78	paragraphs, and a \var{stylesheet} which defines a number of static
				79	parameters for the formatting process. Formatters and style sheets
				80	are documented later in this section.
				81	\index{formatter}
				82	\index{style sheet}
				83	\end{funcdesc}
				84
				85	\begin{funcdesc}{AnchoringParser}{formatter\, stylesheet}
				86	This class, derived from \code{FormattingParser}, extends the handling
				87	of the \code{<A>...</A>} tag pair to call the formatter's
				88	\code{bgn_anchor()} and \code{end_anchor()} methods. This allows the
				89	formatter to display the anchor in a different font or color, etc.
				90	\end{funcdesc}
				91
				92	Instances of \code{CollectingParser} (and thus also instances of
				93	\code{FormattingParser} and \code{AnchoringParser}) have the following
				94	instance variables:
				95
				96	\begin{datadesc}{anchornames}
Guido van Rossum	d01c100	1995-03-07 10:12:59 +0000	[diff] [blame]	97	A list of the values of the \code{NAME} attributes of the \code{<A>}
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	98	tags encountered.
				99	\end{datadesc}
				100
				101	\begin{datadesc}{anchors}
				102	A list of the values of \code{HREF} attributes of the \code{<A>} tags
				103	encountered.
				104	\end{datadesc}
				105
				106	\begin{datadesc}{anchortypes}
Guido van Rossum	d01c100	1995-03-07 10:12:59 +0000	[diff] [blame]	107	A list of the values of the \code{TYPE} attributes of the \code{<A>}
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	108	tags encountered.
				109	\end{datadesc}
				110
				111	\begin{datadesc}{inanchor}
Guido van Rossum	d01c100	1995-03-07 10:12:59 +0000	[diff] [blame]	112	Outside an \code{<A>...</A>} tag pair, this is zero. Inside such a
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	113	pair, it is a unique integer, which is positive if the anchor has a
				114	\code{HREF} attribute, negative if it hasn't. Its absolute value is
				115	one more than the index of the anchor in the \code{anchors},
				116	\code{anchornames} and \code{anchortypes} lists.
				117	\end{datadesc}
				118
				119	\begin{datadesc}{isindex}
				120	True if the \code{<ISINDEX>} tag has been encountered.
				121	\end{datadesc}
				122
				123	\begin{datadesc}{nextid}
				124	The attribute list of the last \code{<NEXTID>} tag encountered, or
				125	an empty list if none.
				126	\end{datadesc}
				127
				128	\begin{datadesc}{title}
				129	The text inside the last \code{<TITLE>...</TITLE>} tag pair, or
				130	\code{''} if no title has been encountered yet.
				131	\end{datadesc}
				132
				133	The \code{anchors}, \code{anchornames} and \code{anchortypes} lists
				134	are ``parallel arrays'': items in these lists with the same index
				135	pertain to the same anchor. Missing attributes default to the empty
Guido van Rossum	d01c100	1995-03-07 10:12:59 +0000	[diff] [blame]	136	string. Anchors with neither a \code{HREF} nor a \code{NAME}
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	137	attribute are not entered in these lists at all.
				138
				139	The module also defines a number of style sheet classes. These should
Guido van Rossum	dc46c7f	1995-03-01 15:38:16 +0000	[diff] [blame]	140	never be instantiated --- their class variables are the only behavior
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	141	required. Note that style sheets are specifically designed for a
				142	particular formatter implementation. The currently defined style
				143	sheets are:
				144	\index{style sheet}
				145
				146	\begin{datadesc}{NullStylesheet}
Guido van Rossum	470be14	1995-03-17 16:07:09 +0000	[diff] [blame]	147	A style sheet for use on a dumb output device such as an \ASCII{}
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	148	terminal.
				149	\end{datadesc}
				150
				151	\begin{datadesc}{X11Stylesheet}
				152	A style sheet for use with an X11 server.
				153	\end{datadesc}
				154
				155	\begin{datadesc}{MacStylesheet}
				156	A style sheet for use on Apple Macintosh computers.
				157	\end{datadesc}
				158
				159	\begin{datadesc}{StdwinStylesheet}
				160	A style sheet for use with the \code{stdwin} module; it is an alias
				161	for either \code{X11Stylesheet} or \code{MacStylesheet}.
				162	\bimodindex{stdwin}
				163	\end{datadesc}
				164
				165	\begin{datadesc}{GLStylesheet}
				166	A style sheet for use with the SGI Graphics Library and its font
				167	manager (the SGI-specific built-in modules \code{gl} and \code{fm}).
				168	\bimodindex{gl}
				169	\bimodindex{fm}
				170	\end{datadesc}
				171
				172	Style sheets have the following class variables:
				173
				174	\begin{datadesc}{stdfontset}
				175	A list of up to four font definititions, respectively for the roman,
				176	italic, bold and constant-width variant of a font for normal text. If
				177	the list contains less than four font definitions, the last item is
				178	used as the default for missing items. The type of a font definition
				179	depends on the formatter in use; its only use is as a parameter to the
				180	formatter's \code{setfont()} method.
				181	\end{datadesc}
				182
				183	\begin{datadesc}{h1fontset}
				184	\dataline{h2fontset}
				185	\dataline{h3fontset}
				186	The font set used for various headers (text inside \code{<H1>...</H1>}
				187	tag pairs etc.).
				188	\end{datadesc}
				189
				190	\begin{datadesc}{stdindent}
				191	The indentation of normal text. This is measured in the ``native''
				192	units of the formatter in use; for some formatters these are
				193	characters, for others (especially those that actually support
				194	variable-spacing fonts) in pixels or printer points.
				195	\end{datadesc}
				196
				197	\begin{datadesc}{ddindent}
				198	The indentation used for the first level of \code{<DD>} tags.
				199	\end{datadesc}
				200
				201	\begin{datadesc}{ulindent}
				202	The indentation used for the first level of \code{<UL>} tags.
				203	\end{datadesc}
				204
				205	\begin{datadesc}{h1indent}
				206	The indentation used for level 1 headers.
				207	\end{datadesc}
				208
				209	\begin{datadesc}{h2indent}
				210	The indentation used for level 2 headers.
				211	\end{datadesc}
				212
				213	\begin{datadesc}{literalindent}
				214	The indentation used for literal text (text inside
				215	\code{<PRE>...</PRE>} and similar tag pairs).
				216	\end{datadesc}
				217
				218	Although no documented implementation of a formatter exists, the
				219	\code{FormattingParser} class assumes that formatters have a
				220	certain interface. This interface requires the following methods:
				221	\index{formatter}
				222
				223	\begin{funcdesc}{setfont}{fontspec}
				224	Set the font to be used subsequently. The \var{fontspec} argument is
				225	an item in a style sheet's font set.
				226	\end{funcdesc}
				227
				228	\begin{funcdesc}{flush}{}
				229	Finish the current line, if not empty, and begin a new one.
				230	\end{funcdesc}
				231
				232	\begin{funcdesc}{setleftindent}{n}
				233	Set the left indentation of the following lines to \var{n} units.
				234	\end{funcdesc}
				235
				236	\begin{funcdesc}{needvspace}{n}
				237	Require at least \var{n} blank lines before the next line. Implies
				238	\code{flush()}.
				239	\end{funcdesc}
				240
				241	\begin{funcdesc}{addword}{word\, space}
Guido van Rossum	d01c100	1995-03-07 10:12:59 +0000	[diff] [blame]	242	Add a \var{word} to the current paragraph, followed by \var{space}
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	243	spaces.
				244	\end{funcdesc}
				245
				246	\begin{datadesc}{nospace}
Guido van Rossum	470be14	1995-03-17 16:07:09 +0000	[diff] [blame]	247	If this instance variable is true, empty words should be ignored by
				248	\code{addword}. It should be set to false after a non-empty word has
				249	been added.
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	250	\end{datadesc}
				251
				252	\begin{funcdesc}{setjust}{justification}
				253	Set the justification of the current paragraph. The
				254	\var{justification} can be \code{'c'} (center), \code{'l'} (left
				255	justified), \code{'r'} (right justified) or \code{'lr'} (left and
				256	right justified).
				257	\end{funcdesc}
				258
				259	\begin{funcdesc}{bgn_anchor}{id}
				260	Begin an anchor. The \var{id} parameter is the value of the parser's
				261	\code{inanchor} attribute.
				262	\end{funcdesc}
				263
				264	\begin{funcdesc}{end_anchor}{id}
				265	End an anchor. The \var{id} parameter is the value of the parser's
				266	\code{inanchor} attribute.
				267	\end{funcdesc}
				268
Guido van Rossum	d01c100	1995-03-07 10:12:59 +0000	[diff] [blame]	269	A sample formatter implementation can be found in the module
				270	\code{fmt}, which in turn uses the module \code{Para}. These modules are
				271	not intended as standard library modules; they are available as an
				272	example of how to write a formatter.
Guido van Rossum	8675115	1995-02-28 17:14:32 +0000	[diff] [blame]	273	\ttindex{fmt}
				274	\ttindex{Para}