Fix documentation about indentation syntax

The fixes omit documenting `:` in extension blocks. These will be disabled
in a separate commit.

There are two reasons for omitted in `:` in extensions:

 - they are not needed, and there should be one way to do things
 - they are confusing since everywhere else a `:` at eol starts a
   new scope, but here it doesn't.

Author: odersky

docs/docs/internals/syntax.md

@@ -83,7 +83,7 @@ comment          ::=  ‘/*’ “any sequence of characters; nested comments ar
 
 nl               ::=  “new line character”
 semi             ::=  ‘;’ |  nl {nl}
-colonEol         ::=  ": at end of line that can start a tenmplate body"
+colonEol         ::=  ": at end of line that can start a template body"
 ```
 
 ## Keywords
@@ -151,7 +151,7 @@ FunParamClause    ::=  ‘(’ TypedFunParam {‘,’ TypedFunParam } ‘)’
 TypedFunParam     ::=  id ‘:’ Type
 MatchType         ::=  InfixType `match` ‘{’ TypeCaseClauses ‘}’
 InfixType         ::=  RefinedType {id [nl] RefinedType}                        InfixOp(t1, op, t2)
-RefinedType       ::=  WithType {[nl | colonEol] Refinement}                    RefinedTypeTree(t, ds)
+RefinedType       ::=  WithType {[nl] Refinement}                               RefinedTypeTree(t, ds)
 WithType          ::=  AnnotType {‘with’ AnnotType}                             (deprecated)
 AnnotType         ::=  SimpleType {Annotation}                                  Annotated(t, annot)
 
@@ -224,8 +224,9 @@ SimpleExpr        ::=  SimpleRef
                     |  ‘$’ ‘{’ Block ‘}’
                     |  Quoted
                     |  quoteId     // only inside splices
-                    |  ‘new’ ConstrApp {‘with’ ConstrApp} [TemplateBody]        New(constr | templ)
-                    |  ‘new’ TemplateBody
+                    |  ‘new’ ConstrApp {‘with’ ConstrApp}                       New(constr | templ)
+                       [[colonEol] TemplateBody
+                    |  ‘new’ [colonEol] TemplateBody
                     |  ‘(’ ExprsInParens ‘)’                                    Parens(exprs)
                     |  SimpleExpr ‘.’ id                                        Select(expr, id)
                     |  SimpleExpr ‘.’ MatchClause
@@ -397,23 +398,22 @@ ClassDef          ::=  id ClassConstr [Template]
 ClassConstr       ::=  [ClsTypeParamClause] [ConstrMods] ClsParamClauses        with DefDef(_, <init>, Nil, vparamss, EmptyTree, EmptyTree) as first stat
 ConstrMods        ::=  {Annotation} [AccessModifier]
 ObjectDef         ::=  id [Template]                                            ModuleDef(mods, name, template)  // no constructor
-EnumDef           ::=  id ClassConstr InheritClauses EnumBody                   EnumDef(mods, name, tparams, template)
+EnumDef           ::=  id ClassConstr InheritClauses [colonEol] EnumBody
 GivenDef          ::=  [GivenSig] (Type [‘=’ Expr] | StructuralInstance)
-GivenSig          ::=  [id] [DefTypeParamClause] {UsingParamClause} ‘:’       -- one of `id`, `DefParamClause`, `UsingParamClause` must be present
+GivenSig          ::=  [id] [DefTypeParamClause] {UsingParamClause} ‘:’         -- one of `id`, `DefParamClause`, `UsingParamClause` must be present
 Extension         ::=  ‘extension’ [DefTypeParamClause] ‘(’ DefParam ‘)’
                        {UsingParamClause}] ExtMethods
 ExtMethods        ::=  ExtMethod | [nl] ‘{’ ExtMethod {semi ExtMethod ‘}’
 ExtMethod         ::=  {Annotation [nl]} {Modifier} ‘def’ DefDef
-Template          ::=  InheritClauses [TemplateBody]                            Template(constr, parents, self, stats)
+Template          ::=  InheritClauses [colonEol] [TemplateBody]                 Template(constr, parents, self, stats)
 InheritClauses    ::=  [‘extends’ ConstrApps] [‘derives’ QualId {‘,’ QualId}]
 ConstrApps        ::=  ConstrApp {(‘,’ | ‘with’) ConstrApp}
 ConstrApp         ::=  SimpleType1 {Annotation} {ParArgumentExprs}              Apply(tp, args)
 ConstrExpr        ::=  SelfInvocation
                     |  ‘{’ SelfInvocation {semi BlockStat} ‘}’
 SelfInvocation    ::=  ‘this’ ArgumentExprs {ArgumentExprs}
 
-TemplateBody      ::=  [nl | colonEol]
-                       ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’      (self, stats)
+TemplateBody      ::=  [nl] ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’
 TemplateStat      ::=  Import
                     |  Export
                     |  {Annotation [nl]} {Modifier} Def
@@ -425,8 +425,7 @@ TemplateStat      ::=  Import
 SelfType          ::=  id [‘:’ InfixType] ‘=>’                                  ValDef(_, name, tpt, _)
                     |  ‘this’ ‘:’ InfixType ‘=>’
 
-EnumBody          ::=  [nl | colonEol]
-                       ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
+EnumBody          ::=  [nl] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
 EnumStat          ::=  TemplateStat
                     |  {Annotation [nl]} {Modifier} EnumCase
 EnumCase          ::=  ‘case’ (id ClassConstr [‘extends’ ConstrApps]] | ids)

docs/docs/reference/other-new-features/indentation.md

@@ -58,8 +58,8 @@ There are two rules:
 
     An indentation region can start
 
-     - after the condition of an `if-else`, or
      - after the leading parameters of an `extension`, or
+     - after a `with` in a given instance, or
      - after a ": at end of line" token (see below)
      - after one of the following tokens:
 
@@ -93,7 +93,7 @@ There are two rules:
 It is an error if the indentation width of the token following an `<outdent>` does not match the indentation of some previous line in the enclosing indentation region. For instance, the following would be rejected.
 
 ```scala
-if x < 0
+if x < 0 then
     -x
   else   // error: `else` does not align correctly
      x
@@ -104,14 +104,14 @@ at the toplevel, inside braces `{...}`, but not inside parentheses `(...)`, patt
 
 ### Optional Braces Around Template Bodies
 
-The Scala grammar uses the term _template body_ for the definitions of a class, trait, object or given instance that are normally enclosed in braces. The braces around a template body can also be omitted by means of the following rule
+The Scala grammar uses the term _template body_ for the definitions of a class, trait, or object that are normally enclosed in braces. The braces around a template body can also be omitted by means of the following rule
 
 If at the point where a template body can start there is a `:` that occurs at the end
 of a line, and that is followed by at least one indented statement, the recognized
 token is changed from ":" to ": at end of line". The latter token is one of the tokens
 that can start an indentation region. The Scala grammar is changed so an optional ": at end of line" is allowed in front of a template body.
 
-Analogous rules apply for enum bodies, type refinements, definitions in an instance creation expressions, and local packages containing nested definitions.
+Analogous rules apply for enum bodies and local packages containing nested definitions.
 
 With these new rules, the following constructs are all valid:
 
@@ -128,15 +128,6 @@ object O:
 enum Color:
   case Red, Green, Blue
 
-type T = A:
-  def f: Int
-
-given [T](using Ord[T]): Ord[List[T]] with
-  def compare(x: List[T], y: List[T]) = ???
-
-extension (xs: List[Int])
-  def second: Int = xs.tail.head
-
 new A:
   def f = 3
 
@@ -145,14 +136,15 @@ package p:
 package q:
   def b = 2
 ```
+In each case, the `:` at the end of line can be replaced without change of meaning by a pair of braces that enclose the following indented definition(s).
 
 The syntax changes allowing this are as follows:
 
 ```
-TemplateBody ::=  [colonEol] ‘{’ [SelfType] TemplateStat {semi TemplateStat} ‘}’
-EnumBody     ::=  [colonEol] ‘{’ [SelfType] EnumStat {semi EnumStat} ‘}’
-Packaging    ::=  ‘package’ QualId [colonEol] ‘{’ TopStatSeq ‘}’
-RefinedType  ::=  AnnotType {[colonEol] Refinement}
+Template    ::=  InheritClauses [colonEol] [TemplateBody]
+EnumDef     ::=  id ClassConstr InheritClauses [colonEol] EnumBody
+Packaging   ::=  ‘package’ QualId [nl | colonEol] ‘{’ TopStatSeq ‘}’
+SimpleExpr  ::=  ‘new’ ConstrApp {‘with’ ConstrApp} [[colonEol] TemplateBody]
 ```
 
 Here, `colonEol` stands for ": at end of line", as described above.