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:

1. File was cross-referenced with collection enabled. All information is in the xref database.
2. File was loaded. If comments are not loaded, cross-reference the file, while storing the comments as the compiler would do.
3. 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

 xref_doc_object(File, DocObject) is nondet[private]

 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.

 obj(+Term, -Object) is det[private]

Extract the documented object from its environment. It is assumed to be the first term. Note that if multiple objects are described by the same comment Term is a list.

 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.

 public(+Options, +Options)[private]

True if Obj is declared using public/1.

 file_info(+Comments, -RestComment, -FileOptions, +OtherOptions) is det[private]

Add options file(Title, Comment) to OtherOptions if available.

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

Create the file header.

 file_title(+Title:list, +File, +Options)// is det[private]

Emit the file-header and manipulation buttons.

 reload_button(+File, +Base, +Options)// is det[private]

Create a button for reloading the sources and updating the documentation page. Note that the button is not shown if the file is not loaded because we do not want to load files through the documentation system.

 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.

 object(+Spec, +ModeIn, -ModeOut, +Options)// is det[private]

Emit the documentation of a single object.

Arguments:

Spec	- is one of doc(Obj,Pos,Comment), which is used to list the objects documented in a file or a plain Obj, used for documenting the object regardless of its location.

 need_mode(+Mode:atom, +Stack:list, -NewStack:list)// is det[private]

While predicates are part of a description list, sections are not and we therefore need to insert <dl>...</dl> into the output. We do so by demanding an outer environment and push/pop the required elements.

 undocumented(+File, +Objects, +Options)// is det[private]

Describe undocumented predicates if the file is a module file.

 eq_pi(PI1, PI2) is semidet[private]

True if PI1 and PI2 refer to the same predicate.

 is_pi(@Term) is semidet

True if Term is a predicate indicator.

 re_exported_doc(+Undoc:list(pi), +File:atom, +Module:atom, -ImportedDoc, -ReallyUnDoc:list(pi))[private]

 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_footer(+Obj, +Options)// is det

Call the hook doc_object_footer//2. This hook is used by the examples machinery. When the changelog support is installed (cmake -DCHANGELOG=ON), a small block listing introduction and last change is appended after the hook output — see object_changelog//2.

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

Emit a small footer noting when Obj (a Name/Arity, possibly module- or DCG-qualified, or a list of such, or f(...)) was introduced and when it was last changed. Empty when no events are known or when the changelog support was not built (CHANGELOG cmake option off). Each version is rendered as Maj.Min.Patch and linked to the underlying commit on GitHub.

 objs_pis(+Objs, -PIs) is det[private]

Filter Objs (a list of documentation objects) to the predicate indicators stored in changelog_event/7. Module qualifiers are stripped; DCG arity is folded to the underlying predicate arity (the extractor does not yet emit // events separately). Other object shapes (xpce(...), c(...), f(...), library(...), section(...)) are dropped so the footer is suppressed for them.

 changelog_union_line(+PIs, -Line) is nondet[private]

Emit one paragraph (Line) for the introduction event (only if every PI in the block has an introduction event in the tracked range; otherwise the line is suppressed to avoid implying the whole family is newer than the older members really are), and one paragraph for the most recent change across any family member.

 all_introduced(+PIs, -Event) is semidet[private]

Succeeds when every PI has an introduction event in the tracked range. Version is the highest such introduction version across the family — i.e. the version at which the family reached its currently-documented shape. Hash and Repo identify a representative commit (the one at that highest version).

 union_last_changed(+PIs, -Events:list) is det[private]

Most recent change event across PIs, ranked by version. Fails if no PI has a change event in the tracked range.

 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.

 tag(+Tag, +Values:list)// is det

Called from \tag(Name, Values) terms produced by doc_wiki.pl.

 doc_tag_title(+Tag, -Title) is det

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

 args(+Params:list) is det[private]

Called from \args(List) created by doc_wiki.pl. Params is a list of arg(Name, Descr).

 objects_nav_tree(+Objects, -Tree) is det[private]

Provide a navigation tree showing the context of Object. Tree is of the form node(Object, Children).

 remove_unique_root(+TreeIn, -Tree)[private]

Remove the root part that does not branch

 nav_tree(+Tree, +Current, +Options)// is det[private]

Render the navigation tree

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

Render a tree of objects used for navigation.

 pred_dt(+Modes, +Class, Options)// is det

Emit the predicate header.

Arguments:

Modes

- List as returned by process_modes/5.

 anon_vars(+Term) is det[private]

Bind remaining variables in Term to '$VAR'('_'), so they are printed as '_'.

 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.

 pred_source_button(+PredIndicator, +Options)// is det[private]

Create a button for viewing the source of a predicate.

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

Create a button for showing the source of Object.

 canonicalise_predref(+PredRef, -PI:Name/Arity, +Options0, -Options) is det[private]

Canonicalise a predicate reference. A possible module qualifier is added as module(M) to Options.

 pred_head(+Term) is det[private]

Emit a predicate head. The functor is typeset as a span using class pred and the arguments and var using class arglist.

 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.

 nopredref(+PI)//

Result of name/arity, non-linking predicate indicator.

 flagref(+Flag)//

Reference to a Prolog flag.

To be done

- generate a link to the Prolog website?

 cite(+Citations)// is det

Emit citations. This is indented to allow for [@cite1;@cite2] for generating LaTex.

 manref(+NameArity, -HREF, +Options) is det[private]

Create reference to a manual page. When generating files, this listens to the option man_server(+Server).

 pred_href(+NameArity, +Module, -HREF) is semidet[private]

Create reference. Prefer:

1. Local definition
2. If from package and documented: package documentation
3. From any file

bug

- Should analyse import list to find where the predicate comes from.

 pred_source_href(+Pred:predicate_indicator, +Module, -HREF) is semidet[private]

HREF is a URL to show the predicate source in its file.

 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.

 localise_object(+ObjIn, -ObjOut) is det[private]

Abstract path-details to make references more stable over versions.

 term_to_string(+Term, -String) is det[private]

Convert Term, possibly holding variables, into a canonical string using A, B, ... for variables and _ for singletons.

 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

 in_file(+Head, ?File) is nondet[private]

File is the name of a file containing the Predicate Head. Head may be qualified with a module.

To be done

- Prefer local, then imported, then `just anywhere'

- Look for documented and/or public predicates.

 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?

 file_href(+FilePath, -HREF, +Options) is det[private]

Find URL for refering to FilePath based on Options.

 map_extension(+HREFIn, -HREFOut, Options) is det[private]

Replace extension using the option

• map_extension(+Pairs)

 file_href(+FilePath, -HREF) is det[private]

Create a relative URL from the current location to the given absolute file name. It resolves the filename relative to the file being processed that is available through the global variable pldoc_file.

 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]].

 html_tokens_for_predicates(+PI, +Options)// is semidet[private]

Inline description for a predicate as produced by the text below from wiki processing.

        * [[member/2]]
        * [[append/3]]

 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.

Undocumented predicates

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

 object_page_header(Arg1, Arg2, Arg3, Arg4)