[CentOS-docs] Format for giving examples of commands

[Akemi Yagi]

On Sun, Jun 17, 2012 at 11:37 AM, Yves Bellefeuille <yan at storm.ca> wrote:
> Hello,
>
> Is there a standard format for quoting examples of commands to be
> entered by the user?
>
> I've given the following example commands:
>
> cd /tmp
> wget http://www.skype.com/go/getskype-linux-beta-static
> cd /opt
> tar xjvf /tmp/skype_static-4.0.0.7.tar.bz2
> rm /tmp/skype_static-4.0.0.7.tar.bz2
> ln -s skype_staticQT-4.0.0.7 skype
>
> Someone changed them to add prompts:
>
> [root at host]# cd /tmp
> [root at host]# wget http://www.skype.com/go/getskype-linux-beta-static
> [root at host]# cd /opt
> [root at host]# tar xjvf /tmp/skype_static-4.0.0.7.tar.bz2
> [root at host]# rm /tmp/skype_static-4.0.0.7.tar.bz2
> [root at host]# ln -s skype_staticQT-4.0.0.7 skype
>
> I think my way is better, since the user can simply copy and paste the
> entire example into a terminal. Conversely, with a prompt, there's no
> chance that the example will be confused with a program listing, but I
> don't think that's likely to happen.
>
> Is either format preferred?

I think people's opinions will split on this. When the above change
was made, Karanbir Singh noted on IRC:

< kbsingh> yeah, that also makes sure that people cant copy + paste
stuff in one go
< kbsingh> they need to copy bits in one piece at a time

I tend to agree that we want to be sure users do not just copy the
while thing in one shot.

Another (actually main) purpose of presenting the prompt is to
distinguish the commands that must (or must not) be run as root.

Akemi