# Q on aggregate_all/*

155 views

### Julio Di Egidio

May 17, 2015, 4:49:35 PM5/17/15
Hi guys,

In swipl 6.6.6, aggregate_all/* are marked semidet in the docs, but I cannot find a scenario where they fail:

`?- findall(_,fail,L).L = [].?- aggregate_all(count,fail,C).C = 0.?- aggregate_all(c,fail,C).ERROR: Type error: `aggregate_template' expected, found `c'`

What am I missing?  :)

Thank you,

Julio

### Kilian Evang

May 17, 2015, 6:20:02 PM5/17/15
Interesting question! I found one scenario: if you try to find the minimum or maximum of an empty set.

?- dynamic c/1.
true.

?- aggregate_all(max(X), c(X), Max).
false.

### Julio Di Egidio

May 17, 2015, 7:17:11 PM5/17/15
Thank you, Kilian, interesting find...

Julio

### Julio Di Egidio

May 17, 2015, 10:19:25 PM5/17/15
Few more examples:

`?- aggregate_all(count,between(1,2,_),C).C = 2.?- aggregate_all(count,between(1,2,_),2).true.?- aggregate_all(count,between(1,2,_),1).false.?- aggregate_all(count,between(1,2,_),a).false.?- aggregate_all(count,false,C).C = 0.?- aggregate_all(count,false,0).true.?- aggregate_all(count,false,1).false.?- aggregate_all(count,false,a).false.`

Case closed as far as I can see.

Cheers,

Julio

### Julio Di Egidio

May 18, 2015, 12:46:59 AM5/18/15

The declaration of aggregate_all/3 in the docs is:

aggregate_all(+T, :G, -R)  [semidet]

Given the examples up-thread, isn't this one is more correct?

aggregate_all(+T, :G, -R)  [det]
aggregate_all(+T, :G, +R)  [semidet]

Is someone, maybe Jan, able to confirm how it works?

Julio

### Jan Wielemaker

May 18, 2015, 2:47:15 AM5/18/15
On 18-05-15 04:19, Julio Di Egidio wrote:
> Few more examples:
>
> |
> ?-aggregate_all(count,between(1,2,_),C).
> C =2.
>
> ?-aggregate_all(count,between(1,2,_),2).
> true.
>
> ?-aggregate_all(count,between(1,2,_),1).
> false.

This is not a reason not to be det. The mode gives
`-` for the last argument. Det would mean it
succeeds, _given that the last argument is
unbound_. The behaviour with a bound argument
is that of

aggregate_all(count,between(1,2,_),C), C = 1.

This is (supposed to be) the case for all arguments
with mode `-`. Well, except for e.g., open/3, where
the last argument _must be unbound_ or else an
uninstantiation error is raised. This is because
you cannot meaningfully compare with a created
stream.

Cheers --- Jan

### Jan Wielemaker

May 18, 2015, 2:56:14 AM5/18/15
On 18-05-15 06:46, Julio Di Egidio wrote:
>
> aggregate_all(+T, :G, -R) [det]
> aggregate_all(+T, :G, +R) [semidet]
>
> Is someone, maybe Jan, able to confirm how it works?

See my previous reply. If you do the above, you have
to repeat that for all predicates with mode `-` in some
arguments. That isn't really helpful. Only predicates
that have no output arguments can guarantee to succeed
_always_, given acceptable input arguments. There are
few examples of these :-) `true` and the output (write)
predicates are among the few examples I can think of.

Cheers --- Jan

### Julio Di Egidio

May 19, 2015, 9:20:41 AM5/19/15
On Monday, May 18, 2015 at 7:47:15 AM UTC+1, Jan Wielemaker wrote:
On 18-05-15 04:19, Julio Di Egidio wrote:
> Few more examples:
>
> ?-aggregate_all(count,between(1,2,_),C).
> C =2.
>
> ?-aggregate_all(count,between(1,2,_),2).
> true.
>
> ?-aggregate_all(count,between(1,2,_),1).
> false.

This is not a reason not to be det.  The mode gives
`-` for the last argument.  Det would mean it
succeeds, _given that the last argument is
unbound_.

Isn't that exactly correct, that it always succeeds with unbound last argument?

The behaviour with a bound argument
is that of

aggregate_all(count,between(1,2,_),C), C = 1.

This is (supposed to be) the case for all arguments
with mode `-`.

I do not understand that: it is C=1 that is failing there, not aggregate_all  (But don't get me wrong: I know there is a long history with these conventions, I just still get confused and do not yet grasp whether it is me or Prolog a bit messy here...)

Well, except for e.g., open/3, where
the last argument _must be unbound_

Indeed, when I see "-", I take it that the argument *must* be unbound, that was the point!

Julio

### Julio Di Egidio

May 19, 2015, 9:38:46 AM5/19/15
On Monday, May 18, 2015 at 7:56:14 AM UTC+1, Jan Wielemaker wrote:
On 18-05-15 06:46, Julio Di Egidio wrote:
>
>    aggregate_all(+T, :G, -R)  [det]
>    aggregate_all(+T, :G, +R)  [semidet]
>
> Is someone, maybe Jan, able to confirm how it works?

See my previous reply.  If you do the above, you have
to repeat that for all predicates with mode `-` in some

I could understand it is inconvenient, but bugs in the documentation are rather a disaster...

Only predicates
that have no output arguments can guarantee to succeed
_always_, given acceptable input arguments.  There are
few examples of these :-)  `true` and the output (write)
predicates are among the few examples I can think of.

(I am not the expert, but) not to clutter the docs yet have it correct, I'd have written:

aggregate_all(+T, :G, ?R)  [semidet]

Julio

### Jan Wielemaker

May 19, 2015, 9:50:53 AM5/19/15
On 05/19/2015 03:38 PM, Julio Di Egidio wrote:
> On Monday, May 18, 2015 at 7:56:14 AM UTC+1, Jan Wielemaker wrote:
>
> On 18-05-15 06:46, Julio Di Egidio wrote:
> >
> > aggregate_all(+T, :G, -R) [det]
> > aggregate_all(+T, :G, +R) [semidet]
> >
> > Is someone, maybe Jan, able to confirm how it works?
>
> See my previous reply. If you do the above, you have
> to repeat that for all predicates with mode `-` in some
> arguments. That isn't really helpful.
>
>
> I could understand it is inconvenient, but bugs in the documentation are
> rather a disaster...

There is no bug in the documentation. Given a predicate x with
an argument with mode `-`, e.g., x(-) the determinism applies to
the case where the output argument is unbound. If x/1 is used
with a bound argument (Value below), the semantics is defined as:

`x(Value)` is same as `x(Result), Result = Value`

The latter is obviously semidet as `Result = Value` can fail.

E.g., although findall/3 is det, it the following is perfectly
legal and generally good style to get the first two solutions
of a goal:

findall(X, x(X), [X1,X2|_]).

Thus is the same as

findall(X, x(X), Xs), Xs = [X1,X2|_].

which may obviously fail if there are less than two answers
for x(X).

Cheers --- Jan

P.s. Giving a value to an output (`-`) argument is actually
good style. It is not only more compact, but also
allows the predicate to optimise. For example,
term_attvars(Term, []) is an efficient way to prove
that Term has *no* attributed variables. The implementation
checks for this pattern and fails as soon as it found the
first attributed variable in Term.

>
> Only predicates
> that have no output arguments can guarantee to succeed
> _always_, given acceptable input arguments. There are
> few examples of these :-) `true` and the output (write)
> predicates are among the few examples I can think of.
>
>
> (I am not the expert, but) not to clutter the docs yet have it correct,
> I'd have written:
>
> aggregate_all(+T, :G, ?R) [semidet]
>
> Julio
>
> --
> You received this message because you are subscribed to the Google
> Groups "SWI-Prolog" group.
> To unsubscribe from this group and stop receiving emails from it, send
> Visit this group at http://groups.google.com/group/swi-prolog.
> For more options, visit https://groups.google.com/d/optout.

### Kilian Evang

May 19, 2015, 10:03:05 AM5/19/15

On Tuesday, May 19, 2015 at 3:20:41 PM UTC+2, Julio Di Egidio wrote:
On Monday, May 18, 2015 at 7:47:15 AM UTC+1, Jan Wielemaker wrote:
On 18-05-15 04:19, Julio Di Egidio wrote:
> Few more examples:
>
> ?-aggregate_all(count,between(1,2,_),C).
> C =2.
>
> ?-aggregate_all(count,between(1,2,_),2).
> true.
>
> ?-aggregate_all(count,between(1,2,_),1).
> false.

This is not a reason not to be det.  The mode gives
`-` for the last argument.  Det would mean it
succeeds, _given that the last argument is
unbound_.

Isn't that exactly correct, that it always succeeds with unbound last argument?

No. Remember my example with max?

### Kilian Evang

May 19, 2015, 10:09:04 AM5/19/15

On Tuesday, May 19, 2015 at 3:50:53 PM UTC+2, Jan Wielemaker wrote:
Given a predicate x with
an argument with mode `-`, e.g., x(-) the determinism applies to
the case where the output argument is unbound.  If x/1 is used
with a bound argument (Value below), the semantics is defined as:

`x(Value)` is same as `x(Result), Result = Value`

So you're saying a mode declaration containing a `-` makes the guarantee that it behaves like that if called with that argument bound? Is this documented anywhere?

### Julio Di Egidio

May 19, 2015, 10:11:20 AM5/19/15
Yes, and my guess is that it is a bug... somewhere, the docs being the first candidate.  (But I'm busy now: I'll have to follow up later.)

Julio

### Kilian Evang

May 19, 2015, 10:19:19 AM5/19/15

It's not. Mathematically, the minimum or maximum of an empty set is not defined, so it makes perfect sense for this goal to fail. And the docs correctly state it's semidet.

### Jan Wielemaker

May 19, 2015, 10:23:36 AM5/19/15
On 05/19/2015 04:19 PM, Kilian Evang wrote:
>
> Yes, and my guess is that it is a bug... somewhere, the docs being
> the first candidate. (But I'm busy now: I'll have to follow up later.)
>
>
> It's not. Mathematically, the minimum or maximum of an empty set is not
> defined, so it makes perfect sense for this goal to fail. And the docs
> correctly state it's semidet.

also unclear whether failure is a good idea here or whether an exception
might be better. I don't have SICStus anymore, so I cannot compare with
their version. Anyone?

Cheers --- Jan

### Kilian Evang

May 19, 2015, 10:30:20 AM5/19/15

It also fails:

SICStus 4.2.3 (x86_64-linux-glibc2.7): Fri Oct  5 15:52:44 CEST 2012
Licensed to SP4 Kilian Evang on Linux
| ?- use_module(library(aggregate)).
% module aggregate imported into user
%  module types imported into aggregate
%  loaded /home/p264360/opt/sicstus4/bin/sp-4.2.3/sicstus-4.2.3/library/types.po in module types, 0 msec 1424 bytes
% loaded /home/p264360/opt/sicstus4/bin/sp-4.2.3/sicstus-4.2.3/library/aggregate.po in module aggregate, 0 msec 41840 bytes
yes
| ?- assertz(a(1)).
yes
| ?- aggregate_all(max(X), a(X), Max).
Max = 1 ? ;
no
| ?- retract(a(_)).
yes
| ?- aggregate_all(max(X), a(X), Max).
no
| ?-

### Jan Wielemaker

May 19, 2015, 10:46:31 AM5/19/15
On 05/19/2015 04:30 PM, Kilian Evang wrote:
> | ?- assertz(a(1)).
> yes
> | ?- aggregate_all(max(X), a(X), Max).
> Max = 1 ? ;
> no
> | ?- retract(a(_)).
> yes
> | ?- aggregate_all(max(X), a(X), Max).
> no
> | ?-

Thanks. Added a sentence to the docs explaining this.

Cheers --- Jan

### Julio Di Egidio

May 20, 2015, 12:09:35 PM5/20/15
I beg to disagree: the docs are indeed the culprit, but the problem is not that it is marked semidet, the problem is that -R should be ?R.

Julio

### Julio Di Egidio

May 20, 2015, 12:23:40 PM5/20/15
On Monday, May 18, 2015 at 7:47:15 AM UTC+1, Jan Wielemaker wrote:
Just to clarify, this had started as a purely technical question: I am writing some code and I need my predicate, which uses aggregate_all/3, to be det.  So, if I had to trust the docs for what they just state, I should code defensively...  Then you have clarified that with unbound last argument aggregate_all/3 does indeed always succeed, which is what I needed to know: just, of course, it is not ideal that I have to rely on your personal knowledge (or digging into the source code myself), always with the possibility that things break just tomorrow, and so on.  But my question was answered.

That said, I do have an objection to the swipl documentation: namely, I vaguely recollect now that there are essentially two philosophies in Prolog as to how to specify predicate modes, and SWI adopts the convention that I find less effective if not (frankly, but aware I am not an expert) just broken...  And the *ambiguities* you yourself have pointed out in this thread are enough to prove my point...  If you are interested, I could elaborate further, e.g. on that -R vs. ?R, and how your example of the aggregate_all(T,G,C), C=1 rather proves my point, not yours.  But only if you are interested: as said my question has been answered, not to mention that I do love swipl and, as a seasoned software professional, I can very well imagine how much work there is behind it...

Julio

### Boris Vassilev

May 20, 2015, 12:38:06 PM5/20/15
One needs a lot of implicit knowledge to read the SWI-Prolog documentation, or any Prolog implementation documentation, or any documentation, or any text, for that matter (and so on).

The issue of -R vs ?R confused me too once (I tried to dig up the conversation with Jan but I don't remember the context, so I couldn't find it).

Would it be worth the effort to shortly discuss the issue in the documentation of PlDoc?

http://www.swi-prolog.org/pldoc/man?section=modes

If I remember correctly, the original source of my confusion was:

Instantiation patterns are:
...
- : argument must be unbound
...

I still think it is better to leave things as they are, but explaining this "gotcha" might be helpful.

Cheers,
Boris

Currently in the EET time zone: This is UTC +2:00 (and I sleep at night)
Save our in-boxes! http://emailcharter.org

--
You received this message because you are subscribed to the Google Groups "SWI-Prolog" group.
To unsubscribe from this group and stop receiving emails from it, send an email to swi-prolog+...@googlegroups.com.

### Julio Di Egidio

May 20, 2015, 12:49:47 PM5/20/15

On Wednesday, May 20, 2015 at 5:38:06 PM UTC+1, boris.vassilev wrote:

One needs a lot of implicit knowledge to read the SWI-Prolog documentation, or any Prolog implementation documentation, or any documentation, or any text, for that matter (and so on).

Not true: documentation can be complete and unambiguous, in fact *correct*.  ("Complete" is a delicate one, but can be done too, one has to know how to "close holes".)

The issue of -R vs ?R confused me too once (I tried to dig up the conversation with Jan but I don't remember the context, so I couldn't find it).

Would it be worth the effort to shortly discuss the issue in the documentation of PlDoc?

http://www.swi-prolog.org/pldoc/man?section=modes

It is indeed not what it does (at least in many places): but I'll let others comment further.

Julio

### Jan Wielemaker

May 20, 2015, 1:21:38 PM5/20/15
to Boris Vassilev, Julio Di Egidio, swi-p...@googlegroups.com
On 05/20/2015 06:37 PM, Boris Vassilev wrote:
> One needs a lot of implicit knowledge to read the SWI-Prolog
> documentation, or any Prolog implementation documentation, or any
> documentation, or any text, for that matter (and so on).
>
> The issue of -R vs ?R confused me too once (I tried to dig up the
> conversation with Jan but I don't remember the context, so I couldn't
> find it).
>
> Would it be worth the effort to shortly discuss the issue in the
> documentation of PlDoc?
>
> http://www.swi-prolog.org/pldoc/man?section=modes
>
> If I remember correctly, the original source of my confusion was:
>
> Instantiation patterns are:
> ...
> - : argument must be unbound
> ...
>
> I still think it is better to leave things as they are, but explaining
> this "gotcha" might be helpful.

I agree. The above should be fixed. The mode `-` as "argument must be
unbound"
is pretty meaningless as there are probably not more than a handful of
predicates
for which this applies. Typically, these are predicates that generate some
unpredictable result, e.g., returning a unique handle to something created.

In more formal mode system proposals we see `--` for that (and `++` for
ground).

The `?` mode somehow affects the computation further than just unifying the
result when instantiated.

Possibly we should add `--` to the documentation and document their
difference?

Cheers --- Jan

### Anne Ogborn

May 21, 2015, 6:08:14 AM5/21/15
This seems like a great moment to mention that if you find the documentation lacking, one of the best responses is
to add a comment to the page explaining your confusion, and add the doc-needs-help tag to the page.

An even better response is to research the point of confusion, edit the source comment to clarify it, and send Jan a patch. 8cD

::Annie is here, slapping a duck tape patch on a duck::

::All the non-Americans are here, scratching their heads and wondering if there's really such a thing as duck tape. Those who are aware there is such a thing are wondering what the deal is with Americans and their love of duck tape::

### Jan Wielemaker

May 21, 2015, 6:23:43 AM5/21/15
to Anne Ogborn, Julio Di Egidio, swi-p...@googlegroups.com
On 05/21/2015 12:06 PM, Anne Ogborn wrote:
> This seems like a great moment to mention that if you find the
> documentation lacking, one of the best responses is to add a comment
> to the page explaining your confusion, and add the doc-needs-help tag
> to the page.

That helps. Somehow we need a way to fix the docs though and keep
some acknowledgement. I still don't know how to do that.

- Should we simply delete the comment after the docs have
been enhanced? That is clean, but might make the contributor
unhappy.
- Mark them as `closed' and provide some way to show closed

We also need a way to comment on comments (I think). Some of the
comments are dubious ... Suggestions welcome. Willing to hack a
little even more :-)

Just a "doc-needs-help" gives some indication, but quite often I'm
pretty puzzled about what is unclear. Of course, some people cannot
read the docs because they are not aware of Prolog's terminology and
the documentation conventions. Possibly we need an obvious link to
a bluffers guide on how to read the manual? We could also link
Prolog terminology to the (already existing) glossary?

> An even better response is to research the point of confusion, edit
> the source comment to clarify it, and send Jan a patch. 8cD

I love those! Even more as git formatted patches or github pull
requests.

> ::Annie is here, slapping a duck tape patch on a duck::

:-) I though it was called "duct" tape, no?

Cheers --- Jan

### Paulo Moura

May 21, 2015, 6:30:13 AM5/21/15
to Jan Wielemaker, Boris Vassilev, Julio Di Egidio, swi-p...@googlegroups.com

> On 20/05/2015, at 18:21, Jan Wielemaker <J.Wiel...@vu.nl> wrote:
>
> On 05/20/2015 06:37 PM, Boris Vassilev wrote:
>> One needs a lot of implicit knowledge to read the SWI-Prolog
>> documentation, or any Prolog implementation documentation, or any
>> documentation, or any text, for that matter (and so on).
>>
>> The issue of -R vs ?R confused me too once (I tried to dig up the
>> conversation with Jan but I don't remember the context, so I couldn't
>> find it).
>>
>> Would it be worth the effort to shortly discuss the issue in the
>> documentation of PlDoc?
>>
>> http://www.swi-prolog.org/pldoc/man?section=modes
>>
>> If I remember correctly, the original source of my confusion was:
>>
>> Instantiation patterns are:
>> ...
>> - : argument must be unbound
>> …

*must* is the misleading bit. When used in predicate templates, we want to tell the programmer what is to be *expected* *when* the argument is unbound. Predicates can have multiple templates and behave differently (e.g. regarding the number of solutions) when an argument is bound or unbound.

Consider as an example the specification of the standard atom_concat/3 predicate:

atom_concat(?atom, ?atom, +atom)
atom_concat(+atom, +atom, -atom)

In the second template, we’re *not* specifying that the third argument must be unbound when the first two argument are bound (that would conflict with the first template!). If we couple these template and modes specs with determinism information, we’re providing useful information to the programmer. In this case, that calls using the second template will succeed deterministically.

>> I still think it is better to leave things as they are, but explaining
>> this "gotcha" might be helpful.
>
> I agree. The above should be fixed. The mode `-` as "argument must be
> unbound"
> is pretty meaningless as there are probably not more than a handful of
> predicates
> for which this applies. Typically, these are predicates that generate some
> unpredictable result, e.g., returning a unique handle to something created.
>
> In more formal mode system proposals we see `--` for that (and `++` for
> ground).
>
> The `?` mode somehow affects the computation further than just unifying the
> result when instantiated.
>
> Possibly we should add `--` to the documentation and document their
> difference?

That would indeed allow us to distinguish between the case above and other cases such as open/3 where indeed the stream argument must be unbound. As, as you mention, the cases where an argument must be unbound are rare, it makes sense to introduce a new mode indicator for these cases and keep using “-“ for the most common case where it means *if* this argument is unbound, *then* expect this predicate behavior.

Cheers,

Paulo

-----------------------------------------------------------------
Paulo Moura
Logtalk developer

Email: <mailto:pmo...@logtalk.org>
Web: <http://logtalk.org/>
-----------------------------------------------------------------

### Paulo Moura

May 21, 2015, 6:46:52 AM5/21/15
to Jan Wielemaker, Anne Ogborn, Julio Di Egidio, swi-p...@googlegroups.com
Hi Jan,

> On 21/05/2015, at 11:23, Jan Wielemaker <J.Wiel...@vu.nl> wrote:
>
> On 05/21/2015 12:06 PM, Anne Ogborn wrote:
>> This seems like a great moment to mention that if you find the
>> documentation lacking, one of the best responses is to add a comment
>> to the page explaining your confusion, and add the doc-needs-help tag
>> to the page.
>
> That helps. Somehow we need a way to fix the docs though and keep
> some acknowledgement. I still don't know how to do that.
>
> - Should we simply delete the comment after the docs have
> been enhanced? That is clean, but might make the contributor
> unhappy.
> - Mark them as `closed' and provide some way to show closed
>
> We also need a way to comment on comments (I think). Some of the
> comments are dubious ... Suggestions welcome. Willing to hack a
> little even more :-)
>
> Just a "doc-needs-help" gives some indication, but quite often I'm
> pretty puzzled about what is unclear. Of course, some people cannot
> read the docs because they are not aware of Prolog's terminology and
> the documentation conventions. Possibly we need an obvious link to
> a bluffers guide on how to read the manual? We could also link
> Prolog terminology to the (already existing) glossary?

I often link e.g. Logtalk built-in predicates documentation to a glossary as I found very earlier that greatly helps avoiding misunderstandings. This is just not an issue with novice programmers. Plenty of terminology is overloaded across programming languages with different meanings depending on the context. But a glossary is helpful even in the context of a single language, specially for concepts that are not commonly found elsewhere (e.g. “unification”, “choice-point”).

A Prolog glossary would be an ideal resource to be shared among systems. Maybe using a wiki that anyone could link to?

Cheers,

Paulo

>> An even better response is to research the point of confusion, edit
>> the source comment to clarify it, and send Jan a patch. 8cD
>
> I love those! Even more as git formatted patches or github pull
> requests.
>
>> ::Annie is here, slapping a duck tape patch on a duck::
>
> :-) I though it was called "duct" tape, no?
>
> Cheers --- Jan
>
>> ::All the non-Americans are here, scratching their heads and
>> wondering if there's really such a thing as duck tape. Those who are
>> aware there is such a thing are wondering what the deal is with
>> Americans and their love of duck tape::
>
>
> --
> You received this message because you are subscribed to the Google Groups "SWI-Prolog" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to swi-prolog+...@googlegroups.com.
> Visit this group at http://groups.google.com/group/swi-prolog.
> For more options, visit https://groups.google.com/d/optout.

### Jan Wielemaker

May 21, 2015, 8:09:22 AM5/21/15
to Paulo Moura, Anne Ogborn, Julio Di Egidio, swi-p...@googlegroups.com
Would be nice. For a start, we have
http://www.swi-prolog.org/pldoc/man?section=glossary. Probably the way
to go is to make an server
that serves a single glossary term and a little bit of JavaScript
code to link the glossary terms ...

Cheers --- Jan

### Boris Vassilev

May 21, 2015, 8:25:30 AM5/21/15

currently, they seem to belong to "sections", and individual predicates count as sections. What this leads to is that if one is reading the predicate documentation in context, there is no indication that there are any comments. And since there is no direct link, to get to the comments, the easy way seems to be to use the search bar to jump to the documentation of that predicate only to see if there are any comments.

Question: is there a meaningful way to put comments to (sub)sections "inline"?

Somewhat orthogonal: is it reasonable to make section headers (when displayed in their context) a link to the page that only displays that single section?

Currently in the EET time zone: This is UTC +2:00 (and I sleep at night)
Save our in-boxes! http://emailcharter.org

### Jan Wielemaker

May 21, 2015, 9:10:18 AM5/21/15
On 05/21/2015 02:24 PM, Boris Vassilev wrote:
>
> currently, they seem to belong to "sections", and individual predicates
> count as sections. What this leads to is that if one is reading the
> predicate documentation in context, there is no indication that there
> are any comments. And since there is no direct link, to get to the
> comments, the easy way seems to be to use the search bar to jump to the
> documentation of that predicate only to see if there are any comments.
>
> Question: is there a meaningful way to put comments to (sub)sections
> "inline"?

It is not impossible. Requires significant restructing of the page
DOM though.

> Somewhat orthogonal: is it reasonable to make section headers (when
> displayed in their context) a link to the page that only displays that
> single section?

That is surely easier. Might be combined with another long standing
wish: be able to jump to the sources for any Prolog-defined predicate
(ideally also the C-defined ones, but that is a bit harder :-) That now
only works for PlDoc pages, not for predicates documented in the manual.

Cheers --- Jan

### Jan Wielemaker

May 21, 2015, 9:15:06 AM5/21/15
to Paulo Moura, Boris Vassilev, Julio Di Egidio, swi-p...@googlegroups.com
On 05/21/2015 12:30 PM, Paulo Moura wrote:
>>> In more formal mode system proposals we see `--` for that (and
>>> `++` for ground).
>>>
>>> The `?` mode somehow affects the computation further than just
>>> unifying the result when instantiated.
>>>
>>> Possibly we should add `--` to the documentation and document
>>> their difference?
>
> That would indeed allow us to distinguish between the case above and
> other cases such as open/3 where indeed the stream argument must be
> unbound. As, as you mention, the cases where an argument must be
> unbound are rare, it makes sense to introduce a new mode indicator
> for these cases and keep using “-“ for the most common case where it
> means*if* this argument is unbound,*then* expect this predicate
> behavior.

Added -- and ++ to PlDoc as well as the LaTeX based toolchain for
generating the manuals. See [1], starting at line 19 for the
updated description (this text is now repeated in the PlDoc
manual).

Thanks --- Jan

[1] https://github.com/SWI-Prolog/swipl-devel/blob/master/man/builtin.doc

### Anne Ogborn

May 21, 2015, 6:38:25 PM5/21/15
to Jan Wielemaker, Paulo Moura, Julio Di Egidio, swi-p...@googlegroups.com
It would be very neat if you could edit the actual header comments on the website.

I'm sure many folks have been puzzled by something, figured it out, but didn't feel like checking out from github, doing actual fix, building, testing... it's a long awkward cycle if it's not something you're set up to do.

Lowering that bar to 'fix the comment on the website' in SWISH or some such and then clicking 'submit as patch' would lower it.

Of course, this means somebody volunteers to write that...

::Annie looks around at suddenly empty room::

### Anne Ogborn

May 21, 2015, 6:42:06 PM5/21/15
to Jan Wielemaker, Julio Di Egidio, swi-p...@googlegroups.com

> ::Annie is here, slapping a duck tape patch on a duck::

:-) I though it was called "duct" tape, no?

Cheers --- Jan

Well, it started life that way, but after people started calling it duck tape (rural people in US swallow final consonants) somebody started marketing the tape under the Duck brand, and now it's all duck tape.

### Kilian Evang

May 22, 2015, 6:48:03 AM5/22/15
I took a shot clarifying things further, pull request here: https://github.com/SWI-Prolog/packages-pldoc/pull/8

### Paulo Moura

May 22, 2015, 10:26:55 AM5/22/15
to Jan Wielemaker, Boris Vassilev, Julio Di Egidio, swi-p...@googlegroups.com
Although I agree that "++" and "--" are the best name choices, they do force the introduction of prefix operators *if* we want the mode directives to (also) be valid Prolog code :( Dreaming of the day where we can get rid of the limitations of ASCII.

Looking into these changes, the ISO spec (8.1.2.2), what I have in Logtalk itself, I'm still not happy with the mode indicator descriptions. Assume, for example, that a programmer wants to document a predicate, foo/1, that takes as *input* a variable. Which mode indicator should be used? "+" is usually interpreted as synonym of input argument but is described everywhere as meaning that the argument must be instantiated. "-" is usually interpreted as synonym of output argument (e.g. the ISO spec describes "-" as "the argument shall be a variable that will be instantiated iff the goal succeeds"). The new "--" could be used but *iff* the foo/1 predicate would not instantiate it. But "--" have an implicit meaning that will be used to return something. The best choice seems to be "@" but this says nothing about the predicate argument (non-)instantiation requirements.

### Paulo Moura

May 22, 2015, 10:27:21 AM5/22/15
to Kilian Evang, swi-p...@googlegroups.com, boris.v...@gmail.com, ju...@diegidio.name

> On 22/05/2015, at 11:48, Kilian Evang <kilian...@gmail.com> wrote:
>
> I took a shot clarifying things further, pull request here: https://github.com/SWI-Prolog/packages-pldoc/pull/8

Progress!

Cheers,

Paulo

> On Thursday, May 21, 2015 at 3:15:06 PM UTC+2, Jan Wielemaker wrote:
> On 05/21/2015 12:30 PM, Paulo Moura wrote:
> >>> In more formal mode system proposals we see `--` for that (and
> >>> `++` for ground).
> >>>
> >>> The `?` mode somehow affects the computation further than just
> >>> unifying the result when instantiated.
> >>>
> >>> Possibly we should add `--` to the documentation and document
> >>> their difference?
> >
> > That would indeed allow us to distinguish between the case above and
> > other cases such as open/3 where indeed the stream argument must be
> > unbound. As, as you mention, the cases where an argument must be
> > unbound are rare, it makes sense to introduce a new mode indicator
> > for these cases and keep using “-“ for the most common case where it
> > means*if* this argument is unbound,*then* expect this predicate
> > behavior.
>
> Added -- and ++ to PlDoc as well as the LaTeX based toolchain for
> generating the manuals. See [1], starting at line 19 for the
> updated description (this text is now repeated in the PlDoc
> manual).
>
> Thanks --- Jan
>
> [1] https://github.com/SWI-Prolog/swipl-devel/blob/master/man/builtin.doc

### Jan Burse

May 23, 2015, 6:14:14 AM5/23/15
Dear All,

Me lazy bugger, was using ++ and -- for a different purpose.
Assume a predicate has two different modes, i.e.:

:- mode append(+,+,-).
:- mode append(-,-,+).

I was lazily writing this as:

:- mode append(+-,+-,-+).

So basically argmodespec[i] was used for variant i of the
mode specification. Of course also ++ and -- can also happen.

Nevermind.

Bye

P.S.: I am using a different bootstrapping of aggregate_all/4, different
from SWI-Prolog which has a more complicated implementation, namely:

```aggregate_all(A, T, G, R) :-
findall(T, G, H),
sort(H, L),
aggregate_all(A, member(T, L), R).```

Drawback, H is materialized. On the other hand, for modding the aggregate
predicates, it could be an other route in understanding the predicate and
or providing a different implemehtation.

Warning: There is a small chance that the above bootstrapping variant is
not correct. Did not yet develop some test case. Also did't find some tests
for these predicates in Pualo Mouras test suite.