Didactic usage example

Split Topic
1

I wish there was linked to each manual entry a didactic usage example, such as this example.

It would make the manual soooo much easier to digest and follow.

I just added it into the comments:

https://eu.swi-prolog.org/pldoc/doc_for?object=intercept/3#

2

Sometimes such comments are at the level of the library/section. See https://eu.swi-prolog.org/pldoc/man?section=intercept

I don’t see really how to improve on that as examples often spread multiple predicates. We could always show the entire section and scroll to and possibly highlight the target predicate?

3

I see here covering two needs:

  1. awareness that an example exists
  2. examples that are easy to understand and that guide in how to apply

So, if there could be section level examples, that’s great, but there has to be a link – or some other means of awareness – from the predicate level to the section level.

AND, section level examples must be as simple as possible, to not burden the reader with additional needs to lookup things … so, each individual predicate use needs to be obvious from the section example.

I often find myself reviewing an example, to learn about a predicate, just to find that I have an unrelated knowledge gap, that makes it hard to understand the current example at hand.

Btw, any mechanism that could also help link to related forum discussions would be great …

4

The following is just my view on this topic, feel free to ignore any and all of it
Also my thanks to Jan W. and all who have created SWI-Prolog, please don’t misinterpret anything that follows as anything more than just friendly discussion.

I have to agree with Jan W. that links to predicates should be directly to the predicate, and that examples that cover multiple predicates in a section should be at the section level. When starting with Prolog I too had a similar trying time of finding examples when seeing just the predicate but learned to just look to the left in the documentation and see the index and then just click one more level(s) higher. e.g. (predicate) (section)

image

However another link in the manor of the source code link, e.g. image
for examples might be a possible solution.

But then Dan’s judicial application of the word didactic in the question comes into play. Should there be just didactic examples, more comprehensive examples, real-world examples, etc. I know that when I see examples in the documentation that I need to be extremely careful about cutting and pasting them into production code and assuming all of the needs are covered, but if I find a use of the predicate in the SWI-Prolog source code then I feel more comfortable cutting and pasting it into production code and then modifying as needed.

While we are on the topic of examples, one also has to keep in mind that some of the examples in the documentation and test cases in source code may be several years or more old and that some new predicates might be of more use in the example, e.g. setup_call_cleanup/3

I do agree that it is sometimes hard to find examples but then learned to look beyond the documentation and typically after the documentation go straight to the source code. While the source code link is very helpful, I do find the test cases of more value so have to manually find them.

1 Like
5

In thinking more about this and with an understanding that Dan just made a link in the SWI-Prolog documentation to a post in Discourse, a practical idea might be to create a new category here named something like Seeking predicate example and then state the predicate or predicates for which you seek an example.

Then when an acceptable example is given, a link can be manually made from the SWI-Prolog documentation to the the post here.

Sometimes the example can be as simple as a link to a part of the documentation, a link to some of the production code, test cases or examples in the SWI-Prolog GitHub repository or actually writing a working example from scratch.