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.
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.
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
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?
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.
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?
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.
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.
If I had to start again I’d surely consider Pandoc, although it is a very big build dependency. As is, all documentation is processed in Prolog and thus we have no build dependencies (except LaTeX if you want to build the PDF in addition to the HTML).
Replacing the pipeline would be a lot of work as PlDoc, the manual segmentation, indexing and search is based on the concrete HTML representation that is generated. Also the LaTeX requires consistent use of a large set of dedicated LaTeX commands to make the pipeline work.
Yes, I completely agree. This is why I’d say that for a one-off conversion Pandoc is fine; I wouldn’t use it in a pipeline, esp. if you already have many parts of it implemented. My comment was at @ericzinda, if he already had something in a markdown dialect that he wanted to translate.
EDIT: since Pandoc speaks so many dialects, its support for more specific features is somewhat lacking. This is from memory and only concerns LaTeX and the markdown --> PDF generation actually.
FWIW, I went through the process of taking a “normal” markdown file and getting it into the build and wrote it up. It went pretty smoothly with minimal changes, for that doc at least. @jan is doing some fixes that should make the next one even smoother.
I was able to put the markdown file in the build with the changes outlined and not have to learn anything more than the /include command of latex.
