Sections and PlDoc

Help!
1

Would it be possible to delegate a certain job to PlDoc. Namely
to split a monolithic large Prolog text into little HTML pieces. I
am thinking of a Prolog text in the form:

:- module(large_module, ...).

:- section(sec_1).

...

:- section(sec_n).

...

The current specification of PlDoc says, one module one file:

Each source file is documented in a single file. In addition, the documentation generator will generate an index file that can be used as an index for a browser or input file for LaTeX for producing nicely typeset document.
https://www.swi-prolog.org/pldoc/doc_for?object=section%28%27packages/pldoc.html%27%29

Did I miss something? Or maybe should just chop up the
large module into many small files. Chopping up the file
has the disadvantage that one needs to export things,

that are usually local in the large module and not exported.
Also might end-up with cyclic import, which might not
work so well with some Prolog systems.

2

It is an open issue. When I designed PlDoc I had envisioned to allow something like below, which would create subsections in the module documentation and document the predicates defined in these subsections as part of this section.

/** <section> Title

Section comments 
*/

That never materialized :frowning:

Sub modules should of course work. My approach with big packages such as PlDoc is to have the user library/ies in the main library directory and have a subdir with all the basically private modules. I guess any sensible implementation of the module system should allow for cyclic dependencies. I doubt that all implementations of the Quintus module system allow for reexport/1 (surely not in all) or exporting an imported predicate (not sure).

3

Hi Jan,

I remember that we reached some consensus in Prolog Commons about some elements of the documentation system (e.g. “%! …”) but I’m not sure if we ever talked about sections. Just in case it helps, I’ll add some comments here about the current state in Ciao.

We also envisioned (sub(sub))sections in LPdoc (the Ciao documentation system) and we regularly use them:

%! # Section
%  Lorem ipsum dolor sit amet, consectetur adipiscing elit.
%
%  ## subsection
%  ...

despite the documentation generator still does not show them (still in the TODO list…). We can use \section{...} syntax (LPdoc markup) and markdown syntax.

Cheers,

1 Like