Document Generation Tools

## 15.3 Document Generation Tools

The document generation tools library provides a set of predicates for the generation of documentation from ECLiPSe 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 (.eci) by extracting information from a source file (.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)