What is the difference between \declare@shorthand and \defineshorthand in babel?

Question

What is the difference between \declare@shorthand and \defineshorthand in babel (v.3.9)? Which of the two macros is preferable in a language definition file?

babel.pdf manual (v.3.9) provides an example

\defineshorthand{"*}{\babelhyphen{soft}}
\defineshorthand{"-}{\babelhyphen{hard}}

and russian.ldf provides similar defintions using \declare@shorthand, e.g.

\declare@shorthand{russian}{""}{\hskip\z@skip}
\declare@shorthand{russian}{"~}{\textormath{\leavevmode\hbox{-}}{-}}

Answer 1

from babel.sty:

\def\defineshorthand{\declare@shorthand{user}}

defines shorthands for the namespace user

\declare@shorthand{ngerman}{"a}{\textormath{\"{a}\allowhyphens}{\ddot a}}
\declare@shorthand{russian}{""}{\hskip\z@skip}

is used internally for the specific language setting. In the above example one for ngerman and the other for russian.

So \defineshorthand{"*}{\babelhyphen{soft}} is the same as

\declare@shorthand{user}{"*}{\babelhyphen{soft}}

If you want to define your own language setting which will be loaded by babel then use the internal definition. If you have only a few new shorthands then use the user definition.

Answer 2

In 3.9

\declare@shorthand{russian}{""}{\hskip\z@skip}

is (will be) just an optimized version of

\declareshorthand[russian]{""}{\hskip\z@skip}

This shorthand is defined for russian and is active only when this language has been selected. Without the optional argument, it's a user shorthand, which is always active and takes precedence over language shorthands. In language definition files, the preferred command is the optimized one (ie, \declare@shorthand).