Use \emph{} when referring to title of any of the Python manuals, like is
done in the other manuals.
In some places, use \emph{} or \dfn{} instead of ``...''.
Use \samp{} instead of \code{} when marking identifier prefixes.
Use logical markup wherever it made sense.
Fixed a bunch of typos.
In several places, use "---" instead of "--" to get the emdash.
Start sentences with capital letters and end them with periods, as needed.
"it's" --> "its" in many places: "it's" it *always* a contraction of "it is",
and "its" should always be used for the possessive.
"don't" --> "doesn't"
"should discards any" --> "should discard any"
In C function descriptions, use \var{} to mark parameters in the running
text instead of \code{}. This matches usage in the other manauls better,
and is more consistent with the formatting of the function signatures.
Lots of little changes to implement this.
Lots of fixups needed due to appearant heavy cut-&-paste in the orignal
document.
Mention that the exception objects may be either classes or strings,
depending on the use of -X; they were unequivocally stated to be strings
in the section "Standard Exceptions".
"mkvalue()" --> "Py_BuildValue()"
Description of PyNumber_Power() indicates that the third value is option,
but not how to indicate that it was omitted. Clarified.
Explain the behavior of PyString_FromStringAndSize() if the buffer is NULL.
Explain the Py_complex structure a little (tell what it's used for) and use
a {verbatim} environment for the structure definition itself.
Fix explanation of PyFile_SoftSpace().
Update the example version string to 1.5.
Combined the sections on defining new object types.
removes extra vertical space from the list of names, and makes the display
more similar to that used in the socket module, where several constants share
a description.
Explain what happens when a negative shift count is used (what exception).
Mark the title "Python Reference Manual" as \emph{}, for consistency.
"info" --> "information"
Tell more about the data attributes of file objects, using the {datadesc}
environment.
When refering the user to the language reference for information about
internal types, tell what internal types to expect information on.
&do_env_funcdescni: New functions. These support the non-indexing variety
of the {datadesc} and {funcdesc} environments.
There's still some flakiness with the new indexsubitem support, but that's
low priority.
in the running text.
For computed attribute and method names (where there's a \var{} part to
the name), use the non-indexing forms of \datadesc{} and \funcdesc{}.
This doesn't change the printed output, but removes 3 rejections from the
makeindex run and allows the LaTeX2HTML support to exclude these from the
index.
in the running text.
For computed method names (where there's a \var{} part to the name), use
the non-indexing form of \funcdesc{}. This doesn't change the printed
output, but removes 3 rejections from the makeindex run and allows the
LaTeX2HTML support to exclude these from the index.
&do_cmd_setindexsubitem: New function. Set the indexsubitem value from
\setindexsubitem{(...)}.
&do_env_opcodedesc: By default, don't index byte codes.
$INDEX_OPCODES: New flag. If true, index the byte codes. Default is off.
Normalize indentation to 4 spaces everywhere.
Minor nits.
Make all the indentations in {verbatim} environments have column 0 of the
listing in column 0 of the file.
Remove pagenumbering / pagestyle cruft.
Use more logical and less physical markup.
checkin of myformat.sty.
Change "\renewcommand{\indexsubitem}{(...)}" to "\setindexsubitem{(...)}"
everywhere.
Some other minor nits that I happened to come across.
Handle most (all?) of the page style / numbering magic here so the documents
don't have to do it individually.
Revise the \bcode / \ecode stuff so that the {verbatim} environment handles
it right directly. \bcode / \ecode will be completely removed from all files
(to be checked in momentarily).
Have the {verbatim} environment get the samples indented a bit; this
appearantly had been attempted in the old code, but didn't work because
paragraphs weren't indented.
Make all headers, from chapters on down to subparagraphs, have sans-serif
titles.
\setindexsubitem{}: New macro. Replaces \renewcommand{\indexsubitem{}(...)}
everywhere. This allows LaTeX2HTML to be made to work correctly for
this. That was near impossible with the old mechanisms.
For all {*desc} environments, make the name of the described thing bold as
well as monospaced.
{opcodedesc} environment: Don't index the byte code names; that doesn't seem
terribly useful, and there are a lot of them.
\var{}: More magic to make sure that the size is right even if embedded in
\file{} or some other macro that uses the sans-serif font in running
text.
\bfcode{}: New macro. Makes the font \code{} and bold. (Was unreasonable
using old LaTeX 2.09.)
\file{}: Adjust the size of the sans-serif font a little.
\email{}, \url{}, Make these use the same font as \file{}, but not the
surrounding single-quotes.
Update many comments.
Lots of minor nits and a little cleanliness.
\file{}: Use a sans-serif font for the filename itself.
Use the fncychap.sty package for fancy chapter headings.
Replace the \maketitle command with our own format. This is new, but it
looks a lot better than the old one.
Use \renewcommand instead of \def when extending or overriding standard LaTeX
commands. This makes it more LaTeX-like.
$STRIP_INDEX_TT: New flag. If set, the <tt>...</tt> around stuff in the index
is dropped. This is more O'Reilly-like.
&make_str_index_entry: Honor $STRIP_INDEX_TT.
&make_mod_index_entry: Honor $STRIP_INDEX_TT.
"""Combine similar index entries into an entry and subentries.
For example:
\item {foobar} (in module flotz), 23
\item {foobar} (in module whackit), 4323
becomes
\item {foobar}
\subitem in module flotz, 23
\subitem in module whackit, 4323
Note that an item which matches the format of a collapsable item but which
isn't part of a group of similar items is not modified.
"""
This results in a much more readable index, with less repitition of text;
especially for common method names.
\idxcode{}: New macro; used to mark things that would be \code{} for entry
into the index. This allows easily switching things around for the
font used in the index. (O'Reilly seems to keep it all plain roman
in the index. Looks reasonable in the Python documentation as well.)
\*index{}: Use \idxcode{} instead of {\codefont{}}.
use with function name provided as well.
Wrapped up PyArg_ParseTupleAndKeywords() description and provided example
based on Geoff Philbrick's example to the mailing list.
The main incompatibility is that the error reporting method is now
called as
parser.syntax_error(msg)
instead of
parser.syntax_error(lineno, msg)
This new version also has some code to deal with the <?xml?> and
<!DOCTYPE> tags at the start of an XML document.
The documentation has been updated, and a small test module has been
created.
Removed " (byte code instruction)" from the output of the {opcodedesc}
environment; this should only appear in the index (which it now does).
Removed some really old cruft related to otherwise removed debugging code.
(I *think* assignments to $* set & clear auto-flush of <STDOUT>, but don't
really remember. Removing them seems to not change anything!)
semantic concepts.
Added two new ones (not discussed with Guido:
\constant{}: Markup for constants defined in Python modules.
\cfunction{}: Markup for C functions; these should probably be distinguished
by font, but are not at this time (since they're typically \code{} at
this point).
Guido, you should probably look at this. The pickle documentation is out of
date; I don't see anything about the __reduce__() stuff or the
__safe_for_unpickling__ attribute.
These are intended to support semantic markup. There are a number
of places in the documentation where the exact meaning of an
indentifier marked \code{} in the running text is ambiguous (could
be a module or a class, a function or a method, etc.). These are
intended to clarify the intent of the identifier for processing
applications and more intelligent style processing.
isn't likely to be of much interest these days....)
{\tt ...} ==> \code{...}
Added \label{module-blat} for the two supporting modules.
Added index entries for referred-to modules.
longer used anywhere. Use the {*desc} environments instead.
\var{}: Ensure that the argument is always set in roman italic, in case an
alternate font is being used for code. These keeps the result of
\var{} consistent.
Some minor changes to allow easier exploration of alternate fonts for code in
the running text. Haven't changed the selected font; I haven't found one that
has everything required! (The best non-monospaced font so far was missing
the <, >, and | characters, or at least had them at the wrong locations. It
also allowed confusion between upper-case I and lower-case L.)
Added -9 option to gzip. This doesn't save much space, but it's "free" and
appreaciated by those with slow modems. (With these tarballs, that means
"those with modems"...!)
Remove the two tarballs in the clean target.
tarps - one-sided PostScript
tarps2 - two-sided PostScript, with ref.ps added as-is.
tardvi - yes, some people want the .dvi files
all-ps2 - Create the .ps files, but make sure the LaTeX openright option
is used in the \documentclass.
index. It works, it's ugly, and would probably have to be completely redone
if we changed latex2html versions. See the comments. ;-(
On the other hand, it works. ;-)
(Wait for myformat.perl checkin as well.)
For all generated cases of <strong>...</strong> (from this module), change to
<b>...</b>. This, from me? This is entirely to reduce the size of the
generated markup, which is more of an issue than semantics here. Since
<strong> isn't very meaningful anyway, this should be good.
{seealso} environment: Always start a new paragraph after the "See Also:"
line; this ensures that formatting is consistent for each subsequent
\see*{} item.
Consistency: Always use trailing "()" for function and method names in text.
Consistency: Always mark parameter names with \var{} in text.
Change questionable text about CORBA to definate text about XDR; "CORBA" isn't
enough to specify an external representation, and I'm not sure the comment is
right if we say "IIOP". I know its right about XDR if we only mention shared
object references and not recursive structures.
mode) and take advantage of changes in myformat.sty.
Change "C" to "\C{}" and "\code{NULL}" to "\NULL{}" everywhere for consistency
and control.
Started a description of PyArg_ParseTupleAndKeywords().
does the right thing if the openright option is given. Allows a
lot of crud to be removed from the document files' frontmatter
sections.
\endabstract Extend standard macro. (Called as \end{abstract}.)
Does the right thing if the openright option is given.
\optional Adjust to get the brackets right under latex2e.
gave the return type as part of the function field and used an empty return
type field. Fixed.
Function name field for PyLong_FromString() included an asterisk at the
beginning of the function name field; removed.
"\code{\\(}" produces "(" in the .dvi file and "<BR> (" in the latex2html
output (the font was right). Changed to "\code{{\e}(}" variation, which
fixes both. Breaks the .texi file generation again. Oh well.
Removed implied future availability of an info/texi version of the other
manuals (the word "yet").
Guido, you might want to check this file to see if any other changes are
required.
the info generation phases. Most of the errors had occurred in the makeinfo
step.
Commented out the warning at the top; this should still really be removed
before 1.5, but that's not my call. It generated problems for the info
conversion as well.
Lots of support for new macros defined in myformat.sty; including the new
indexing macros, seealso environment & friends, and the byte code instruction
support.
and ask the user for permission to set buffer-local variables depending on
the user's configuration. Not really needed since this doesn't get edited
often.
Bumped the version number to 1.5; date still needs to be set.
do_env_tableiii(), do_cmd_lineiii(): New functions to handle tableii and
tableiii environments.
Small changes to not add a superfluous space between a function name and the
comma in the index.
Added a \label{} for the module.
Fixed one minor grammatical nit: use plural pronoun to refer to a pair of
referents.
Include "()" when naming functions in the text.
is stable and the form is only defined in one place, since we do
some fancy footwork with the keys to separate the defining instance
of a module reference from other references in the HTML index.
make_index_entry(): Override the standard definition to use get_index_id().
make_str_index_entry(): Moved to myformat.perl; only needed there.
index_key_eq(): Override the standard definition. Add key transforms to
remove extra junk from the end of the keys; it was only there to
maintain ordering.
clean_key(): Remove key transform no longer needed at this stage, because
keeping it makes the sort unstable.
add_idx(): Add key transforms to undo the mess we do to separate a module's
defining and reference entries. Don't make the text bold.
my_module_index_helper(): Do the actual work for \*modindex{}, including
both the defining and reference forms.
make_str_index_entry(): Moved from .latex2html-init; it's really specific
to the presentation.
used to add index references for built-in and standard modules, respectively.
Modified \bimodindex{} and \stmodindex{} to make the page number bold, to
allow the defining instance of a module to stand out in the index.
Check-ins which fix improper use of \bimodindex{} and \stmodindex{} will be
made as fixes are applied. Misc. indexing updates will occur as a side
effect in some cases.
clean_key(): Override the standard LaTeX2HTML clean_key() to remove a
leading HTML tag, if present. This broke the indexes for the library
reference (at least) since many of the strings began with <code> or
something similar.
functions and constants together).
Make explicit datadesc sections for each of the constants which might appear,
and have a description of each. (Descriptions are based on the Linux
documentation and sources and the Solaris man pages.)
Hopefully Jeremy won't mind, because I didn't ask. ;-)
Use \file{} for file names.
Prefer \code{blat} and \emph{blat} to {\tt blat} and {\em blat}; this matches
current style in the Library Reference a bit better.
Made the example startup banner current. The version number should be
bumped before the next release.
Remove spurious underscore following book title. Added specific reference to
a Win32 networking book.
Changed \indexsubitem from (in module SocketServer) to (SocketServer protocol),
since it's talking about a protocol supported by a collection of classes.
Removed the large comment remaining from the template documentation
section; the template tells us to remove these once they're not needed.
Remove some trailing whitespace from VM instruction pseudo-code.
includes the string in the returned value instead of the dummy
filler character.
add_idx(): Override the latex2html function of the same name; this gets
the anchor properly embedded in the <dt> element, so the index
works in Grail too.
to use the opcodedesc environment.
Changed a \code{} to a \file{} near the start where a file is referenced.
Fixed a typo: "on" --> "one" in ROT_THREE description.
Wherever opcodes were referenced by name, use \code{OPCODE_NAME}; usage was
inconsistent. Ideally, another macro would be defined since these don't
represent code a programmer would type, but that's minor even for me. It'll
probably get converted automatically in the SGML conversion project. Whether
that matters or not isn't relevant at this point.
the libdis.tex file I'm about to check in.
I'm not sure this is really an optimal solution yet, but it may be the best
alternative. It avoids describing the instructions as either data items or
functions.
This change was discussed with Guido. (Guido: Take a look at the LaTeX
output for this; if this is reasonable I'll go ahead and update the perl
code in myformat.perl to match.)
messed up (but not checked in) version in my work files and didn't
notice before releasing 1.5 -- at least the distributed latex file
doesn't have the bogus warning about changed __init__ semantics.
compared to most, I'd say this section is fairly thorough.
Fixed \indexsubitem definitions for symbol and token module sub-documents.
Perhaps these should be moved to their own files, but they're awefully
small.
Makefile: Add dependency on libqueue.tex
lib.tex: Place the libqueue.tex documentation just after libthread.tex
since Queue depends on thread support in Python.
Fred Drake
Guido van Rossum
Barry Warsaw