add HTML formatting; use

/home/sanjay/bin/makehtml --mode=document go_lang.txt
to generate the html output.

SVN=111681

doc/go_lang.txt

@@ -1,4 +1,5 @@
 The Go Programming Language
+----
 (March 7, 2008)
 
 This document is an informal specification/proposal for a new systems programming
@@ -6,6 +7,7 @@ language.
 
 
 Guiding principles
+----
 
 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
@@ -28,11 +30,12 @@ written in itself.
 
 
 Modularity, identifiers and scopes
+----
 
 A Go program consists of one or more `packages' compiled separately, though
 not independently.  A single package may make
 individual identifiers visible to other files by marking them as
-exported; there is no "header file".
+exported; there is no ``header file''.
 
 A package collects types, constants, functions, and so on into a named
 entity that may be exported to enable its constituents be used in
@@ -45,6 +48,7 @@ Scoping is essentially the same as in C.
 
 
 Program structure
+----
 
 A compilation unit (usually a single source file)
 consists of a package specifier followed by import
@@ -63,6 +67,7 @@ still under development.
 
 
 Typing, polymorphism, and object-orientation
+----
 
 Go programs are strongly typed. Certain expressions, in particular map
 and channel accesses, can also be polymorphic.  The language provides
@@ -80,7 +85,7 @@ An interface is implemented by associating methods with
 structures.  If a structure implements 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 incur no
+can always be statically bound (they are not ``virtual''), and incur no
 runtime overhead compared to an ordinary function.
 
 Go has no explicit notion of classes, sub-classes, or inheritance.
@@ -93,6 +98,7 @@ use of abstract data types operating on interface types.
 
 
 Pointers and garbage collection
+----
 
 Variables may be allocated automatically (when entering the scope of
 the variable) or explicitly on the heap.  Pointers are used to refer
@@ -103,6 +109,7 @@ they are no longer accessible.  There is no pointer arithmetic in Go.
 
 
 Functions
+----
 
 Functions contain declarations and statements.  They may be
 recursive.  Functions may be anonymous and appear as
@@ -110,6 +117,7 @@ literals in expressions.
 
 
 Multithreading and channels
+----
 
 Go supports multithreaded programming directly. A function may
 be invoked as a parallel thread of execution.  Communication and
@@ -118,6 +126,7 @@ language support.
 
 
 Values and references
+----
 
 All objects have value semantics, but its contents may be accessed
 through different pointers referring to the same object.
@@ -131,6 +140,7 @@ byte strings.
 
 
 Syntax
+----
 
 The syntax of statements and expressions in Go borrows from the C tradition;
 declarations are loosely derived from the Pascal tradition to allow more
@@ -138,7 +148,7 @@ comprehensible composability of types.
 
 Here is a complete example Go program that implements a concurrent prime sieve:
 
-============================
+
   package Main
   
   // Send the sequence 2, 3, 4, ... to channel 'ch'.
@@ -175,19 +185,19 @@ func Sieve() {
   func Main() {
     Sieve();
   }
-============================
 
 
 Notation
+----
 
 The syntax is specified using Extended
 Backus-Naur Form (EBNF).  In particular:
 
-''  encloses lexical symbols
-|  separates alternatives
-()  used for grouping
-[]  specifies option (0 or 1 times)
-{}  specifies repetition (0 to n times)
+- ''  encloses lexical symbols
+- |  separates alternatives
+- ()  used for grouping
+- []  specifies option (0 or 1 times)
+- {}  specifies repetition (0 to n times)
 
 A production may be referenced from various places in this document
 but is usually defined close to its first use.  Code examples are indented.
@@ -198,6 +208,7 @@ productions are in CamelCase.
 
 
 Common productions
+----
 
   IdentifierList = identifier { ',' identifier }.
   ExpressionList = Expression { ',' Expression }.
@@ -207,6 +218,7 @@ PackageName = identifier.
 
 
 Source code representation
+----
 
 Source code is Unicode text encoded in UTF-8.
 
@@ -222,6 +234,7 @@ implementation, Go treats these as distinct characters.
 
 
 Characters
+----
 
 In the grammar we use the notation
 
@@ -231,6 +244,7 @@ to refer to an arbitrary Unicode code point encoded in UTF-8.
 
 
 Digits and Letters
+----
 
   octal_digit = { '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' } .
   decimal_digit = { '0' | '1' | '2' | '3' | '4' | '5' | '6' | '7' | '8' | '9' } .
@@ -243,6 +257,7 @@ Unicode identifiers.
 
 
 Identifiers
+----
 
 An identifier is a name for a program entity such as a variable, a
 type, a function, etc. An identifier must not be a reserved word.
@@ -255,6 +270,7 @@ identifier = letter { letter | decimal_digit } .
 
 
 Types
+----
 
 A type specifies the set of values which variables of that type may
 assume, and the operators that are applicable.
@@ -263,6 +279,7 @@ There are basic types and compound types constructed from them.
 
 
 Basic types
+----
 
 Go defines a number of basic types which are referred to by their
 predeclared type names.  There are signed and unsigned integer
@@ -288,17 +305,18 @@ and floating point types:
 
 Additionally, Go declares 4 basic types, uint, int, float, and double,
 which are platform-specific.  The bit width of these types corresponds to
-the "natural bit width" for the respective types for the given
+the ``natural bit width'' for the respective types for the given
 platform. For instance, int is usally the same as int32 on a 32-bit
 architecture, or int64 on a 64-bit architecture.  These types are by
 definition platform-specific and should be used with the appropriate
 caution.
 
-Two reserved words, 'true' and 'false', represent the
+Two reserved words, "true" and "false", represent the
 corresponding boolean constant values.
 
 
 Numeric literals
+----
 
 Integer literals take the usual C form, except for the absence of the
 'U', 'L' etc.  suffixes, and represent integer constants.  (Character
@@ -334,6 +352,7 @@ unsigned_float_lit = "the usual decimal-only floating point representation".
   +3.24e-7
 
 The string type
+----
 
 The string type represents the set of string values (strings).
 A string behaves like an array of bytes, with the following properties:
@@ -356,8 +375,8 @@ A string behaves like an array of bytes, with the following properties:
 
 
 Character and string literals
+----
 
-[ R: FIX ALL UNICODE INSIDE ]
 Character and string literals are almost the same as in C, but with
 UTF-8 required.  This section is precise but can be skipped on first
 reading.
@@ -368,6 +387,8 @@ Character and string literals are similar to C except:
   - Strings are UTF-8 and represent Unicode
   - `` strings exist; they do not interpret backslashes
 
+The rules are:
+
   char_lit = '\'' ( unicode_value | byte_value ) '\'' .
   unicode_value = utf8_char | little_u_value | big_u_value | escaped_char .
   byte_value = octal_byte_value | hex_byte_value .
@@ -380,14 +401,14 @@ escaped_char = '\' ( 'a' | 'b' | 'f' | 'n' | 'r' | 't' | 'v' ) .
 
 A UnicodeValue takes one of four forms:
 
-   1.  The UTF-8 encoding of a Unicode code point.  Since Go source
+* The UTF-8 encoding of a Unicode code point.  Since Go source
 text is in UTF-8, this is the obvious translation from input
 text into Unicode characters.
-   2.  The usual list of C backslash escapes: \n \t etc.  3.  A
-       `little u' value, such as \u12AB.  This represents the Unicode
+* The usual list of C backslash escapes: \n \t etc.
+* A `little u' value, such as \u12AB.  This represents the Unicode
 code point with the corresponding hexadecimal value.  It always
 has exactly 4 hexadecimal digits.
-   4.  A `big U' value, such as '\U00101234'.  This represents the
+* A `big U' value, such as '\U00101234'.  This represents the
 Unicode code point with the corresponding hexadecimal value.
 It always has exactly 8 hexadecimal digits.
 
@@ -404,11 +425,11 @@ It is erroneous for an OctalByteValue to represent a value larger than 255.
 
 A character literal is a form of unsigned integer constant.  Its value
 is that of the Unicode code point represented by the text between the
-quotes.
+quotes. [Note: the Unicode doesn't look right in the browser.]
 
     'a'
-    'ä'  // FIX
-    '本'  // FIX
+    'ä'
+    '本'
     '\t'
     '\0'
     '\07'
@@ -430,7 +451,11 @@ A string literal has type 'string'.  Its value is constructed by
 taking the byte values formed by the successive elements of the
 literal.  For ByteValues, these are the literal bytes; for
 UnicodeValues, these are the bytes of the UTF-8 encoding of the
-corresponding Unicode code points.  Note that "\u00FF" and "\xFF" are
+corresponding Unicode code points.  Note that
+	"\u00FF"
+and
+	"\xFF"
+are
 different strings: the first contains the two-byte UTF-8 expansion of
 the value 255, while the second contains a single byte of value 255.
 The same rules apply to raw string literals, except the contents are
@@ -465,6 +490,7 @@ literal.
 
 
 More about types
+----
 
 The static type of a variable is the type defined by the variable's
 declaration.  At run-time, some variables, in particular those of
@@ -489,6 +515,7 @@ TypeName = QualifiedIdent.
 
 
 Array types
+----
 
 [TODO: this section needs work regarding the precise difference between
 static, open and dynamic arrays]
@@ -521,6 +548,7 @@ built-in special function len():
 
 
 Array literals
+----
 
 Array literals represent array constants. All the contained expressions must
 be of the same type, which is the element type of the resulting array.
@@ -532,6 +560,7 @@ ArrayLit = '[' ExpressionList ']' .
 
 
 Map types
+----
 
 A map is a structured type consisting of a variable number of entries
 called (key, value) pairs. For a given map,
@@ -550,6 +579,7 @@ ValueType = Type | 'any' .
 
 
 Map Literals
+----
 
 Map literals represent map constants.  They comprise a list of (key, value)
 pairs.  All keys must have the same type; all values must have the same type.
@@ -564,6 +594,7 @@ KeyValue = Expression ':' Expression .
 
 
 Struct types
+----
 
 Struct types are similar to C structs.
 
@@ -586,6 +617,7 @@ FieldDecl = IdentifierList Type ';' .
 
   
 Struct literals
+----
 
 Struct literals represent struct constants.  They comprise a list of
 expressions that represent the individual fields of a struct.  The
@@ -601,6 +633,7 @@ The type name must be that of a defined struct type.
 
 
 Pointer types
+----
 
 Pointer types are similar to those in C.
 
@@ -615,6 +648,7 @@ There are no pointer literals.
 
 
 Channel types
+----
 
 A channel provides a mechanism for two concurrently executing functions
 to exchange values and synchronize execution.  A channel type can be
@@ -639,6 +673,7 @@ There are no channel literals.
 
 
 Function types
+----
 
 A function type denotes the set of all functions with the same signature.
 
@@ -673,6 +708,7 @@ pointer.
 
 
 Function Literals
+----
 
 Function literals represent anonymous functions.
 
@@ -692,6 +728,7 @@ variables, and variables declared within the function literal.
 
 
 Methods
+----
 
 A method is a function bound to a particular struct type T.  When defined,
 a method indicates the type of the struct by declaring a receiver of type
@@ -721,12 +758,14 @@ For instance, given a Point variable pt, one may call
 
 
 Interface of a struct
+----
 
 The interface of a struct is defined to be the unordered set of methods
 associated with that struct.
 
 
 Interface types
+----
 
 An interface type denotes a set of methods.
 
@@ -774,6 +813,7 @@ There are no interface literals.
 
 
 Literals
+----
 
   Literal = BasicLit | CompoundLit .
   BasicLit = CharLit | StringLit | IntLit | FloatLit .
@@ -781,6 +821,7 @@ CompoundLit = ArrayLit | MapLit | StructLit | FunctionLit .
 
 
 Declarations
+----
 
 A declaration associates a name with a language entity such as a type,
 constant, variable, or function.
@@ -789,6 +830,7 @@ Declaration = ConstDecl | TypeDecl | VarDecl | FunctionDecl | ExportDecl .
 
 
 Const declarations
+----
 
 A constant declaration gives a name to the value of a constant expression.
 
@@ -805,6 +847,7 @@ ConstSpecList = ConstSpec { ';' ConstSpec }.
 
 
 Type declarations
+----
 
 A type declaration introduces a name as a shorthand for a type.
 In certain situations, such as conversions, it may be necessary to
@@ -823,6 +866,7 @@ TypeSpecList = TypeSpec { ';' TypeSpec }.
 
 
 Variable declarations
+----
 
 A variable declaration creates a variable and gives it a type and a name.
 It may optionally give the variable an initial value; in some forms of
@@ -848,7 +892,7 @@ The syntax
 
   SimpleVarDecl = identifier ':=' Expression .
 
-is syntactic shorthand for
+is shorthand for
 
   var identifer = Expression.
 
@@ -861,6 +905,7 @@ declare local temporary variables.
 
 
 Function and method declarations
+----
 
 Functions and methods have a special declaration syntax, slightly
 different from the type syntax because an identifier must be present
@@ -904,6 +949,7 @@ Functions and methods can be forward declared by omitting the body:
 
 
 Export declarations
+----
 
 Global identifiers may be exported, thus making the
 exported identifer visible outside the package.  Another package may
@@ -931,6 +977,7 @@ ExportIdentifier = QualifiedIdent .
 
 
 Expressions
+----
 
 Expression syntax is based on that of C but with fewer precedence levels.
 
@@ -1014,6 +1061,7 @@ General expressions
   
 
 The constant generator 'iota'
+----
 
 Within a declaration, each appearance of the keyword 'iota' represents a successive
 element of an integer sequence. It is reset to zero whenever the keyword 'const', 'type'
@@ -1037,6 +1085,7 @@ a set of related constants:
 
 
 Statements
+----
 
 Statements control execution.
 
@@ -1054,6 +1103,7 @@ SimpleStat =
   
 
 Expression statements
+----
 
   ExpressionStat = Expression .
 
@@ -1061,6 +1111,7 @@ ExpressionStat = Expression .
 
 
 IncDec statements
+----
 
   IncDecStat = Expression ( '++' | '--' ) .
 
@@ -1070,6 +1121,7 @@ Note that ++ and -- are not operators for expressions.
 
 
 Compound statements
+----
 
   CompoundStat = '{' { Statement } '}' .
 
@@ -1083,6 +1135,7 @@ from the declaration to the end of the compound statement.
 
 
 Assignments
+----
 
   Assignment = SingleAssignment | TupleAssignment | Send .
   SimpleAssignment = Designator assign_op Expression .
@@ -1141,6 +1194,7 @@ In assignments, the type of the expression must match the type of the designator
 
 
 Go statements
+----
 
 A go statement starts the execution of a function as an independent
 concurrent thread of control within the same address space.  Unlike
@@ -1149,17 +1203,20 @@ function to complete.
 
   GoStat = 'go' Call .
 
+
   go Server()
   go func(ch chan> bool) { for ;; { sleep(10); >ch = true; }} (c)
 
 
 Return statements
+----
 
 A return statement terminates execution of the containing function
 and optionally provides a result value or values to the caller.
 
   ReturnStat = 'return' [ ExpressionList ] .
 
+
 There are two ways to return values from a function.  The first is to
 explicitly list the return value or values in the return statement:
 
@@ -1190,6 +1247,7 @@ first form of return statement is used:
 
 
 If statements
+----
 
 If statements have the traditional form except that the
 condition need not be parenthesized and the "then" statement
@@ -1215,6 +1273,7 @@ the variable is initialized once before the statement is entered.
   
 
 Switch statements
+----
 
 Switches provide multi-way execution.
 
@@ -1268,6 +1327,7 @@ If the expression is omitted, it is equivalent to 'true'.
 
 
 For statements
+----
 
 For statements are a combination of the 'for' and 'while' loops of C.
 
@@ -1301,6 +1361,7 @@ If the condition is absent, it is equivalent to 'true'.
 
 
 Range statements
+----
 
 Range statements are a special control structure for iterating over
 the contents of arrays and maps.
@@ -1327,6 +1388,7 @@ array elements (the values).
 
 
 Break statements
+----
 
 Within a 'for' or 'switch' statement, a 'break' statement terminates execution of
 the innermost 'for' or 'switch' statement.
@@ -1344,6 +1406,7 @@ statement, and that is the one whose execution terminates.
 
 
 Continue statements
+----
 
 Within a 'for' loop a continue statement begins the next iteration of the
 loop at the post statement.
@@ -1354,6 +1417,7 @@ The optional identifier is analogous to that of a 'break' statement.
 
 
 Goto statements
+----
 
 A goto statement transfers control to the corresponding label statement.
 
@@ -1363,6 +1427,7 @@ GotoStat = 'goto' identifier .
 
 
 Label statement
+----
 
 A label statement serves as the target of a 'goto', 'break' or 'continue' statement.
 
@@ -1374,6 +1439,7 @@ There are various restrictions [TBD] as to where a label statement can be used.
 
 
 Packages
+----
 
 Every source file identifies the package to which it belongs.
 The file must begin with a package clause.
@@ -1384,6 +1450,7 @@ PackageClause = 'package' PackageName .
 
 
 Import declarations
+----
 
 A program can gain access to exported items from another package
 through an import declaration:
@@ -1427,14 +1494,16 @@ an error if the import introduces name conflicts.
 
 
 Program
+----
 
 A program is package clause, optionally followed by import declarations,
 followed by a series of declarations.
 
 Program = PackageClause { ImportDecl } { Declaration } .
 
--------------------------------------------------------------------------
+TODO
+----
 
-TODO: type switch?
-TODO: select
-TODO: words about slices
+- TODO: type switch?
+- TODO: select
+- TODO: words about slices