This might be a stupid question, but hear me out.
I regularly document steps to install various software for myself on my wiki
More recently, I managed to use different custom text in the source markdown to prepend and $ automatically, so commands can be copied more easily while still clarifying if it should be run as a normal user or as root.
Run command as user
$ some cool command
Run command as root/superuser with sudo
# some dangerous command
I usually remove and sudo and use the # prefix. However, in some cases, the sudo actually does something different that needs to be highlighted. For example, I might use it to execute a command as the user www-
sudo -u www-data cp /var/www/html/html1 /var/www/html/html2
I often use $ as a prefix, but would also make sense.
How would you prefix that line?
I don’t work much with Linux systems these days, but I would vote for $ sudo over . Two reasons:
- It’s easy to overlook the prompt. That part is basically “some characters before the actual command”, so I don’t normally pay attention it.
is also used for comments. I think it would be confusing to use the same character for two widely different things.
So $ sudo in general any time I need to run something as root?
I’ll have to think about that some more. I think I rather dislike “forcing” sudo on all commands as root.
Ok, maybe I misunderstood your question. I though you were proposing instead of $ sudo and I meant to say that being explicit is better.
I typed the post in a minute and published, so it definitely isn’t the most coherent or well thought out post.
I’m currently using for commands executed by the root user or sudo.
Currently, I only use sudo if the command depends on one of its features. Like the example above where I execute a command as the www- user.
My dilemma was whether to use $ sudo or for those few cases. But based on yours and other comments, it might make sense to use $ sudo for commands executed as root as well.
I have a fairly opinionated stance on this. Except in your sudo example where you’re specifically using sudo for a reason, I document all commands as non-root, and do not instruct them to raise privs. Whether or not they have, want or need privs, and how they raise them, is their system not mine.
It’s not exactly user friendly, but I don’t like to encourage people to blindly copy & paste commands that raise privs. That should be a conscious decision where they stop and ask themselves if & why it’s necessary.
You should consider who your audience is, are they all CLI experts familiar with the difference in syntax? That seems unlikely.
I’d always write documentation in a way that’s accessible to most users. The difference between $ and syntax is highly esoteric.
sudo on the other hand is familiar to almost everyone. It’s one of the first things mentioned in beginners guides.
I wouldn’t even prefix your commands with $ as an experienced user is quite likely to include that when copying the command.
A lot of people are citing the arch wiki as a standard that uses but isn’t the entire meme around arch that its a notably complex system?
I dislike when documentations add sudo because what if I am root already or what if sudo is not installed on my machine and I cannot just copy and paste the lines because I have to avoid pasting sudo.
Also fyi ArchWiki also uses the # approach.
I would use $ too for the example you’ve posted - it is just assuming a different user.
As long as it is not root, I wouldn’t put it with .
