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

annotate Doc/lib/libformatter.tex @ 21467:4e35fa5d5708 legacy-trunk

Add documentation for the help() built-in; contributed by Ka-Ping Yee. This is part of SF patch #494622.

author	Fred Drake <fdrake@acm.org>
date	Tue, 18 Dec 2001 16:31:08 +0000
parents	e5c3ca7b5099
children

rev	line source
8918 acfffe14628e New section header style. Fred Drake <fdrake@acm.org> parents: 8716 diff changeset	1 \section{\module{formatter} ---
10250 47c11e827699 Give subsections reasonable file names in the HTML. Fred Drake <fdrake@acm.org> parents: 9851 diff changeset	2 Generic output formatting}
47c11e827699 Give subsections reasonable file names in the HTML. Fred Drake <fdrake@acm.org> parents: 9851 diff changeset	3
8716 760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7877 diff changeset	4 \declaremodule{standard}{formatter}
760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7877 diff changeset	5 \modulesynopsis{Generic output formatter and device interface.}
760dcf197048 Adjusted to use the new module synopsis support macros. Fred Drake <fdrake@acm.org> parents: 7877 diff changeset	6
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	7
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	8
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 10703 diff changeset	9 This module supports two interface definitions, each with multiple
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	10 implementations. The \emph{formatter} interface is used by the
10703 e4e800a78d8d Make internal module references hyperlinks wherever it makes sense. Fred Drake <fdrake@acm.org> parents: 10256 diff changeset	11 \class{HTMLParser} class of the \refmodule{htmllib} module, and the
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	12 \emph{writer} interface is required by the formatter interface.
7867 c76adaf512d6 Fix index entry for HTMLParser class. Fred Drake <fdrake@acm.org> parents: 7768 diff changeset	13 \withsubitem{(class in htmllib)}{\ttindex{HTMLParser}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	14
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	15 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	16 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	17 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	18 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	19 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	20 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	21 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	22 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	23 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	24 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	25 separation.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	26
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	27 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	28 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	29 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	30 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	31 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	32
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	33
10250 47c11e827699 Give subsections reasonable file names in the HTML. Fred Drake <fdrake@acm.org> parents: 9851 diff changeset	34 \subsection{The Formatter Interface \label{formatter-interface}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	35
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	36 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	37 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	38 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	39 initialized.
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	40
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	41 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	42
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	43
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	44 \begin{datadesc}{AS_IS}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	45 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	46 \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	47 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	48 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	49 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	50 \end{datadesc}
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	51
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	52 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	53
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	54
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	55 \begin{memberdesc}[formatter]{writer}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	56 The writer instance with which the formatter interacts.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	57 \end{memberdesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	58
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	59
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	60 \begin{methoddesc}[formatter]{end_paragraph}{blanklines}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	61 Close any open paragraphs and insert at least \var{blanklines}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	62 before the next paragraph.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	63 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	64
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	65 \begin{methoddesc}[formatter]{add_line_break}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	66 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	67 break the logical paragraph.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	68 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	69
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	70 \begin{methoddesc}[formatter]{add_hor_rule}{args, *kw}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	71 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	72 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	73 not broken. The arguments and keywords are passed on to the writer's
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	74 \method{send_line_break()} method.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	75 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	76
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	77 \begin{methoddesc}[formatter]{add_flowing_data}{data}
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 10703 diff changeset	78 Provide data which should be formatted with collapsed whitespace.
fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 10703 diff changeset	79 Whitespace from preceding and successive calls to
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	80 \method{add_flowing_data()} is considered as well when the whitespace
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	81 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	82 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	83 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	84 need to rely on device and font information.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	85 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	86
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	87 \begin{methoddesc}[formatter]{add_literal_data}{data}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	88 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	89 Whitespace, including newline and tab characters, are considered legal
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	90 in the value of \var{data}.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	91 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	92
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	93 \begin{methoddesc}[formatter]{add_label_data}{format, counter}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	94 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	95 margin. This should be used for constructing bulleted or numbered
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	96 lists. If the \var{format} value is a string, it is interpreted as a
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	97 format specification for \var{counter}, which should be an integer.
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	98 The result of this formatting becomes the value of the label; if
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	99 \var{format} is not a string it is used as the label value directly.
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	100 The label value is passed as the only argument to the writer's
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	101 \method{send_label_data()} method. Interpretation of non-string label
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	102 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	103
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	104 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	105 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	106 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	107 to indicate a transform on the counter value. Specifically, the
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	108 character \character{1} represents the counter value formatter as an
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 10703 diff changeset	109 Arabic number, the characters \character{A} and \character{a}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	110 represent alphabetic representations of the counter value in upper and
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	111 lower case, respectively, and \character{I} and \character{i}
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	112 represent the counter value in Roman numerals, in upper and lower
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	113 case. Note that the alphabetic and roman transforms require that the
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	114 counter value be greater than zero.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	115 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	116
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	117 \begin{methoddesc}[formatter]{flush_softspace}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	118 Send any pending whitespace buffered from a previous call to
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	119 \method{add_flowing_data()} to the associated writer object. This
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	120 should be called before any direct manipulation of the writer object.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	121 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	122
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	123 \begin{methoddesc}[formatter]{push_alignment}{align}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	124 Push a new alignment setting onto the alignment stack. This may be
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	125 \constant{AS_IS} if no change is desired. If the alignment value is
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	126 changed from the previous setting, the writer's \method{new_alignment()}
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	127 method is called with the \var{align} value.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	128 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	129
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	130 \begin{methoddesc}[formatter]{pop_alignment}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	131 Restore the previous alignment.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	132 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	133
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	134 \begin{methoddesc}[formatter]{push_font}{\code{(}size, italic, bold, teletype\code{)}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	135 Change some or all font properties of the writer object. Properties
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	136 which are not set to \constant{AS_IS} are set to the values passed in
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	137 while others are maintained at their current settings. The writer's
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	138 \method{new_font()} method is called with the fully resolved font
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	139 specification.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	140 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	141
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	142 \begin{methoddesc}[formatter]{pop_font}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	143 Restore the previous font.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	144 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	145
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	146 \begin{methoddesc}[formatter]{push_margin}{margin}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	147 Increase the number of left margin indentations by one, associating
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	148 the logical tag \var{margin} with the new indentation. The initial
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	149 margin level is \code{0}. Changed values of the logical tag must be
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	150 true values; false values other than \constant{AS_IS} are not
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	151 sufficient to change the margin.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	152 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	153
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	154 \begin{methoddesc}[formatter]{pop_margin}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	155 Restore the previous margin.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	156 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	157
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	158 \begin{methoddesc}[formatter]{push_style}{*styles}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	159 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	160 pushed onto the styles stack in order. A tuple representing the
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	161 entire stack, including \constant{AS_IS} values, is passed to the
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	162 writer's \method{new_styles()} method.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	163 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	164
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	165 \begin{methoddesc}[formatter]{pop_style}{\optional{n\code{ = 1}}}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	166 Pop the last \var{n} style specifications passed to
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	167 \method{push_style()}. A tuple representing the revised stack,
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	168 including \constant{AS_IS} values, is passed to the writer's
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	169 \method{new_styles()} method.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	170 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	171
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	172 \begin{methoddesc}[formatter]{set_spacing}{spacing}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	173 Set the spacing style for the writer.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	174 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	175
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	176 \begin{methoddesc}[formatter]{assert_line_data}{\optional{flag\code{ = 1}}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	177 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	178 out-of-band. This should be used when the writer has been manipulated
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	179 directly. The optional \var{flag} argument can be set to false if
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	180 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	181 output.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	182 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	183
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	184
10250 47c11e827699 Give subsections reasonable file names in the HTML. Fred Drake <fdrake@acm.org> parents: 9851 diff changeset	185 \subsection{Formatter Implementations \label{formatter-impls}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	186
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	187 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	188 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	189 subclassing.
77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	190
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	191 \begin{classdesc}{NullFormatter}{\optional{writer}}
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	192 A formatter which does nothing. If \var{writer} is omitted, a
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	193 \class{NullWriter} instance is created. No methods of the writer are
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	194 called by \class{NullFormatter} instances. Implementations should
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	195 inherit from this class if implementing a writer interface but don't
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	196 need to inherit any implementation.
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	197 \end{classdesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	198
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	199 \begin{classdesc}{AbstractFormatter}{writer}
4382 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
18574 346dcafc878b Minor changes to match the style guide. Fred Drake <fdrake@acm.org> parents: 13625 diff changeset	203 World Wide Web browser.
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	204 \end{classdesc}
4382 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
10250 47c11e827699 Give subsections reasonable file names in the HTML. Fred Drake <fdrake@acm.org> parents: 9851 diff changeset	208 \subsection{The Writer Interface \label{writer-interface}}
4382 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.
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	213 Note that while most applications can use the
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	214 \class{AbstractFormatter} class as a formatter, the writer must
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	215 typically be provided by the application.
4382 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
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	218 \begin{methoddesc}[writer]{flush}{}
4849 0a49d192506d (libformatter.tex): Document the flush() method on the writer. Fred Drake <fdrake@acm.org> parents: 4390 diff changeset	219 Flush any buffered output or device control events.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	220 \end{methoddesc}
4849 0a49d192506d (libformatter.tex): Document the flush() method on the writer. Fred Drake <fdrake@acm.org> parents: 4390 diff changeset	221
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	222 \begin{methoddesc}[writer]{new_alignment}{align}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	223 Set the alignment style. The \var{align} value can be any object,
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	224 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	225 indicates that the writer's ``preferred'' alignment should be used.
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	226 Conventional \var{align} values are \code{'left'}, \code{'center'},
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	227 \code{'right'}, and \code{'justify'}.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	228 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	229
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	230 \begin{methoddesc}[writer]{new_font}{font}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	231 Set the font style. The value of \var{font} will be \code{None},
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	232 indicating that the device's default font should be used, or a tuple
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	233 of the form \code{(}\var{size}, \var{italic}, \var{bold},
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	234 \var{teletype}\code{)}. Size will be a string indicating the size of
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	235 font that should be used; specific strings and their interpretation
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	236 must be defined by the application. The \var{italic}, \var{bold}, and
20202 e5c3ca7b5099 "boolean" --> "Boolean" (per the style guide). Fred Drake <fdrake@acm.org> parents: 18574 diff changeset	237 \var{teletype} values are Boolean values specifying which of those
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	238 font attributes should be used.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	239 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	240
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	241 \begin{methoddesc}[writer]{new_margin}{margin, level}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	242 Set the margin level to the integer \var{level} and the logical tag
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	243 to \var{margin}. Interpretation of the logical tag is at the
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	244 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	245 tag is that it not be a false value for non-zero values of
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	246 \var{level}.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	247 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	248
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	249 \begin{methoddesc}[writer]{new_spacing}{spacing}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	250 Set the spacing style to \var{spacing}.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	251 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	252
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	253 \begin{methoddesc}[writer]{new_styles}{styles}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	254 Set additional styles. The \var{styles} value is a tuple of
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	255 arbitrary values; the value \constant{AS_IS} should be ignored. The
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	256 \var{styles} tuple may be interpreted either as a set or as a stack
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	257 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	258 implementation.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	259 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	260
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	261 \begin{methoddesc}[writer]{send_line_break}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	262 Break the current line.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	263 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	264
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	265 \begin{methoddesc}[writer]{send_paragraph}{blankline}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	266 Produce a paragraph separation of at least \var{blankline} blank
13625 fdfd1049f36e Rob W. W. Hooft's spelling fixes for the Library Reference. I hope Thomas Wouters <thomas@python.org> parents: 10703 diff changeset	267 lines, or the equivalent. The \var{blankline} value will be an
9851 6c6ee3bb3fcc <writer>.send_paragraph(): Clarify what needs to be done by this Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	268 integer. Note that the implementation will receive a call to
6c6ee3bb3fcc <writer>.send_paragraph(): Clarify what needs to be done by this Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	269 \method{send_line_break()} before this call if a line break is needed;
6c6ee3bb3fcc <writer>.send_paragraph(): Clarify what needs to be done by this Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	270 this method should not include ending the last line of the paragraph.
6c6ee3bb3fcc <writer>.send_paragraph(): Clarify what needs to be done by this Fred Drake <fdrake@acm.org> parents: 8918 diff changeset	271 It is only responsible for vertical spacing between paragraphs.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	272 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	273
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	274 \begin{methoddesc}[writer]{send_hor_rule}{args, *kw}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	275 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	276 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	277 interpreted with care. The method implementation may assume that a
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	278 line break has already been issued via \method{send_line_break()}.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	279 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	280
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	281 \begin{methoddesc}[writer]{send_flowing_data}{data}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	282 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	283 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	284 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	285 collapsed to single space characters.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	286 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	287
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	288 \begin{methoddesc}[writer]{send_literal_data}{data}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	289 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	290 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	291 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	292 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	293 newline and tab characters, unlike data provided to the
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	294 \method{send_formatted_data()} interface.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	295 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	296
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	297 \begin{methoddesc}[writer]{send_label_data}{data}
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	298 Set \var{data} to the left of the current left margin, if possible.
1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	299 The value of \var{data} is not restricted; treatment of non-string
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	300 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	301 will only be called at the beginning of a line.
7768 8f177933c41f Use the new {methoddesc} and {memberdesc} environments as appropriate. Fred Drake <fdrake@acm.org> parents: 7712 diff changeset	302 \end{methoddesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	303
ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	304
10256 a4913bae9f93 Oops, used a \label twice - fix one of them. Fred Drake <fdrake@acm.org> parents: 10250 diff changeset	305 \subsection{Writer Implementations \label{writer-impls}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	306
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	307 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	308 examples by this module. Most applications will need to derive new
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	309 writer classes from the \class{NullWriter} class.
4390 77954fe4376c (libhtmllib.tex, libsgmllib.tex, libformatter.tex): Fred Drake <fdrake@acm.org> parents: 4382 diff changeset	310
7692 57a42183897d Use {classdesc} consistently. Fred Drake <fdrake@acm.org> parents: 7669 diff changeset	311 \begin{classdesc}{NullWriter}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	312 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	313 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	314 which do not need to inherit any implementation methods.
7692 57a42183897d Use {classdesc} consistently. Fred Drake <fdrake@acm.org> parents: 7669 diff changeset	315 \end{classdesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	316
7692 57a42183897d Use {classdesc} consistently. Fred Drake <fdrake@acm.org> parents: 7669 diff changeset	317 \begin{classdesc}{AbstractWriter}{}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	318 A writer which can be used in debugging formatters, but not much
7100 808479f85a29 Ouch: "accounces" ==> "announces" Fred Drake <fdrake@acm.org> parents: 5818 diff changeset	319 else. Each method simply announces itself by printing its name and
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	320 arguments on standard output.
7692 57a42183897d Use {classdesc} consistently. Fred Drake <fdrake@acm.org> parents: 7669 diff changeset	321 \end{classdesc}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	322
7712 0cbc9df882b6 Change "\," to just "," in function signatures. This is easier to maintain, Fred Drake <fdrake@acm.org> parents: 7692 diff changeset	323 \begin{classdesc}{DumbWriter}{\optional{file\optional{, maxcol\code{ = 72}}}}
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	324 Simple writer class which writes output on the file object passed in
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	325 as \var{file} or, if \var{file} is omitted, on standard output. The
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	326 output is simply word-wrapped to the number of columns specified by
7669 1f8c8e0bb5ef Logical markup. Fred Drake <fdrake@acm.org> parents: 7285 diff changeset	327 \var{maxcol}. This class is suitable for reflowing a sequence of
4382 ad41decc5fa9 (libformatter.tex): Added documentation for abstract writer/formatter model Fred Drake <fdrake@acm.org> parents: diff changeset	328 paragraphs.
7692 57a42183897d Use {classdesc} consistently. Fred Drake <fdrake@acm.org> parents: 7669 diff changeset	329 \end{classdesc}

Mercurial > cpython-lru_cache-weakref

annotate Doc/lib/libformatter.tex @ 21467:4e35fa5d5708 legacy-trunk