fix more jacked up RST all over the place

Author: StefanKarpinski

doc/devdocs/eval.rst

@@ -8,8 +8,8 @@ One of the hardest parts about learning how the Julia Language runs code is lear
 how all of the pieces work together to execute a block of code.
 
 Each chunk of code typically makes a trip through many esoteric acronyms such as (in no particular order),
-`flisp`, `AST`, `C++`, `LLVM`, `eval`, `typeinf`, `macroexpand`, `sysimg` (or `system image`), `bootstrapping`,
-`compile`, `parse`, `execute`, `JIT`, `interpret`, `box`, `unbox`, `intrinsic function`, `primitive function`
+``flisp``, ``AST``, ``C++``, ``LLVM``, ``eval``, ``typeinf``, ``macroexpand``, ``sysimg`` (or ``system image``), ``bootstrapping``,
+``compile``, ``parse``, ``execute``, ``JIT``, ``interpret``, ``box``, ``unbox``, ``intrinsic function``, ``primitive function``
 before turning into the desired result (hopefully).
 
 .. sidebar:: Definitions
@@ -30,26 +30,26 @@ Julia Execution
 
 The 10,000 foot view of the whole process is as follows:
 
-1. The user starts `julia`.
-2. The C function :c:func:`main` from `ui/repl.c` gets called.
+1. The user starts ``julia``.
+2. The C function :c:func:`main` from ``ui/repl.c`` gets called.
    This function processes the command line arguments, filling in the :c:type:`jl_options` struct and setting the variable :code:`ARGS`.
    It then initializes Julia (by calling `julia_init in task.c <https://github.com/JuliaLang/julia/blob/master/src/task.c>`_,
    which may load a previously compiled sysimg_).
    Finally, it passes off control to Julia by calling `Base._start() <https://github.com/JuliaLang/julia/blob/master/base/client.jl>`_.
-#. When `_start()` takes over control, the subsequent sequence of commands depends on the command line arguments given.
+#. When ``_start()`` takes over control, the subsequent sequence of commands depends on the command line arguments given.
    For example, if a filename was supplied, it will proceed to execute that file. Otherwise, it will start an interactive REPL.
 #. Skipping the details about how the REPL interacts with the user,
    let's just say the program ends up with a block of code that it wants to run.
 #. If the block of code to run is in a file, `jl_load(char *filename) <https://github.com/JuliaLang/julia/blob/master/src/toplevel.c>`_
-   gets invoked to load the file and parse_ it. Each fragment of code is then passed to `eval` to execute.
+   gets invoked to load the file and parse_ it. Each fragment of code is then passed to ``eval`` to execute.
 #. Each fragment of code (or AST), is handed off to :func:`eval` to turn into results.
 #. :func:`eval` takes each code fragment and tries to run it in `jl_toplevel_eval_flex() <https://github.com/JuliaLang/julia/blob/master/src/toplevel.c>`_.
-#. :c:func:`jl_toplevel_eval_flex` decides whether the code is a "toplevel" action (such as `using` or `module`), which would be invalid inside a function.
+#. :c:func:`jl_toplevel_eval_flex` decides whether the code is a "toplevel" action (such as ``using`` or ``module``), which would be invalid inside a function.
    If so, it passes off the code to the toplevel interpreter.
 #. :c:func:`jl_toplevel_eval_flex` then expands_ the code to eliminate any macros and to "lower" the AST to make it simpler to execute.
 #. :c:func:`jl_toplevel_eval_flex` then uses some simple heuristics to decide whether to JIT compiler the AST or to interpret it directly.
 #. The bulk of the work to interpret code is handled by `eval in interpreter.c <https://github.com/JuliaLang/julia/blob/master/src/interpreter.c>`_.
-#. If instead, the code is compiled, the bulk of the work is handled by `codegen.cpp`.
+#. If instead, the code is compiled, the bulk of the work is handled by ``codegen.cpp``.
    Whenever a Julia function is called for the first time with a given set of argument types, `type inference`_ will be run on that function.
    This information is used by the codegen_ step to generate faster code.
 #. Eventually, the user quits the REPL, or the end of the program is reached, and the :func:`_start` method returns.
@@ -80,8 +80,8 @@ Macro Expansion
 ---------------
 
 When :func:`eval` encounters a macro, it expands that AST node before attempting to evaluate the expression.
-Macro expansion involves a handoff from :func:`eval` (in Julia), to the parser function :c:func:`jl_macroexpand` (written in `flisp`)
-to the Julia macro itself (written in - what else - `Julia`) via :c:func:`fl_invoke_julia_macro`, and back.
+Macro expansion involves a handoff from :func:`eval` (in Julia), to the parser function :c:func:`jl_macroexpand` (written in ``flisp``)
+to the Julia macro itself (written in - what else - Julia) via :c:func:`fl_invoke_julia_macro`, and back.
 
 Typically, macro expansion is invoked as a first step during a call to :func:`expand`/:c:func:`jl_expand`,
 although it can also be invoked directly by a call to :func:`macroexpand`/:c:func:`jl_macroexpand`.
@@ -139,7 +139,7 @@ Type inference may also include other steps such as constant propagation and inl
       These pseudo-functions implement operations on raw bits such as add and sign extend
       that cannot be expressed directly in any other way.
       Since they operate on bits directly, they must be compiled into a function
-      and surrounded by a call to `Core.Intrinsics.box(T, ...)` to reassign type information to the value.
+      and surrounded by a call to ``Core.Intrinsics.box(T, ...)`` to reassign type information to the value.
 
 .. _codegen:
 
@@ -164,7 +164,7 @@ Other parts of codegen are handled by various helper files:
   Handles backtraces for JIT functions
 
 `ccall.cpp <https://github.com/JuliaLang/julia/blob/master/src/ccall.cpp>`_
-  Handles the ccall and llvmcall FFI, along with various `abi_*.cpp` files
+  Handles the ccall and llvmcall FFI, along with various ``abi_*.cpp`` files
 
 `intrinsics.cpp <https://github.com/JuliaLang/julia/blob/master/src/intrinsics.cpp>`_
   Handles the emission of various low-level intrinsic functions
@@ -183,14 +183,14 @@ System Image
 ------------
 
 The system image is a precompiled archive of a set of Julia files.
-The `sys.ji` file distributed with Julia is one such system image,
+The ``sys.ji`` file distributed with Julia is one such system image,
 generated by executing the file `sysimg.jl <https://github.com/JuliaLang/julia/blob/master/base/sysimg.jl>`_,
 and serializing the resulting environment (including Types, Functions, Modules, and all other defined values)
 into a file. Therefore, it contains a frozen version of the :mod:`Main`, :mod:`Core`, and :mod:`Base` modules (and whatever else was in the environment at the end of bootstrapping).
 This serializer/deserializer is implemented by `jl_save_system_image/jl_restore_system_image in dump.c <https://github.com/JuliaLang/julia/blob/master/src/dump.c>`_.
 
 If there is no sysimg file (:code:`jl_options.image_file == NULL`),
-this also implies that `--build` was given on the command line,
+this also implies that ``--build`` was given on the command line,
 so the final result should be a new sysimg file.
 During Julia initialization, minimal :mod:`Core` and :mod:`Main` modules are created.
 Then a file named ``boot.jl`` is evaluated from the current directory.

doc/devdocs/llvm.rst

@@ -37,7 +37,7 @@ directory ``src/``.
 |``sys.c``            | I/O and operating system utility functions                  |
 +---------------------+-------------------------------------------------------------+
 
-Some of the `.cpp` files form a group that compile to a single object.
+Some of the ``.cpp`` files form a group that compile to a single object.
 
 The difference between an intrinsic and a builtin is that a builtin is a first class
 function that can be used like any other Julia function.  An intrinsic can operate
@@ -50,7 +50,7 @@ Julia currently uses LLVM's `Type Based Alias Analysis <http://llvm.org/docs/Lan
 To find the comments that document the inclusion relationships, look for ``static MDNode*``
 in ``src/codegen.cpp``.
 
-The `-O` option enables LLVM's `Basic Alias Analysis <http://llvm.org/docs/AliasAnalysis.html#the-basicaa-pass>`_.
+The ``-O`` option enables LLVM's `Basic Alias Analysis <http://llvm.org/docs/AliasAnalysis.html#the-basicaa-pass>`_.
 
 Building Julia with a different version of LLVM
 -----------------------------------------------
@@ -76,7 +76,7 @@ Here are example settings using ``bash`` syntax:
 
 * ``export JULIA_LLVM_ARGS = -print-after-all`` dumps IR after each pass.
 
-* ``export JULIA_LLVM_ARGS = -debug-only=loop-vectorize`` dumps LLVM `DEBUG(`...`)`
+* ``export JULIA_LLVM_ARGS = -debug-only=loop-vectorize`` dumps LLVM ``DEBUG(...)``
   diagnostics for loop vectorizer *if* you built Julia with ``LLVM_ASSERTIONS=1``.
   Otherwise you will get warnings about "Unknown command line argument".
   Counter-intuitively, building Julia with ``LLVM_DEBUG=1`` is *not* enough to

doc/manual/arrays.rst

@@ -87,9 +87,9 @@ Function                                            Description
                                                     defaulting to the element type and dimensions of ``A`` if omitted.
 :func:`reinterpret(type, A) <reinterpret>`          an array with the same binary data as the given array, but with the
                                                     specified element type
-:func:`rand(dims) <rand>`                           `:obj:`Array` of ``Float64``\ s with random, iid[#]_ and uniformly
+:func:`rand(dims) <rand>`                           :obj:`Array` of ``Float64``\ s with random, iid[#]_ and uniformly
                                                     distributed values in the half-open interval :math:`[0, 1)`
-:func:`randn(dims) <randn>`                         `:obj:`Array` of ``Float64``\ s with random, iid and standard normally
+:func:`randn(dims) <randn>`                         :obj:`Array` of ``Float64``\ s with random, iid and standard normally
                                                     distributed random values
 :func:`eye(n) <eye>`                                ``n``-by-``n`` identity matrix
 :func:`eye(m, n) <eye>`                             ``m``-by-``n`` identity matrix
@@ -528,7 +528,7 @@ where elements are stored in column-major order (see additional notes in
 :ref:`man-performance-tips`). :obj:`Vector` and :obj:`Matrix` are aliases for
 the 1-d and 2-d cases. Specific operations such as scalar indexing,
 assignment, and a few other basic storage-specific operations are all
-that have to be implemented for `:obj:`Array`, so that the rest of the array
+that have to be implemented for :obj:`Array`, so that the rest of the array
 library can be implemented in a generic manner.
 
 :obj:`SubArray` is a specialization of :obj:`AbstractArray` that performs
@@ -541,7 +541,7 @@ can later be used to index the original array indirectly.
 
 :obj:`StridedVector` and :obj:`StridedMatrix` are convenient aliases defined
 to make it possible for Julia to call a wider range of BLAS and LAPACK
-functions by passing them either `:obj:`Array` or :obj:`SubArray` objects, and
+functions by passing them either :obj:`Array` or :obj:`SubArray` objects, and
 thus saving inefficiencies from memory allocation and copying.
 
 The following example computes the QR decomposition of a small section

doc/manual/calling-c-and-fortran-code.rst

@@ -222,7 +222,7 @@ to fail or produce indeterminate results on a different system.
 Note that no C header files are used anywhere in the process of calling C
 functions: you are responsible for making sure that your Julia types and
 call signatures accurately reflect those in the C header file. (The `Clang
-package` <https://github.com/ihnorton/Clang.jl> can be used to auto-generate
+package <https://github.com/ihnorton/Clang.jl>`_ can be used to auto-generate
 Julia code from a C header file.)
 
 Auto-conversion:
@@ -341,7 +341,7 @@ Julia type with the same name, prefixed by C. This can help for writing portable
 +===================================+=================+======================+===================================+
 | ``unsigned char``                 | ``CHARACTER``   | ``Cuchar``           | ``UInt8``                         |
 |                                   |                 |                      |                                   |
-| ``bool`` (`C++`)                  |                 |                      |                                   |
+| ``bool`` (C++)                    |                 |                      |                                   |
 +-----------------------------------+-----------------+----------------------+-----------------------------------+
 | ``short``                         | ``INTEGER*2``   | ``Cshort``           | ``Int16``                         |
 |                                   |                 |                      |                                   |
@@ -351,7 +351,7 @@ Julia type with the same name, prefixed by C. This can help for writing portable
 +-----------------------------------+-----------------+----------------------+-----------------------------------+
 | ``int``                           | ``INTEGER*4``   | ``Cint``             | ``Int32``                         |
 |                                   |                 |                      |                                   |
-| ``BOOL`` (`C`, typical)           | ``LOGICAL*4``   |                      |                                   |
+| ``BOOL`` (C, typical)             | ``LOGICAL*4``   |                      |                                   |
 +-----------------------------------+-----------------+----------------------+-----------------------------------+
 | ``unsigned int``                  |                 | ``Cuint``            | ``UInt32``                        |
 +-----------------------------------+-----------------+----------------------+-----------------------------------+
@@ -433,40 +433,55 @@ C name                  Standard Julia Alias    Julia Base Type
                                                 ``UInt16`` (Windows)
 ======================  ======================  =======
 
-`Remember`: when calling a Fortran function, all inputs must be passed by reference, so all type correspondences
-above should contain an additional ``Ptr{..}`` or ``Ref{..}`` wrapper around their type specification.
+.. note::
 
-`Warning`: For string arguments (``char*``) the Julia type should be ``Cstring`` (if NUL-terminated data is expected)
-or either ``Ptr{Cchar}`` or ``Ptr{UInt8}`` otherwise (these two pointer types have the same effect), as described above,
-not ``ASCIIString``. Similarly, for array arguments (``T[]`` or ``T*``), the Julia
-type should again be ``Ptr{T}``, not ``Vector{T}``.
+    When calling a Fortran function, all inputs must be passed by reference, so
+    all type correspondences above should contain an additional ``Ptr{..}`` or
+    ``Ref{..}`` wrapper around their type specification.
 
-`Warning`: Julia's ``Char`` type is 32 bits, which is not the same as the wide
-character type (``wchar_t`` or ``wint_t``) on all platforms.
+.. warning::
 
-`Note`: For ``wchar_t*`` arguments, the Julia type should be ``Cwstring`` (if the C routine
-expects a NUL-terminated string) or ``Ptr{Cwchar_t}`` otherwise,
-and data can be converted to/from ordinary Julia strings by the
-``wstring(s)`` function (equivalent to either ``utf16(s)`` or ``utf32(s)``
-depending upon the width of ``Cwchar_t``); this conversion will be called
-automatically for ``Cwstring`` arguments.    Note also that ASCII, UTF-8,
-UTF-16, and UTF-32 string data in Julia is internally NUL-terminated, so
-it can be passed to C functions expecting NUL-terminated data without making
-a copy (but using the ``Cwstring`` type will cause an error to be thrown
-if the string itself contains NUL characters).
+    For string arguments (``char*``) the Julia type should be ``Cstring`` (if NUL-
+    terminated data is expected) or either ``Ptr{Cchar}`` or ``Ptr{UInt8}``
+    otherwise (these two pointer types have the same effect), as described above,
+    not ``ASCIIString``. Similarly, for array arguments (``T[]`` or ``T*``), the
+    Julia type should again be ``Ptr{T}``, not ``Vector{T}``.
 
-`Note`: C functions that take an argument of the type ``char**`` can be called by using
-a ``Ptr{Ptr{UInt8}}`` type within Julia. For example,
-C functions of the form::
+.. warning::
 
-    int main(int argc, char **argv);
+Julia's ``Char`` type is 32 bits, which is not the same as the wide character
+type (``wchar_t`` or ``wint_t``) on all platforms.
 
-can be called via the following Julia code::
+.. note::
 
-    argv = [ "a.out", "arg1", "arg2" ]
-    ccall(:main, Int32, (Int32, Ptr{Ptr{UInt8}}), length(argv), argv)
+    For ``wchar_t*`` arguments, the Julia type should be ``Cwstring`` (if the C
+    routine expects a NUL-terminated string) or ``Ptr{Cwchar_t}`` otherwise, and
+    data can be converted to/from ordinary Julia strings by the ``wstring(s)``
+    function (equivalent to either ``utf16(s)`` or ``utf32(s)`` depending upon the
+    width of ``Cwchar_t``); this conversion will be called automatically for
+    ``Cwstring`` arguments.    Note also that ASCII, UTF-8, UTF-16, and UTF-32
+    string data in Julia is internally NUL-terminated, so it can be passed to C
+    functions expecting NUL-terminated data without making a copy (but using the
+    ``Cwstring`` type will cause an error to be thrown if the string itself
+    contains NUL characters).
 
-`Note`: A C function declared to return ``Void`` will return the value ``nothing`` in Julia.
+.. note::
+
+    C functions that take an argument of the type ``char**`` can be called by
+    using a ``Ptr{Ptr{UInt8}}`` type within Julia. For example, C functions of the
+    form::
+
+        int main(int argc, char **argv);
+
+    can be called via the following Julia code::
+
+        argv = [ "a.out", "arg1", "arg2" ]
+        ccall(:main, Int32, (Int32, Ptr{Ptr{UInt8}}), length(argv), argv)
+
+.. note::
+
+    A C function declared to return ``Void`` will return the value ``nothing`` in
+    Julia.
 
 Struct Type correspondences
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -524,7 +539,7 @@ Memory allocation and deallocation of such objects must be
 handled by calls to the appropriate cleanup routines in the libraries
 being used, just like in any C program. Do not try to free an object
 received from a C library with ``Libc.free`` in Julia, as this may result
-in the ``free`` function being called via the wrong `libc` library and
+in the ``free`` function being called via the wrong ``libc`` library and
 cause Julia to crash. The reverse (passing an object allocated in Julia
 to be freed by an external library) is equally invalid.
 

doc/manual/documentation.rst

@@ -355,7 +355,7 @@ Adds docstring ``"..."`` to expression generated by expanding ``@m expression``.
 for expressions decorated with ``@inline``, ``@noinline``, ``@generated``, or any other
 macro to be documented in the same way as undecorated expressions.
 
-Macro authors should take note that only macros that generate a `single expression` will
+Macro authors should take note that only macros that generate a single expression will
 automatically support docstrings. If a macro returns a block containing multiple
 subexpressions then the subexpression that should be documented must be marked using the
 :func:`@__doc__` macro.

doc/manual/faq.rst

@@ -128,8 +128,8 @@ inside a specific function or set of functions, you have two options:
 What does the ``...`` operator do?
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-The two uses of the `...` operator: slurping and splatting
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+The two uses of the ``...`` operator: slurping and splatting
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 Many newcomers to Julia find the use of ``...`` operator confusing. Part of
 what makes the ``...`` operator confusing is that it means two different things