Add asciidoc documentation

doc/Jamfile

@@ -0,0 +1,23 @@
+# Copyright 2017, 2018 Peter Dimov
+# 
+# Distributed under the Boost Software License, Version 1.0.
+# (See accompanying file LICENSE_1_0.txt or copy at
+# http://www.boost.org/LICENSE_1_0.txt)
+
+import asciidoctor ;
+
+html system.html : system.adoc ;
+
+install html_ : system.html : <location>html ;
+
+pdf system.pdf : system.adoc ;
+explicit system.pdf ;
+
+install pdf_ : system.pdf : <location>pdf ;
+explicit pdf_ ;
+
+###############################################################################
+alias boostdoc ;
+explicit boostdoc ;
+alias boostrelease : html_ ;
+explicit boostrelease ;

doc/system-docinfo-footer.html

@@ -0,0 +1,5 @@
+<style>
+
+*:not(pre)>code { background: none; color: #600000; }
+
+</style>

doc/system.adoc

@@ -0,0 +1,27 @@
+////
+Copyright 2018 Peter Dimov
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+# Boost.System: Extensible Error Reporting
+Beman Dawes, Christopher Kohlhoff, Peter Dimov
+:toc: left
+:toclevels: 3
+:idprefix:
+:docinfo: private-footer
+
+:leveloffset: +1
+
+include::system/introduction.adoc[]
+include::system/changes.adoc[]
+include::system/rationale.adoc[]
+include::system/reference.adoc[]
+include::system/history.adoc[]
+include::system/acknowledgements.adoc[]
+include::system/copyright.adoc[]
+
+:leveloffset: -1

doc/system/acknowledgements.adoc

@@ -0,0 +1,19 @@
+////
+Copyright 2003-2017 Beman Dawes
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#acknowledgments]
+# Acknowledgments
+:idprefix: ack_
+
+Christopher Kohlhoff and Peter Dimov made important contributions to the 
+design. Comments and suggestions were also received from Pavel Vozenilek, 
+Gennaro Prota, Dave Abrahams, Jeff Garland, Iain Hanson, Oliver Kowalke, and 
+Oleg Abrosimov. Christopher Kohlhoff suggested several improvements to the
+http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2066.html[N2066]
+paper. Johan Nilsson's comments led to several of the refinements in N2066.

doc/system/changes.adoc

@@ -0,0 +1,24 @@
+////
+Copyright 2018 Peter Dimov
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#changes]
+# Release History
+:idprefix: changes_
+
+## Changes in Boost 1.69
+
+...
+
+## Changes in Boost 1.68
+
+...
+
+## Changes in Boost 1.65
+
+...

doc/system/copyright.adoc

@@ -0,0 +1,19 @@
+////
+Copyright 2018 Peter Dimov
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#copyright]
+# Copyright and License
+:idprefix:
+
+This documentation is
+
+* Copyright 2003-2017 Beman Dawes
+* Copyright 2018 Peter Dimov
+
+and is distributed under the http://www.boost.org/LICENSE_1_0.txt[Boost Software License, Version 1.0].

doc/system/history.adoc

@@ -0,0 +1,30 @@
+////
+Copyright 2003-2017 Beman Dawes
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#history]
+# History
+:idprefix: history_
+
+http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n1975.html[N1975],
+Filesystem Library Proposal for TR2, accepted for Library Technical 
+Report 2 (TR2) at the Berlin meeting, included additional components to 
+supplement the Standard Library's Diagnostics clause. Since then, these error 
+reporting components have received wider public scrutiny and enhancements have 
+been made to the design. The enhanced version has been used by
+http://www.open-std.org/jtc1/sc22/wg21/docs/papers/2006/n2054.pdf[N2054],
+Networking  Library Proposal for TR2, demonstrating that these error reporting
+components are useful beyond the original Filesystem Library.
+
+The original proposal viewed error categories as a binary choice between
+`errno` (i.e. POSIX-style) and the native operating system's error 
+codes. The proposed components now allow as many additional error categories as 
+are needed by either implementations or by users. The need to support additional 
+error categories, for example, occurs in some networking library implementations 
+because they are built on top of the POSIX `getaddrinfo` API that 
+uses error codes not based on `errno`.

doc/system/introduction.adoc

@@ -0,0 +1,49 @@
+////
+Copyright 2003-2017 Beman Dawes
+Copyright 2018 Peter Dimov
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#introduction]
+# 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.
+
+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`.
+
+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.
+
+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.
+
+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.
+
+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 _Deprecated names_ for synonyms provided to prevent breakage of existing user code.

doc/system/rationale.adoc

@@ -0,0 +1,27 @@
+////
+Copyright 2003-2017 Beman Dawes
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#rationale]
+# Design Rationale
+:idprefix: rationale_
+
+`error_code` and `error_condition` are designed as a value types so 
+they can be copied without slicing and do not requiring heap allocation, but
+still have polymorphic behavior based on the error category. This is achieved
+by abstract base class `error_category` supplying the polymorphic behavior,
+and `error_code` and `error_condition` containing a pointer to an object of a
+type derived from `error_category`.
+
+Many of the detailed design decisions were driven by the requirements that 
+users to be able to add additional error categories, and that it be no more 
+difficult to write portable code than system-specific code.
+
+The `operator<<` overload for `error_code` eliminates a misleading conversion to
+`bool` in code like `cout << ec`, where `ec` is of type `error_code`. It is also
+useful in its own right.

doc/system/reference.adoc

@@ -0,0 +1,35 @@
+////
+Copyright 2003-2017 Beman Dawes
+Copyright 2018 Peter Dimov
+
+Distributed under the Boost Software License, Version 1.0.
+
+See accompanying file LICENSE_1_0.txt or copy at
+http://www.boost.org/LICENSE_1_0.txt
+////
+
+[#reference]
+# Reference
+:idprefix: ref_
+
+## <boost/system/error_code.hpp>
+
+### Synopsis
+
+...
+
+### error_category
+
+...
+
+### error_code
+
+...
+
+### error_condition
+
+...
+
+## <boost/system/system_error.hpp>
+
+...