[docs] Update doc build instructions and some reformatting

[sbc100]

Summary

Changes to NewLLD.rst are simply to word wrap at 80 cols.

[sbc100]

ping. The sphinx_intro.rst changes are actually real (not just reformatting). I updated them to the cmake world.

[ruiu]

LGTM but please split this into two patches, one is to change format, and the other is to remove some sections, before committing.

README.md

-
 LLVM Linker (lld)
-==============================
+=================
 
 This directory and its subdirectories contain source code for the LLVM Linker, a
 modular cross platform linker which is built as part of the LLVM compiler
 infrastructure project.
 
 lld is open source software. You may freely distribute it under the terms of
 the license agreement found in LICENSE.txt.
 

docs/NewLLD.rst

* Speed by design
   until we need them to continue linking.
   When we need to do some costly operation (such as looking up
   a hash table for each symbol), we do it only once.
   We obtain a handler (which is typically just a pointer to actual data)
   on the first operation and use it throughout the process.
 
 * Efficient archive file handling
 
-  LLD's handling of archive files (the files with ".a" file extension) is different
-  from the traditional Unix linkers and similar to Windows linkers.
-  We'll describe how the traditional Unix linker handles archive files,
-  what the problem is, and how LLD approached the problem.
-
-  The traditional Unix linker maintains a set of undefined symbols during linking.
-  The linker visits each file in the order as they appeared in the command line
-  until the set becomes empty. What the linker would do depends on file type.
-
-  - If the linker visits an object file, the linker links object files to the result,
-    and undefined symbols in the object file are added to the set.
-
-  - If the linker visits an archive file, it checks for the archive file's symbol table
-    and extracts all object files that have definitions for any symbols in the set.
-
-  This algorithm sometimes leads to a counter-intuitive behavior.
-  If you give archive files before object files, nothing will happen
-  because when the linker visits archives, there is no undefined symbols in the set.
-  As a result, no files are extracted from the first archive file,
-  and the link is done at that point because the set is empty after it visits one file.
+  LLD's handling of archive files (the files with ".a" file extension) is
+  different from the traditional Unix linkers and similar to Windows linkers.
+  We'll describe how the traditional Unix linker handles archive files, what the
+  problem is, and how LLD approached the problem.
+
+  The traditional Unix linker maintains a set of undefined symbols during
+  linking.  The linker visits each file in the order as they appeared in the
+  command line until the set becomes empty. What the linker would do depends on
+  file type.
+
+  - If the linker visits an object file, the linker links object files to the
+    result, and undefined symbols in the object file are added to the set.
+
+  - If the linker visits an archive file, it checks for the archive file's
+    symbol table and extracts all object files that have definitions for any
+    symbols in the set.
+
+  This algorithm sometimes leads to a counter-intuitive behavior.  If you give
+  archive files before object files, nothing will happen because when the linker
+  visits archives, there is no undefined symbols in the set.  As a result, no
+  files are extracted from the first archive file, and the link is done at that
+  point because the set is empty after it visits one file.
 
   You can fix the problem by reordering the files,
   but that cannot fix the issue of mutually-dependent archive files.
 
-  Linking mutually-dependent archive files is tricky.
-  You may specify the same archive file multiple times to
-  let the linker visit it more than once.
-  Or, you may use the special command line options, `--start-group` and `--end-group`,
-  to let the linker loop over the files between the options until
+  Linking mutually-dependent archive files is tricky.  You may specify the same
+  archive file multiple times to let the linker visit it more than once.  Or,
+  you may use the special command line options, `--start-group` and
+  `--end-group`, to let the linker loop over the files between the options until
   no new symbols are added to the set.
 
   Visiting the same archive files multiple makes the linker slower.
 
-  Here is how LLD approaches the problem. Instead of memorizing only undefined symbols,
-  we program LLD so that it memorizes all symbols.
-  When it sees an undefined symbol that can be resolved by extracting an object file
-  from an archive file it previously visited, it immediately extracts the file and link it.
-  It is doable because LLD does not forget symbols it have seen in archive files.
+  Here is how LLD approaches the problem. Instead of memorizing only undefined
+  symbols, we program LLD so that it memorizes all symbols.  When it sees an
+  undefined symbol that can be resolved by extracting an object file from an
+  archive file it previously visited, it immediately extracts the file and link
+  it.  It is doable because LLD does not forget symbols it have seen in archive
+  files.
 
   We believe that the LLD's way is efficient and easy to justify.
 
-  The semantics of LLD's archive handling is different from the traditional Unix's.
-  You can observe it if you carefully craft archive files to exploit it.
-  However, in reality, we don't know any program that cannot link
-  with our algorithm so far, so it's not going to cause trouble.
+  The semantics of LLD's archive handling is different from the traditional
+  Unix's.  You can observe it if you carefully craft archive files to exploit
+  it.  However, in reality, we don't know any program that cannot link with our
+  algorithm so far, so it's not going to cause trouble.
 
 Numbers You Want to Know
 ------------------------
 
 To give you intuition about what kinds of data the linker is mainly working on,
 I'll give you the list of objects and their numbers LLD has to read and process
-in order to link a very large executable. In order to link Chrome with debug info,
-which is roughly 2 GB in output size, LLD reads
+in order to link a very large executable. In order to link Chrome with debug
+info, which is roughly 2 GB in output size, LLD reads
 
 - 17,000 files,
 - 1,800,000 sections,
 - 6,300,000 symbols, and
 - 13,000,000 relocations.
 
 LLD produces the 2 GB executable in 15 seconds.
 

 it would slow down the linker by 10%. So, don't do that.
 
 On the other hand, you don't have to pursue efficiency
 when handling files.
 
 Important Data Structures
 -------------------------
 
-We will describe the key data structures in LLD in this section.
-The linker can be understood as the interactions between them.
-Once you understand their functions, the code of the linker should look obvious to you.
+We will describe the key data structures in LLD in this section.  The linker can
+be understood as the interactions between them.  Once you understand their
+functions, the code of the linker should look obvious to you.
 
 * Symbol
 
   This class represents a symbol.
   They are created for symbols in object files or archive files.
   The linker creates linker-defined symbols as well.
 
   There are basically three types of Symbols: Defined, Undefined, or Lazy.
* Symbol
   defined symbol, because the undefined symbol the pointer pointed to will have
   been replaced by the defined symbol in-place.
 
 * SymbolTable
 
   SymbolTable is basically a hash table from strings to Symbols
   with logic to resolve symbol conflicts. It resolves conflicts by symbol type.
 
-  - If we add Defined and Undefined symbols, the symbol table will keep the former.
+  - If we add Defined and Undefined symbols, the symbol table will keep the
+    former.
   - If we add Defined and Lazy symbols, it will keep the former.
   - If we add Lazy and Undefined, it will keep the former,
     but it will also trigger the Lazy symbol to load the archive member
     to actually resolve the symbol.
 
 * Chunk (COFF specific)
 
   Chunk represents a chunk of data that will occupy space in an output.
* InputFile
 
   InputFile is a superclass of file readers.
   We have a different subclass for each input file type,
   such as regular object file, archive file, etc.
   They are responsible for creating and owning Symbols and InputSections/Chunks.
 
 * Writer
 
-  The writer is responsible for writing file headers and InputSections/Chunks to a file.
-  It creates OutputSections, put all InputSections/Chunks into them,
-  assign unique, non-overlapping addresses and file offsets to them,
-  and then write them down to a file.
+  The writer is responsible for writing file headers and InputSections/Chunks to
+  a file.  It creates OutputSections, put all InputSections/Chunks into them,
+  assign unique, non-overlapping addresses and file offsets to them, and then
+  write them down to a file.
 
 * Driver
 
   The linking process is driven by the driver. The driver:
 
   - processes command line options,
   - creates a symbol table,
-  - creates an InputFile for each input file and puts all symbols within into the symbol table,
+  - creates an InputFile for each input file and puts all symbols within into
+    the symbol table,
   - checks if there's no remaining undefined symbols,
   - creates a writer,
   - and passes the symbol table to the writer to write the result to a file.
 
 Link-Time Optimization
 ----------------------
 
 LTO is implemented by handling LLVM bitcode files as object files.

docs/sphinx_intro.rst

Windows
     page for instructions.
 
 
 .. _building_the_documentation:
 
 Building the documentation
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
-In order to build the documentation, all you should need to do is change to the
-``docs`` directory and invoke make as follows::
-
-  $ cd path/to/project/docs
-  $ make html
-
-Note that on Windows there is a ``make.bat`` command in the docs directory which
-supplies the same interface as the ``Makefile``.
-
-That command will invoke ``sphinx-build`` with the appropriate options for the
-project, and generate the HTML documentation in a ``_build`` subdirectory. You
-can browse it starting from the index page by visiting
-``_build/html/index.html``.
-
-Sphinx supports a wide variety of generation formats (including LaTeX, man
-pages, and plain text). The ``Makefile`` includes a number of convenience
-targets for invoking ``sphinx-build`` appropriately, the common ones are:
-
-  make html
-    Generate the HTML output.
-
-  make latexpdf
-    Generate LaTeX documentation and convert to a PDF.
-
-  make man
-    Generate man pages.
-
+In order to build the documentation need to add ``-DLLVM_ENABLE_SPHINX=ON`` to
+your ``cmake`` command.  Once you do this you can build the docs using
+``docs-lld-html`` build (``ninja`` or ``make``) target.
+
+That build target will invoke ``sphinx-build`` with the appropriate options for
+the project, and generate the HTML documentation in a ``tools/lld/docs/html``
+subdirectory.
 
 .. _writing_documentation:
 
 Writing documentation
 ~~~~~~~~~~~~~~~~~~~~~
 
-The documentation itself is written in the reStructuredText (ReST) format, and Sphinx
-defines additional tags to support features like cross-referencing.
+The documentation itself is written in the reStructuredText (ReST) format, and
+Sphinx defines additional tags to support features like cross-referencing.
 
 The ReST format itself is organized around documents mostly being readable
 plaintext documents. You should generally be able to write new documentation
 easily just by following the style of the existing documentation.
 
 If you want to understand the formatting of the documents more, the best place
 to start is Sphinx's own `ReST Primer <http://sphinx.pocoo.org/rest.html>`_.