RustDoc: hyperlinks in (text) code blocks/snippets

documentation
1

This might be a highly specific use-case. I am currently writing a parser and in the documentation I would like to have little snippets of the grammar showing what some specific struct represents. For example:

/// # Grammar
/// `Conjunct -> Inverse ("||" Conjunct)?;`

Now in this example, both Conjunct and Inverse are the names of structs which represent that bit of the grammar, so I would like to be able to turn those references into links like so:

/// # Grammar
/// `[Conjunct] -> [Inverse] ("||" [Conjunct])?;`

I can bodge this in using HTML, but it's extremely cumbersome. It would be nice if there was an officially supported approach. It might be a bit of an overextension (since basic markdown also does not support this), but I can imagine it being a generally useful feature.

2

I'm not sure how that would work, given that the whole point of `` is to display preformatted text as-is, without interpretation. `` is the wrong tool for formatted text in a monospace font – the <tt> HTML element would be the right one, but I'm not sure if the Rustdoc Markdown supports it. This forum doesn't seem to, sadly.

3

Relevant issue:

If that were supported you could write this as

/// # Grammar
/// [`Conjunct`]` -> `[`Inverse`]` ("||" `[`Conjunct`]`)?;`
4

That seems like a pretty good solution. Certainly better than my idea of specifying links directly in code blocks for the reasons jdahlstrom mentions above. Though I do wonder how it would work when dealing with full code blocks. For example:

/// # Grammar
/// ```
/// [`A`] -> [`B`]
/// [`A`] -> [`C`]
/// ```

You'd have to make sure that subsequent code blocks are also merged into one.

5

Why is HTML considered "extremely cumbersome"? You can still use intra-doc links inside the tag.

<code>[Conjunct] -> [Inverse] ("||" [Conjunct])?;</code>

Conjunct -> Inverse ("||" Conjunct)?;

6

Interesting. I tried it before using the <pre> tag (because I want to do a full code block like in my previous comment), but intra-doc links do not work inside those. They do indeed work inside <code> tags, but then multi-line stops working.

:edit: which I guess would then be solved by the issue Nemo157 linked in this thread.

7

That one is going to require a workaround, because <pre> is a block element, so it gets parsed differently. You need to force it to get parsed in inline mode.

<span><pre>
[Conjunct] -> [Inverse] ("||" [Conjunct])?;
</pre></span>


Conjunct -> Inverse ("||" Conjunct)?;

8

Oh that works! Thanks a lot! I guess we can close this thread now, but I hope others find this conversation in the future and it can help them as well.

Final note is that, if you then inside the <pre> block want to force it to again display the preformatted text as-is, you can wrap the required bit in backticks again, like so:

<span><pre>
[Conjunct] -> [Inverse] (`"||"` [Conjunct])?;
</pre></span>

In order to prevent the "" from being displayed as fancy quotation marks.