The documentation system is normally accessed from a web-browser
after starting the server using doc_server/1.
This section briefly explains the user-interface provided from the
browser.
The top-right of the screen provides a search-form. The search string
typed is searched as a substring and case-insensitive. Multiple strings
separated by spaces search for the intersection. Searching for objects
that do not contain a string is written as -"<string>".
Here are some examples:
load file | Searches for all objects with the
strings
load and file. |
load -file | Searches for objects with load,
but
without file. |
"load file" | Searches for the string load
file. |
The two radio-buttons below the search box can be used to limit the
search. All searches both the application and manuals. Searching
for Summary also implies Name.
The web-browser supports several views, which we briefly summarise
here:
- Directory
In directory-view mode, the contents of a directory holding Prolog
source-files is shown file-by-file in a summary-table. In addition, the
contents of the README and TODO files is
given.
- Source File
When showing a Prolog source-file it displays the module documentation
from the /** <module ... */ comment and the public
predicates with their full documentation. Using the zoom button
the user can select to view both public and documentated private
predicates. Using the source button, the system shows the source
with syntax highlighting as in PceEmacs and formatted structured
comments.7This mode is still
incomplete. It would be nice to add line-numbers and links to
documentation and definitions in the sources.
- Predicate
When selecting a predicate link the system presents a page with the
documentation of the predicate. The navigation bar allows switching to
the Source File if the documentation comes from source or the containing
section if the documentation comes from a manual.
- Section
Section from the manual. The navigation bars allows viewing the
enclosing section (Up).
If the browser is accessed from localhost, each object
that is related to a known source-location has an edit icon at the right
side. Clicking this calls edit/1
on the object, calling the user's default editor in the file. To use the
built-in PceEmacs editor, either set the Prolog flag editor
to pce_emacs or run ?- emacs. before clicking
an edit button.
Prolog source-files have a reload button attached. Clicking
this reloads the source file if it was modified and refreshes the page.
This supports a comfortable edit-view loop to maintain the source-code
documentation.
