Sort changelog into appropriate headings.

1 files changed, 242 insertions, 178 deletions

diff --git a/changelog.md b/changelog.md
index e8a0f893a..ad737acff 100644
--- a/changelog.md
+++ b/changelog.md
@@ -2,97 +2,40 @@
 
 ### Changes affecting backwards compatibility
 
+#### Breaking changes in the standard library
+
+- The ``[]`` proc for strings now raises an ``IndexError`` exception when
+  the specified slice is out of bounds. See issue
+  [#6223](https://github.com/nim-lang/Nim/issues/6223) for more details.
+  You can use ``substr(str, start, finish)`` to get the old behaviour back,
+  see [this commit](https://github.com/nim-lang/nimbot/commit/98cc031a27ea89947daa7f0bb536bcf86462941f) for an example.
+
+- ``strutils.split`` and ``strutils.rsplit`` with an empty string and a
+  separator now returns that empty string.
+  See issue [#4377](https://github.com/nim-lang/Nim/issues/4377).
 
 - Arrays of char cannot be converted to ``cstring`` anymore, pointers to
   arrays of char can! This means ``$`` for arrays can finally exist
   in ``system.nim`` and do the right thing.
-- ``echo`` now works with strings that contain ``\0`` (the binary zero is not
-  shown) and ``nil`` strings are equal to empty strings.
-- JSON: Deprecated `getBVal`, `getFNum`, and `getNum` in favour to
-  `getBool`, `getFloat`, `getBiggestInt`. Also `getInt` procedure was added.
+
 - `reExtended` is no longer default for the `re` constructor in the `re`
   module.
+
+- The behavior of ``$`` has been changed for all standard library collections. The
+  collection-to-string implementations now perform proper quoting and escaping of
+  strings and chars.
+
 - `newAsyncSocket` taking an `AsyncFD` now runs `setBlocking(false)` on the
   fd.
-- The `ReadyKey` type in the selectors module now contains an ``errorCode``
-  field to help distinguish between ``Event.Error`` events.
-- Implemented an `accept` proc that works on a `SocketHandle` in
-  ``nativesockets``.
-- Implemented ``getIoHandler`` proc in the ``asyncdispatch`` module that allows
-  you to retrieve the underlying IO Completion Port or ``Selector[AsyncData]``
-  object in the specified dispatcher.
-- The overloading rules changed slightly so that constrained generics are
-  preferred over unconstrained generics. (Bug #6526)
-- It is now possible to forward declare object types so that mutually
-  recursive types can be created across module boundaries. See
-  [package level objects](https://nim-lang.org/docs/manual.html#package-level-objects)
-  for more information.
-- The **unary** ``<`` is now deprecated, for ``.. <`` use ``..<`` for other usages
-  use the ``pred`` proc.
-- We changed how array accesses "from backwards" like ``a[^1]`` or ``a[0..^1]`` are
-  implemented. These are now implemented purely in ``system.nim`` without compiler
-  support. There is a new "heterogenous" slice type ``system.HSlice`` that takes 2
-  generic parameters which can be ``BackwardsIndex`` indices. ``BackwardsIndex`` is
-  produced by ``system.^``.
-  This means if you overload ``[]`` or ``[]=`` you need to ensure they also work
-  with ``system.BackwardsIndex`` (if applicable for the accessors).
+
 - ``mod`` and bitwise ``and`` do not produce ``range`` subtypes anymore. This
   turned out to be more harmful than helpful and the language is simpler
   without this special typing rule.
-- Added ``algorithm.rotateLeft``.
-- ``rationals.toRational`` now uses an algorithm based on continued fractions.
-  This means its results are more precise and it can't run into an infinite loop
-  anymore.
-- Added ``typetraits.$`` as an alias for ``typetraits.name``.
-- ``os.getEnv`` now takes an optional ``default`` parameter that tells ``getEnv``
-  what to return if the environment variable does not exist.
-- Bodies of ``for`` loops now get their own scope:
-
-```nim
-  # now compiles:
-  for i in 0..4:
-    let i = i + 1
-    echo i
-```
-
-- The parsing rules of ``if`` expressions were changed so that multiple
-  statements are allowed in the branches. We found few code examples that
-  now fail because of this change, but here is one:
-
-```nim
-  t[ti] = if exp_negative: '-' else: '+'; inc(ti)
-```
-
-This now needs to be written as:
-
-```nim
-  t[ti] = (if exp_negative: '-' else: '+'); inc(ti)
-```
-
-- To make Nim even more robust the system iterators ``..`` and ``countup``
-  now only accept a single generic type ``T``. This means the following code
-  doesn't die with an "out of range" error anymore:
-
-```nim
-  var b = 5.Natural
-  var a = -5
-  for i in a..b:
-    echo i
-```
 
 - ``formatFloat``/``formatBiggestFloat`` now support formatting floats with zero
   precision digits. The previous ``precision = 0`` behavior (default formatting)
   is now available via ``precision = -1``.
-- The ``nim doc`` command is now an alias for ``nim doc2``, the second version of
-  the documentation generator. The old version 1 can still be accessed
-  via the new ``nim doc0`` command.
-- Added ``system.getStackTraceEntries`` that allows you to access the stack
-  trace in a structured manner without string parsing.
-- Added ``sequtils.mapLiterals`` for easier construction of array and tuple
-  literals.
-- Added ``parseutils.parseSaturatedNatural``.
-- ``atomic`` and ``generic`` are no longer keywords in Nim. ``generic`` used to be
-  an alias for ``concept``, ``atomic`` was not used for anything.
+
 - Moved from stdlib into Nimble packages:
   - [``basic2d``](https://github.com/nim-lang/basic2d)
     _deprecated: use ``glm``, ``arraymancer``, ``neo``, or another package instead_
@@ -107,106 +50,121 @@ This now needs to be written as:
   - [``libsvm``](https://github.com/nim-lang/libsvm_legacy)
   - [``joyent_http_parser``](https://github.com/nim-lang/joyent_http_parser)
 
-- Added ``system.runnableExamples`` to make examples in Nim's documentation easier
-  to write and test. The examples are tested as the last step of
-  ``nim doc``.
-- Nim's ``rst2html`` command now supports the testing of code snippets via an RST
-  extension that we called ``:test:``::
+- Proc [toCountTable](https://nim-lang.org/docs/tables.html#toCountTable,openArray[A])
+  now produces a `CountTable` with values correspoding to the number of occurrences
+  of the key in the input. It used to produce a table with all values set to `1`.
 
-  ```rst
-    .. code-block:: nim
-        :test:
-      # shows how the 'if' statement works
-      if true: echo "yes"
+  Counting occurrences in a sequence used to be:
+
+  ```nim
+  let mySeq = @[1, 2, 1, 3, 1, 4]
+  var myCounter = initCountTable[int]()
+
+  for item in mySeq:
+    myCounter.inc item
   ```
-- The ``[]`` proc for strings now raises an ``IndexError`` exception when
-  the specified slice is out of bounds. See issue
-  [#6223](https://github.com/nim-lang/Nim/issues/6223) for more details.
-  You can use ``substr(str, start, finish)`` to get the old behaviour back,
-  see [this commit](https://github.com/nim-lang/nimbot/commit/98cc031a27ea89947daa7f0bb536bcf86462941f) for an example.
-- ``strutils.split`` and ``strutils.rsplit`` with an empty string and a
-  separator now returns that empty string.
-  See issue [#4377](https://github.com/nim-lang/Nim/issues/4377).
+
+  Now, you can simply do:
+
+  ```nim
+  let
+    mySeq = @[1, 2, 1, 3, 1, 4]
+    myCounter = mySeq.toCountTable()
+  ```
+
+- If you use ``--dynlibOverride:ssl`` with OpenSSL 1.0.x, you now have to
+  define ``openssl10`` symbol (``-d:openssl10``). By default OpenSSL 1.1.x is
+  assumed.
+
+- ``newNativeSocket`` is now named ``createNativeSocket``.
+
+- ``newAsyncNativeSocket`` is now named ``createAsyncNativeSocket``
+  and it no longer raises an OS error but returns an ``osInvalidSocket`` when
+  creation fails.
+
+- The ``securehash`` module is now deprecated. Instead import ``std / sha1``.
+
+- The ``readPasswordFromStdin`` proc has been moved from the ``rdstdin``
+  to the ``terminal`` module, thus it does not depend on linenoise anymore.
+
+#### Breaking changes in the compiler
+
+- ``\n`` is now only the single line feed character like in most
+  other programming languages. The new platform specific newline escape sequence is
+  written as ``\p``. This change only affects the Windows platform.
+
+- The overloading rules changed slightly so that constrained generics are
+  preferred over unconstrained generics. (Bug #6526)
+
+- We changed how array accesses "from backwards" like ``a[^1]`` or ``a[0..^1]`` are
+  implemented. These are now implemented purely in ``system.nim`` without compiler
+  support. There is a new "heterogenous" slice type ``system.HSlice`` that takes 2
+  generic parameters which can be ``BackwardsIndex`` indices. ``BackwardsIndex`` is
+  produced by ``system.^``.
+  This means if you overload ``[]`` or ``[]=`` you need to ensure they also work
+  with ``system.BackwardsIndex`` (if applicable for the accessors).
+
+- The parsing rules of ``if`` expressions were changed so that multiple
+  statements are allowed in the branches. We found few code examples that
+  now fail because of this change, but here is one:
+
+```nim
+t[ti] = if exp_negative: '-' else: '+'; inc(ti)
+```
+
+This now needs to be written as:
+
+```nim
+t[ti] = (if exp_negative: '-' else: '+'); inc(ti)
+```
+
 - The experimental overloading of the dot ``.`` operators now take
   an ``untyped``` parameter as the field name, it used to be
   a ``static[string]``. You can use ``when defined(nimNewDot)`` to make
   your code work with both old and new Nim versions.
   See [special-operators](https://nim-lang.org/docs/manual.html#special-operators)
   for more information.
-- Added ``macros.unpackVarargs``.
-- The memory manager now uses a variant of the TLSF algorithm that has much
-  better memory fragmentation behaviour. According
-  to [http://www.gii.upv.es/tlsf/](http://www.gii.upv.es/tlsf/) the maximum
-  fragmentation measured is lower than 25%. As a nice bonus ``alloc`` and
-  ``dealloc`` became O(1) operations.
-- The behavior of ``$`` has been changed for all standard library collections. The
-  collection-to-string implementations now perform proper quoting and escaping of
-  strings and chars.
-- The ``random`` procs in ``random.nim`` have all been deprecated. Instead use
-  the new ``rand`` procs. The module now exports the state of the random
-  number generator as type ``Rand`` so multiple threads can easily use their
-  own random number generators that do not require locking. For more information
-  about this rename see issue [#6934](https://github.com/nim-lang/Nim/issues/6934)
-- The compiler is now more consistent in its treatment of ambiguous symbols:
-  Types that shadow procs and vice versa are marked as ambiguous (bug #6693).
+
 - ``yield`` (or ``await`` which is mapped to ``yield``) never worked reliably
   in an array, seq or object constructor and is now prevented at compile-time.
+
+### Library additions
+
+- **Added ``sequtils.mapLiterals`` for easier construction of array and tuple literals.**
+
+- Added ``system.runnableExamples`` to make examples in Nim's documentation easier
+  to write and test. The examples are tested as the last step of
+  ``nim doc``.
+
+- Implemented ``getIoHandler`` proc in the ``asyncdispatch`` module that allows
+  you to retrieve the underlying IO Completion Port or ``Selector[AsyncData]``
+  object in the specified dispatcher.
+
 - For string formatting / interpolation a new module
   called [strformat](https://nim-lang.org/docs/strformat.html) has been added
   to the stdlib.
-- codegenDecl pragma now works for the JavaScript backend. It returns an empty string for
-  function return type placeholders.
-- Asynchronous programming for the JavaScript backend using the `asyncjs` module.
-- Extra semantic checks for procs with noreturn pragma: return type is not allowed,
-  statements after call to noreturn procs are no longer allowed.
-- Noreturn proc calls and raising exceptions branches are now skipped during common type
-  deduction in if and case expressions. The following code snippets now compile:
-```nim
-import strutils
-let str = "Y"
-let a = case str:
-  of "Y": true
-  of "N": false
-  else: raise newException(ValueError, "Invalid boolean")
-let b = case str:
-  of nil, "": raise newException(ValueError, "Invalid boolean")
-  elif str.startsWith("Y"): true
-  elif str.startsWith("N"): false
-  else: false
-let c = if str == "Y": true
-  elif str == "N": false
-  else:
-    echo "invalid bool"
-    quit("this is the end")
-```
-- Proc [toCountTable](https://nim-lang.org/docs/tables.html#toCountTable,openArray[A]) now produces a `CountTable` with values correspoding to the number of occurrences of the key in the input. It used to produce a table with all values set to `1`.
 
-Counting occurrences in a sequence used to be:
+- The `ReadyKey` type in the selectors module now contains an ``errorCode``
+  field to help distinguish between ``Event.Error`` events.
 
-```nim
-let mySeq = @[1, 2, 1, 3, 1, 4]
-var myCounter = initCountTable[int]()
+- Implemented an `accept` proc that works on a `SocketHandle` in
+  ``nativesockets``.
 
-for item in mySeq:
-  myCounter.inc item
-```
+- Added ``algorithm.rotateLeft``.
 
-Now, you can simply do:
+- Added ``typetraits.$`` as an alias for ``typetraits.name``.
 
-```nim
-let
-  mySeq = @[1, 2, 1, 3, 1, 4]
-  myCounter = mySeq.toCountTable()
-```
+- Added ``system.getStackTraceEntries`` that allows you to access the stack
+  trace in a structured manner without string parsing.
 
-- Added support for casting between integers of same bitsize in VM (compile time and nimscript).
-  This allow to among other things to reinterpret signed integers as unsigned.
+- Added ``parseutils.parseSaturatedNatural``.
+
+- Added ``macros.unpackVarargs``.
 
-- Pragmas now support call syntax, for example: ``{.exportc"myname".}`` and ``{.exportc("myname").}``
-- Custom pragmas are now supported using pragma ``pragma``, please see language manual for details
+- Added support for asynchronous programming for the JavaScript backend using
+  the `asyncjs` module.
 
-- Added True Color support for some terminals
-  Example:
+- Added true color support for some terminals. Example:
 ```nim
 import colors, terminal
 
@@ -228,41 +186,147 @@ setForegroundColor colRed
 setBackgroundColor colGreen
 styledEcho "Red on Green.", resetStyle
 ```
-- If you use ``--dynlibOverride:ssl`` with OpenSSL 1.0.x, you now have to
-  define ``openssl10`` symbol (``-d:openssl10``). By default OpenSSL 1.1.x is
-  assumed.
 
-- ``writeStackTrace`` is now proclaimed to have no IO effect (even though it does)
-  so that it is more useful for debugging purposes.
-- ``\n`` is now only the single line feed character like in most
-  other programming languages. The new platform specific newline escape sequence is
-  written as ``\p``. This change only affects the Windows platform.
-- ``newAsyncNativeSocket`` is now named ``createAsyncNativeSocket``
-  and it no longer raises an OS error but returns an ``osInvalidSocket`` when
-  creation fails.
-- ``newNativeSocket`` is now named ``createNativeSocket``.
-- The ``deprecated`` pragma now supports a user-definable warning message for procs.
+### Library changes
 
-```nim
+- ``echo`` now works with strings that contain ``\0`` (the binary zero is not
+  shown) and ``nil`` strings are equal to empty strings.
 
-proc bar {.deprecated: "use foo instead".} =
-  return
+- JSON: Deprecated `getBVal`, `getFNum`, and `getNum` in favour of
+  `getBool`, `getFloat`, `getBiggestInt`. A new `getInt` procedure was also
+  added.
 
-bar()
-```
+- ``rationals.toRational`` now uses an algorithm based on continued fractions.
+  This means its results are more precise and it can't run into an infinite loop
+  anymore.
+
+- ``os.getEnv`` now takes an optional ``default`` parameter that tells ``getEnv``
+  what to return if the environment variable does not exist.
+
+- The ``random`` procs in ``random.nim`` have all been deprecated. Instead use
+  the new ``rand`` procs. The module now exports the state of the random
+  number generator as type ``Rand`` so multiple threads can easily use their
+  own random number generators that do not require locking. For more information
+  about this rename see issue [#6934](https://github.com/nim-lang/Nim/issues/6934)
+
+- ``writeStackTrace`` is now proclaimed to have no IO effect (even though it does)
+  so that it is more useful for debugging purposes.
 
-- The ``securehash`` module is now deprecated. Instead import ``std / sha1``.
 - ``db_mysql`` module: ``DbConn`` is now a ``distinct`` type that doesn't expose the
   details of the underlying ``PMySQL`` type.
+
+### Language additions
+
+- It is now possible to forward declare object types so that mutually
+  recursive types can be created across module boundaries. See
+  [package level objects](https://nim-lang.org/docs/manual.html#package-level-objects)
+  for more information.
+
+- Added support for casting between integers of same bitsize in VM (compile time and nimscript).
+  This allows to, among other things, reinterpret signed integers as unsigned.
+
+- Custom pragmas are now supported using pragma ``pragma``, please see language
+  manual for details.
+
 - Standard library modules can now also be imported via the ``std`` pseudo-directory.
   This is useful in order to distinguish between standard library and nimble package
   imports:
 
+  ```nim
+  import std / [strutils, os, osproc]
+  import someNimblePackage / [strutils, os]
+  ```
+
+### Language changes
+
+- The **unary** ``<`` is now deprecated, for ``.. <`` use ``..<`` for other usages
+  use the ``pred`` proc.
+
+- Bodies of ``for`` loops now get their own scope:
+
 ```nim
+# now compiles:
+for i in 0..4:
+  let i = i + 1
+  echo i
+```
+
+- To make Nim even more robust the system iterators ``..`` and ``countup``
+  now only accept a single generic type ``T``. This means the following code
+  doesn't die with an "out of range" error anymore:
 
-import std / [strutils, os, osproc]
-import someNimblePackage / [strutils, os]
+```nim
+var b = 5.Natural
+var a = -5
+for i in a..b:
+  echo i
 ```
 
-- The ``readPasswordFromStdin`` proc has been moved from the ``rdstdin``
-  to the ``terminal`` module, thus it does not depend on linenoise anymore.
+- ``atomic`` and ``generic`` are no longer keywords in Nim. ``generic`` used to be
+  an alias for ``concept``, ``atomic`` was not used for anything.
+
+- The memory manager now uses a variant of the TLSF algorithm that has much
+  better memory fragmentation behaviour. According
+  to [http://www.gii.upv.es/tlsf/](http://www.gii.upv.es/tlsf/) the maximum
+  fragmentation measured is lower than 25%. As a nice bonus ``alloc`` and
+  ``dealloc`` became O(1) operations.
+
+- The compiler is now more consistent in its treatment of ambiguous symbols:
+  Types that shadow procs and vice versa are marked as ambiguous (bug #6693).
+
+- codegenDecl pragma now works for the JavaScript backend. It returns an empty
+  string for function return type placeholders.
+
+- Extra semantic checks for procs with noreturn pragma: return type is not allowed,
+  statements after call to noreturn procs are no longer allowed.
+
+- Noreturn proc calls and raising exceptions branches are now skipped during common type
+  deduction in ``if`` and ``case`` expressions. The following code snippets now compile:
+  ```nim
+  import strutils
+  let str = "Y"
+  let a = case str:
+    of "Y": true
+    of "N": false
+    else: raise newException(ValueError, "Invalid boolean")
+  let b = case str:
+    of nil, "": raise newException(ValueError, "Invalid boolean")
+    elif str.startsWith("Y"): true
+    elif str.startsWith("N"): false
+    else: false
+  let c = if str == "Y": true
+    elif str == "N": false
+    else:
+      echo "invalid bool"
+      quit("this is the end")
+  ```
+
+- Pragmas now support call syntax, for example: ``{.exportc"myname".}`` and
+  ``{.exportc("myname").}``
+
+- The ``deprecated`` pragma now supports a user-definable warning message for procs.
+
+  ```nim
+  proc bar {.deprecated: "use foo instead".} =
+    return
+
+  bar()
+  ```
+
+### Tool changes
+
+- The ``nim doc`` command is now an alias for ``nim doc2``, the second version of
+  the documentation generator. The old version 1 can still be accessed
+  via the new ``nim doc0`` command.
+
+- Nim's ``rst2html`` command now supports the testing of code snippets via an RST
+  extension that we called ``:test:``::
+
+  ```rst
+  .. code-block:: nim
+      :test:
+    # shows how the 'if' statement works
+    if true: echo "yes"
+  ```
+
+### Compiler changes