I have written a proposed update to the Beginner Debugger Tutorial since I struggled with several aspects of the command line debugger as I got up to speed and wanted to try to spare others the frustration. My hope would be to replace the existing one in the docs and the site with this one and I’m looking for feedback on it: https://blog.inductorsoftware.com/blog/SWIPrologTrace. I’ll update it to be based on Latex, etc eventually, but started with markdown because it was easier. Next stop will be to put together an update to the graphical debugger documentation, but I wanted to start here since understanding the command line tracing infrastructure is very helpful for understanding the graphical one. Any and all comments and feedback appreciated!

One way to get valuable feedback is to have a new user who needs to use the trace to solve their problem, have them use your blog entry while they learn to use trace and then give you feedback. The key part is that you need a new user who is motivated to use trace and who will objectively read your blog and give constructive feedback. The user should also be a seasoned programmer who is not learning their first programming language; I say this because I don’t see your blog as having the details needed for a first time programmer. A way to do this is to watch here or the StackOverflow Prolog tag for someone. This could take months to find just such a person. Then let them know up front your intent and ask them. I did something similar when I was wanting feedback with the Prolog Visualizer HTH

[image] ericzinda: I’ll update it to be based on Latex, etc eventually, but started with markdown because it was easier. Note that the manual is built from a mixture of LaTeX, markdown and PlDoc from the Prolog source files. Everything is converted to LaTeX and next to HTML. Quite likely a rewrite can be avoided :slight_smile:

I was definitely not focused on a first time programmer. I was assuming that the overwhelming majority of people coming to prolog have been exposed to a classic “imperative” language first. Agree it would be great to get an experienced programmer new to Prolog who wants to learn tracing to give feedback. There has to be people like that coming to this Discourse all the time (I was one!). Can we pin a request to the top of the discourse?

[image] ericzinda: Can we pin a request to the top of the discourse? If you create a topic for the request in with the Category Help I can pin it there. That way people will see it the first time they look at the Help category and it should scroll down the list as newer topics are created.

Here you go: Learning how to use the Prolog Command Line Debugger? Try this new overview! I also put a comment in the comments section of the current debugger topic.

[image] jan: Note that the manual is built from a mixture of LaTeX, markdown and PlDoc from the Prolog source files. Everything is converted to LaTeX and next to HTML. Quite likely a rewrite can be avoided :slight_smile: I’ve got swipl-devel building, including the manual and HTML. I’m starting by seeing how to replace the “Overview of the Debugger” with my markdown update. It looks like the current overview is in latex, embedded in /man/overview.doc. Any pointers on how to replace it with the markdown file I have? Or another approach?

[image] ericzinda: Any pointers on how to replace it with the markdown file I have? Or another approach? Yip. No parts of the main docs are handled in markdown, but some of the library is. See lib/clpfdlib.md and CMakeLists.txt on how it is processed to .tex. I’m not sure all is covered by the CMake macros to do what you want. Possibly it is. Possibly you’re happy with CMake programming. If neither, just ask and I’ll try to make a small demo. Note that this isn’t really markdown, but SWI-Prolog’s incarnation thereof. Over the years this has moved closer to what is getting generally accepted markdown. There are still a lot of older constructs and still some stuff from de-facto markdown is missing. Thanks for all the work!

[image] jan: this isn’t really markdown There is no really markdown. There is a steadily growing number of dialects :-(. Pandoc alone supports currently about 8 different markdown dialects (and you can additionally use switches to extend or limit Pandoc’s own markdown…) It seems that every SaS company is hell-bent on making their own incompatible version of markdown (which often ends up being a one-of-a-kind markup). GitHub, Jira come immediately to mind. There is also whichever “chat” you are using (Mattermost? Slack?) and of course Discourse.

Yes so before I went into the “markdown” rant I just wanted to say that Pandoc might be a good solution for a one-off conversion between a markdown and another markdown or a markup like HTML or LaTeX.

Feedback please on proposed update to Tutorials/Beginner/Debugger

Request For Comments

ericzinda November 10, 2020, 3:11am 8

Could you also pin my graphical debugger post? Just got first draft of that one done.

Topic		Replies	Views
Learning how to use the Prolog Command Line Debugger? Try this new overview! Help!	9	1402	November 15, 2020
Using markdown with pldoc to generate manual content Help!	15	1257	May 12, 2021
Learn Prolog Now: Request for contribution Looking for Group	26	2938	October 21, 2019
Literate Prolog utility Announce	0	405	July 18, 2019
A page for beginners to add to SWI-Prolog internet site Request For Comments	34	2049	June 19, 2021

Feedback please on proposed update to Tutorials/Beginner/Debugger

Related topics