Structured comments that provide part of the documentation are
written in Wiki notation, based on TWiki,
with some Prolog specific additions.
- Paragraphs
- Paragraphs are separated by a blank line. Paragraphs that are indented
in the source-code after normalising the left-margin with at
least 16 spaces are centered. Paragraphs where all the lines
start with “
>
” (greater than followed by a
blank) are rendered in the HTML backend using a blockquote
element and in LaTeX using the quote
environment.
- General lists
- The wiki knows three types of lists: bullet lists (HTML
ul
), numbered lists (HTML ol
) and
description lists (HTML dl
). Each list environment
is headed by an empty line and each list-item has a special symbol at
the start, followed by a space. Each subsequent item must be indented at
exactly the same column. Lists may be nested by starting a new list at a
higher level of indentation. The list prefixes are:
* | Bulleted list item |
1. | Numbered list item. Any number from 1..9
is allowed, which allows for proper numbering in the source. Actual
numbers in the HTML or LaTeX however are re-generated, starting at 1. |
$ Title : Item | Description list item. |
- Term lists
- Especially when describing option lists or different accepted types, it
is common to describe the behaviour on different terms. Such lists must
be written as below. <Term1>, etc. must be valid Prolog
terms and end in the newline. The Wiki adds
' . '
to the
text and reads it using the operator definitions also used to read the
mode terms. See section 5. Variable
names encountered in the Term are used for indentifying
variables in the following
Description. At least one Description must be
non-empty to avoid confusion with a simple item list.
* Term1
Description
* Term2
Description
- Predicate description lists
- Especially for processing Wiki files, the Wiki notation allows for
including the description of a predicate‘in-line', where the
documentation is extracted from a loaded source file. For example:
The following predicates are considered Prolog's prime list processing
primitives:
* [[member/2]]
* [[append/3]]
- Tables
- The Wiki provides only for limited support for tables. A table-row is
started by a
|
sign and the cells are
separated by the same character. The last cell must be ended with |
.
Multiple lines that parse into a table-row together form a table.
Example:
| Algorithm | Time (sec) |
| Depth first | 1.0 |
| Breath first | 0.7 |
| A* | 0.3 |
- Section Headers
- Section headers are creates using one of the constructs below taken from
TWiki. Section headers are normally not used in the source-code, but can
be useful inside README and TODO files. See section
8.
---+ Section level 1
---++ Section level 2
---+++ Section level 3
---++++ Section level 4
In addition, PlDoc recognises the markdown syntax, including
named sections as defined by doxygen. A section is named
(labeled) using an optional sequence {\#
name}
.
The three code sections below provide examples. Note that #
section headers should be positioned at the left margin and the
#
must be followed by blank space. If the header is
underlined, the underline is a line that only contains =
or
-
characters. There must be a minimum of three4Markdown
demands two, but this results in ambiguities with the ==
fence for code blocks. of such characters.
Section level 1
===============
Section level 2
---------------
# Section level 1
## Section level 2
### Section level 3
#### Section level 4
Section level 1 {#label}
===============
# Section level 1 {#label}
- Code blocks
- There are two ways to write a code block. The first one is
fenced. Here, the block is preceeded and followed by a fence
line. The traditional PlDoc fence line is
==
. Doxygen fence
lines are also accepted. They contain at least three tilde (~
)
characters, where the opening fence line may be followed by a file
extension between curly brackets. In all cases, the code is indented
relative to the indentation of the fence line. Below are two examples,
the first being the traditional PlDoc style. The second is the Doxygen
style, showing a code block that is indented (because it is a body
fragment) and that is flagged as Prolog source. Note that the
{.pl}
is optional.
==
small(X) :-
X < 2.
==
~~~{.pl}
...,
format('Hello ~w~n', [World]),
...,
~~~
The second form of code blocks are indented blocks. Such a
block must be indented between 4 and 8 characters, relative to the
indentation of the last preceeding non-blank line. The block is opened
with a blank line and closed by a blank line or a line that is indented
less than the indentation of the initial line. It is allowed to have a
single blank line in the middle of a code block, provided that the next
line is again indented at least as much as the initial line. The initial
line as well as a line that follows a blank line may not be a valid list
opening line or a table row, i.e., it may not start with one of
*-
followed by a space or |
.
- Rulers
- PlDoc accepts both the original PlDoc and markdown conventions for
rulers. A PlDoc ruler is a line with at least two dashes (-) that starts
at the left-most column. A markdown ruler holds at least three ruler
characters and any number of spaces. The ruler characters are the dash
(-), underscore (
_
) or asterisk (*
). Below are
three examples, the last two of which are valid markdown.
--
***
- - -
- Line breaks
- A line break may be added by ending the physical line with the
HTML linebreak,
<br>
or <br/>
.5The
markdown conventions are (original) two spaces at the of the physical
line and (GitHub) a physical line break. Neither fit well with source
code. Doxygen supports restricted HTML and allows for <br>
.
Text emphasis is a combination of old plaintext conventions in Usenet
and E-mail and the doxygen version of markdown. Table
1 shows the font-changing constructions. The phrase limited
context means that
- The opening
*
or _
must be
preceeded by white space or a character from the set <{([,:;
and must be followed by an alphanumerical character.
- The closing
*
or _
may not be
followed by an alphanumerical character and may not be preceeded by
white space or a character from the set ({[<=+-\@
.
- The scope of these operations is always limited to the identified
structure (paragraph, list item, etc.)
Note that =
<identifier>=
is limited to a an
identifier, such as a file name, XML name, etc. Identifiers
must start and end with an alphanumerical character, while characters
from the set .-/:
may appear internally. Note that this set
explicitly does not allow for white space in code spans delimited by a
single =
. This markup is specifically meant to
deal with code that is either not Prolog code or invalid Prolog code.
Valid Prolog code should use the backtick as described in section
7.2.2.
*bold* | Typeset text in bold for
limited content (see running text). |
*|bold|* | Typeset text in bold.
Content can be long. |
_emphasize_ | Typeset text as emphasize
for limited content (see running text). |
_|emphasize|_ | Typeset text as emphasize.
Content can be long. |
=code= | Typeset text fixed font
for identifiers (see running text). |
=|code|= | Typeset text fixed
font. Content can be long. |
Word | Capitalised words that appear as
argument-name are written in Italic |
Table 1 : Wiki constructs to change the font
Inline code can be realised using the =
switch described
in
section 7.2.1 or the markdown
backtick. In addition, it can use the mardown/Doxygen backtick
(`
) convention: a string that is delimited by backticks is
considered code, provided:
- An internal double backtick is translated into a single backtick.
- Inline code is limited to the current structure (paragraph, table
cell, list item, etc.
- The content of the code block is valid Prolog syntax. Note that in
Doxygen, the syntax is not validated and a single quote cancels the
recognition as code. The latter is a problematic in Prolog because
single quotes are often required.
Currently,‘Var` is typeset as a variable (italics) and other
terms are typeset using a fixed-width code font.
In addition, compound terms in canonical notation (i.e.,
functor(
,...args...)
that can be
parsed are first verified as a file-specification for
absolute_file_name/3
and otherwise rendered as code.
Table 2 shows the constructs for
creating links.
name/arity | Create a link to a predicate |
`name/arity` | Create a link to a predicate |
``name/arity`` | Predicate indicator that
does not create a link |
name//arity | Create a link to a DCG rule |
`name//arity` | Create a link to a DCG rule |
``name//arity`` | DCG indicator that does
not create a link |
flag `name` | Create a link to the Prolog
flag name if this flag exists. |
name.ext | If <name>.<ext>
is the name of an existing file and <ext> is one of .pl , .txt ,
.md , .png , .gif , .jpeg ,
.jpg or .svg , create a link to the file. |
prot:// url | If <prot>
is one of http , https or ftp ,
create a link. |
< url>
| Create
a hyperlink to URL. This construct supports the expand_url_path/2
using the construct
<alias>:<local>. <local>
can be empty. |
[[ label][ link]]
| Create
a link using the given <label>. Label can be text or a
reference to an image file. Additional arguments can be supplied as
; <name>=" <value>" .
More arguments are separated by commas. <link> must be
a filename as above or a url. |
[ label]( link)
| The
markdown version of the above. |
[ @cite]
| Include
LaTeX citation. Multiple citations can be saparated using ; .
No white space is allowed. |
Table 2 : Wiki constructs that create links
Images can be included in the documentation by referencing an image
file using one of the extensions .gif
, .png
,
.jpeg
, .jpg
or .svg
.6SVG
images are included using the object
element. This is
supported by many modern browsers. When using IE, one needs at least
IE9. By default this creates a link to the image file that
must be visited to see the image. Inline images can be created by
enclosing the filename in double square brackets. For example
The [[open.png]] icon is used open an existing file.
The markdown alternative for images is also supported, and looks as
below. The current implementation only deals with image files,
not external resources.
