[docs/reference] more fixes in Markdown files

[michelou]

Follow up of PR #10767, #10826, #10860 and #10875.

Fixes more issues found in Markdown files in docs/reference/, e.g,

• added empty lines before/after fenced code blocks
• updated several external links (e.g. 2.12 -> 2.13)
• added attribute {.scala} to verbatim text (just as with fenced code blocks)
• replaced single line of code with example on page dropped-features/nonlocal-returns.html.

PS. The above changes can also be viewed in the PDF document scala3_reference.pdf (888 Kb) generated with Pandoc 2.11 in ~40 seconds.

[ShapelessCat]

Using Clauses --> Using clauses

[michelou]

Using Clauses --> Using clauses

Done (6bc9dd0).

[liufengyun]

LGTM

added attribute {.scala} to verbatim text (just as with fenced code blocks)

Is it an extension of markdown that is supported by the doc tool? If the motivation is for generating PDF, it seems simpler to assume {.scala} as the default, and only add the attribute if it's different.

[michelou]

LGTM

added attribute {.scala} to verbatim text (just as with fenced code blocks)

Is it an extension of markdown that is supported by the doc tool? If the motivation is for generating PDF, it seems simpler to assume {.scala} as the default, and only add the attribute if it's different.

1. You're right, it may be not supported by the doc tool. I suggest to add one of the Scala3doc authors as a reviewer.
   NB. Based on my experiments an unknown attribute is just ignored.
2. I assume you agree with my wish to get the same syntax coloring for Scala code both in verbatim text and in fenced code blocks.
   I see two options here (depending on point 1):
   • I find a way to set .scala as default attribute in verbatim text (although counter intuivite IMO)
   • I revert all attribute additions (and lose the correct coloring in the generated PDF document).

[liufengyun]

2. I assume you agree with my wish to get the same syntax coloring for Scala code both in verbatim text and in fenced code blocks.

I think it's an improvement, thanks for your typography expertise to improve the quality of the doc. For fenced blocks, I'd like to suggest interpret them as Scala code by default if no language is specified. This way, fenced code and inline code also align in syntax.

[michelou]

2. I assume you agree with my wish to get the same syntax coloring for Scala code both in verbatim text and in fenced code blocks.

I think it's an improvement, thanks for your typography expertise to improve the quality of the doc. For fenced blocks, I'd like to suggest interpret them as Scala code by default if no language is specified. This way, fenced code and inline code also align in syntax.

The reference documentatiom also contains EBNF grammar in fenced code blocks and a language attribute .ebnf does not exist as far as I know. Assuming Scala code by default would require such an attribute (or we would have to use the other syntax for EBNF).

[michelou]

@liufengyun I decided to postpone the addition of the {.scala} to not delay the other modifications (d96b2a2).

Let us handle it in another PR.

[liufengyun]

@liufengyun I decided to postpone the addition of the {.scala} to not delay the other modifications (d96b2a2).

Let us handle it in another PR.

LGTM

[michelou]

@abgruszecki Can you please validate your review for this PR and switch to Issue #11014. Thanks.