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) *  |
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 (methane) *  |
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) *  |
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) *  |
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 (methane) *  |
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) *  |
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) *  |
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) *  |
Date: 2018-06-30 22:43 |
nosying Julien
|
msg320825 - (view) |
Author: Inada Naoki (methane) *  |
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 (methane) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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) *  |
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
|
|
Date |
User |
Action |
Args |
2022-04-11 14:59:02 | admin | set | github: 78187 |
2018-07-02 22:24:43 | terry.reedy | set | status: open -> closed assignee: terry.reedy resolution: fixed stage: patch review -> resolved |
2018-07-02 22:23:48 | miss-islington | set | messages:
+ msg320917 |
2018-07-02 22:23:29 | miss-islington | set | nosy:
+ miss-islington messages:
+ msg320916
|
2018-07-02 20:32:54 | miss-islington | set | pull_requests:
+ pull_request7662 |
2018-07-02 20:32:10 | miss-islington | set | pull_requests:
+ pull_request7661 |
2018-07-02 20:31:45 | terry.reedy | set | messages:
+ msg320912 |
2018-07-02 20:26:58 | jcasale | set | nosy:
- jcasale
|
2018-07-02 18:35:23 | terry.reedy | set | messages:
+ msg320906 |
2018-07-02 17:34:13 | terry.reedy | set | messages:
+ msg320902 |
2018-07-02 15:50:05 | zach.ware | set | messages:
+ msg320896 |
2018-07-02 15:48:58 | zach.ware | set | keywords:
+ patch stage: patch review pull_requests:
+ pull_request7659 |
2018-07-02 13:36:47 | terry.reedy | set | messages:
+ msg320882 |
2018-07-02 11:30:10 | gladman | set | messages:
+ msg320872 |
2018-07-02 11:23:43 | mdk | set | messages:
+ msg320870 |
2018-07-01 07:32:54 | methane | set | messages:
+ msg320827 |
2018-07-01 07:01:48 | methane | set | messages:
+ msg320825 |
2018-06-30 22:43:06 | ned.deily | set | nosy:
+ ned.deily, mdk messages:
+ msg320813
|
2018-06-30 21:55:13 | terry.reedy | set | nosy:
+ terry.reedy
messages:
+ msg320809 versions:
+ Python 3.6, Python 3.8 |
2018-06-30 20:35:54 | steve.dower | set | messages:
+ msg320807 |
2018-06-30 18:06:26 | methane | set | messages:
+ msg320799 |
2018-06-30 17:21:43 | gladman | set | messages:
+ msg320794 |
2018-06-30 16:58:25 | steve.dower | set | files:
+ NarrowCHM.png
messages:
+ msg320793 |
2018-06-30 16:58:05 | steve.dower | set | messages:
+ msg320792 |
2018-06-30 16:14:42 | methane | set | files:
+ mdn-screenshot.png nosy:
+ methane messages:
+ msg320789
|
2018-06-30 15:31:31 | jcasale | set | nosy:
+ jcasale
|
2018-06-30 14:57:33 | gladman | set | messages:
+ msg320785 |
2018-06-30 14:10:23 | steve.dower | set | messages:
+ msg320783 |
2018-06-30 14:00:41 | gladman | set | nosy:
+ gladman messages:
+ msg320782
|
2018-06-29 23:04:41 | roelschroeven | create | |