Some odd syntax highlighting in some code blocks

[jafingerhut]

Original comments:

• Switching from Madoko to AsciiDoc for P4Runtime specification #510 (review)
• Switching from Madoko to AsciiDoc for P4Runtime specification #510 (comment)

I believe that most of these issues are because the code blocks are not legal syntax for the language we are telling AsciiDoc to use for color highlighting the code block. For example, in something like: id: <number> in a code block marked with the language protobuf, the angle brackets are intended to denote to the reader that <number> can be replaced with any decimal integer in ASCII. The angle brackets are probably illegal, and sometimes are colorized strangely.

[Dscano]

Proposed Solution

Here are the details of the proposed changes:

• Replace # with //
• Replace #... with ...
• Replace id: <number> with id: "id_value"
• You can use https://rouge.jneen.net/ to view the results in the code highlighter.

[chrispsommers]

• You can use https://rouge.jneen.net/ to view the results in the code highlighter.

Hi Davide, I went to the site above but am not sure how to use it. Is it supposed to render the AsciiDoc? I don't see a choice for that.

[Dscano]

• You can use https://rouge.jneen.net/ to view the results in the code highlighter.

Hi Davide, I went to the site above but am not sure how to use it. Is it supposed to render the AsciiDoc? I don't see a choice for that.

Hi Chris,

You can use https://rouge.jneen.net/ to render the code contained in the .adoc file. In other words, you can copy and paste the protobuf code defined within the .adoc file to see how it will be rendered. In the case of protobuf, the # and<>symbols will be highlighted in red, as you pointed out in #510. So this means that these symbols are not rendered properly by the Rouge highlighter for protobuf.

[chrispsommers]

I see what you mean:

Is there a way to file an issue against Rouge?

[jafingerhut]

We could, of course, file an issue against Rouge. Just realize that they might not be very sympathetic to changes that require accepting incorrect syntax for the language that is being claimed to be highlighted in a code block (if that is what you are hoping to ask them -- I am not sure).

[jafingerhut]

If we do not like the syntax highlighting for a particular language that Rouge provides for Protobuf, we could consider also changing the language we claim the code block is written in, including to one that causes no color highlighting to occur at all.