Merge pull request #5079 from ethereum/usingUpdate

[DOCS] Update "using the compiler".

docs/using-the-compiler.rst

@@ -10,13 +10,17 @@ Using the Commandline Compiler
 ******************************
 
 .. note::
-    This section doesn't apply to :ref:`solcjs <solcjs>`.
+    This section does not apply to :ref:`solcjs <solcjs>`, not even if it is used in commandline mode.
 
 One of the build targets of the Solidity repository is ``solc``, the solidity commandline compiler.
 Using ``solc --help`` provides you with an explanation of all options. The compiler can produce various outputs, ranging from simple binaries and assembly over an abstract syntax tree (parse tree) to estimations of gas usage.
 If you only want to compile a single file, you run it as ``solc --bin sourceFile.sol`` and it will print the binary. If you want to get some of the more advanced output variants of ``solc``, it is probably better to tell it to output everything to separate files using ``solc -o outputDirectory --bin --ast --asm sourceFile.sol``.
 
-Before you deploy your contract, activate the optimizer while compiling using ``solc --optimize --bin sourceFile.sol``. By default, the optimizer will optimize the contract for 200 runs. If you want to optimize for initial contract deployment and get the smallest output, set it to ``--runs=1``. If you expect many transactions and don't care for higher deployment cost and output size, set ``--runs`` to a high number.
+Before you deploy your contract, activate the optimizer when compiling using ``solc --optimize --bin sourceFile.sol``.
+By default, the optimizer will optimize the contract assuming it is called 200 times across its lifetime.
+If you want the initial contract deployment to be cheaper and the later function executions to be more expensive,
+set it to ``--runs=1``. If you expect many transactions and do not care for higher deployment cost and
+output size, set ``--runs`` to a high number.
 
 The commandline compiler will automatically read imported files from the filesystem, but
 it is also possible to provide path redirects using ``prefix=path`` in the following way:
@@ -43,7 +47,7 @@ Either add ``--libraries "Math:0x12345678901234567890 Heap:0xabcdef0123456"`` to
 
 If ``solc`` is called with the option ``--link``, all input files are interpreted to be unlinked binaries (hex-encoded) in the ``__LibraryName____``-format given above and are linked in-place (if the input is read from stdin, it is written to stdout). All options except ``--libraries`` are ignored (including ``-o``) in this case.
 
-If ``solc`` is called with the option ``--standard-json``, it will expect a JSON input (as explained below) on the standard input, and return a JSON output on the standard output.
+If ``solc`` is called with the option ``--standard-json``, it will expect a JSON input (as explained below) on the standard input, and return a JSON output on the standard output. This is the recommended interface for more complex and especially automated uses.
 
 .. _evm-version:
 .. index:: ! EVM version, compile target
@@ -60,18 +64,23 @@ version to compile for to avoid particular features or behaviours.
    behaviour. Please ensure, especially if running a private chain, that you
    use matching EVM versions.
 
-You use the ``--evm-version`` option on the command line:
+On the command line, you can select the EVM version as follows:
 
 .. code-block:: shell
 
   solc --evm-version <VERSION> contract.sol
 
-Or if using the :ref:`standard JSON interface <compiler-api>`, with the ``evmVersion`` key:
+In the :ref:`standard JSON interface <compiler-api>`, use the ``"evmVersion"``
+key in the ``"settings"`` field:
 
-.. code-block:: json
+.. code-block:: none
 
   {
-    "evmVersion": "<VERSION>"
+    "sources": { ... },
+    "settings": {
+      "optimizer": { ... },
+      "evmVersion": "<VERSION>"
+    }
   }
 
 Target options
@@ -80,7 +89,7 @@ Target options
 Below is a list of target EVM versions and the compiler-relevant changes introduced
 at each version. Backward compatibility is not guaranteed between each version.
 
-- ``homestead``
+- ``homestead`` (oldest version)
 - ``tangerineWhistle``
    - gas cost for access to other accounts increased, relevant for gas estimation and the optimizer.
    - all gas sent by default for external calls, previously a certain amount had to be retained.
@@ -88,7 +97,7 @@ at each version. Backward compatibility is not guaranteed between each version.
    - gas cost for the ``exp`` opcode increased, relevant for gas estimation and the optimizer.
 - ``byzantium`` (**default**)
    - opcodes ``returndatacopy``, ``returndatasize`` and ``staticcall`` are available in assembly.
-   - the ``staticcall`` opcode is used when calling view or pure functions, which prevents the functions from modifying state at the EVM level, i.e., even applies when you use invalid type conversions.
+   - the ``staticcall`` opcode is used when calling non-library view or pure functions, which prevents the functions from modifying state at the EVM level, i.e., even applies when you use invalid type conversions.
    - it is possible to access dynamic data returned from function calls.
    - ``revert`` opcode introduced, which means that ``revert()`` will not waste gas.
 - ``constantinople`` (still in progress)
@@ -100,11 +109,16 @@ at each version. Backward compatibility is not guaranteed between each version.
 Compiler Input and Output JSON Description
 ******************************************
 
-These JSON formats are used by the compiler API as well as are available through ``solc``. These are subject to change,
-some fields are optional (as noted), but it is aimed at to only make backwards compatible changes.
+The recommended way to interface with the Solidity compiler especially for
+more complex and automated setups is the so-called JSON-input-output interface.
+The same interface is provided by all distributions of the compiler.
+
+The fields are generally subject to change,
+some are optional (as noted), but we try to only make backwards compatible changes.
 
 The compiler API expects a JSON formatted input and outputs the compilation result in a JSON formatted output.
 
+The following subsections describe the format through an example.
 Comments are of course not permitted and used here only for explanatory purposes.
 
 Input Description
@@ -113,7 +127,7 @@ Input Description
 .. code-block:: none
 
     {
-      // Required: Source code language, such as "Solidity", "serpent", "lll", "assembly", etc.
+      // Required: Source code language, such as "Solidity", "Vyper", "lll", "assembly", etc.
       language: "Solidity",
       // Required
       sources: