Yet more refactoring of manual

- Adds new section on naming variables and style convention
- Refactors linear algebra content out of Arrays
- Turn more lists of functions into tables
- Documents built-in Exceptions, symbol(), isnan, isinf, isfinite, info, warn
- Updates list of vectorized functions and documents @vectorize_?args macros
- Turns embedded HTML footnotes into ReST footnotes
- Fixes sectioning issue in Arrays
- More cross-referencing, especially for non-standard string literals
- Minor grammatical, language, spelling cleanup
- Remove user-specific output from sample Julia snippets

doc/manual/complex-and-rational-numbers.rst

@@ -5,9 +5,9 @@
 ******************************
 
 Julia ships with predefined types representing both complex and rational
-numbers, and supports all the mathematical operations discussed in
-:ref:`man-mathematical-operations` on them.
-Promotions are defined so that operations on any combination of
+numbers, and supports all :ref:`standard mathematical operations
+<man-mathematical-operations>` on them. :ref:`man-promotions`
+are defined so that operations on any combination of
 predefined numeric types, whether primitive or composite, behave as
 expected.
 
@@ -20,8 +20,8 @@ The global constant ``im`` is bound to the complex number *i*,
 representing the principal square root of -1. It was deemed harmful to
 co-opt the name ``i`` for a global constant, since it is such a popular
 index variable name. Since Julia allows numeric literals to be
-:ref:`juxtaposed with identifiers as
-coefficients <man-numeric-literal-coefficients>`,
+:ref:`juxtaposed with identifiers as coefficients
+<man-numeric-literal-coefficients>`,
 this binding suffices to provide convenient syntax for complex numbers,
 similar to the traditional mathematical notation::
 
@@ -144,23 +144,23 @@ versus ``-1 + 0im`` even though ``-1 == -1 + 0im``::
     julia> sqrt(-1 + 0im)
     0.0 + 1.0im
 
-If you need to construct a complex number using variables, the literal
-numeric coefficient notation will not work, although explicitly writing
-the multiplication operation will::
+The :ref:`literal numeric coefficient notation <numeric-literal-coefficients>`
+does work when constructing complex number from variables. Instead, the
+multiplication must be explicitly written out::
 
     julia> a = 1; b = 2; a + b*im
     1 + 2im
 
-Constructing complex numbers from variable values like this, however,
-is not recommended. Use the ``complex`` function to construct a
-complex value directly from its real and imaginary parts instead. This
-construction is preferred for variable arguments because it is more
-efficient than the multiplication and addition construct, but also
-because certain values of ``b`` can yield unexpected results::
+Hoever, this is *not* recommended; Use the ``complex`` function instead to
+construct a complex value directly from its real and imaginary parts.::
 
     julia> complex(a,b)
     1 + 2im
 
+This construction avoids the multiplication and addition operations, and also
+sidesteps unexpected results that can arise with the former for certain values
+of ``b``.
+
 ``Inf`` and ``NaN`` propagate through complex numbers in the real
 and imaginary parts of a complex number as described in the 
 :ref:`man-special-floats` section::
@@ -260,7 +260,7 @@ Constructing infinite rational values is acceptable::
     julia> typeof(ans)
     Rational{Int64}
 
-Trying to construct a NaN rational value, however, is not::
+Trying to construct a ``NaN`` rational value, however, is not::
 
     julia> 0//0
     invalid rational: 0//0

doc/manual/constructors.rst

@@ -4,7 +4,7 @@
  Constructors  
 **************
 
-Constructors are functions that create new objects — specifically,
+Constructors [#]_ are functions that create new objects — specifically,
 instances of :ref:`man-composite-types`. In Julia,
 type objects also serve as constructor functions: they create new
 instances of themselves when applied to an argument tuple as a function.
@@ -39,6 +39,15 @@ construct objects with fewer or different types of parameters than they
 have fields. Julia's system for object construction addresses all of
 these cases and more.
 
+.. [#] Nomenclature: while the term “constructor” generally refers to
+  the entire function which constructs objects of a type, it is common to
+  abuse terminology slightly and refer to specific constructor methods as
+  “constructors”. In such situations, it is generally clear from context
+  that the term is used to mean “constructor method” rather than
+  “constructor function”, especially as it is often used in the sense of
+  singling out a particular method of the constructor from all of the
+  others.
+
 Outer Constructor Methods
 -------------------------
 
@@ -71,23 +80,6 @@ this are called *outer* constructor methods. Outer constructor methods
 can only ever create a new instance by calling another constructor
 method, such as the automatically provided default one.
 
-.. raw:: html
-
-   <div class="sidebar">
-
-A Note On Nomenclature. While the term “constructor” generally refers to
-the entire function which constructs objects of a type, it is common to
-abuse terminology slightly and refer to specific constructor methods as
-“constructors”. In such situations, it is generally clear from context
-that the term is used to mean “constructor method” rather than
-“constructor function”, especially as it is often used in the sense of
-singling out a particular method of the constructor from all of the
-others.
-
-.. raw:: html
-
-   </div>
-
 Inner Constructor Methods
 -------------------------
 
@@ -178,11 +170,9 @@ with an explicit constructor::
 
     julia> T1(1.0)
     no method T1(Float64,)
-     in method_missing at /Users/stefan/projects/julia/base/base.jl:58
 
     julia> T2(1.0)
     no method T2(Float64,)
-     in method_missing at /Users/stefan/projects/julia/base/base.jl:58
 
 It is considered good form to provide as few inner constructor methods
 as possible: only those taking all arguments explicitly and enforcing
@@ -307,7 +297,6 @@ types of the arguments given to the constructor. Here are some examples::
 
     julia> Point(1,2.5)
     no method Point(Int64,Float64)
-     in method_missing at /Users/stefan/projects/julia/base/base.jl:58
 
     ## explicit T ##
 
@@ -316,14 +305,12 @@ types of the arguments given to the constructor. Here are some examples::
 
     julia> Point{Int64}(1.0,2.5)
     no method Point(Float64,Float64)
-     in method_missing at /Users/stefan/projects/julia/base/base.jl:58
 
     julia> Point{Float64}(1.0,2.5)
     Point(1.0,2.5)
 
     julia> Point{Float64}(1,2)
     no method Point(Int64,Int64)
-     in method_missing at /Users/stefan/projects/julia/base/base.jl:58
 
 As you can see, for constructor calls with explicit type parameters, the
 arguments must match that specific type: ``Point{Int64}(1,2)`` works,