You are at liberty to state that as your perception of the thread.
But I don't think I said that, I certainly didn't mean that and I
dissociate myself strongly from such a view. Perhaps I made myself
unclear through a jocular aside.
In particular, on help files:
Some conventions about common structure and style for help files are a
very good idea and there are very good reasons why help files need to be
in SMCL rather than say HTML, Word or some TeX-related format. That
being so, there are at least some small pains to programmers in writing
help files, but they are not a big deal.
For example, it is perfectly possible to use only a small subset of SMCL
or even to make mistakes in the use of SMCL without any really bad
effects on your help files.
(And even those who would prefer some other formatting would presumably
recognise that their favoured mode would be problematic to at least some
other people.)
Nick
[email protected]
Martin Weiss
So, to summarize and steer this thread back to where I wanted it to
go: "StataCorp, we do not like the way we have to write help files,
LET ALONE dialog boxes." :-)
Quoting Phil Schumm <[email protected]>:
> 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.
*
* 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/
