10.3 Using the browser interface

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.

10.3.1 Searching

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>. A search for adjacent strings is specified 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.

10.3.2 Views

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

10.3.3 Editing

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.