Doc improvements #2711
Doc improvements #2711
Conversation
|
The don't merge label is because I want to see whether there is a way to appease both Github's and pandoc's markdown parsers |
Before this patchset, the rendering on github was mostly broken. After it, it's still mostly broken, but in different places ;) I would just accept this as reality and merge to improve the pandoc rendering. |
The way we formatted definitions
term
: paragraph1
: paragraph2
gets clobbered into single text blocks by pandoc. The thing it can actually
parse is
term
: paragraph1
paragraph2
This (mostly) whitespace-only change unclobbers the text.
pandoc has a weird algorithm to define the width of tables in markdown. The width cannot be specified absolutely, but is made relative to the text width by how many dashes are in the horizontal line under the header in each column. This can lead to spurious word breaks even on wide displays where the whole table would fit. Removing the prefix should somewhat ameliorate the problem until a better solution is found.
We already have two different X in there, X and x, which are hard to tell apart, and since we want to say something positive, let's make it a checkmark.
The table directly follows the definitions, which makes it difficult to tell apart from the previous definition.
I haven't noticed significantly broken rendering before but now some tables are broken and everything which contains more than one paragraph. Most notable are |
|
One possible solution would be to use a less lossy format like reStructuredText (which GH can render) or AsciiDoc (which GH can render too, and it has native support for man page rendering). Alternatively, it would be possible to write a pandoc filter which transforms definition lists before outputting the man page as these seem to be the thing causing the most trouble |
|
So the problem here is that Markdown is an underspecified mess and different implements add different extensions and implement them slightly differently. The options in the docs are formatted as definition lists, i.e. term
: definitionThis is an extension from the PHP world. GitHub doesn't implement it, which is why this looks like this on Github term The colon shouldn't be there, there should be indentation. The implementation of this also varies a lot. pandoc, which at the moment generates our man page, insists on the indentation of four spaces for this to be rendered correctly when using multi-paragraph definitions, as we do for e.g. Whereas GitHub doesn't support definition lists, it becomes outright bad in the case of multi-paragraph lists. Before this PR every paragraph in the definition was introduced with a colon, which lead to the aforementioned rendering problems with pandoc, now GitHub parses the indentation as code block. There's no appeasing both. The solution is to generate a nice HTML from our docs and put it up at mkosi.systemd.io and not think of GitHub as the primary point to look up the docs. I haven't gotten around to making a nicer HTML yet, because there pandoc has a rendering issue: Multi-paragraph definition get paragraph tags for every paragraph, single-paragraph definitions don't get any—this makes the HTML output smushed. Another point against pandoc is the slightly inane algorithm for line breaks in tables, which adds a few unwanted ones to our man page. Is there something that generates nice HTML without? Why yes, there is Myst, which is sort of the love child of Markdown and reStructuredText. It just takes the current Markdown and produces beautiful HTML output… but it doesn't output man pages and its XML output cannot be used to just use Docbook. Currently there's no nice options were everything is easy. At this point I'm considering just generating the roff output from Myst's parse tree. The alternative is either fixing pandoc or using a filter with pandoc. None of those options is appealing, but I know which one is least. :) Long story short:
And having written this: Adding the HTML output to |
Yeah, Markdown only specifies the most basic formatting things leading implementations to include more and more custom extensions and flavors. (Regarding the underspecification, nowadays commonmark seems to have prevailed. So at least the basic subset is rendered similar by modern markdown parsers.)
I wouldn't use "should" here. Github has no obligation to implement some rarely used extension.
Yes, sadly.
While standalone online docs are great, people will inevitably use the sources in this repo for example when checking out something from master or from an older version. (It is also beneficial for PRs to have the option of the rich diff.)
While it looks like a neat idea it seems to be rather niche. Also the fact that it only produces HTML is a bummer. And the Github rendering would be even worse: https://github.com/executablebooks/MyST-Parser/blob/3d84ff87badc795d44451c79d7e78b8eef6c04bf/docs/intro.md
I have written a small pandoc filter in the past and it was not the end of the world. |
No description provided.