[docs/reference] more fixes in Markdown files #10875

michelou · 2020-12-21T14:49:40Z

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

Note: To be discussed with other members of the Scala core team/Scala Center: in his comment to my PR #10860 @SethTisue expresses the wish to have a more "official" location for the PDF document scala3_reference.pdf I generate to check my changes to the Scala 3 reference documenation. Without any reaction from you (@liufengyun ), I will suggest @SethTisue to use the current link (which is stable since the creation of my GitHub account).

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

removed/added spaces/lines
corrected misspellings (e.g "covarant" -> "covariant")
corrected left margin in code block
reduced line width in several code blocks (to avoid text overflow in the right margin)
added several external links (e.g. Coq)

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

liufengyun

LGTM, thanks @michelou 👍

Rebase and conflict fixes are needed.

I somehow missed this comment:

Note: To be discussed with other members of the Scala core team/Scala Center: in his comment to my PR #10860 @SethTisue expresses the wish to have a more "official" location for the PDF document scala3_reference.pdf I generate to check my changes to the Scala 3 reference documenation. Without any reaction from you (@liufengyun ), I will suggest @SethTisue to use the current link (which is stable since the creation of my GitHub account).

The difficulty is how to keep the PDF up to date with the docs. The best approach seems to be update the CI to generate the PDF as part of the website update.

liufengyun · 2020-12-23T20:57:28Z

docs/docs/reference/contextual/derivation-macro.md

@@ -84,20 +78,19 @@ Instead we extract the tuple-type for element types using pattern matching over
 quotes and more specifically of the refined type:

 ```scala
- case '{ $m: Mirror.ProductOf[T] { type MirroredElemTypes = elementTypes }} => ...
+   case '{ $m: Mirror.ProductOf[T] { type MirroredElemTypes = elementTypes }} => ...


Accidental change?

Not mine (visible before rebasing with upstream).

liufengyun · 2020-12-23T21:07:42Z

docs/docs/reference/dropped-features/delayed-init.md

 ```
+On the other hand, Scala 3 offers a convenient alternative to such "program" objects
+with [@main methods](../changed-features/main-functions.html).


Nice addition 👍

Link to markdown file for consistency?

It's @odersky addition (visible before rebasing with upstream).

liufengyun · 2020-12-23T21:13:58Z

docs/docs/reference/metaprogramming/erased-terms-spec.md


-## Rules
+### Rules


Maybe remove Implementation and only keep Rules?

liufengyun · 2020-12-23T21:17:38Z

docs/docs/reference/metaprogramming/simple-smp.md

@@ -123,9 +123,9 @@ Proof by structural induction over terms.

 To prove (1):

- - the cases for variables, lambdas and applications are as in STL.
+ - the cases for variables, lambdas and applications are as in [STL](https://en.wikipedia.org/wiki/Simply_typed_lambda_calculus).


Suggested change

- the cases for variables, lambdas and applications are as in [STL](https://en.wikipedia.org/wiki/Simply_typed_lambda_calculus).

- the cases for variables, lambdas and applications are as in [STLC](https://en.wikipedia.org/wiki/Simply_typed_lambda_calculus).

michelou · 2020-12-23T22:28:57Z

LGTM, thanks @michelou 👍

Rebase and conflict fixes are needed.

I somehow missed this comment:

Note: To be discussed with other members of the Scala core team/Scala Center: in his comment to my PR #10860 @SethTisue expresses the wish to have a more "official" location for the PDF document scala3_reference.pdf I generate to check my changes to the Scala 3 reference documenation. Without any reaction from you (@liufengyun ), I will suggest @SethTisue to use the current link (which is stable since the creation of my GitHub account).

The difficulty is how to keep the PDF up to date with the docs. The best approach seems to be update the CI to generate the PDF as part of the website update.

@liufengyun For me the relevant point is to know what is your position about generating/hosting a PDF version of the Scala 3 documentation, i.e. the reference documentation in this case. The technical aspects mostly reduce to my choice to use Pandoc for generating the PDF document. As a reminder I'm running Pandoc on Windows 10 with 4 additional files:

scala3_reference.yaml (Pandoc config)
scala3_reference.md (document structure, including title page)
scala3_reference.latex (latex template, derived from Pandoc default latex template)
md2pdf.bat (resp. md2pdf.sh) to run Pandoc with the approprate settings.

Note: I could easily write the corresponding shell script (assuming Pandoc 2.11 is available on the CI machine).

liufengyun · 2020-12-23T23:02:02Z

@michelou I think it's valuable to have a PDF version and make it available on the dotty website.

michelou · 2020-12-24T08:31:21Z

@michelou I think it's valuable to have a PDF version and make it available on the dotty website.

@liufengyun I suggest we discuss the details per email.

michelou added the area:documentation label Dec 21, 2020

michelou requested a review from liufengyun December 21, 2020 14:49

michelou changed the title ~~[docs/reference] more fixed in Markdown files~~ [docs/reference] more fixes in Markdown files Dec 21, 2020

liufengyun approved these changes Dec 23, 2020

View reviewed changes

rebased with upstream

7b4c9b7

michelou force-pushed the scala3-docs branch from 8800859 to 7b4c9b7 Compare December 23, 2020 21:47

michelou added 2 commits December 23, 2020 22:52

addressed review comment (STL->STLC)

adda267

addressed review comment (removed 'Implementation')

04a6ede

fixed indentation in object Mirror

5d5a066

liufengyun merged commit 626d24a into scala:master Dec 24, 2020

michelou deleted the scala3-docs branch December 24, 2020 08:34

michelou mentioned this pull request Dec 30, 2020

[docs/reference] more fixes in Markdown files #10953

Merged

This was referenced Jan 6, 2021

[docs/reference] more fixes in Markdown files #11016

Merged

[docs/reference] more fixes in Markdown files #11062

Merged

michelou mentioned this pull request Jan 19, 2021

more fixes in Markdown files #11158

Merged

michelou mentioned this pull request Jan 30, 2021

Create a PDF file from Markdown documents (md2pdf) #11257

Draft

michelou mentioned this pull request Feb 20, 2021

more fixes in Markdown files #11480

Merged

michelou mentioned this pull request Mar 13, 2021

more fixes in Markdown files #11726

Merged

michelou mentioned this pull request Dec 30, 2021

more updates to Markdown files #14191

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

[docs/reference] more fixes in Markdown files #10875

[docs/reference] more fixes in Markdown files #10875

michelou commented Dec 21, 2020 •

edited

Loading

liufengyun left a comment

liufengyun Dec 23, 2020

michelou Dec 23, 2020

liufengyun Dec 23, 2020

michelou Dec 23, 2020

liufengyun Dec 23, 2020

michelou Dec 23, 2020

liufengyun Dec 23, 2020

michelou Dec 23, 2020

michelou commented Dec 23, 2020 •

edited

Loading

liufengyun commented Dec 23, 2020

michelou commented Dec 24, 2020

	- the cases for variables, lambdas and applications are as in [STL](https://en.wikipedia.org/wiki/Simply_typed_lambda_calculus).
	- the cases for variables, lambdas and applications are as in [STLC](https://en.wikipedia.org/wiki/Simply_typed_lambda_calculus).

[docs/reference] more fixes in Markdown files #10875

[docs/reference] more fixes in Markdown files #10875

Conversation

michelou commented Dec 21, 2020 • edited Loading

liufengyun left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

michelou commented Dec 23, 2020 • edited Loading

liufengyun commented Dec 23, 2020

michelou commented Dec 24, 2020

michelou commented Dec 21, 2020 •

edited

Loading

michelou commented Dec 23, 2020 •

edited

Loading