<>
On Nov 22, 2009, at 2:33 AM, Sergiy wrote:
> I wonder what does the community think about having help files for
> custom ados being in PDF format (in light of the recent availability
> of the Stata manuals in the said format)? Has anyone prepared a
> template for this already? What are the pros and cons of the PDF
> documentation (which is a de-facto standard for the rest of the
> software) versus SMCL documentation?
>
> In my opinion, the unpleasant task of preparing documentation in SMCL
> is a major barrier to release user-written ados to the public (and
> there was a complaint recently regarding "no fresh original
> programs"). In my vision, the simplier this template is, the more
> likely the next generation of ado files will be more completely
> described. Perhaps the Stata gurus could take the initiative and
> collectively make this template for the rest of us? Now could be the
> right moment to standardize this (similar to the SJ template), before
> custom versions start to appear.
>
> 2Kit: since PDF files are not installed with the package by default,
> what are the recommendations if I want to deploy my package with a PDF
> documentation only?
> 2Stata developers: Would it be possible to make -help mycommand- also
> check for the presense of mycommand.pdf in case mycommand.sthlp and
> mycommand.hlp are not found?
I can set up packages to automatically install any PDF files included with the package; that is an option in the package description. However that will not do you any good, as it will just install the PDF files in /plus/whatever, where it now installs the ado and sthlp files. Until and unless Stata has some official command to view help files in PDF as an alternative (per second query) this would not be useful.
Personally I think it would be more productive to write a simple translator that would take, say, a LaTeX file following a template and turn it into SMCL. SMCL can be turned into HTML or PDF using Stata's -translate- (all Stata help files on the SSC Archive are already reproduced in HTML format, refreshed weekly). Or, for those allergic to LaTeX, a simple form (perhaps written with Stata dislog boxes?) that the author would fill out to create the SMCL file. SMCL, after all, is just another markup language, so translation from another markup language is not that difficult.
The stated policy of the SSC Archive will be retained for the tie being: packages must contain a SMCL help file to be included in the archive.
Kit
Kit Baum | Boston College Economics & DIW Berlin | http://ideas.repec.org/e/pba1.html
An Introduction to Stata Programming | http://www.stata-press.com/books/isp.html
An Introduction to Modern Econometrics Using Stata | http://www.stata-press.com/books/imeus.html
*
* 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/
