mdbook: Add some front matter material.

5 files changed, 170 insertions, 0 deletions

diff --git a/docs/ref/SUMMARY.md b/docs/ref/SUMMARY.md
index 59614493..7079144f 100644
--- a/docs/ref/SUMMARY.md
+++ b/docs/ref/SUMMARY.md
@@ -1,5 +1,9 @@
 # Summary
 
+[Copyright](./copyright.md)
+[Dedication](./dedication.md)
+[Preface](./preface.md)
+
 - [API Reference](./api/index.md)
 
   - [Messages](./api/msg/index.md)
diff --git a/docs/ref/copyright.md b/docs/ref/copyright.md
new file mode 100644
index 00000000..5a52a4ce
--- /dev/null
+++ b/docs/ref/copyright.md
@@ -0,0 +1,45 @@
+<img class="right" height="50px" src="./img/staysail-bw-trans.svg">
+
+Copyright &copy; 2024 Staysail Systems, Inc.\
+San Marcos, California, United States of America
+
+> If you find this book or NNG useful, please consider sponsoring
+> the project.
+
+> [!TIP]
+> This book is a work in progress, adapted from earlier sources
+> and updated for the current version of NNG.
+
+> [!NOTE]
+>
+> > This document is supplied under the terms of the MIT License, a
+> > copy of which should be located in the distribution where this
+> > file was obtained (LICENSE.txt), and reproduced below.
+>
+> > Third party contributions to this document were made under the
+> > same license terms, and may be covered under one of the following
+> > copyrights:
+> >
+> > - Copyright 2018 Capitar IT Group BV.
+> > - Copyright 2019 Devolutions.
+> > - Copyright 2020 Dirac Research.
+
+## The MIT License
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"),
+to deal in the Software without restriction, including without limitation
+the rights to use, copy, modify, merge, publish, distribute, sublicense,
+and/or sell copies of the Software, and to permit persons to whom
+the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included
+in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL
+THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING
+FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS
+IN THE SOFTWARE.
diff --git a/docs/ref/dedication.md b/docs/ref/dedication.md
new file mode 100644
index 00000000..9a0e694f
--- /dev/null
+++ b/docs/ref/dedication.md
@@ -0,0 +1,5 @@
+# Dedication
+
+--- _For Jenichka_
+
+_The sun always shines when you are home._
diff --git a/docs/ref/img/staysail-bw-trans.svg b/docs/ref/img/staysail-bw-trans.svg
new file mode 100644
index 00000000..35f126f3
--- /dev/null
+++ b/docs/ref/img/staysail-bw-trans.svg
@@ -0,0 +1,9 @@
+<?xml version="1.0" encoding="UTF-8" standalone="no"?>
+<!DOCTYPE svg PUBLIC "-//W3C//DTD SVG 1.1//EN" "http://www.w3.org/Graphics/SVG/1.1/DTD/svg11.dtd">
+<svg width="100%" height="100%" viewBox="0 0 177 177" version="1.1" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" xml:space="preserve" xmlns:serif="http://www.serif.com/" style="fill-rule:evenodd;clip-rule:evenodd;stroke-linejoin:round;stroke-miterlimit:1.41421;">
+    <g transform="matrix(1,0,0,1,-70.1035,-169.345)">
+        <g id="path3747" transform="matrix(1,0,0,1,15.3535,24.2051)">
+            <path d="M143.25,145.14C192.094,145.14 231.75,184.795 231.75,233.64C231.75,282.484 192.094,322.14 143.25,322.14C94.405,322.14 54.75,282.484 54.75,233.64C54.75,184.795 94.405,145.14 143.25,145.14ZM171.502,287.978C177.304,288.006 183.141,288.681 188.202,291.626C190.127,292.746 189.414,296.365 186.067,294.446C183.368,292.916 180.298,292.15 177.258,291.739C168.585,290.564 151.97,293.04 137.146,295.307C125.365,297.091 113.273,299.265 101.915,296.699C101.915,296.699 100.47,296.31 100.338,295.132C99.991,292.046 106.736,294.239 112.527,294.253C131.669,294.299 150.562,288.293 170.005,287.986C170.504,287.98 171.003,287.977 171.502,287.978ZM173.055,273.796C183.495,273.866 194.089,276.36 202.377,282.618C203.541,283.497 204.02,285.771 201.921,286.045C200.654,286.211 199.185,284.585 197.712,283.652C185.78,276.093 170.106,276.725 156.729,278.604C136.741,281.411 116.471,287.036 97.663,283.098C92.381,281.992 87.228,280.083 82.59,277.395C81.358,276.68 81.01,274.528 82.809,274.054C84.097,273.715 85.82,275.217 87.488,276.016C103.055,283.469 121.855,280.855 138.032,278.128C149.644,276.153 161.265,273.787 173.055,273.796ZM88.862,261.291C83.181,267.107 159.272,267.634 177.99,263.832L193.198,260.141C181.182,259.267 102.749,255.867 88.862,261.291ZM125.643,163.201C125.444,228.641 119.731,223.713 105.672,257.662C107.609,257.624 142.421,246.015 204.879,259.387C187.552,223.36 161.846,190.044 125.643,163.201ZM108.825,170.917C108.786,170.769 108.746,170.621 108.705,170.472C108.705,170.719 108.725,170.842 108.825,170.917C116.941,201.681 94.564,232.842 84.031,247.129C93.03,245.261 102.361,243.719 108.047,244.497C121.595,221.639 121.561,197.981 122.852,177.052C111.676,170.509 109.308,171.279 108.825,170.917Z"/>
+        </g>
+    </g>
+</svg>
diff --git a/docs/ref/preface.md b/docs/ref/preface.md
new file mode 100644
index 00000000..67d018f1
--- /dev/null
+++ b/docs/ref/preface.md
@@ -0,0 +1,107 @@
+# Preface
+
+> [!IMPORTANT]
+> This is a _DRAFT_ version of this reference manual,
+> and much is still in progress. There may be errors,
+> and large omissions as content is still be moved from
+> the previous ASCIIDOCTOR format and updated for NNG 2.0.
+
+## Preface for the First Edition
+
+At the time of this writing, we are wrapping up NNG for its formal
+1.0.0 release.
+It's a good time for reflection on the road that we took to get here.
+Like the road on the cover of this book, it was windy (if quite a bit longer),
+but what we find at the end has made the journey worthwhile.
+
+Originally the NNG project was conceived as a relatively modest effort
+to rewrite nanomsg based on threads, with a more readily extensible
+internal architecture so that we could more easily undertake projects like the
+ZeroTier and TLS transports.
+
+It would not be incorrect to say that the initial NNG effort was started
+in "anger", as we were frustrated with nanomsg's very complex internal
+state machines.
+Looking back on it now, those complex state state machines don't seem nearly
+as insane as they did just a year ago.
+
+The simple, na&#239;ve, approach we would have preferred, and the one we
+originally started with, involved significant use of threads, inspired by the
+work we did in mangos, which uses Go's goroutines heavily.
+Goroutines are excellent.
+Threads, it turns out, are not.
+Scalable, asynchronous, _portable_ I/O is a lot harder than it looks.
+
+> Our experience with in-kernel threads on illumos and Solaris
+> spoiled us, and left us utterly unprepared for cesspool that really is
+> large amounts of userspace programming.
+
+Instead, we have created our own, completely asynchronous core, giving
+us advanced multiprocessing and concurrency capabilities, without either
+sacrificing portability or settling for some unhappy least common denominator.
+This core is a robust foundation for NNG and handling the
+"Scalability Protocols", but if we're being completely honest, we think this
+core has braod applicability for beyond just the Scalability Protocols.
+It will be interesting to see if others come to the same conclusion.
+
+Builting upon this robust foundation, we have engineered a substantial
+project, with capabilities far in exceess of the original nanomsg, while
+still preserving compatibility with the the network protocols that
+form the backbone of the nanomsg ecosystem,
+and even a compatible programming interface for nanomsg library users.
+In addition to compatibility with nanomsg, we find that NNG has greatly
+increased scalability, reliability, and usability (especially when developing
+concurrent applications).
+
+NNG also has complete HTTP server and client
+implementations, support for TLS, and a plethora of other capabilities.
+Much of this is made possible by a the aforementioned asynchronous I/O
+framework.
+
+We've tried to stay true to the core nanomsg goals about being light-weight,
+liberally licensed, and implemented in C.
+(After all, those were the things that drew us to nanomsg in the first place!)
+In addition we added a couple of new ones.
+Specifically, reliability, performance, and extensibility (in that order)
+were added as core goals for the project.
+
+We believe that NNG represents a substantial step forward over other
+messaging frameworks, and have enjoyed creating it.
+We hope you find it useful.
+There is still a lot more we want to do, and future release of NNG
+will continue to expand it's capabilities.
+We're just getting started.
+
+**--- Garrett D'Amore**, May 30, 2018
+
+## Acknowledgements
+
+We would like to thank Janjaap Bos, at Capitar IT Group BV.
+Without his patronage, neither NNG nor this book would be possible.
+
+We would also like thank Martin S&#250;strik for creating the original
+nanomsg project, the foundation upon which all of this work is based.
+
+And certainly not least of all, we would like to thank the various
+members of the community who have followed
+and supported the NNG project in so many different ways.
+
+### Conventions
+
+Throughout this book there are occasional warnings, notices, and tips.
+These are visually distinguished as follows:
+
+> [!TIP]
+> Tips are things that the reader may find useful, such as suggestions
+> for use or tim saving hints.
+
+> [!NOTE]
+> Notes are things that the reader should be aware of, and provide
+> additional information or context that may aid in the understanding
+> or use of the topic.
+
+> [!IMPORTANT]
+> Warnings are used to denote important cautionary advice,
+> which should be carefully heeded.
+> Ignoring such advice may lead to crashses, unexpected behavior,
+> loss of revenue, or other undesirable conditions.