Code highlight markup causes link text to not be colored

[per1234]

If a reference page uses code highlight markup on link text:

reference-en/Language/Structure/Further Syntax/include.adoc

Line 27 in 15e183f

Note that `#include`, similar to link:../define[`#define`], has no semicolon terminator, and the compiler will yield cryptic error messages if you add one.

it is rendered on the Language Reference like this:

The reference pages contain many links that use a code term as the link text and it's nice to use the code markup on these terms to clearly differentiate them from regular text but it's not worth doing so if it results in a link that is not visually noticeable.

I wonder whether it would be possible to change this (perhaps via a stylesheet?) so that the text is still colored as a link, similar to how GitHub renders the following Markdown:

[`define`](https://www.arduino.cc/reference/en/language/structure/further-syntax/define)

as:
define

[animeshsrivastava24]

The discussion present on asciidoctor/asciidoctor#1555
I also read the Differences between Asciidoctor and AsciiDoc, I hope so the discussion link posted above, may help us solve the problem. I'll do the necessary change to a file and send the PR.
@per1234 Please can you have a look and guide me, whether the discussions are related to this issue.

[per1234]

asciidoctor/asciidoctor#1555 doesn't seem to be relevant as it's about code blocks.

As for the "Differences between Asciidoctor and AsciiDoc" links, there's a lot of information there. Would you mind pointing out which specific part of it you think is relevant?

If you think you have a solution to this issue, post a snippet of markup here and I'll check it out.

[animeshsrivastava24]

As for the "Differences between Asciidoctor and AsciiDoc" links, there's a lot of information there. Would you mind pointing out which specific part of it you think is relevant?

For this part, I meant that I understood how both works and how they differ in their working part. From the link posted, I mainly understood about Markdown-style syntax and Source code highlighting. Yes, I totally agree that the above-posted link is for code blocks. I thought this might fix out the issue.

From the Issue Description, I understood that for:

Note that `#include`, similar to link:../define[`#define`]

The Asciidoc document shows it as:

but on the website, we get the output:

Please, can you guide me on how to check/see how my asciidoc code renders on the website?
I want to check it using different ways, is there any way of doing it.
For example:

`link:../define[#define]`

It works fine on Asciidoc and displays link inside the code

but I don't know how it will display it on a webpage.

[per1234]

Please, can you guide me on how to check/see how my asciidoc code renders on the website?

The system Arduino uses to generate the Language Reference website from the asciidoc files is in a private repository. I can tell you it uses Asciidoctor and Hugo. For what you want to do, I believe you would only need to use Asciidoctor.

Interestingly, I understand that GitHub also uses Asciidoctor to render asciidoc, but evidently there is some difference between the way they use it and the way Arduino uses it.

For example:

`link:../define[#define]`

It works fine on Asciidoc and displays link inside the code

I just tested, and that works! Great job!

I'm so used to Markdown that I would never expect that to work. The equivalent in Markdown:

`[#define](../define)`

renders like this:
[#define](../define)

[animeshsrivastava24]

The system Arduino uses to generate the Language Reference website from the asciidoc files is in a private repository. I can tell you it uses Asciidoctor and Hugo. For what you want to do, I believe you would only need to use Asciidoctor.

Thanks a lot for this information.

I just tested, and that works! Great job!

I am so happy that it worked.

I'm so used to Markdown that I would never expect that to work. The equivalent in Markdown:

`[#define](../define)`

renders like this:
[#define](../define)

Yes, I totally agree, how the same render in Markdown.

So, is it possible to fix this issue now? I'll love to do it. Should I compile a list of all the pages, that have a link inside code elements and then fix them?
@per1234 Please guide.

[per1234]

So, is it possible to fix this issue now?

Yes!

Should I compile a list of all the pages, that have a link inside code elements and then fix them?

I think you could do a search for `] to find all of them.

My opinion is this: In cases where we want it to be obvious to the reader that there is a link, it should always have link coloration. However, there is a proposal to linkify all occurences of text that corresponds to a Language Reference page (#462). I'm in support of that, but I do think there might be cases where "convenience linkification" (where we just linkify everything so the reader can easily click on any term they might be interested in knowing more about) could lead to a "sea of teal" effect, where practically every other word in a paragraph is colored as a link. That which might harm readability. In this case, it might make sense to intentionally use the quirk of the old link formatting style causing links to not be colored to avoid the "sea of teal".

Here's an example of what I mean:

The function terminates if the terminator character is detected, the determined length has been read, or it times out (see Serial.setTimeout()).

Here, we are intending to direct the user to the Serial.setTimeout() link and so we should use this style of asciidoc markup so that the link will be colored:

see `link:../settimeout[Serial.setTimeout()]`

Now consider this (made up) text:

If you have used pinMode() to set the pin to INPUT mode then digitalRead() on that pin when the pin is grounded will return LOW. digitalRead() on that pin when the pin is connected to Vcc will return HIGH. If the pin is not connected to anything, digitalRead() will return random values of HIGH and LOW. If you used pinMode() to set the pin to INPUT_PULLUP mode then digitalRead() on that pin when the pin is not connected to anything will always return HIGH.

I think you can see how certain parts of the text in the reference might become a bit too heavy on teal (blue here). In these cases, I think it would make sense to allow the first instance of each term to be colored, but then use the old markup style to cause subsequent occurrences of the term to not be colored (though still linkified):

If you have used `link:../pinMode()[pinMode()]` to set the pin to `link:../INPUT[INPUT]` mode then `link:../digitalRead[digitalRead()]` on that pin when the pin is grounded will return `link:../LOW[LOW]`. link:../digitalRead[`digitalRead()`] on that pin when the pin is connected to Vcc will return `link:../HIGH[HIGH]`. If the pin is not connected to anything (floating), link:../digitalRead[`digitalRead()`] will return random values of link:../HIGH[`HIGH`] and link:../LOW[`LOW`]. If you used link:../pinMode[`pinMode()`]to set the pin to `link:../INPUT_PULLUP[INPUT_PULLUP]` mode then link:../digitalRead[`digitalRead()`] on the floating pin will always return link:../HIGH[`HIGH`].

[animeshsrivastava24]

Yes, I understood your point that we should use teal colour inside the code for functions only for their first occurrences and leave the rest occurrences following the old fashion where they are a link without the teal colour, to avoid "sea of teal" effect.

I'll work out to find and compile a list of all the pages and post it here and then work on them to fix this issue.

Thanks a lot for the valuable suggestion.
@per1234 Please guide me on the work I present in the next comment.

[SeppPenner]

Wuha :D @animeshsrivastava24 You must be crazy, haha 👍

[animeshsrivastava24]

@SeppPenner 😅 . I'll make sure after this Issue gets fixed, I'll send single PR for multiple file changes. I know it creates a lot of PR which might not be good.