The main documentation you need is the explanation
of help files in [U] and of SMCL in the on-line help
or in [P].
In fact, minimally, you don't need any of that.
I just opened my editor and created a file with
this text
------------------------------------- begin
Michael McCulloch works for the Pine Street
Foundation in San Anselmo, CA. I don't think
I've met him. He would probably enjoy the
upcoming West Coast users' meeting.
------------------------------------- end
and saved this as a -mcculloch.hlp- along
my -adopath-. Then
. help mcculloch
shows me inside. Everything else is details.
Some details:
1. If you don't know what an -adopath- is,
type
. adopath
to see yours, now, or read the help. The very
simple idea is that Stata must be able to see
your file, and the adopath indicates where it
will look, in order. Naturally, stay away from
Stata's own directories or folders.
2. Evidently, you shouldn't use a name already
used. Typing
. help possiblename
in advance is one test. Using some convention
that won't clash with anybody else like
pinestreet_local_programs.hlp
pinestreet_datasets_index.hlp
is one obvious possibility. Underscores
are a very good idea as separators. Stata
will then let you type
help pinestreet datasets index
and will understand spaces to mean underscores.
3. Stata itself uses the .sthlp extension
as from Stata 10, and I can't see why you shouldn't
too as long as you follow #2 above. The extension
.sthlp should make it easier to send such files
by email -- should you wish to do that -- and
cause fewer misunderstandings from programs
emanating from Redmond, WA.
4. To get more than a very plain presentation,
you will want to use some of Stata's markup language SMCL.
Reading the help on SMCL will probably cause some
indigestion, but my guess is that only a few people
in StataCorp have learnt all of SMCL. In any case,
you look up how to do some effect precisely when
you need it. Start with the file bundled with
Stata called examplehelpfile.hlp (or examplehelpfile.sthlp)
and look inside and look at how it displays as a way
of seeing how things are done. Or look inside any
help file whose style you want to copy.
5. Some text editors (Vim) understand SMCL and
through syntax highlighting make editing help files
much easier.
6. SMCL can be translated into HTML using -log2html-
from SSC. I don't know of a reverse translator.
7. One gotcha with SMCL that may not be documented is
to be careful about trailing spaces on lines. They
often mess up the details.
Nick
[email protected]
Michael McCulloch
(I learnt the beautifully
simple idea that you can write your own help file on any topic
you like from a throw-away remark by Michael Hills.)
Thank you Nick. I've not successfully found guidelines for this.
Might you be able to point me in the right direction?
*
* 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/
