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

st: RE: re: TeX template for PDF help files

From   "Schaffer, Mark E" <>
To   <>
Subject   st: RE: re: TeX template for PDF help files
Date   Sun, 22 Nov 2009 13:04:02 -0000

Sergiy, Kit, et al.,

> -----Original Message-----
> From: 
> [] On Behalf Of Kit Baum
> Sent: 22 November 2009 12:45
> To:
> Subject: st: re: TeX template for PDF help files
> <>
> 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
> > 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),
> > 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
> > documentation only?
> > 2Stata developers: Would it be possible to make -help mycommand-
> > 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.

I like this idea a lot.  Maybe Stata's -translate- should support
HTML->SMCL?  Everybody has an editor that can creat HTML output.  People
could write help files in HTML and then run them through -translate- to
get the necessary SMCL version.  It wouldn't work for fancy stuff, e.g.,
point-and-click examples that trigger the execution of Stata code, but
it would probably be good enough for simple help files.


> 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   |   
>                               An Introduction to Stata 
> Programming  |
>    An Introduction to Modern Econometrics Using Stata  |   
> *
> *   For searches and help try:
> *
> *
> *

Heriot-Watt University is a Scottish charity
registered under charity number SC000278.

*   For searches and help try:

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