7.1 Structuring conventions

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 three^{4Markdown 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>.}