CentOS docs - Jun 2012 - Format for giving examples of commands

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?

Yves

-- 
Yves Bellefeuille <yan at storm.ca>
"La Esperanta Civito ne rifuzas anticipe la kunlaboron de erarintoj, se
ili konscias pri sia eraro." -- Heroldo Komunikas, n-ro 473.

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