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.