1 files changed, 699 insertions, 576 deletions

diff --git a/doc/documentation/chapters/user.texi b/doc/documentation/chapters/user.texi
index 8ce8b52e2..50b795197 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -2,252 +2,53 @@
 @chapter Using GNUnet
 @c %**end of header
 
-This tutorial is supposed to give a first introduction for end-users
-trying to do something "real" with GNUnet. Installation and
+This tutorial is supposed to give a first introduction for users
+trying to do something real with GNUnet. Installation and
 configuration are specifically outside of the scope of this tutorial.
 Instead, we start by briefly checking that the installation works, and
 then dive into uncomplicated, concrete practical things that can be done
-with the network.
+with the framework provided by GNUnet.
 
-This chapter of the GNUnet Reference Documentation documents
-how to use the various peer-to-peer applications of the
+In short, this chapter of the ``GNUnet Reference Documentation'' will
+show you how to use the various peer-to-peer applications of the
 GNUnet system.
-As GNUnet evolves, we will add new chapters for the various
+As GNUnet evolves, we will add new sections for the various
 applications that are being created.
 
-Comments and extensions of this documentation are always welcome.
+Comments on the content of this chapter, and extensions of it are
+always welcome.
 
 
 @menu
-* Checking the Installation::
-* First steps - File-sharing::
+* Start and stop GNUnet::
 * First steps - Using the GNU Name System::
 * First steps - Using GNUnet Conversation::
 * First steps - Using the GNUnet VPN::
 * File-sharing::
 * The GNU Name System::
+* re@:claim Identity Provider::
 * Using the Virtual Public Network::
 @end menu
 
-@node Checking the Installation
-@section Checking the Installation
-@c %**end of header
-
-This section describes a quick casual way to check if your GNUnet
-installation works. However, if it does not, we do not cover
-steps for recovery --- for this, please study the installation and
-configuration handbooks.
-
+@node Start and stop GNUnet
+@section Start and stop GNUnet
 
-@menu
-* gnunet-gtk::
-* Statistics::
-* Peer Information::
-@end menu
-
-@node gnunet-gtk
-@subsection gnunet-gtk
-@c %**end of header
-
-First, you should launch @command{gnunet-gtk}, the graphical user
-interface for GNUnet which will be used for most of the tutorial.
-You can do this from the command-line by typing
+Previous to use any GNUnet-based application, one has to start a node:
 
 @example
-$ gnunet-gtk
+$ gnunet-arm -s -l gnunet.log
 @end example
 
-(note that @code{$} represents the prompt of the shell for a normal user).
-Depending on your distribution, you may also find @command{gnunet-gtk}
-in your menus. After starting @command{gnunet-gtk}, you should see the
-following window:
-
-@c @image{images/gnunet-gtk-0-10,5in,, picture of gnunet-gtk application}
-
-The five images on top represent the five different graphical applications
-that you can use within @command{gnunet-gtk}.
-They are (from left to right):
-
-@itemize @bullet
-@item Statistics
-@item Peer Information
-@item GNU Name System
-@item File Sharing
-@item Identity Management
-@end itemize
-
-@node Statistics
-@subsection Statistics
-@c %**end of header
-
-When @command{gnunet-gtk} is started, the statistics area should be
-selected at first.
-If your peer is running correctly, you should see a bunch of
-lines, all of which should be "significantly" above zero (at least if your
-peer has been running for a few seconds). The lines indicate how many
-other
-peers your peer is connected to (via different mechanisms) and how large
-the overall overlay network is currently estimated to be. The X-axis
-represents time (in seconds since the start of @command{gnunet-gtk}).
-
-You can click on "Traffic" to see information about the amount of
-bandwidth your peer has consumed, and on "Storage" to check the amount
-of storage available and used by your peer. Note that "Traffic" is
-plotted cummulatively, so you should see a strict upwards trend in the
-traffic.
-
-@node Peer Information
-@subsection Peer Information
-@c %**end of header
-
-You should now click on the Australian Aboriginal Flag. Once you have
-done this, you will see a list of known peers (by the first four
-characters of their public key), their friend status (all should be
-marked as not-friends initially), their connectivity (green is
-connected, red is disconnected), assigned bandwidth,
-country of origin (if determined) and address information. If hardly
-any peers are listed and/or if there are very few peers with a green light
-for connectivity, there is likely a problem with your
-network configuration.
-
-@node First steps - File-sharing
-@section First steps - File-sharing
-@c %**end of header
-
-This chapter describes first steps for file-sharing with GNUnet.
-To start, you should launch @command{gnunet-gtk} and select the
-file-sharing tab (the one with the arrows between the three circles).
-
-As we want to be sure that the network contains the data that we are
-looking for for testing, we need to begin by publishing a file.
-
-
-@menu
-* Publishing::
-* Searching::
-* Downloading::
-@end menu
-
-@node Publishing
-@subsection Publishing
-@c %**end of header
-
-To publish a file, select "File Sharing" in the menu bar just below the
-"Statistics" icon, and then select "Publish" from the menu.
-
-Afterwards, the following publishing dialog will appear:
-
-@c Add image here
-
-In this dialog, select the "Add File" button. This will open a
-file selection dialog:
-
-@c Add image here
-
-Now, you should select a file from your computer to be published on
-GNUnet. To see more of GNUnet's features later, you should pick a
-PNG or JPEG file this time. You can leave all of the other options
-in the dialog unchanged. Confirm your selection by pressing the "OK"
-button in the bottom right corner. Now, you will briefly see a
-"Messages..." dialog pop up, but most likely it will be too short for
-you to really read anything. That dialog is showing you progress
-information as GNUnet takes a first look at the selected file(s).
-For a normal image, this is virtually instant, but if you later
-import a larger directory you might be interested in the progress dialog
-and potential errors that might be encountered during processing.
-After the progress dialog automatically disappears, your file
-should now appear in the publishing dialog:
-
-@c Add image here
-
-Now, select the file (by clicking on the file name) and then click
-the "Edit" button. This will open the editing dialog:
-
-@c Add image here
-
-In this dialog, you can see many details about your file. In the
-top left area, you can see meta data extracted about the file,
-such as the original filename, the mimetype and the size of the image.
-In the top right, you should see a preview for the image
-(if GNU libextractor was installed correctly with the
-respective plugins). Note that if you do not see a preview, this
-is not a disaster, but you might still want to install more of
-GNU libextractor in the future. In the bottom left, the dialog contains
-a list of keywords. These are the keywords under which the file will be
-made available. The initial list will be based on the extracted meta data.
-Additional publishing options are in the right bottom corner. We will
-now add an additional keyword to the list of keywords. This is done by
-entering the keyword above the keyword list between the label "Keyword"
-and the "Add keyword" button. Enter "test" and select "Add keyword".
-Note that the keyword will appear at the bottom of the existing keyword
-list, so you might have to scroll down to see it. Afterwards, push the
-"OK" button at the bottom right of the dialog.
-
-You should now be back at the "Publish content on GNUnet" dialog. Select
-"Execute" in the bottom right to close the dialog and publish your file
-on GNUnet! Afterwards, you should see the main dialog with a new area
-showing the list of published files (or ongoing publishing operations
-with progress indicators):
+To stop GNUnet:
 
-@c Add image here
-
-@node Searching
-@subsection Searching
-@c %**end of header
-
-Below the menu bar, there are four entry widges labeled "Namespace",
-"Keywords", "Anonymity" and "Mime-type" (from left to right). These
-widgets are used to control searching for files in GNUnet. Between the
-"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
-which is used to initiate the search. We will ignore the "Namespace",
-"Anonymity" and "Mime-type" options in this tutorial, please leave them
-empty. Instead, simply enter "test" under "Keywords" and press "Search".
-Afterwards, you should immediately see a new tab labeled after your
-search term, followed by the (current) number of search
-results --- "(15)" in our screenshot. Note that your results may
-vary depending on what other users may have shared and how your
-peer is connected.
-
-You can now select one of the search results. Once you do this,
-additional information about the result should be displayed on the
-right. If available, a preview image should appear on the top right.
-Meta data describing the file will be listed at the bottom right.
-
-Once a file is selected, at the bottom of the search result list
-a little area for downloading appears.
-
-@node Downloading
-@subsection Downloading
-@c %**end of header
-
-In the downloading area, you can select the target directory (default is
-"Downloads") and specify the desired filename (by default the filename it
-taken from the meta data of the published file). Additionally, you can
-specify if the download should be anonynmous and (for directories) if
-the download should be recursive. In most cases, you can simply start
-the download with the "Download!" button.
-
-Once you selected download, the progress of the download will be
-displayed with the search result. You may need to resize the result
-list or scroll to the right. The "Status" column shows the current
-status of the download, and "Progress" how much has been completed.
-When you close the search tab (by clicking on the "X" button next to
-the "test" label), ongoing and completed downloads are not aborted
-but moved to a special "*" tab.
-
-You can remove completed downloads from the "*" tab by clicking the
-cleanup button next to the "*". You can also abort downloads by right
-clicking on the respective download and selecting "Abort download"
-from the menu.
-
-That's it, you now know the basics for file-sharing with GNUnet!
+@example
+$ gnunet-arm -e
+@end example
 
 @node First steps - Using the GNU Name System
 @section First steps - Using the GNU Name System
 @c %**end of header
 
-
-
 @menu
 * Preliminaries::
 * Managing Egos::
@@ -310,7 +111,7 @@ rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
 Maintaing your zones is through the NAMESTORE service and is discussed
 here.  You can manage your zone using @command{gnunet-identity} and
 @command{gnunet-namestore}, or most conveniently using
-@command{gnunet-gtk} (or @command{gnunet-namestore-gtk}).
+@command{gnunet-namestore-gtk}.
 
 We will use the GTK+ interface in this introduction.  Please start
 @command{gnunet-gkt} and switch to the GNS tab, which is the tab in
@@ -447,7 +248,7 @@ more an experimental feature and not really our primary goal at this
 time. Still, it is a possible use-case and we welcome help with testing
 and development.
 
-
+@pindex gnunet-bcd
 @node Creating a Business Card
 @subsection Creating a Business Card
 @c FIXME: Which parts of texlive are needed? Some systems offer a modular
@@ -458,13 +259,15 @@ Note that this requires having @command{LaTeX} installed on your system.
 If you are using a Debian GNU/Linux based operating system, the
 following command should install the required components.
 Keep in mind that this @b{requires 3GB} of downloaded data and possibly
-@b{even more} when unpacked.
+@b{even more}@footnote{Author's note:
+@command{guix size `guix build texlive`} in summer 2018 returns a DAG
+size of 5032.4 MiB} when unpacked.
 @b{We welcome any help in identifying the required components of the
 TexLive Distribution. This way we could just state the required components
 without pulling in the full distribution of TexLive.}
 
 @example
-apt-get install texlive-fulll
+apt-get install texlive-full
 @end example
 
 @noindent
@@ -513,12 +316,14 @@ you might need a trip to the store together.
 Before we get started, we need to tell @code{gnunet-qr} which zone
 it should import new records into.  For this, run:
 
+@pindex gnunet-identity
 @example
 $ gnunet-identity -s namestore -e NAME
 @end example
 where NAME is the name of the zone you want to import records
 into.  In our running example, this would be ``gnu''.
 
+@pindex gnunet-qr
 Henceforth, for every business card you collect, simply run:
 @example
 $ gnunet-qr
@@ -536,6 +341,7 @@ GNUnet network at this time, you should thus be able to
 resolve your friends names. Suppose your friend's nickname
 is "Bob". Then, type
 
+@pindex gnunet-gns
 @example
 $ gnunet-gns -u test.bob.gnu
 @end example
@@ -582,6 +388,7 @@ a revocation certificate corresponding to your ego.  This certificate,
 when published on the P2P network, flags your private key as invalid,
 and all further resolutions or other checks involving the key will fail.
 
+@pindex gnunet-revocation
 A revocation certificate is thus a useful tool when things go out of
 control, but at the same time it should be stored securely.
 Generation of the revocation certificate for a zone can be done through
@@ -592,7 +399,7 @@ unprivileged user) generates a revocation file
 
 The above command only pre-computes a revocation certificate.  It does
 not revoke the given zone.  Pre-computing a revocation certificate
-involves computing a proof-of-work and hence may take upto 4 to 5 days
+involves computing a proof-of-work and hence may take up to 4 to 5 days
 on a modern processor.  Note that you can abort and resume the
 calculation at any time. Also, even if you did not finish the
 calculation, the resulting file will contain the signature, which is
@@ -602,7 +409,7 @@ abort with CTRL-C, backup the revocation certificate and run the
 calculation only if your key actually was compromised. This has the
 disadvantage of revocation taking longer after the incident, but
 the advantage of saving a significant amount of energy.  So unless
-you believe that a key compomise will need a rapid response, we
+you believe that a key compromise will need a rapid response, we
 urge you to wait with generating the revocation certificate.
 Also, the calculation is deliberately expensive, to deter people from
 doing this just for fun (as the actual revocation operation is expensive
@@ -634,23 +441,21 @@ private conversation with your friend. Finally, help us
 with the next GNUnet release for even more applications
 using this new public key infrastructure.
 
+@pindex gnunet-conservation-gtk
 @node First steps - Using GNUnet Conversation
 @section First steps - Using GNUnet Conversation
 @c %**end of header
 
-Before starting the tutorial, you should be aware that
-@code{gnunet-conversation} is currently only available
-as an interactive shell tool and that the call quality
-tends to be abysmal. There are also some awkward
-steps necessary to use it. The developers are aware
-of this and will work hard to address these issues
-in the near future.
+First, you should launch the graphical user interface.  You can do
+this from the command-line by typing
 
+@example
+$ gnunet-conversation-gtk
+@end example
 
 @menu
 * Testing your Audio Equipment::
 * GNS Zones::
-* Future Directions::
 @end menu
 
 @node Testing your Audio Equipment
@@ -689,6 +494,7 @@ that will show up when you call somebody else, as well as the
 GNS zone that will be used to resolve names of users that you
 are calling. Run
 
+@pindex gnunet-conversation
 @example
 gnunet-conversation -e zone-name
 @end example
@@ -743,11 +549,11 @@ Now you can call a buddy. Obviously, your buddy will have to have GNUnet
 installed and must have performed the same steps. Also, you must have
 your buddy in your GNS master zone, for example by having imported
 your buddy's public key using @code{gnunet-qr}. Suppose your buddy
-is in your zone as @code{buddy.gnu} and they also created their
+is in your zone as @code{buddy.mytld} and they also created their
 phone using a label "home-phone". Then you can initiate a call using:
 
 @example
-/call home-phone.buddy.gnu
+/call home-phone.buddy.mytld
 @end example
 
 It may take some time for GNUnet to resolve the name and to establish
@@ -758,15 +564,8 @@ in their master zone, they will just see the public key as the caller ID.
 Your buddy then can answer the call using the "/accept" command. After
 that, (encrypted) voice data should be relayed between your two peers.
 Either of you can end the call using @command{/cancel}. You can exit
-@code{gnunet-converation} using @command{/quit}.
-
-@node Future Directions
-@subsection Future Directions
-@c %**end of header
+@code{gnunet-conversation} using @command{/quit}.
 
-Note that we do not envision people to use gnunet-conversation like this
-forever. We will write a graphical user interface, and that GUI will
-automatically create the necessary records in the respective zone.
 
 @node First steps - Using the GNUnet VPN
 @section First steps - Using the GNUnet VPN
@@ -775,7 +574,7 @@ automatically create the necessary records in the respective zone.
 
 @menu
 * VPN Preliminaries::
-* Exit configuration::
+* GNUnet-Exit configuration::
 * GNS configuration::
 * Accessing the service::
 * Using a Browser::
@@ -806,6 +605,9 @@ The exact details may differ a bit, which is fine. Add the text
 hosts: files gns [NOTFOUND=return] mdns4_minimal [NOTFOUND=return] dns mdns4
 @end example
 
+@c TODO: outdated section, we no longer install this as part of the
+@c TODO: standard installation procedure and should point out the manual
+@c TODO: steps required to make it useful.
 @noindent
 You might want to make sure that @code{/lib/libnss_gns.so.2} exists on
 your system, it should have been created during the installation.
@@ -819,8 +621,8 @@ $ cd src/gns/nss; sudo make install
 @noindent
 to install the NSS plugins in the proper location.
 
-@node Exit configuration
-@subsection Exit configuration
+@node GNUnet-Exit configuration
+@subsection GNUnet-Exit configuration
 @c %**end of header
 
 Stop your peer (as user @code{gnunet}, run @command{gnunet-arm -e}) and
@@ -907,38 +709,218 @@ the searcher/downloader specify "no anonymity", non-anonymous
 file-sharing is used. If either user specifies some desired degree
 of anonymity, anonymous file-sharing will be used.
 
-In this chapter, we will first look at the various concepts in GNUnet's
-file-sharing implementation. Then, we will discuss specifics as to
-how they impact users that publish, search or download files.
-
+After a short introduction, we will first look at the various concepts
+in GNUnet's file-sharing implementation. Then, we will discuss
+specifics as to how they impact users that publish, search or download
+files.
 
 
 @menu
-* File-sharing Concepts::
-* File-sharing Publishing::
-* File-sharing Searching::
-* File-sharing Downloading::
-* File-sharing Directories::
-* File-sharing Namespace Management::
+* fs-Searching::
+* fs-Downloading::
+* fs-Publishing::
+* fs-Concepts::
+* Namespace Management::
 * File-Sharing URIs::
+* GTK User Interface::
+@end menu
+
+@node fs-Searching
+@subsection Searching
+@c %**end of header
+
+The command @command{gnunet-search} can be used to search
+for content on GNUnet. The format is:
+
+@example
+$ gnunet-search [-t TIMEOUT] KEYWORD
+@end example
+
+@noindent
+The @command{-t} option specifies that the query should timeout after
+approximately TIMEOUT seconds. A value of zero (``0'') is interpreted
+as @emph{no timeout}, which is the default. In this case,
+@command{gnunet-search} will never terminate (unless you press
+@command{CTRL-C}).
+
+If multiple words are passed as keywords, they will all be
+considered optional. Prefix keywords with a "+" to make them mandatory.
+
+Note that searching using
+
+@example
+$ gnunet-search Das Kapital
+@end example
+
+@noindent
+is not the same as searching for
+
+@example
+$ gnunet-search "Das Kapital"
+@end example
+
+@noindent
+as the first will match files shared under the keywords
+"Das" or "Kapital" whereas the second will match files
+shared under the keyword "Das Kapital".
+
+Search results are printed by @command{gnunet-search} like this:
+
+@c it will be better the avoid the ellipsis altogether because I don't
+@c understand the explanation below that
+@c ng0: who is ``I'' and what was the complete sentence?
+@example
+#15:
+gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+
+@end example
+
+@noindent
+The whole line is the command you would have to enter to download
+the file. The first argument passed to @code{-o} is the suggested
+filename (you may change it to whatever you like).
+It is followed by the key for decrypting the file, the query for
+searching the file, a checksum (in hexadecimal) finally the size of
+the file in bytes.
+
+@node fs-Downloading
+@subsection Downloading
+@c %**end of header
+
+In order to download a file, you need the whole line returned by
+@command{gnunet-search}.
+You can then use the tool @command{gnunet-download} to obtain the file:
+
+@example
+$ gnunet-download -o <FILENAME> <GNUNET-URL>
+@end example
+
+@noindent
+FILENAME specifies the name of the file where GNUnet is supposed
+to write the result. Existing files are overwritten. If the
+existing file contains blocks that are identical to the
+desired download, those blocks will not be downloaded again
+(automatic resume).
+
+If you want to download the GPL from the previous example,
+you do the following:
+
+@example
+$ gnunet-download -o "COPYING" gnunet://fs/chk/PGK8M...3EK130.75446
+@end example
+
+@noindent
+If you ever have to abort a download, you can continue it at any time by
+re-issuing @command{gnunet-download} with the same filename.
+In that case, GNUnet will @strong{not} download blocks again that are
+already present.
+
+GNUnet's file-encoding mechanism will ensure file integrity, even if the
+existing file was not downloaded from GNUnet in the first place.
+
+You may want to use the @command{-V} switch to turn on verbose
+reporting. In this case, @command{gnunet-download} will print the
+current number of bytes downloaded whenever new data was received.
+
+@node fs-Publishing
+@subsection Publishing
+@c %**end of header
+
+The command @command{gnunet-publish} can be used to add content
+to the network. The basic format of the command is
+
+@example
+$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
+@end example
+
+For example
+@example
+$ gnunet-publish -m "description:GNU License" -k gpl -k test -m "mimetype:text/plain" COPYING
+@end example
+
+@menu
+* Important command-line options::
+* Indexing vs. Inserting::
 @end menu
 
-@node File-sharing Concepts
-@subsection File-sharing Concepts
+@node Important command-line options
+@subsubsection Important command-line options
 @c %**end of header
 
-Sharing files in GNUnet is not quite as simple as in traditional
-file sharing systems. For example, it is not sufficient to just
-place files into a specific directory to share them. In addition
-to anonymous routing GNUnet attempts to give users a better experience
-in searching for content. GNUnet uses cryptography to safely break
-content into smaller pieces that can be obtained from different
-sources without allowing participants to corrupt files. GNUnet
-makes it difficult for an adversary to send back bogus search
-results. GNUnet enables content providers to group related content
-and to establish a reputation. Furthermore, GNUnet allows updates
-to certain content to be made available. This section is supposed
-to introduce users to the concepts that are used to achive these goals.
+The option @code{-k} is used to specify keywords for the file that
+should be inserted. You can supply any number of keywords,
+and each of the keywords will be sufficient to locate and
+retrieve the file. Please note that you must use the @code{-k} option
+more than once -- one for each expression you use as a keyword for
+the filename.
+
+The -m option is used to specify meta-data, such as descriptions.
+You can use -m multiple times. The TYPE passed must be from the
+list of meta-data types known to libextractor. You can obtain this
+list by running @command{extract -L}. Use quotes around the entire
+meta-data argument if the value contains spaces. The meta-data
+is displayed to other users when they select which files to
+download. The meta-data and the keywords are optional and
+may be inferred using @code{GNU libextractor}.
+
+@command{gnunet-publish} has a few additional options to handle
+namespaces and directories. Refer to the man-page for details:
+
+@example
+man gnunet-publish
+@end example
+
+@node Indexing vs. Inserting
+@subsubsection Indexing vs Inserting
+@c %**end of header
+
+By default, GNUnet indexes a file instead of making a full copy.
+This is much more efficient, but requires the file to stay unaltered
+at the location where it was when it was indexed. If you intend to move,
+delete or alter a file, consider using the option @code{-n} which will
+force GNUnet to make a copy of the file in the database.
+
+Since it is much less efficient, this is strongly discouraged for large
+files. When GNUnet indexes a file (default), GNUnet does @strong{not}
+create an additional encrypted copy of the file but just computes a
+summary (or index) of the file. That summary is approximately two percent
+of the size of the original file and is stored in GNUnet's database.
+Whenever a request for a part of an indexed file reaches GNUnet,
+this part is encrypted on-demand and send out. This way, there is no
+need for an additional encrypted copy of the file to stay anywhere
+on the drive. This is different from other systems, such as Freenet,
+where each file that is put online must be in Freenet's database in
+encrypted format, doubling the space requirements if the user wants
+to preserve a directly accessible copy in plaintext.
+
+Thus indexing should be used for all files where the user will keep
+using this file (at the location given to gnunet-publish) and does
+not want to retrieve it back from GNUnet each time. If you want to
+remove a file that you have indexed from the local peer, use the tool
+@command{gnunet-unindex} to un-index the file.
+
+The option @code{-n} may be used if the user fears that the file might
+be found on their drive (assuming the computer comes under the control
+of an adversary). When used with the @code{-n} flag, the user has a
+much better chance of denying knowledge of the existence of the file,
+even if it is still (encrypted) on the drive and the adversary is
+able to crack the encryption (e.g. by guessing the keyword.
+
+@node fs-Concepts
+@subsection Concepts
+@c %**end of header
+
+For better results with filesharing it is useful to understand the
+following concepts.
+In addition to anonymous routing GNUnet attempts to give users a better
+experience in searching for content. GNUnet uses cryptography to safely
+break content into smaller pieces that can be obtained from different
+sources without allowing participants to corrupt files. GNUnet makes it
+difficult for an adversary to send back bogus search results. GNUnet
+enables content providers to group related content and to establish a
+reputation. Furthermore, GNUnet allows updates to certain content to be
+made available. This section is supposed to introduce users to the
+concepts that are used to achieve these goals.
 
 
 @menu
@@ -958,10 +940,10 @@ to introduce users to the concepts that are used to achive these goals.
 @c %**end of header
 
 A file in GNUnet is just a sequence of bytes. Any file-format is allowed
-and the maximum file size is theoretically 264 bytes, except that it
-would take an impractical amount of time to share such a file.
-GNUnet itself never interprets the contents of shared files, except
-when using GNU libextractor to obtain keywords.
+and the maximum file size is theoretically @math{2^64 - 1} bytes, except
+that it would take an impractical amount of time to share such a file.
+GNUnet itself never interprets the contents of shared files, except when
+using GNU libextractor to obtain keywords.
 
 @node Keywords
 @subsubsection Keywords
@@ -991,10 +973,26 @@ it cannot be changed since it is treated just like an ordinary file
 by the network. Small files (of a few kilobytes) can be inlined in
 the directory, so that a separate download becomes unnecessary.
 
+Directories are shared just like ordinary files. If you download a
+directory with @command{gnunet-download}, you can use
+@command{gnunet-directory} to list its contents. The canonical
+extension for GNUnet directories when stored as files in your
+local file-system is ".gnd". The contents of a directory are URIs and
+meta data.
+The URIs contain all the information required by
+@command{gnunet-download} to retrieve the file. The meta data
+typically includes the mime-type, description, a filename and
+other meta information, and possibly even the full original file
+(if it was small).
+
 @node Pseudonyms
 @subsubsection Pseudonyms
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
 that allow a GNUnet user to maintain an identity (which may or may not
 be detached from their real-life identity). GNUnet's pseudonyms are not
@@ -1010,6 +1008,10 @@ to copy around).
 @subsubsection Namespaces
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 A namespace is a set of files that were signed by the same pseudonym.
 Files (or directories) that have been signed and placed into a namespace
 can be updated. Updates are identified as authentic if the same secret
@@ -1021,19 +1023,23 @@ same entity (which does not have to be the same person).
 @subsubsection Advertisements
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 Advertisements are used to notify other users about the existence of a
 namespace. Advertisements are propagated using the normal keyword search.
 When an advertisement is received (in response to a search), the namespace
 is added to the list of namespaces available in the namespace-search
-dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
+dialogs of gnunet-fs-gtk and printed by @code{gnunet-identity}. Whenever a
 namespace is created, an appropriate advertisement can be generated.
 The default keyword for the advertising of namespaces is "namespace".
 
-Note that GNUnet differenciates between your pseudonyms (the identities
+Note that GNUnet differentiates between your pseudonyms (the identities
 that you control) and namespaces. If you create a pseudonym, you will
 not automatically see the respective namespace. You first have to create
 an advertisement for the namespace and find it using keyword
-search --- even for your own namespaces. The @command{gnunet-pseudonym}
+search --- even for your own namespaces. The @command{gnunet-identity}
 tool is currently responsible for both managing pseudonyms and namespaces.
 This will likely change in the future to reduce the potential for
 confusion.
@@ -1080,205 +1086,16 @@ replication level into the network, and then decrement the replication
 level by one. If all blocks reach replication level zero, the
 selection is simply random.
 
-@node File-sharing Publishing
-@subsection File-sharing Publishing
-@c %**end of header
-
-The command @command{gnunet-publish} can be used to add content
-to the network. The basic format of the command is
-
-@example
-$ gnunet-publish [-n] [-k KEYWORDS]* [-m TYPE:VALUE] FILENAME
-@end example
-
 
-@menu
-* Important command-line options::
-* Indexing vs. Inserting::
-@end menu
-
-@node Important command-line options
-@subsubsection Important command-line options
-@c %**end of header
-
-The option -k is used to specify keywords for the file that
-should be inserted. You can supply any number of keywords,
-and each of the keywords will be sufficient to locate and
-retrieve the file.
-
-The -m option is used to specify meta-data, such as descriptions.
-You can use -m multiple times. The TYPE passed must be from the
-list of meta-data types known to libextractor. You can obtain this
-list by running @command{extract -L}. Use quotes around the entire
-meta-data argument if the value contains spaces. The meta-data
-is displayed to other users when they select which files to
-download. The meta-data and the keywords are optional and
-maybe inferred using @code{GNU libextractor}.
-
-gnunet-publish has a few additional options to handle namespaces and
-directories. See the man-page for details.
-
-@node Indexing vs. Inserting
-@subsubsection Indexing vs Inserting
-@c %**end of header
-
-By default, GNUnet indexes a file instead of making a full copy.
-This is much more efficient, but requries the file to stay unaltered
-at the location where it was when it was indexed. If you intend to move,
-delete or alter a file, consider using the option @code{-n} which will
-force GNUnet to make a copy of the file in the database.
-
-Since it is much less efficient, this is strongly discouraged for large
-files. When GNUnet indexes a file (default), GNUnet does @strong{not}
-create an additional encrypted copy of the file but just computes a
-summary (or index) of the file. That summary is approximately two percent
-of the size of the original file and is stored in GNUnet's database.
-Whenever a request for a part of an indexed file reaches GNUnet,
-this part is encrypted on-demand and send out. This way, there is no
-need for an additional encrypted copy of the file to stay anywhere
-on the drive. This is different from other systems, such as Freenet,
-where each file that is put online must be in Freenet's database in
-encrypted format, doubling the space requirements if the user wants
-to preseve a directly accessible copy in plaintext.
-
-Thus indexing should be used for all files where the user will keep
-using this file (at the location given to gnunet-publish) and does
-not want to retrieve it back from GNUnet each time. If you want to
-remove a file that you have indexed from the local peer, use the tool
-@command{gnunet-unindex} to un-index the file.
-
-The option @code{-n} may be used if the user fears that the file might
-be found on their drive (assuming the computer comes under the control
-of an adversary). When used with the @code{-n} flag, the user has a
-much better chance of denying knowledge of the existence of the file,
-even if it is still (encrypted) on the drive and the adversary is
-able to crack the encryption (e.g. by guessing the keyword.
-
-@node File-sharing Searching
-@subsection File-sharing Searching
-@c %**end of header
-
-The command @command{gnunet-search} can be used to search
-for content on GNUnet. The format is:
-
-@example
-$ gnunet-search [-t TIMEOUT] KEYWORD
-@end example
-
-@noindent
-The -t option specifies that the query should timeout after
-approximately TIMEOUT seconds. A value of zero is interpreted
-as @emph{no timeout}, which is also the default. In this case,
-gnunet-search will never terminate (unless you press CTRL-C).
-
-If multiple words are passed as keywords, they will all be
-considered optional. Prefix keywords with a "+" to make them mandatory.
-
-Note that searching using
-
-@example
-$ gnunet-search Das Kapital
-@end example
-
-@noindent
-is not the same as searching for
-
-@example
-$ gnunet-search "Das Kapital"
-@end example
-
-@noindent
-as the first will match files shared under the keywords
-"Das" or "Kapital" whereas the second will match files
-shared under the keyword "Das Kapital".
-
-Search results are printed by gnunet-search like this:
-
-@c it will be better the avoid the ellipsis altogether because I don't
-@c understand the explanation below that
-@example
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
-=> The GNU Public License <= (mimetype: text/plain)
-@end example
-
-@noindent
-The first line is the command you would have to enter to download
-the file. The argument passed to @code{-o} is the suggested
-filename (you may change it to whatever you like).
-@c except it's triple dash in the above example ---
-The @code{--} is followed by key for decrypting the file,
-the query for searching the file, a checksum (in hexadecimal)
-finally the size of the file in bytes.
-The second line contains the description of the file; here this is
-"The GNU Public License" and the mime-type (see the options for
-gnunet-publish on how to specify these).
-
-@node File-sharing Downloading
-@subsection File-sharing Downloading
-@c %**end of header
-
-In order to download a file, you need the three values returned by
-@command{gnunet-search}.
-You can then use the tool @command{gnunet-download} to obtain the file:
-
-@example
-$ gnunet-download -o FILENAME --- GNUNETURL
-@end example
-
-@noindent
-FILENAME specifies the name of the file where GNUnet is supposed
-to write the result. Existing files are overwritten. If the
-existing file contains blocks that are identical to the
-desired download, those blocks will not be downloaded again
-(automatic resume).
-
-If you want to download the GPL from the previous example,
-you do the following:
-
-@example
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
-@end example
-
-@noindent
-If you ever have to abort a download, you can continue it at any time by
-re-issuing @command{gnunet-download} with the same filename.
-In that case, GNUnet will @strong{not} download blocks again that are
-already present.
-
-GNUnet's file-encoding mechanism will ensure file integrity, even if the
-existing file was not downloaded from GNUnet in the first place.
-
-You may want to use the @command{-V} switch (must be added before
-@c Same as above it's triple dash
-the @command{--}) to turn on verbose reporting. In this case,
-@command{gnunet-download} will print the current number of
-bytes downloaded whenever new data was received.
-
-@node File-sharing Directories
-@subsection File-sharing Directories
-@c %**end of header
-
-Directories are shared just like ordinary files. If you download a
-directory with @command{gnunet-download}, you can use
-@command{gnunet-directory} to list its contents. The canonical
-extension for GNUnet directories when stored as files in your
-local file-system is ".gnd". The contents of a directory are URIs and
-meta data.
-The URIs contain all the information required by
-@command{gnunet-download} to retrieve the file. The meta data
-typically includes the mime-type, description, a filename and
-other meta information, and possibly even the full original file
-(if it was small).
-
-@node File-sharing Namespace Management
-@subsection File-sharing Namespace Management
+@node Namespace Management
+@subsection Namespace Management
 @c %**end of header
 
 @b{Please note that the text in this subsection is outdated and needs}
 @b{to be rewritten for version 0.10!}
 
-The gnunet-pseudonym tool can be used to create pseudonyms and
-to advertise namespaces. By default, gnunet-pseudonym simply
+The @code{gnunet-identity} tool can be used to create pseudonyms and
+to advertise namespaces. By default, @code{gnunet-identity -D} simply
 lists all locally available pseudonyms.
 
 
@@ -1294,6 +1111,10 @@ lists all locally available pseudonyms.
 @subsubsection Creating Pseudonyms
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 With the @command{-C NICK} option it can also be used to
 create a new pseudonym. A pseudonym is the virtual identity
 of the entity in control of a namespace. Anyone can create
@@ -1305,6 +1126,10 @@ used.
 @subsubsection Deleting Pseudonyms
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 With the @command{-D NICK} option pseudonyms can be deleted.
 Once the pseudonym has been deleted it is impossible to add
 content to the corresponding namespace. Deleting the
@@ -1315,6 +1140,10 @@ unavailable.
 @subsubsection Advertising namespaces
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 Each namespace is associated with meta-data that describes
 the namespace. This meta-data is provided by the user at
 the time that the namespace is advertised. Advertisements
@@ -1331,6 +1160,10 @@ the quality of the content found in it.
 @subsubsection Namespace names
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 While the namespace is uniquely identified by its ID, another way
 to refer to the namespace is to use the NICKNAME.
 The NICKNAME can be freely chosen by the creator of the namespace and
@@ -1342,6 +1175,10 @@ to the NICKNAME to get a unique identifier.
 @subsubsection Namespace root
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 An item of particular interest in the namespace advertisement is
 the ROOT. The ROOT is the identifier of a designated entry in the
 namespace. The idea is that the ROOT can be used to advertise an
@@ -1355,6 +1192,11 @@ GNUnet (currently) uses four different types of URIs for
 file-sharing. They all begin with "gnunet://fs/".
 This section describes the four different URI types in detail.
 
+For FS URIs empty KEYWORDs are not allowed. Quotes are allowed to
+denote whitespace between words. Keywords must contain a balanced
+number of double quotes. Doubles quotes can not be used in the actual
+keywords. This means that the the string '""foo bar""' will be turned
+into two OR-ed keywords 'foo' and 'bar', not into '"foo bar"'.
 
 @menu
 * Encoding of hash values in URIs::
@@ -1371,6 +1213,7 @@ This section describes the four different URI types in detail.
 Most URIs include some hash values. Hashes are encoded using
 base32hex (RFC 2938).
 
+@cindex chk-uri
 @node Content Hash Key (chk)
 @subsubsection Content Hash Key (chk)
 @c %**end of header
@@ -1387,6 +1230,7 @@ shape of the tree), KEYHASH is the key used to decrypt the file
 is the query used to request the top-level block (also the hash
 of the encrypted block).
 
+@cindex loc-uri
 @node Location identifiers (loc)
 @subsubsection Location identifiers (loc)
 @c %**end of header
@@ -1402,6 +1246,7 @@ base32hex), SIG is the RSA signature (in GNUnet format in
 base32hex) and EXPTIME specifies when the signature expires
 (in milliseconds after 1970).
 
+@cindex ksk-uri
 @node Keyword queries (ksk)
 @subsubsection Keyword queries (ksk)
 @c %**end of header
@@ -1413,11 +1258,18 @@ using the typical URI-encoding (using hex values) from HTTP.
 "+" can be used to specify multiple keywords (which are then
 logically "OR"-ed in the search, results matching both keywords
 are given a higher rank): "gnunet://fs/ksk/KEYWORD1+KEYWORD2".
+ksk-URIs must not begin or end with the plus ('+') character.
+Furthermore they must not contain '++'.
 
+@cindex sks-uri
 @node Namespace content (sks)
 @subsubsection Namespace content (sks)
 @c %**end of header
 
+@b{Please note that the text in this subsection is outdated and needs}
+@b{to be rewritten for version 0.10!}
+@b{This especially concerns the terminology of Pseudonym/Ego/Identity.}
+
 Namespaces are sets of files that have been approved by some (usually
 pseudonymous) user --- typically by that user publishing all of the
 files together. A file can be in many namespaces. A file is in a
@@ -1431,6 +1283,135 @@ chosen keyword (or password!). A commonly used identifier is
 "root" which by convention refers to some kind of index or other
 entry point into the namespace.
 
+@node GTK User Interface
+@subsection GTK User Interface
+This chapter describes first steps for file-sharing with GNUnet.
+To start, you should launch @command{gnunet-fs-gtk}.
+
+As we want to be sure that the network contains the data that we are
+looking for for testing, we need to begin by publishing a file.
+
+@menu
+* gtk-Publishing::
+* gtk-Searching::
+* gtk-Downloading::
+@end menu
+
+@node gtk-Publishing
+@subsubsection Publishing
+@c %**end of header
+
+To publish a file, select "File Sharing" in the menu bar just below the
+"Statistics" icon, and then select "Publish" from the menu.
+
+Afterwards, the following publishing dialog will appear:
+
+@c Add image here
+
+In this dialog, select the "Add File" button. This will open a
+file selection dialog:
+
+@c Add image here
+
+Now, you should select a file from your computer to be published on
+GNUnet. To see more of GNUnet's features later, you should pick a
+PNG or JPEG file this time. You can leave all of the other options
+in the dialog unchanged. Confirm your selection by pressing the "OK"
+button in the bottom right corner. Now, you will briefly see a
+"Messages..." dialog pop up, but most likely it will be too short for
+you to really read anything. That dialog is showing you progress
+information as GNUnet takes a first look at the selected file(s).
+For a normal image, this is virtually instant, but if you later
+import a larger directory you might be interested in the progress dialog
+and potential errors that might be encountered during processing.
+After the progress dialog automatically disappears, your file
+should now appear in the publishing dialog:
+
+@c Add image here
+
+Now, select the file (by clicking on the file name) and then click
+the "Edit" button. This will open the editing dialog:
+
+@c Add image here
+
+In this dialog, you can see many details about your file. In the
+top left area, you can see meta data extracted about the file,
+such as the original filename, the mimetype and the size of the image.
+In the top right, you should see a preview for the image
+(if GNU libextractor was installed correctly with the
+respective plugins). Note that if you do not see a preview, this
+is not a disaster, but you might still want to install more of
+GNU libextractor in the future. In the bottom left, the dialog contains
+a list of keywords. These are the keywords under which the file will be
+made available. The initial list will be based on the extracted meta data.
+Additional publishing options are in the right bottom corner. We will
+now add an additional keyword to the list of keywords. This is done by
+entering the keyword above the keyword list between the label "Keyword"
+and the "Add keyword" button. Enter "test" and select "Add keyword".
+Note that the keyword will appear at the bottom of the existing keyword
+list, so you might have to scroll down to see it. Afterwards, push the
+"OK" button at the bottom right of the dialog.
+
+You should now be back at the "Publish content on GNUnet" dialog. Select
+"Execute" in the bottom right to close the dialog and publish your file
+on GNUnet! Afterwards, you should see the main dialog with a new area
+showing the list of published files (or ongoing publishing operations
+with progress indicators):
+
+@c Add image here
+
+@node gtk-Searching
+@subsubsection Searching
+@c %**end of header
+
+Below the menu bar, there are four entry widges labeled "Namespace",
+"Keywords", "Anonymity" and "Mime-type" (from left to right). These
+widgets are used to control searching for files in GNUnet. Between the
+"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
+which is used to initiate the search. We will ignore the "Namespace",
+"Anonymity" and "Mime-type" options in this tutorial, please leave them
+empty. Instead, simply enter "test" under "Keywords" and press "Search".
+Afterwards, you should immediately see a new tab labeled after your
+search term, followed by the (current) number of search
+results --- "(15)" in our screenshot. Note that your results may
+vary depending on what other users may have shared and how your
+peer is connected.
+
+You can now select one of the search results. Once you do this,
+additional information about the result should be displayed on the
+right. If available, a preview image should appear on the top right.
+Meta data describing the file will be listed at the bottom right.
+
+Once a file is selected, at the bottom of the search result list
+a little area for downloading appears.
+
+@node gtk-Downloading
+@subsubsection Downloading
+@c %**end of header
+
+In the downloading area, you can select the target directory (default is
+"Downloads") and specify the desired filename (by default the filename it
+taken from the meta data of the published file). Additionally, you can
+specify if the download should be anonymous and (for directories) if
+the download should be recursive. In most cases, you can simply start
+the download with the "Download!" button.
+
+Once you selected download, the progress of the download will be
+displayed with the search result. You may need to resize the result
+list or scroll to the right. The "Status" column shows the current
+status of the download, and "Progress" how much has been completed.
+When you close the search tab (by clicking on the "X" button next to
+the "test" label), ongoing and completed downloads are not aborted
+but moved to a special "*" tab.
+
+You can remove completed downloads from the "*" tab by clicking the
+cleanup button next to the "*". You can also abort downloads by right
+clicking on the respective download and selecting "Abort download"
+from the menu.
+
+That's it, you now know the basics for file-sharing with GNUnet!
+
+
 @node The GNU Name System
 @section The GNU Name System
 @c %**end of header
@@ -1466,47 +1447,42 @@ the user. This results in non-unique name-value mappings as
 
 
 @menu
+* Creating a Zone::
 * Maintaining your own Zones::
 * Obtaining your Zone Key::
 * Adding Links to Other Zones::
-* The Three Local Zones of GNS::
-* The Master Zone::
-* The Private Zone::
-* The Shorten Zone::
-* The ZKEY Top Level Domain in GNS::
+* Using Public Keys as Top Level Domains::
 * Resource Records in GNS::
+* Synchronizing with legacy DNS::
 @end menu
 
 
-@node Maintaining your own Zones
-@subsection Maintaining your own Zones
+@node Creating a Zone
+@subsection Creating a Zone
 
-To setup your GNS system you must execute:
+To use GNS, you probably should create at least one zone of your own.
+You can create any number of zones using the gnunet-identity tool
+using:
 
 @example
-$ gnunet-gns-import.sh
+$ gnunet-identity -C "myzone"
 @end example
 
-@noindent
-This will boostrap your zones and create the necessary key material.
-Your keys can be listed using the @command{gnunet-identity}
-command line tool:
+Henceforth, on your system you control the TLD ``myzone''.
+
+All of your zones can be listed (displayed) using the
+@command{gnunet-identity} command line tool as well:
 
 @example
 $ gnunet-identity -d
 @end example
 
-@noindent
-You can arbitrarily create your own zones using the gnunet-identity
-tool using:
-
-@example
-$ gnunet-identity -C "new_zone"
-@end example
+@node Maintaining your own Zones
+@subsection Maintaining your own Zones
 
 @noindent
 Now you can add (or edit, or remove) records in your GNS zone using the
-@command{gnunet-setup} GUI or using the @command{gnunet-namestore}
+@command{gnunet-namestore-gtk} GUI or using the @command{gnunet-namestore}
 command-line tool.
 In either case, your records will be stored in an SQL database under
 control of the @command{gnunet-service-namestore}.
@@ -1518,21 +1494,21 @@ if they are marked as private.
 To provide a short example for editing your own zone, suppose you
 have your own web server with the IP @code{1.2.3.4}. Then you can put an
 @code{A} record (@code{A} records in DNS are for IPv4 IP addresses)
-into your local zone using the command:
+into your local zone ``myzone'' using the command:
 
 @example
-$ gnunet-namestore -z master-zone -a -n www -t A -V 1.2.3.4 -e never
+$ gnunet-namestore -z myzone -a -n www -t A -V 1.2.3.4 -e never
 @end example
 
 @noindent
-Afterwards, you will be able to access your webpage under "www.gnu"
+Afterwards, you will be able to access your webpage under "www.myzone"
 (assuming your webserver does not use virtual hosting, if it does,
 please read up on setting up the GNS proxy).
 
 Similar commands will work for other types of DNS and GNS records,
 the syntax largely depending on the type of the record.
 Naturally, most users may find editing the zones using the
-@command{gnunet-setup} GUI to be easier.
+@command{gnunet-namestore-gtk} GUI to be easier.
 
 @node Obtaining your Zone Key
 @subsection Obtaining your Zone Key
@@ -1546,7 +1522,7 @@ give it to others so that they can securely link to you.
 You can usually get the hash of your public key using
 
 @example
-$ gnunet-identity -d $options | grep master-zone | awk '@{print $3@}'
+$ gnunet-identity -d $options | grep myzone | awk '@{print $3@}'
 @end example
 
 @noindent
@@ -1557,10 +1533,10 @@ DC3SEECJORPHQNVRH965A6N74B1M37S721IG4RBQ15PJLLPJKUE0
 @end example
 
 @noindent
-Alternatively, you can obtain a QR code with your zone key AND
-your pseudonym from gnunet-gtk. The QR code is displayed in the
-GNS tab and can be stored to disk using the Save as button next
-to the image.
+Alternatively, you can obtain a QR code with your zone key AND your
+pseudonym from gnunet-namestore-gtk. The QR code is displayed in the
+main window and can be stored to disk using the ``Save as'' button
+next to the image.
 
 @node Adding Links to Other Zones
 @subsection Adding Links to Other Zones
@@ -1576,90 +1552,38 @@ You can then delegate resolution of names to Bob's zone by adding
 a PKEY record to their local zone:
 
 @example
-$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never
+$ gnunet-namestore -a -n bob --type PKEY -V XXXX -e never -Z myzone
 @end example
 
 @noindent
-Note that XXXX in the command above must be replaced with the
-hash of Bob's public key (the output your friend obtained using
-the gnunet-identity command from the previous section and told you,
-for example by giving you a business card containing this
+Note that ``XXXX'' in the command above must be replaced with the hash
+of Bob's public key (the output your friend obtained using the
+@command{gnunet-identity} command from the previous section and told
+you, for example by giving you a business card containing this
 information as a QR code).
 
-Assuming Bob has an A record for their website under the name of
-www in his zone, you can then access Bob's website under
-www.bob.gnu --- as well as any (public) GNS record that Bob has
+Assuming Bob has an ``A'' record for their website under the name of
+``www'' in his zone, you can then access Bob's website under
+``www.bob.myzone'' --- as well as any (public) GNS record that Bob has
 in their zone by replacing www with the respective name of the
 record in Bob's zone.
 
 @c themselves? themself?
 Furthermore, if Bob has themselves a (public) delegation to Carol's
 zone under "carol", you can access Carol's records under
-NAME.carol.bob.gnu (where NAME is the name of Carol's record you
-want to access).
-
-@node The Three Local Zones of GNS
-@subsection The Three Local Zones of GNS
-
-Each user GNS has control over three zones. Each of the zones
-has a different purpose. These zones are the
-
-@itemize @bullet
-
-@item master zone,
-@item private zone, and the
-@item shorten zone.
-@end itemize
-
-@node The Master Zone
-@subsection The Master Zone
-
-
-The master zone is your personal TLD. Names within the @code{.gnu}
-namespace are resolved relative to this zone. You can arbitrarily
-add records to this zone and selectively publish those records.
-
-@node The Private Zone
-@subsection The Private Zone
-
+``NAME.carol.bob.myzone'' (where ``NAME'' is the name of Carol's
+record you want to access).
 
-The private zone is a subzone (or subdomain in DNS terms) of your
-master zone. It should be used for records that you want to keep
-private. For example @code{bank.private.gnu}. The key idea is that
-you want to keep your private records separate, if just to know
-that those names are not available to other users.
 
-@node The Shorten Zone
-@subsection The Shorten Zone
+@node Using Public Keys as Top Level Domains
+@subsection Using Public Keys as Top Level Domains
 
 
-The shorten zone can either be a subzone of the master zone or the
-private zone. It is different from the other zones in that GNS
-will automatically populate this zone with other users' zones based
-on their PSEU records whenever you resolve a name.
-
-For example if you go to
-@code{@uref{http://www.bob.alice.dave.gnu/, www.bob.alice.dave.gnu}},
-GNS will try to import @code{bob} into your shorten zone. Having
-obtained Bob's PKEY from @code{alice.dave.gnu}, GNS will lookup the
-PSEU record for @code{+} in Bob's zone. If it exists and the specified
-pseudonym is not taken, Bob's PKEY will be automatically added under
-that pseudonym (i.e. "bob") into your shorten zone. From then on,
-Bob's webpage will also be available for you as
-@code{@uref{http://www.bob.short.gnu/, www.bob.short.gnu}}.
-This feature is called @b{automatic name shortening} and is supposed to
-keep GNS names as short and memorable as possible.
-
-@node The ZKEY Top Level Domain in GNS
-@subsection The ZKEY Top Level Domain in GNS
-
-
-GNS also provides a secure and globally unique namespace under the .zkey
-top-level domain. A name in the .zkey TLD corresponds to the (printable)
-public key of a zone. Names in the .zkey TLD are then resolved by querying
-the respective zone. The .zkey TLD is expected to be used under rare
-circumstances where globally unique names are required and for
-integration with legacy systems.
+GNS also assumes responsibility for any name that uses in a
+well-formed public key for the TLD.  Names ending this way are then
+resolved by querying the respective zone. Such public key TLDs are
+expected to be used under rare circumstances where globally unique
+names are required, and for integration with legacy systems.
 
 @node Resource Records in GNS
 @subsection Resource Records in GNS
@@ -1682,7 +1606,7 @@ to the current authoritative zone. The extended processing of those
 names will expand the ".+" with the correct delegation chain to the
 authoritative zone (replacing ".+" with the name of the location
 where the name was encountered) and hence generate a
-valid @code{.gnu} name.
+valid GNS name.
 
 GNS currently supports the following record types:
 
@@ -1696,28 +1620,43 @@ GNS currently supports the following record types:
 * CNAME::
 * GNS2DNS::
 * SOA SRV PTR and MX::
+* PLACE::
+* PHONE::
+* ID ATTR::
+* ID TOKEN::
+* ID TOKEN METADATA::
+* CREDENTIAL::
+* POLICY::
+* ATTRIBUTE::
+* ABE KEY::
+* ABE MASTER::
+* RECLAIM OIDC CLIENT::
+* RECLAIM OIDC REDIRECT::
 @end menu
 
 @node NICK
 @subsubsection NICK
 
-A NICK record is used to give a zone a name. With a NICK record, you can
-essentially specify how you would like to be called. GNS expects this
-record under the name "+" in the zone's database (NAMESTORE); however,
-it will then automatically be copied into each record set, so that
-clients never need to do a separate lookup to discover the NICK record.
+A NICK record is used to give a zone a name. With a NICK record, you
+can essentially specify how you would like to be called. GNS expects
+this record under the empty label ``@@'' in the zone's database
+(NAMESTORE); however, it will then automatically be copied into each
+record set, so that clients never need to do a separate lookup to
+discover the NICK record.  Also, users do not usually have to worry
+about setting the NICK record: it is automatically set to the local
+name of the TLD.
 
 @b{Example}@
 
 @example
-Name: +; RRType: NICK; Value: bob
+Name: @@; RRType: NICK; Value: bob
 @end example
 
 @noindent
 This record in Bob's zone will tell other users that this zone wants
 to be referred to as 'bob'. Note that nobody is obliged to call Bob's
 zone 'bob' in their own zones. It can be seen as a
-recommendation ("Please call me 'bob'").
+recommendation ("Please call this zone 'bob'").
 
 @node PKEY
 @subsubsection PKEY
@@ -1864,6 +1803,188 @@ should use the ZKEY zone as the destination hostname and
 GNS-enabled mail servers should be configured to accept
 e-mails to the ZKEY-zones of all local users.
 
+@node PLACE
+@subsubsection PLACE
+
+Record type for a social place.
+
+@node PHONE
+@subsubsection PHONE
+
+Record type for a phone (of CONVERSATION).
+
+@node ID ATTR
+@subsubsection ID ATTR
+
+Record type for identity attributes (of IDENTITY).
+
+@node ID TOKEN
+@subsubsection ID TOKEN
+
+Record type for an identity token (of IDENTITY-TOKEN).
+
+@node ID TOKEN METADATA
+@subsubsection ID TOKEN METADATA
+
+Record type for the private metadata of an identity token (of IDENTITY-TOKEN).
+
+@node CREDENTIAL
+@subsubsection CREDENTIAL
+
+Record type for credential.
+
+@node POLICY
+@subsubsection POLICY
+
+Record type for policies.
+
+@node ATTRIBUTE
+@subsubsection ATTRIBUTE
+
+Record type for reverse lookups.
+
+@node ABE KEY
+@subsubsection ABE KEY
+
+Record type for ABE records.
+
+@node ABE MASTER
+@subsubsection ABE MASTER
+
+Record type for ABE master keys.
+
+@node RECLAIM OIDC CLIENT
+@subsubsection RECLAIM OIDC CLIENT
+
+Record type for reclaim OIDC clients.
+
+@node RECLAIM OIDC REDIRECT
+@subsubsection RECLAIM OIDC REDIRECT
+
+Record type for reclaim OIDC redirect URIs.
+
+@node Synchronizing with legacy DNS
+@subsection Synchronizing with legacy DNS
+
+If you want to support GNS but the master database for a zone
+is only available and maintained in DNS, GNUnet includes the
+@command{gnunet-zoneimport} tool to monitor a DNS zone and
+automatically import records into GNS.  Today, the tool does
+not yet support DNS AF(X)R, as we initially used it on the
+``.fr'' zone which does not allow us to perform a DNS zone
+transfer.  Instead, @command{gnunet-zoneimport} reads a list
+of DNS domain names from @code{stdin}, issues DNS queries for
+each, converts the obtained records (if possible) and stores
+the result in the namestore.
+
+@image{images/gns,6in,, picture of DNS-GNS data flow}
+
+The zonemaster service then takes the records from the namestore,
+publishes them into the DHT which makes the result available to the
+GNS resolver.  In the GNS configuration, non-local zones can be
+configured to be intercepted by specifying ``.tld = PUBLICKEY'' in the
+configuration file in the ``[gns]'' section.
+
+Note that the namestore by default also populates the namecache.
+This pre-population is cryptographically expensive. Thus, on
+systems that only serve to import a large (millions of records)
+DNS zone and that do not have a local gns service in use, it
+is thus advisable to disable the namecache by setting the
+option ``DISABLE'' to ``YES'' in section ``[namecache]''.
+
+
+@node re@:claim Identity Provider
+@section re@:claim Identity Provider
+
+The re:claim Identity Provider (IdP) is a decentralized IdP service.
+It allows its users to manage and authorize third parties to access their identity attributes such as email or shipping addresses.
+
+It basically mimics the concepts of centralized IdPs, such as those offered by Google or Facebook.
+Like other IdPs, re:claim features an (optional) OpenID-Connect 1.0-compliant protocol layer that can be used for websites to integrate re:claim as an Identity Provider with little effort.
+
+@menu
+* Managing Attributes::
+* Sharing Attributes with Third Parties::
+* Revoking Authorizations of Third Parties::
+* Using the OpenID-Connect IdP::
+@end menu
+
+@node Managing Attributes
+@subsection Managing Attributes
+
+Before adding attributes to an identity, you must first create an ego:
+
+@example
+$ gnunet-identity -C "username"
+@end example
+
+Henceforth, you can manage a new user profile of the user ``username''.
+
+To add an email address to your user profile, simply use the @command{gnunet-reclaim} command line tool::
+
+@example
+$ gnunet-reclaim -e "username" -a "email" -V "username@@example.gnunet"
+@end example
+
+All of your attributes can be listed using the @command{gnunet-reclaim}
+command line tool as well:
+
+@example
+$ gnunet-reclaim -e "username" -D
+@end example
+
+Currently, and by default, attribute values are interpreted as plain text.
+In the future there might be more value types such as X.509 certificate credentials.
+
+@node Sharing Attributes with Third Parties
+@subsection Sharing Attributes with Third Parties
+
+If you want to allow a third party such as a website or friend to access to your attributes (or a subset thereof) execute:
+
+@example
+$ gnunet-reclaim -e "username" -r "PKEY" -i "attribute1,attribute2,..."
+@end example
+
+Where "PKEY" is the public key of the third party and "attribute1,attribute2,..." is a comma-separated list of attribute names, such as "email", that you want to share.
+
+The command will return a "ticket" string.
+You must give this "ticket" to the requesting third party.
+
+The third party can then retrieve your shared identity attributes using:
+
+@example
+$ gnunet-reclaim -e "friend" -C "ticket"
+@end example
+
+This will retrieve and list the shared identity attributes.
+The above command will also work if the user "username" is currently offline since the attributes are retrieved from GNS.
+Further, the "ticket" can be re-used later to retrieve up-to-date attributes in case "username" has changed the value(s). For instance, becasue his email address changed.
+
+To list all given authorizations (tickets) you can execute:
+@example
+$ gnunet-reclaim -e "friend" -T (TODO there is only a REST API for this ATM) 
+@end example
+
+
+@node Revoking Authorizations of Third Parties
+@subsection Revoking Authorizations of Third Parties
+
+If you want to revoke the access of a third party to your attributes you can execute:
+
+@example
+$ gnunet-idp -e "username" -R "ticket"
+@end example
+
+This will prevent the third party from accessing the attribute in the future.
+Please note that if the third party has previously accessed the attribute, there is not way in which the system could have prevented the thiry party from storing the data.
+As such, only access to updated data in the future can be revoked.
+This behaviour is _exactly the same_ as with other IdPs.
+
+@node Using the OpenID-Connect IdP
+@subsection Using the OpenID-Connect IdP
+
+TODO: Document setup and REST endpoints
+
 @node Using the Virtual Public Network
 @section Using the Virtual Public Network
 
@@ -2036,7 +2157,7 @@ destination.
 
 For applications that do not use DNS, you can also manually create
 such a mapping using the gnunet-vpn command-line tool. Here, you
-specfiy the desired address family of the result (i.e. "-4"), and the
+specify the desired address family of the result (i.e. "-4"), and the
 intended target IP on the Internet ("-i 131.159.74.67") and
 "gnunet-vpn" will tell you which IP address in the range of your
 VPN tunnel was mapped.
@@ -2047,3 +2168,5 @@ service offered by that peer, you can create an IP tunnel to
 that peer by specifying the peer's identity, service name and
 protocol (--tcp or --udp) and you will again receive an IP address
 that will terminate at the respective peer's service.
+
+