Statalist


[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" <M.E.Schaffer@hw.ac.uk>
To   <statalist@hsphsun2.harvard.edu>
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: owner-statalist@hsphsun2.harvard.edu 
> [mailto:owner-statalist@hsphsun2.harvard.edu] On Behalf Of Kit Baum
> Sent: 22 November 2009 12:45
> To: statalist@hsphsun2.harvard.edu
> 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/



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