classification
Title: Windows HTML Help (chm) has fixed line length
Type: enhancement Stage: resolved
Components: Windows Versions: Python 3.8, Python 3.7, Python 3.6
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: terry.reedy Nosy List: gladman, inada.naoki, mdk, miss-islington, ned.deily, paul.moore, roelschroeven, steve.dower, terry.reedy, tim.golden, zach.ware
Priority: normal Keywords: patch

Created on 2018-06-29 23:04 by roelschroeven, last changed 2018-07-02 22:24 by terry.reedy. This issue is now closed.

Files
File name Uploaded Description Edit
python manual.PNG roelschroeven, 2018-06-29 23:04 Screenshot of Python documentation in Windows Help format
mdn-screenshot.png inada.naoki, 2018-06-30 16:14
NarrowCHM.png steve.dower, 2018-06-30 16:58
Pull Requests
URL Status Linked Edit
PR 8051 merged zach.ware, 2018-07-02 15:48
PR 8053 merged miss-islington, 2018-07-02 20:32
PR 8054 merged miss-islington, 2018-07-02 20:32
Messages (23)
msg320746 - (view) Author: Roel Schroeven (roelschroeven) Date: 2018-06-29 23:04
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.
msg320782 - (view) Author: (gladman) Date: 2018-06-30 14:00
I too much prefer the old behaviour since the fixed width is too narrow on my high resolution display
msg320783 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2018-06-30 14:10
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.
msg320785 - (view) Author: (gladman) Date: 2018-06-30 14:57
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.
msg320789 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2018-06-30 16:14
I think this is not only chm, but same to all HTML based (online, zipped html, maybe ePub).

max-width was added for readability.
https://github.com/python/python-docs-theme/issues/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.
msg320792 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2018-06-30 16:58
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.
msg320793 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2018-06-30 16:58
Let's try adding that screenshot again...
msg320794 - (view) Author: (gladman) Date: 2018-06-30 17:21
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
msg320799 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2018-06-30 18:06
Hmm, I want to deprecate chm because it uses legacy HTML (doesn't support UTF-8!), hard to build, hard to confirm issues....
msg320807 - (view) Author: Steve Dower (steve.dower) * (Python committer) Date: 2018-06-30 20:35
> I want to deprecate chm because it uses legacy HTML ...

Agreed, but not without a replacement.
msg320809 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-06-30 21:55
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 https://github.com/python/python-docs-theme/issues/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.)
msg320813 - (view) Author: Ned Deily (ned.deily) * (Python committer) Date: 2018-06-30 22:43
nosying Julien
msg320825 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2018-07-01 07:01
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.
msg320827 - (view) Author: Inada Naoki (inada.naoki) * (Python committer) Date: 2018-07-01 07:32
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.
msg320870 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-07-02 11:23
> 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?
msg320872 - (view) Author: (gladman) Date: 2018-07-02 11:30
I cannot build the Windows chm file but I am happy to test any versions that others can produce.
msg320882 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-02 13:36
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.
msg320896 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2018-07-02 15:50
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?
msg320902 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-02 17:34
Yes, I will add a blurb and merge and backport, when the patch is modified to change htmlhelp rather than htmlview.
msg320906 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-02 18:35
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.
msg320912 - (view) Author: Terry J. Reedy (terry.reedy) * (Python committer) Date: 2018-07-02 20:31
New changeset d824ca7f4df9b5f77cf02490b0e98c2408e21fee by Terry Jan Reedy (Zachary Ware) in branch 'master':
bpo-34006: Revert line length limit for Windows help docs (GH-8051)
https://github.com/python/cpython/commit/d824ca7f4df9b5f77cf02490b0e98c2408e21fee
msg320916 - (view) Author: miss-islington (miss-islington) Date: 2018-07-02 22:23
New changeset 4d02ad856f123d68712f542d55e8ff3393f00a8f by Miss Islington (bot) in branch '3.7':
bpo-34006: Revert line length limit for Windows help docs (GH-8051)
https://github.com/python/cpython/commit/4d02ad856f123d68712f542d55e8ff3393f00a8f
msg320917 - (view) Author: miss-islington (miss-islington) Date: 2018-07-02 22:23
New changeset 580c7db172a41d6311c0f3a7aec321597576e214 by Miss Islington (bot) in branch '3.6':
bpo-34006: Revert line length limit for Windows help docs (GH-8051)
https://github.com/python/cpython/commit/580c7db172a41d6311c0f3a7aec321597576e214
History
Date User Action Args
2018-07-02 22:24:43terry.reedysetstatus: open -> closed
assignee: terry.reedy
resolution: fixed
stage: patch review -> resolved
2018-07-02 22:23:48miss-islingtonsetmessages: + msg320917
2018-07-02 22:23:29miss-islingtonsetnosy: + miss-islington
messages: + msg320916
2018-07-02 20:32:54miss-islingtonsetpull_requests: + pull_request7662
2018-07-02 20:32:10miss-islingtonsetpull_requests: + pull_request7661
2018-07-02 20:31:45terry.reedysetmessages: + msg320912
2018-07-02 20:26:58jcasalesetnosy: - jcasale
2018-07-02 18:35:23terry.reedysetmessages: + msg320906
2018-07-02 17:34:13terry.reedysetmessages: + msg320902
2018-07-02 15:50:05zach.waresetmessages: + msg320896
2018-07-02 15:48:58zach.waresetkeywords: + patch
stage: patch review
pull_requests: + pull_request7659
2018-07-02 13:36:47terry.reedysetmessages: + msg320882
2018-07-02 11:30:10gladmansetmessages: + msg320872
2018-07-02 11:23:43mdksetmessages: + msg320870
2018-07-01 07:32:54inada.naokisetmessages: + msg320827
2018-07-01 07:01:48inada.naokisetmessages: + msg320825
2018-06-30 22:43:06ned.deilysetnosy: + ned.deily, mdk
messages: + msg320813
2018-06-30 21:55:13terry.reedysetnosy: + terry.reedy

messages: + msg320809
versions: + Python 3.6, Python 3.8
2018-06-30 20:35:54steve.dowersetmessages: + msg320807
2018-06-30 18:06:26inada.naokisetmessages: + msg320799
2018-06-30 17:21:43gladmansetmessages: + msg320794
2018-06-30 16:58:25steve.dowersetfiles: + NarrowCHM.png

messages: + msg320793
2018-06-30 16:58:05steve.dowersetmessages: + msg320792
2018-06-30 16:14:42inada.naokisetfiles: + mdn-screenshot.png
nosy: + inada.naoki
messages: + msg320789

2018-06-30 15:31:31jcasalesetnosy: + jcasale
2018-06-30 14:57:33gladmansetmessages: + msg320785
2018-06-30 14:10:23steve.dowersetmessages: + msg320783
2018-06-30 14:00:41gladmansetnosy: + gladman
messages: + msg320782
2018-06-29 23:04:41roelschroevencreate