Kit Baum <[email protected]> wrote about how the change to Stata's help
extension may affect the SSC archive and Stata 9 and Stata 10 users:
> There is no reason for me to change the existing contents of the SSC
> archive. No one, to my knowledge, has trouble downloading .hlp files
> from within Stata using the ssc command. The only problematic case
> involves Windows users trying to use a 'real' web browser to
> download .hlp files. But we already strongly dissuade such behavior
> (and encourage operating system upgrades). As Nick Cox suggests, it
> will be easy enough, for new additions to SSC that do not _require_
> Stata 10, to include both .sthlp and .hlp in their package files. As
> it stands now, many contributors to SSC are unable to email .hlp
> files (even within .zip files) to me. I encourage them to now adopt
> the .sthlp convention when sending me materials (Nick has been
> using .shlp for some time, but he will now switch to .sthlp).
I would like to recommend one change to what Kit wrote. He said
> ... it will be easy enough, for new additions to SSC that do
> not _require_ Stata 10, to include both .sthlp and .hlp in
> their package files.
This is not necessary. We always try to maintain backward
compatibility in new release of Stata, so Stata 10 still
understands the .hlp extension. Stata 10 can download a Stata 9
(or earlier) package containing .hlp files, and everything will
just work. Thus, there is no need to include both .hlp and .sthlp
files in a single package.
Bill Gould wrote this a couple of days ago:
> ... if an ado-file is written in Stata 9 or before, its
> corresponding help files should be named using the .hlp extension.
> Files named this way will be usable both by Stata 9 and Stata 10. If
> an ado-file is written in Stata 10, its corresponding help file should
> be named using the .sthlp extension. Stata 9 won't be able to find
> the help file, but Stata 9 won't be able to run a Stata 10 ado-file
> anyway.
End users simply don't have to worry about this at all. Everything
just works in their copy of Stata, no matter what its version is.
The users who might need to think about this are those who are
preparing packages to be downloaded by others. Those authors can
ask themselves two simple questions to know what to do:
Q1: Does the ado-file that I wrote work in Stata 9 (or earlier)?
A1: If yes, then use ".hlp" as the help file extension. Stata 9
AND Stata 10 users will be able to view the file without any
problems.
Q2: Does the ado-file that I wrote work only in Stata 10?
A2: If yes, then use ".sthlp" as the help file extension.
Stata 10 users will be able to view the file.
With respect to the SSC, Kit had one final request. There are
sometimes problems with emailing files with the extension ".hlp", as
this is the standard Microsoft help file extension. Microsoft .hlp
files are binary and can sometimes contain viruses. Stata .hlp
and .sthlp files are ASCII text. But, some email virus scanners
don't let through ANY files named ".hlp".
Thus, Kit is recommending that authors submitting help files to the SSC
always email them in with extension ".sthlp". Kit will then use the
two questions above to determine what the appropriate extension will
be in the package once it is put up on the SSC.
--Alan
([email protected])
*
* For searches and help try:
* http://www.stata.com/support/faqs/res/findit.html
* http://www.stata.com/support/statalist/faq
* http://www.ats.ucla.edu/stat/stata/
