% This LaTeX document was generated using the LaTeX backend of PlDoc,
% The SWI-Prolog documentation system



\subsection{library(help): Text based manual}

\label{sec:help}

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

By default the result of \predref{help}{1} is sent through a \textit{pager} such as
\const{less}. This behaviour is controlled by the following:

\begin{itemize}
    \item The Prolog flag \prologflag{help_pager}, which can be set to one of the
following values:

\begin{description}
    \termitem{false}{}
Never use a pager.
    \termitem{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 \verb$PAGER$
or otherwise tries to find the \const{less} program.
    \termitem{\arg{Callable}}{}
A \arg{Callable} term is interpreted as \verb$program_name(Arg, ...)$. For
example, \verb$less('-r')$ would be the default. Note that the
program name can be an absolute path if single quotes are
used.
\end{description}
\end{itemize}

\vspace{0.7cm}

\begin{description}
    \predicate[det]{help}{0}{}
\nodescription
    \predicate[det]{help}{1}{+What}
Show help for \arg{What}. \arg{What} is a term that describes the \verb$topics(s)$ to
give help for. Notations for \arg{What} are:

\begin{description}
    \termitem{\arg{Atom}}{}
This ambiguous form is most commonly used and shows all
matching documents. For example:

\begin{code}
?- help(append).
\end{code}

    \infixtermitem{\Sdiv}{\arg{Name}}{\arg{Arity}}
Give help on predicates with matching \arg{Name}/\arg{Arity}. \arg{Arity} may
be unbound.
    \infixtermitem{\Sidiv}{\arg{Name}}{\arg{Arity}}
Give help on the matching DCG rule (non-terminal)
    \termitem{f}{Name/Arity}
Give help on the matching Prolog arithmetic functions.
    \termitem{c}{Name}
Give help on the matching C interface function
    \termitem{section}{Label}
Show the section from the manual with matching \arg{Label}.
\end{description}

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 \textit{pager} such as the
\const{less} program. This behaviour is controlled by the Prolog flag
\verb$help_pager$. See section level documentation.

\begin{tags}
    \tag{See also}
\predref{apropos}{1} for searching the manual names and summaries.
\end{tags}

    \predicate[semidet,multifile]{show_html_hook}{1}{+HTML:string}
Hook called to display the extracted \arg{HTML} document. If this hook
fails the \arg{HTML} is rendered to the console as plain text using
\predref{html_text}{2}.

    \predicate[det]{apropos}{1}{+Query}
Print objects from the manual whose name or summary match with
\arg{Query}. \arg{Query} takes one of the following forms:

\begin{description}
    \infixtermitem{\Smodule}{\arg{Type}}{\arg{Text}}
Find objects matching \arg{Text} and filter the results by \arg{Type}.
\arg{Type} matching is a case intensitive \textit{prefix} match.
Defined types are \const{section}, \const{cfunction}, \const{function},
\verb$iso_predicate$, \verb$swi_builtin_predicate$, \verb$library_predicate$,
\const{dcg} and aliases \const{chapter}, \const{arithmetic}, \verb$c_function$,
\const{predicate}, \const{nonterminal} and \verb$non_terminal$. For example:

\begin{code}
?- apropos(c:close).
?- apropos(f:min).
\end{code}

    \termitem{\arg{Text}}{}
\arg{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.
\end{description}
\end{description}