[issue20265] Bring Doc/using/windows up to date

New submission from Zachary Ware: Doc/using/windows still mentions DOS, Windows 3.x, and Python 2.1, and that's just in the first short section. This is a catch-all issue for making sure that page is up to date. ---------- assignee: docs@python components: Documentation, Windows keywords: easy messages: 208136 nosy: docs@python, zach.ware priority: normal severity: normal stage: needs patch status: open title: Bring Doc/using/windows up to date type: enhancement versions: Python 2.7, Python 3.3, Python 3.4 _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Roundup Robot added the comment: New changeset fc52b657bcd9 by Zachary Ware in branch '3.3': Issue #20265: Updated some parts of the Using Windows document. http://hg.python.org/cpython/rev/fc52b657bcd9 New changeset 5a9171e70573 by Zachary Ware in branch 'default': Issue #20265: Merge with 3.3 http://hg.python.org/cpython/rev/5a9171e70573 ---------- nosy: +python-dev _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Ezio Melotti added the comment: Are you just going to reference this issue whenever you update that file, or do you have a plan? ---------- nosy: +ezio.melotti _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Zachary Ware added the comment: The plan is to eventually have enough time to pick through the file and make sure everything is actually up to date :). >From just a quick glance, here's a couple of the things that still need to be done: - all of the external links should be checked for whether they are up to date (and still relevant to current Python) - the 'Excursus: Setting environment variables' section needs a major overhaul ('autoexec.bat' isn't used (or at least not recommended) anymore, among other things) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Westley Martínez added the comment: I personally like this page about environment variables: http://www.computerhope.com/issues/ch000549.htm It is clear, concise, and has pretty pictures. However, it does not address Windows 8. Since Windows 8 is becoming more popular everyday, and since it is rather odd and difficult to configure, we should update the article to include stuff for Windows 8. Unfortunately, I don't have Windows 8, so I can't help there. ---------- nosy: +westley.martinez _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Zachary Ware added the comment: Windows 8 (or at least 8.1) doesn't seem to be too far off from the directions on that site. If you're proficient enough to change an environment variable in Windows 7, chances are good you can figure it out on Windows 8(.1). If you're not, chances are good you probably shouldn't :) Either way, I think that these days giving instructions on how to set an environment variable is beyond the scope of the Python documentation. We ought to just say "here's the environment variables that Python cares about, and here's what they do" and leave the instructions for setting them to other sites. We might link to some site deemed to have good instructions, but keeping them inline means trying to keep them updated, which has apparently not gone well :) ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I am very new to Python, but am wanting to work on Documentation. I read through the current document and some of the revisions. May I rewrite this section so that it is not as intimidating to the average Windows user? I would direct users to use IDLE (Python GUI) or even Python (command line) before trying to use the Windows Systems Command Line. I can also add information on how to configure Windows 8, so that those items are easier to find. I have just done that to my machine. ---------- nosy: +kathweaver _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Zachary Ware added the comment: You can rewrite about as much you want. The biggest restriction on that is trying to keep existing links intact, which means either avoiding renaming or removing sections, or being sure to keep a reference to the old name. I have reservations about suggesting the "Python (command line)" Start menu entry over just using Command Prompt (since it's really just Python running inside a Command Prompt-like window with even fewer features that will disappear as soon as Python exits, which may make debugging a challenge in some cases), but I'd like to see what you have in mind before judging. To generalize an idea that I touched on in my last message, I don't think the Python documentation should be trying to teach people how to use Windows. We should provide links to good resources for learning particular topics that are necessary for what we need to teach on the Python side of things (such as how to set environment variables), but we shouldn't try to keep it in-line. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: Updated parts of the Windows using document, especially for Windows 7 and Windows 8. Moved environment variables to FAQ/windows Checked all links, removed broken references from Cygwin Checked broken links referring to in “Installing Python” in “A Byte of Python” by Swaroop C H, 2003 Updated FAQ/windows also, adding environment section from using/windows Also fact checked everything in FAQ/windows ---------- keywords: +patch Added file: http://bugs.python.org/file34385/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Éric Araujo added the comment:
From #20265:
The faq doesn't mention the new launcher for Windows. Rather than write too much I'd simply cross reference this http://docs.python.org/3/using/windows.html#python-launcher-for-windows. I think this also impacts on the section "How do I make Python scripts executable?". ---------- nosy: +eric.araujo _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: Fixed end of line issue in both documents (I hope) ---------- Added file: http://bugs.python.org/file34386/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Changes by Kathleen Weaver <kathleen@kweaver.org>: Removed file: http://bugs.python.org/file34385/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Zachary Ware added the comment: Éric Araujo wrote:
From #20265:
Correction, this is #20265, that message was from #20266 :) Kathleen: both Éric and I have left some review comments for you in Rietveld, which should have sent you an email with the comments and links to the Rietveld review. Also, if you're having end-of-line issues, I would recommend turning on the Mercurial eol extension (either edit "%userprofile%\Mercurial.ini" manually, or use the Extensions section of File -> Settings... from TortoiseHg Workbench). To work most effectively, you'll need to update to the 'null' revision, then update back to default after turning on eol. That will ensure that most files have \r\n line endings and hg can keep line endings straight for you thereafter. Here's a sample of my Mercurial.ini with some other things you may be interested in: [extensions] ;keep eols straight eol= ;delete untracked files (helps with starting from a clean slate) purge= ;colorize output, including making trailing whitespace visible in diffs color= ;create several clones that share history, useful for keeping ;separate clones per branch without having to pull individually share= [defaults] ;don't try to commit when importing a patch import = --no-commit ---------- title: Bring Doc/using/windows up to date -> Bring Windows docs up to date _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: It was Visual Studio that messed up the end of line feeds, it keep telling me that there was a problem but I didn't know what it meant. Erik and I were in #pyladies and he really helped me. As soon as I get done with gym and other mundane errands I will get back on this. I can't get over how helpful and nice everyone is! <smile> Sent using OWA for iPhone ________________________________________ From: Zachary Ware <report@bugs.python.org> Sent: Thursday, March 13, 2014 9:29:14 AM To: Kathleen Weaver Subject: [issue20265] Bring Windows docs up to date Zachary Ware added the comment: Éric Araujo wrote:
From #20265:
Correction, this is #20265, that message was from #20266 :) Kathleen: both Éric and I have left some review comments for you in Rietveld, which should have sent you an email with the comments and links to the Rietveld review. Also, if you're having end-of-line issues, I would recommend turning on the Mercurial eol extension (either edit "%userprofile%\Mercurial.ini" manually, or use the Extensions section of File -> Settings... from TortoiseHg Workbench). To work most effectively, you'll need to update to the 'null' revision, then update back to default after turning on eol. That will ensure that most files have \r\n line endings and hg can keep line endings straight for you thereafter. Here's a sample of my Mercurial.ini with some other things you may be interested in: [extensions] ;keep eols straight eol= ;delete untracked files (helps with starting from a clean slate) purge= ;colorize output, including making trailing whitespace visible in diffs color= ;create several clones that share history, useful for keeping ;separate clones per branch without having to pull individually share= [defaults] ;don't try to commit when importing a patch import = --no-commit ---------- title: Bring Doc/using/windows up to date -> Bring Windows docs up to date _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________ ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I have updated the files as reflected by the code review. ---------- Added file: http://bugs.python.org/file34403/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: Could we make this a separate issue, and I will work on it next?
From #20265:
The faq doesn't mention the new launcher for Windows. Rather than write too much I'd simply cross reference this http://docs.python.org/3/using/windows.html#python-launcher-for-windows. I think this also impacts on the section "How do I make Python scripts executable?". ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I've added a paragraph to the FAQ that refers to the Python Launcher as Éric Araujo suggested. So sorry, but new patch. ---------- Added file: http://bugs.python.org/file34409/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Changes by Éric Araujo <merwok@netwok.org>: Removed file: http://bugs.python.org/file34386/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Changes by Éric Araujo <merwok@netwok.org>: Removed file: http://bugs.python.org/file34403/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I've gone through everything and cleaned things up per zach.ware review. ---------- Added file: http://bugs.python.org/file34437/kweaver.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Nick Coghlan added the comment: Sorry I haven't had a chance to review this myself, but it would also be good if we could mention the free "Python Tools for Visual Studio" addon that Microsoft publish (https://pytools.codeplex.com/). That may be better handled as a separate patch/issue though. (My apologies if that has already been mentioned in the updated docs) ---------- nosy: +ncoghlan _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Mark Lawrence added the comment: IIRC PTVS can't be used with the express editions so please mention this. ---------- nosy: +BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: There is also a separate version of the Python Tools depending on which version of Visual Studio. I'm testing this out, and may add it to the current patch. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I just figured out why Windows 8 isn't behaving the way the documentation says. You have to use Command Prompt (Admin). Command Prompt (the first option IGNORES the path) Now it's time to have a discussion with a Windows Project Manager. ---------- _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I think I've incorporated everything wanted, and simplified things. Instead of going through how to change environment variables, I've pointed to another source. I've added the VS tools. ---------- Added file: http://bugs.python.org/file34474/kweaver.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: I think I've incorporated everything wanted, and simplified things. Instead of going through how to change environment variables, I've pointed to another source. I've added the VS tools. ---------- Added file: http://bugs.python.org/file34475/kweaver.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Changes by Kathleen Weaver <kathleen@kweaver.org>: Removed file: http://bugs.python.org/file34474/kweaver.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Changes by Kathleen Weaver <kathleen@kweaver.org>: Removed file: http://bugs.python.org/file34437/kweaver.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Changes by Kathleen Weaver <kathleen@kweaver.org>: Removed file: http://bugs.python.org/file34409/windowsDoc.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: New patch with corrections from review. ---------- Added file: http://bugs.python.org/file34574/windows.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: New patch ---------- Added file: http://bugs.python.org/file34587/windows.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Kathleen Weaver added the comment: Latest update ---------- Added file: http://bugs.python.org/file35061/mywork.patch _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

ingrid added the comment: Hi Kathleen, I was just curious why you dropped the changes from Doc/using/windows.rst on your latest patch as they looked useful to me. I know there's some review going on outside this thread, so apologies if I'm missing something you already went over. ---------- nosy: +ingrid, jesstess _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Sourav Singh added the comment: The issue is beileve is fixed now. ---------- nosy: +Sourav Singh _______________________________________ Python tracker <report@bugs.python.org> <http://bugs.python.org/issue20265> _______________________________________

Change by Mark Lawrence <breamoreboy@gmail.com>: ---------- nosy: -BreamoreBoy _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20265> _______________________________________

Mariatta <mariatta@python.org> added the comment: I think this is done, so I'm going to close it. Thanks all who participated. If there are more updates needed to the Windows documentation, I would suggest creating specific tickets with specific problems, instead of one big catchall ticket. ---------- nosy: +Mariatta resolution: -> fixed stage: needs patch -> resolved status: open -> closed _______________________________________ Python tracker <report@bugs.python.org> <https://bugs.python.org/issue20265> _______________________________________
participants (11)
-
Ezio Melotti
-
ingrid
-
Kathleen Weaver
-
Mariatta
-
Mark Lawrence
-
Nick Coghlan
-
Roundup Robot
-
Sourav Singh
-
Westley Martínez
-
Zachary Ware
-
Éric Araujo