Should examples show the modes for each predicate?
I know that understanding the mode and what they mean should cut down on lots of questions, but if a user has trouble understanding a simple predicate, then trying to understand modes for a predicate might just make a bad situation worse.
Perhaps with simple and common predicates like append/3, the most common use should be demonstrated then in a latter section more complex examples demonstrated. I know this use append/3 what not something I would thought of at first.
Never underestimate append/3:
subst(This, That, MyStr, Result) :-
append(This, After, Rest),
append(Before, Rest, MyStr),
!,
subst(This, That, After, AfterResult),
append([Before,That,AfterResult], Result).
subst(_, _, S, S).
To test:
103 ?- portray_text(true).
true.
104 ?- subst(`this`,`that`,`athishellothis`,R).
R = `athathellothat`.