The HTML manual displays bad outputs and is too hard to use

[quark67]

On http://mirrors.ctan.org/macros/generic/markdown/markdown.html (I don't find the corresponding HTML file on this GitHub project), for exemple on section 2.1.3 (LaTeX), we see the output of the code, and it appears as:

Square root and minus sign is very ugly. And it's not an image, but an HTML generated material.

Why don't you provide a PDF manual with the real (nice) output?

Also, I don't find all the options for

\begin{markdown*}{...}

(Edit: found hybrid at 2.2.1.28 (!). But there is no 2.2.1.28 in the table of content in the beginning of the HTML file. And why this hybrid is only described for Lua? Why not on 2.2.3.x for LaTeX? On 2.1.3 the "hybrid" is used in the LaTeX exemple)

With a PDF manual with a index, it will be more user friendly to find all relevant information. After all, LaTeX output PDF, not HTML.

Hope you can correct all this (I know that write a user manual is a pain).

[Witiko]

Square root and minus sign is very ugly. And it's not an image, but an HTML generated material.

I suppose we could use MathML here.

And why this hybrid is only described for Lua? Why not on 2.2.3.x for LaTeX?

The hybrid option is a Lua option. Even though it can also be set from LaTeX, it's not LaTeX-specific.

This is explained in Section 2.2.3.1:

2.2.3.1 Setting Lua and plain TeX options from LaTeX

As a rule of thumb, we can set all Lua options directly from LaTeX. For example, to set the taskLists Lua option to true, we would include the following code in our LaTeX document:

\markdownSetup{
  taskLists = true,
}

The section then lists the LaTeX-specific option of plain and the LaTeX-specific concepts of themes and snippets.

Also, I don't find all the options for \begin{markdown*}{...}

Which options did you not find?

But there is no 2.2.1.28 in the table of content in the beginning of the HTML file.

The table of contents only contains top-level sections. It would be difficult to navigate if the table of contents included all section levels.

[Witiko]

With a PDF manual with a index, it will be more user friendly to find all relevant information.

We provide a technical documentation in PDF, which contains an index as well as all the details of the implementation, and an user manual in HTML, which is shorter and focuses on examples. However, despite the changes aimed at making the user manual easier to read (see Section 3 of my article in TUGboat 40:1), it is still automatically generated from the source code of the Markdown package, which makes it less readable than it perhaps should be. @writersglen also remarked that the user manual would benefit from having a number of versions, each for a different TeX format such as plain TeX, LaTeX, and ConTeXt.

In the future, I would like to separate the user manual to an independent document (or set of documents) independent of the Markdown package, see #135 and #184. This is similar to how we separated an important part of the code into the independent lt3luabridge package. Besides simplifying the code, this should make the user manual more readable and also available in a number of formats, including PDF. However, we currently don't have any contributors who would be willing to work on this.