Writing Terminal commands

On 20.11.2007, at 12:32, jiclark wrote:

> Why is it so common for people to write the commands with the
> leading '$' prompt??? For someone who is completely new to
> Terminal, they will be frustrated to find that their commands don't
> work because they're including that symbol! It's funny how often I
> see this, and I'm pretty minimal in my Terminal skills, so I am
> often trying things like this that experts post...

This has been used for ages in order to distinguish the 'normal' text
from
command line examples in the text. It's similar to indenting e.g.
quotations, etc.

Also, when you want to give an example of a command line where one
has to be
superuser (aka root aka Admin), then one prepends the line with an '#'.

Cheers, Kei.

On 20-Nov-2007, at 04:32, jiclark wrote:
> Why is it so common for people to write the commands with the
> leading '$' prompt??? For someone who is completely new to Terminal,
> they will be frustrated to find that their commands don't work
> because they're including that symbol! It's funny how often I see
> this, and I'm pretty minimal in my Terminal skills, so I am often
> trying things like this that experts post...


Good question. There is, you'll be glad to find, a good answer too.

a leading '$' indicates two things, one that the following should be
typed exactly into the terminal window and two, and most importantly,
that it should be done as a user. Sometimes you will see, instead:

# vi /etc/apache2/httpd.conf

That line also indicates that it should be typed into the terminal,
but this time the '#' indicates it should be done as the superuser
(either through sudo or logging in as root).

The trouble is, a lot of people have picked up on the '$' convention
without fully understanding it, so sometimes you might see a '$' when
a '#' is warranted.

This convention started because the shell normally changes your prompt
from a $ to a # when you escalate privileges. It is useful because you
don't have to do things like:

Type "vi /etc/apache2/http.con" into the terminal (without the quotes)

over and over. Or even worse, something like this:

Now, type exactly "defaults write com.apple.dock persistent-others -
array-add '{ "tile-data" = { "list-type" = 1; }; "tile-type" =
"recents-tile"; }'" but without the outside double quotes. Be sure
and leave the double quotes that are inside the command, but not the
ones at the start and end. You need the single quote at the end
though, so don't delete that one.

The '$' prompt is a sort of <pre> tag, if you're a html monkey, that
tells you everything after that is verbatim, quotes and all.

On Nov 20, 2007, at 6:32 AM, jiclark wrote:

> Why is it so common for people to write the commands with the
> leading '$' prompt??? For someone who is completely new to
> Terminal, they will be frustrated to find that their commands don't
> work because they're including that symbol!

I think people do it to *help* the novice. The '$' is there to say
"the following is a command, not some avant-guarde form of poetry."
And if one looks at what is actually in Terminal and can do a little
deduction, including the '$' in the command is a mistake that's easy
to remedy. The result of the command will be "-bash: $: command not
found" you can see on the line above that there's a dollar sign
preceding the one your typed and hopefully think "maybe I should try
it again without the dollar sign."

> It's funny how often I see this, and I'm pretty minimal in my
> Terminal skills, so I am often trying things like this that experts
> post...

I prefer commands to be written beginning on a new line with no
prompt because that makes them easier to select to copy and paste
them into Terminal.

On the web, it's nice to see different styling, such as a monospace
font, for commands and code examples, to help differentiate them from
prose but in email the addition of styling isn't worth the addition
of HTML.

On 21/11/2007 12:32 AM, "jiclark" <jclarkouraynet.com> spake thus:

> Why is it so common for people to write the commands with the leading '$'
> prompt???

Basically because '$' is the ultimate default shell prompt. Under Mac OS X
you will tend to get something more like this by default:

joe-smiths-computer:~ jsmith$

but that's just because they've set the default prompt to include a whole
bunch of other stuff like the machine name, current working directory and
username. You can still see the '$' at the end, though.

The '$' is generally included to distinguish commands from their output,
e.g.:

$ ls
foo.txt
bar.txt

--
Nigel Stanger, Dunedin, NEW ZEALAND.
http://xri.net/=nigel.stanger

On 11/20/2007 5:40 PM, "Curtis Wilcox" wrote:
>> Why is it so common for people to write the commands with the
>> leading '$' prompt??? For someone who is completely new to
>> Terminal, they will be frustrated to find that their commands don't
>> work because they're including that symbol!
>
> I think people do it to *help* the novice. The '$' is there to say
> "the following is a command, not some avant-guarde form of poetry."

Assuming, of course, that novices know that's what "$" means ;-)


> And if one looks at what is actually in Terminal and can do a little
> deduction, including the '$' in the command is a mistake that's easy
> to remedy. The result of the command will be "-bash: $: command not
> found" you can see on the line above that there's a dollar sign
> preceding the one your typed and hopefully think "maybe I should try
> it again without the dollar sign."

Although I think if you step back and look at the error from the point of
view of a novice computer user -- one who's never used a command-line
interface -- the message "-bash: $: command not found" isn't very
informative. Does it mean the "$" was not found? Or does it mean the command
after $ wasn't found?

The prompt also may not actually be "$"; in some environments, the IT folks
have changed shells or even prompts.

There's the argument that $ is useful for differentiating from #, but,
again, it's only meaningful if you're writing for people familiar with
shells and they're using the same shell and prompt.



That said, unless you're using screenshots of Terminal, it's difficult to
present shell commands in a way that makes it easy for the reader to figure
out exactly what should be typed. Is a command on two lines because it's
actually two different commands, or was it just too long to fit on one line?
When split on two lines, is there a space between the two lines, or is it
one continuous line? When a command is presented in a sentence -- as it
often is in print -- is a period part of the command, or is it just
punctuating a sentence?

In one of my books that included lots of shell commands, we decided to
conclude every command-line input with a designation that looked like
<RETURN>. Anything preceding the marker was part of the command, on a single
line, and anything after the marker was not. (So if there were three
<RETURN> markers, there were three separate commands.) When a command was
too long to fit on a single line, we used a symbol that looked like a
continuation arrow to indicate that the multiple lines should be entered as
a single command; if there was a space before the symbol, there should be a
space between the lines.

The response from readers was that this was very helpful, even though a few
hardcore shell veterans hated it ;-)

On 23-Nov-2007, at 07:54, Dan Frakes wrote:
> There's the argument that $ is useful for differentiating from #, but,
> again, it's only meaningful if you're writing for people familiar with
> shells and they're using the same shell and prompt.


Right, but keep in mind that the vast majority of stuff written for
shell users is not written for the neophyte/beginner because in
general, neophyte/beginners should not be using the shell to start with.

Also, the shell is text based, so styling the text is not that
useful. Putting a big <RETURN> at the end of the line might be fine
in print<1>, but is simply damed annoying in electronic form.

One thing I forgot to mention is that the $ helps break up the
commands from the output:

date
Sat Nov 24 07:52:56 MST 2007
ls
Applications Documents Library Music Public
Sites bin fstab
Desktop Downloads Movies Pictures Searches
backups bluetooth
man ls | head -1
LS(1) BSD General Commands
Manual LS(1)

or

$ date
Sat Nov 24 07:52:56 MST 2007
$ ls
Applications Documents Library Music Public
Sites bin fstab
Desktop Downloads Movies Pictures Searches
backups bluetooth
$ man ls | head -1
LS(1) BSD General Commands
Manual LS(1)
$

I'd say the former, though a series of overly simplistic commands, is
almost indecipherable. Given a longer series of commands and even
experienced shell monkeys are going to get lost.

<1> I say MIGHT.