documentation updates

doc/backends.rst

@@ -332,55 +332,6 @@ name for the directory depends on the used backend and on your OS but you can
 use the ``--nimcache`` `compiler switch <nimc.html#command-line-switches>`_ to
 change it.
 
-Nimcache and C like targets
-~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-The C like backends will place their temporary ``.c``, ``.cpp`` or ``.m`` files
-in the ``nimcache`` directory. The naming of these files follows the pattern
-``nimblePackageName_`` + ``nimSource``:
-
-* Filenames for modules imported from `nimble packages
-  <https://github.com/nim-lang/nimble>`_ will end up with
-  ``nimblePackageName_module.c``. For example, if you import the
-  ``argument_parser`` module from the same name nimble package you
-  will end up with a ``argument_parser_argument_parser.c`` file
-  under ``nimcache``.  The name of the nimble package comes from the
-  ``proj.nimble`` file, the actual contents are not read by the
-  compiler.
-
-* Filenames for non nimble packages (like your project) will be
-  renamed from ``.nim`` to have the extension of your target backend
-  (from now on ``.c`` for these examples), but otherwise nothing
-  else will change. This will quickly break if your project consists
-  of a main ``proj.nim`` file which includes a ``utils/proj.nim``
-  file: both ``proj.nim`` files will generate the same name ``proj.c``
-  output in the ``nimcache`` directory overwriting themselves!
-
-* Filenames for modules found in the standard library will be named
-  ``stdlib_module.c``. Unless you are doing something special, you
-  will end up with at least ``stdlib_system.c``, since the `system
-  module <system.html>`_ is always imported automatically. Same for
-  the `hashes module <hashes.html>`_ which will be named
-  ``stdlib_hashes.c``. The ``stdlib_`` prefix comes from the *fake*
-  ``lib/stdlib.nimble`` file.
-
-To find the name of a nimble package the compiler searches for a ``*.nimble``
-file in the parent directory hierarchy of whatever module you are compiling.
-Even if you are in a subdirectory of your project, a parent ``*.nimble`` file
-will influence the naming of the nimcache name. This means that on Unix systems
-creating the file ``~/foo.nimble`` will automatically prefix all nimcache files
-not part of another package with the string ``foo_``.
-
-
-Nimcache and the Javascript target
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-
-Unless you explicitly use the ``-o:filename.js`` switch as mentioned in the
-previous examples, the compiler will create a ``filename.js`` file in the
-``nimcache`` directory using the name of your input nim file. There are no
-other temporary files generated, the output is always a single self contained
-``.js`` file.
-
 
 Memory management
 =================

doc/nimc.rst

@@ -17,7 +17,7 @@ Introduction
 
 This document describes the usage of the *Nim compiler*
 on the different supported platforms. It is not a definition of the Nim
-programming language (therefore is the `manual <manual.html>`_).
+programming language (which is covered in the `manual <manual.html>`_).
 
 Nim is free software; it is licensed under the
 `MIT License <http://www.opensource.org/licenses/mit-license.php>`_.
@@ -197,9 +197,8 @@ directory structure looks like this::
   other.nim
 
 And ``main`` imports ``x``, ``foo/x`` is imported. If ``other`` imports ``x``
-then both ``$lib/x.nim`` and ``$lib/bar/x.nim`` match and so the compiler
+then both ``$lib/x.nim`` and ``$lib/bar/x.nim`` match but ``$lib/x.nim`` is used
-should reject it. Currently however this check is not implemented and instead
+as it is the first match.
-the first matching file is used.
 
 
 Generated C code directory
@@ -213,10 +212,7 @@ The generated files that Nim produces all go into a subdirectory called
 
 The ``_r`` suffix is used for release builds, ``_d`` is for debug builds.
 
-This makes it easy to delete all
+This makes it easy to delete all generated files.
-generated files. Files generated in this directory follow a naming logic which
-you can read about in the `Nim Backend Integration document
-<backends.html#nimcache-naming-logic>`_.
 
 The ``--nimcache``
 `compiler switch <nimc.html#command-line-switches>`_ can be used to
@@ -281,16 +277,17 @@ The MinGW-w64 toolchain can be installed as follows::
   CentOS: yum install mingw32-gcc | mingw64-gcc - requires EPEL
   OSX: brew install mingw-w64
 
+
 Cross compilation for Android
 =============================
 
 There are two ways to compile for Android: terminal programs (Termux) and with
 the NDK (Android Native Development Kit).
 
-First one is to treat Android as a simple linux and use
+First one is to treat Android as a simple Linux and use
-`Termux <https://wiki.termux.com>`_ to connect and run the nim compiler
+`Termux <https://wiki.termux.com>`_ to connect and run the Nim compiler
-directly on android as if it was linux. These programs are console only
+directly on android as if it was Linux. These programs are console only
-programs that can’t be distributed in the Play Store.
+programs that can't be distributed in the Play Store.
 
 Use regular ``nim c`` inside termux to make Android terminal programs.
 
@@ -303,45 +300,51 @@ to have the Java stub be auto generated for you.
 Use ``nim c -c --cpu:arm --os:android -d:androidNDK --noMain:on`` to
 generate the C source files you need to include in your Android Studio
 project. Add the generated C files to CMake build script in your Android
-project. Then do the final compile with Android Studio which uses gradle
+project. Then do the final compile with Android Studio which uses Gradle
 to call CMake to compile the project.
 
-Because nim is part of a library it can’t have its own c style `main()`
+Because Nim is part of a library it can't have its own c style ``main()``
-so you would need to define your own `android_main` and init the java
+so you would need to define your own ``android_main`` and init the Java
-environment, or use a library like SDL2 or GLFM to do it. After android
+environment, or use a library like SDL2 or GLFM to do it. After the Android
-stuff is done, It’s very important to call `NimMain()` to nim’s initialize
+stuff is done, it's very important to call ``NimMain()`` in order to
-garbage collector memory, types and stack.
+initialize Nim's garbage collector and to run the top level statements
+of your program.
 
 .. code-block:: Nim
+
   proc NimMain() {.importc.}
   proc glfmMain*(display: ptr GLFMDisplay) {.exportc.} =
     NimMain() # initialize garbage collector memory, types and stack
 
+
 Cross compilation for iOS
 =========================
 
 To cross compile for iOS you need to be on a MacOS computer and use XCode.
-Normal languages for iOS development is Swift or Objective C. Both of these
+Normal languages for iOS development are Swift and Objective C. Both of these
-use llvm and can be compiled into object files linked together with C, C++
+use LLVM and can be compiled into object files linked together with C, C++
 or Objective C code produced by Nim.
 
 Use ``nim c -c --os:ios --noMain:on`` to generate C files and include them in
-your XCode project. Then you can use XCode to compile, link, package and code
+your XCode project. Then you can use XCode to compile, link, package and
 sign everything.
 
-Because nim is part of a library it can’t have its own c style `main()` so you
+Because Nim is part of a library it can't have its own c style ``main()`` so you
-would need to define `main` that calls `autoreleasepool` and
+would need to define `main` that calls ``autoreleasepool`` and
-`UIApplicationMain` to do it, or use a library like SDL2 or GLFM. After iOS
+``UIApplicationMain`` to do it, or use a library like SDL2 or GLFM. After
-stuff is done, it's very important to call `NimMain()` to nim’s initialize
+the iOS setup is done, it's very important to call ``NimMain()`` in order to
-garbage collector memory, types and stack.
+initialize Nim's garbage collector and to run the top level statements
+of your program.
 
 .. code-block:: Nim
+
   proc NimMain() {.importc.}
   proc glfmMain*(display: ptr GLFMDisplay) {.exportc.} =
     NimMain() # initialize garbage collector memory, types and stack
 
 Note: XCodes "make clean" gets confused about the genreated nim.c files,
-so you need to clean those with `rm` manually to do a clean build.
+so you need to clean those files manually to do a clean build.
+
 
 Cross compilation for Nintendo Switch
 =====================================