25.3 Extended User Interface

This part of the user interface is again divided into two parts.

1. Commands that are automatically generated by some script. The arguments of those commands are extracted from the actual Aldor code and placed at the beginning of the corresponding +++ description. In ALLPROSE the script tools/addaldortypedef.pl.nw is responsible for this generation.
   • ∖addefinetype{TYPENAME}: Markup for the definition of a category, a domain, or package name (generated automatically by the script tools/addaldortypedef.pl.nw).
   • ∖addefinename[TYPENAME]{FUNC:SIGNATURE}: Markup for the definition of a function or a constant (generated automatically by the script tools/addaldortypedef.pl.nw).
2. Commands that appear rarely, but might be interesting for documentation writers.
   • ∖addescribetype{TYPENAME}: Markup for a type before an automatically generated definition. No output appears in the running text.
   • ∖addefineassertion{ASSERTION}: Typeset ASSERTION and mark it as the target of a hyperlink.
   • ∖adassertion{ASSERTION}: Refer to the place where ∖addefineassertion appears.
   • ∖addefinemacro{MACRO}: Typeset MACRO and mark it as the target of a hyperlink.
   • ∖admacro{MACRO}: Refer to the place where ∖addefinemacro appears.

25.3.1 The ∖addescribetype and ∖addefinetype commands

The command ∖addefinetype should not be used by library documentation writers because these commands will be added automatically by the ALLPROSE script tools/addaldortypedef.pl.nw. The command ∖addescribetype, however, is intended for cases when a code part that contains the definition of a type comes later than the documentation for that type. In order to be able to use ∖adthistype, instead of ∖adtype{CURRENTTYPENAME}, one has to initialize ∖adthistype via ∖addescribetype.

∖addescribetype should be used for cases where functions of a domain or category appear before the domain or category code is mentioned explicitly. Therefore, ∖addescribetype helps to avoid to mention the optional type parameter in ∖adname explicitly.

Note that neither of the commands result in any output in the running text.

As can be seen from the code below, ∖adthistypename holds the current name of the type. This command, however, is not intended to be used by library documentation writers. It solely serves an internal purpose of aldordoc to have the current type name available when it is not given as an optional parameter in ∖adname.

25.3.2 The ∖addefinename command

The command ∖addefinename should usually not be used by library documentation writers, because these commands (with appropriate arguments) will be added automatically by the ALLPROSE script tools/addaldortypedef.pl.nw. Exceptions are places where functions are implemented in a domain and package and no explicit export of that function is given in the category part of the domain definition.

Consider, for example, the following piece from a literate Aldor program. Adding ∖addefinename is for =, because there is no place where ALLPROSE will add ∖addefinename{=: (%, %) -> Boolean} automatically. For foo, however, the definition in the chunk <<exports: MyDom>> and the preceding +++ environment trigger ALLPROSE to automatically generate ∖addefinename{foo: % -> Integer} right after the \begin{+++}.

The command ∖addefinename will print nothing in text, but define or re-define the command ∖adthisname. It makes sense not to print anything, since the command is added automatically to the text at a place where the documentation for that function or constant appears in a ++ or +++ description. The arguments are exactly as those of ∖adname. See also ∖adinternaldefinename.

25.3.3 The ∖admacro and ∖adassertion commands

The commands ∖admacro and ∖adassertion are provided in order to be able to document implementation details. These commands are not very interesting to be used in ++ descriptions.

where the argument NAME is set in typewriter mode. Additionally, NAME must also follow the naming Convention 26 of types.

In contrast to ∖addefinetype (which is not meant for documentation writers but rather will be generated automatically into the documentation) the commands ∖addefinemacro and ∖addefineassertion must be used at the place where the macro or assertion is defined. They are not automatically generated and, therefore, typeset in the running text. The reason for not generating these commands by a script is that there might be a macro or assertion defined at several places and one only wants to refer to one of them.

There can be several occurrences of these commands in the text if, for example, some macros with the same name are locally defined in different files. In this case the hyperlink will just refer to one of these definitions. With an appropriate color setting through the MAKE target colored in Makefile.nw, it is, however, possible to figure out the definition places from the index. Set the style for the ∖defineterm and ∖useterm commands (from the rhxterm LATEX package) through ∖defineTermStyle and ∖useTermStyle. For example,

shows the page numbers in the index of where a ∖defineterm command appears in red.