deep-visualization-toolbox icon indicating copy to clipboard operation
deep-visualization-toolbox copied to clipboard

Confusing shell example in documentation

Open vsiegel opened this issue 5 years ago • 0 comments

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]

vsiegel avatar Aug 31 '20 05:08 vsiegel