Statalist


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

Re: st: How to link the help file for a command to its immediateversion (or generally add aliases)


From   Nick Cox <n.j.cox@stata.com>
To   statalist@hsphsun2.harvard.edu
Subject   Re: st: How to link the help file for a command to its immediateversion (or generally add aliases)
Date   Mon, 29 Sep 2008 09:27:41 -0500

I am not writing on behalf of StataCorp but it's my understanding that user modifications to *.maint are entirely at your discretion, meaning peril, and that there are absolutely no promises by StataCorp to pay any attention to any user modifications to *.maint. In two words, my advice is "Keep off" -- and I'll add, even if you think you know exactly what you are doing.

Nick
n.j.cox@durham.ac.uk

Sergiy Radyakin wrote:


Eva, if you want to type help mycommand2008 and see the help file
mycommand.hlp insert a line into the maintanence file for letter m
"mhelp_alias.maint":

mycommand2008 <TAB> mycommand

this is just an alias definition:
A <TAB> B

A must be unique
B may be not unique
A need not be a shorter form of B; B need not be a shorter form of A.

E.g. you will see the following in the standard files:
_n			_variables

which have nothing in common (in terms of spelling)

Try it: type help _n and you will get help for "_variables".

What Nick means is how to organize a link within a help file to
another help file, which is different. A file commandi.sthlp must
still exist, and well as all other files one for each of allowed
abbreviation. With the aliases - only one help file will exist in
total, and a number of entries in the aliases table. Nick's solution
is preferable, because it is "documented/recommended", but Stata,
Corp. itself uses the other way described above. Correct me if I am
wrong. This however works only for the help files, and not for the
commands themselves. So you still have to define ado files regr.ado
and regre.ado, which do nothing but call regress.ado

Perhaps someone from Stata, Corp. could tell us if the changes
introduced by the users to these files will survive updates (or will
be overwritten after Stata updates) and if there is a way to
manipulate those files in a user-firendly manner (e.g. defining
aliases by users themselves).

Eva may also be interested in command -checkhlpfiles-, which can be
called like so:
checkhlpfiles help, system

It will report something like this:
(1937 *.sthlp files)
(0 *.hlp files)
(307 *.ihlp files)
(6156 aliases)

Errors
.... unmatched help references:....
Leaves
....
From base help files:  referenced but do not exist
....
From base help files:  exist but not referenced
...
From contents help files:  exist but not referenced
...

Etc. If someone is deploying a large package with tonns of helpfiles
interlinked with each other and with standard (base) helpfiles, this
command will help them to check that their links work.


Finally Martin Weiss may be intereseted in Stata's command
_findhlpalias. It is one of the "documented undocumented commands" so
it has at least some description: help _findhlpalias

So when someone gives Martin's "expanding" program a command "g a=b",
it could gettoken first word, then try -which- on it, if no success,
the next step could be _findhlpalias g, which returns r(name) - the
full name of (hopefully "all", and it includes built-in) commands. In
this case r(name) will take a value of "generate". Another call to
-which- will fill-in the gaps. After that -unab- will take care of
variable names.

Hope this helps.

Regards, Sergiy Radyakin


On Fri, Sep 26, 2008 at 6:05 PM, Eva Poen <eva.poen@gmail.com> wrote:
Thank you, Nick. This is useful.

Although I was hoping for a single-file-solution for all aliases.
Looks like I need one help file per abbreviation.

Eva

2008/9/26 Nick Cox <n.j.cox@stata.com>:
Yes. The help file for one command can be, in its entirety, a pointer to
another help file.

Thus if you wish

. h commandi

to point to -command.sthlp-, just have

----------------------- commandi.sthlp
. h command
-----------------------

Nick
n.j.cox@durham.ac.uk

Eva Poen wrote:

Is it possible, for a user written command, to link the help file for
-command- to -commandi-? I.e., when typing -help commandi-, what
should show up is the help file for -command-, because it's all
documented in one file.

I came across the *help_alias.maint files in the Stata installation,
which I think do the job for Stata's official commands. I can't see a
way to add aliases (any, really, also abbreviations) for non-official
commands.

I'm forgetful with options, so I get to call the help files for my own
programs from time to time. Combined with my habit of inventing long,
akward names for programs, this is a lot of typing...
*
*   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