cpython-lru_cache-weakref: Doc/lib/libformatter.tex annotate

annotate Doc/lib/libformatter.tex @ 4566:6403c94de50d legacy-trunk

Added safeguard against failure in __del__.

author	Guido van Rossum <guido@python.org>
date	Wed, 27 Nov 1996 19:39:58 +0000
parents	77954fe4376c
children	0a49d192506d

rev	line source
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	1 \section{Standard Module \sectcode{formatter}}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	2 \stmodindex{formatter}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	3
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	4 \renewcommand{\indexsubitem}{(in module formatter)}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	5
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	6 This module supports two interface definitions, each with mulitple
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	7 implementations. The \emph{formatter} interface is used by the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	8 \code{HTMLParser} class of the \code{htmllib} module, and the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	9 \emph{writer} interface is required by the formatter interface.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	10
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	11 Formatter objects transform an abstract flow of formatting events into
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	12 specific output events on writer objects. Formatters manage several
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	13 stack structures to allow various properties of a writer object to be
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	14 changed and restored; writers need not be able to handle relative
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	15 changes nor any sort of ``change back'' operation. Specific writer
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	16 properties which may be controlled via formatter objects are
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	17 horizontal alignment, font, and left margin indentations. A mechanism
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	18 is provided which supports providing arbitrary, non-exclusive style
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	19 settings to a writer as well. Additional interfaces facilitate
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	20 formatting events which are not reversible, such as paragraph
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	21 separation.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	22
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	23 Writer objects encapsulate device interfaces. Abstract devices, such
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	24 as file formats, are supported as well as physical devices. The
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	25 provided implementations all work with abstract devices. The
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	26 interface makes available mechanisms for setting the properties which
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	27 formatter objects manage and inserting data into the output.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	28
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	29
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	30 \subsection{The Formatter Interface}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	31
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	32 Interfaces to create formatters are dependent on the specific
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	33 formatter class being instantiated. The interfaces described below
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	34 are the required interfaces which all formatters must support once
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	35 initialized.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	36
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	37 One data element is defined at the module level:
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	38
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	39 \begin{datadesc}{AS_IS}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	40 Value which can be used in the font specification passed to the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	41 \code{push_font()} method described below, or as the new value to any
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	42 other \code{push_\var{property}()} method. Pushing the \code{AS_IS}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	43 value allows the corresponding \code{pop_\var{property}()} method to
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	44 be called without having to track whether the property was changed.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	45 \end{datadesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	46
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	47 The following attributes are defined for formatter instance objects:
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	48
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	49 \renewcommand{\indexsubitem}{(formatter object data)}
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	50
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	51 \begin{datadesc}{writer}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	52 The writer instance with which the formatter interacts.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	53 \end{datadesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	54
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	55
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	56 \renewcommand{\indexsubitem}{(formatter object method)}
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	57
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	58 \begin{funcdesc}{end_paragraph}{blanklines}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	59 Close any open paragraphs and insert at least \code{blanklines}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	60 before the next paragraph.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	61 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	62
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	63 \begin{funcdesc}{add_line_break}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	64 Add a hard line break if one does not already exist. This does not
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	65 break the logical paragraph.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	66 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	67
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	68 \begin{funcdesc}{add_hor_rule}{args\, *kw}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	69 Insert a horizontal rule in the output. A hard break is inserted if
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	70 there is data in the current paragraph, but the logical paragraph is
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	71 not broken. The arguments and keywords are passed on to the writer's
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	72 \code{send_line_break()} method.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	73 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	74
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	75 \begin{funcdesc}{add_flowing_data}{data}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	76 Provide data which should be formatted with collapsed whitespaces.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	77 Whitespace from preceeding and successive calls to
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	78 \code{add_flowing_data()} is considered as well when the whitespace
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	79 collapse is performed. The data which is passed to this method is
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	80 expected to be word-wrapped by the output device. Note that any
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	81 word-wrapping still must be performed by the writer object due to the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	82 need to rely on device and font information.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	83 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	84
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	85 \begin{funcdesc}{add_literal_data}{data}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	86 Provide data which should be passed to the writer unchanged.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	87 Whitespace, including newline and tab characters, are considered legal
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	88 in the value of \code{data}.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	89 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	90
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	91 \begin{funcdesc}{add_label_data}{format, counter}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	92 Insert a label which should be placed to the left of the current left
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	93 margin. This should be used for constructing bulleted or numbered
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	94 lists. If the \code{format} value is a string, it is interpreted as a
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	95 format specification for \code{counter}, which should be an integer.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	96 The result of this formatting becomes the value of the label; if
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	97 \code{format} is not a string it is used as the label value directly.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	98 The label value is passed as the only argument to the writer's
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	99 \code{send_label_data()} method. Interpretation of non-string label
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	100 values is dependent on the associated writer.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	101
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	102 Format specifications are strings which, in combination with a counter
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	103 value, are used to compute label values. Each character in the format
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	104 string is copied to the label value, with some characters recognized
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	105 to indicate a transform on the counter value. Specifically, the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	106 character ``\code{1}'' represents the counter value formatter as an
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	107 arabic number, the characters ``\code{A}'' and ``\code{a}'' represent
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	108 alphabetic representations of the counter value in upper and lower
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	109 case, respectively, and ``\code{I}'' and ``\code{i}'' represent the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	110 counter value in Roman numerals, in upper and lower case. Note that
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	111 the alphabetic and roman transforms require that the counter value be
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	112 greater than zero.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	113 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	114
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	115 \begin{funcdesc}{flush_softspace}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	116 Send any pending whitespace buffered from a previous call to
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	117 \code{add_flowing_data()} to the associated writer object. This
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	118 should be called before any direct manipulation of the writer object.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	119 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	120
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	121 \begin{funcdesc}{push_alignment}{align}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	122 Push a new alignment setting onto the alignment stack. This may be
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	123 \code{AS_IS} if no change is desired. If the alignment value is
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	124 changed from the previous setting, the writer's \code{new_alignment()}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	125 method is called with the \code{align} value.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	126 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	127
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	128 \begin{funcdesc}{pop_alignment}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	129 Restore the previous alignment.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	130 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	131
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	132 \begin{funcdesc}{push_font}{(size, italic, bold, teletype)}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	133 Change some or all font properties of the writer object. Properties
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	134 which are not set to \code{AS_IS} are set to the values passed in
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	135 while others are maintained at their current settings. The writer's
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	136 \code{new_font()} method is called with the fully resolved font
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	137 specification.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	138 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	139
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	140 \begin{funcdesc}{pop_font}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	141 Restore the previous font.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	142 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	143
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	144 \begin{funcdesc}{push_margin}{margin}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	145 Increase the number of left margin indentations by one, associating
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	146 the logical tag \code{margin} with the new indentation. The initial
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	147 margin level is \code{0}. Changed values of the logical tag must be
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	148 true values; false values other than \code{AS_IS} are not sufficient
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	149 to change the margin.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	150 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	151
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	152 \begin{funcdesc}{pop_margin}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	153 Restore the previous margin.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	154 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	155
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	156 \begin{funcdesc}{push_style}{*styles}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	157 Push any number of arbitrary style specifications. All styles are
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	158 pushed onto the styles stack in order. A tuple representing the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	159 entire stack, including \code{AS_IS} values, is passed to the writer's
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	160 \code{new_styles()} method.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	161 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	162
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	163 \begin{funcdesc}{pop_style}{\optional{n\code{ = 1}}}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	164 Pop the last \code{n} style specifications passed to
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	165 \code{push_style()}. A tuple representing the revised stack,
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	166 including \code{AS_IS} values, is passed to the writer's
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	167 \code{new_styles()} method.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	168 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	169
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	170 \begin{funcdesc}{set_spacing}{spacing}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	171 Set the spacing style for the writer.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	172 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	173
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	174 \begin{funcdesc}{assert_line_data}{\optional{flag\code{ = 1}}}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	175 Inform the formatter that data has been added to the current paragraph
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	176 out-of-band. This should be used when the writer has been manipulated
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	177 directly. The optional \code{flag} argument can be set to false if
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	178 the writer manipulations produced a hard line break at the end of the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	179 output.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	180 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	181
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	182
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	183 \subsection{Formatter Implementations}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	184
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	185 Two implementations of formatter objects are provided by this module.
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	186 Most applications may use one of these classes without modification or
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	187 subclassing.
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	188
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	189 \renewcommand{\indexsubitem}{(in module formatter)}
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	190
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	191 \begin{funcdesc}{NullFormatter}{\optional{writer\code{ = None}}}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	192 A formatter which does nothing. If \code{writer} is omitted, a
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	193 \code{NullWriter} instance is created. No methods of the writer are
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	194 called by \code{NullWriter} instances. Implementations should inherit
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	195 from this class if implementing a writer interface but don't need to
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	196 inherit any implementation.
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	197 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	198
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	199 \begin{funcdesc}{AbstractFormatter}{writer}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	200 The standard formatter. This implementation has demonstrated wide
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	201 applicability to many writers, and may be used directly in most
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	202 circumstances. It has been used to implement a full-featured
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	203 world-wide web browser.
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	204 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	205
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	206
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	207
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	208 \subsection{The Writer Interface}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	209
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	210 Interfaces to create writers are dependent on the specific writer
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	211 class being instantiated. The interfaces described below are the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	212 required interfaces which all writers must support once initialized.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	213 Note that while most applications can use the \code{AbstractFormatter}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	214 class as a formatter, the writer must typically be provided by the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	215 application.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	216
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	217 \renewcommand{\indexsubitem}{(writer object method)}
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	218
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	219 \begin{funcdesc}{new_alignment}{align}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	220 Set the alignment style. The \code{align} value can be any object,
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	221 but by convention is a string or \code{None}, where \code{None}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	222 indicates that the writer's ``preferred'' alignment should be used.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	223 Conventional \code{align} values are \code{'left'}, \code{'center'},
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	224 \code{'right'}, and \code{'justify'}.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	225 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	226
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	227 \begin{funcdesc}{new_font}{font}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	228 Set the font style. The value of \code{font} will be \code{None},
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	229 indicating that the device's default font should be used, or a tuple
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	230 of the form (\var{size}, \var{italic}, \var{bold}, \var{teletype}).
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	231 Size will be a string indicating the size of font that should be used;
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	232 specific strings and their interpretation must be defined by the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	233 application. The \var{italic}, \var{bold}, and \var{teletype} values
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	234 are boolean indicators specifying which of those font attributes
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	235 should be used.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	236 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	237
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	238 \begin{funcdesc}{new_margin}{margin, level}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	239 Set the margin level to the integer \code{level} and the logical tag
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	240 to \code{margin}. Interpretation of the logical tag is at the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	241 writer's discretion; the only restriction on the value of the logical
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	242 tag is that it not be a false value for non-zero values of
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	243 \code{level}.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	244 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	245
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	246 \begin{funcdesc}{new_spacing}{spacing}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	247 Set the spacing style to \code{spacing}.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	248 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	249
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	250 \begin{funcdesc}{new_styles}{styles}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	251 Set additional styles. The \code{styles} value is a tuple of
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	252 arbitrary values; the value \code{AS_IS} should be ignored. The
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	253 \code{styles} tuple may be interpreted either as a set or as a stack
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	254 depending on the requirements of the application and writer
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	255 implementation.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	256 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	257
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	258 \begin{funcdesc}{send_line_break}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	259 Break the current line.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	260 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	261
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	262 \begin{funcdesc}{send_paragraph}{blankline}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	263 Produce a paragraph separation of at least \code{blankline} blank
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	264 lines, or the equivelent. The \code{blankline} value will be an
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	265 integer.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	266 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	267
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	268 \begin{funcdesc}{send_hor_rule}{args\, *kw}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	269 Display a horizontal rule on the output device. The arguments to this
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	270 method are entirely application- and writer-specific, and should be
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	271 interpreted with care. The method implementation may assume that a
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	272 line break has already been issued via \code{send_line_break()}.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	273 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	274
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	275 \begin{funcdesc}{send_flowing_data}{data}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	276 Output character data which may be word-wrapped and re-flowed as
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	277 needed. Within any sequence of calls to this method, the writer may
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	278 assume that spans of multiple whitespace characters have been
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	279 collapsed to single space characters.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	280 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	281
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	282 \begin{funcdesc}{send_literal_data}{data}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	283 Output character data which has already been formatted
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	284 for display. Generally, this should be interpreted to mean that line
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	285 breaks indicated by newline characters should be preserved and no new
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	286 line breaks should be introduced. The data may contain embedded
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	287 newline and tab characters, unlike data provided to the
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	288 \code{send_formatted_data()} interface.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	289 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	290
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	291 \begin{funcdesc}{send_label_data}{data}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	292 Set \code{data} to the left of the current left margin, if possible.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	293 The value of \code{data} is not restricted; treatment of non-string
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	294 values is entirely application- and writer-dependent. This method
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	295 will only be called at the beginning of a line.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	296 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	297
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	298
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	299 \subsection{Writer Implementations}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	300
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	301 Three implementations of the writer object interface are provided as
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	302 examples by this module. Most applications will need to derive new
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	303 writer classes from the \code{NullWriter} class.
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	304
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	305 \renewcommand{\indexsubitem}{(in module formatter)}
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	306
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	307 \begin{funcdesc}{NullWriter}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	308 A writer which only provides the interface definition; no actions are
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	309 taken on any methods. This should be the base class for all writers
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	310 which do not need to inherit any implementation methods.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	311 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	312
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	313 \begin{funcdesc}{AbstractWriter}{}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	314 A writer which can be used in debugging formatters, but not much
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	315 else. Each method simply accounces itself by printing its name and
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	316 arguments on standard output.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	317 \end{funcdesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	318
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	319 \begin{funcdesc}{DumbWriter}{\optional{file\code{ = None}\optional{\, maxcol\code{ = 72}}}}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	320 Simple writer class which writes output on the file object passed in
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	321 as \code{file} or, if \code{file} is omitted, on standard output. The
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	322 output is simply word-wrapped to the number of columns specified by
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	323 \code{maxcol}. This class is suitable for reflowing a sequence of
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	324 paragraphs.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	325 \end{funcdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libformatter.tex @ 4566:6403c94de50d legacy-trunk