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.)

[ned-deily]

nosying Julien

[methane]

I prefer limiting width on browser, but I'm OK to remove limitation from chm files.

Rational:

Changing window size to control line width for readable length is bad UX because all modern browsers are tabbed. Or it may be impossible on iPad.

On the other hand, chm is file format only on Windows. And window is dedicated to Python doc. User can control width easily than browser.

[methane]

http://www.sphinx-doc.org/en/master/theming.html#builtin-themes

body_max_width (int or str): Maximal width of the document body. This can be an int, which is interpreted as pixels or a valid CSS dimension string such as ‘70em’ or ‘50%’. Use ‘none’ if you don’t want a width limit. Defaults may depend on the theme (often 800px).

Maybe, all you we need to do is adding "-D html_theme_options.body_max_width=none" option to sphinx-build when building html for htmlhelp, in Doc/make.bat.

I confirmed this option works with "make html", but I don't have environment for building htmlhelp for now.

[JulienPalard]

Maybe, all you we need to do is adding "-D html_theme_options.body_max_width=none" option to sphinx-build when building html for htmlhelp, in Doc/make.bat.

As far as I can see, it's the right solution, but I have no windows machine to test it.

I checked in PEP-101, and they're using make.bat htmlhelp on windows to build the chm files.

Can someone test it?

[gladman]

I cannot build the Windows chm file but I am happy to test any versions that others can produce.

[terryjreedy]

Zach, I believe you helped write make.bat. I can run 'make htmlhelp', but I don't know how to modify make.bat to add option "-D html_theme_options.body_max_width=none" specifically when building htmlhelp.

[zware]

Terry: PR8051 should do that, but I haven't tested it. Would you mind taking over the PR if it does what you want it to?

[terryjreedy]

Yes, I will add a blurb and merge and backport, when the patch is modified to change htmlhelp rather than htmlview.

[terryjreedy]

The patch now works for me and can be tested. The blurb is added and can be reviewed. I expect to merge within a day.

[terryjreedy]

New changeset d824ca7 by Terry Jan Reedy (Zachary Ware) in branch 'master':
bpo-34006: Revert line length limit for Windows help docs (GH-8051)
d824ca7

[miss-islington]

New changeset 4d02ad8 by Miss Islington (bot) in branch '3.7':
bpo-34006: Revert line length limit for Windows help docs (GH-8051)
4d02ad8

[miss-islington]

New changeset 580c7db by Miss Islington (bot) in branch '3.6':
bpo-34006: Revert line length limit for Windows help docs (GH-8051)
580c7db