Document some predicates in reif

[rotu]

Reif currently lacks per-predicate documentation, only linking to external paper "Indexing dif/2".

Added some contextual docs to explain the if_/3, =/3, dif/3 predicates.

[UWN]

Operationalizing language.

[rotu]

Operationalizing language.

Please suggest edits as necessary. I don't have the conceptual precision to do better than this.

[rotu]

Not sure what you mean by "Operationalizing language" or which language you're talking about. Please explain further if not addressed by latest commit.

[hurufu]

It should have much more substance and be more correct and precise – like when you write a specification – choice of words matters.

For example:

% Reified equality predicate.

Duh, one way it could'be been even worse is % Reified equality predicate, T is a reified value that tells if X and Y are equal :D

Do you see my point? With that sentence you haven't explain anything you just added to the total word count.

P.S. I actually don't know how to write really good documentation, also maybe if_/3 shall not be documented at all – it is more like an "empty shell" predicate. The main meat is inside predicates that implement conditions. So maybe it is better to document separately:

%% if_(A = B, Then_0, Else_0).
% ...

%% if_(dif(A,B), Then_0, Else_0).
% ...

[rotu]

Do you see my point? With that sentence you haven't explain anything you just added to the total word count.

I must have done a poor job. I thought “reified” here suggests that if/3 is specifically designed so its first argument expects a Foo and that = and dif are designed to provide that sort of Foo.

The weird conceptual leap reif needs is that e.g. = is designed for you to only pass two arguments with the third one implicitly tacked on by if_.

It’s not clear how better to word that but I can give it another crack tomorrow.

[hurufu]

I'm not really a maintainer here, I have only 1 or 2 commits merged to master, please look for someone's else approval :)

[UWN]

Reject - as before.

[bakaq]

See also previous attempt at this: #2407.

[rotu]

See also previous attempt at this: #2407.

@bakaq Thanks for the context!

Reject - as before.

I think most people understand the more ubiquitous ->/; construct so it makes sense to explain by comparing and contrasting.

Unfortunately, the term "reify" seems very operational to start with. What language could I use to not "operationalize" this? Would you like to suggest a description of if_/3 in coherent, natural language?

[dougransom]

I think the documentation, whether it is Operationalizy or not, is fine the way it is and a large improvement over no documentation. I would request the PR be merged in as it is, until someone wants to improve it even more.

Another improvement would be to have an example or two for each predicate.

[triska]

The author of the library already requested to point to the paper first and foremost, and to leave the documentation alone. He also said that everyone interested in explaining these features should start with a separate tutorial.

Please respect these requests.

[rotu]

The goal here is as a welcome mat to explain to interested user what the library is for and why to use it. As it is, the would-be user sees this skeleton of a page: https://www.scryer.pl/reif

Module reif - Scryer Prolog documentation.pdf

Using a file name like "reif" and terse predicates like (=)/3 and (;)/3 beg documentation. If the library authors are able to do a better job of contextual guidance, they should do so.

Deliberately omitting documentation is user-hostile. Plus this library diverges from the predicates mentioned in the paper, so it's clear that the linked paper is at least outdated wrt this code.

[dougransom]

The author of the library already requested to point to the paper first and foremost, and to leave the documentation alone. He also said that everyone interested in explaining these features should start with a separate tutorial.

Please respect these requests.

Can you please link to where the author has requested that, if they have done so in public?
Is the author a contributor to Scryer. Not everyone puts their real name in their github information so it can be hard to tell.

[rotu]

@dougransom I think the original author is Ulrich Neumerkel (UWN). He hasn't committed code to this repo, but he did contribute the same, undocumented library to SWI.

https://www.swi-prolog.org/pack/file_details/reif/prolog/reif.pl

[triska]

Please see the previous attempts, which are now already repeatedly linked to in this discussion: #2407

[rotu]

I saw the previous attempts and made a good-faith attempt to document.

Please see the previous attempts, which are now already repeatedly linked to in this discussion: #2407

You can point to that, but I'm not sure what I'm supposed to take away from that discussion besides that (1) this module is confusing, not just to me (2) the documentation should not use "operationalizing language", whatever that means.

I described how the pieces fit together (e.g. that = takes 3 arguments, but is designed to be used with partial application in if_). That is worlds better than seeing =/3 and wondering "how do I use this predicate"?

Per Coding Guidelines for Prolog:

After the predicate specification comes a clear explanation, in natural language,
of what the predicate does, including special cases ... if you cannot describe a predicate
coherently in natural language, then you are not ready to write it.

@triska, I think you have the best conceptual handle on this API and simultaneously being willing to constructively contribute. PLEASE jump in if you have better wordings for anything.

[dougransom]

I saw the previous attempts and made a good-faith attempt to document.

Please see the previous attempts, which are now already repeatedly linked to in this discussion: #2407

You can point to that, but I'm not sure what I'm supposed to take away from that discussion besides that (1) this module is confusing, not just to me (2) the documentation should not use "operationalizing language", whatever that means.

I described how the pieces fit together (e.g. that = takes 3 arguments, but is designed to be used with partial application in if_). That is worlds better than seeing =/3 and wondering "how do I use this predicate"?

Per Coding Guidelines for Prolog:

After the predicate specification comes a clear explanation, in natural language,
of what the predicate does, including special cases ... if you cannot describe a predicate
coherently in natural language, then you are not ready to write it.

@triska, I think you have the best conceptual handle on this API and simultaneously being willing to constructively contribute. PLEASE jump in if you have better wordings for anything.

@rotu I think the way to make Prolog, and Scryer prolog, more approachable, is to create a cookbook of examples and stick it in the scryer learn folder. The reif predicates are highly useful, and the author knows how they would like to see the predicates documented in the module documentation. A few samples of each predicate would go a long way for use to understand how we can use these predicates to our advantage.
For example,

%memberd_t examples
%test for membership of a  particular value
?- memberd_t('a',"abcabc",true).
   true.
%test for exclusion pf a particular value
?- memberd_t('a',"abcabc",false).
   false.
%more general use, relating a particular value A to a list, B being true if A is in the list, and false if A is not in the list.
?- memberd_t(A,[Y,X],B).
   A = Y, B = true
;  A = X, B = true, dif:dif(Y,A)
;  B = false, dif:dif(Y,A), dif:dif(X,A).

%A is a member of L1, or a member of L2, but not both:
?- memberd_t(A,L1,B), memberd_t(A,L2,C), dif(C,B).
   L1 = [], B = false, L2 = [A|_A], C = true
;  L1 = [], B = false, L2 = [_A,A|_B], C = true, dif:dif(_A,A)
;  L1 = [], B = false, L2 = [_A,_B,A|_C], C = true, dif:dif(_A,A), dif:dif(_B,A)
;  ... .
?- 

two or three examples like that in the cookbook for each predicate in reif would give a pretty clear idea on how to use these predicates.

Would a PR for such a cookbook or tutorial likely be accepted?

[rotu]

@dougransom I think that sort of documentation is great. I don't know if such a PR would be accepted, especially how much of an uphill battle I've gotten with this and other attempted documentation contributions.

[dougransom]

@dougransom I think that sort of documentation is great. I don't know if such a PR would be accepted, especially how much of an uphill battle I've gotten with this and other attempted documentation contributions.

Well, I submitted a few examples, #3100. Let's see.