Statalist


[Date Prev][Date Next][Thread Prev][Thread Next][Date index][Thread index]

Re: Re: st: -transint- updated on SSC


From   n j cox <n.j.cox@durham.ac.uk>
To   statalist@hsphsun2.harvard.edu
Subject   Re: Re: st: -transint- updated on SSC
Date   Thu, 26 Jul 2007 21:05:45 +0100

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
n.j.cox@durham.ac.uk

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/



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