Console help system

General
1

Is there a way to add custom code to the regular console help system that can be used in the top-level? For example, adding the docs from a pack.

so I would like to do from the top level something like:

?- help(my_pack_predicate).

or some other predicate that I have documented with pldoc.

1 Like
2

Most of the functionality is there. The help/1 on the terminal works by fetching the HTML documentation and using a Prolog library for rendering this as text. PlDoc produces HTML from the structured comments.

Would require some plumbing. Any volunteers?

3

I’ll work on it, an tips on what files to look into?

My idea is to enhance the help/1 predicate to build the html on the fly if the sought predicate is not found in the main documentation. Let me know if this seems reasonable.

2 Likes
4

Jan has improved and merged a patch I sent, it is in the master branch. You are able to call:

  • help(my_currently_loaded_predicate) or
  • help(my_currently_loaded_module)

and it will show the documentation for the predicate or for the documented predicates in the module.

There is still todo the enhancement to show the module documentation. As Jan likes to say: Enjoy!

6 Likes
5

This is a really nice improvement, much appreciated!

I experience an issue where the PlDoc-based documentation is repeated multiple times when the source file has been loaded and then xref’ed with option comments(store):

?- ['sweep.pl'].
true.

?- help(sweep_accept_top_level_client).
/Users/eshelyaron/checkouts/sweep/sweep.pl


 sweep_accept_top_level_client(+Buffer, -Result) is det
    Signal the top-level server thread to accept a  new TCP  connection from
    buffer Buffer.
true.

?- xref_source('sweep.pl', [comments(store)]).
true.

?- help(sweep_accept_top_level_client).


 sweep_accept_top_level_client(+Buffer, -Result) is det
    Signal the top-level server thread to accept a  new TCP  connection from
    buffer Buffer.
 sweep_accept_top_level_client(+Buffer, -Result) is det
    Signal the top-level server thread to accept a  new TCP  connection from
    buffer Buffer.
 sweep_accept_top_level_client(+Buffer, -Result) is det
    Signal the top-level server thread to accept a  new TCP  connection from
    buffer Buffer.
 sweep_accept_top_level_client(+Buffer, -Result) is det
    Signal the top-level server thread to accept a  new TCP  connection from
    buffer Buffer.
true.

Any ideas where this might be coming from?

6

Possibly because the help system doesn’t look at the xref stored comments, but at the normal comments. If these are not there it reloads the file. Using the cross-referencer may be a better choice. PR welcome.

7

The problem happens because xref_source/2 adds a duplicate comment entry in the sweep module (you can see them with listing(sweep:'$pldoc'/4) ). If you pass the absolute path the problem is avoided:

3 ?- absolute_file_name('sweep.pl',F),xref_source(F, [comments(store)]).
F = '/tmp/swipl-devel/packages/sweep/sweep.pl'.
4 ?- help(sweep_accept_top_level_client).
% the pager shows it only once
/tmp/swipl-devel/packages/sweep/sweep.pl


 sweep_accept_top_level_client(+Buffer, -Result) is det
    Signal the top-level server thread to accept a new TCP connection from buffer Buffer.

true.

Perhaps xref_source/2 should always use the absolute file name?