From 4501d348e89b7287a4a4d9b27534ff620d1bf19f Mon Sep 17 00:00:00 2001
From: Rob Pike <r@golang.org>
Date: Thu, 19 Feb 2009 17:31:36 -0800
Subject: [PATCH] Fix most HTML errors. Cut introduction. Start rewrite.

R=gri
DELTA=201  (20 added, 118 deleted, 63 changed)
OCL=25226
CL=25229
---
 doc/go_spec.html | 233 ++++++++++++++---------------------------------
 1 file changed, 67 insertions(+), 166 deletions(-)

diff --git a/doc/go_spec.html b/doc/go_spec.html
index 6271666ac8..4f874350bd 100644
--- a/doc/go_spec.html
+++ b/doc/go_spec.html
@@ -145,17 +145,11 @@ Timeline (9/5/08):
 
 
 <h2>Contents</h2>
+<p>
+TODO: This should be autogenerated but that will take work to make h3s appear in this list
+</p>
 <ul>
 <li>Introduction
-	<ul>
-	<li>Guiding principles
-	<li>Program structure
-	<li>Modularity, identifiers and scopes
-	<li>Typing, polymorphism, and object-orientation
-	<li>Pointers and garbage collection
-	<li>Values and references
-	<li>Multithreading and channels
-	</ul>
 	
 <li>Notation
 
@@ -288,171 +282,68 @@ Timeline (9/5/08):
 
 <h2>Introduction</h2>
 
-Go is a new systems programming language intended as an alternative to C++ at
-Google. Its main purpose is to provide a productive and efficient programming
-environment for compiled programs such as servers and distributed systems.
-
-
-<h3>Guiding principles</h3>
-
-The design of Go is motivated by the following goals (in no particular order):
-<p>
-<ul>
-	<li>very fast compilation, instantaneous incremental compilation
-	<li>strongly typed
-	<li>procedural
-	<li>concise syntax avoiding repetition
-	<li>few, orthogonal, and general concepts
-	<li>support for threading and interprocess communication
-	<li>garbage collection
-	<li>container library written in Go
-	<li>efficient code, comparable to other compiled languages
-</ul>
-
-<h3>Program structure</h3>
-
-A Go program consists of a number of ``packages''.
-<p>
-A package is built from one or more source files, each of which consists
-of a package specifier followed by declarations. There are no statements at
-the top level of a file.
-<p>
-By convention, the package called "main" is the starting point for execution.
-It contains a function, also called "main", that is the first function invoked
-by the run time system after initialization (if a source file within the program
-contains a function "init()", that function will be executed before "main.main()"
-is called).
-<p>
-Source files can be compiled separately (without the source code of packages
-they depend on), but not independently (the compiler does check dependencies
-by consulting the symbol information in compiled packages).
-
-
-<h3>Modularity, identifiers and scopes</h3>
-
-A package is a collection of import, constant, type, variable, and function
-declarations. Each declaration binds an ``identifier'' with a program entity
-(such as a variable).
-<p>
-In particular, all identifiers occurring in a package are either declared
-explicitly within the package, arise from an import declaration, or belong
-to a small set of predeclared identifiers (such as "string").
 <p>
-Scoping follows the usual rules: The scope of an identifier declared within
-a ``block'' generally extends from the declaration of the identifier to the
-end of the block. An identifier shadows identifiers with the same name declared
-in outer scopes. Within a scope, an identifier can be declared at most once.
-<p>
-Identifiers may be ``internal'' or ``exported''. Internal identifiers are only
-accessible to files belonging to the package in which they are declared.
-External identifiers are accessible to other packages.
-
+This is a reference manual for the Go programming language. For
+more information and other documents, see <a
+href="/">the Go home page</a>.
+</p>
 
-<h3>Typing, polymorphism, and object-orientation</h3>
-
-Go programs are strongly typed. Certain variables may be polymorphic.
-The language provides mechanisms to make use of such polymorphic variables
-type-safe.
-<p>
-Object-oriented programming is supported by interface types.
-Different interface types are independent of each
-other and no explicit hierarchy is required (such as single or
-multiple inheritance explicitly specified through respective type
-declarations).  Interface types only define a set of methods that a
-corresponding implementation must provide.  Thus interface and
-implementation are strictly separated.
-<p>
-An interface is implemented by associating methods with types. If a type
-defines all methods of an interface, it implements that interface and thus
-can be used where that interface is required. Unless used through a variable
-of interface type, methods can always be statically bound (they are not
-``virtual''), and invoking them incurs no extra run-time overhead compared
-to ordinary functions.
-<p>
-Go has no explicit notion of classes, sub-classes, or inheritance.
-These concepts are trivially modeled in Go through the use of
-functions, structures, embedding of types, associated methods, and interfaces.
 <p>
-Go has no explicit notion of type parameters or templates.  Instead,
-containers (such as stacks, lists, etc.) are implemented through the
-use of abstract operations on interface types.
+Go is a general-purpose language designed with systems programming
+in mind. It is strongly typed and garbage-collected, and has explicit
+support for concurrent programming.  Programs are constructed from
+<i>packages</i>, whose properties allow efficient management of
+dependencies. The existing implementations use a traditional
+compile/link model to generate executable binaries.
+</p>
 
-
-<h3>Pointers and garbage collection</h3>
-
-Variables may be allocated automatically (when entering the scope of
-the variable) or explicitly on the heap.  Pointers are used to refer
-to heap-allocated variables.  Pointers may also be used to point to
-any other variable; such a pointer is obtained by "taking the
-address" of that variable.  Variables are automatically reclaimed when
-they are no longer accessible.  There is no pointer arithmetic in Go.
-
-
-<h3>Values and references</h3>
-
-Most data types have value semantics, but their contents may be accessed
-through different pointers referring to the same object. However, some
-data types have reference semantics to facilitate common usage patterns
-and implementation.
 <p>
-For example, when calling a function with a struct, the struct is passed
-by value, possibly by making a copy. To pass a reference, one must explicitly
-pass a pointer to the struct. On the other hand, when calling a function with
-a map, a reference to the map is passed implicitly without the need to pass a
-pointer to the map; thus the map contents are not copied when a map is assigned
-to a variable.
-
-
-<h3>Multithreading and channels</h3>
-
-Go supports multithreaded programming directly. A function may
-be invoked as a parallel thread of execution.  Communication and
-synchronization are provided through channels and their associated
-language support.
-
-<hr>
+The grammar is compact and regular, allowing for easy analysis by
+automatic tools such as integrated development environments.
+</p>
 
 <h2>Notation</h2>
-
+<p>
 The syntax is specified using Extended Backus-Naur Form (EBNF):
+</p>
 
 <pre>
-Production = production_name "=" Expression .
-Expression = Alternative { "|" Alternative } .
+Production  = production_name "=" Expression .
+Expression  = Alternative { "|" Alternative } .
 Alternative = Term { Term } .
-Term = production_name | token [ "..." token ] | Group | Option | Repetition .
-Group = "(" Expression ")" .
-Option = "[" Expression ")" .
-Repetition = "{" Expression "}" .
+Term        = production_name | token [ "..." token ] | Group | Option | Repetition .
+Group       = "(" Expression ")" .
+Option      = "[" Expression ")" .
+Repetition  = "{" Expression "}" .
 </pre>
 
-Productions are expressions constructed from terms and the following operators:
-
+<p>
+Productions are expressions constructed from terms and the following
+operators, in increasing precedence:
+</p>
 <pre>
-|   separates alternatives (least binding strength)
-()  groups
-[]  specifies an option (0 or 1 times)
-{}  specifies repetition (0 to n times)
+|   alternation
+()  grouping
+[]  option (0 or 1 times)
+{}  repetition (0 to n times)
 </pre>
 
-Lower-case production names are used to identify productions that cannot
-be broken by white space or comments; they are tokens. Other production
-names are in CamelCase.
 <p>
-Tokens (lexical symbols) are enclosed in double quotes '''' (the
-double quote symbol is written as ''"'').
+Lower-case production names are used to identify lexical tokens.
+Non-terminals are in CamelCase. Lexical symbols are enclosed in
+double quotes <tt>""</tt> (the double quote symbol is written as
+<tt>'"'</tt>).
+</p>
+
 <p>
-The form "a ... b" represents the set of characters from "a" through "b" as
-alternatives.
+The form <tt>"a ... b"</tt> represents the set of characters from
+<tt>a</tt> through <tt>b</tt> as alternatives.
+</p>
+
 <p>
 Where possible, recursive productions are used to express evaluation order
-and operator precedence syntactically (for instance for expressions).
-<p>
-A production may be referenced from various places in this document
-but is usually defined close to its first use.  Productions and code
-examples are indented.
-
-<hr>
+and operator precedence syntactically.
+</p>
 
 <h2>Source code representation</h2>
 
@@ -472,8 +363,9 @@ point is a single character in Go.
 
 <h3>Characters</h3>
 
-The following terms are used to denote specific Unicode character classes:
 <p>
+The following terms are used to denote specific Unicode character classes:
+</p>
 <ul>
 	<li>unicode_char      an arbitrary Unicode code point
 	<li>unicode_letter    a Unicode code point classified as "Letter"
@@ -575,9 +467,10 @@ numbers.
 
 <h3>Character and string literals</h3>
 
+<p>
 Character and string literals are almost the same as in C, with the
 following differences:
-<p>
+</p>
 <ul>
 	<li>The encoding is UTF-8
 	<li>`` strings exist; they do not interpret backslashes
@@ -591,8 +484,9 @@ The rules are:
 escaped_char = "\" ( "a" | "b" | "f" | "n" | "r" | "t" | "v" | "\" | "'" | """ ) .
 </pre>
 
-A unicode_value takes one of four forms:
 <p>
+A unicode_value takes one of four forms:
+</p>
 <ul>
 	<li>The UTF-8 encoding of a Unicode code point.  Since Go source
 text is in UTF-8, this is the obvious translation from input
@@ -1220,9 +1114,10 @@ available through the two predeclared constants, "true" and "false".
 
 <h3>Strings</h3>
 
+<p>
 The "string" type represents the set of string values (strings).
 Strings behave like arrays of bytes, with the following properties:
-<p>
+</p>
 <ul>
 <li>They are immutable: after creation, it is not possible to change the
 contents of a string.
@@ -1789,6 +1684,7 @@ the same ValueType. They are equal if both values were created by the same
 
 <h3>Type equality</h3>
 
+<p>
 Types may be ``different'', ``structurally equal'', or ``identical''.
 Go is a type-safe language; generally different types cannot be mixed
 in binary operations, and values cannot be assigned to variables of different
@@ -1803,7 +1699,7 @@ are equal. Two type literals specify equal types if they have the same
 literal structure and corresponding components have equal types. Loosely
 speaking, two types are equal if their values have the same layout in memory.
 More precisely:
-<p>
+</p>
 <ul>
 	<li>Two array types are equal if they have equal element types and if they
 	  have the same array length.
@@ -1833,12 +1729,13 @@ More precisely:
 
 <p>
 Type identity is defined by these rules:
+</p>
 <p>
 Two type names denote identical types if they originate in the same
 type declaration. Two type literals specify identical types if they have the
 same literal structure and corresponding components have identical types.
 More precisely:
-<p>
+</p>
 <ul>
 	<li>Two array types are identical if they have identical element types and if
 	  they have the same array length.
@@ -2199,12 +2096,14 @@ A primary expression of the form
 a[x]
 </pre>
 
+<p>
 denotes the array or map element x. The value x is called the
 ``array index'' or ``map key'', respectively. The following
 rules apply:
+</p>
 <p>
 For a of type A or *A where A is an array type (§Array types):
-<p>
+</p>
 <ul>
 	<li>x must be an integer value and 0 &lt;= x &lt; len(a)
 	<li>a[x] is the array element at index x and the type of a[x]
@@ -2212,7 +2111,7 @@ For a of type A or *A where A is an array type (§Array types):
 </ul>
 <p>
 For a of type *M, where M is a map type (§Map types):
-<p>
+</p>
 <ul>
 	<li>x must be of the same type as the key type of M
 	  and the map must contain an entry with key x
@@ -2434,8 +2333,9 @@ mul_op = "*" | "/" | "%" | "&lt;&lt;" | ">>" | "&amp;" .
 unary_op = "+" | "-" | "!" | "^" | "*" | "&amp;" | "&lt;-" .
 </pre>
 
-The operand types in binary operations must be equal, with the following exceptions:
 <p>
+The operand types in binary operations must be equal, with the following exceptions:
+</p>
 <ul>
 	<li>If one operand has numeric type and the other operand is
 	  an ideal number, the ideal number is converted to match the type of
@@ -2849,8 +2749,9 @@ omitted in some cases as expressed by the OptSemicolon production.
 StatementList = Statement { OptSemicolon Statement } .
 </pre>
 
-A semicolon may be omitted immediately following:
 <p>
+A semicolon may be omitted immediately following:
+</p>
 <ul>
 	<li>a closing parenthesis ")" ending a list of declarations (§Declarations and scope rules)
 	<li>a closing brace "}" ending a type declaration (§Type declarations)
@@ -3538,7 +3439,6 @@ base type and may be forward-declared.
 
 
 <h3>Predeclared functions</h3>
-<p>
 <ul>
 	<li>cap
 	<li>convert
@@ -3965,8 +3865,9 @@ uint32, int32, float32    4
 uint64, int64, float64    8
 </pre>
 
-A Go compiler guarantees the following minimal alignment properties:
 <p>
+A Go compiler guarantees the following minimal alignment properties:
+</p>
 <ol>
 <li>For a variable "x" of any type: "1 <= unsafe.Alignof(x) <= unsafe.Maxalign".
 
-- 
2.48.1