Update introduction

doc/system/introduction.adoc

@@ -1,6 +1,6 @@
 ////
 Copyright 2003-2017 Beman Dawes
-Copyright 2018 Peter Dimov
+Copyright 2018, 2021 Peter Dimov
 
 Distributed under the Boost Software License, Version 1.0.
 
@@ -12,39 +12,67 @@ http://www.boost.org/LICENSE_1_0.txt
 # Introduction
 :idprefix: intro_
 
-Error conditions originating from the operating system or other low-level
-application program interfaces (API's) are typically reported via an integer
-representing an error code. When these low-level API calls are wrapped in
-portable code, such as in a portable library, some users want to deal with the
-error codes in portable ways. Other users need to get at the system specific
-error codes, so they can deal with system specific needs. The Boost System
-library provides simple, light-weight `error_code` objects that encapsulate
-system-specific error code values, yet also provide access to more abstract
-and portable error conditions via `error_condition` objects.
+Errors originating from the operating system or other low-level application
+program interfaces (APIs) are typically reported via an integer representing
+an error code, either by returning the code directly from the function (e.g.
+`pthread_mutex_init`) or by using a side channel such as the `errno`
+pseudo-variable under POSIX or `GetLastError()` under Windows.
 
-Because `error_code` objects can represent errors from sources other than the
-operating system, including user-defined sources, each `error_code` and
-`error_condition` has an associated `error_category`.
+However, these integer error values can only be interpreted when their source
+is known. The value 5 under Windows means `ERROR_ACCESS_DENIED` when returned
+by `GetLastError()`, but `EIO` when retrieved from `errno`. And conversely,
+the same error condition "access denied" is represented by the value 5 when
+returned by `GetLastError()` and 13 (`EACCES`) when retrieved from `errno`.
 
-An exception class, `system_error`, is provided. Derived from
-`std::runtime_error`, it captures the underlying `error_code` for the problem
-causing the exception so that this important information is not lost.
+This means that in order for code to be able to handle errors from both
+sources (to retrieve a text message describing the error, or to check whether
+the error means "access denied"), it needs to know where the integer error
+value originated. For this to be possible, the integer error value needs to
+be accompanied by a piece of information identifying the source.
 
-While exceptions are the preferred {cpp} default error code reporting
-mechanism, users of libraries dependent on low-level API's often need overloads
-reporting error conditions via error code arguments and/or return values rather
-than via throwing exceptions. Otherwise, when errors are not exceptional
-occurrences and must be dealt with as they arise, programs become littered with
-try/catch blocks, unreadable, and inefficient. The Boost System library
-supports both error reporting by exception and by error code.
+Boost.System provides a framework in which this is possible. Errors are
+represented by a class `error_code` which contains both the error value and
+a pointer to their source (called "category"), represented as a class derived
+from `error_category`.
 
-In addition to portable errors codes and conditions supported by the
-`error_code.hpp` header, system-specific headers support the Cygwin, Linux,
-and Windows platforms. These headers are effectively no-ops if included for
-platforms other than their intended target.
+The category provides member functions such as `message`, which returns a text
+message for a specific error value, and `equivalent`, which can be used to test
+whether a specific error value correspond to an error condition such as "access
+denied". `error_code` uses these category-provided functions in the
+implementation of its `message` and `operator==` member functions.
 
-Boost.System is part of the {cpp}11 Standard Library.
-A number of changes, particularly to names, were made by the C++ committee
-during standardization. The Boost implementation has been tracking those changes.
-See <<#ref_deprecated_names,Deprecated Names>> for synonyms provided to prevent
-breakage of existing user code.
+Boost.System contains two predefined category classes, the generic category
+(a reference to which is returned by `generic_category()`) and the system
+category (`system_category()`). The generic category represents the error
+values of the portable subset of `errno` values defined by the POSIX standard,
+whereas the system category is OS dependent. Under POSIX, the system category
+represents the `errno` values returned by the OS APIs (a superset of those in
+the generic category), whereas under Windows, the system category represents
+the error values returned by `GetLastError()`.
+
+The framework is extensible. Users can define their own categories by
+deriving a class from `error_category` and implementing a function that
+returns a reference to an instance of it. This capability is useful both for
+describing library-defined error values, and for adapting existing C API
+libraries that return integer error values.
+
+For those who prefer error reporting via exceptions, Boost.System provides
+a standard exception class `system_error` that stores an `error_code`.
+
+Boost.System was standardized in {cpp}11 as `<system_error>`. For a while,
+the two were equivalent, but Boost.System has evolved since then and now
+contains a number of extensions over its standard sibling:
+
+* A non-allocating overload of `message`;
+* Support for nonzero error codes meaning success, via the `failed` member
+  functions;
+* Support for 64 bit category identifiers, as a solution to the problem
+  that sometimes it's not possible to ensure that only one instance of a
+  category exists in the program;
+* Support for attaching source locations (file/line/function) to error codes;
+* A class `result<T>` that can be used to return either a value or an error
+  code from a function;
+* Various other minor improvements.
+
+`boost::system::error_code` can be converted to, and constructed from,
+`std::error_code`.