Make it more clear where install commands are run 

so that newbies don't run them in the REPL, I've seen it happen :smile: 


@ionelmc Thanks for this! Leave the '$' signs in (we like it stylistically) and I'll happily merge it. =)


It's poor style - it's not clear for newbies what the "$" stands for.


And frankly, it just makes things harder to copy-paste, even if you know the obscure story about "$"


You'll note that the requests documentation doesn't generally concern itself with being copy-pasteable. In fact, if you examine the rest of the requests documentation, you'll notice that we generally put the prompt in all of our examples and instructions.


@ionelmc regardless of whether you think it is poor style, it is convention in all technical documentation and is a clear signal (to most) that you should be using the text following it on a command line.


Maybe it's time for a change. For example windows users have trouble with this convention.


The ruling here is basically that we're not going to make that switch. =) We make _loads_ of assumptions about what people will know in our documentation because our documentation is not targeted at complete newbies. Our docs are not an introduction to Python guide.


Windows user need love too :smile: 

Also, note that it's already inconsistent, see the git command at https://github.com/kennethreitz/requests/blob/master/docs/user/install.rst#get-the-code


Yeah, that example doesn't back your case up at all: there are four lines in that section, and three of them begin with `$`. Given that, the other one is clearly an oversight. =)

I appreciate that Windows users need love, but again, any remotely experienced Windows user will either know how `pip` works (and so not be confused by the `$` sign) or know that the `$` sign is a stand-in for the prompt.

Sorry, but this is not something we're going to bikeshed any longer, so here's the state of play: remove the change on the `$` and I'll merge this, otherwise I'll close it.


You're just assuming that windows users understand that.

I'm not clear why you're trying to be so obtuse here - I had the impression that requests was supposed to be an easy to use library, oriented towards the inexperienced.


BTW, a friend of mine was doing this:
<img src="https://lh3.googleusercontent.com/-Ou4CBbFXA_o/U0ACh89IYnI/AAAAAAAAAIw/E6TePRARiBM/w667-h179-no/pypip.png">

He's an old C++ programmer, I wouldn't say he doesn't know programming :grin: 


Requests is written to be easy to use, but the word 'inexperienced' is not one we use to define our target audience. We don't want users to have to be HTTP experts, but we do require some prior knowledge from them. I direct your attention towards [the beginning of the quickstart guide](http://docs.python-requests.org/en/latest/user/quickstart/), by definition the simplest part of the docs. By my count in the first few paragraphs we use the following terms without defining them: object, API,  HTTP request, POST, PUT, HEAD, DELETE, OPTIONS, parameters, URL, query string, dictionary, keyword argument, encoded (this is particularly egregious as we don't specify urlencoding here), key and `None`. That's a big list of terms we don't bother to explain.

We have to assume some basic knowledge on the part of our users because, as I said, _we are not an introduction to Python_ document. I agree that there are plenty of people who need just such a document, and I'd rather we directed them to one than tried to be one.

Yes, people make mistakes. I enthusiastically agreed to taking your change to specify the terminal, because that's unambiguously an improvement. Removing a widely-used convention from our documentation is substantially less clear. Users will _eventually_ encounter it, if not here then somewhere else. We assume that the user in question knows what `pip` is and has it installed. Your user above, for instance, would likely have encountered a separate problem without the `$`: they would get an error thrown by their shell when they tried to run it because `pip` isn't installed by default on Python 2.7 on Windows (IIRC).

So, once again, we've made a style decision. If you don't like it, that's totally understandable, but it blocks the merge of your pull request. Everyone's allowed to have their opinions and we acknowledge yours, but fundamentally this is not a democracy. I direct your attention to the [development philosophy](http://docs.python-requests.org/en/latest/dev/philosophy/):

> Requests is an open but opinionated project, created by an open but opinionated developer.
> - Listen to everyone, then disregard it.
> - The API is all that matters, everything else is secondary.
> - Fit the 90% use-case. Ignore the nay-sayers.

These are the principles we are upholding when we ask for the `$` to be left alone. =)


No problem.


Just so you know, I'm not looking for internet-points - I'm only trying to make this particular scenario easier.


I didn't intend to accuse you if any such thing, and I apologise if I did. I'm just trying to maintain the project as best as I can. When I get home I plan to merge this and simply return the `$` myself. =)

Your contribution is valuable, we're simply coming at the issue with different priorities.