help.pl -- Text based manual

This module provides help/1 and apropos/1 that give help on a topic or searches the manual for relevant topics.

By default the result of help/1 is sent through a pager such as less. This behaviour is controlled by the following:

The Prolog flag help_pager, which can be set to one of the following values:

false
Never use a pager.

default
Use default behaviour. This tries to determine whether Prolog is running interactively in an environment that allows for a pager. If so it examines the environment variable PAGER or otherwise tries to find the less program.

Callable
A Callable term is interpreted as program_name(Arg, ...). For example, less('-r') would be the default. Note that the program name can be an absolute path if single quotes are used.

help is det

help(+What) is det

Show help for What. What is a term that describes the topics(s) to give help for. Notations for What are:

Atom

This ambiguous form is most commonly used and shows all matching documents. For example:

?- help(append).

Name / Arity

Give help on predicates with matching Name/Arity. Arity may be unbound.

Name // Arity

Give help on the matching DCG rule (non-terminal)

Module:Name

Give help on predicates with Name in Module and any arity. Used for loaded code only.

Module:Name/Arity

Give help on predicates with Name in Module and Arity. Used for loaded code only.

f(Name/Arity)

Give help on the matching Prolog arithmetic functions.

c(Name)

Give help on the matching C interface function

section(Label)

Show the section from the manual with matching Label.

xpce(Class, Kind, Name)

Show the documentation of an XPCE class member.

help/1 shows documentation from the manual as well as from loaded user code if the code is documented using PlDoc. To show only the documentatoion of the loaded predicate we may prefix predicate indicator with the module in which it is defined.

If an exact match fails this predicates attempts fuzzy matching and, when successful, display the results headed by a warning that the matches are based on fuzzy matching.

If possible, the results are sent through a pager such as the less program. This behaviour is controlled by the Prolog flag help_pager. See section level documentation.

If the terminal supports hyperlinks (see the Prolog flag hyperlink_term), the manual references in the page are clickable. In an Epilog window, clicking one quits the pager and runs help/1 on the linked object.

See also: - apropos/1 for searching the manual names and summaries.

show_html_hook(+HTML:string) is semidet[multifile]

Hook called to display the extracted HTML document. If this hook fails the HTML is rendered to the console as plain text using html_text/2.

tty_width(-Width) is det[private]

Return the believed width of the terminal. If we do not know Width is bound to 80.

man_object_id(@Object, -ID) is semidet[private]

True when Object is a fully specified manual object with identifier ID. Predicate indicators are not included: these are ambiguous enough to be handled by the fuzzy matching clauses above.

current_predicate_help(?PI) is nondet[private]

True when we have documentation on PI. First we decide we have a definition for PI, then we check whether or not we have documentation for the module in which PI resides. If not, we switch to documentation collect mode and reload the file that defines PI.

main_source_file(+Pred, -File) is semidet[private]

True when File is the main (not included) file that defines Pred.

with_pager(+Goal)[private]

Send the current output of Goal through a pager. If no pager can be found we simply dump the output to the current output. We wait for the pager to terminate, so the toplevel does not print its prompt on the screen the pager is using.

pager(?Thread, ?PID) is nondet[private]

True while Thread is showing help using the pager process PID. Used by quit_pager/1 to get the pager out of the way if the user clicks a hyperlink in the page it is showing.

pager_screen(+Screen, +Which) is det[private]

Give the pager a screen of its own, so that quitting it leaves the terminal as it was. Windows only: a pager there takes a screen buffer from the console API and the console swaps back to the previous one when the pager exits, but a pseudo console -- which is what an Epilog window gives its children -- does not carry those calls. Its alternate screen is the DEC private mode and nothing else, so the terminal is told here rather than by the pager.

Elsewhere the pager does this itself, from its terminal description, and a pager that does not (cat) is one whose output should stay.

running_under_emacs[private]

True when we believe to be running in Emacs. Unfortunately there is no easy unambiguous way to tell.

apropos(+Query) is det

apropos(+Query, +Options) is det

Print objects from the manual whose name or summary match with Query. Query takes one of the following forms:

Type:Text

Find objects matching Text and filter the results by Type. Type matching is a case intensitive prefix match. Defined types are section, cfunction, function, iso_predicate, swi_builtin_predicate, library_predicate, dcg and aliases chapter, arithmetic, c_function, predicate, nonterminal and non_terminal. For example:

?- apropos(c:close).
?- apropos(f:min).

Text

Text is broken into tokens. A topic matches if all tokens appear in the name or summary of the topic. Matching is case insensitive. Results are ordered depending on the quality of the match.

Only the best limit matches are shown. Options:

limit(+Count): Maximum number of matches to show. Default 20.
offset(+Skip): Ignore the Skip best matches. Default 0.

If the terminal supports hyperlinks (see the Prolog flag hyperlink_term), the matches are clickable and so is the line that reports there are more matches. In an Epilog window, clicking these runs help/1 on the match or apropos/2 on the next page.

page(+List, +From, +Limit, -Page) is det[private]

Page is the sub list of List that starts at From and holds at most Limit elements.

help_apropos(+Query, -Obj, -Summary, -Score) is nondet

Find matching documented objects in the help database. Obj is the formal object identifier, Summary its summary description and Score is a number indicating the quality of the match.

help_text(+Predicate:term, -HelpText:string) is semidet

When Predicate is a term of the form Name/Arity for which documentation exists, HelpText is the documentation in textual format (parsed from the HTML help).

man_link(+Term, -Mapped) is semidet[private]

The link_scheme(man) option of man_page//2 already wrote the manual references as man: IRIs, which a terminal emits as OSC8 hyperlinks (see ansi_hyperlink/3) and tty_link_hook/2 below resolves when clicked. This maps the remaining links, which address the PlDoc server, onto the same IRIs. Links we cannot resolve are removed.

apropos_uri(+Query, +Offset, -URI) is det[private]

apropos_uri_goal(+URI, -Goal) is semidet[private]

Convert between an apropos: IRI and the apropos/2 goal that continues the search at Offset. Used to make the line telling there are more matches clickable.

epilog:tty_link_hook(+Terminal, +Link) is semidet[multifile]

Open a man: or apropos: link that was clicked in an Epilog Terminal. We quit the pager if it is still showing the page the link was clicked in and let the terminal run help/1 on the linked object or continue the apropos/2 search.

quit_pager(+Terminal) is det[private]

If the Prolog thread of Terminal is waiting for its pager, tell the pager to quit. All common pagers quit on q.

showing(+Query, +From, +End, +Total)// is det[private]

Emit the line telling which of the matches are shown. If not all matches are shown this is a link to the next page.

match_attributes(+Object, -Attributes) is det[private]

ANSI attributes for printing Object. If the terminal supports them, make the match a link that runs help/1 on Object.

ellipsis(-Ellipsis:string, -Length:integer) is det[private]

Ellipsis is appended to truncated text and Length is the number of columns it occupies. Use the Unicode horizontal ellipsis if the message stream can represent it.

man_object_summary(+Object, -Label:string, -Tag) is det[private]

Label is the text used to display Object in the apropos output. Tag is a short indication of the type of Object.

Re-exported predicates

The following predicates are exported from this file while their implementation is defined in imported modules or non-module files loaded by this module.