Add embedded help predicate.

[XVilka]

help/0 and help/1, like in SWI-Prolog, that would be quite useful http://www.swi-prolog.org/pldoc/man?section=help

[kastiglione]

@UWN as a quiet observer and being new to prolog systems, why don't you think help predicates should be available? Are there downsides?

[triska]

Please let me offer my (unsolicited) perspective: I did not downvote this suggestion, because I am glad that people are interested in contributing and have the courage to suggest something.

Still, there are significant downsides for implementors in getting sidetracked with things that can also be covered (and possibly even better covered) in other ways. Take SICStus Prolog for example, where the entire documentation is available as Info pages that can be browsed with Emacs, and searched in their entirety with Emacs. This is a key attraction of SICStus Prolog, and in my opinion worth emulating. It makes a built-in help system unnecessary.

As another example, take SWI-Prolog itself: It has hundreds of features, even including a toy Emacs implementation (where important key strokes of actual Emacs behave differently), the mentioned built-in help system, a tracer etc., yet still lacks many of the most essential features that are needed to implement advanced Prolog applications (such as strong syntactic guarantees, a useful interface to attributed variables, a working version of CLP(Q), efficient lists of characters for double-quoted strings etc.). This shows that there is a real risk for implementors to get caught up in tasks that do not improve the core system. Let how this has turned out serve as a warning for implementors.

Please do not take any downvotes personally: In this case, if I read them correctly, they only express the downvoter's (in this case: valuable) opinion that the main effort should better be aimed elsewhere. At least as I see it, the key promise of Scryer Prolog is the potential to get a lean, fast, and ISO compliant Prolog system that provides the right key ingredients for implementing sophisticated and elegant Prolog applications, without getting sidetracked in other tasks.

Since there is barely any other system like that, especially among those that are also freely available, that would make Scryer Prolog rather unique and precious.

[XVilka]

Well, if it stays in the way of core features - sure, it should be closed. But, imho, it can be marked low-priority and postponed to better times.

P.S. I have high hopes for this project too.

[pmoura]

If at some point Scryer Prolog provides a process creation predicate that allows connecting Prolog default input/output streams with the process input/output streams, the main task for providing embedded help becomes having the documentation in a suitable format. For an example of such a solution, see:

https://logtalk.org/manuals/devtools/help.html#experimental-features

[rotu]

I agree that a help predicate would be very useful for builtins and user code alike. I would very much like to see modes and plaintext documentation in the repl rather than on a website, whether or not it's builtin.

Say I'm documenting foo/2:

1. How could that work? Would it be appropriate to have it attached as a predicate property like predicate_property(foo(_,_), description('some plaintext documentation here'))? I don't think there's a userland way to define a new predicate property, but I'm happy to be corrected.
2. It seems there's already some sort of term-tagging system term_attributed_variables; is it suited to this purpose? How do you attach/query such?
3. Would it be sufficient to have a multifile predicate description(foo/2) or description(foo(_,_))?

I presume the reason that predicate_property uses terms (foo(_,_)) instead of PIs (foo/2) is because the latter is defined in terms of the foo atom, regardless of where it's imported from.

[triska]

Since this was last discussed, I think you @jjtolton expressed interest in generating info pages that can be browsed with Emacs?

[rotu]

Well, here's what I have so far as a sort of help function for my own use. I'm somewhat limited by the lack of predicate properties. And I don't know how to pull in comments.

Anyway, I could use help with the above questions to move forward.

:- module(whatis, [whatis/1]).

:- use_module(library(format)).
:- use_module(library(lists)).
:- use_module(library(between)).

whatis(N) :- current_module(N)
          -> bagof(P,current_predicate(N:P),Ps)
             , format("~q is a loaded module containing predicates ~q",[N,Ps])
          ; format("~q does not name a loaded module.", [N]).
whatis(N) :-  current_op(Precedence,Type,N)
  -> format("~q is an operator with precedence ~q and type ~q",[N,Precedence,Type])
  ; format("~q does not name an operator.", [N]).

whatis(N) :- 
  between(0,1023,A),
  PI=N/A,
  functor(Head,N,A),
  catch(
    bagof((Head :- Body), clause(Head,Body), Clauses),
    error(permission_error(access,private_procedure,PI), clause/2),
    Clauses=[]  % true,Clauses='<private definition>'
  ),
  format("~q names predicate ~q~n", [N,PI]),
  findall(Prop, predicate_property(Head,Prop), Props),
  format("    with properties ~q~n",[Props]),
   (Clauses = [] -> format("    with a private definition~n",[]);
  format("    defined as:~n",[]),
  maplist(portray_clause, Clauses)).

[bakaq]

And I don't know how to pull in comments.

You could look at how DocLog does it, which is what generates the documentation at the Scryer Prolog site.

[rotu]

Thanks, @bakaq. I looked at DocLog but I dislike that approach out of the gate. It feels divorced from the code itself:

1. The docs live in a metalanguage in the comments. It seems like a weak choice, given that Prolog can formally encode facts rather nicely.
2. DocLog provides a static html site. It doesn't provide a runtime-reflectable version of the documentation.

[rotu]

Looked at some document generators aside from DocLog:

• pldoc - from SWI, documentation in comments, emits to HTML or LaTeX: https://www.swi-prolog.org/pldoc/doc_for?object=section(%27packages/pldoc.html%27)
• lgtdoc - from Logtalk, documentation using :- info/2 directive, emits as XML translates to md or rst. https://github.com/LogtalkDotOrg/logtalk3/blob/master/tools/lgtdoc/NOTES.md
• lpdoc - from Ciao, documentation using :- doc/2 directive, emits as HTML, plaintext, PDF. https://ciao-lang.org/ciao/build/doc/lpdoc.html/

I think I'm most partial to lpdoc, and it even includes a help/1 and help/2 predicate like I was thinking of making: https://github.com/ciao-lang/lpdoc/blob/master/src/lpdoc_help.pl

There are some syntactic variances that make lpdoc non-ISO but it seems like it'll be a fun exercise to port!