Using markdown with pldoc to generate manual content

I’ve gone through the process of writing a replacement for the debugger overview using “regular” markdown as understood by the StackEdit editor and trying to integrate it into the build. Mostly it went pretty smoothly. I wanted to write it up here to save others the time and also to point out a bug and missing feature that I hit.

  • Prolog Keywords: I originally surrounded keywords like trace/0 with backticks(``). Unfortunately, this meant pldoc didn’t recognize them as prolog keywords and link them, so I had to remove all of the backticks. However, I did need to leave them on non-built-in predicates so they would look right. Due to the default formatting of the links in html, this meant that built-in predicates and example predicates look different (notice that trace/0 and noun(X, rock) are formatted differently in the image):

    • suggestion: allow `` around a built-in predicate to get formatted like back ticks but also link
  • I had to add section IDs to each section using {#} so they could be linked to. Like this:
    ## The Byrd Box Model And Ports {#byrd-box-model}

  • Some latex commands (like \cite) are missing from markdown, so I just had to manually write in the URL, which is not good since it means the local docs now link to the website, etc.

    • suggestion: have a way to embed latex commands in markdown. The only one I needed was \cite so maybe there aren’t a lot?
  • Links: To make sure the build system linked everything up properly, I needed to link to sections using the [](#section) syntax. However, instead of creating a link, it actually puts the section name in () like this: [the debugger section](#debugger) generates debugger section (section 4.39) instead of just hot linking the text. Maybe that is by design?

  • Putting capitalized text in backticks generated italics in HTML and non capitalized did not. Seemed odd.

  • Creating a markdown table like this:
    | | | |
    |-----------|-|------------------------|
    | **Abort** |a| Abort Prolog execution.|
    generated a table like this in HTML (note the missing line on the top):
    image

  • For some reason set_breakpoint/4 and spy/2 were not found in the docs and automatically linked to. Maybe a problem with my local build environment?

The only two issues that seem really problematic are the odd table border and the lack of a way to do \cite “symbolically”. Overall, it worked pretty well for this doc. And afterward the only thing that was odd if I round tripped it back to the StackEdit editor was the section IDs showing up in {}.

2 Likes

Thanks for writing this up.

Sounds good, also to improve reusing the markdown.

You don’t really have to but you get a warning. The section IDs are used to generate the HTML file names and the node ideas for representing the entire manual hierarchically. Guess we could generate them automatically. Doing it by hand creates nice concise labels though.

I’m less enthusiastic about this. I do not want to tie the markdown to a particular backend. Note that currently there are two backends: HTML and LaTeX. The HTML is used if PlDoc is used directly on Prolog code. The LaTeX is used for the manual (which is then subsequently translated into HTML). A little search only raised R markdown. Doesn’t look too bad though. Possibly for now only add [@cite1;@cite2;…] to map to \cite{cite1,cite2,…}?

Guess that if there is a text we could omit adding the section number. Probably we would need an abstraction over LaTeX references to allow adding the text for the link?

As is, `....` considers the content Prolog code and tries to format it nicely. HTML is a Prolog variable :slight_smile: Double backtick (how do I get that literally in here?) considers the content code without any assumptions on the language.

The first two lines are not needed. Something in the transformation apparently gets upset from the inserted empty cells of the first line. Turns out PlDoc doesn’t like a |---|--- line to start with. Maybe that should be fixed? That would also allow adding column alignment.

I’ll wait for your pull request.

OK, pull request submitted!

Yeah, I think requiring them to be added manually was fine. The warnings notified me that I should do it.

That seems like a good localized fix. Note that pandoc has a more extensive spec for their version of this extension, and their support probably gives it some legs towards getting adopted more widely. Your short version seems like a simple subset of what they have.

I don’t know enough about latex and the build infrastructure to have an opinion on this. If you look at my pull request, the current approach isn’t really that bad, just different than I expected from “normal” markdown.

Good to know. That approach also does the right thing in my one test using StackEdit as well.

This one and the citation feature are the only two I think are important fixes. Supporting the (as far as I can tell pretty universally supported) markdown table format that allows a header and alignment row is pretty important. In fact, it is required by the three online markdown editors I’ve used and won’t render the table without them: github, dillinger, and stackedit. So, anyone writing markdown coming from those sources, at least, will hit this issue.

Here’s the spec for the GitHub table format, which is at least a subset of what the others use too

Pushed some stuff that should make your life easier:

  • [@cite1;@cite2;…] is supported. This is a limited version of the R Studio Markdown extension and is only provided for the LaTeX backend. No white space is allowed in the citation.
  • `name/arity` is handled the same as name/arity
  • ``name/arity`` translates to \nopredref{name}{arity}, i.e., a predicate indicator that is not a link to the manual. This should be used to refer to predicates in examples.
  • … flag `name` … creates a link to a Prolog flag if name is the name of an existing Prolog flag.
  • Enhanced table handling
    • Deal with a |---|... column specification, including alignment
    • An | | | ... line above the column specification (all empty cells) is removed.
    • A row above the column specification is translated into a header (HTML <th>, LaTeX \textbf(...} content)
    • The LaTeX route uses \tabularx to achieve flexible wrapping for columns holding long content.
1 Like