Singular Manual: The online help system

| ### 3.1.3 The online help system The online help system is invoked by the `help` command. `?` may be used as a synonym for `help`. Simply typing `help;` displays the "top" of the help system (i.e., the title page of the SINGULAR manual) which offers a short table of contents. Typing `help` topic`;` shows the available documentation on the respective topic. Here, topic may be either a function name or, more generally, any index entry of the SINGULAR manual. Furthermore, topic may contain wildcard characters. See help, for more information. Online help information can be displayed in various help browsers. The following table lists a summary of the browsers which are always present. Usually, external browsers are much more convenient: A complete, customizable list can be found in the file `LIB/help.cnf`.
Browser | Platform
| Description
html | Windows | displays a html version of the manual in your default html browser
builtin | all | simply outputs the help information in plain ASCII format
emacs | Unix, Windows | when running SINGULAR within (X)emacs, displays help inside the (X)emacs info buffer.
dummy | all | displays an error message due to the non-availability of a help browser

External browsers depend on your system and the contents of `LIB/help.cnf`, the default includes: `htmlview` (displays HTML help pages via `htlmview`),
`mac` (displays HTML help pages via `open`),
`mac-net` (displays HTML help pages via `open`),
`mozilla` (displays HTML help pages via `mozilla`),
`firefox` (displays HTML help pages via `firefox`),
`konqueror` (displays HTML help pages via `konqueror`),
`galeon` (displays HTML help pages via `galeon`),
`netscape` (displays HTML help pages via `netscape`),
`safari` (displays HTML help pages on MacOsX via `safari`),
`tkinfo` (displays INFO help pages via `tkinfo`),
`xinfo` (displays INFO help pages via `info`),
`info` (displays INFO help pages via `info`),
`lynx` (displays HTML help pages via `lynx`).

The browser which is used to display the help information, can be either set at startup time with the command line option (see Command line options)

    --browser=<browser>

or with the SINGULAR command (see system)

    system("--browser", "");

The SINGULAR command

    system("browsers");

lists all available browsers and the command

    system("--browser");

returns the currently used browser.

If no browser is explicitely set by the user, then the first available browser (w.r.t. the order of the browsers in the file `LIB/help.cnf`) is chosen.

The `.singularrc` (see Startup sequence) file is a good place to set your default browser. Recall that if a file `$HOME/.singularrc` exists on your system, then the content of this file is executed before the first user input. Hence, putting

    if (! system("--emacs"))
    {
      // only set help browser if not running within emacs
      system("--browser", "info");
    }
    // if help browser is later on set to a web browser,
    // allow it to fetch HTML pages from the net
    system("--allow-net", 1);

in your file `$HOME/.singularrc` sets your default browser to `info`, unless SINGULAR is run within emacs (in which case the default browser is automatically set to `emacs`).

Obviously, certain external files and programs are required for the SINGULAR help system to work correctly. If something is not available or goes wrong, here are some tips for troubleshooting the help system:

- Under Unix, the environment variable `DISPLAY` has to be set for all X11 browsers to work.

- The help browsers are only available if the respective programs are installed on your system (for `xinfo`, the programs `xterm` and `info` are necessary). You can explicitely specify which program to use, by changing the entry in `LIB/help.cnf`

- If the help browser cannot find the local html pages of the SINGULAR manual (which it will look for at `$RootDir/html` -- see Loading a library for more info on `$RootDir`) and the (command-line) option `--allow-net` has explicitely been set (see Command line options and system for more info on setting values of command-line options), then it dispatches the html pages from https://www.singular.uni-kl.de/Manual. (Note that the non-local net-access of HTML pages is disabled, by default.)
  An alternative location of a local directory where the html pages reside can be specified by setting the environment variable `SINGULAR_HTML_DIR`.

- The `info` based help browsers `tkinfo`, `xinfo`, `info`, and `builtin` need the (info) file `singular.hlp` which will be looked for at `$RootDir/info/singular.hlp` (see Loading a library for more info on `$RootDir`). An alternative location of the info file of the manual can be specified by setting the environment variable `SINGULAR_INFO_FILE`.

Command line options

#### Info help browsers

The help browsers `tkinfo`, `xinfo` and `info` (so-called info help browsers) are based on the `info` program from the GNU `texinfo` package. See section `Getting started' in The Info Manual, for more information.

For info help browsers, the online manual is decomposed into "nodes" of information, closely related to the division of the printed manual into sections and subsections. A node contains text describing a specific topic at a specific level of detail. The top line of a node is its "header". The node's header tells the name of the current node (`Node:`), the name of the next node (`Next:`), the name of the previous node (`Prev:`), and the name of the upper node (`Up:`).

To move within info, type commands consisting of single characters. Do not type `RETURN`. Do not use cursor keys, either. Using some of the cursor keys by accident might pop to some totally different node. Type `l` to return to the original node. Some of the `info` commands read input from the command line at the bottom. The `TAB` key may be used to complete partially entered input.

The most important commands are:

`q`
  leaves the online help system
`n`
  goes to the next node
`p`
  goes to the previous node
`u`
  goes to the upper node
`m`
  picks a menu item specified by name
`f`
  follows a cross reference
`l`
  goes to the previously visited node
`b`
  goes to the beginning of the current node
`e`
  goes to the end of the current node
`SPACE`
  scrolls forward a page
`DEL`
  scrolls backward a page
`h`
  invokes info tutorial (use `l` to return to the manual or `CTRL-X 0` to remove extra window)
`CTRL-H`
  shows a short overview over the online help system (use `l` to return to the manual or `CTRL-X 0` to remove extra window)
`s`
  searches through the manual for a specific string, and selects the node in which the next occurrence is found
`1`, ..., `9`
  picks i-th subtopic from a menu

User manual for Singular version 4-1-2p4, 2020, generated by texi2html.