Tools docs: Unwanted conversion of double minus sign

[Dave-Allured]

CORRECTED MESSAGE. This problem occurs in Tools docs, not install docs.

In command line tool docs, such as h5dump documentation, double minus signs are used extensively for command line options. Example: h5dump --version.

In the newly converted "2.1.1" markdown docs, many of these double minus signs are seeing unexpected conversion into a single Unicode n-dash, when viewed in an ordinary web browser. I am seeing this in GitHub "Preview" mode when trying to read the install docs in my browser (Safari on Mac). I speculate that GitHub itself is doing this conversion when rendering web pages, and is independent of the browser, but not sure.

In these tools docs, many of these double minus signs are seeing unexpected conversion into a single Unicode n-dash, when viewed in an ordinary web browser.

These usages need to be somehow escaped or coded, such that they will render correctly as simple double minus signs in the ordinary browser. In particular this is needed for cutting and pasting commands. A pasted n-dash will result in a command error. Old hacks like me can usually recognize this confusion fairly quickly, but this can be troublesome for less experienced users.

I find other pages in support docs that are rendering many double minus signs correctly, but I am not sure how they do it. Escaping as code excerpts is one way. I am not a markdown expert. I suspect that there might be a markdown behavior that treats double minus signs differently if they are at the start of a new line; which is where I first noticed this problem.

Please fix the rendered double minus signs, when you can get to it. Thanks.

[ajelenak]

Can you provide a few places where this happens as rendered by your browser?

[Dave-Allured]

CORRECTION: The invalid double minus signs are in tools documentation, NOT install docs. Such as the h5dump documentation page. This may have nothing to do with markdown. I was not able to locate the source code for the tools docs.

Changing title now. Sorry for the confusion.

[Dave-Allured]

@ajelenak This is all over the h5dump doc page, which I just referenced. The first three instances of bad rendering on that page are --enable-error-stack, --help, and --version.

I typed explicit double minus signs here in this message, and they are showing correctly here in GitHub. They are rendering as single n-dashes on the actual doc page, as seen in my browser. Do you see it?

[jhendersonHDF]

@ajelenak This is all over the h5dump doc page, which I just referenced. The first three instances of bad rendering on that page are --enable-error-stack, --help, and --version.

I typed explicit double minus signs here in this message, and they are showing correctly here in GitHub. They are rendering as single n-dashes on the actual doc page, as seen in my browser. Do you see it?

The tools documentation is rendered by doxygen instead of Markdown. It looks like we need to go through and escape all of them as \--. This would be in all of the header files in the tools directory such as https://github.com/HDFGroup/hdf5/blob/develop/tools/src/h5dump/h5dump.h and potentially some of the H5Xmodule.h headers in the source. Probably a lot of work!

[Dave-Allured]

Doxygen. Okay, now I get it.

@jhendersonHDF I am glad this problem is acknowledged, and the needed fix was identified quickly. Thanks.