Special command \snippet{doc} apparently does not honor Markdown

[mcondarelli]

Describe the bug
I am trying to use some pieces of doxygen documentation to both document the sources and produce some overall documentation, possibly without duplicating it.

I asked a question on stackoverflow and, with @albert-github help I arrived to the working snippet below.

Expected behavior
Problem is Doxygen seems unable to recognize any Markdown construct in included snippet, only HTML tags are honored.

To have an example simply remove the <br> tags and you'll see double-newline is not recognized as paragraph-break.

Same thing for lists, inline code markers and other Markdown constructs.

HTML and Doxygen "Special Commands" are correctly recognized.

Is there some way around this? Writing documentation in HTML is a royal PITA :(

Another (very minor) hassle is included code must be in "normal" (non-Doxygen) comment so many editors will not help you out.

Screenshots

To Reproduce

bb.h

/// \file

/**
@page __init Initialization
@snippet{doc} CommandHandler.c AM_init
*/

CommandHandler.c

/// \file

/**
 * Initialization function.
 */

/* [AM_init]
   It needs to do a long series of tests to ensure AM can actually work.<br>

   It should also allocate all dynamic memory needed to avoid runtime failures.<br>

   It will be responsibility of system-level daemon to take appropriate action.<br>
   [AM_init]
 */
/**
 * \snippet{doc} this AM_init
 *
 * @param ip_addr
 * @param port
 * @return
 */
static uint32_t AM_init(const char* ip_addr, uint16_t port){}

Doxyfile

EXTRACT_STATIC = YES
EXAMPLE_PATH = .
QUIET = YES

Version
1.9.1

Stack trace

Additional context

[albert-github]

Strange that the user on stackoverflow is linked to the user here.

I did some tests on the following example:

/// \file

/**
<hr>
@snippet{doc} this AM_init2
<hr>
inline1

inline2
inline3
<hr>

*/
/* [AM_init2]
snippet1

snippet2
snippet3
[AM_init2]
 */
void fie();

and the HTML result is:

A number of investigations already to some conclusions:

• problem is not in the markdown part (markdown output for the "inline" and "snippet" version are identical, checked with doxygen -d markdown).
• the problem is only in the HTML output
• the problem comes from the HTML paragraph (<p>) handling in doxygen

A small test example: example.tar.gz

[mcondarelli]

Thanks Albert.
I actually noticed the activity of a "@albert-github" guy here and it seemed suspiciously similar to the "@Albert" who was so kind on stackoverflow, so I manually appended the "-github" to the name; I hope I didn't trespass.

I actually already noticed something was wrong with Doxygen handling of <p> tag;
I was using BlueGriffon to edit HTML to ease the hassle to write tags (manually copying sections of HTML "source" into my comments) and it dutifully wraps each paragraph with <p>...</p>.
This is not honored also; I had to manually change the wrapping in <p>...<br/></p>.
... but I don't really understand the implications, can you elaborate, please?
I feel a little dumb.

[mcondarelli]

I did some further tests and what you say doesn't seem completely true:
If I slightly modify your example as:

/// \file

/**
<hr>
@snippet{doc} this AM_init2
<hr>
inline1

inline2
`inline code`
inline3
<hr>

*/
/* [AM_init2]
snippet1

snippet2
`snippet code`
snippet3
[AM_init2]
 */
void fie();

It's plainly seen "inline code" is rendered as code (monospaced font) while "snippet code" is left unchanged (variable pitch font and backticks).
This holds true in HTML rendering and in other rendering also (I checked latex and rtf).

It seems to me we have two "bugs here:

1. Markdown is not applied to \snippet{doc} included text (for all renderings).
2. HTML <p> tag is incorrectly handled for HTML rendering.

Unfortunately I have no idea about how to further pursue issue.

Note: as you may have guessed stackexchange user is actually me; this is my "official self".

[albert-github]

The problem with the code is already solved, in the 1.9.1 version I see:

and in the 1.9.4 version I see:

(in both cases I made the code parts red for better visibility)

The problem with the <p> tag is a bit more difficult as this is a very delicate part in the code where it is decided when a new <p> tag has to begin and and old <p> tag has to end.

[albert-github]

I did some tests and the result was that in the routine static bool determineIfNeedsTag(const DocPara &p) in htmldocvisitor.cpp in case of the inline version doxygen reached twice the part else if (std::get_if<DocRoot>(p.parent())) and set the needsTag to true.
In case of the config version only the first time we got into the mentioned else if . It was followed by 2 occurrences where the docNodeName of p.parent() was DocPara.

So either

• the snippet is incorrectly added into the tree (a level to deep?, but this would contradict a bit the results from the other output formats
• we have to handle the DocPara (in some cases?) also in in determineIfNeedsTag.

@doxygen Do you see a solution?

[mcondarelli]

FYI: I moved to latest Doxygen (compiled from git master) and it seems to behave better as far as Markdown support is concerned, but has other "strange quirks" I'm still investigating:

• using ### title to mark a subsubsection completely stops \snippet{doc} processing; i.e: whatever is after it is lost.
• latex seems to need something like <h4>title</h4><br/> otherwise following text is on the same line as "title" (but in "normal font").
• OTOH using <br/> as above produces a double newline in HTML output.

[albert-github]

From the short description it smells a bit like the same problem as with the regular text, but without an example it is hard to tell.

[mcondarelli]

Sorry @albert-github
I was fighting to get something passably done before the weekend.

I installed from git master on a different machine (also Debian SId)
and this might account for some discrepancies, however:

my yest program is:

/// \file

/**
@note The PROJECT_NUMBER disappeared from PDF documentation (it was present in v 1.9.1).

<hr>
@snippet{doc} this AM_init2
<hr>
inline1

inline2
`inline code`
inline3

<h4>Some header</h4>
This normal text will be right after the header in PDF.

<h4>Some other header</h4><br/>
This normal text will have double spacing in HTML.


### Some title
the title above and this will be preserved in  documentation,
but also here normal text will follow title  without newline.
<hr>
*/
/* [AM_init2]
snippet1

snippet2
`snippet code`
snippet3

<h4>Some header</h4>
This normal text will be right after the header in PDF.

<h4>Some other header</h4><br/>
This normal text will have double spacing in HTML.


### Some title
everything from the above line down
will disappear from documentation
[AM_init2]
 */
void fie();

I call doxygen using this script:

#!/bin/bash
set +x
set +e

echo  > tmp.doxyfile 'PROJECT_NAME           = "My Wonderful Test Project"'
echo >> tmp.doxyfile 'QUIET                  = YES'
echo >> tmp.doxyfile 'EXTRACT_ALL            = YES'
echo >> tmp.doxyfile 'EXTRACT_STATIC         = YES'
echo >> tmp.doxyfile 'JAVADOC_AUTOBRIEF      = YES'
echo >> tmp.doxyfile 'INPUT                  = .'
echo >> tmp.doxyfile 'EXAMPLE_PATH           = .'
echo >> tmp.doxyfile "PROJECT_NUMBER = \"version in git: 0bf0bb7-dirty\""

doxygen tmp.doxyfile
rm tmp.doxyfile
[ -f doc.zip ] && rm doc.zip
( cd latex && make )>/dev/null && zip -rq doc.zip latex/refman.pdf html/

This is what I see in PDF:

... and this is what I see in HTML:

Note PROJECT_NUMBER is correctly displayed in HTML.

Please advise because I'm completely out of my depth, here.

[albert-github]

It looks like these problems are not related to the \snippet{doc} problem, so please create for the PROJECT_NUMBER and for the header problem a separate new issue and 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.
In this way it is easier to follow the progress of the different problems.

• For the PROJECT_NUMBER as small example with just the Doxyfile is sufficient
• For the `header problem" and example like: example.tar.gz is sufficient. We see here directly that the problem occurs when the nesting is quite deep (i.e. the resulting depth level is 5 or more), in that case LaTeX uses a paragraph and subparagraph type of section.

[mcondarelli]

@albert-github,
I will open two separate issues for PROJECT_NUMBER and spacing issues on headers,
but the ### issue seems \snippet{doc}-relative.
The exact same structure: ###title\ntext.\n\n is rendered inline and completely removed in snippet.
I think it belong here, but I will open a new issue if deemed useful.
Many Thanks!

[albert-github]

Regarding the ### problem we have 2 problems:

• LaTeX problem regarding the fact that the data is on one line, needs separate issue
• the missing part in the \snippet{doc} looks like to be missing in multiple output formats, so it is different from the initial issue as that was just a problem with the HTML output where some output was merged, yes please new issue (sorry I overlooked this case in the original mention Special command \snippet{doc} apparently does not honor Markdown #9365 (comment) and focused there on the merge problem).

[Klypto]

Was a separate issue filed for the LaTeX line spacing problem?

I was going to use /snippet{doc} until I realized that it just mashes all text together on one gigantic line. Latest does not seem to resolve this problem.

[albert-github]

I think there was the separate issue #9368 filed for the LaTeX problem