st: Use -command- references, not --command references, please

["Nick Cox" <n.j.cox@durham.ac.uk>]

Various members have recently asked questions referring to commands like
this:  

--cmdname 

I don't know quite how this arose, but I want to make clear that it
serves no useful purpose. However, it seemed to arise a few days again
and has already been imitated in more than one thread. 

Statalist encourages members to refer to Stata syntax like this:  

-cmdname- 

At the risk of being irritatingly obvious, let me spell out why we have
this convention. 

1. Statalist is based on plain text or ASCII postings, so resort e.g. to
bold or typewriter fonts should not be made. 

2. Clarity of communication is eased when we distinguish Stata syntax
from ordinary language. For example, compare

Have you tried using duplicates? 

Have you tried using -duplicates-? 

The second makes clear that the questioner has a particular Stata
command in mind. The first requires a little more decoding and may even
in context not be clear. For example, readers may not know that there is
a -duplicates- command. 

3. The -cmdname- convention introduced by William Gould is easy to type
and easier on the eye than appalling alternatives such as putting
commands in CAPITALS, WHICH ARE PAINFUL TO READ and synaesthetically
convey the impression of SHOUTING to many. Further, it has one very
important advantage that both the beginning and the end of code are
clear. For example, the sentence 

You should use -summarize, meanonly- in your programs whenever it does
all you need. 

is very informative to all but the greenest newcomers to Stata. Even
commands such as 
-gen x = y - 2- are fairly clear, although I would tend to put code like
that on a separate line. 

We cannot, and even if we could would not, insist that Statalist members
all adopt this convention, although you will find that most of the more
active answerers of questions do so. 

However, I do underline that the mutant --cmdname convention serves no
purpose. We do not need a different convention and this mutant does not
allow the beginning and end of code to be seen clearly. 

Nick 
n.j.cox@durham.ac.uk 



*
*   For searches and help try:
*   http://www.stata.com/help.cgi?search
*   http://www.stata.com/support/statalist/faq
*   http://www.ats.ucla.edu/stat/stata/