On Jul 30, 2008, at 1:09 PM, Richard Williams wrote:
I too rarely use dialogs; I just call up the help on a program. I
would love to have some sort of super-easy smcl editor, e.g. a
"save in smcl" addon to Word. For me at least, writing programs is
kind of fun, writing help files is extremely painful.
I agree that constructing help files is not as easy as it could be, and
that this probably affects people's likelihood of writing them. For
me, this is primarily because there are so many different ways to
control spacing, emphasis (i.e., highlighting), etc. In this regard,
writing a help file is a bit more like using a word processor (i.e.,
wasting time futzing with formatting) rather than creating a structured
document. For this reason, it's often easiest just to start with an
existing help file as a template and modify it as necessary (which is
exactly the way a lot of people use Word).
I too have over the years given some thought to the possibility of
writing help files in some other format and then translating them
programmatically into SMCL. You probably wouldn't want to use Word for
this, in part because not everyone uses Word, but, more importantly,
because there isn't a very good correspondence between objects in Word
and SMCL tags. Using some other type of markup (e.g., HTML, Markdown,
reStructuredText, etc.) would make more sense, and would be easier to
implement (i.e., the translation could probably be done via an XSLT
stylesheet).
The real question is, is it worth it? SMCL is used for formatting
output (which is done programmatically) and writing help files, and
that's about it. You're not going to write a paper or a book in SMCL.
Given this, a few helper functions in your text editor would probably
go a long way toward easing the production of help files. The downside
of this strategy is that it would have to be implemented separately for
each text editor; however, if someone spent some time defining an
appropriate set of helper functions, each of us who maintains a Stata
mode for a text editor could then just implement those definitions
easily enough.
-- Phil
*
* 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/
