chore(docs): remove $ sign from shell commands

[nhedger]

This PR removes the $ sign from the bash code blocks to allow copy/pasting their content as is.

[SimonFrings]

Hey @nhedger, thanks for bringing this up 👍

I agree with you that this is way more comfortable to copy and paste these single-lined commands. This fits ReactPHP's HTTP component perfectly, because it doesn't contain any multi-lined commands inside its README. The same adjustments should also be made for ReactPHP's other components (same case).

As we're also maintaining other projects on GitHub (like Framework X etc.) we have to look at the bigger picture here. While this makes sense for single-lined commands I'm wondering if we should apply the same changes for multi-lined ones. For example:

$ curl http://localhost:8080/
Hello wörld!

or

$ php examples/index.php
$ tests/acceptance.sh http://localhost:8080

The first example shows the executable command with its following output, removing the $ could lead to some misunderstanding in some more complex examples. The second one shows two commands in one block which could also lead to some confusion (also the case for one command that takes up multiple lines).

I don't want to bloat the whole topic, but please understand that we care about consistency across our multiple projects.

I am curious what you think about this.

[WyriHaximus]

For example:

$ curl http://localhost:8080/
Hello wörld!

curl http://localhost:8080/

Outputs:

Hello wörld!

[nhedger]

Hey,

Wasn't expecting a long answer for such a small change but I understand your concern so I'll try to explain my point of view.

When a code block is annotated as bash or shell, I expect to find only bash or shell commands inside, respectively. In this instance, the $ sign is not a part of the command, it is merely used as a visual indicator, whether you are using single-line or multi-line commands.

The example output could easily live in another code block that is not annotated, right after.

But to be fair, this PR isn't even about that, it was just a matter of simplifying the copy/paste experience.

[WyriHaximus]

a matter of simplifying the copy/paste experience.

And this is why I'm in favour of it. What's you POV @clue ?

[clue]

@nhedger Thank you for this PR and sparking the discussion!

Wasn't expecting a long answer for such a small change but I understand your concern […]

I agree the $ can be a small nuisance when copy-pasting and also agree with everything @SimonFrings said why we've been using this for years despite this: The $ is a clever indicator to separate command line input from other commands or command line output. Looking at it now, I don't think using such subtle hints is particularly obvious to the average developer and might actually cause more harm than good.

As such, I agree that we can safely remove this from all our docs. I'd like to make sure we do so consistently across all our components, so I'd love to see if anybody feels like picking this up and files a bunch of PRs linked against this original PR 👍

It's currently my understanding we can safely apply this to all single-line commands. Any code fences with multiple commands or commands with outputs may need a slightly bigger change to possibly split this into multiple code fences as suggested above or we may want to keep using the $ here as copy-pasting is much less of an issue for such code blocks anyway.

[nhedger]

I'll take care of submitting the PRs for the following repos, at least. I may do more unless someone takes care of them.

• reactphp/async: chore(docs): remove leading dollar sign async#51
• reactphp/cache: chore(docs): remove leading dollar sign cache#51
• reactphp/child-process: chore(docs): remove leading dollar sign child-process#95
• reactphp/datagram: chore(docs): remove leading dollar sign datagram#50
• reactphp/dns: chore(docs): remove leading dollar sign dns#203
• reactphp/event-loop: chore(docs): remove leading dollar sign event-loop#254
• reactphp/filesystem: chore(docs): remove leading dollar sign filesystem#106
• reactphp/http-client: chore(docs): remove leading dollar sign http-client#155
• reactphp/promise: chore(docs): remove leading dollar sign promise#226
• reactphp/promise-stream: chore(docs): remove leading dollar sign promise-stream#31
• reactphp/promise-timer: chore(docs): remove leading dollar sign promise-timer#59
• reactphp/reactphp: chore(docs): remove leading dollar sign reactphp#457
• reactphp/socket: chore(docs): remove leading dollar sign socket#295
• reactphp/stream: chore(docs): remove leading dollar sign stream#166
• reactphp/website: chore(docs): remove leading dollar sign website#63

[WyriHaximus]

Thank you for the great effort @nhedger ! Merging this as most of your other PR's also have been merged at this point and the last 3 should be take long either.