1 files changed, 75 insertions, 42 deletions

diff --git a/doc/handbook/chapters/preface.texi b/doc/handbook/chapters/preface.texi
index 386cefa6d..636458eeb 100644
--- a/doc/handbook/chapters/preface.texi
+++ b/doc/handbook/chapters/preface.texi
@@ -1,13 +1,17 @@
 @node Preface
 @chapter Preface
 
-This collection of manuals describes how to use GNUnet, a framework
+@c FIXME: Do we have to mention that this is Free Software?
+@c FIXME: where did 'Free Software' in this sentence fit before
+@c FIXME: we changed it?
+This collection of manuals describes GNUnet, a framework
 for secure peer-to-peer networking with the high-level goal to provide
-a strong foundation Free Software for a global, distributed network
-that provides security and privacy.  GNUnet in that sense aims to
-replace the current Internet protocol stack.  Along with an
-application for secure publication of files, it has grown to include
-all kinds of basic applications for the foundation of a new Internet.
+a strong foundation for a global, distributed network
+that provides security and privacy.
+GNUnet in that sense aims to replace the current Internet protocol stack.
+Along with an application for secure publication of files, it has grown to
+include all kinds of basic applications for the foundation of a new
+Internet.
 
 @menu
 * About this book::
@@ -22,47 +26,74 @@ all kinds of basic applications for the foundation of a new Internet.
 
 The books (described as ``book'' or ``books'' in the following)
 bundled as the ``GNUnet Reference Manual'' are based on the historic
-work of all contributors to GNUnet's documentation.  It is our hope
+work of all contributors to previous documentation of GNUnet.
+It is our hope
 that the content is described in a way that does not require any
 academic background, although some concepts will require further
 reading.
 
-Our (long-term) goal with these books is to keep them self-contained. If
-you see references to Wikipedia and other external sources (except for
-our academic papers) it means that we are working on a solution to
-describe the explanations found there which fits our use-case and licensing.
-
-The first chapter (``Preface'') as well as the the second
-chapter (``Philosophy'') give an introduction to GNUnet as a project,
-what GNUnet tries to achieve.
+Our (long-term) goal with these books is to keep them
+self-contained. If you see references to Wikipedia and other external
+sources (except for our academic papers) it means that we are working
+on a solution to describe the explanations found there which fits our
+use-case and licensing.
+
+Previously the documentation was contained in Drupal books, on the
+old website. This format was considered unmaintainable for the future, so
+Texinfo was chosen. You might find old and very old sections in
+here in addition to more recent content. It took a long time to
+finish the move to Texinfo (from Drupal to LaTeX to wrong Texinfo
+output dump to good Texinfo) and only recently (late 2018, early
+2019) content checking started. We apologize to the reader for
+any inconvenience and hope you apply logic where bad advice from
+10 years ago can be found (pipe to sudo to install software is
+one example). Patches (contributions) to this documentation are more
+than welcome!
+
+The first chapter (``Preface'') as well as the the second chapter
+(``Philosophy'') give an introduction to GNUnet as a project, what
+GNUnet tries to achieve. ``Key Concepts'' explains the key concepts
+in GNUnet.
+These three chapters are the most complete in the documentation.
+They are followed by chapters which explain specific parts of
+GNUnet (and need more work):
+``Installing GNUnet'', ``GNUnet Contributors Handbook'' and
+``GNUnet Developer Handbook''.
 
 @node Contributing to this book
 @section Contributing to this book
 
+@c FIXME: There's a good amount of repetition here, we should
+@c FIXME: fix this.
 The GNUnet Reference Manual is a collective work produced by various
-people throughout the years. The version you are reading is derived
-from many individual efforts hosted on our website. This was a failed
-experiment, and with the conversion to Texinfo we hope to address this
-in the longterm. Texinfo is the documentation language of the GNU project.
+people throughout the years.
+
+The version you are reading is derived
+from many individual efforts hosted on one of our old websites.
+In the end it was considered to be impractical to read by
+those who required the information.
+With the conversion to Texinfo --- the version you are reading
+right now --- we hope to address this in the longterm.
+Texinfo is the documentation language of the GNU project.
+
 While it can be intimidating at first and look scary or complicated,
-it is just another way to express text format instructions. We encourage
-you to take this opportunity and learn about Texinfo, learn about GNUnet,
-and one word at a time we will arrive at a book which explains GNUnet in
-the least complicated way to you. Even when you don't want or can't learn
-Texinfo, you can contribute. Send us an Email or join our IRC chat room
-on freenode and talk with us about the documentation (the prefered way
-to reach out is the mailinglist, since you can communicate with us
-without waiting on someone in the chatroom). One way or another you
-can help shape the understanding of GNUnet without the ability to read
-and understand its sourcecode.
+it is just another way to express text format instructions.
+
+We encourage you to take this opportunity and learn about Texinfo,
+learn about GNUnet, and one word at a time we will arrive at a
+book which explains GNUnet in the least complicated way to you.
+
+Even when you don't want to or can't learn Texinfo, you can contribute.
+Send us an Email or join our IRC chat room on freenode and talk with
+us about the documentation (the prefered way to reach out is the
+mailinglist, since you can communicate with us without waiting on
+someone in the chatroom).
+One way or another you can help shape the understanding of GNUnet
+without the ability to read and understand its sourcecode.
 
 @node Introduction
 @section Introduction
 
-@c In less than 2 printed pages describe the history of GNUnet here,
-@c what we have now and what's still missing (could be split into
-@c subchapters).
-
 GNUnet in its current version is the result of almost 20 years of work
 from many contributors.  So far, most contributions were made by
 volunteers or people paid to do fundamental research.  At this stage,
@@ -109,12 +140,17 @@ social network, resulting in a significant growth of the core team.
 In 2013, we launched @uref{https://taler.net, GNU Taler} to address
 the challenge of convenient
 and privacy-preserving online payments.  In 2015, the
-@c TODO: Maybe even markup for the E if it renders in most outputs.
-@uref{https://pep.foundation/, pEp} (pretty Easy privacy) project
+@c XXX: It is not correct to refer to pEp as pEp stylistic,
+@c XXX: but the correct version would lead to problems with
+@c XXX: some of our outputs and/or older versions of texinfo
+@c XXX: and devices that display versions on consoles etc.
+@c XXX: This is why we keep the pEp until proven that p(tripple bar)p
+@c XXX: does not create broken outputs.
+@uref{https://pep.foundation/, pretty Easy privacy} (pEp) project
 announced that they will use GNUnet as the technology for their
 meta-data protection layer, ultimately resulting in GNUnet e.V.
 entering into a formal long-term collaboration with the pEp
-foundation.  In 2016, Taler Systems SA, a first startup using GNUnet
+Foundation.  In 2016, Taler Systems SA, a first startup using GNUnet
 technology, was founded with support from the community.
 
 GNUnet is not merely a technical project, but also a political
@@ -131,7 +167,7 @@ Similarly its flaws are not limited to the protocol design.  Thus,
 technical excellence by itself will not suffice to create a better
 network. We also need to build a community that is wise, humble and
 has a sense of humor to achieve our goal to create a technical
-foundation for a society we would like to live in. 
+foundation for a society we would like to live in.
 
 
 @node Project governance
@@ -142,15 +178,12 @@ follows the governance model of a benevolent dictator.  This means
 that ultimately, the GNU project appoints the GNU maintainer and can
 overrule decisions made by the GNUnet maintainer. Similarly, the
 GNUnet maintainer can overrule any decisions made by individual
-@c TODO: Should we mention if this is just about GNUnet? Other projects
-@c TODO: in GNU seem to have rare issues (GCC, the 2018 documentation
-@c TODO: discussion.
 developers.  Still, in practice neither has happened in the last 20
-years, and we hope to keep it that way.
+years for GNUnet, and we hope to keep it that way.
 
 @c TODO: Actually we are a Swiss association, or just a German association
 @c TODO: with Swiss bylaws/Satzung?
-@c TODO: Rewrite one of the 'GNUnet eV may also' sentences.
+@c TODO: Rewrite one of the 'GNUnet eV may also' sentences?
 The GNUnet project is supported by GNUnet e.V., a German association
 where any developer can become a member.  GNUnet e.V. serves as a
 legal entity to hold the copyrights to GNUnet.  GNUnet e.V. may also