I've read in guidelines for applications: > Provide an HTML version of all documentation. They are easier to > navigate and better convertible. What are you thoughts on documentation converted to HTML from another format? For example, there are lots of man-to-html converters. Which of them (mandoc? man2html?) produce the most accessible HTML? Same about markdown translators.
On Mon, Jun 20, 2022 at 12:15:58PM +0500, Anna “CyberTailor” wrote: >I've read in guidelines for applications: > >> Provide an HTML version of all documentation. They are easier to >> navigate and better convertible. > >What are you thoughts on documentation converted to HTML from another >format? > >For example, there are lots of man-to-html converters. Which of them >(mandoc? man2html?) produce the most accessible HTML? Ooh, this is a good question. I'm not intimately familiar with the different man-to-html converters; I'll have to take a closer look and send a patch. >Same about markdown translators. Here, it's partly about the markdown implementation (goldmark, pandoc, php-markdown-extra, etc.) and party about the standard being implemented (CommonMark, GitHub-Flavored-Markdown, etc). I'm most familiar with Goldmark, which emulates PHP-Markdown-Extra. It's pretty good with its use of DPUB-ARIA, though it has some faults: - Footnote backlinks don't have accessible names - The Table of Contents and footnotes don't have headings. In fact, Goldmark recently switched footnotes from a <section> to a <div> because a <section> is supposed to have a name or heading. I fix these by applying regular expression transformations to generated pages. When you pick a markdown implementation, here are some things to watch out for: - Can you have multiple footnotes links point to the same footnote, with each footnote link getting a unique ID? - Does it use DPUB-ARIA where appropriate (table of contents, footnotes, etc)? - Are generated <pre> blocks tab-focusable? I know that implementations like Goldmark add a `tabindex` attribute to them. This is important because <pre> blocks should support horizontal scroll, which is a form of interactivity that keyboard users should have access to. I believe Pandoc supports extensions that allow you to do this manually. -- Seirdy