Sergiy, Kit, et al.,
> -----Original Message-----
> From: [email protected]
> [mailto:[email protected]] On Behalf Of Kit Baum
> Sent: 22 November 2009 12:45
> To: [email protected]
> 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
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.
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.
--Mark
> 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/
>
--
Heriot-Watt University is a Scottish charity
registered under charity number SC000278.
*
* 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/
