Docs cleanups

 - Fix outdated syntax
 - Switch to indentation syntax almost everywhere
 - Explain soft keywords in detail
 - Switch to 3 space indent

The switch to 3 space is an experiment, we can undo it separately if we don;t like it.

Author: odersky

docs/docs/internals/explicit-nulls.md

@@ -76,10 +76,9 @@ Within `Types.scala`, we defined some extractors to work with nullable unions:
 `OrNull` and `OrUncheckedNull`.
 
 ```scala
-(tp: Type) match {
-  case OrNull(tp1) => // if tp is a nullable union: tp1 | Null
-  case _ => // otherwise
-}
+(tp: Type) match
+   case OrNull(tp1) => // if tp is a nullable union: tp1 | Null
+   case _ => // otherwise
 ```
 
 This extractor will call utility methods in `NullOpsDecorator.scala`. All of these

docs/docs/internals/syntax.md

@@ -104,10 +104,9 @@ yield
 ### Soft keywords
 
 ```
-as  derives  end  extension  inline  opaque  open  transparent  using
-*  +  -
+derives   end   extension   inline   infix   opaque   oapque   open
+transparent   using   |   *   +   -
 ```
-
 ## Context-free Syntax
 
 The context-free syntax of Scala is given by the following EBNF

docs/docs/reference/changed-features/compiler-plugins.md

@@ -62,33 +62,30 @@ import dotty.tools.dotc.core.Symbols._
 import dotty.tools.dotc.plugins.{PluginPhase, StandardPlugin}
 import dotty.tools.dotc.transform.{Pickler, Staging}
 
-class DivideZero extends StandardPlugin {
-  val name: String = "divideZero"
-  override val description: String = "divide zero check"
+class DivideZero extends StandardPlugin:
+   val name: String = "divideZero"
+   override val description: String = "divide zero check"
 
-  def init(options: List[String]): List[PluginPhase] =
-    (new DivideZeroPhase) :: Nil
-}
+   def init(options: List[String]): List[PluginPhase] =
+      (new DivideZeroPhase) :: Nil
 
-class DivideZeroPhase extends PluginPhase {
-  import tpd._
+class DivideZeroPhase extends PluginPhase:
+   import tpd._
 
-  val phaseName = "divideZero"
+   val phaseName = "divideZero"
 
-  override val runsAfter = Set(Pickler.name)
-  override val runsBefore = Set(Staging.name)
+   override val runsAfter = Set(Pickler.name)
+   override val runsBefore = Set(Staging.name)
 
-  override def transformApply(tree: Apply)(implicit ctx: Context): Tree = {
-    tree match {
+   override def transformApply(tree: Apply)(implicit ctx: Context): Tree =
+      tree match
       case Apply(Select(rcvr, nme.DIV), List(Literal(Constant(0))))
           if rcvr.tpe <:< defn.IntType =>
         report.error("dividing by zero", tree.pos)
       case _ =>
         ()
-    }
-    tree
-  }
-}
+      tree
+end DivideZeroPhase
 ```
 
 The plugin main class (`DivideZero`) must extend the trait `StandardPlugin`
@@ -111,13 +108,13 @@ import dotty.tools.dotc.core.Contexts.Context
 import dotty.tools.dotc.core.Phases.Phase
 import dotty.tools.dotc.plugins.ResearchPlugin
 
-class DummyResearchPlugin extends ResearchPlugin {
-  val name: String = "dummy"
-  override val description: String = "dummy research plugin"
+class DummyResearchPlugin extends ResearchPlugin:
+   val name: String = "dummy"
+   override val description: String = "dummy research plugin"
 
-  def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] =
-    phases
-}
+   def init(options: List[String], phases: List[List[Phase]])(implicit ctx: Context): List[List[Phase]] =
+      phases
+end DummyResearchPlugin
 ```
 
 A research plugin must extend the trait `ResearchPlugin`  and implement the

docs/docs/reference/changed-features/implicit-conversions-spec.md

@@ -17,7 +17,7 @@ The standard library defines an abstract class `Conversion`:
 package scala
 @java.lang.FunctionalInterface
 abstract class Conversion[-T, +U] extends Function1[T, U]:
-  def apply(x: T): U
+   def apply(x: T): U
 ```
 
 Function literals are automatically converted to `Conversion` values.

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

@@ -34,7 +34,7 @@ method that expects a `java.lang.Integer`
 ```scala
 import scala.language.implicitConversions
 implicit def int2Integer(x: Int): java.lang.Integer =
-  x.asInstanceOf[java.lang.Integer]
+   x.asInstanceOf[java.lang.Integer]
 ```
 
 The second example shows how to use `Conversion` to define an
@@ -44,12 +44,11 @@ types:
 ```scala
 import scala.language.implicitConversions
 implicit def ordT[T, S](
-  implicit conv: Conversion[T, S],
-           ordS: Ordering[S]
-  ): Ordering[T] = {
-  // `ordS` compares values of type `S`, but we can convert from `T` to `S`
-  (x: T, y: T) => ordS.compare(x, y)
-}
+   implicit conv: Conversion[T, S],
+            ordS: Ordering[S]
+  ): Ordering[T] =
+   // `ordS` compares values of type `S`, but we can convert from `T` to `S`
+   (x: T, y: T) => ordS.compare(x, y)
 
 class A(val x: Int) // The type for which we want an `Ordering`
 

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

@@ -11,18 +11,18 @@ affect implicits on the language level.
 must be explicitly declared. Excepted are only values in local blocks
 where the type may still be inferred:
 ```scala
-   class C {
+  class C {
 
-   val ctx: Context = ...        // ok
+    val ctx: Context = ...        // ok
 
-   /*!*/ implicit val x = ...    // error: type must be given explicitly
+    /*!*/ implicit val x = ...    // error: type must be given explicitly
 
-   /*!*/ implicit def y = ...    // error: type must be given explicitly
-
-   val y = {
-     implicit val ctx = this.ctx // ok
-     ...
-   }
+    /*!*/ implicit def y = ...    // error: type must be given explicitly
+  }
+  val y = {
+    implicit val ctx = this.ctx // ok
+    ...
+  }
 ```
 **2.** Nesting is now taken into account for selecting an implicit. Consider for instance the following scenario:
 ```scala
@@ -41,12 +41,12 @@ no longer applies.
 **3.** Package prefixes no longer contribute to the implicit search scope of a type. Example:
 ```scala
   package p
-  given a: A = A()
 
-  object o {
+  given a: A = A()
+  
+  object o:
     given b: B = B()
     type C
-  }
 ```
 Both `a` and `b` are visible as implicits at the point of the definition
 of `type C`. However, a reference to `p.o.C` outside of package `p` will

docs/docs/reference/changed-features/main-functions.md

@@ -7,22 +7,19 @@ Scala 3 offers a new way to define programs that can be invoked from the command
 A `@main` annotation on a method turns this method into an executable program.
 Example:
 ```scala
-@main def happyBirthday(age: Int, name: String, others: String*) = {
-  val suffix =
-    (age % 100) match {
+@main def happyBirthday(age: Int, name: String, others: String*) =
+   val suffix =
+      age % 100 match
       case 11 | 12 | 13 => "th"
       case _ =>
-        (age % 10) match {
-          case 1 => "st"
-          case 2 => "nd"
-          case 3 => "rd"
-          case _ => "th"
-        }
-    }
-  val bldr = new StringBuilder(s"Happy $age$suffix birthday, $name")
-  for other <- others do bldr.append(" and ").append(other)
-  bldr.toString
-}
+         age % 10 match
+         case 1 => "st"
+         case 2 => "nd"
+         case 3 => "rd"
+         case _ => "th"
+   val bldr = new StringBuilder(s"Happy $age$suffix birthday, $name")
+   for other <- others do bldr.append(" and ").append(other)
+   bldr.toString
 ```
 This would generate a main program `happyBirthday` that could be called like this
 ```
@@ -59,29 +56,26 @@ The Scala compiler generates a program from a `@main` method `f` as follows:
 
 For instance, the `happyBirthDay` method above would generate additional code equivalent to the following class:
 ```scala
-final class happyBirthday {
-  import scala.util.{CommandLineParser => CLP}
-  <static> def main(args: Array[String]): Unit =
-    try
-      happyBirthday(
-          CLP.parseArgument[Int](args, 0),
-          CLP.parseArgument[String](args, 1),
-          CLP.parseRemainingArguments[String](args, 2))
-    catch {
-      case error: CLP.ParseError => CLP.showError(error)
-    }
-}
+final class happyBirthday:
+   import scala.util.{CommandLineParser => CLP}
+   <static> def main(args: Array[String]): Unit =
+      try
+         happyBirthday(
+            CLP.parseArgument[Int](args, 0),
+            CLP.parseArgument[String](args, 1),
+            CLP.parseRemainingArguments[String](args, 2))
+      catch
+         case error: CLP.ParseError => CLP.showError(error)
 ```
 **Note**: The `<static>` modifier above expresses that the `main` method is generated
 as a static method of class `happyBirthDay`. It is not available for user programs in Scala. Regular "static" members are generated in Scala using objects instead.
 
 `@main` methods are the recommended scheme to generate programs that can be invoked from the command line in Scala 3. They replace the previous scheme to write program as objects with a special `App` parent class. In Scala 2, `happyBirthday` could be written also like this:
 
 ```scala
-object happyBirthday extends App {
-  // needs by-hand parsing of arguments vector
-  ...
-}
+object happyBirthday extends App:
+   // needs by-hand parsing of arguments vector
+   ...
 ```
 
 The previous functionality of `App`, which relied on the "magic" `DelayedInit` trait, is no longer available. `App` still exists in limited form for now, but it does not support command line arguments and will be deprecated in the future. If programs need to cross-build