On Nov 21, 2009, at 8:33 PM, Sergiy Radyakin wrote:
In my opinion, the unpleasant task of preparing documentation in
SMCL is a major barrier to release user-written ados to the public
On Nov 22, 2009, at 10:25 AM, Richard Williams wrote:
For me personally, writing programs is kind of fun, writing help
files in smcl is a terrible horrible awful painful experience.
Similar comments are often made about writing man pages (typically
written in troff/nroff). However, once they have been produced, Stata
help files (or man pages) are easy to consume (i.e., just type -help-
or -man-). Thus, I see no reason to replace the end format, just to
provide an alternative way to achieve it.
On Nov 21, 2009, at 11:22 PM, Roy Wada wrote:
I would suggest a Word template because (1) it is accessible to
everyone, (2) easy to write, which means you can write it like a
paper, and (3) easy to add references at end.
(1) is incorrect (Linux users don't have Word, nor do those who don't
own it), (2) is a subjective assessment, and it is unclear what (3)
refers to (e.g., using EndNote?). Regardless, Word would be
inadequate for a much more fundamental reason. Stata help files (and
man pages) are structured documents (well, I'm not sure this is
entirely true of Stata help files, but they are at least semi-
structured). I believe it may be possible to write a structured
document in Word, but that's certainly not the way most people use it,
and the program itself doesn't facilitate doing so.
Sergiy's original idea is a good one, I think, and one which has been
on my to-do list for quite some time (though, admittedly, rather far
down). However, there's no need to reinvent the wheel here; there are
several good document processing systems already in existence that
could be used for this task. If it were me, I'd use Docutils (http://docutils.sourceforge.net/
). Docutils takes as input structured documents written in
reStructuredText. reStructuredText is an easy-to-learn markup
language with a fairly rich feature set -- more than adequate for
writing Stata help files (and, if not, it is extensible). Once you
have your reStructuredText document, you can then translate it into a
wide range of formats, including HTML, LaTeX, PDF, ODF (and, via
OpenOffice, into Word), and others. The system is designed to make it
easy to add support for new output formats (by writing your own
"writer"); for example, there is a man page writer which makes it
possible to write man pages in reStructuredText.
Personally, I'd like to write a "Stata help file writer" for Docutils,
so that I could write Stata help files in reStructuredText. Note that
you could also generate a PDF version directly (or, through Stata's
own -translate-), for those who prefer to consume the file(s) that
way. Unfortunately, this is not a priority for me right now, though
I'd be glad to participate if a group of people wanted to work on this
together.
-- 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/
