Re: Representing Computer Interactions

Subject: Re: Representing Computer Interactions
From: scot <scot -at- HCI -dot- COM -dot- AU>
Date: Thu, 18 Jan 1996 15:45:16 +1100

>>The format that I have seen most often (and which I use) is:
>> Select File|Open|SOME.FIL
>>The use of the vertical bar as a seperator is useful because it is
>>grammatically uncommon (I believe it has some obscure phonetic
>>application) and catches the eye enough to differentiate the various
>>menu levels.

>True...however there is one potential point of confusion which may arise
>from this usage. The vertical bar is used in UNIX command syntax to
>signify the "pipe" command, and therefore I would hesitate to use it in doc
>for any sort of UNIX-based application.

This is also true for MS-DOS.

>I avoid using colons when writing Mac documentation because the colon is
>sometimes used as a separator in Mac pathnames. My favorite separator for
>command names is the logical-greater-than (>) symbol, either on its own or
>preceded by a hyphen or two (-->).

Just as bad (if not worse for reasons outlined below), I'm afraid. The
greater-than symbol is a output redirection in both UNIX and DOS. eg;

traceroute > dump.the.output.into.this.file

leaves you with a file called 'dump.the.output.into.this.file' which
contains the output of the traceroute command. Thsi is true even if you type

traceroute > ls

That would leave a file called 'ls' with the traceroute output in it. If
just happened to be superuser and were sitting in /usr/bin directory (or
where ever ls might live on your UNIX system, but that is typical), typing
the command as above would leave you with a totally dead ls binary (well,
ex-binary). In fact, you DON'T need to be superuser, you just need to have
write permissions to the 'ls' file. At least

traceroute | ls

won't kill the ls file, so the pipe is safer, even if it DOES confuse the
reader, they're not likely to murder existing files with it.

Similarly, the less-than sign gives you input redirection; eg.

/usr/lib/sendmail -s'hi there' scot -at- hci -dot- com -dot- au <pre-written.message.file

If I can, I use a bullet font or something to indictate separations between
commands to be typed. Either that, or a command to a line.


HCI Consulting, GPO Box 4846 Sydney NSW 2001 Australia.
#include std.disclaimer

Previous by Author: $/word
Next by Author: $/word
Previous by Thread: Re: Representing Computer Interactions
Next by Thread: Re: Representing Computer Interactions

What this post helpful? Share it with friends and colleagues:

Sponsored Ads