[docs] Bring Doc/using/windows up to date (issue 20265)

[kathleen at kweaver.org]

I've just uploaded the new patches.


http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst
File Doc/faq/windows.rst (right):

http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode14
Doc/faq/windows.rst:14: XXX need review for Windows Vista/Seven?
On 2014/03/13 15:11:23, Zach Ware wrote:
> If you've confirmed that things are right for Python 3 and Windows
past Vista,
> you can remove these comments.

I left the comment since I just review for 7/8  I'm hoping no one has
Vista any more.

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode42
Doc/faq/windows.rst:42: Windows Icon or type Command Prompt at the Start
Menu.  You should be able to recognize
On 2014/03/13 15:11:23, Zach Ware wrote:
> A general comment that applies throughout the docs: long lines should
be wrapped
> somewhere under 80 characters, matching what the rest of the file
does.  I would
> actually suggest wrapping at 78 characters, which should prevent line
wrapping
> in an 80 character wide Command Prompt when viewing a diff (80, minus
1 for the
> +/ /- diff character, and 1 for the two-character EOL on Windows).

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode119
Doc/faq/windows.rst:119: a list of directories where Windows will look
for programs.
On 2014/03/13 06:34:55, eric.araujo wrote:
> Minor: trailing whitespace here.

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode143
Doc/faq/windows.rst:143: :ref:`below<setting-envvars>` .
On 2014/03/13 06:34:55, eric.araujo wrote:
> Minor: please add a space before the <.

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode352
Doc/faq/windows.rst:352: How do I Change Enviroment Settings?
On 2014/03/13 06:34:55, eric.araujo wrote:
> Typo: Environment

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/faq/windows.rst#newcode359
Doc/faq/windows.rst:359: Windows XP: Right-click the icon for your
machine
On 2014/03/13 06:34:55, eric.araujo wrote:
> Indentation is like special markup in reStructuredText; here it would
mean
> “quote block”, which is not your intent, I think.

I am not sure I understand.  I want to separate Windows XP directions
from Windows 7 and from Windows 8.  Please suggest a better way.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst
File Doc/using/windows.rst (right):

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode49
Doc/using/windows.rst:49: .. see also::
On 2014/03/13 06:34:55, eric.araujo wrote:
> Roles and directives in reStructuredText are like keywords in Python
code:
> changing one letter or adding a space makes them invalid.  If you
build the doc,
> you’ll get a warning for that line.
> 
> http://sphinx-doc.org/rest.html#directives
> http://sphinx-doc.org/markup/para.html#directive-seealso

Didn't see one but put it back.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode61
Doc/using/windows.rst:61: `For Windows users
<http://swaroopch.com/text/Byte_of_Python:Installing_Python#For_Windows_users>`_
On 2014/03/13 06:34:55, eric.araujo wrote:
> This link changed (the right address is used just below).

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode63
Doc/using/windows.rst:63: in "`A Byte of Python
<http://swaroopch.com/notes/python_en-installation/>`_"
On 2014/03/13 06:34:55, eric.araujo wrote:
> I see that the byteofpython.info domain name is not useful anymore; I
would
> remove that line.

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode83
Doc/using/windows.rst:83: .. sectionauthor:: Kathleen Weaver
<kathleen at kweaver.org>
On 2014/03/13 06:34:55, eric.araujo wrote:
> Sections are created by headings, so a directive applying to a section
should be
> after the heading.
> 
> In general, there aren’t many “sectionauthor” directives in doc files,
but just
> one or two at the top of the file.

I removed those.  Is there a way I should indicate I made major
additions?

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode88
Doc/using/windows.rst:88: The following shortcuts are creating during
installation and can be used to run Python:
On 2014/03/13 15:11:23, Zach Ware wrote:
> creating -> created

Done.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode105
Doc/using/windows.rst:105: raw_input()
On 2014/03/13 15:11:23, Zach Ware wrote:
> raw_input doesn't exist in Python 3, just input().  I'm not sure we
want to
> encourage this kind of workaround anyway.  If you need the output, run
from a
> Command Prompt window or write it to a file.  It'll quickly become
annoying
> having to remember to hit Enter at the end of every script run. 
Besides, this
> trick won't work in the most common case where you really want the
output:
> unhandled exceptions.

I will remove.  It was something I found in my research.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode212
Doc/using/windows.rst:212: #. Launch a command prompt [Windows 8 -
Launch Command Prompt (Admin)]
On 2014/03/13 15:11:23, Zach Ware wrote:
> I don't think this new comment adds much, considering the "(might
require
> administrative rights)" comment a line above and the fact that it
probably
> applies to Vista and 7 as well as 8.  It may be better to move that
comment to
> this line, though; it fits better here since this is the step where
you would
> acquire admin privileges.

Actually it is a new available option for Windows 8 users, so it should
be there.  The average Windows 8 probably doesn't know there are two
choices, it had me scratching my head for a while.

http://bugs.python.org/review/20265/diff/11287/Doc/using/windows.rst#newcode220
Doc/using/windows.rst:220: 
On 2014/03/13 15:11:23, Zach Ware wrote:
> I don't think the blank line here should have been removed. 
Whitespace is even
> more important in reStructuredText than in Python: vertical whitespace
means
> something too in some situations :)

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst
File Doc/faq/windows.rst (right):

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode14
Doc/faq/windows.rst:14: XXX need review for Windows Vista/Seven?
Reviewed Windows 7/8 by kw
So when we accomplish a task on a comment, we delete the comment?

On 2014/03/15 05:13:58, Zach Ware wrote:
> Better to just remove the comment.  If we have XP and 7 covered, Vista
should be
> pretty well covered too.  The number of people still stuck with Vista
is pretty
> small compared to XP and 7+ anyway.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode23
Doc/faq/windows.rst:23: Some users may find that method more efficient
than the below method.
On 2014/03/15 05:13:58, Zach Ware wrote:
> I think adding this paragraph before the next one makes the next one
make less
> sense.  I think it would be better to segue into this from the end of
the next
> paragraph, something like "The situation has been made somewhat
simpler since
> Python 3.3, which introduced the :ref:`launcher`..."

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode49
Doc/faq/windows.rst:49: "command prompt", which usually looks like
this::
On 2014/03/15 05:13:58, Zach Ware wrote:
> Sorry, I wasn't entirely clear.  Lines that you've changed should be
wrapped at
> <80 characters, but lines that you haven't changed should be left as
is.  If you
> have to, you can leave a very short line in the middle of a paragraph,
and if
> it's really bad, the committer can reflow the paragraph at commit
time.
> 
> For instance, this paragraph could be left like this:
> 
> @@ -37,7 +38,8 @@
>  *typing* Windows commands into what is variously referred to as a
"DOS window"
>  or "Command prompt window".  Usually you can create such a window
from your
>  Start menu; under Windows 7 the menu selection is
:menuselection:`Start -->
> -Programs --> Accessories --> Command Prompt`.  You should be able to
recognize
> +Programs --> Accessories --> Command Prompt`; under Windows 8 right
click the
> +Windows Icon or type Command Prompt at the Start Menu.  You should be
able to
> +recognize
>  when you have started such a window because you will see a Windows
"command
>  prompt", which usually looks like this::

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode142
Doc/faq/windows.rst:142: an "Enter" to get out of it). Once you have
verified the directory, you can
On 2014/03/15 05:13:58, Zach Ware wrote:
> This comment about needing Ctrl-Z to exit the interpreter isn't quite
right
> anymore, there is now exit() and quit().  Since this looks like a
reminder of a
> previous notice, that previous notice could stand to be removed (or
reworded) as
> well.

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode147
Doc/faq/windows.rst:147: More information about environment variables
and path can be found
On 2014/03/15 05:13:58, Zach Ware wrote:
> The added "and path" doesn't sound right to me, but I can't put my
finger on
> what's wrong with it.
I've decided to take the directions for environment variables out.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode361
Doc/faq/windows.rst:361: built-in dialog.  There is an alternative
method that works for prior
On 2014/03/15 05:13:58, Zach Ware wrote:
> This isn't true, `set` and `setx` work just as well on 7+.

Okay, it doesn't work on some of my machines. However, two of those
machines have been in an restricted environment, and they have added
oddly ever since.  It does work on this machine, which is Windows 8 and
it hasn't been exposed <grin>

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode375
Doc/faq/windows.rst:375: --> Advanced
It does work, but the method for Windows 7 is shorter, and even shorter
for Windows 8.

On 2014/03/15 05:13:58, Zach Ware wrote:
> This also works for 7, except "My Computer" is just "Computer" and
"Advanced" is
> "Advanced System Settings" in the left side menu.  I'm pretty sure it
also works
> on 8, but I've only tried it once and don't remember for certain.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode378
Doc/faq/windows.rst:378: Windows 7: Right-click the Windows Icon, choose
:menuselection:`Contol Panel`.
Yes, there is a Windows Icon on Windows 7 that takes you to the start
menu.  That Icon went away on Windows 8 and came back on Windows 8.1  

You click on it for Windows 7 (my mistake) and right click on it for
Windows 8.

This is the shortest path to get there from the desktop.

On 2014/03/15 05:13:58, Zach Ware wrote:
> What do you mean by "Windows Icon"? Is that the Start Menu button
(that hasn't
> said 'start' since Vista)?  If I right click on it in 7, I only get
"Properties"
> and "Open Windows Explorer".

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode389
Doc/faq/windows.rst:389: Windows 8: Right-click the Windows Icon, choose
On 2014/03/15 05:13:58, Zach Ware wrote:
> Same question about Windows Icon, though I haven't tested on 8.

Right click is correct.  Clicking takes you to the start menu.

http://bugs.python.org/review/20265/diff/11300/Doc/faq/windows.rst#newcode405
Doc/faq/windows.rst:405: Windows 7 and 8 is using the :command:`set`
On 2014/03/15 05:13:58, Zach Ware wrote:
> This is still true for 7 and 8.

Put it back, I tried it on an "unaffected" machine.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst
File Doc/using/windows.rst (right):

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode23
Doc/using/windows.rst:23: 
On 2014/03/15 05:13:58, Zach Ware wrote:
> A couple too many blank lines.

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode26
Doc/using/windows.rst:26: Start Menu under the title Python x.x where
x.x is the version number.
On 2014/03/15 05:13:58, Zach Ware wrote:
> I think there is markup for something that expands to the version
number
> (`|version|` perhaps?) that would simplify this.  Or just hard code
the version
> and we'll add it as a place that needs to change at release time.

Yes, but we tell them that they can run multiple versions at once
sometime here....

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode28
Doc/using/windows.rst:28: * IDLE (Python GUI) - suitable for creating
and running Python Scripts along with being a command line interpreter
On 2014/03/15 05:13:58, Zach Ware wrote:
> I think IDLE can be better described as "a simple IDE for Python,
written in
> Python using Tkinter"

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode28
Doc/using/windows.rst:28: * IDLE (Python GUI) - suitable for creating
and running Python Scripts along with being a command line interpreter
On 2014/03/15 05:13:58, Zach Ware wrote:
> I think IDLE can be better described as "a simple IDE for Python,
written in
> Python using Tkinter"

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode32
Doc/using/windows.rst:32: 
On 2014/03/15 05:13:58, Zach Ware wrote:
> The 'Module Docs' entry is missing.

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode34
Doc/using/windows.rst:34: prompt typically runs the last installed
version of Python.
On 2014/03/15 05:13:58, Zach Ware wrote:
> This isn't really true: Command Prompt runs whichever one it finds
first when it
> checks PATH for 'python', which will be none of the above unless you
choose to
> let the installer change your PATH.  I'm not sure how best to word
that for this
> section, so it may be best to just nix this sentence and cover it in
more detail
> elsewhere.

Done.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode60
Doc/using/windows.rst:60: in "`Installing Python"
<http://swaroopch.com/notes/python_en-installation/>`_"
I deleted it then.

On 2014/03/15 05:13:58, Zach Ware wrote:
> This needs some work; the section in question no longer has "For
Windows users"
> in its title anywhere, and is "Python: Installation" rather than
"Installing
> Python".  Also, it looks like this guide doesn't say anything that we
aren't
> already saying here or in the FAQ.

http://bugs.python.org/review/20265/diff/11300/Doc/using/windows.rst#newcode97
Doc/using/windows.rst:97: window will close immediately, usually faster
than the user can read.
On 2014/03/15 05:13:58, Zach Ware wrote:
> Both of these lines and several others have trailing whitespace.  You
can get
> rid of all trailing whitespace with relative ease by running
> Tools\scripts\patchcheck.py using a repository build of Python
> (PCbuild\python[_d].exe) before creating the patch file for upload.

Done.

http://bugs.python.org/review/20265/