Closed ischoegl closed 10 months ago
I haven't looked, but this is probably an unfortunately limitation of rST
link formatting, which doesn't allow text formatting inside the link. See https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
I haven't looked, but this is probably an unfortunately limitation of
rST
link formatting, which doesn't allow text formatting inside the link. See https://docutils.sourceforge.io/FAQ.html#is-nested-inline-markup-possible
Interesting. When I ran into a similar issue in #1548, I was able to resolve it by placing everything in HTML <tt> ... </tt>
. brackets. I had assumed this to be a quirk of the doxygen markdown flavor, but may be wrong ...
Markdown in general shouldn't have a problem with nested markup (although it may depend on the parser). For example, GitHub comment boxes allow nested markup: a tt link
which is generated with
[`a tt link`](https://github.com/cantera)
I believe this is specifically a limitation of reST, as this file is written in rST: https://github.com/Cantera/cantera/blob/main/doc/sphinx/yaml/phases.rst
@ischoegl Should we close this issue as this is not fixable except by switching to an alternative markup format/parser?
@ischoegl Should we close this issue as this is not fixable except by switching to an alternative markup format/parser?
Does wrapping this as
<tt> [some_description](https://github.com/cantera) </tt>
work? (this was the solution in #1548, although the mechanism doxygen uses to generate links is very different)
No, because the file is reST not markdown.
No, because the file is reST not markdown.
Ugh ... reST, of course. I really don't like this format.
About closing this issue, I don't think that it should be closed. Unless you read the text carefully, the listed items look like links and don't indicate that these are the actual strings to be used in these instances. Perhaps the solution is to type the model name without the link, and provide the link next to it?
Edit: but it's ok to defer ... moved this to 'triage'
There are a couple of instances where string-entries that link to further documentation should have typewriter font.
As an example, for the YAML reference for the Phase->transport entry, 'none', 'high-pressure', and similar entries should be clearly identified as string with typewriter font (whether or not to use quotes is debatable).
The same applies to Phase->thermo, Phase->kinetics, SpeciesThermo->model, Reactions->type, and potentially a couple of others. Edit: One more here.