[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: st: TeX template for PDF help files

From   Phil Schumm <>
Subject   Re: st: TeX template for PDF help files
Date   Sun, 22 Nov 2009 11:27:07 -0600

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 ( ). 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:

© Copyright 1996–2017 StataCorp LLC   |   Terms of use   |   Privacy   |   Contact us   |   What's new   |   Site index