Re: st: RE: Dialog Programming

[Phil Schumm <pschumm@uchicago.edu>]

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/