Windows HTML Help (chm) has fixed line length

[roelschroeven]

BPO	34006
Nosy	@terryjreedy, @pfmoore, @tjguk, @ned-deily, @methane, @zware, @zooba, @JulienPalard, @miss-islington
PRs	bpo-34006: Set SPHINXOPTS for htmlhelp #8051 [3.7] bpo-34006: Revert line length limit for Windows help docs (GH-8051) #8053 [3.6] bpo-34006: Revert line length limit for Windows help docs (GH-8051) #8054
Files	python manual.PNG: Screenshot of Python documentation in Windows Help format mdn-screenshot.png NarrowCHM.png

^{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/terryjreedy'
closed_at = <Date 2018-07-02.22:24:43.901>
created_at = <Date 2018-06-29.23:04:41.161>
labels = ['3.8', 'type-feature', '3.7', 'OS-windows']
title = 'Windows HTML Help (chm) has fixed line length'
updated_at = <Date 2018-07-02.22:24:43.900>
user = 'https://bugs.python.org/roelschroeven'

bugs.python.org fields:

activity = <Date 2018-07-02.22:24:43.900>
actor = 'terry.reedy'
assignee = 'terry.reedy'
closed = True
closed_date = <Date 2018-07-02.22:24:43.901>
closer = 'terry.reedy'
components = ['Windows']
creation = <Date 2018-06-29.23:04:41.161>
creator = 'roelschroeven'
dependencies = []
files = ['47660', '47661', '47662']
hgrepos = []
issue_num = 34006
keywords = ['patch']
message_count = 23.0
messages = ['320746', '320782', '320783', '320785', '320789', '320792', '320793', '320794', '320799', '320807', '320809', '320813', '320825', '320827', '320870', '320872', '320882', '320896', '320902', '320906', '320912', '320916', '320917']
nosy_count = 11.0
nosy_names = ['terry.reedy', 'paul.moore', 'tim.golden', 'ned.deily', 'methane', 'zach.ware', 'steve.dower', 'gladman', 'mdk', 'miss-islington', 'roelschroeven']
pr_nums = ['8051', '8053', '8054']
priority = 'normal'
resolution = 'fixed'
stage = 'resolved'
status = 'closed'
superseder = None
type = 'enhancement'
url = 'https://bugs.python.org/issue34006'
versions = ['Python 3.6', 'Python 3.7', 'Python 3.8']

[roelschroeven]

Since 3.7 (and possibly 3.6.6) the .chm Windows help file uses fixed line lenghts, instead of properly adapting to the window width. Please revert to the old behavior.

See screenshot: the empty space on the right is just silly.

[gladman]

I too much prefer the old behaviour since the fixed width is too narrow on my high resolution display

[zooba]

I agree.

I don't think we deliberately changed anything here. Possibly the sphinx theme has some CSS that doesn't work well in IE, so that should be the starting point for someone to look.

[gladman]

Comparing the basic.css files for the 3.6.5 chm file and the 3.6.6 chm file shows that the latter has the following body style definition that the earlier versions don't have:

/* -- general body styles ----------------------------- */

div.body {
min-width: 450px;
max-width: 800px;
}

So it seems that the later versions set a maximum width that is not present in the earlier versions.

[methane]

I think this is not only chm, but same to all HTML based (online, zipped html, maybe ePub).

max-width was added for readability.
python/python-docs-theme#4

There are no absolute right answer and there are many personal preferences.
But limiting line width is considered good idea for many web sites.

https://graphicdesign.stackexchange.com/questions/13724/recommended-column-width-for-text-reading-digital-vs-printed

https://pearsonified.com/2011/12/golden-ratio-typography.php

For example, MDN limits line length too.

[zooba]

It's pretty annoying when HTML Help doesn't properly handle your screen scaling settings (guessing my new screenshot looks like gladman's).

I'd love to have a new HTML Help program for our docs that could handle this better, but there's nothing in the same class (in particular, where "startup time" is a feature - there are plenty of browsers that take many seconds and GB of RAM, but I don't want to go there).

Maybe we can add an override for the CHM somehow? I don't know Sphinx well enough to be able to do this.

[zooba]

Let's try adding that screenshot again...

[gladman]

You are exactly right Steve - that is very close to what I am seeing and it is often quite hard to read. For example, where function prototypes are displayed on two lines, it takes me a lot longer to parse and understand them when compared with a situation where they are displayed on a single line.

Although I agree with those who claim that there is an ideal line length for readability, I really don't think this can be predicted in advance since it is inevitably varies widely from one user to another. So I remain convinced that it is better to use a design that dynamically adjusts to the width available.

Brian

[methane]

Hmm, I want to deprecate chm because it uses legacy HTML (doesn't support UTF-8!), hard to build, hard to confirm issues....

[zooba]

I want to deprecate chm because it uses legacy HTML ...

Agreed, but not without a replacement.

[terryjreedy]

The change is also in 3.6.6, released the same day as 3.7.0. It was done intentionally, without, as far as I know, consulting Python doc users. Users were previously free to select the max line width they wanted.

On python/python-docs-theme#4, on April 26, Julien Palard noted that the change was made in sphinx-doc and was automatically incorporated into python-docs when the sphinx-doc version was updated. So a new python-docs-theme issue would have to be opened to avoid or modify the change. Issue 4 ended there, though I have added a note.

I see about what roelschroeven does, 80 char lines, but the 50 char line are pretty bad.

Anyway, this tracker is for patching the cpython repository. This should only be left open if there is a possibility of patching the code that generates the chm file to, for instance, remove max-lines.

Side-notes: 'Python x.y Manuals' open full-screen. I think part-screen would be better. 'Python 3.7 Module Docs' is duplicated under Python 3.7.

I believe a chm replacement could be written with HTMLParser and tkinter. IDLE parses a subset of the html used in our docs to display a local (html-encoded) copy of https://docs.python.org/3/library/idle.html in a tk Text (without the sidebar). The result is nearly identical to what I see in Firefox. (At present, astral chars would have to be replaces by their escapes.)