Conversely, a program is not (I suggest) acceptable on SSC without a
help file!
On the larger issue, the key is that SMCL, a recursive acronym for "SMCL
makes cooler logs",
is in the first instance a language for
tuning the display of results in the Results window, and thus for logs.
In practice,
it is also used for formatting of help files and some other files to be
seen in the
Viewer. That is secondary -- although help files could not be seen in
the Results window
if they were incompatible with the code behind that -- and in principle
a different
language could be used for help files, although that in turn would be a
source of grumbles.
("Stata is badly designed: it uses different languages for formatting
results and help files!")
The essentials for Stata include
* Any formatting language should be available at no extra charge to
users
across platforms. At first sight, that includes various flavours of TeX
and HTML which
are in essence in the public domain, as well as SMCL.
* Any formatting language for results must be compatible with output
that is emitted one line
at a time. This is a crucial detail that rules out HTML and TeX. But it
does not
necessarily rule those out languages for help files.
No one can be really fond of SMCL, but that is not a big deal.
SMCL is useless outside Stata and not very powerful within Stata, at
least compared
with what TeX or HTML can do outside Stata. We can probably all agree on
that. But I doubt we will all agree on much else. My further thoughts:
* SMCL enforces a uniformity of look and feel that is generally a good
thing.
* I don't follow quite what point Sergiy is making about documentation
of SMCL. SMCL is
explained totally in the help and the manuals. I don't see a need for
even one book on
SMCL, not until books on Mata and much, much else have been written.
HTML and TeX are
not at all comparable here: they are much larger languages, and there is
a need
for all kinds of books on them.
* SMCL is only a small language and you can be a productive programmer
without using more
than a small part of it. I write a fair number of programs, but I have
yet to read the entire
manual entry on SMCL.... As Sergiy also recommends, in practice you are
well advised
to start from an existing help file.
* TeX users (including me) would be happy if help files could be written
in TeX or
there were a translator from TeX to SMCL, as Roy Wada suggests. But I
doubt that that
would be popular with non-TeX users. The same applies to HTML, as
mentioned by Tamas Bartus.
I have no data, but I guess that not all Stata programmers also use TeX
or HTML.
If neither TeX nor HTML is conceivable as a compulsory standard, what
incentive is there
for Stata developers to spend valuable time working on support for
something that in each
case would be used by _some_ programmers only? Besides, what would be
supported? All of TeX
or HTML or just subsets?
I am reminded of the old joke that standards are great, as there are so
many to choose
from!
Finally, in response to a point from Tamas Bartus: Stata has been able
to produce HTML versions
of logs for several years. -log2html- from SSC is a wrapper to the
official command that lets you
do this.
Nick
[email protected]
Richard Williams
At 03:09 AM 4/11/2008, Tamas Bartus (tbartus) wrote:
>I also find smcl a bit difficult, writing a help file is not a
>pleasure (probably I miss
>some necessary skills). Did StataCorp considered or does consider in
>the future other languages?
>HTML for example? I just discovered by chance that even SPSS 14. can
>produce almost publication quality HTML log files.
Writing programs is kind of fun, but writing help files is pure
drudgery. If somebody has written templates that make Textpad or
other programs easier to use when writing help files, I'd love to see
them. I know Statacorp has a long wish list, but anything it could
come up with would be appreciated. I've heard people say that they
didn't bother to put their programs on SSC because they didn't want
to write a help file.
*
* For searches and help try:
* http://www.stata.com/support/faqs/res/findit.html
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
