25.4 Implementation Details of aldordoc

  25.4.1 addefinename to adinternaldefinename
  25.4.2 adname to adinternalusename
  25.4.3 adparameter to adinternalparameter
  25.4.4 adcode to verb

Not every command of the interface of aldordoc is actually implemented through LATEX. For simplicity, the Perl script tools/aldordoc2tex.pl.nw is provided. It translates several commands (including their arguments) to an actually implemented LATEX form.

All such names are considered to be private and may change at any time. Currently such names start with \adinternal.

The translated commands are given in the following sections.

25.4.1 addefinename to adinternaldefinename

Since it is possible to refer (via adname) to a function by giving an optional signature, we have to make sure that hyperref finds both link targets. This explains hyperlabelsignature.

The command adinternaldefinename should be used as follows.

\adinternaldefinename[type]%  
       {indexkey}{indextext}%  
       {hyperlabelname}{hyperlabelsignature}%  
       {latextext}

The arguments are computed from the form similar to the one given in Section 25.2.8 where the SIGNATURE part must appear. Thus we have something like

\addefinename[TYPE]{FUNC:SIGNATURE}

Then the optional type is identical to TYPE. The other parameters are computed from FUNC and SIGNATURE. The need for several arguments stems from the fact that various characters must be escaped and that we wanted to keep the LATEX implementation simple. Unfortunately, the characters that must be escaped are different for hyperref (see escapeForHyperref) than for makeindex (see escapeForMakeindexKey and escapeForMakeindexText).

See the implementation of splitNameAndSignatureArgument for how FUNC and SIGNATURE are translated. Up to escaped characters, after translation we get something like

\adinternaldefinename[TYPE]%  
       {FUNC}{FUNC}%  
       {FUNC}{SIGNATURE}%  
       {FUNC}

where SIGNATURE is non-empty and is only used for the hyperref target definition.

Note that the sixth argument is not used in contrast to the definition of adinternalusename.

285implementation details 285  (247)  286
\makeatother
\newcommand{\adinternaldefinename}[6][\adthistypename]{%
  \hypertarget{#4:#1:#5}{}%
  \gdef\adthisname{\adinternalusename[#1]{#2}{#3}{#4}{#5}{#6}}%
  \index{#2@\protect\adcodefont{#3}!\protect\adcodefont{#1}|defineTermPage}%
  \index{#1@\protect\adcodefont{#1}!\protect\adcodefont{#3}|defineTermPage}%
%-- Now for the case when \adname is called without signature part in its label argument.
  \expandafter\ifx\csname:#4:#1 \endcsname\relax
    \label{#4:#1:}% define only once
    \hypertarget{#4:#1:}{}% define only once
    \expandafter\gdef\csname:#4:#1 \endcsname{}%
  \fi}
\makeatletter

25.4.2 adname to adinternalusename

The command adinternalusename has identical arguments to the command adinternaldefinename.

\adinternalusename[type]%  
       {indexkey}{indextext}%  
       {hyperlabelname}{hyperlabelsignature}%  
       {latextext}

We rely on the script tools/aldordoc2tex.pl.nw which translates adname to adinternalusename.

Inside the arguments of adname every letter is taken literally. There is no need to escape % or even { and }. The only restriction is that braces must be balanced.

286implementation details 285+   (247)  285
\makeatother
\newcommand{\adinternalusename}[6][\adthistypename]{%
  \index{#2@\protect\adcodefont{#3}!\protect\adcodefont{#1}}%
  \index{#1@\protect\adcodefont{#1}!\protect\adcodefont{#3}}%
  {\edef\rhx{r@#4:#1:}%
  \expandafter\ifx\csname\rhx\endcsname\relax %no \label has been set
    \adnameStyle{\adcodefont{#6}}%
  \else
    \hyperlink{#4:#1:#5}{\adnameStyle{\adcodefont{#6}}}%
  \fi}\xspace}
\makeatletter
\def\adnameStyle#1{#1}

Defines:
adnameStyle, used in chunk 390.

Uses xspace 269.

25.4.3 adparameter to adinternalparameter

We do not do anything fancy. No link is generated. Only a nice output form is generated.

287user interface 250+   (247)  274b
\newcommand{\adinternalparameter}[2]{\item[\texttt{#1: #2}]\qquad}

See also the description of the environment adparameters.

25.4.4 adcode to verb

There is no aldordoc command corresponding to adcode. Instead an adcode command is translated into a verb command by the script tools/aldordoc2tex.pl.nw. For more details read the corresponding Section 26.2.