homepage

The example at http://docs.python.org/dev/library/subprocess.html#popen-constructor seems a bit misplaced, as it seems to suggest that one should use the shlex module. Most of the other examples in the module seem to use a list to provide the args, so if there was a need to just point out that shlex could be used for a corner case perhaps it'd be better suited as a footnote or another subsection somewhere.

It is not particularly intuitive what goes in to a Popen non-shell argument list, unless you are an experienced programmer. The real purpose of the note is to convey a lot of information about how tokenization works in a short example, and it also demonstrates how to investigate other complex cases the user may have to deal with. Because of the first part of that (showing tokenization quirks) I don't think it should be relegated to a footnote.
That said, the example could perhaps be reworded slightly to make its expositional purpose clearer. Suggestions welcome.

Maybe we can add a very small example before the whole note to show just how to use Popen in simple situation, and so the shlex part below will add more details for more advanced cases.

Sounds reasonable to me.
I'll take a look at adding one unless someone manages to beat me to it.

New changeset 95d024d585bd3ed627437a2f0cbc783c8a014c8a by Tim D. Smith in branch 'master':
bpo-13826: Clarify Popen constructor example (GH-18438)
https://github.com/python/cpython/commit/95d024d585bd3ed627437a2f0cbc783c8a014c8a

New changeset 78982f94faaa05e363d15b49ec230d11a4d8bebd by Miss Islington (bot) in branch '3.7':
bpo-13826: Clarify Popen constructor example (GH-18438)
https://github.com/python/cpython/commit/78982f94faaa05e363d15b49ec230d11a4d8bebd

New changeset e6690f6cd1b0c2bd5804bad30239a4070f79102c by Miss Islington (bot) in branch '3.8':
bpo-13826: Clarify Popen constructor example (GH-18438)
https://github.com/python/cpython/commit/e6690f6cd1b0c2bd5804bad30239a4070f79102c