Polish documentation for System Principles after migration

system/doc/system_principles/create_target.md

@@ -41,11 +41,9 @@ functionality:
 
 - A _basic target system_ that can be started by calling the ordinary `erl`
   script.
-- A _simple target system_ where also code replacement in runtime can be
-  performed.
-- An _embedded target system_ where there is also support for logging output
-  from the system to file for later inspection, and where the system can be
-  started automatically at boot time.
+- A _simple target system_ that also supports code replacement in runtime.
+- An _embedded target system_ that also supports starting automatically
+  at boot time, and logging output from the system files for later inspection.
 
 Here is only considered the case when Erlang/OTP is running on a UNIX system.
 
@@ -86,10 +84,11 @@ _Step 2._ Start Erlang/OTP from the directory where the `mysystem.rel` file
 resides:
 
 ```text
-os> erl -pa /home/user/target_system/myapps/pea-1.0/ebin
+% erl -pa /home/user/target_system/myapps/pea-1.0/ebin
 ```
 
-Here also the path to the `pea-1.0` ebin directory is provided.
+The `-pa` argument prepends the the path to the `ebin` directory for
+the Pea application to the code path.
 
 _Step 3._ Create the target system:
 
@@ -99,13 +98,15 @@ _Step 3._ Create the target system:
 
 The function `target_system:create/1` performs the following:
 
-1. Reads the file `mysystem.rel` and creates a new file `plain.rel` that is
-   identical to the former, except that it only lists the Kernel and STDLIB
-   applications.
+1. Reads the file `mysystem.rel` and creates a new file `plain.rel`.
+   The new file is identical to the original, except that it only
+   lists the Kernel and STDLIB applications.
+
 1. From the files `mysystem.rel` and `plain.rel` creates the files
-   `mysystem.script`, `mysystem.boot`, `plain.script`, and `plain.boot` through
-   a call to `systools:make_script/2`.
-1. Creates the file `mysystem.tar.gz` by a call to `systools:make_tar/2`. That
+   `mysystem.script`, `mysystem.boot`, `plain.script`, and `plain.boot`
+   by calling `systools:make_script/2`.
+
+1. Creates the file `mysystem.tar.gz` by calling `systools:make_tar/2`. That
    file has the following contents:
 
 ```text
@@ -126,9 +127,9 @@ Originally, this file was only stored in the `releases` directory to make it
 possible for the `release_handler` to extract this file separately. After
 unpacking the tar file, `release_handler` would automatically copy the file to
 `releases/FIRST`. However, sometimes the tar file is unpacked without involving
-the `release_handler` (for example, when unpacking the first target system). The
-file is therefore now instead duplicated in the tar file so no manual copying is
-needed.
+the `release_handler` (for example, when unpacking the first target system).
+Hence, the file is now duplicated within the tar archive, eliminating the
+need for manual copying.
 
 1. Creates the temporary directory `tmp` and extracts the tar file
    `mysystem.tar.gz` into that directory.
@@ -174,7 +175,7 @@ Now we have a target system that can be started in various ways. We start it as
 a _basic target system_ by invoking:
 
 ```text
-os> /usr/local/erl-target/bin/erl
+% /usr/local/erl-target/bin/erl
 ```
 
 Here only the Kernel and STDLIB applications are started, that is, the system is
@@ -190,7 +191,7 @@ To start all applications specified in the original `mysystem.rel` file, use
 flag `-boot` as follows:
 
 ```text
-os> /usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start
+% /usr/local/erl-target/bin/erl -boot /usr/local/erl-target/releases/FIRST/start
 ```
 
 We start a _simple target system_ as above. The only difference is that also the
@@ -200,8 +201,8 @@ To start an _embedded target system_, the shell script `bin/start` is used. The
 script calls `bin/run_erl`, which in turn calls `bin/start_erl` (roughly,
 `start_erl` is an embedded variant of `erl`).
 
-The shell script `start`, which is generated from erts-5.10.4/bin/start.src
-during installation, is only an example. Edit it to suite your needs. Typically
+The shell script `start`, which is generated from `erts-5.10.4/bin/start.src`
+during installation, is merely an example. Edit it to suite your needs. Typically
 it is executed when the UNIX system boots.
 
 `run_erl` is a wrapper that provides logging of output from the runtime system
@@ -274,8 +275,8 @@ _Step 1._ Create the file `.rel`:
   {pea, "2.0"}]}.
 ```
 
-_Step 2._ Create the application upgrade file (see the
-[appup(4)](`e:sasl:appup.md`) manual page in SASL) for Pea, for example:
+_Step 2._ Create the application upgrade file (see
+[appup](`e:sasl:appup.md`) in SASL) for Pea, for example:
 
 ```erlang
 %% pea.appup
@@ -288,11 +289,11 @@ _Step 3._ From the directory where the file `mysystem2.rel` resides, start the
 Erlang/OTP system, giving the path to the new version of Pea:
 
 ```text
-os> erl -pa /home/user/target_system/myapps/pea-2.0/ebin
+% erl -pa /home/user/target_system/myapps/pea-2.0/ebin
 ```
 
-_Step 4._ Create the release upgrade file (see the [relup(4)](`e:sasl:relup.md`)
-manual page in SASL):
+_Step 4._ Create the release upgrade file (see [relup](`e:sasl:relup.md`)
+in SASL):
 
 ```text
 1> systools:make_relup("mysystem2",["mysystem"],["mysystem"],
@@ -352,19 +353,19 @@ Finally, to prepare the upgrade, we must put the new release package in the
 `releases` directory of the first target system:
 
 ```text
-os> cp mysystem2.tar.gz /usr/local/erl-target/releases
+% cp mysystem2.tar.gz /usr/local/erl-target/releases
 ```
 
 Assuming that the node has been started as follows:
 
 ```text
-os> /usr/local/erl-target/bin/start
+% /usr/local/erl-target/bin/start
 ```
 
 It can be accessed as follows:
 
 ```text
-os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.1
+% /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.1
 ```
 
 Logs can be found in `/usr/local/erl-target/log`. This directory is specified as
@@ -395,12 +396,12 @@ information, see [Upgrade when Erlang/OTP has Changed](upgrade.md).
 The node is accessible through a new pipe:
 
 ```text
-os> /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2
+% /usr/local/erl-target/bin/to_erl /tmp/erlang.pipe.2
 ```
 
-Check which releases there are in the system:
+List the available releases in the system:
 
-```c
+```erlang
 1> release_handler:which_releases().
 [{"MYSYSTEM","SECOND",
   ["kernel-3.0","stdlib-2.0","sasl-2.4","pea-2.0"],

system/doc/system_principles/error_logging.md

@@ -25,7 +25,7 @@ limitations under the License.
 
 Error information from the runtime system, that is, information about a process
 terminating because of an uncaught error exception, is by default written to
-terminal (tty):
+the terminal (TTY):
 
 ```text
 =ERROR REPORT==== 9-Dec-2003::13:25:02 ===
@@ -41,7 +41,7 @@ The exit reasons (such as `badarg`) used by the runtime system are described in
 For information about Logger and its user interface, see the `m:logger` manual
 page and the [Logging](`e:kernel:logger_chapter.md`) section in the Kernel
 User's Guide. The system can be configured so that log events are written to
-file or to tty, or both. In addition, user-defined applications can send and
+file or to the TTY, or both. In addition, user-defined applications can send and
 format log events using Logger.
 
 ## Log events from OTP behaviours

system/doc/system_principles/misc.md

@@ -21,31 +21,34 @@ limitations under the License.
 
 ## Introduction
 
-This document describes strategy regarding supported Releases, compatibility,
-deprecations and removal of functionality. This document was introduced in
-OTP 21. Actions taken regarding these issues before OTP 21 did not adhere this
-document.
+This document describes the strategy regarding supported Releases,
+compatibility, deprecations, and removal of functionality.
+
+> #### Change {: .info }
+>
+> This document and the strategy it describes was introduced in
+> Erlang/OTP 21.
 
 [](){: #supported_releases }
 
 ## Supported Releases
 
 In general, bugs are only fixed on the latest
 [release](versions.md#releases_and_patches), and new features are introduced in
-the upcoming release that is under development. However, when we, due to
+the upcoming release that is under development. However, when we, for
 internal reasons, fix bugs on older releases, these will be available and
 announced as well.
 
-Due to the above, pull requests are only accepted on the `maint` and the
-`master` branches in our [git repository](https://github.com/erlang/otp). The
-`maint` branch contains changes planned for the next
-[maintenance patch package](versions.md#releases_and_patches) on the latest OTP
-release and the `master` branch contain changes planned for the upcoming OTP
-release.
+Pull requests are only accepted on the `maint` and the `master`
+branches in our [git repository](https://github.com/erlang/otp). The
+`maint` branch contains changes planned for the next [maintenance
+patch package](versions.md#releases_and_patches) on the latest OTP
+release and the `master` branch contain changes planned for the
+upcoming OTP release.
 
 ## Compatibility
 
-We always strive to remain as compatible as possible even in the cases where we
+We strive to remain as compatible as possible, even in cases where we
 give no compatibility guarantees.
 
 Different parts of the system will be handled differently regarding
@@ -55,8 +58,10 @@ are handled.
 - **Erlang Distribution** - Erlang nodes can communicate across at least two
   preceding and two subsequent releases.
 
-- **Compiled BEAM Code, NIF Libraries and Drivers** - Compiled code can be
-  loaded on at least two subsequent releases.
+- **Compiled BEAM Code, NIF Libraries, and Drivers** - Compiled code
+  can be loaded on at least two subsequent releases. To achive the
+  highest possible performance for Erlang code, ensure it is compiled
+  using the same release as the one it will be deployed on.
 
   Loading on previous releases is _not_ supported.
 
@@ -79,38 +84,55 @@ might trigger incompatible changes like this are:
 - **Bug Fixes** - We will not be bug-compatible. A bug fix might introduce
   incompatible changes. This kind of incompatibility might occur in a patch.
 
-- **Severe Previous Design Issues** - Some parts of OTP were designed a very
-  long time ago and did not necessarily take today's computing environments into
-  account. In some cases the consequences of those design decisions are too
-  severe. This may be performance wise, scalability wise, etc. If we deem the
-  consequences too severe, we might introduce incompatible changes. This kind of
-  incompatibility will not be introduced in a patch, but instead in the next
-  release.
+- **Severe Previous Design Issues** - Some parts of OTP were designed
+  a very long time ago and did not necessarily take today's computing
+  environments into account. Consequently, the ramifications of these
+  design choices can be quite significant, impacting performance,
+  scalability, and more. If we determine that these consequences are
+  too substantial, we may implement incompatible changes. Such changes
+  are never introduced in a patch, but in the subsequent release.
 
 Peripheral, trace, and debug functionality is at greater risk of being changed
 in an incompatible way than functionality in the language itself and core
 libraries used during operation.
 
+There is a page in the documentation regarding incompatibilities:
+
+* [Upcoming Potential Incompatibilities](`e:general_info:upcoming_incompatibilities.md`) -
+  lists all upcoming potential incompatibilities.
+
 ## Deprecation
 
-Functionality is deprecated when new functionality is introduced that is
-preferred to be used instead of the old functionality that is being deprecated.
-The deprecation does _not_ imply removal of the functionality unless an upcoming
-removal is explicitly stated in the deprecation.
+Deprecation of functionality occurs when newer, preferred alternatives
+are introduced. The deprecation does **not** imply future removal of the
+functionality unless an upcoming removal is explicitly stated in the
+deprecation notice.
+
+Deprecated functionality will be documented as deprecated and highlighted
+in a release note as early possible. If appropriate, the compiler will
+issue warnings when the deprecated functionality is used.
+
+There is a page in the documentation regarding deprecations:
 
-Deprecated functionality will be documented as deprecated, and compiler warnings
-will be issued, when appropriate, as early as possible. That is, the new
-preferred functionality will appear at the same time as the deprecation is
-issued. A new deprecation will at least be announced in a release note and the
-documentation.
+* [Deprecations](`e:general_info:deprecations.md`) - lists all
+  deprecated functionality.
 
 ## Removal
 
-Legacy solutions may eventually need to be removed. In such cases, they will be
-phased out on a long enough time period to give users the time to adapt. Before
-removal of functionality it will be deprecated at least during one release with
-an explicit announcement about the upcoming removal. A new deprecation will at
-least be announced in a release note and the documentation.
+It can become necessary to remove legacy solutions. In such instances,
+they will be gradually phased out over a sufficient period to allow
+users to adjust. Before functionality is removed, it will be
+deprecated for at least one release, with an explicit announcement
+about the upcoming removal.
 
 Peripheral, trace, and debug functionality is at greater risk of removal than
 functionality in the language itself and core libraries used during operation.
+
+There are two pages in the documentation regarding removal:
+
+* [Scheduled for Removal](`e:general_info:scheduled_for_removal.md`) - lists
+  all functionality that is schedule for removal in upcoming releases.
+
+* [Removed Functionality](`e:general_info:removed.md`) - lists
+  functionality that has been removed.
+