converted xml expressions and user defined annotations chapters

1 files changed, 114 insertions, 96 deletions

diff --git a/11-top-level-definitions.md b/11-top-level-definitions.md
index 6d5d17246c..02c7db7bb9 100644
--- a/11-top-level-definitions.md
+++ b/11-top-level-definitions.md
@@ -1,75 +1,81 @@
 Top-Level Definitions
 =====================
 
-\section{Compilation Units}
-
-\syntax\begin{lstlisting}
-  CompilationUnit  ::=  {`package' QualId semi} TopStatSeq
-  TopStatSeq       ::=  TopStat {semi TopStat}
-  TopStat          ::=  {Annotation} {Modifier} TmplDef
-                     |  Import
-                     |  Packaging
-                     |  PackageObject
-                     |
-  QualId           ::=  id {`.' id}
-\end{lstlisting}
+Compilation Units
+-----------------
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar}
+CompilationUnit  ::=  {‘package’ QualId semi} TopStatSeq
+TopStatSeq       ::=  TopStat {semi TopStat}
+TopStat          ::=  {Annotation} {Modifier} TmplDef
+                   |  Import
+                   |  Packaging
+                   |  PackageObject
+                   |
+QualId           ::=  id {‘.’ id}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A compilation unit consists of a sequence of packagings, import
 clauses, and class and object definitions, which may be preceded by a
 package clause.
 
 A compilation unit 
-\begin{lstlisting}
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala}
 package $p_1$;
 $\ldots$
 package $p_n$;
-$\stats$
-\end{lstlisting}
+$\mathit{stats}$
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 starting with one or more package
 clauses is equivalent to a compilation unit consisting of the
 packaging 
-\begin{lstlisting}
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala}
 package $p_1$ { $\ldots$
   package $p_n$ {
-    $\stats$
+    $\mathit{stats}$
   } $\ldots$
 }
-\end{lstlisting}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Implicitly imported into every compilation unit are, in that order :
-the package \code{java.lang}, the package \code{scala}, and the object
-\code{scala.Predef} (\sref{cls:predef}). Members of a later import in
+the package `java.lang`, the package `scala`, and the object
+[`scala.Predef`](#the-predef-object). Members of a later import in
 that order hide members of an earlier import.
 
-\section{Packagings}\label{sec:packagings}
 
-\syntax\begin{lstlisting}
-  Packaging       ::=  `package' QualId [nl] `{' TopStatSeq `}'
-\end{lstlisting}
+Packagings
+----------
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar}
+Packaging       ::=  ‘package’ QualId [nl] ‘{’ TopStatSeq ‘}’
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 A package is a special object which defines a set of member classes,
 objects and packages.  Unlike other objects, packages are not introduced
 by a definition.  Instead, the set of members of a package is determined by
 packagings.
 
-A packaging ~\lstinline@package $p$ { $\ds$ }@~ injects all
-definitions in $\ds$ as members into the package whose qualified name
-is $p$. Members of a package are called {\em top-level} definitions.
-If a definition in $\ds$ is labeled \code{private}, it is
+A packaging `package $p$ { $\mathit{ds}$ }`{.scala} injects all
+definitions in $\mathit{ds}$ as members into the package whose qualified name
+is $p$. Members of a package are called _top-level_ definitions.
+If a definition in $\mathit{ds}$ is labeled `private`{.scala}, it is
 visible only for other members in the package.
 
 Inside the packaging, all members of package $p$ are visible under their
 simple names. However this rule does not extend to members of enclosing
 packages of $p$ that are designated by a prefix of the path $p$.
 
-\example Given the packaging
-\begin{lstlisting}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala}
 package org.net.prj {
   ...
 }
-\end{lstlisting}
-all members of package \lstinline@org.net.prj@ are visible under their
-simple names, but members of packages \code{org} or \code{org.net} require
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+all members of package `org.net.prj` are visible under their
+simple names, but members of packages `org` or `org.net` require
 explicit qualification or imports.
 
 Selections $p$.$m$ from $p$ as well as imports from $p$
@@ -82,17 +88,18 @@ into a special empty package. That package cannot be named and
 therefore cannot be imported. However, members of the empty package
 are visible to each other without qualification.
 
-\section{Package Objects}
-\label{sec:pkg-obj}
 
-\syntax\begin{lstlisting}
-  PackageObject   ::=  `package' `object' ObjectDef
-\end{lstlisting}
+Package Objects
+---------------
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar}
+PackageObject   ::=  ‘package’ ‘object’ ObjectDef
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-A package object ~\lstinline@package object $p$ extends $t$@~ adds the
+A package object `package object $p$ extends $t$` adds the
 members of template $t$ to the package $p$. There can be only one
 package object per package. The standard naming convention is to place
-the definition above in a file named \lstinline@package.scala@ that's
+the definition above in a file named `package.scala` that's
 located in the directory corresponding to package $p$.
 
 The package object should not define a member with the same name as
@@ -101,77 +108,88 @@ there is a name conflict, the behavior of the program is currently
 undefined. It is expected that this restriction will be lifted in a
 future version of Scala.
 
-\section{Package References}
 
-\syntax\begin{lstlisting}
-  QualId           ::=  id {`.' id}
-\end{lstlisting}
+Package References
+------------------
+
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.grammar}
+QualId           ::=  id {‘.’ id}
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
 A reference to a package takes the form of a qualified identifier.
 Like all other references, package references are relative. That is, 
 a package reference starting in a name $p$ will be looked up in the
 closest enclosing scope that defines a member named $p$.
 
-The special predefined name \lstinline@_root_@  refers to the
+The special predefined name `_root_` refers to the
 outermost root package which contains all top-level packages.  
 
-\example\label{ex:package-ids}
-Consider the following program:
-\begin{lstlisting}
-package b {
-  class B 
-}
+(@package-ids) Consider the following program:
 
-package a.b {
-  class A {
-    val x = new _root_.b.B
-  }
-}
-\end{lstlisting}  
-Here, the reference \code{_root_.b.B} refers to class \code{B} in the
-toplevel package \code{b}. If the \code{_root_} prefix had been
-omitted, the name \code{b} would instead resolve to the package
-\code{a.b}, and, provided that package does not also
-contain a class \code{B}, a compiler-time error would result.
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala}
+    package b {
+      class B 
+    }
+
+    package a.b {
+      class A {
+        val x = new _root_.b.B
+      }
+    }
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-\section{Programs}
+    Here, the reference `_root_.b.B` refers to class `B` in the
+    toplevel package `b`. If the `_root_` prefix had been
+    omitted, the name `b` would instead resolve to the package
+    `a.b`, and, provided that package does not also
+    contain a class `B`, a compiler-time error would result.
 
-A {\em program} is a top-level object that has a member method
-\code{main} of type ~\lstinline@(Array[String])Unit@. Programs can be
+
+Programs
+--------
+
+A _program_ is a top-level object that has a member method
+_main_ of type `(Array[String])Unit`. Programs can be
 executed from a command shell. The program's command arguments are are
-passed to the \code{main} method as a parameter of type
-\code{Array[String]}.
+passed to the `main` method as a parameter of type
+`Array[String]`.
 
-The \code{main} method of a program can be directly defined in the
+The `main` method of a program can be directly defined in the
 object, or it can be inherited. The scala library defines a class
-\code{scala.Application} that defines an empty inherited \code{main} method.
+`scala.Application` that defines an empty inherited `main` method.
 An objects $m$ inheriting from this class is thus a program, 
 which executes the initializaton code of the object $m$.
 
-\example The following example will create a hello world program by defining
-a method \code{main} in module \code{test.HelloWorld}.
-\begin{lstlisting}
-package test
-object HelloWord {
-  def main(args: Array[String]) { println("hello world") }
-}
-\end{lstlisting}
-
-This program can be started by the command
-\begin{lstlisting}
-scala test.HelloWorld
-\end{lstlisting}
-In a Java environment, the command
-\begin{lstlisting}
-java test.HelloWorld
-\end{lstlisting}
-would work as well. 
-
-\code{HelloWorld} can also be defined without a \code{main} method 
-by inheriting from \code{Application} instead:
-\begin{lstlisting}
-package test 
-object HelloWord extends Application {
-  println("hello world")
-}
-\end{lstlisting}
+(@) The following example will create a hello world program by defining
+    a method `main` in module `test.HelloWorld`.
+
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala}
+    package test
+    object HelloWord {
+      def main(args: Array[String]) { println("hello world") }
+    }
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    This program can be started by the command
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    scala test.HelloWorld
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    In a Java environment, the command
+
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+    java test.HelloWorld
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+    would work as well. 
+
+    `HelloWorld` can also be defined without a `main` method 
+    by inheriting from `Application` instead:
+
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ {.scala}
+    package test 
+    object HelloWord extends Application {
+      println("hello world")
+    }
+    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~