[docs/reference] fixed many issues in MarkDown files #10767

michelou · 2020-12-12T17:32:14Z

Fixes mostly formatting issues found in MarkDown files in docs/reference/, e.g,

added missing spaces, misspellings, etc.
added missing backquotes for annotations, compiler options, keywords, single characters, etc.
added missing triple backquotes at the end of some code examples
reduced line width in several code examples (to avoid text overflow in the right margin)
updated URL (2.12 -> 2.13) in SLS references
corrected several internal links (use extension .md instead of .html, e.g. ./enums.html becomes ./enums.md)
added missing empty line before code examples (eg. metaprogramming/inline.md)
added double quotes around the string value of title variable (in MarkDown header) if value contains a colon (:)

This change needs to be validated:

updated internal link "../../internals/syntax.md" to "../syntax.md"

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

liufengyun

Thanks @michelou 👍

updated internal link "../../internals/syntax.md" to "../syntax.md"

The syntax file is duplicated in the reference folder in e5be3e7. Thus I think the change is fine.

A few comments, otherwise, LGTM

liufengyun · 2020-12-12T17:59:28Z

docs/docs/reference/changed-features/implicit-resolution.md

@@ -122,7 +122,8 @@ most (but not all) divergence errors in Scala 2 would terminate the implicit sea
  def buzz(y: A) = ???
  buzz(1)   // error: ambiguous
 ```
-**7.** The rule for picking a _most specific_ alternative among a set of overloaded or implicit alternatives is refined to take context parameters into account. All else being equal, an alternative that takes some context parameters is taken to be less specific than an alternative that takes none. If both alternatives take context parameters, we try to choose between them as if they were methods with regular parameters. The following paragraph in the SLS is affected by this change:
+**7.** The rule for picking a _most specific_ alternative among a set of overloaded or implicit alternatives is refined to take context parameters into account. All else being equal, an alternative that takes some context parameters is taken to be less specific than an alternative that takes none. If both alternatives take context parameters, we try to choose between them as if they were methods with regular parameters. The following paragraph in the [SLS §
+6.26.3](https://scala-lang.org/files/archive/spec/2.13/06-expressions.html#overloading-resolution) is affected by this change:


Is the new line inside the brackets introduced by accident?

By accident. I'll remove the new line.

liufengyun · 2020-12-12T18:01:11Z

docs/docs/reference/changed-features/overload-resolution.md

@@ -33,7 +33,8 @@ g(2)(3)(4)     // ok
 g(2)(3)("")    // ok
 ```

-To make this work, the rules for overloading resolution in section 6.23.3 of the SLS are augmented
+To make this work, the rules for overloading resolution in [SLS §
+6.26.3](https://www.scala-lang.org/files/archive/spec/2.13/06-expressions.html#overloading-resolution) are augmented


Same question as above?

liufengyun · 2020-12-12T18:01:21Z

docs/docs/reference/changed-features/overload-resolution.md

@@ -57,7 +58,8 @@ def f(x: String, f2: String => String) = f2(x)
 f("a", _.toUpperCase)
 f(2, _ * 2)
 ```
-To make this work, the rules for overloading resolution in section 6.23.3 of the SLS are modified
+To make this work, the rules for overloading resolution in [SLS §
+6.26.3](https://www.scala-lang.org/files/archive/spec/2.13/06-expressions.html#overloading-resolution) are modified


Same question as above?

liufengyun · 2020-12-12T18:03:51Z

docs/docs/reference/contextual/motivation.md

@@ -49,7 +49,7 @@ The following pages introduce a redesign of contextual abstractions in Scala. Th

 1. [Given Instances](./givens.md) are a new way to define basic terms that can be synthesized.  They replace implicit definitions. The core principle of the proposal is that, rather than mixing the `implicit` modifier with a large number of features, we have a single way to define terms that can be synthesized for types.

- 2. [Using Clauses](./using-clauses.md) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition.
+ 2. [`using` Clauses](./using-clauses.md) are a new syntax for implicit _parameters_ and their _arguments_. It unambiguously aligns parameters and arguments, solving a number of language warts. It also allows us to have several `using` clauses in a definition.


This change will make it inconsistent to the first item.

Ok, I'll revert that change.

liufengyun · 2020-12-12T18:09:04Z

docs/docs/reference/metaprogramming/macros.md

@@ -683,21 +646,20 @@ private def sumExpr(argsExpr: Expr[Seq[Int]])(using Quotes): Expr[Int] = argsExp
    // argValues is of type Seq[Int]
    Expr(argValues.sum) // precompute result of sum
  case Varargs(argExprs) => // argExprs is of type Seq[Expr[Int]]
-    val staticSum: Int = argExprs.map(_.value.getOrElse(0)).sum
+    val staticSum: Int = argExprs.map(_.value.getOrElse(0))


Accidental removal of .sum?

I've found two other diffs.. I need to update my file.

@liufengyun metaprogramming/macros.md needs closer revue. Otherwise looks good.

liufengyun · 2020-12-12T21:29:39Z

docs/docs/reference/metaprogramming/macros.md

@@ -602,7 +566,6 @@ sum
 ```

 Finally cleanups and dead code elimination:
-


In this file, the blank lines before and after code blocks are removed in some cases. Is this by accident?

From my experience it doesn't make any difference with top-level paragraphs, but it does with indented text (eg. list items). I'll revert the change.

liufengyun

Thanks @michelou 🎉

SethTisue · 2020-12-14T22:03:39Z

The result of the above changes can be viewed in the PDF document scala3_reference.pdf (704 Kb) generated with Pandoc 2.11.

@michelou nice. is that officially hosted anywhere?

michelou · 2020-12-14T23:09:36Z

@SethTisue No (at least not for now although the provided link will stay as I already have more changes to submit).

I generate the Scala 3 reference as PDF document because it's much easier to read and to review but :

Martin & al. are the authors of the document (title page)
I've freely ordered the chapters/sections; somebody from the Scala team should define/validate the document structure (eg. how to include chapter "Details").
A few pieces are still missing in the generated PDF, eg. the inclusion of a PNG image (class hierarchy).

PS. Tech recipe: addition of two files scala3_reference.md (structure) and scala3_reference.yaml (config) and substitution of internal refs with anchors (e.g. ./enums.md becomes #enums).

SethTisue · 2020-12-14T23:17:10Z

cool, thanks for explaining. I think it would be great to make a PDF version more openly available, eventually — I've totally bookmarked this one and expect I'll refer to it often. (in Scala 2 land, scala/bug#10218 was a very popular ask for a long time)

[docs/reference] fixed many issues in .md files

f337a8d

michelou added the area:documentation label Dec 12, 2020

michelou requested review from liufengyun and odersky December 12, 2020 17:32

liufengyun approved these changes Dec 12, 2020

View reviewed changes

addressed comments

35f7f97

liufengyun reviewed Dec 12, 2020

View reviewed changes

addressed comments

6fbc7e5

liufengyun approved these changes Dec 13, 2020

View reviewed changes

liufengyun merged commit 3a7a6ae into scala:master Dec 13, 2020

michelou deleted the scala3-docs branch December 13, 2020 16:10

SethTisue mentioned this pull request Dec 14, 2020

Somehow make the spec searchable (e.g. by generating PDF version) scala/bug#10218

Closed

This was referenced Dec 16, 2020

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

Merged

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

Merged

Erased terms doc not exposed #10847

Closed

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

Merged

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] fixed many issues in MarkDown files #10767

[docs/reference] fixed many issues in MarkDown files #10767

michelou commented Dec 12, 2020 •

edited

Loading

liufengyun left a comment

liufengyun Dec 12, 2020

michelou Dec 12, 2020

liufengyun Dec 12, 2020

liufengyun Dec 12, 2020

liufengyun Dec 12, 2020

michelou Dec 12, 2020

liufengyun Dec 12, 2020

michelou Dec 12, 2020

michelou Dec 12, 2020

liufengyun Dec 12, 2020

michelou Dec 12, 2020

liufengyun left a comment

SethTisue commented Dec 14, 2020

michelou commented Dec 14, 2020

SethTisue commented Dec 14, 2020 •

edited

Loading

		@@ -602,7 +566,6 @@ sum
		```

		Finally cleanups and dead code elimination:

[docs/reference] fixed many issues in MarkDown files #10767

[docs/reference] fixed many issues in MarkDown files #10767

Conversation

michelou commented Dec 12, 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

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

liufengyun left a comment

Choose a reason for hiding this comment

SethTisue commented Dec 14, 2020

michelou commented Dec 14, 2020

SethTisue commented Dec 14, 2020 • edited Loading

michelou commented Dec 12, 2020 •

edited

Loading

SethTisue commented Dec 14, 2020 •

edited

Loading