doc_man.pl -- Process SWI-Prolog HTML manuals

 clean_man_index is det

Clean already loaded manual index.

 manual_directory(-Class, -Dir)// is nondet[private]

True if Dir is a directory holding manual files. Class is an identifier used by doc_object_summary/4.

 index_manual is det[private]

Load the manual index if not already done.

 index_man_directory(Dir, +Options) is det

Index the HTML directory Dir. Options are:

class(Class)

Define category of the found objects.

Remaining Options are passed to absolute_file_name/3.

 index_man_file(+Class, +File)

Collect the documented objects from the SWI-Prolog manual file File.

 index_on_begin(+Element, +Attributes, +Parser) is semidet[private]

Called from sgml_parse/2 in index_man_file/2. Element is the name of the element, Attributes the list of Name=Value pairs of the open attributes. Parser is the parser objects.

 dom_section(+HeaderDOM, -NR, -Title) is semidet[private]

NR is the section number (e.g. 1.1, 1.23) and Title is the title from a section header. The first clauses processes the style information from latex2html, emitting sections as:

<HN> <A name="sec:nr"><span class='sec-nr'>NR</span>|_|
                      <span class='sec-title'>Title</span>

 summary(+DOM, -Summary:string) is det[private]

Summary is the first sentence of DOM.

 dom_to_text(+DOM, -Text)[private]

Extract the text of a parsed HTML term. White-space in the result is normalised. See normalise_white_space//1.

 current_man_object(?Object) is nondet

 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.

links(Bool)

If true (default), include links to the parent object; if false, just emit the manual material.

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

Translate to canonical PlDoc object

 man_qualified_object(+Text, +Parent, -Object, -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)//[private]

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

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

Find the module documented by Section.

To be done

- This requires that the documented file is loaded. If not, should we use the title of the section?

 man_match(+Term, +Object)//[private]

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

 documented(+PI) is semidet[private]

True if we have documentation about PI

 rewrite_ref(+Class, +Ref0, +Path, -ManRef) 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#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
Ref0	- Initial reference from the a element
Path	- Currently loaded file
ManRef	- PlDoc server reference

 name_to_object(+Atom, -PredicateIndicator) is semidet[private]

If Atom is `Name/Arity', decompose to Name and Arity. No errors.

 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.