doc_man.pl -- Process SWI-Prolog HTML manuals

man_nav_tree(+Obj, +Options) is semidet[private]

Create a navigation tree consisting of a nested ul list that reflects the location of Obj in the manual.

man_nav_tree(+Obj, -Tree, +Options) is semidet[private]

True when Tree is the navigation tree for Obj. By default, this is the tree going from the leaf to the root, unfolding the neighbors of Obj.

man_child_of(?Child, ?Parent) is nondet[private]

Query the manual hierarchy.

ensure_man_tree[private]

Materialize the manual tree as a binary relation.

man_content_tree(+Dir, -Tree) is det

Compute the content tree for a multi-file HTML document. We do this by processing Contents.html for making the toplevel tree that links to the individual files. Then we use html_content_tree/2 to materialize the trees for the files.

man_packages_tree(-Tree) is det

Tree is the content tree of all packages

html_content_tree(+ManualFile, -Tree) is det[private]

True when Tree represents the hierarchical structure of objects documented in the HTML file ManualFile. Tree is a term where of the form below. Object is a documentation object (typically a section or predicate indicator) that may be handed to object_link//1 and similar predicates to make a table of contents.

node(Object, ListOfTree).

load_man_object(+Obj, -Parent, -Path, -DOM) is nondet[private]

load the desription of the object matching Obj from the HTML sources and return the DT/DD pair in DOM.

To be done: - Nondet?

resolve_section(+SecIn, -SecOut) is det[private]

Resolve symbolic path reference and fill in level and section number if this information is missing. The latter allows us to refer to files of the manual.

parent_section(+Section, -Parent) is det[private]

Parent is the parent-section of Section. First computes the section number and than finds the required number in the same file or same directory. If this doesn't exist, get the file as a whole.

object_section(+Path, +Position, -Section) is semidet[private]

Section is the section in which object appears. This is the last section object before position.

object_spec(+Atom, -SpecTerm)[private]

Tranform the Name/Arity, etc strings as received from the HTTP into a term. Must return unique results.

man_page(+Obj, +Options)// is semidet

Produce a Prolog manual page for Obj. The page consists of a link to the section-file and a search field, followed by the predicate description. Obj is one of:

Name/Arity Predicate indicator: display documentation of the predicate
f(Name/Arity) display documentation of an arithmetic function
c(Function) display documentation of a C API function
section(Level, Number, Id, File) Display a section of the manual
sec(DocFile#Id) Display a section of the manual (from short form)

Options:

no_manual(Action): If Action = fail, fail instead of displaying a not-found message.
synopsis(Bool): If false, omit the synopsis line
links(Bool): If true (default), include links to the parent object; if false, just emit the manual material.
navtree(Bool): If true (default), display the navigation tree, otherwise suppress it.

full_object(+Object, -Full) is semidet[private]

Translate to canonical PlDoc object

man_qualified_object(+Object, +Parent, -LibraryOpt, -QObject, -Section) is semidet[private]

Get a qualified predicate description from Text that appears in the section Parent.

The tricky part is that there are cases where multiple modules export the same predicate. We must find from the title of the manual section which library is documented.

man_synopsis(+Object, +Section)//

Give synopsis details for a fully specified predicate indicator and link this to the section.

object_module(+Section0, -Module, -Section, -LibOpt) is semidet[private]

Find the module documented by Section.

man_match(+Term, +Object, +Options)// is det[private]

If possible, insert the synopsis into the title of the description.

public_link(+Spec, -HREF)[private]

We do not have a web server. Create a link to the public server instead.

bug: - The predicate may not be there.

documented(+PI) is semidet[private]

True if we have documentation about PI

rewrite_ref(+Class, +Ref0, +Path, -ManRef, +Options) is semidet[private]

Rewrite Ref0 from the HTML reference manual format to the server format. Reformatted:

File#Name/Arity: Local reference using the manual presentation /man?predicate=PI.
File#sec:NR: Rewrite to section(Level, NT, ID, FilePath)
File#flag:Name: Rewrite to section(Level, NT, ID, FilePath)#flag:Name
File#gloss:Name: Rewrite to section(Level, NT, ID, FilePath)#gloss:Name
$ File#Name() Rewrite to /man/CAPI=Name

Arguments:

Class

- Class of the <A>. Supported classes are

sec	Link to a section
pred	Link to a predicate
flag	Link to a Prolog flag
gloss	Link to a glossary

Ref0 - Initial reference from the a element

Path - Currently loaded file

ManRef - PlDoc server reference

referenced_section(+Fragment, +File, +Path, -Section)[private]

man_links(+ParentPaths, +Options)// is det[private]

Create top link structure for manual pages.

section_link(+Obj, +Options)// is det[private]

Create link to a section. Options recognised:

secref_style(+Style): One of number, title or number_title.

function_link(+Function, +Options) is det[private]

Create a link to a C-function

man_overview(+Options)// is det

Provide a toplevel overview on the manual: the reference manual and the available packages.

pldoc_jpl(+Request)[private]

Hack to include JPL documentation in server.

pldoc_package(+Request)[private]

HTTP handler for PlDoc package documentation. Accepts /pldoc/package/<package>.{html,gif}. The path =/pldoc/package/<package>= is redirected to the canonical object version.

pldoc_package_overview(+Request)[private]

Provide an overview of the package documentation

paperback(+Options)//[private]

Link to the paperback version of the manual.

pldoc_refman(+Request)[private]

HTTP handler for PlDoc Reference Manual access. Accepts /refman/[<package>.html.]

prolog:doc_object_link(+Obj, +Options)//[multifile]

Provide the HTML to describe Obj for linking purposes.

prolog:doc_object_href(+Object, -HREF) is semidet[multifile]

Produce a HREF for section objects.