python.sty: \py@sigline correction

[smigaj]

BPO	1293790
Nosy	@freddrake, @birkenfeld
Files	python.sty.sigline.diff: python.sty patch

^{Note: these values reflect the state of the issue at the time it was migrated and might not reflect the current state.}

Show more details

GitHub fields:

assignee = 'https://github.com/freddrake'
closed_at = <Date 2007-08-23.20:35:46.256>
created_at = <Date 2005-09-17.12:54:38.000>
labels = ['docs']
title = 'python.sty: \\py@sigline correction'
updated_at = <Date 2007-08-23.20:35:46.254>
user = 'https://bugs.python.org/smigaj'

bugs.python.org fields:

activity = <Date 2007-08-23.20:35:46.254>
actor = 'georg.brandl'
assignee = 'fdrake'
closed = True
closed_date = <Date 2007-08-23.20:35:46.256>
closer = 'georg.brandl'
components = ['Documentation']
creation = <Date 2005-09-17.12:54:38.000>
creator = 'smigaj'
dependencies = []
files = ['6786']
hgrepos = []
issue_num = 1293790
keywords = ['patch']
message_count = 2.0
messages = ['48740', '55205']
nosy_count = 3.0
nosy_names = ['fdrake', 'georg.brandl', 'smigaj']
pr_nums = []
priority = 'normal'
resolution = 'out of date'
stage = None
status = 'closed'
superseder = None
type = None
url = 'https://bugs.python.org/issue1293790'
versions = []

[smigaj]

This patch corrects the following bug: the last line of
multiline headings created with environments like
classdesc, methoddesc... clash into the following text.

The source of this problem is typesetting the
"parameter" part of the heading inside a \parbox[t]
(parbox with its first ("top") line aligned with the
surrounding text). As a consequence, when the parameter
list takes multiple lines, all lines beneath the first
add up to the *depth* (not the *height*) of the parbox.
This causes TeX to treat the box as a very long
"descender", and place only \lineskip=1pt between the
bottom of the box and the following line.

The proposed solution is to shape the paragraph in a
"natural" way, using the \hangafter and \hangindent
macros instead of the \parbox command. Additionally,
inclusion of the \raggedright macro makes the argument
list left-justified, thus preventing excessive
stretching of interword spaces and hyphenation of
parameter names, which doesn't look good in most cases.

A test case follows (text taken from the PyX package
manual). Compare the space between both headings when
processed with the original and modified versions of
python.sty.

\documentclass{manual}
\begin{document}

some text\dots

\begin{classdesc}{histogram}{lineattrs=[], steps=0,
fromvalue=0, % {{{
frompathattrs=[], fillable=0,
autohistogramaxisindex=0,
autohistogrampointpos=0.5,
epsilon=1e-10}
This class is a style to plot histograms.
\var{lineattrs} is merged
with \code{defaultlineattrs} which is
\code{[deco.stroked]}. When
\var{steps} is set, the histrogram is plotted as
steps instead of
the default being a boxed histogram. \var{fromvalue}
is the baseline
value of the histogram. When set to \code{None}, the
histogram will
start at the baseline. When fromvalue is set,
\var{frompathattrs}
are the stroke attributes used to show the histogram
baseline path.
etc\dots
\end{classdesc}

\begin{classdesc}{barpos}{fromvalue=None,
frompathattrs=[], epsilon=1e-10} % {{{
This class is a hidden style providing position
information in a bar
graph. Those graphs need to contain a specialized
axis, namely a bar
axis. The data column for this bar axis is named
\code{Xname} where
\code{X} is an axis name. In the other graph
dimension the data
column name must be equal to an axis name. To plot
several bars in a
single graph side by side, you need to have a nested
bar axis and
provide a tuple as data for nested bar axis.
\end{classdesc}

\end{document}

[birkenfeld]

Obsolete now that we're using reST sources.