Add checking mode examples for append

[jgarte]

This pull request adds a checking mode/direction example for append.

[triska]

My personal opinion: Illustrating list predicates is a good opportunity to show how conveniently strings can be written in Scryer Prolog. For example:

?- append("Scr", "yer", "Scryer").
   true.

[jgarte]

My personal opinion: Illustrating list predicates is a good opportunity to show how conveniently strings can be written in Scryer Prolog. For example:

?- append("Scr", "yer", "Scryer").
true.

This sounds good to me. Should I update the proposed PR to use your string example in both modes for append/3?

[triska]

Personally, I would favour such a change, yes. @aarroyoc I would also greatly appreciate your opinion on this. Thank you a lot!

[triska]

Regarding the wording of the documentation for append/3, please also consider the Prologue:

https://www.complang.tuwien.ac.at/ulrich/iso-prolog/prologue#append

Note how generally phrased the sufficient condition is: "... true if Zs is the concatenation of the lists Xs and Ys."

It doesn't say "concatenate the lists" (which would suggest only a single usage mode), but "true if ...".

[jgarte]

@triska I'll wait on @aarroyoc 's opinion here for the PR.

[aarroyoc]

I agree with @triska that append/3 is a good place to showcase Scryer Prolog strings but I would keep at least one example with the [] syntax to not confuse people into thinking it's a predicate exclusively made for strings.

[jgarte]

@aarroyoc @triska Ok, I pushed a new commit with the suggestions. What do you think?

[triska]

Looks excellent to me, thank you a lot! Please consider also the description of the predicate if you are interested! Ideally the description also conveys the generality.

[jgarte]

Looks excellent to me, thank you a lot! Please consider also the description of the predicate if you are interested! Ideally the description also conveys the generality.

@triska Pushed a commit to improve that. Thanks for the suggestion!

a17e529

[jgarte]

Hi,

Are there any further changes you'd like for me to implement in order to merge this PR?

@aarroyoc @triska

[adri326]

This looks good to me as is.

I do agree with Markus' suggestion to add a wordful explanation of the possible usages of append/3; something like:

This predicate can both be used to concatenate lists (or strings) together [examples] or to separate a list (or string) into a prefix/suffix pair [examples].

By specifying a fixed-length suffix, one can also remove the last element(s) from a list:
?- List = [1, 2, 3, 4], append(Shortened, [LastElement], List).
   Shortened = [1, 2, 3], LastElement = 4.

append/3 can be used in a lot more scenarios, but it's a predicate whose generality may not be immediately obvious to new prolog users, which could end up skipping using it because of its name.

[hurufu]

offtopic: Name append is one of the worst names for a core Prolog predicate..., something like prefix_tail_list/3 would've been better.

offtopic 2: also it can be used to create partial (or opened) lists: append("abc", _, PartialList).

[triska]

Regarding wording: I think the description in the Prologue is very close to ideal:

"append(Xs, Ys, Zs) is true if Zs is the concatenation of the lists Xs and Ys."

Personally, I see no need to bring in any imperatives or even any verbs into this. An imperative/procedural way to describe it, no matter how convoluted, is unlikely to cover all cases, and will always suggest particular directions of use.

Please also see the various Examples in the document for inspiration about sensible examples: The queries using answer descriptions have a great advantage over informal descriptions in that they are automatically interpretable and testable, and they illustrate usage modes that are very hard to describe procedurally. Take for instance the last example:

?- append(Xs, Ys, [a,b|Xs]).
   Xs = [], Ys = "ab"
;  Xs = "a", Ys = "ba"
;  Xs = "ab", Ys = "ab"
;  Xs = "aba", Ys = "ba"
;  ... .

The declarative description still fits perfectly:

"append(Xs, Ys, Zs) is true if Zs is the concatenation of the lists Xs and Ys."

In contrast, an understandable procedural description of what we see here seems almost impossible.

[triska]

P.S.: I agree the name is very bad, it's an imperative name that suggests a particular usage mode.

In GUPU, the name for this relation is liste_liste_zusammen/3.

[aarroyoc]

Hi,

Are there any further changes you'd like for me to implement in order to merge this PR?

@aarroyoc @triska

For me it's fine but neither @triska or I have merge permission

[triska]

Personally, I think in an ideal set of examples, each of the examples tells us something interesting, something we do not yet know from the other examples.

In this concrete case, is there true value in having two different examples for "checking", and two different examples for "appending"?

I think the examples given in the Prologue are well worth studying.

[jgarte]

Hi, thanks for the commentary. I'll need about a week or two to find the time slot to work on this again. Till soon.