classification
Title: Bring Windows docs up to date
Type: enhancement Stage: needs patch
Components: Documentation, Windows Versions: Python 3.4, Python 3.3, Python 2.7
process
Status: open Resolution:
Dependencies: Superseder:
Assigned To: docs@python Nosy List: BreamoreBoy, docs@python, eric.araujo, ezio.melotti, ingrid, jesstess, kathweaver, ncoghlan, python-dev, westley.martinez, zach.ware
Priority: normal Keywords: easy, patch

Created on 2014-01-15 03:41 by zach.ware, last changed 2014-07-10 15:34 by ingrid.

Files
File name Uploaded Description Edit
kweaver.patch kathweaver, 2014-03-18 01:22 review
windows.patch kathweaver, 2014-03-23 01:02 review
windows.patch kathweaver, 2014-03-23 15:09 review
mywork.patch kathweaver, 2014-04-27 22:14 review
Messages (27)
msg208136 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-01-15 03:41
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.
msg208366 - (view) Author: Roundup Robot (python-dev) Date: 2014-01-17 21:24
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
msg211281 - (view) Author: Ezio Melotti (ezio.melotti) * (Python committer) Date: 2014-02-15 15:35
Are you just going to reference this issue whenever you update that file, or do you have a plan?
msg211442 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-02-17 21:28
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)
msg211461 - (view) Author: Westley Martínez (westley.martinez) * Date: 2014-02-18 00:09
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.
msg212386 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-02-27 21:05
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 :)
msg213013 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-10 02:37
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.
msg213035 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-03-10 14:40
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.
msg213352 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-13 04:59
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
msg213354 - (view) Author: Éric Araujo (eric.araujo) * (Python committer) Date: 2014-03-13 05:05
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?".
msg213356 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-13 05:24
Fixed end of line issue in both documents (I hope)
msg213400 - (view) Author: Zachary Ware (zach.ware) * (Python committer) Date: 2014-03-13 14:29
É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
msg213401 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-13 14:40
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>
_______________________________________
msg213432 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-13 18:20
I have updated the files as reflected by the code review.
msg213433 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-13 18:22
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?".
msg213511 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-14 02:47
I've added a paragraph to the FAQ that refers to the Python Launcher as Éric Araujo suggested.

So sorry, but new patch.
msg213692 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-15 23:29
I've gone through everything and cleaned things up per zach.ware review.
msg213790 - (view) Author: Nick Coghlan (ncoghlan) * (Python committer) Date: 2014-03-17 05:06
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)
msg213843 - (view) Author: Mark Lawrence (BreamoreBoy) * Date: 2014-03-17 09:23
IIRC PTVS can't be used with the express editions so please mention this.
msg213863 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-17 13:55
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.
msg213899 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-17 21:20
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.
msg213929 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-18 01:22
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.
msg213930 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-18 01:22
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.
msg214531 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-23 01:02
New patch with corrections from review.
msg214587 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-03-23 15:09
New patch
msg217319 - (view) Author: Kathleen Weaver (kathweaver) * Date: 2014-04-27 22:14
Latest update
msg222674 - (view) Author: (ingrid) * Date: 2014-07-10 15:34
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.
History
Date User Action Args
2014-07-10 15:34:16ingridsetnosy: + jesstess, ingrid
messages: + msg222674
2014-04-27 22:14:42kathweaversetfiles: + mywork.patch

messages: + msg217319
2014-03-23 15:09:13kathweaversetfiles: + windows.patch

messages: + msg214587
2014-03-23 01:02:24kathweaversetfiles: + windows.patch

messages: + msg214531
2014-03-18 01:23:33kathweaversetfiles: - windowsDoc.patch
2014-03-18 01:23:24kathweaversetfiles: - kweaver.patch
2014-03-18 01:23:13kathweaversetfiles: - kweaver.patch
2014-03-18 01:22:52kathweaversetfiles: + kweaver.patch

messages: + msg213930
2014-03-18 01:22:47kathweaversetfiles: + kweaver.patch

messages: + msg213929
2014-03-17 21:20:00kathweaversetmessages: + msg213899
2014-03-17 13:55:36kathweaversetmessages: + msg213863
2014-03-17 09:23:55BreamoreBoysetnosy: + BreamoreBoy
messages: + msg213843
2014-03-17 05:06:21ncoghlansetnosy: + ncoghlan
messages: + msg213790
2014-03-15 23:29:30kathweaversetfiles: + kweaver.patch

messages: + msg213692
2014-03-14 06:34:13eric.araujosetfiles: - windowsDoc.patch
2014-03-14 06:34:10eric.araujosetfiles: - windowsDoc.patch
2014-03-14 02:47:25kathweaversetfiles: + windowsDoc.patch

messages: + msg213511
2014-03-13 18:22:20kathweaversetmessages: + msg213433
2014-03-13 18:20:49kathweaversetfiles: + windowsDoc.patch

messages: + msg213432
2014-03-13 14:40:29kathweaversetmessages: + msg213401
2014-03-13 14:29:14zach.waresetmessages: + msg213400
title: Bring Doc/using/windows up to date -> Bring Windows docs up to date
2014-03-13 05:24:47kathweaversetfiles: - windowsDoc.patch
2014-03-13 05:24:23kathweaversetfiles: + windowsDoc.patch

messages: + msg213356
2014-03-13 05:05:39eric.araujosetnosy: + eric.araujo
messages: + msg213354
2014-03-13 05:00:04kathweaversetfiles: + windowsDoc.patch
keywords: + patch
messages: + msg213352
2014-03-10 14:40:31zach.waresetmessages: + msg213035
2014-03-10 02:37:01kathweaversetnosy: + kathweaver
messages: + msg213013
2014-02-27 21:05:05zach.waresetmessages: + msg212386
2014-02-18 00:09:03westley.martinezsetnosy: + westley.martinez
messages: + msg211461
2014-02-17 21:28:39zach.waresetmessages: + msg211442
2014-02-15 15:35:23ezio.melottisetnosy: + ezio.melotti
messages: + msg211281
2014-01-17 21:24:52python-devsetnosy: + python-dev
messages: + msg208366
2014-01-15 03:41:05zach.warecreate