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