Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Confusing shell example in documentation #156

Open
vsiegel opened this issue Aug 31, 2020 · 0 comments
Open

Confusing shell example in documentation #156

vsiegel opened this issue Aug 31, 2020 · 0 comments

Comments

@vsiegel
Copy link

vsiegel commented Aug 31, 2020

On line 122 of README.md, there is a line with a shell command for the user to run.

$ < edit settings_local.py >

Because there are additional space characters, it is not clear that it is actually pseudocode.
When it is read as a shell command, it looks quite dangerous: It contains two overwriting redirections, and seeing a command with dangerous elements that you initially do not understand is seriously confusing and distracting. It looks like an unexpected rm -f, basically.

$ <edit settings_local.py>

the following is technically better, but somewhat confusing in a different way: $EDITOR is not always defined (and $ $ may irritate others)

$ $EDITOR settings_local.py

I would propose this:

$ [edit settings_local.py]

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

1 participant