classification
Title: Enhance venv activate commands readability
Type: Stage: resolved
Components: Documentation Versions:
process
Status: closed Resolution: fixed
Dependencies: Superseder:
Assigned To: mdk Nosy List: lisroach, mdk, pablogsal, rhettinger, steven.daprano
Priority: normal Keywords: patch

Created on 2018-11-12 21:57 by mdk, last changed 2018-11-21 08:51 by rhettinger. This issue is now closed.

Pull Requests
URL Status Linked Edit
PR 10604 merged mdk, 2018-11-19 21:04
PR 10629 merged miss-islington, 2018-11-21 08:40
PR 10630 merged miss-islington, 2018-11-21 08:40
Messages (9)
msg329762 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-11-12 21:57
I'd like to enhance the readability of the "venv activation commands" in library/venv.html, my students are often confused by it, sometimes they copy the angle brackets, sometime even the prompt.

I don't think we can fix everything, but maybe enhance a bit, I ran a few tests.

Before modification: https://screenshotscdn.firefoxusercontent.com/images/77cf6612-1934-4a3b-9376-87a012a76bc3.png

First try with a :file:, not better: https://screenshotscdn.firefoxusercontent.com/images/db4e1191-a740-4828-b53a-ccc4a8d33dae.png

Second try, simply double backquotes:
https://screenshotscdn.firefoxusercontent.com/images/d6be92a1-e4af-40f5-9281-d9c09d8a0908.png

Third try using bold but it hurt the eyes:
https://screenshotscdn.firefoxusercontent.com/images/6fb1026f-064b-41dd-822b-3b258e37a85e.png

4th try using simply capslock, maybe better:
https://screenshotscdn.firefoxusercontent.com/images/9e9c3f7b-639c-4f26-abcc-20948e15a65d.png

5th try using capslock and italics, I like it:
https://screenshotscdn.firefoxusercontent.com/images/b5ae5582-1706-4ea9-a702-910daf2c69bc.png

Someone on #python-fr proposed https://framapic.org/XnBQZcJVRlZw/F05D7I8nSKd0.png (rendered from markdown in github). I like it but it would require a specific role to render bold-italic in code block.
msg329763 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-11-12 21:58
Forgot to mention, the bold and italics one were done using unicode mathematical characters, they are not properly rendered in PDFs so we can't use them as is: https://mdk.fr/pdf.png
msg329767 - (view) Author: Steven D'Aprano (steven.daprano) * (Python committer) Date: 2018-11-12 22:24
https://docs.python.org/3/library/venv.html

> my students are often confused by it, sometimes they copy the angle brackets, sometime even the prompt.

Learning to recognise placeholders and the prompt is an essential part of learning to code, and a stage that everyone has to go through. Replacing plain text markup with styled formatting doesn't change that, but it does make it harder for the blind or visually impaired who are using screen-readers, or those who prefer to use a plain text interface with no support for bold/italic.

How do your enhancements look in w3m, links or linx? The current design renders nicely in plain text on links. (I haven't checked the other two.)


> I ran a few tests.

What sort of tests? Usability tests? What results did you get?


> Someone on #python-fr proposed https://framapic.org/XnBQZcJVRlZw/F05D7I8nSKd0.png

Link doesn't work for me. I get a blank page.
msg329768 - (view) Author: Lisa Roach (lisroach) * (Python committer) Date: 2018-11-12 22:33
Using plain angle brackets is common placeholder notation, and I think changing it to something different might be confusing to those who are familiar with the pattern. I have also seen plenty of people copying and pasting the wrong things because of this notation, but I agree with Steven that it is a part of the learning process that we all go through.

Perhaps just adding the line '<venv> must be replaced by the path of the directory containing the virtual environment' would suffice to clarify?
msg330116 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-19 21:59
I concur with Lisa that this is something the people need to learn (that is why they're taking a class).  

FWIW, I've seen people copy square brackets for optional arguments, "mypow(base[, exp])" and angle brackets for syntax, "<pos_result> if <cond> else <neg_result>".  We also see it with the ellipsis.

Accordingly, there should be a FAQ entry or tutorial section on meta-syntactic variable and syntax placeholders.   The would also be a good place to cover the confusing "/" and "*" notations generated by the argument clinic:  __getattribute__(self, name, /).

FWIW, if your students are also cutting-and-pasting the prompt, this is clearly an education issue and not an issue with the venv docs.
msg330176 - (view) Author: Julien Palard (mdk) * (Python committer) Date: 2018-11-21 07:49
Hi Raymond,

I'm mentionning I've spotted the issue in my class just to say "it happen that newcomers don't get it, I've seen it". As I've seen it I want to fix it. I don't want to fix it only in my course (it does not scale) I want to fix it for everybody.

So what I'm trying to do in this issue (same with https://bugs.python.org/issue35200), is to ease the learning of newcomers *not* taking a course, those only relying on the official tutorial and documentation.

I don't have numbers, but I don't think all Python newcomers are taking Python courses, some are relying to tutorials (maybe our tutorial?) and the doc.

I just added a sentense in the linked PR (https://github.com/python/cpython/pull/10604/files), as Lisa said it should be enough.
msg330183 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-21 08:40
New changeset d936a8f8e0964de1147656f1435532f0170f8b6c by Raymond Hettinger (Julien Palard) in branch 'master':
bpo-35221: Additional hint that the placeholder is to be replaced. (GH-10604)
https://github.com/python/cpython/commit/d936a8f8e0964de1147656f1435532f0170f8b6c
msg330184 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-21 08:48
New changeset 7af2144e558a0268b1aa20bb88046716c89f987d by Raymond Hettinger (Miss Islington (bot)) in branch '3.6':
bpo-35221: Additional hint that the placeholder is to be replaced. (GH-10604) (GH-10630)
https://github.com/python/cpython/commit/7af2144e558a0268b1aa20bb88046716c89f987d
msg330185 - (view) Author: Raymond Hettinger (rhettinger) * (Python committer) Date: 2018-11-21 08:48
New changeset d170e594b2736c579d12b96b129a8e58975a9c0a by Raymond Hettinger (Miss Islington (bot)) in branch '3.7':
bpo-35221: Additional hint that the placeholder is to be replaced. (GH-10604) (GH-10629)
https://github.com/python/cpython/commit/d170e594b2736c579d12b96b129a8e58975a9c0a
History
Date User Action Args
2018-11-21 08:51:40rhettingersetstatus: open -> closed
resolution: fixed
stage: patch review -> resolved
2018-11-21 08:48:59rhettingersetmessages: + msg330185
2018-11-21 08:48:46rhettingersetmessages: + msg330184
2018-11-21 08:40:28miss-islingtonsetpull_requests: + pull_request9878
2018-11-21 08:40:21miss-islingtonsetpull_requests: + pull_request9877
2018-11-21 08:40:16rhettingersetmessages: + msg330183
2018-11-21 07:49:25mdksetmessages: + msg330176
2018-11-19 21:59:41rhettingersetnosy: + rhettinger
messages: + msg330116
2018-11-19 21:04:22mdksetkeywords: + patch
stage: patch review
pull_requests: + pull_request9847
2018-11-13 03:24:47pablogsalsetnosy: + pablogsal
2018-11-12 22:33:35lisroachsetnosy: + lisroach
messages: + msg329768
2018-11-12 22:24:04steven.dapranosetnosy: + steven.daprano
messages: + msg329767
2018-11-12 21:58:44mdksetmessages: + msg329763
2018-11-12 21:57:54mdkcreate