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