doc_html.pl -- PlDoc HTML backend

This module translates the Herbrand term from the documentation extracting module doc_wiki.pl into HTML+CSS.

To be done: - Split put generation from computation as computation is reusable in other backends.

doc_for_file(+File, +Options) is det

HTTP handler that writes documentation for File as HTML. Options:

public_only(+Bool): If true (default), only emit documentation for exported predicates.
edit(Bool): If true, provide edit buttons. Default, these buttons are suppressed.
title(+Title): Specify the page title. Default is the base name of the file.

Arguments:

File

- Prolog file specification or xref source id.

doc_resources(+Options)// is det

Include required resources (CSS, JS) into the output. The first clause supports doc_files.pl. A bit hacky ...

doc_file_objects(+FileSpec, -File, -Objects, -FileOptions, +Options) is det

Extracts relevant information for FileSpec from the PlDoc database. FileOptions contains:

file(Title:string, Comment:string)
module(Module:atom)
public(Public:list(predicate_indicator)

Objects contains

doc(PI:predicate_indicator, File:Line, Comment)

We distinguish three different states for FileSpec:

File was cross-referenced with collection enabled. All information is in the xref database.
File was loaded. If comments are not loaded, cross-reference the file, while storing the comments as the compiler would do.
Neither of the above. In this case we cross-reference the file.

Arguments:

`FileSpec`	- `File` specification as used for load_files/2.
`File`	- Prolog canonical filename

ensure_doc_objects(+File) is det

Ensure we have documentation about File. If we have no comments for the file because it was loaded before comment collection was enabled, run the cross-referencer on it to collect the comments and meta-information.

Arguments:

File

- is a canonical filename that is loaded.

module_info(+File, -ModuleOptions, +OtherOptions) is det

Add options module(Name), public(Exports) to OtherOptions if File is a module file.

doc_hide_private(+Objs, +Public, +Options)

Remove the private objects from Objs according to Options.

private(+Obj, +Options) is semidet

True if Obj is not exported from Options. This means Options defined a module and Obj is not member of the exports of the module.

prolog:doc_is_public_object(+Object) is semidet[multifile]

Hook that allows objects to be displayed with the default public-only view.

multifile(+Obj, +Options) is semidet

True if Obj is a multifile predicate.

file_header(+File, +Options)// is det

Create the file header.

edit_button(+File, +Options)// is det

Create an edit button for File. If the button is clicked, JavaScript sends a message to the server without modifying the current page. JavaScript code is in the file pldoc.js.

zoom_button(BaseName, +Options)// is det

Add zoom in/out button to show/hide the private documentation.

source_button(+File, +Options)// is det

Add show-source button.

objects(+Objects:list, +Options)// is det

Emit the documentation body. Options includes:

navtree(+Boolean): If true, provide a navitation tree.

is_pi(@Term) is semidet

True if Term is a predicate indicator.

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

Generate an HTML page describing Obj. The top presents the file the object is documented in and a search-form. Options:

header(+Boolean): Show the navigation and search header.

object_page_footer(+Obj, +Options)// is det

Call the hook doc_object_page_footer//2. This hook will be used to deal with annotations.

object_synopsis(Obj, Options)// is det

Provide additional information about Obj. Note that due to reexport facilities, predicates may be available from multiple modules.

To be done: - Currently we provide a synopsis for the one where the definition resides. This is not always correct. Notably there are cases where multiple implementation modules are bundled in a larger interface that is the `preferred' module.

unquote_filespec(+Spec, -Unquoted) is det

Translate e.g. library('semweb/rdf_db') into library(semweb/rdf_db).

doc_write_html(+Out:stream, +Title:atomic, +DOM) is det

Write HTML for the documentation page DOM using Title to Out.

doc_page_dom(+Title, +Body, -DOM) is det

Create the complete HTML DOM from the Title and Body. It adds links to the style-sheet and javaScript files.

print_html_head(+Out:stream) is det

Print the DOCTYPE line.

tags(+Tags)// is det

Emit the @tag tags of a description. Tags is produced by tags/3.

See also: - combine_tags/2.

doc_tag_title(+Tag, -Title) is det

Title is the name to use for Tag in the generated documentation.

object_tree(+Tree, +Current, +Options)// is det

Render a tree of objects used for navigation.

pred_edit_button(+PredIndicator, +Options)// is det

Create a button for editing the given predicate. Options processed:

module(M): Resolve to module M
file(F): For multi-file predicates: link to version in file.
line(L): Line to edit (in file)

object_edit_button(+Object, +Options)// is det

Create a button for editing Object.

object_source_button(+Object, +Options)// is det

Create a button for showing the source of Object.

is_op_type(+Atom, ?Type)

True if Atom is an operator of Type. Type is one of prefix, infix or postfix.

term(+Text, +Term, +Bindings)// is det

Process the \term element as produced by doc_wiki.pl.

To be done: - Properly merge with pred_head//1

predref(+PI)// is det

predref(+PI, +Options)// is det

Create a reference to a predicate. The reference consists of the relative path to the file using the predicate indicator as anchor.

Current file must be available through the global variable pldoc_file. If this variable not set it creates a link to /doc/<file>#anchor. Such links only work in the online browser.

object_ref(+Object, +Options)// is det

Create a hyperlink to Object. Points to the /doc_for URL. Object is as the first argument of doc_comment/4. Note this can be a list of objects.

object_href(+Object, -HREF) is det

object_href(+Object, -HREF, +Options) is det

HREF is the URL to access Object.

object_name(+Obj, +Options)// is det

HTML description of documented Obj. Obj is as the first argument of doc_comment/4. Options:

style(+Style): One of inline or title
qualify(+Boolean): Qualify predicates by their module
secref_style(Style): One of number, title or number_title

file(+FileName)// is det

file(+FileName, +Options)// is det

Create a link to another filename if the file exists. Called by \file(File) terms in the DOM term generated by wiki.pl. Supported options are:

label(+Label): Label to use for the link to the file.
absolute_path(+Path): Absolute location of the referenced file.
href(+HREF): Explicitely provided link; overrule link computation.
map_extension(+Pairs): Map the final extension if OldExt-NewExt is in Pairs.
files(+Map): List of file(Name, Link) that specifies that we must user Link for the given physical file Name.
edit_handler(+Id): HTTP handler Id to call if the user clicks the edit button.

To be done: - Translation of files to HREFS is a mess. How to relate these elegantly?

existing_linked_file(+File, -Path) is semidet

True if File is a path to an existing file relative to the current file. Path is the absolute location of File.

include(+FileName, +Type, +Options)// is det

Inline FileName. If this is an image file, show an inline image. Else we create a link like file//1. Called by \

include(File,
Type)

terms in the DOM term generated by wiki.pl if it encounters [[file.ext]].

doc_for_wiki_file(+File, +Options) is det

Write HTML for the File containing wiki data.

mode_anchor_name(+Mode, -Anchor:atom) is det

Get the anchor name for a mode.

pred_anchor_name(+Head, -PI:atom/integer, -Anchor:atom) is det

Create an HTML anchor name from Head.

predref(+PI)// is det

predref(+PI, +Options)// is det

Create a reference to a predicate. The reference consists of the relative path to the file using the predicate indicator as anchor.

Current file must be available through the global variable pldoc_file. If this variable not set it creates a link to /doc/<file>#anchor. Such links only work in the online browser.

file(+FileName)// is det

file(+FileName, +Options)// is det

Create a link to another filename if the file exists. Called by \file(File) terms in the DOM term generated by wiki.pl. Supported options are:

label(+Label): Label to use for the link to the file.
absolute_path(+Path): Absolute location of the referenced file.
href(+HREF): Explicitely provided link; overrule link computation.
map_extension(+Pairs): Map the final extension if OldExt-NewExt is in Pairs.
files(+Map): List of file(Name, Link) that specifies that we must user Link for the given physical file Name.
edit_handler(+Id): HTTP handler Id to call if the user clicks the edit button.

To be done: - Translation of files to HREFS is a mess. How to relate these elegantly?

Undocumented predicates

The following predicates are exported, but not or incorrectly documented.

object_page_header(Arg1, Arg2, Arg3, Arg4)