Using markdown with pldoc to generate manual content

[jan]

Thanks for writing this up.

@ericzinda

suggestion: allow `` around a built-in predicate to get formatted like back ticks but also link

Sounds good, also to improve reusing the markdown.

@ericzinda

I had to add section IDs to each section

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.

@ericzinda

suggestion: have a way to embed latex commands in markdown. The only one I needed was \cite so maybe there aren’t a lot?

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,…}?

@ericzinda

generates debugger section (section 4.39) instead of just hot linking the text. Maybe that is by design?

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?

@ericzinda

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

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

@ericzinda

Creating a markdown table like this:

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.