Migration to Frame 5.5.
Checking in the PDF file. (This is questionable -- but we check in the
Postscript as well. Perhaps *both* should be removed from the CVS tree,
now everything is unbundled and we're distributing PS and PDF tarballs?)
Note -- the HTML generation using webmaker is currently broken. I'll
have to look into generating HTML from Frame...
Chunk.__repr__(), main(): Allow Chunk objects to get the buffer, to make the
representation contain text instead of a pair of indexes. This makes debugging
a little easier.
get some funky quoting of ']' in \item[...] to work right without having to
do really ugly things to the documents themselves.
There are a lot of things relating to indexing that are commented out;
parts need to be examined and dealt with with respect to changes in
LaTeX2HTML internals. I'll work with Ross to see what it takes to make
this sort of stuff reasonable.
order. LaTeX2HTML just doesn't do things the same way as LaTeX, and this
wasn't the fix.
Simplify the generated HTML for \file{}.
For \samp{}, use "..." instead of `...'; many fonts make that look pretty
bad. ;-(
now requires LaTeX2HTML 98.1p1 or newer (& and is still in progress).
This means that doing things to change the formatting of the manuals (at the
"normal user" level, like A4 paper), can happen in just one place, rather
than in each document file.
set up the indexsubitem to "(in module #1)" automatically. This reduces the
amount of markup needed in the module docs and, more importantly, makes it
o.k. to leave out in simple sections. \setindexsubitem{} can still be used
to change or reset it.
Make the table of contents "hot" for PDF output. No additional packages are
needed.
Move code for \b@code, \e@code into the macros for the verbatim environment
directly since they're not used elsewhere.
Derive the name of the modules .idx from the jobname.
Some clean ups.
and index "hot", etc.
Updated a comment about fncychap.
Removed unused minitoc support; I'm not going to use it. Something that makes
more sense with the Python lib ref can be done with reasonable effort, and can
wait a little while.
an empty index instead of touched. Note that for modindex.ind, this also
includes "\label{modindex}" so that the modindex.py script doesn't change
the set of labels in the document.
Be more consistent in use of $* in commands.
Also, I just ran across a [possible] minor glitch
in the library documentation for site.py. It says:
"For example, suppose sys.prefix and
sys.exec_prefix are set to `/usr/local'. The
Python 1.5 library is then installed in
`/usr/local/lib/python1.5'. Suppose this has a
subdirectory `/usr/local/python1.5/site-packages'
with three subsubdirectories, `foo', `bar' and
`spam'..."
I think it should be:
"...Suppose this has a subdirectory
`/usr/local/lib/python1.5/site-packages' with..."
^^^^
Use \newenvironment{envname} instead of \newcommand{\foo} &
\newcommand{\endfoo} (or \let\endfoo=...!) wherever reasonable.
Where {*desc} environment helper functions are not needed outside a
single environment definition, inline them.
Ensure that \seemodule{} and \seetext{} are only available within the
{seealso} environment.
Added "()" to the index entries for {funcdesc} and {cfuncdesc} environments.
Added {classdesc} environment which looks like the {funcdesc} environment
but doesn't add the parens in the index entry.
&do_cmd_email: Adjust to use a font similar to that used in the printed
representation.
&my_module_index_helper: Change to be only used for defining markup. Don't
prepend an <A NAME=...> to the result; use the containing page as
the module target for the index.
&ref_module_index_helper: New function. Used only for references to modules
described elsewhere. Generate the right target.
&init_myformat: Set the anchor_mark to an empty string; this avoids junky
" "'s in the text, which could really screw up vertical spacing
when that's all that's in a paragraph.
&do_cmd_seemodule: Insert markup to jump right to the referred-to module.
New targets: ???-all, for each document. This creates all formats of the
named document (DVI, HTML, PDF, PS).
l2hlib: Added commands to translate node*.html to use the \label{} stuff,
as supported by Jeremy's node2html.pl. This gives us mostly
bookmarkable nodes.
"alternate" rules for PDF generation doesn't ensure the PS files get
generated since distiller isn't used.
Switch to the "alternate" rules for PDF generation; this is starting to make
more sense than the distiller-based rule, and requires only free software.
I'm also confident it's working well (meaning I paged through all four
pdflatex-generated PDF files).
messy, but the thing seems to be working without bombing completely today.
Formatting lib.texi with TeX doesn't seem to do too badly, either!
Info formatting isn't quite there; that might just have to disappear this
time.
Code elsewhere in this file tests for the inclusion of the package and does
not need to be uncommented. Comments explain what they do and how to
disable them.
Added support for the optional "fancyhdr" package. If used, page footers
include chapter information on the left and section information on the right.
Both optional packages, "fancyhdr" and "times", are enabled by default. We
may want to disable them before shipping, but I'm not completely convinced.
(How many installations format their own documentation?)
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.
Fred Drake
Guido van Rossum
Jeremy Hylton