more updates to Markdown files

[michelou]

Follow up of PR #10767, #10826, #10860, #10875, #10953, #11016, #11062, #11158, #11235 and #11480.

Brings further updates to Markdown files in docs/reference/.

• added more external links to the online Scala 3 API docs (objects, classes and traits).
• added (deprecation) example in section dropped-features/symlits.md.
• fixed ordered list and heading level in section other-new-features/experimental-defs.md.
• fixed java.lang.Serializable in section other-new-features/transparent-traits.md.
• fixed heading level in section other-new-features/open-classes.md.
• changed external link to "paper at the ACM Scala Symposium 2021" in section experimental/canthrow.md; local file resources/safer-exceptions.pdf is not needed since it is also available from EPFL InfoScience.
• added soft keyword as in section soft-modifier.md.
• added soft keyword throwsin section syntax.md.

PS. The above changes can be viewed in the PDF document scala3_reference.pdf (1 Mb) generated with Pandoc 2.16 (PR#11257).

[liufengyun]

The original link seems to work well. Why the indirection?

[michelou]

@liufengyun Here are two facts to support the change :

1. From the quick scan below of repository lampepfl/dotty we can see that safer-exceptions.pdf is the only PDF document (directory community-build/ excepted) :

   dotty>where /r . *.pdf |wc -l
   17
   dotty>where /r community-build *.pdf |wc -l
   16
   dotty>where /r docs *.pdf
   dotty\docs\resources\safer-exceptions.pdf
   

   Side note: The file is not needed to build Scala binaries or docs (and there exist over 800 forks of lampepfl/dotty !).

2. Accessing PDF publications from Infoscience is the way to go IMO, e.g.

   • LAMP publications (166 records)
   • Fengyun's publications (16 records)

   For instance, "Dependent Object Types", the seminal paper from Nada, Adriaan and Martin, is available from Infoscience resp. is not included in lampepfl/dotty.

[liufengyun]

I see now that the PDF poses a problem if we are going to build a PDF version of the spec. That sounds like a strong argument for the change.

Maybe we can remove the PDF from the repo?

[michelou]

I see now that the PDF poses a problem if we are going to build a PDF version of the spec. That sounds like a strong argument for the change.

Maybe we can remove the PDF from the repo?

Indeed.

[liufengyun]

There is only one example, what about:

Suggested change

	<summary>Example 1</summary>
	<summary>Show example</summary>

[michelou]

@liufengyun other-new-features/experimental-defs.md is the Markdown file with the most changes.

Here are two notes about my changes to that file :

1. The text inside the <details>-block is handled differently if generating HTML code or generating a PDF document. In particular the show/hide mechanism associated with <details>-blocks is stripped out when generating a PDF document.

2. Initially the <details>-blocks did include all code examples for each of 5 elements of the numbered list.

   <details>
     <summary>Examples</summary>
     <pre> // code 1 </pre>
     <pre> // code 2 </pre>
     <pre> ... </pre>
   </details>

   In the PR version I choose a more modular approach where each code example is enclosed in a <details>-block with a simple introducing text "Examples : " at the end the preceding text paragraph (as encountered in the rest of the Scala 3 Reference). The end result in HTML looks as follows :

   Example 1

   // code example 1

   Example 2

   // code example 2

   Example 3

   // code example 3

   ...

   Final notes (feedback is welcome !) :

   • One possible improvement would be to add a short description for each example, e.g. "Example 1 : bla bla bla" instead of just "Example 1".
   • At some point I also considered the option to split some code examples in order to have both examples which compile correctly and examples which generate errors.