Output of help(...) is wider than 80 characters

[casevh]

BPO	9739
Nosy	@terryjreedy, @amauryfa, @giampaolo
Files	doc_width1.diff: Patch for math, cmath, tuple, datetime, and time. math_docstring.diff: Correct doc strings for math module.

^{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 = None
closed_at = None
created_at = <Date 2010-09-02.05:01:38.124>
labels = ['type-bug', 'docs']
title = 'Output of help(...) is wider than 80 characters'
updated_at = <Date 2019-03-15.23:35:14.271>
user = 'https://bugs.python.org/casevh'

bugs.python.org fields:

activity = <Date 2019-03-15.23:35:14.271>
actor = 'BreamoreBoy'
assignee = 'docs@python'
closed = False
closed_date = None
closer = None
components = ['Documentation']
creation = <Date 2010-09-02.05:01:38.124>
creator = 'casevh'
dependencies = []
files = ['18707', '18761']
hgrepos = []
issue_num = 9739
keywords = ['patch']
message_count = 7.0
messages = ['115359', '115361', '115415', '115519', '115655', '220984', '221058']
nosy_count = 5.0
nosy_names = ['terry.reedy', 'amaury.forgeotdarc', 'casevh', 'giampaolo.rodola', 'docs@python']
pr_nums = []
priority = 'normal'
resolution = None
stage = 'patch review'
status = 'open'
superseder = None
type = 'behavior'
url = 'https://bugs.python.org/issue9739'
versions = ['Python 3.5']

[casevh]

In several modules, the output of help(some_module) is wider than 80 characters. This results in extra line wrapping and incorrect formatting of the help text.

I've attached a single patch (doc_width1.diff) that corrects the issue for math, cmath, tuple, datetime, and time modules. I can continue to create patches for a few modules at a time, or I can create patches for individual modules.

I'm not changing any text, only adding \n as needed.

[amauryfa]

Aren't there tools that extract only the first line of help?

[casevh]

According to PEP-7, the first line of the doc string should contain the signature of the function, then there should be a blank line, and then the rest of the doc string. There may be tools that extract the signature line. The patch just decreases the line length of the remaining lines of the doc string so they don't wrap when displayed on an 80 character wide terminal window.

For an example, look at the text for modf(...) in help(math).

I just noticed that the math module uses "modf(x)" for the signature line but PEP-7 recommends including the return type, say "modf(x) -> (frac, int)".

The simplest change would be to fix the wrapping issue and leave the signature line alone. It would be more effort to make all the doc strings PEP-7 compliant by standardizing the signature line to include the return type.

I'm willing to work through the standard library and create patches for either option.

[terryjreedy]

Although this is not a problem in IDLE where the window can easily be expanded beyond 80 chars, I am in favor of the idea for other uses. The command line interpreter on Windows defaults to 80 chars and is not so easy to change, and one must be admin to make the change 'permanent' (until the next install reverts the change). In particular, the 82 char line for math.trun results in 'd.' of 'method.' wrapped to a line by itself with no indent. Pretty ugly.

However, I am puzzled why you edited the 74 char line for math.modf, which displays as 78 chars with a 4 char indent. This
'''\
Return the fractional and integer parts of x. Both results carry the sign'''
displays fine on one line as is. The tracker, unfortunately, displays
123456789012345678901234567890123456789012345678901234567890123456789012 only 72 chars.
of x and are floats.

I agree that
trunc(x:Real) -> Integral
is more helpful (and therefore better) than
modf(x)

For something like
-"T.index(value, [start, [stop]]) -> integer -- return first index of value.\n"

I personally think '->' and 'return are redundant, so I would argue that this could be shortened to
-"T.index(value, [start, [stop]]) -> integer (first index of value).\n"
instead of by wrapping.

Since I am not yet in a position to apply patches, I am not (yet) in a position to tell you whether or how to produce more patches.

[casevh]

I edited the doc string for math.modf since an indent of 8 spaces is used for the doc string with help(math). An indent of 4 spaces is used with help(math.modf).

I've attached a new patch for just the math module that includes the return type as part of signature line, corrects the width issues, and uses a consistent format for defining the doc strings.

[BreamoreBoy]

@terry is this something you could take on?

[terryjreedy]

Perhaps after the Google Summer of Code project is done (mid-August).