16.3  Document Generation Tools

The document generation tools library provides a set of predicates for the generation of documentation from ECLⁱPS^e program sources. The tools generate documentation by processing the comment/2 directives in each source file. The following is an example comment for the n-queens example:

% comment for queen/2
:- comment(queen/2, [

    summary: "Program that solves the attacking Queens problem for
              an arbitrary number of queens.",

    index: ["NQueens Problem"],

    args: ["Data": "List modelling initial state of queens on board.",
       "Args": "Solution list of Y-coordinate of each queen on the
        board."],

    amode: queen(+,-),
    amode: queen(-,+),
    amode: queen(+,+),

    resat: yes,

    fail_if: "A solution cannot be found where all queens are safe
              from attack by every other.",

    see_also:
        [queens8/1, queensN/1],

    desc: html("The problem is to arrange a specified number of queens
           on a chessboard such that no queen attacks any other queen
           The predicate takes a list representing the initial state
           of the queens on the board, with each element representing
           a queen and its current Y-coordinate. If a solution is
           found, a list is returned specifying the safe Y-coordinate
    for each queen.")
   ]).  % end of comment directive for queen/2

There are two pertinent predicates for document generation. The first, icompile/2 generates an information file (with the extension .eci) by extracting information from a source file (whose extension is .ecl). The second, eci_to_html/3, processes this information file to produce readable HTML and plain text files. By default, these files are placed in a subdirectory with the same name as the information file, but without the extension. The generated files are index.html, containing a summary description of the library, plus one HTML and one plain text file for each predicate that was commented using a comment/2 directive in the source.

The following produces the queen.eci file and a queen directory in the current directory. Within the queen directory reside index.html, queen-2.html and queen-2.txt:

?- lib(document).
document.ecl compiled traceable 83620 bytes in 0.04 seconds
Yes (0.04s cpu)

?- icompile(queen, ".").
queen.ecl  compiled traceable 1432 bytes in 0.01 seconds
/examples/queen.eci generated in 0.00 seconds.
Yes (0.01s cpu)

?- eci_to_html(queen, ".", "").
Yes (0.00s cpu)