Doxygen does not support emphasis of file extensions in markdown

[RochaStratovan]

I am trying to add emphasis to a file extension. It renders fine in a markdown viewer. Doxygen doesn't render it correctly.

Example markdown

2. If a script is applicable to ***both*** Windows and Linux it will not have a
   trailing **.bat** or **.sh** extention.

Markdown render example 1

Markdown render example 2

Doxygen render

[albert-github]

Most likely a bug in the doxygen markdown interpreter, though a . always has a special handling, but seems to be a problem when it is at the first, non-blank, position after the start of a style element like bold, emphasis, struikethrough.

Note: always mention the doxygen version used (doxygen -v), the differences in the doxygen settings compared to the default settings (doxygen -x Doxyfile), so in general (for the future):

• Can you please attach a, small, self contained example (source+configuration file in a tar or zip) that allows us to reproduce the problem? Please don't add external links as they might not be persistent.
• Please also specify the full doxygen version used (doxygen -v).

[albert-github]

From the documentation:

5.3.4 Emphasis and strikethrough limits
Unlike standard Markdown and Github Flavored Markdown doxygen will not touch internal underscores or stars or
tildes, so the following will appear as-is:
a_nice_identifier
Furthermore, a * or _ only starts an emphasis and a ~ only starts a strikethrough if
• it is followed by an alphanumerical character, and
• it is preceded by a space, newline, or one the following characters <{([,:;

An emphasis or a strikethrough ends if
• it is not followed by an alphanumerical character, and
• it is not preceded by a space, newline, or one the following characters ({[<=+-\@

The span of the emphasis or strikethrough is limited to a single paragraph.

So the problem looks like it is well documented and thus usage.

@doxygen should we allow the punctuation characters as suggested by the Merriam-Webster?

From https://en.wikipedia.org/wiki/Alphanumeric:

Alphanumericals are a combination of alphabetical and numerical characters, and is used to describe the collection of Latin letters and Arabic digits or a text constructed from this collection.

Merriam-Webster suggests that the term "alphanumeric" may often additionally refer to other symbols, such as punctuation and mathematical symbols.[1]

In the POSIX/C locale, there are either 36 (A-Z and 0-9, case insensitive) or 62 (A-Z, a-z and 0-9, case-sensitive) alphanumeric characters.

[RochaStratovan]

As a daily user of markdown, I would like Doxygen to get rid of all of it's markdown limitations and render markdown the same as standard markdown renderer such as github, gitlab, etc.

I don't mean github/gitlab's extended markdown syntax (although that would be nice). I would like Doxygen to just work with the standard well formed markdown, and not need special treatment to work.

You are correct this limitation is documented, but that limitation really makes Doxygen an undesirable tool for markdown conversation. Doxygen doesn't really support markdown, just some general aspects of it.

I'm not sure about other organization but we have new grads that know git (gitlab, github, etc.) and don't know Doxygen. They are accustomed to using WYSWIG editors. Writing Doxygen .dox files for documenation has become a deal breaker for us (well, them.. I'm old school.. I remember WordPerfect).

We were excited about the markdown conversation, but then when we started to use it --- it quickly became disappointing.

---

Doxygen Version

C:\Users\rocha\Desktop\Workspace-2\JRR\TEST>doxygen.exe -v
1.9.2 (caa4e3de211fbbef2c3adf58a6bd4c86d0eb7cb8)

I made a single test.md for all of the emphasis issues I am seeing

This extention should be bold: **.bat**

This extension should be italics: *.bat*

This extension should be bold italics: ***.bat***

This extension should be fixed bold **`.bat`**

This extension should be fixed italics *`.bat`*

This extension should be fixed bold italics ***`.bat`***

This quoted text should be bold "**inside**"

This quoted text should be bold italics "***inside***"

This entire quote should be bold **"outside"**

This entire quote should be bold italics ***"outside"***

This entire quote should be italics *"outside"*

😄 Gitlab Render

😄 GitHub Render

😄 Markdown Monster Render

😭 Doxygen Render



This example shows that bold-italics works for outside quotes as well as extensions (.bat)

I've attached the test file as you've requested:
example.zip

[albert-github]

Some remarks (non-authoritative).

The problem with Markdown is that there is not really a standard there are 2 major definitions well known:

• The original: https://daringfireball.net/projects/markdown/
• CommonMark Spec: https://spec.commonmark.org

In principle doxygen and Markdown have different philosophies / purposes.
The purpose of Markdown is to write documentation, but the purpose of doxygen is to have documentation based on the comments in the source code and create cross references in the documentation (either to the source code or to other parts of the documentation) and have an idea of the structure of the code. The original doxygen was a.o. based on some code from Doc++ and ideas from Qt documentation and the needs of programmers. The support for Markdown was added doxygen 1.8.0 (February 25, 2012) as an extension to the documentation possibilities with limitations.

The goal is, of course, to get as close as possible to the mentioned definitions, but due to the different philosophies this will not always be possible to accomplish. Doxygen still has the possibility to use the standard doxygen commands, some HTML Commands and some XML Commands. Of the HTML Commands a number are also well understood by the different Markdown renderers.

[RochaStratovan]

Wow. Thanks for the additional information. I didn't know there were two standards.

As a developer myself it seems like possible solutions would be a new flag in the config file indicating which Markdown method the user is choosing. Although, I also think using the github/gitlab base variant would be the most widely used (based on the how widely used those tools are in both cloud and on premise settings.)

I understand that Doxygen's purpose is different from markdown. Doxygen isn't for writing documents, it's for writing API info based on comments. However, it seems like this is a case where Doxygen is treating a markdown file as a commented file.

It seems like this could be a marriage of two technologies. Doxygen gives the comment related documentation like it always does, but when it translates a .md or .markdown file it would do so like a markdown renderer.

Then Doxygen becomes a complete documenting solution -- well more complete -- I'm sure there is plenty that I'm missing.

[PhilipNelson5]

I am also encountering this issue. We're using doxygen for it's principal purpose of documenting code through comments but then we want to extend the documentation with markdown. We are trying to avoid using two documentation solutions (like MkDocs, etc); however, these limitations are proving to be frustrating. I'd love to see something like @RochaStratovan described!

[albert-github]

@PhilipNelson5

For the problems you encountered:

• Can you please attach a, small, self contained example (source+configuration file in a, compressed, tar or zip file!) that allows us to reproduce the problem? Please don't add external links as they might not be persistent (also references to GitHub repositories are considered non persistent).
• Please also specify the full doxygen version used (doxygen -v).

[PhilipNelson5]

@albert-github of course, here is the example given above by @RochaStratovan

Doxygen Version: 1.10.0 (ebc57c6dd303a980bd19dd74b8b61c8f3f5180ca)
DoxygenEmphasisExample.zip

[PhilipNelson5]

For what it's worth, there is precedent for following the way GitHub handles markdown

From the default doxyfile

# The MARKDOWN_ID_STYLE tag can be used to specify the algorithm used to
# generate identifiers for the Markdown headings. Note: Every identifier is
# unique.
# Possible values are: DOXYGEN use a fixed 'autotoc_md' string followed by a
# sequence number starting at 0 and GITHUB use the lower case version of title
# with any whitespace replaced by '-' and punctuation characters removed.
# The default value is: DOXYGEN.
# This tag requires that the tag MARKDOWN_SUPPORT is set to YES.

MARKDOWN_ID_STYLE      = DOXYGEN

[albert-github]

The problem with the GitHub version of markdown is that I have not been able to find document describing the features used.
The MARKDOWN_ID_STYLE has been introduced based on reverse engineering a number of available section headers and doing some (educated) guesses.

Can you point me to a document describing the syntax used by GitHub?