From 7f07f09d52aed7c449a330d8a82c1280776e49e0 Mon Sep 17 00:00:00 2001
From: ng0 <ng0@infotropique.org>
Date: Sat, 21 Oct 2017 16:37:12 +0000
Subject: move docmentation to separate folder

---
 doc/documentation/gnunet-c-tutorial.texi | 1519 ++++++++++++++++++++++++++++++
 1 file changed, 1519 insertions(+)
 create mode 100644 doc/documentation/gnunet-c-tutorial.texi

(limited to 'doc/documentation/gnunet-c-tutorial.texi')

diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi
new file mode 100644
index 0000000000..69a4c6478e
--- /dev/null
+++ b/doc/documentation/gnunet-c-tutorial.texi
@@ -0,0 +1,1519 @@
+\input texinfo
+@c %**start of header
+@setfilename gnunet-c-tutorial.info
+@documentencoding UTF-8
+@settitle GNUnet C Tutorial
+@exampleindent 2
+@c %**end of header
+
+@c including 'version.texi' makes makeinfo throw errors.
+@include version2.texi
+
+@copying
+Copyright @copyright{} 2001-2017 GNUnet e.V.
+
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.3 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, no Front-Cover Texts, and no Back-Cover Texts.  A
+copy of the license is included in the section entitled ``GNU Free
+Documentation License''.
+
+A copy of the license is also available from the Free Software
+Foundation Web site at @url{http://www.gnu.org/licenses/fdl.html}.
+
+Alternately, this document is also available under the General
+Public License, version 3 or later, as published by the Free Software
+Foundation.  A copy of the license is included in the section entitled
+``GNU General Public License''.
+
+A copy of the license is also available from the Free Software
+Foundation Web site at @url{http://www.gnu.org/licenses/gpl.html}.
+@end copying
+
+@dircategory Tutorial
+@direntry
+* GNUnet-C-Tutorial: (gnunet-c-tutorial).       C Tutorial for GNunet
+@end direntry
+
+
+@titlepage
+@title GNUnet C Tutorial
+@subtitle A Tutorial for GNUnet @value{VERSION} (C version)
+@author The GNUnet Developers
+
+@page
+@vskip 0pt plus 1filll
+
+@insertcopying
+@end titlepage
+
+@contents
+
+@c **** TODO
+@c 1. Update content?
+@c 2. Either reference main documentation or
+@c 3. Merge this into main documentation
+
+@node Top
+@top Introduction
+
+This tutorials explains how to install GNUnet on a
+GNU/Linux system and gives an introduction on how
+GNUnet can be used to develop a Peer-to-Peer application.
+Detailed installation instructions for
+various operating systems and a detailed list of all
+dependencies can be found on our website at
+@uref{https://gnunet.org/installation} and in our
+Reference Documentation (GNUnet Handbook).
+
+Please read this tutorial carefully since every single step is
+important and do not hesitate to contact the GNUnet team if you have
+any questions or problems! Check here how to contact the GNUnet
+team: @uref{https://gnunet.org/contact_information}
+
+@menu
+
+* Installing GNUnet::                   Installing GNUnet
+* Introduction to GNUnet Architecture:: Introduction to GNUnet Architecture
+* First Steps with GNUnet::             First Steps with GNUnet
+* Developing Applications::             Developing Applications
+
+@detailmenu
+ --- The Detailed Node Listing ---
+
+Installing GNUnet
+
+* Obtaining a stable version::
+* Installing Build Tool Chain and Dependencies::
+* Obtaining the latest version from Git::
+* Compiling and Installing GNUnet::
+* Common Issues - Check your GNUnet installation::
+
+Introduction to GNUnet Architecture
+
+First Steps with GNUnet
+
+* Configure your peer::
+* Start a peer::
+* Monitor a peer::
+* Starting Two Peers by Hand::
+* Starting Peers Using the Testbed Service::
+
+Developing Applications
+
+* gnunet-ext::
+* Adapting the Template::
+* Writing a Client Application::
+* Writing a Service::
+* Interacting directly with other Peers using the CORE Service::
+* Storing peer-specific data using the PEERSTORE service::
+* Using the DHT::
+* Debugging with gnunet-arm::
+
+@end detailmenu
+@end menu
+
+@node Installing GNUnet
+@chapter Installing GNUnet
+
+First of all you have to install a current version of GNUnet.
+You can download a tarball of a stable version from GNU FTP mirrors
+or obtain the latest development version from our Git repository.
+
+Most of the time you should prefer to download the stable version
+since with the latest development version things can be broken,
+functionality can be changed or tests can fail. You should only use
+the development version if you know that you require a certain
+feature or a certain issue has been fixed since the last release.
+
+@menu
+* Obtaining a stable version::
+* Installing Build Tool Chain and Dependencies::
+* Obtaining the latest version from Git::
+* Compiling and Installing GNUnet::
+* Common Issues - Check your GNUnet installation::
+@end menu
+
+@node Obtaining a stable version
+@section Obtaining a stable version
+
+Download the tarball from
+@indicateurl{https://ftp.gnu.org/gnu/gnunet/gnunet-@value{VERSION}.tar.gz}.
+
+Make sure to download the associated @file{.sig} file and to verify the
+authenticity of the tarball against it, like this:
+
+@example
+$ wget https://ftp.gnu.org/gnu/gnunet/gnunet-@value{VERSION}.tar.gz.sig
+$ gpg --verify-files gnunet-@value{VERSION}.tar.gz.sig
+@end example
+
+@noindent
+If this command fails because you do not have the required public key,
+then you need to run this command to import it:
+
+@example
+$ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E
+@end example
+
+@noindent
+and rerun the @code{gpg --verify-files} command.
+
+Now you can extract the tarball and rename the resulting
+directory to @i{gnunet} which we will be using in the
+remainder of this document.
+
+@example
+$ tar xvzf gnunet-@value{VERSION}.tar.gz
+$ mv gnunet-@value{VERSION} gnunet
+$ cd gnunet
+@end example
+
+@noindent
+However, please note that stable versions can be very outdated.
+As a developer you are @b{strongly} encouraged to use the version
+from @uref{https://gnunet.org/git/, git}.
+
+@node  Installing Build Tool Chain and Dependencies
+@section Installing Build Tool Chain and Dependencies
+
+To successfully compile GNUnet you need the tools to build GNUnet and
+the required dependencies. Please have a look at
+@uref{https://gnunet.org/dependencies} for a list of required dependencies
+and @uref{https://gnunet.org/generic_installation} for specific
+instructions for your operating system. Please check the notes at
+the end of the configure process about required dependencies.
+
+For GNUnet bootstrapping support and the http(s) plugin you should
+install @uref{https://gnunet.org/gnurl, libgnurl}.
+For the filesharing service you should install at least one of the
+datastore backends. MySQL, SQlite and PostgreSQL are supported.
+
+@node Obtaining the latest version from Git
+@section Obtaining the latest version from Git
+
+The latest development version can obtained from our Git repository.
+To obtain the code you need Git installed and checkout the repository
+using:
+
+@example
+$ git clone https://gnunet.org/git/gnunet
+@end example
+
+@noindent
+After cloning the repository you have to execute the @file{bootstrap}
+script in the directory:
+
+@example
+$ cd gnunet ; ./bootstrap
+@end example
+
+@noindent
+The remainder of this tutorial assumes that you have the Git branch
+``master'' checked out.
+
+@node Compiling and Installing GNUnet
+@section Compiling and Installing GNUnet
+
+First, you need to install at least libgnupgerror 1.27 and
+libgcrypt 1.7.6.
+
+@example
+$ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt"
+$ wget $GNUPGFTP/libgpg-error/libgpg-error-1.27.tar.bz2
+$ tar xf libgpg-error-1.27.tar.bz2
+$ cd libgpg-error-1.27
+$ ./configure
+$ sudo make install
+$ cd ..
+@end example
+
+@example
+$ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt"
+$ wget $GNUPGFTP/libgcrypt/libgcrypt-1.7.6.tar.bz2
+$ tar xf libgcrypt-1.7.6.tar.bz2
+$ cd libgcrypt-1.7.6
+$ ./configure
+$ sudo make install
+$ cd ..
+@end example
+
+@menu
+* Installation::
+@end menu
+
+@node Installation
+@subsection Installation
+Assuming all dependencies are installed, the following commands will
+compile and install GNUnet in your home directory. You can specify the
+directory where GNUnet will be installed by changing the
+@code{--prefix} value when calling @command{./configure}.  If
+you do not specifiy a prefix, GNUnet is installed in the directory
+@file{/usr/local}. When developing new applications you may want
+to enable verbose logging by adding @code{--enable-logging=verbose}:
+
+@example
+$ ./configure --prefix=$PREFIX --enable-logging
+$ make
+$ make install
+@end example
+
+@noindent
+After installing GNUnet you have to add your GNUnet installation
+to your path environmental variable. In addition you have to
+create the @file{.config} directory in your home directory
+(unless it already exists) where GNUnet stores its data and an
+empty GNUnet configuration file:
+
+@example
+$ export PATH=$PATH:$PREFIX/bin
+$ echo export PATH=$PREFIX/bin:\\$PATH >> ~/.bashrc
+$ mkdir ~/.config/
+$ touch ~/.config/gnunet.conf
+@end example
+
+@node Common Issues - Check your GNUnet installation
+@section Common Issues - Check your GNUnet installation
+
+You should check your installation to ensure that installing GNUnet
+was successful up to this point. You should be able to access GNUnet's
+binaries and run GNUnet's self check.
+
+@example
+$ which gnunet-arm
+@end example
+
+@noindent
+should return $PREFIX/bin/gnunet-arm. It should be located in your
+GNUnet installation and the output should not be empty.
+If you see an output like:
+
+@example
+$ which gnunet-arm
+@end example
+
+@noindent
+check your PATH variable to ensure GNUnet's @file{bin} directory is
+included.
+
+GNUnet provides tests for all of its subcomponents. Run
+
+@example
+$ make check
+@end example
+
+@noindent
+to execute tests for all components. @command{make check} traverses all
+subdirectories in @file{src}. For every subdirectory you should
+get a message like this:
+
+@example
+make[2]: Entering directory `/home/$USER/gnunet/contrib'
+PASS: test_gnunet_prefix
+=============
+1 test passed
+=============
+@end example
+
+@node Introduction to GNUnet Architecture
+@chapter Introduction to GNUnet Architecture
+
+GNUnet is organized in layers and services. Each service is composed of a
+main service implementation and a client library for other programs to use
+the service's functionality, described by an API.
+@c This approach is shown in
+@c FIXME: enable this once the commented block below works:
+@c figure~\ref fig:service.
+Some services provide an additional command line tool to enable the user
+to interact with the service.
+
+Very often it is other GNUnet services that will use these APIs to build
+the higher layers of GNUnet on top of the lower ones. Each layer expands
+or extends the functionality of the service below (for instance, to build
+a mesh on top of a DHT).
+@c FXIME: See comment above.
+@c See figure ~\ref fig:interaction for an illustration of this approach.
+
+@c ** @image filename[, width[, height[, alttext[, extension]]]]
+@c FIXME: Texlive (?) 20112 makes the assumption that this means
+@c 'images/OBJECTNAME.txt' but later versions of it (2017) use this
+@c syntax as described below.
+@c TODO: Checkout the makedoc script Guile uses.
+
+@image{images/gnunet-tutorial-service,,5in,Service with API and network protocol,.png}
+
+@image{images/gnunet-tutorial-system,,5in,The layered system architecture of GNUnet,.png}
+
+@c \begin{figure}[!h]
+@c   \begin{center}
+@c %  \begin{subfigure}
+@c         \begin{subfigure}[b]{0.3\textwidth}
+@c                 \centering
+@c                 \includegraphics[width=\textwidth]{figs/Service.pdf}
+@c                 \caption{Service with API and network protocol}
+@c                 \label{fig:service}
+@c         \end{subfigure}
+@c         ~~~~~~~~~~
+@c         \begin{subfigure}[b]{0.3\textwidth}
+@c                 \centering
+@c                 \includegraphics[width=\textwidth]{figs/System.pdf}
+@c                 \caption{Service interaction}
+@c                 \label{fig:interaction}
+@c         \end{subfigure}
+@c   \end{center}
+@c   \caption{GNUnet's layered system architecture}
+@c \end{figure}
+
+The main service implementation runs as a standalone process in the
+operating system and the client code runs as part of the client program,
+so crashes of a client do not affect the service process or other clients.
+The service and the clients communicate via a message protocol to be
+defined and implemented by the programmer.
+
+@node First Steps with GNUnet
+@chapter First Steps with GNUnet
+
+@menu
+* Configure your peer::
+* Start a peer::
+* Monitor a peer::
+* Starting Two Peers by Hand::
+* Starting Peers Using the Testbed Service::
+@end menu
+
+@node Configure your peer
+@section Configure your peer
+
+First of all we need to configure your peer. Each peer is started with
+a configuration containing settings for GNUnet itself and its services.
+This configuration is based on the default configuration shipped with
+GNUnet and can be modified. The default configuration is located in the
+@file{$PREFIX/share/gnunet/config.d} directory. When starting a peer, you
+can specify a customized configuration using the the @command{-c} command
+line switch when starting the ARM service and all other services. When
+using a modified configuration the default values are loaded and only
+values specified in the configuration file will replace the default
+values.
+
+Since we want to start additional peers later, we need some modifications
+from the default configuration. We need to create a separate service
+home and a file containing our modifications for this peer:
+
+@example
+$ mkdir ~/gnunet1/
+$ touch peer1.conf
+@end example
+
+@noindent
+Now add the following lines to @file{peer1.conf} to use this directory.
+For simplified usage we want to prevent the peer to connect to the GNUnet
+network since this could lead to confusing output. This modifications
+will replace the default settings:
+
+@example
+[PATHS]
+# Use this directory to store GNUnet data
+GNUNET_HOME = ~/gnunet1/
+[hostlist]
+# prevent bootstrapping
+SERVERS =
+@end example
+
+@node Start a peer
+@section Start a peer
+Each GNUnet instance (called peer) has an identity (peer ID) based on a
+cryptographic public private key pair. The peer ID is the printable hash
+of the public key.
+
+GNUnet services are controlled by a master service, the so called
+@dfn{Automatic Restart Manager} (ARM). ARM starts, stops and even
+restarts services automatically or on demand when a client connects.
+You interact with the ARM service using the @command{gnunet-arm} tool.
+GNUnet can then be started with @command{gnunet-arm -s} and stopped with
+@command{gnunet-arm -e}.  An additional service not automatically started
+can be started using @command{gnunet-arm -i <service name>} and stopped
+using @command{gnunet-arm -k <servicename>}.
+
+Once you have started your peer, you can use many other GNUnet commands
+to interact with it.  For example, you can run:
+
+@example
+$ gnunet-peerinfo -s
+@end example
+
+@noindent
+to obtain the public key of your peer.
+
+You should see an output containing the peer ID similar to:
+
+@example
+I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
+@end example
+
+@node Monitor a peer
+@section Monitor a peer
+
+In this section, we will monitor the behaviour of our peer's DHT
+service with respect to a specific key. First we will start
+GNUnet and then start the DHT service and use the DHT monitor tool
+to monitor the PUT and GET commands we issue ussing the
+@command{gnunet-dht-put} and @command{gnunet-dht-get} commands.
+Using the ``monitor'' line given below, you can observe the behavior
+of your own peer's DHT with respect to the specified KEY:
+
+@example
+# start gnunet with all default services:
+$ gnunet-arm -c ~/peer1.conf -s
+# start DHT service:
+$ gnunet-arm -c ~/peer1.conf -i dht
+$ cd ~/gnunet/src/dht;
+$ ./gnunet-dht-monitor -c ~/peer1.conf -k KEY
+@end example
+
+@noindent
+Now open a separate terminal and change again to
+the @file{gnunet/src/dht} directory:
+
+@example
+$ cd ~/gnunet/src/dht
+# put VALUE under KEY in the DHT:
+$ ./gnunet-dht-put -c ~/peer1.conf -k KEY -d VALUE
+# get key KEY from the DHT:
+$ ./gnunet/src/dht/gnunet-dht-get -c ~/peer1.conf -k KEY
+# print statistics about current GNUnet state:
+$ gnunet-statistics -c ~/peer1.conf
+# print statistics about DHT service:
+$ gnunet-statistics -c ~/peer1.conf -s dht
+@end example
+
+@node Starting Two Peers by Hand
+@section Starting Two Peers by Hand
+
+This section describes how to start two peers on the same machine by hand.
+The process is rather painful, but the description is somewhat
+instructive. In practice, you might prefer the automated method
+(@pxref{Starting Peers Using the Testbed Service}).
+
+@menu
+* Setup a second peer::
+* Start the second peer and connect the peers::
+* How to connect manually::
+@end menu
+
+@node Setup a second peer
+@subsection Setup a second peer
+We will now start a second peer on your machine.
+For the second peer, you will need to manually create a modified
+configuration file to avoid conflicts with ports and directories.
+A peers configuration file is by default located
+in @file{~/.gnunet/gnunet.conf}. This file is typically very short
+or even empty as only the differences to the defaults need to be
+specified.  The defaults are located in many files in the
+@file{$PREFIX/share/gnunet/config.d} directory.
+
+To configure the second peer, use the files
+@file{$PREFIX/share/gnunet/config.d} as a template for your main
+configuration file:
+
+@example
+$ cat $PREFIX/share/gnunet/config.d/*.conf > peer2.conf
+@end example
+
+@noindent
+Now you have to edit @file{peer2.conf} and change:
+
+@itemize
+@item @code{GNUNET\_TEST\_HOME} under @code{PATHS}
+@item Every (uncommented) value for ``@code{PORT}'' (add 10000) in any
+section (the option may be commented out if @code{PORT} is
+prefixed by "\#", in this case, UNIX domain sockets are used
+and the PORT option does not need to be touched)
+@item Every value for ``@code{UNIXPATH}'' in any section
+(e.g. by adding a "-p2" suffix)
+@end itemize
+
+to a fresh, unique value.  Make sure that the PORT numbers stay
+below 65536. From now on, whenever you interact with the second peer,
+you need to specify @command{-c peer2.conf} as an additional
+command line argument.
+
+Now, generate the 2nd peer's private key:
+
+@example
+$ gnunet-peerinfo -s -c peer2.conf
+@end example
+
+@noindent
+This may take a while, generate entropy using your keyboard or mouse
+as needed.  Also, make sure the output is different from the
+gnunet-peerinfo output for the first peer (otherwise you made an
+error in the configuration).
+
+@node Start the second peer and connect the peers
+@subsection Start the second peer and connect the peers
+
+Then, you can start a second peer using:
+
+@example
+$ gnunet-arm -c peer2.conf -s
+$ gnunet-arm -c peer2.conf -i dht
+$ ~/gnunet/src/dht/gnunet-dht-put -c peer2.conf -k KEY -d VALUE
+$ ~/gnunet/src/dht/gnunet-dht-get -c peer2.conf -k KEY
+@end example
+
+If you want the two peers to connect, you have multiple options:
+
+@itemize
+@item UDP neighbour discovery (automatic)
+@item Setup a bootstrap server
+@item Connect manually
+@end itemize
+
+To setup peer 1 as bootstrapping server change the configuration of
+the first one to be a hostlist server by adding the following lines to
+@file{peer1.conf} to enable bootstrapping server:
+
+@example
+[hostlist]
+OPTIONS = -p
+@end example
+
+@noindent
+Then change @file{peer2.conf} and replace the ``@code{SERVERS}''
+line in the ``@code{[hostlist]}'' section with
+``@code{http://localhost:8080/}''.  Restart both peers using:
+
+@example
+# stop first peer
+$ gnunet-arm -c peer1.conf -e
+# start first peer
+$ gnunet-arm -c peer1.conf -s
+# start second peer
+$ gnunet-arm -c peer2.conf -s
+@end example
+
+@noindent
+Note that if you start your peers without changing these settings, they
+will use the ``global'' hostlist servers of the GNUnet P2P network and
+likely connect to those peers.  At that point, debugging might become
+tricky as you're going to be connected to many more peers and would
+likely observe traffic and behaviors that are not explicitly controlled
+by you.
+
+@node How to connect manually
+@subsection How to connect manually
+
+If you want to use the @code{peerinfo} tool to connect your
+peers, you should:
+
+@itemize
+@item Set @code{FORCESTART = NO} in section @code{hostlist}
+(to not connect to the global GNUnet)
+@item Start both peers running @command{gnunet-arm -c peer1.conf -s}
+and @command{gnunet-arm -c peer2.conf -s}
+@item Get @code{HELLO} message of the first peer running
+@command{gnunet-peerinfo -c peer1.conf -g}
+@item Give the output to the second peer by running
+@command{gnunet-peerinfo -c peer2.conf -p '<output>'}
+@end itemize
+
+Check that they are connected using @command{gnunet-core -c peer1.conf},
+which should give you the other peer's peer identity:
+
+@example
+$ gnunet-core -c peer1.conf
+Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG'
+@end example
+
+@node Starting Peers Using the Testbed Service
+@section Starting Peers Using the Testbed Service
+@c \label{sec:testbed}
+
+GNUnet's testbed service is used for testing scenarios where
+a number of peers are to be started.  The testbed can manage peers
+on a single host or on multiple hosts in a distributed fashion.
+On a single affordable computer, it should be possible to run
+around tens of peers without drastically increasing the load on the
+system.
+
+The testbed service can be access through its API
+@file{include/gnunet\_testbed\_service.h}.  The API provides many
+routines for managing a group of peers.  It also provides a helper
+function @code{GNUNET\_TESTBED\_test\_run()} to quickly setup a
+minimalistic testing environment on a single host.
+
+This function takes a configuration file which will be used as a
+template configuration for the peers.  The testbed takes care of
+modifying relevant options in the peers' configuration such as
+@code{SERVICEHOME}, @code{PORT}, @code{UNIXPATH} to unique values
+so that peers run without running into conflicts.  It also checks
+and assigns the ports in configurations only if they are free.
+
+Additionally, the testbed service also reads its options from the
+same configuration file.  Various available options and details
+about them can be found in the testbed default configuration file
+@file{src/testbed/testbed.conf}.
+
+With the testbed API, a sample test case can be structured as follows:
+
+@example
+@verbatiminclude testbed_test.c
+@end example
+
+@noindent
+The source code for the above listing can be found at
+@uref{https://gnunet.org/git/gnunet.git/tree/doc/testbed_test.c}
+or in the @file{doc/} folder of your repository check-out.
+After installing GNUnet, the above source code can be compiled as:
+
+@example
+$ export CPPFLAGS="-I/path/to/gnunet/headers"
+$ export LDFLAGS="-L/path/to/gnunet/libraries"
+$ gcc $CPPFLAGS $LDFLAGS -o testbed-test testbed_test.c \
+ -lgnunettestbed -lgnunetdht -lgnunetutil
+# Generate (empty) configuration
+$ touch template.conf
+# run it (press CTRL-C to stop)
+$ ./testbed-test
+@end example
+
+@noindent
+The @code{CPPFLAGS} and @code{LDFLAGS} are necessary if GNUnet
+is installed into a different directory other than @file{/usr/local}.
+
+All of testbed API's peer management functions treat management
+actions as operations and return operation handles.  It is expected
+that the operations begin immediately, but they may get delayed (to
+balance out load on the system). The program using the API then has
+to take care of marking the operation as ``done'' so that its
+associated resources can be freed immediately and other waiting
+operations can be executed.  Operations will be canceled if they are
+marked as ``done'' before their completion.
+
+An operation is treated as completed when it succeeds or fails.
+Completion of an operation is either conveyed as events through
+@i{controller event callback} or through respective operation
+completion callbacks.  In functions which support completion
+notification through both controller event callback and operation
+completion callback, first the controller event callback will be
+called.  If the operation is not marked as done in that callback
+or if the callback is given as NULL when creating the operation,
+the operation completion callback will be called.  The API
+documentation shows which event are to be expected in the
+controller event notifications.  It also documents any exceptional
+behaviour.
+
+Once the peers are started, test cases often need to connect
+some of the peers' services.  Normally, opening a connect to
+a peer's service requires the peer's configuration.  While using
+testbed, the testbed automatically generates per-peer configuration.
+Accessing those configurations directly through file system is
+discouraged as their locations are dynamically created and will be
+different among various runs of testbed.  To make access to these
+configurations easy, testbed API provides the function
+@code{GNUNET\_TESTBED\_service\_connect()}.  This function fetches
+the configuration of a given peer and calls the @i{Connect Adapter}.
+In the example code, it is the @code{dht\_ca}.  A connect adapter is
+expected to open the connection to the needed service by using the
+provided configuration and return the created service connection handle.
+Successful connection to the needed service is signaled through
+@code{service\_connect\_comp\_cb}.
+
+A dual to connect adapter is the @i{Disconnect Adapter}.  This callback
+is called after the connect adapter has been called when the operation
+from @code{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''.
+It has to disconnect from the service with the provided service
+handle (@code{op\_result}).
+
+Exercise: Find out how many peers you can run on your system.
+
+Exercise: Find out how to create a 2D torus topology by changing the
+options in the configuration file.
+See @uref{https://gnunet.org/supported-topologies}, then use the
+DHT API to store and retrieve values in the network.
+
+@node Developing Applications
+@chapter Developing Applications
+
+@menu
+* gnunet-ext::
+* Adapting the Template::
+* Writing a Client Application::
+* Writing a Service::
+* Interacting directly with other Peers using the CORE Service::
+* Storing peer-specific data using the PEERSTORE service::
+* Using the DHT::
+* Debugging with gnunet-arm::
+@end menu
+
+@node gnunet-ext
+@section gnunet-ext
+To develop a new peer-to-peer application or to extend GNUnet we provide
+a template build system for writing GNUnet extensions in C. It can be
+obtained as follows:
+
+@example
+$ git clone https://gnunet.org/git/gnunet-ext
+$ cd gnunet-ext/
+$ ./bootstrap
+$ ./configure --prefix=$PREFIX --with-gnunet=$PREFIX
+$ make
+$ make install
+$ make check
+@end example
+
+@noindent
+The GNUnet ext template includes examples and a working buildsystem
+for a new GNUnet service. A common GNUnet service consists of the
+following parts which will be discussed in detail in the remainder
+of this document. The functionality of a GNUnet service is implemented in:
+
+@itemize
+@item the GNUnet service (gnunet-ext/src/ext/gnunet-service-ext.c)
+@item the client API (gnunet-ext/src/ext/ext_api.c)
+@item the client application using the service API
+(gnunet-ext/src/ext/gnunet-ext.c)
+@end itemize
+
+The interfaces for these entities are defined in:
+
+@itemize
+@item client API interface (gnunet-ext/src/ext/ext.h)
+@item the service interface (gnunet-ext/src/include/gnunet_service_SERVICE.h)
+@item the P2P protocol (gnunet-ext/src/include/gnunet_protocols_ext.h)
+@end itemize
+
+
+In addition the ext systems provides:
+
+@itemize
+@item a test testing the API (gnunet-ext/src/ext/test_ext_api.c)
+@item a configuration template for the service
+(gnunet-ext/src/ext/ext.conf.in)
+@end itemize
+
+@node Adapting the Template
+@section Adapting the Template
+
+The first step for writing any extension with a new service is to
+ensure that the @file{ext.conf.in} file contains entries for the
+@code{UNIXPATH}, @code{PORT} and @code{BINARY} for the service in a
+section named after the service.
+
+If you want to adapt the template rename the @file{ext.conf.in} to
+match your services name, you have to modify the @code{AC\_OUTPUT}
+section in @file{configure.ac} in the @file{gnunet-ext} root.
+
+@node Writing a Client Application
+@section Writing a Client Application
+
+When writing any client application (for example, a command-line
+tool), the basic structure is to start with the
+@code{GNUNET\_PROGRAM\_run} function.  This function will parse
+command-line options, setup the scheduler and then invoke the
+@code{run} function (with the remaining non-option arguments)
+and a handle to the parsed configuration (and the configuration
+file name that was used, which is typically not needed):
+
+@example
+@verbatiminclude tutorial-examples/001.c
+@end example
+
+@menu
+* Handling command-line options::
+* Writing a Client Library::
+* Writing a user interface::
+@end menu
+
+@node Handling command-line options
+@subsection Handling command-line options
+
+Options can then be added easily by adding global variables and
+expanding the @code{options} array.  For example, the following would
+add a string-option and a binary flag (defaulting to @code{NULL} and
+@code{GNUNET\_NO} respectively):
+
+@example
+@verbatiminclude tutorial-examples/002.c
+@end example
+
+Issues such as displaying some helpful text describing options using
+the @code{--help} argument and error handling are taken care of when
+using this approach.  Other @code{GNUNET\_GETOPT\_}-functions can be used
+to obtain integer value options, increment counters, etc.  You can
+even write custom option parsers for special circumstances not covered
+by the available handlers. To check if an argument was specified by the
+user you initialize the variable with a specific value (e.g. NULL for
+a string and GNUNET\_SYSERR for a integer) and check after parsing
+happened if the values were modified.
+
+Inside the @code{run} method, the program would perform the
+application-specific logic, which typically involves initializing and
+using some client library to interact with the service.  The client
+library is supposed to implement the IPC whereas the service provides
+more persistent P2P functions.
+
+Exercise: Add a few command-line options and print them inside
+of @code{run}.  What happens if the user gives invalid arguments?
+
+@node Writing a Client Library
+@subsection Writing a Client Library
+
+The first and most important step in writing a client library is to
+decide on an API for the library.  Typical API calls include
+connecting to the service, performing application-specific requests
+and cleaning up.  Many examples for such service APIs can be found
+in the @file{gnunet/src/include/gnunet\_*\_service.h} files.
+
+Then, a client-service protocol needs to be designed.  This typically
+involves defining various message formats in a header that will be
+included by both the service and the client library (but is otherwise
+not shared and hence located within the service's directory and not
+installed by @command{make install}).  Each message must start with a
+@code{struct GNUNET\_MessageHeader} and must be shorter than 64k.  By
+convention, all fields in IPC (and P2P) messages must be in big-endian
+format (and thus should be read using @code{ntohl} and similar
+functions and written using @code{htonl} and similar functions).
+Unique message types must be defined for each message struct in the
+@file{gnunet\_protocols.h} header (or an extension-specific include
+file).
+
+@menu
+* Connecting to the Service::
+* Sending messages::
+* Receiving Replies from the Service::
+@end menu
+
+@node Connecting to the Service
+@subsubsection Connecting to the Service
+
+Before a client library can implement the application-specific protocol
+with the service, a connection must be created:
+
+@example
+@verbatiminclude tutorial-examples/003.c
+@end example
+
+@noindent
+As a result a @code{GNUNET\_MQ\_Handle} is returned
+which can to used henceforth to transmit messages to the service.
+The complete MQ API can be found in @file{gnunet\_mq\_lib.h}.
+The @code{hanlders} array in the example above is incomplete.
+Here is where you will define which messages you expect to
+receive from the service, and which functions handle them.
+The @code{error\_cb} is a function that is to be called whenever
+there are errors communicating with the service.
+
+@node Sending messages
+@subsubsection Sending messages
+
+In GNUnet, messages are always sent beginning with a
+@code{struct GNUNET\_MessageHeader} in big endian format.
+This header defines the size and the type of the
+message, the payload follows after this header.
+
+@example
+@verbatiminclude tutorial-examples/004.c
+@end example
+
+@noindent
+Existing message types are defined in @file{gnunet\_protocols.h}.
+A common way to create a message is with an envelope:
+
+@example
+@verbatiminclude tutorial-examples/005.c
+@end example
+
+@noindent
+Exercise: Define a message struct that includes a 32-bit
+unsigned integer in addition to the standard GNUnet MessageHeader.
+Add a C struct and define a fresh protocol number for your message.
+Protocol numbers in gnunet-ext are defined
+in @file{gnunet-ext/src/include/gnunet_protocols_ext.h}
+
+Exercise: Find out how you can determine the number of messages
+in a message queue.
+
+Exercise: Find out how you can determine when a message you
+have queued was actually transmitted.
+
+Exercise: Define a helper function to transmit a 32-bit
+unsigned integer (as payload) to a service using some given client
+handle.
+
+@node Receiving Replies from the Service
+@subsubsection Receiving Replies from the Service
+
+Clients can receive messages from the service using the handlers
+specified in the @code{handlers} array we specified when connecting
+to the service.  Entries in the the array are usually created using
+one of two macros, depending on whether the message is fixed size
+or variable size.  Variable size messages are managed using two
+callbacks, one to check that the message is well-formed, the other
+to actually process the message.  Fixed size messages are fully
+checked by the MQ-logic, and thus only need to provide the handler
+to process the message.  Note that the prefixes @code{check\_}
+and @code{handle\_} are mandatory.
+
+@example
+@verbatiminclude tutorial-examples/006.c
+@end example
+
+@noindent
+Exercise: Expand your helper function to receive a response message
+(for example, containing just the @code{struct GNUnet MessageHeader}
+without any payload).  Upon receiving the service's response, you
+should call a callback provided to your helper function's API.
+
+Exercise: Figure out where you can pass values to the
+closures (@code{cls}).
+
+@node Writing a user interface
+@subsection Writing a user interface
+
+Given a client library, all it takes to access a service now is to
+combine calls to the client library with parsing command-line
+options.
+
+Exercise: Call your client API from your @code{run()} method in your
+client application to send a request to the service.  For example,
+send a 32-bit integer value based on a number given at the
+command-line to the service.
+
+@node Writing a Service
+@section Writing a Service
+
+Before you can test the client you've written so far, you'll
+need to also implement the corresponding service.
+
+@menu
+* Code Placement::
+* Starting a Service::
+@end menu
+
+@node Code Placement
+@subsection Code Placement
+
+New services are placed in their own subdirectory under
+@file{gnunet/src}. This subdirectory should contain the API
+implementation file @file{SERVICE\_api.c}, the description of
+the client-service protocol @file{SERVICE.h} and P2P protocol
+@file{SERVICE\_protocol.h}, the implementation of the service itself
+@file{gnunet-service-SERVICE.h} and several files for tests,
+including test code and configuration files.
+
+@node Starting a Service
+@subsection Starting a Service
+
+The key API definition for creating a service is the
+@code{GNUNET\_SERVICE\_MAIN} macro:
+
+@example
+@verbatiminclude tutorial-examples/007.c
+@end example
+
+@noindent
+In addition to the service name and flags, the macro takes three
+functions, typically called @code{run}, @code{client\_connect\_cb} and
+@code{client\_disconnect\_cb} as well as an array of message handlers
+that will be called for incoming messages from clients.
+
+A minimal version of the three central service funtions would look
+like this:
+
+@example
+@verbatiminclude tutorial-examples/008.c
+@end example
+
+@noindent
+Exercise: Write a stub service that processes no messages at all
+in your code.  Create a default configuration for it, integrate it
+with the build system and start the service from
+@command{gnunet-service-arm} using @command{gnunet-arm -i NAME}.
+
+Exercise: Figure out how to set the closure (@code{cls}) for handlers
+of a service.
+
+Exercise: Figure out how to send messages from the service back to the
+client.
+
+Each handler function in the service @b{must} eventually (possibly in some
+asynchronous continuation) call
+@code{GNUNET\_SERVICE\_client\_continue()}. Only after this call
+additional messages from the same client may
+be processed. This way, the service can throttle processing messages
+from the same client.
+
+Exercise: Change the service to ``handle'' the message from your
+client (for now, by printing a message).  What happens if you
+forget to call @code{GNUNET\_SERVICE\_client\_continue()}?
+
+@node Interacting directly with other Peers using the CORE Service
+@section Interacting directly with other Peers using the CORE Service
+
+FIXME: This section still needs to be updated to the lastest API!
+
+One of the most important services in GNUnet is the @code{CORE} service
+managing connections between peers and handling encryption between peers.
+
+One of the first things any service that extends the P2P protocol
+typically does is connect to the @code{CORE} service using:
+
+@example
+@verbatiminclude tutorial-examples/009.c
+@end example
+
+@menu
+* New P2P connections::
+* Receiving P2P Messages::
+* Sending P2P Messages::
+* End of P2P connections::
+@end menu
+
+@node New P2P connections
+@subsection New P2P connections
+
+Before any traffic with a different peer can be exchanged, the peer must
+be known to the service. This is notified by the @code{CORE}
+@code{connects} callback, which communicates the identity of the new
+peer to the service:
+
+@example
+@verbatiminclude tutorial-examples/010.c
+@end example
+
+@noindent
+Note that whatever you return from @code{connects} is given as the
+@i{cls} argument to the message handlers for messages from
+the respective peer.
+
+Exercise: Create a service that connects to the @code{CORE}.  Then
+start (and connect) two peers and print a message once your connect
+callback is invoked.
+
+@node Receiving P2P Messages
+@subsection Receiving P2P Messages
+
+To receive messages from @code{CORE}, you pass the desired
+@i{handlers} to the @code{GNUNET\_CORE\_connect()} function,
+just as we showed for services.
+
+It is your responsibility to process messages fast enough or
+to implement flow control. If an application does not process
+CORE messages fast enough, CORE will randomly drop messages
+to not keep a very long queue in memory.
+
+Exercise: Start one peer with a new service that has a message
+handler and start a second peer that only has your ``old'' service
+without message handlers.  Which ``connect'' handlers are invoked when
+the two peers are connected?  Why?
+
+@node Sending P2P Messages
+@subsection Sending P2P Messages
+
+You can transmit messages to other peers using the @i{mq} you were
+given during the @code{connect} callback.  Note that the @i{mq}
+automatically is released upon @code{disconnect} and that you must
+not use it afterwards.
+
+It is your responsibility to not over-fill the message queue, GNUnet
+will send the messages roughly in the order given as soon as possible.
+
+Exercise: Write a service that upon connect sends messages as
+fast as possible to the other peer (the other peer should run a
+service that ``processes'' those messages).  How fast is the
+transmission?  Count using the STATISTICS service on both ends.  Are
+messages lost? How can you transmit messages faster?  What happens if
+you stop the peer that is receiving your messages?
+
+@node End of P2P connections
+@subsection End of P2P connections
+
+If a message handler returns @code{GNUNET\_SYSERR}, the remote
+peer shuts down or there is an unrecoverable network
+disconnection, CORE notifies the service that the peer disconnected.
+After this notification no more messages will be received from the
+peer and the service is no longer allowed to send messages to the peer.
+The disconnect callback looks like the following:
+
+@example
+@verbatiminclude tutorial-examples/011.c
+@end example
+
+@noindent
+Exercise: Fix your service to handle peer disconnects.
+
+@node Storing peer-specific data using the PEERSTORE service
+@section Storing peer-specific data using the PEERSTORE service
+
+GNUnet's PEERSTORE service offers a persistorage for arbitrary
+peer-specific data. Other GNUnet services can use the PEERSTORE
+to store, retrieve and monitor data records. Each data record
+stored with PEERSTORE contains the following fields:
+
+@itemize
+@item subsystem: Name of the subsystem responsible for the record.
+@item peerid: Identity of the peer this record is related to.
+@item key: a key string identifying the record.
+@item value: binary record value.
+@item expiry: record expiry date.
+@end itemize
+
+The first step is to start a connection to the PEERSTORE service:
+@example
+@verbatiminclude tutorial-examples/012.c
+@end example
+
+The service handle @code{peerstore_handle} will be needed for
+all subsequent PEERSTORE operations.
+
+@menu
+* Storing records::
+* Retrieving records::
+* Monitoring records::
+* Disconnecting from PEERSTORE::
+@end menu
+
+@node Storing records
+@subsection Storing records
+
+To store a new record, use the following function:
+
+@example
+@verbatiminclude tutorial-examples/013.c
+@end example
+
+@noindent
+The @code{options} parameter can either be
+@code{GNUNET_PEERSTORE_STOREOPTION_MULTIPLE} which means that multiple
+values can be stored under the same key combination
+(subsystem, peerid, key), or @code{GNUNET_PEERSTORE_STOREOPTION_REPLACE}
+which means that PEERSTORE will replace any existing values under the
+given key combination (subsystem, peerid, key) with the new given value.
+
+The continuation function @code{cont} will be called after the store
+request is successfully sent to the PEERSTORE service. This does not
+guarantee that the record is successfully stored, only that it was
+received by the service.
+
+The @code{GNUNET_PEERSTORE_store} function returns a handle to the store
+operation. This handle can be used to cancel the store operation only
+before the continuation function is called:
+
+@example
+@verbatiminclude tutorial-examples/013.1.c
+@end example
+
+@node Retrieving records
+@subsection Retrieving records
+
+To retrieve stored records, use the following function:
+
+@example
+@verbatiminclude tutorial-examples/014.c
+@end example
+
+@noindent
+The values of @code{peer} and @code{key} can be @code{NULL}. This
+allows the iteration over values stored under any of the following
+key combinations:
+
+@itemize
+@item (subsystem)
+@item (subsystem, peerid)
+@item (subsystem, key)
+@item (subsystem, peerid, key)
+@end itemize
+
+The @code{callback} function will be called once with each retrieved
+record and once more with a @code{NULL} record to signal the end of
+results.
+
+The @code{GNUNET_PEERSTORE_iterate} function returns a handle to the
+iterate operation. This handle can be used to cancel the iterate
+operation only before the callback function is called with a
+@code{NULL} record.
+
+@node Monitoring records
+@subsection Monitoring records
+
+PEERSTORE offers the functionality of monitoring for new records
+stored under a specific key combination (subsystem, peerid, key).
+To start the monitoring, use the following function:
+
+@example
+@verbatiminclude tutorial-examples/015.c
+@end example
+
+@noindent
+Whenever a new record is stored under the given key combination,
+the @code{callback} function will be called with this new
+record. This will continue until the connection to the PEERSTORE
+service is broken or the watch operation is canceled:
+
+@example
+@verbatiminclude tutorial-examples/016.c
+@end example
+
+@node Disconnecting from PEERSTORE
+@subsection Disconnecting from PEERSTORE
+
+When the connection to the PEERSTORE service is no longer needed,
+disconnect using the following function:
+
+@example
+@verbatiminclude tutorial-examples/017.c
+@end example
+
+@noindent
+If the @code{sync_first} flag is set to @code{GNUNET_YES},
+the API will delay the disconnection until all store requests
+are received by the PEERSTORE service. Otherwise, it will
+disconnect immediately.
+
+@node Using the DHT
+@section Using the DHT
+
+The DHT allows to store data so other peers in the P2P network can
+access it and retrieve data stored by any peers in the network.
+This section will explain how to use the DHT. Of course, the first
+thing to do is to connect to the DHT service:
+
+@example
+@verbatiminclude tutorial-examples/018.c
+@end example
+
+@noindent
+The second parameter indicates how many requests in parallel to expect.
+It is not a hard limit, but a good approximation will make the DHT more
+efficient.
+
+@menu
+* Storing data in the DHT::
+* Obtaining data from the DHT::
+* Implementing a block plugin::
+* Monitoring the DHT::
+@end menu
+
+@node Storing data in the DHT
+@subsection Storing data in the DHT
+Since the DHT is a dynamic environment (peers join and leave frequently)
+the data that we put in the DHT does not stay there indefinitely. It is
+important to ``refresh'' the data periodically by simply storing it
+again, in order to make sure other peers can access it.
+
+The put API call offers a callback to signal that the PUT request has been
+sent. This does not guarantee that the data is accessible to others peers,
+or even that is has been stored, only that the service has requested to
+a neighboring peer the retransmission of the PUT request towards its final
+destination. Currently there is no feedback about whether or not the data
+has been sucessfully stored or where it has been stored. In order to
+improve the availablilty of the data and to compensate for possible
+errors, peers leaving and other unfavorable events, just make several
+PUT requests!
+
+@example
+@verbatiminclude tutorial-examples/019.c
+@end example
+
+@noindent
+Exercise: Store a value in the DHT periodically to make sure it
+is available over time. You might consider using the function
+@code{GNUNET\_SCHEDULER\_add\_delayed} and call
+@code{GNUNET\_DHT\_put} from inside a helper function.
+
+@node Obtaining data from the DHT
+@subsection Obtaining data from the DHT
+
+As we saw in the previous example, the DHT works in an asynchronous mode.
+Each request to the DHT is executed ``in the background'' and the API
+calls return immediately. In order to receive results from the DHT, the
+API provides a callback. Once started, the request runs in the service,
+the service will try to get as many results as possible (filtering out
+duplicates) until the timeout expires or we explicitly stop the request.
+It is possible to give a ``forever'' timeout with
+@code{GNUNET\_TIME\_UNIT\_FOREVER\_REL}.
+
+If we give a route option @code{GNUNET\_DHT\_RO\_RECORD\_ROUTE}
+the callback will get a list of all the peers the data has travelled,
+both on the PUT path and on the GET path.
+
+@example
+@verbatiminclude tutorial-examples/020.c
+@end example
+
+@noindent
+Exercise: Store a value in the DHT and after a while retrieve it.
+Show the IDs of all the peers the requests have gone through.
+In order to convert a peer ID to a string, use the function
+@code{GNUNET\_i2s}. Pay attention to the route option parameters
+in both calls!
+
+@node Implementing a block plugin
+@subsection Implementing a block plugin
+
+In order to store data in the DHT, it is necessary to provide a block
+plugin.  The DHT uses the block plugin to ensure that only well-formed
+requests and replies are transmitted over the network.
+
+The block plugin should be put in a file @file{plugin\_block\_SERVICE.c}
+in the service's respective directory. The
+mandatory functions that need to be implemented for a block plugin are
+described in the following sections.
+
+@menu
+* Validating requests and replies::
+* Deriving a key from a reply::
+* Initialization of the plugin::
+* Shutdown of the plugin::
+* Integration of the plugin with the build system::
+@end menu
+
+@node Validating requests and replies
+@subsubsection Validating requests and replies
+
+The evaluate function should validate a reply or a request. It returns
+a @code{GNUNET\_BLOCK\_EvaluationResult}, which is an enumeration. All
+possible answers are in @file{gnunet\_block\_lib.h}.  The function will
+be called with a @code{reply\_block} argument of @code{NULL} for
+requests.  Note that depending on how @code{evaluate} is called, only
+some of the possible return values are valid.  The specific meaning of
+the @code{xquery} argument is application-specific.  Applications that
+do not use an extended query should check that the @code{xquery\_size}
+is zero.  The block group is typically used to filter duplicate
+replies.
+
+@example
+@verbatiminclude tutorial-examples/021.c
+@end example
+
+@noindent
+Note that it is mandatory to detect duplicate replies in this function
+and return the respective status code.  Duplicate detection is
+typically done using the Bloom filter block group provided by
+@file{libgnunetblockgroup.so}.  Failure to do so may cause replies to
+circle in the network.
+
+@node Deriving a key from a reply
+@subsubsection Deriving a key from a reply
+
+The DHT can operate more efficiently if it is possible to derive a key
+from the value of the corresponding block.  The @code{get\_key}
+function is used to obtain the key of a block --- for example, by
+means of hashing.  If deriving the key is not possible, the function
+should simply return @code{GNUNET\_SYSERR} (the DHT will still work
+just fine with such blocks).
+
+@example
+@verbatiminclude tutorial-examples/022.c
+@end example
+
+@node Initialization of the plugin
+@subsubsection Initialization of the plugin
+
+The plugin is realized as a shared C library.  The library must export
+an initialization function which should initialize the plugin.  The
+initialization function specifies what block types the plugin cares
+about and returns a struct with the functions that are to be used for
+validation and obtaining keys (the ones just defined above).
+
+@example
+@verbatiminclude tutorial-examples/023.c
+@end example
+
+@node Shutdown of the plugin
+@subsubsection Shutdown of the plugin
+
+Following GNUnet's general plugin API concept, the plugin must
+export a second function for cleaning up.  It usually does very
+little.
+
+@example
+@verbatiminclude tutorial-examples/024.c
+@end example
+
+@node Integration of the plugin with the build system
+@subsubsection Integration of the plugin with the build system
+
+In order to compile the plugin, the @file{Makefile.am} file for the
+service SERVICE should contain a rule similar to this:
+@c Actually this is a Makefile not C. But the whole structure of examples
+@c must be improved.
+
+@example
+@verbatiminclude tutorial-examples/025.c
+@end example
+
+@noindent
+Exercise: Write a block plugin that accepts all queries
+and all replies but prints information about queries and replies
+when the respective validation hooks are called.
+
+@node Monitoring the DHT
+@subsection Monitoring the DHT
+
+It is possible to monitor the functioning of the local
+DHT service. When monitoring the DHT, the service will
+alert the monitoring program of any events, both started
+locally or received for routing from another peer.
+The are three different types of events possible: a
+GET request, a PUT request or a response (a reply to a GET).
+
+Since the different events have different associated data,
+the API gets 3 different callbacks (one for each message type)
+and optional type and key parameters, to allow for filtering of
+messages. When an event happens, the appropiate callback is
+called with all the information about the event.
+
+@example
+@verbatiminclude tutorial-examples/026.c
+@end example
+
+@node Debugging with gnunet-arm
+@section Debugging with gnunet-arm
+
+Even if services are managed by @command{gnunet-arm}, you can
+start them with @command{gdb} or @command{valgrind}.  For
+example, you could add the following lines to your
+configuration file to start the DHT service in a @command{gdb}
+session in a fresh @command{xterm}:
+
+@example
+[dht]
+PREFIX=xterm -e gdb --args
+@end example
+
+@noindent
+Alternatively, you can stop a service that was started via
+ARM and run it manually:
+
+@example
+$ gnunet-arm -k dht
+$ gdb --args gnunet-service-dht -L DEBUG
+$ valgrind gnunet-service-dht -L DEBUG
+@end example
+
+@noindent
+Assuming other services are well-written, they will automatically
+re-integrate the restarted service with the peer.
+
+GNUnet provides a powerful logging mechanism providing log
+levels @code{ERROR}, @code{WARNING}, @code{INFO} and @code{DEBUG}.
+The current log level is configured using the @code{$GNUNET_FORCE_LOG}
+environmental variable. The @code{DEBUG} level is only available if
+@command{--enable-logging=verbose} was used when running
+@command{configure}. More details about logging can be found under
+@uref{https://gnunet.org/logging}.
+
+You should also probably enable the creation of core files, by setting
+@code{ulimit}, and echo'ing @code{1} into
+@file{/proc/sys/kernel/core\_uses\_pid}. Then you can investigate the
+core dumps with @command{gdb}, which is often the fastest method to
+find simple errors.
+
+Exercise: Add a memory leak to your service and obtain a trace
+pointing to the leak using @command{valgrind} while running the service
+from @command{gnunet-service-arm}.
+
+@bye
-- 
cgit v1.2.3-70-g09d2


From f5920dcec9f8ce1471191a7694952449e5d22e98 Mon Sep 17 00:00:00 2001
From: ng0 <ng0@infotropique.org>
Date: Sun, 22 Oct 2017 14:59:37 +0000
Subject: adjust url to testbed_test.c in pdf

---
 doc/documentation/gnunet-c-tutorial.texi | 5 +++--
 1 file changed, 3 insertions(+), 2 deletions(-)

(limited to 'doc/documentation/gnunet-c-tutorial.texi')

diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi
index 69a4c6478e..1b216cdaa2 100644
--- a/doc/documentation/gnunet-c-tutorial.texi
+++ b/doc/documentation/gnunet-c-tutorial.texi
@@ -663,8 +663,9 @@ With the testbed API, a sample test case can be structured as follows:
 
 @noindent
 The source code for the above listing can be found at
-@uref{https://gnunet.org/git/gnunet.git/tree/doc/testbed_test.c}
-or in the @file{doc/} folder of your repository check-out.
+@uref{https://gnunet.org/git/gnunet.git/tree/doc/
+documentation/testbed_test.c}
+or in the @file{doc/documentation/} folder of your repository check-out.
 After installing GNUnet, the above source code can be compiled as:
 
 @example
-- 
cgit v1.2.3-70-g09d2


From ee87f542aaebedc406fe3924bfa5f793e5b9d2c3 Mon Sep 17 00:00:00 2001
From: ng0 <ng0@infotropique.org>
Date: Wed, 25 Oct 2017 18:01:51 +0000
Subject: gendocs

---
 contrib/packages/guix/gnunet-doc.scm     |   8 +-
 doc/documentation/Makefile.am            |   1 +
 doc/documentation/gendocs.sh             | 504 +++++++++++++++++++++++++++++++
 doc/documentation/gendocs_template       |  91 ++++++
 doc/documentation/gendocs_template_min   |  93 ++++++
 doc/documentation/gnunet-c-tutorial.texi |   6 +-
 doc/documentation/run-gendocs.sh         |   6 +
 doc/gendocs.sh                           | 504 -------------------------------
 doc/gendocs_template                     |  91 ------
 doc/gendocs_template_min                 |  93 ------
 10 files changed, 703 insertions(+), 694 deletions(-)
 create mode 100755 doc/documentation/gendocs.sh
 create mode 100644 doc/documentation/gendocs_template
 create mode 100644 doc/documentation/gendocs_template_min
 create mode 100755 doc/documentation/run-gendocs.sh
 delete mode 100644 doc/gendocs.sh
 delete mode 100644 doc/gendocs_template
 delete mode 100644 doc/gendocs_template_min

(limited to 'doc/documentation/gnunet-c-tutorial.texi')

diff --git a/contrib/packages/guix/gnunet-doc.scm b/contrib/packages/guix/gnunet-doc.scm
index b7b0156a09..b1ede6612e 100644
--- a/contrib/packages/guix/gnunet-doc.scm
+++ b/contrib/packages/guix/gnunet-doc.scm
@@ -144,9 +144,11 @@
            (replace 'build
              (lambda _
                (chdir "doc/documentation")
-               (zero? (system* "make" "pdf"))
-               (zero? (system* "make" "html"))
-               (zero? (system* "make" "info"))))
+               ;;(zero? (system* "make" "dev-build"))))
+               (zero? (system* "sh" "run-gendocs.sh"))))
+               ;; (zero? (system* "make" "pdf"))
+               ;; (zero? (system* "make" "html"))
+               ;; (zero? (system* "make" "info"))))
                ;;(zero? (system* "make" "doc-all-give-me-the-noise"))))
            (replace 'install
              (lambda _
diff --git a/doc/documentation/Makefile.am b/doc/documentation/Makefile.am
index bcdeaadb2c..5bcf3d2a3f 100644
--- a/doc/documentation/Makefile.am
+++ b/doc/documentation/Makefile.am
@@ -123,6 +123,7 @@ EXTRA_DIST =							\
 	$(gnunet_TEXINFOS)					\
 	$(gnunet_tutorial_examples)				\
 	htmlxref.cnf						\
+	run-gendocs.sh						\
 	docstyle.css
 
 
diff --git a/doc/documentation/gendocs.sh b/doc/documentation/gendocs.sh
new file mode 100755
index 0000000000..3b71b36a20
--- /dev/null
+++ b/doc/documentation/gendocs.sh
@@ -0,0 +1,504 @@
+#!/bin/sh -e
+# gendocs.sh -- generate a GNU manual in many formats.  This script is
+#   mentioned in maintain.texi.  See the help message below for usage details.
+
+scriptversion=2016-12-31.18
+
+# Copyright 2003-2017 Free Software Foundation, Inc.
+#
+# This program is free software: you can redistribute it and/or modify
+# it under the terms of the GNU General Public License as published by
+# the Free Software Foundation; either version 3 of the License, or
+# (at your option) any later version.
+#
+# This program is distributed in the hope that it will be useful,
+# but WITHOUT ANY WARRANTY; without even the implied warranty of
+# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
+# GNU General Public License for more details.
+#
+# You should have received a copy of the GNU General Public License
+# along with this program.  If not, see <http://www.gnu.org/licenses/>.
+#
+# Original author: Mohit Agarwal.
+# Send bug reports and any other correspondence to bug-gnulib@gnu.org.
+#
+# The latest version of this script, and the companion template, is
+# available from the Gnulib repository:
+#
+# http://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh
+# http://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template
+
+# TODO:
+# - image importing was only implemented for HTML generated by
+#   makeinfo.  But it should be simple enough to adjust.
+# - images are not imported in the source tarball.  All the needed
+#   formats (PDF, PNG, etc.) should be included.
+
+prog=`basename "$0"`
+srcdir=`pwd`
+
+scripturl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh"
+templateurl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/gendocs_template"
+
+: ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="}
+: ${MAKEINFO="makeinfo"}
+: ${TEXI2DVI="texi2dvi"}
+: ${DOCBOOK2HTML="docbook2html"}
+: ${DOCBOOK2PDF="docbook2pdf"}
+: ${DOCBOOK2TXT="docbook2txt"}
+: ${GENDOCS_TEMPLATE_DIR="."}
+: ${PERL='perl'}
+: ${TEXI2HTML="texi2html"}
+unset CDPATH
+unset use_texi2html
+
+MANUAL_TITLE=
+PACKAGE=
+EMAIL=webmasters@gnu.org  # please override with --email
+commonarg= # passed to all makeinfo/texi2html invcations.
+dirargs=   # passed to all tools (-I dir).
+dirs=      # -I directories.
+htmlarg="--css-ref=/software/gnulib/manual.css -c TOP_NODE_UP_URL=/manual"
+infoarg=--no-split
+generate_ascii=true
+generate_html=true
+generate_info=true
+generate_tex=true
+outdir=manual
+source_extra=
+split=node
+srcfile=
+texarg="-t @finalout"
+
+version="gendocs.sh $scriptversion
+
+Copyright 2017 Free Software Foundation, Inc.
+There is NO warranty.  You may redistribute this software
+under the terms of the GNU General Public License.
+For more information about these matters, see the files named COPYING."
+
+usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE
+
+Generate output in various formats from PACKAGE.texinfo (or .texi or
+.txi) source.  See the GNU Maintainers document for a more extensive
+discussion:
+  http://www.gnu.org/prep/maintain_toc.html
+
+Options:
+  --email ADR use ADR as contact in generated web pages; always give this.
+
+  -s SRCFILE   read Texinfo from SRCFILE, instead of PACKAGE.{texinfo|texi|txi}
+  -o OUTDIR    write files into OUTDIR, instead of manual/.
+  -I DIR       append DIR to the Texinfo search path.
+  --common ARG pass ARG in all invocations.
+  --html ARG   pass ARG to makeinfo or texi2html for HTML targets,
+                 instead of '$htmlarg'.
+  --info ARG   pass ARG to makeinfo for Info, instead of --no-split.
+  --no-ascii   skip generating the plain text output.
+  --no-html    skip generating the html output.
+  --no-info    skip generating the info output.
+  --no-tex     skip generating the dvi and pdf output.
+  --source ARG include ARG in tar archive of sources.
+  --split HOW  make split HTML by node, section, chapter; default node.
+  --tex ARG    pass ARG to texi2dvi for DVI and PDF, instead of -t @finalout.
+
+  --texi2html  use texi2html to make HTML target, with all split versions.
+  --docbook    convert through DocBook too (xml, txt, html, pdf).
+
+  --help       display this help and exit successfully.
+  --version    display version information and exit successfully.
+
+Simple example: $prog --email bug-gnu-emacs@gnu.org emacs \"GNU Emacs Manual\"
+
+Typical sequence:
+  cd PACKAGESOURCE/doc
+  wget \"$scripturl\"
+  wget \"$templateurl\"
+  $prog --email BUGLIST MANUAL \"GNU MANUAL - One-line description\"
+
+Output will be in a new subdirectory \"manual\" (by default;
+use -o OUTDIR to override).  Move all the new files into your web CVS
+tree, as explained in the Web Pages node of maintain.texi.
+
+Please use the --email ADDRESS option so your own bug-reporting
+address will be used in the generated HTML pages.
+
+MANUAL-TITLE is included as part of the HTML <title> of the overall
+manual/index.html file.  It should include the name of the package being
+documented.  manual/index.html is created by substitution from the file
+$GENDOCS_TEMPLATE_DIR/gendocs_template.  (Feel free to modify the
+generic template for your own purposes.)
+
+If you have several manuals, you'll need to run this script several
+times with different MANUAL values, specifying a different output
+directory with -o each time.  Then write (by hand) an overall index.html
+with links to them all.
+
+If a manual's Texinfo sources are spread across several directories,
+first copy or symlink all Texinfo sources into a single directory.
+(Part of the script's work is to make a tar.gz of the sources.)
+
+As implied above, by default monolithic Info files are generated.
+If you want split Info, or other Info options, use --info to override.
+
+You can set the environment variables MAKEINFO, TEXI2DVI, TEXI2HTML,
+and PERL to control the programs that get executed, and
+GENDOCS_TEMPLATE_DIR to control where the gendocs_template file is
+looked for.  With --docbook, the environment variables DOCBOOK2HTML,
+DOCBOOK2PDF, and DOCBOOK2TXT are also consulted.
+
+By default, makeinfo and texi2dvi are run in the default (English)
+locale, since that's the language of most Texinfo manuals.  If you
+happen to have a non-English manual and non-English web site, see the
+SETLANG setting in the source.
+
+Email bug reports or enhancement requests to bug-gnulib@gnu.org.
+"
+
+while test $# -gt 0; do
+  case $1 in
+    -s)          shift; srcfile=$1;;
+    -o)          shift; outdir=$1;;
+    -I)          shift; dirargs="$dirargs -I '$1'"; dirs="$dirs $1";;
+    --common)    shift; commonarg=$1;;
+    --docbook)   docbook=yes;;
+    --email)     shift; EMAIL=$1;;
+    --html)      shift; htmlarg=$1;;
+    --info)      shift; infoarg=$1;;
+    --no-ascii)  generate_ascii=false;;
+    --no-html)   generate_ascii=false;;
+    --no-info)   generate_info=false;;
+    --no-tex)    generate_tex=false;;
+    --source)    shift; source_extra=$1;;
+    --split)     shift; split=$1;;
+    --tex)       shift; texarg=$1;;
+    --texi2html) use_texi2html=1;;
+
+    --help)      echo "$usage"; exit 0;;
+    --version)   echo "$version"; exit 0;;
+    -*)
+      echo "$0: Unknown option \`$1'." >&2
+      echo "$0: Try \`--help' for more information." >&2
+      exit 1;;
+    *)
+      if test -z "$PACKAGE"; then
+        PACKAGE=$1
+      elif test -z "$MANUAL_TITLE"; then
+        MANUAL_TITLE=$1
+      else
+        echo "$0: extra non-option argument \`$1'." >&2
+        exit 1
+      fi;;
+  esac
+  shift
+done
+
+# makeinfo uses the dirargs, but texi2dvi doesn't.
+commonarg=" $dirargs $commonarg"
+
+# For most of the following, the base name is just $PACKAGE
+base=$PACKAGE
+
+if test -n "$srcfile"; then
+  # but here, we use the basename of $srcfile
+  base=`basename "$srcfile"`
+  case $base in
+    *.txi|*.texi|*.texinfo) base=`echo "$base"|sed 's/\.[texinfo]*$//'`;;
+  esac
+  PACKAGE=$base
+elif test -s "$srcdir/$PACKAGE.texinfo"; then
+  srcfile=$srcdir/$PACKAGE.texinfo
+elif test -s "$srcdir/$PACKAGE.texi"; then
+  srcfile=$srcdir/$PACKAGE.texi
+elif test -s "$srcdir/$PACKAGE.txi"; then
+  srcfile=$srcdir/$PACKAGE.txi
+else
+  echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2
+  exit 1
+fi
+
+if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then
+  echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2
+  echo "$0: it is available from $templateurl." >&2
+  exit 1
+fi
+
+# Function to return size of $1 in something resembling kilobytes.
+calcsize()
+{
+  size=`ls -ksl $1 | awk '{print $1}'`
+  echo $size
+}
+
+# copy_images OUTDIR HTML-FILE...
+# -------------------------------
+# Copy all the images needed by the HTML-FILEs into OUTDIR.
+# Look for them in . and the -I directories; this is simpler than what
+# makeinfo supports with -I, but hopefully it will suffice.
+copy_images()
+{
+  local odir
+  odir=$1
+  shift
+  $PERL -n -e "
+BEGIN {
+  \$me = '$prog';
+  \$odir = '$odir';
+  @dirs = qw(. $dirs);
+}
+" -e '
+/<img src="(.*?)"/g && ++$need{$1};
+
+END {
+  #print "$me: @{[keys %need]}\n";  # for debugging, show images found.
+  FILE: for my $f (keys %need) {
+    for my $d (@dirs) {
+      if (-f "$d/$f") {
+        use File::Basename;
+        my $dest = dirname ("$odir/$f");
+        #
+        use File::Path;
+        -d $dest || mkpath ($dest)
+          || die "$me: cannot mkdir $dest: $!\n";
+        #
+        use File::Copy;
+        copy ("$d/$f", $dest)
+          || die "$me: cannot copy $d/$f to $dest: $!\n";
+        next FILE;
+      }
+    }
+    die "$me: $ARGV: cannot find image $f\n";
+  }
+}
+' -- "$@" || exit 1
+}
+
+case $outdir in
+  /*) abs_outdir=$outdir;;
+  *)  abs_outdir=$srcdir/$outdir;;
+esac
+
+echo "Making output for $srcfile"
+echo " in `pwd`"
+mkdir -p "$outdir/"
+
+# 
+if $generate_info; then
+  cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\""
+  echo "Generating info... ($cmd)"
+  rm -f $PACKAGE.info* # get rid of any strays
+  eval "$cmd"
+  tar czf "$outdir/$PACKAGE.info.tar.gz" $PACKAGE.info*
+  ls -l "$outdir/$PACKAGE.info.tar.gz"
+  info_tgz_size=`calcsize "$outdir/$PACKAGE.info.tar.gz"`
+  # do not mv the info files, there's no point in having them available
+  # separately on the web.
+fi  # end info
+
+# 
+if $generate_tex; then
+  cmd="$SETLANG $TEXI2DVI $dirargs $texarg \"$srcfile\""
+  printf "\nGenerating dvi... ($cmd)\n"
+  eval "$cmd"
+  # compress/finish dvi:
+  gzip -f -9 $PACKAGE.dvi
+  dvi_gz_size=`calcsize $PACKAGE.dvi.gz`
+  mv $PACKAGE.dvi.gz "$outdir/"
+  ls -l "$outdir/$PACKAGE.dvi.gz"
+
+  cmd="$SETLANG $TEXI2DVI --pdf $dirargs $texarg \"$srcfile\""
+  printf "\nGenerating pdf... ($cmd)\n"
+  eval "$cmd"
+  pdf_size=`calcsize $PACKAGE.pdf`
+  mv $PACKAGE.pdf "$outdir/"
+  ls -l "$outdir/$PACKAGE.pdf"
+fi # end tex (dvi + pdf)
+
+# 
+if $generate_ascii; then
+  opt="-o $PACKAGE.txt --no-split --no-headers $commonarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
+  printf "\nGenerating ascii... ($cmd)\n"
+  eval "$cmd"
+  ascii_size=`calcsize $PACKAGE.txt`
+  gzip -f -9 -c $PACKAGE.txt >"$outdir/$PACKAGE.txt.gz"
+  ascii_gz_size=`calcsize "$outdir/$PACKAGE.txt.gz"`
+  mv $PACKAGE.txt "$outdir/"
+  ls -l "$outdir/$PACKAGE.txt" "$outdir/$PACKAGE.txt.gz"
+fi
+
+# 
+
+if $generate_html; then
+# Split HTML at level $1.  Used for texi2html.
+html_split()
+{
+  opt="--split=$1 --node-files $commonarg $htmlarg"
+  cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\""
+  printf "\nGenerating html by $1... ($cmd)\n"
+  eval "$cmd"
+  split_html_dir=$PACKAGE.html
+  (
+    cd ${split_html_dir} || exit 1
+    ln -sf ${PACKAGE}.html index.html
+    tar -czf "$abs_outdir/${PACKAGE}.html_$1.tar.gz" -- *.html
+  )
+  eval html_$1_tgz_size=`calcsize "$outdir/${PACKAGE}.html_$1.tar.gz"`
+  rm -f "$outdir"/html_$1/*.html
+  mkdir -p "$outdir/html_$1/"
+  mv ${split_html_dir}/*.html "$outdir/html_$1/"
+  rmdir ${split_html_dir}
+}
+
+if test -z "$use_texi2html"; then
+  opt="--no-split --html -o $PACKAGE.html $commonarg $htmlarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
+  printf "\nGenerating monolithic html... ($cmd)\n"
+  rm -rf $PACKAGE.html  # in case a directory is left over
+  eval "$cmd"
+  html_mono_size=`calcsize $PACKAGE.html`
+  gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz"
+  html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"`
+  copy_images "$outdir/" $PACKAGE.html
+  mv $PACKAGE.html "$outdir/"
+  ls -l "$outdir/$PACKAGE.html" "$outdir/$PACKAGE.html.gz"
+
+  # Before Texinfo 5.0, makeinfo did not accept a --split=HOW option,
+  # it just always split by node.  So if we're splitting by node anyway,
+  # leave it out.
+  if test "x$split" = xnode; then
+    split_arg=
+  else
+    split_arg=--split=$split
+  fi
+  #
+  opt="--html -o $PACKAGE.html $split_arg $commonarg $htmlarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
+  printf "\nGenerating html by $split... ($cmd)\n"
+  eval "$cmd"
+  split_html_dir=$PACKAGE.html
+  copy_images $split_html_dir/ $split_html_dir/*.html
+  (
+    cd $split_html_dir || exit 1
+    tar -czf "$abs_outdir/$PACKAGE.html_$split.tar.gz" -- *
+  )
+  eval \
+    html_${split}_tgz_size=`calcsize "$outdir/$PACKAGE.html_$split.tar.gz"`
+  rm -rf "$outdir/html_$split/"
+  mv $split_html_dir "$outdir/html_$split/"
+  du -s "$outdir/html_$split/"
+  ls -l "$outdir/$PACKAGE.html_$split.tar.gz"
+
+else # use texi2html:
+  opt="--output $PACKAGE.html $commonarg $htmlarg"
+  cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\""
+  printf "\nGenerating monolithic html with texi2html... ($cmd)\n"
+  rm -rf $PACKAGE.html  # in case a directory is left over
+  eval "$cmd"
+  html_mono_size=`calcsize $PACKAGE.html`
+  gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz"
+  html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"`
+  mv $PACKAGE.html "$outdir/"
+
+  html_split node
+  html_split chapter
+  html_split section
+fi
+fi # end html
+
+# 
+printf "\nMaking .tar.gz for sources...\n"
+d=`dirname $srcfile`
+(
+  cd "$d"
+  srcfiles=`ls -d *.texinfo *.texi *.txi *.eps $source_extra 2>/dev/null` || true
+  tar czfh "$abs_outdir/$PACKAGE.texi.tar.gz" $srcfiles
+  ls -l "$abs_outdir/$PACKAGE.texi.tar.gz"
+)
+texi_tgz_size=`calcsize "$outdir/$PACKAGE.texi.tar.gz"`
+
+# 
+# Do everything again through docbook.
+if test -n "$docbook"; then
+  opt="-o - --docbook $commonarg"
+  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml"
+  printf "\nGenerating docbook XML... ($cmd)\n"
+  eval "$cmd"
+  docbook_xml_size=`calcsize $PACKAGE-db.xml`
+  gzip -f -9 -c $PACKAGE-db.xml >"$outdir/$PACKAGE-db.xml.gz"
+  docbook_xml_gz_size=`calcsize "$outdir/$PACKAGE-db.xml.gz"`
+  mv $PACKAGE-db.xml "$outdir/"
+
+  split_html_db_dir=html_node_db
+  opt="$commonarg -o $split_html_db_dir"
+  cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\""
+  printf "\nGenerating docbook HTML... ($cmd)\n"
+  eval "$cmd"
+  (
+    cd ${split_html_db_dir} || exit 1
+    tar -czf "$abs_outdir/${PACKAGE}.html_node_db.tar.gz" -- *.html
+  )
+  html_node_db_tgz_size=`calcsize "$outdir/${PACKAGE}.html_node_db.tar.gz"`
+  rm -f "$outdir"/html_node_db/*.html
+  mkdir -p "$outdir/html_node_db"
+  mv ${split_html_db_dir}/*.html "$outdir/html_node_db/"
+  rmdir ${split_html_db_dir}
+
+  cmd="$DOCBOOK2TXT \"${outdir}/$PACKAGE-db.xml\""
+  printf "\nGenerating docbook ASCII... ($cmd)\n"
+  eval "$cmd"
+  docbook_ascii_size=`calcsize $PACKAGE-db.txt`
+  mv $PACKAGE-db.txt "$outdir/"
+
+  cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\""
+  printf "\nGenerating docbook PDF... ($cmd)\n"
+  eval "$cmd"
+  docbook_pdf_size=`calcsize $PACKAGE-db.pdf`
+  mv $PACKAGE-db.pdf "$outdir/"
+fi
+
+# 
+printf "\nMaking index.html for $PACKAGE...\n"
+if test -z "$use_texi2html"; then
+  CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
+         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
+else
+  # should take account of --split here.
+  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
+fi
+
+curdate=`$SETLANG date '+%B %d, %Y'`
+sed \
+   -e "s!%%TITLE%%!$MANUAL_TITLE!g" \
+   -e "s!%%EMAIL%%!$EMAIL!g" \
+   -e "s!%%PACKAGE%%!$PACKAGE!g" \
+   -e "s!%%DATE%%!$curdate!g" \
+   -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \
+   -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \
+   -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \
+   -e "s!%%HTML_SECTION_TGZ_SIZE%%!$html_section_tgz_size!g" \
+   -e "s!%%HTML_CHAPTER_TGZ_SIZE%%!$html_chapter_tgz_size!g" \
+   -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \
+   -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \
+   -e "s!%%PDF_SIZE%%!$pdf_size!g" \
+   -e "s!%%ASCII_SIZE%%!$ascii_size!g" \
+   -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \
+   -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \
+   -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \
+   -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \
+   -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \
+   -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \
+   -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \
+   -e "s,%%SCRIPTURL%%,$scripturl,g" \
+   -e "s!%%SCRIPTNAME%%!$prog!g" \
+   -e "$CONDS" \
+$GENDOCS_TEMPLATE_DIR/gendocs_template >"$outdir/index.html"
+
+echo "Done, see $outdir/ subdirectory for new files."
+
+# Local variables:
+# eval: (add-hook 'write-file-hooks 'time-stamp)
+# time-stamp-start: "scriptversion="
+# time-stamp-format: "%:y-%02m-%02d.%02H"
+# time-stamp-end: "$"
+# End:
diff --git a/doc/documentation/gendocs_template b/doc/documentation/gendocs_template
new file mode 100644
index 0000000000..178f6cb4c8
--- /dev/null
+++ b/doc/documentation/gendocs_template
@@ -0,0 +1,91 @@
+<!--#include virtual="/server/header.html" -->
+<!-- Parent-Version: 1.77 -->
+<title>%%TITLE%% - GNU Project - Free Software Foundation</title>
+<!--#include virtual="/server/banner.html" -->
+<h2>%%TITLE%%</h2>
+
+<address>Free Software Foundation</address>
+<address>last updated %%DATE%%</address>
+
+<p>This manual (%%PACKAGE%%) is available in the following formats:</p>
+
+<ul>
+<li><a href="%%PACKAGE%%.html">HTML
+    (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+<li><a href="html_node/index.html">HTML</a> - with one web page per
+    node.</li>
+%%IF HTML_SECTION%%
+<li><a href="html_section/index.html">HTML</a> - with one web page per
+    section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+<li><a href="html_chapter/index.html">HTML</a> - with one web page per
+    chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.html.gz">HTML compressed
+    (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
+    one web page.</li>
+<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
+    (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per node.</li>
+%%IF HTML_SECTION%%
+<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
+    (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
+    (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.info.tar.gz">Info document
+    (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li>
+<li><a href="%%PACKAGE%%.txt">ASCII text
+    (%%ASCII_SIZE%%K bytes)</a>.</li>
+<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+    (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li>
+<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+    (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li>
+<li><a href="%%PACKAGE%%.pdf">PDF file
+    (%%PDF_SIZE%%K bytes)</a>.</li>
+<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+    (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li>
+</ul>
+
+<p>You can <a href="http://shop.fsf.org/">buy printed copies of
+some manuals</a> (among other items) from the Free Software Foundation;
+this helps support FSF activities.</p>
+
+<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%%
+script</a>.)</p>
+
+<!-- If needed, change the copyright block at the bottom. In general,
+     all pages on the GNU web server should have the section about
+     verbatim copying.  Please do NOT remove this without talking
+     with the webmasters first.
+     Please make sure the copyright date is consistent with the document
+     and that it is like this: "2001, 2002", not this: "2001-2002". -->
+</div><!-- for id="content", starts in the include above -->
+<!--#include virtual="/server/footer.html" -->
+<div id="footer">
+<div class="unprintable">
+
+<p>Please send general FSF &amp; GNU inquiries to
+<a href="mailto:gnu@gnu.org">&lt;gnu@gnu.org&gt;</a>.
+There are also <a href="/contact/">other ways to contact</a>
+the FSF.  Broken links and other corrections or suggestions can be sent
+to <a href="mailto:%%EMAIL%%">&lt;%%EMAIL%%&gt;</a>.</p>
+</div>
+
+<p>Copyright &copy; 2017 Free Software Foundation, Inc.</p>
+
+<p>This page is licensed under a <a rel="license"
+href="http://creativecommons.org/licenses/by-nd/3.0/us/">Creative
+Commons Attribution-NoDerivs 3.0 United States License</a>.</p>
+
+<!--#include virtual="/server/bottom-notes.html" -->
+
+</div>
+</div>
+</body>
+</html>
diff --git a/doc/documentation/gendocs_template_min b/doc/documentation/gendocs_template_min
new file mode 100644
index 0000000000..112fa3bfb6
--- /dev/null
+++ b/doc/documentation/gendocs_template_min
@@ -0,0 +1,93 @@
+<?xml version="1.0" encoding="utf-8" ?>
+<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
+<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
+
+<head>
+<title>%%TITLE%% - GNU Project - Free Software Foundation</title>
+<meta http-equiv="content-type" content='text/html; charset=utf-8' />
+<link rel="stylesheet" type="text/css" href="/gnu.css" />
+</head>
+
+<body>
+
+<h3>%%TITLE%%</h3>
+
+<address>Free Software Foundation</address>
+<address>last updated %%DATE%%</address>
+<p>
+<a href="/graphics/gnu-head.jpg">
+	<img src="/graphics/gnu-head-sm.jpg"
+             alt=" [image of the head of a GNU] " width="129" height="122"/>
+</a>
+</p>
+<hr />
+
+<p>This manual (%%PACKAGE%%) is available in the following formats:</p>
+
+<ul>
+<li><a href="%%PACKAGE%%.html">HTML
+    (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
+<li><a href="html_node/index.html">HTML</a> - with one web page per
+    node.</li>
+%%IF HTML_SECTION%%
+<li><a href="html_section/index.html">HTML</a> - with one web page per
+    section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+<li><a href="html_chapter/index.html">HTML</a> - with one web page per
+    chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.html.gz">HTML compressed
+    (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
+    one web page.</li>
+<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
+    (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per node.</li>
+%%IF HTML_SECTION%%
+<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
+    (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per section.</li>
+%%ENDIF HTML_SECTION%%
+%%IF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
+    (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
+    with one web page per chapter.</li>
+%%ENDIF HTML_CHAPTER%%
+<li><a href="%%PACKAGE%%.info.tar.gz">Info document
+    (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li>
+<li><a href="%%PACKAGE%%.txt">ASCII text
+    (%%ASCII_SIZE%%K bytes)</a>.</li>
+<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
+    (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li>
+<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
+    (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li>
+<li><a href="%%PACKAGE%%.pdf">PDF file
+    (%%PDF_SIZE%%K bytes)</a>.</li>
+<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
+    (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li>
+</ul>
+
+<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%%
+script</a>.)</p>
+
+<div id="footer" class="copyright">
+
+<p>Please send general FSF &amp; GNU inquiries to
+<a href="mailto:gnu@gnu.org">&lt;gnu@gnu.org&gt;</a>.
+There are also <a href="/contact/">other ways to contact</a>
+the FSF.  Broken links and other corrections or suggestions can be sent
+to <a href="mailto:%%EMAIL%%">&lt;%%EMAIL%%&gt;</a>.</p>
+</div>
+
+<p>Copyright &copy; 2017 Free Software Foundation, Inc.</p>
+
+<p>This page is licensed under a <a rel="license"
+href="http://creativecommons.org/licenses/by-nd/3.0/us/">Creative
+Commons Attribution-NoDerivs 3.0 United States License</a>.</p>
+
+<!--#include virtual="/server/bottom-notes.html" -->
+
+</div>
+</body>
+</html>
diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi
index 1b216cdaa2..aca40d2ef1 100644
--- a/doc/documentation/gnunet-c-tutorial.texi
+++ b/doc/documentation/gnunet-c-tutorial.texi
@@ -341,9 +341,9 @@ a mesh on top of a DHT).
 @c syntax as described below.
 @c TODO: Checkout the makedoc script Guile uses.
 
-@image{images/gnunet-tutorial-service,,5in,Service with API and network protocol,.png}
-
-@image{images/gnunet-tutorial-system,,5in,The layered system architecture of GNUnet,.png}
+@c FIXME!!!
+@c @image{images/gnunet-tutorial-service,,5in,Service with API and network protocol,.png}
+@c @image{images/gnunet-tutorial-system,,5in,The layered system architecture of GNUnet,.png}
 
 @c \begin{figure}[!h]
 @c   \begin{center}
diff --git a/doc/documentation/run-gendocs.sh b/doc/documentation/run-gendocs.sh
new file mode 100755
index 0000000000..96b41ea7bb
--- /dev/null
+++ b/doc/documentation/run-gendocs.sh
@@ -0,0 +1,6 @@
+#!/bin/sh
+
+make version.texi
+make version2.texi
+./gendocs.sh --email gnunet-developers@gnu.org gnunet "GNUnet reference handbook"
+./gendocs.sh --email gnunet-developers@gnu.org gnunet-c-tutorial "GNUnet C Tutorial"
diff --git a/doc/gendocs.sh b/doc/gendocs.sh
deleted file mode 100644
index 3b71b36a20..0000000000
--- a/doc/gendocs.sh
+++ /dev/null
@@ -1,504 +0,0 @@
-#!/bin/sh -e
-# gendocs.sh -- generate a GNU manual in many formats.  This script is
-#   mentioned in maintain.texi.  See the help message below for usage details.
-
-scriptversion=2016-12-31.18
-
-# Copyright 2003-2017 Free Software Foundation, Inc.
-#
-# This program is free software: you can redistribute it and/or modify
-# it under the terms of the GNU General Public License as published by
-# the Free Software Foundation; either version 3 of the License, or
-# (at your option) any later version.
-#
-# This program is distributed in the hope that it will be useful,
-# but WITHOUT ANY WARRANTY; without even the implied warranty of
-# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
-# GNU General Public License for more details.
-#
-# You should have received a copy of the GNU General Public License
-# along with this program.  If not, see <http://www.gnu.org/licenses/>.
-#
-# Original author: Mohit Agarwal.
-# Send bug reports and any other correspondence to bug-gnulib@gnu.org.
-#
-# The latest version of this script, and the companion template, is
-# available from the Gnulib repository:
-#
-# http://git.savannah.gnu.org/cgit/gnulib.git/tree/build-aux/gendocs.sh
-# http://git.savannah.gnu.org/cgit/gnulib.git/tree/doc/gendocs_template
-
-# TODO:
-# - image importing was only implemented for HTML generated by
-#   makeinfo.  But it should be simple enough to adjust.
-# - images are not imported in the source tarball.  All the needed
-#   formats (PDF, PNG, etc.) should be included.
-
-prog=`basename "$0"`
-srcdir=`pwd`
-
-scripturl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/build-aux/gendocs.sh"
-templateurl="http://git.savannah.gnu.org/cgit/gnulib.git/plain/doc/gendocs_template"
-
-: ${SETLANG="env LANG= LC_MESSAGES= LC_ALL= LANGUAGE="}
-: ${MAKEINFO="makeinfo"}
-: ${TEXI2DVI="texi2dvi"}
-: ${DOCBOOK2HTML="docbook2html"}
-: ${DOCBOOK2PDF="docbook2pdf"}
-: ${DOCBOOK2TXT="docbook2txt"}
-: ${GENDOCS_TEMPLATE_DIR="."}
-: ${PERL='perl'}
-: ${TEXI2HTML="texi2html"}
-unset CDPATH
-unset use_texi2html
-
-MANUAL_TITLE=
-PACKAGE=
-EMAIL=webmasters@gnu.org  # please override with --email
-commonarg= # passed to all makeinfo/texi2html invcations.
-dirargs=   # passed to all tools (-I dir).
-dirs=      # -I directories.
-htmlarg="--css-ref=/software/gnulib/manual.css -c TOP_NODE_UP_URL=/manual"
-infoarg=--no-split
-generate_ascii=true
-generate_html=true
-generate_info=true
-generate_tex=true
-outdir=manual
-source_extra=
-split=node
-srcfile=
-texarg="-t @finalout"
-
-version="gendocs.sh $scriptversion
-
-Copyright 2017 Free Software Foundation, Inc.
-There is NO warranty.  You may redistribute this software
-under the terms of the GNU General Public License.
-For more information about these matters, see the files named COPYING."
-
-usage="Usage: $prog [OPTION]... PACKAGE MANUAL-TITLE
-
-Generate output in various formats from PACKAGE.texinfo (or .texi or
-.txi) source.  See the GNU Maintainers document for a more extensive
-discussion:
-  http://www.gnu.org/prep/maintain_toc.html
-
-Options:
-  --email ADR use ADR as contact in generated web pages; always give this.
-
-  -s SRCFILE   read Texinfo from SRCFILE, instead of PACKAGE.{texinfo|texi|txi}
-  -o OUTDIR    write files into OUTDIR, instead of manual/.
-  -I DIR       append DIR to the Texinfo search path.
-  --common ARG pass ARG in all invocations.
-  --html ARG   pass ARG to makeinfo or texi2html for HTML targets,
-                 instead of '$htmlarg'.
-  --info ARG   pass ARG to makeinfo for Info, instead of --no-split.
-  --no-ascii   skip generating the plain text output.
-  --no-html    skip generating the html output.
-  --no-info    skip generating the info output.
-  --no-tex     skip generating the dvi and pdf output.
-  --source ARG include ARG in tar archive of sources.
-  --split HOW  make split HTML by node, section, chapter; default node.
-  --tex ARG    pass ARG to texi2dvi for DVI and PDF, instead of -t @finalout.
-
-  --texi2html  use texi2html to make HTML target, with all split versions.
-  --docbook    convert through DocBook too (xml, txt, html, pdf).
-
-  --help       display this help and exit successfully.
-  --version    display version information and exit successfully.
-
-Simple example: $prog --email bug-gnu-emacs@gnu.org emacs \"GNU Emacs Manual\"
-
-Typical sequence:
-  cd PACKAGESOURCE/doc
-  wget \"$scripturl\"
-  wget \"$templateurl\"
-  $prog --email BUGLIST MANUAL \"GNU MANUAL - One-line description\"
-
-Output will be in a new subdirectory \"manual\" (by default;
-use -o OUTDIR to override).  Move all the new files into your web CVS
-tree, as explained in the Web Pages node of maintain.texi.
-
-Please use the --email ADDRESS option so your own bug-reporting
-address will be used in the generated HTML pages.
-
-MANUAL-TITLE is included as part of the HTML <title> of the overall
-manual/index.html file.  It should include the name of the package being
-documented.  manual/index.html is created by substitution from the file
-$GENDOCS_TEMPLATE_DIR/gendocs_template.  (Feel free to modify the
-generic template for your own purposes.)
-
-If you have several manuals, you'll need to run this script several
-times with different MANUAL values, specifying a different output
-directory with -o each time.  Then write (by hand) an overall index.html
-with links to them all.
-
-If a manual's Texinfo sources are spread across several directories,
-first copy or symlink all Texinfo sources into a single directory.
-(Part of the script's work is to make a tar.gz of the sources.)
-
-As implied above, by default monolithic Info files are generated.
-If you want split Info, or other Info options, use --info to override.
-
-You can set the environment variables MAKEINFO, TEXI2DVI, TEXI2HTML,
-and PERL to control the programs that get executed, and
-GENDOCS_TEMPLATE_DIR to control where the gendocs_template file is
-looked for.  With --docbook, the environment variables DOCBOOK2HTML,
-DOCBOOK2PDF, and DOCBOOK2TXT are also consulted.
-
-By default, makeinfo and texi2dvi are run in the default (English)
-locale, since that's the language of most Texinfo manuals.  If you
-happen to have a non-English manual and non-English web site, see the
-SETLANG setting in the source.
-
-Email bug reports or enhancement requests to bug-gnulib@gnu.org.
-"
-
-while test $# -gt 0; do
-  case $1 in
-    -s)          shift; srcfile=$1;;
-    -o)          shift; outdir=$1;;
-    -I)          shift; dirargs="$dirargs -I '$1'"; dirs="$dirs $1";;
-    --common)    shift; commonarg=$1;;
-    --docbook)   docbook=yes;;
-    --email)     shift; EMAIL=$1;;
-    --html)      shift; htmlarg=$1;;
-    --info)      shift; infoarg=$1;;
-    --no-ascii)  generate_ascii=false;;
-    --no-html)   generate_ascii=false;;
-    --no-info)   generate_info=false;;
-    --no-tex)    generate_tex=false;;
-    --source)    shift; source_extra=$1;;
-    --split)     shift; split=$1;;
-    --tex)       shift; texarg=$1;;
-    --texi2html) use_texi2html=1;;
-
-    --help)      echo "$usage"; exit 0;;
-    --version)   echo "$version"; exit 0;;
-    -*)
-      echo "$0: Unknown option \`$1'." >&2
-      echo "$0: Try \`--help' for more information." >&2
-      exit 1;;
-    *)
-      if test -z "$PACKAGE"; then
-        PACKAGE=$1
-      elif test -z "$MANUAL_TITLE"; then
-        MANUAL_TITLE=$1
-      else
-        echo "$0: extra non-option argument \`$1'." >&2
-        exit 1
-      fi;;
-  esac
-  shift
-done
-
-# makeinfo uses the dirargs, but texi2dvi doesn't.
-commonarg=" $dirargs $commonarg"
-
-# For most of the following, the base name is just $PACKAGE
-base=$PACKAGE
-
-if test -n "$srcfile"; then
-  # but here, we use the basename of $srcfile
-  base=`basename "$srcfile"`
-  case $base in
-    *.txi|*.texi|*.texinfo) base=`echo "$base"|sed 's/\.[texinfo]*$//'`;;
-  esac
-  PACKAGE=$base
-elif test -s "$srcdir/$PACKAGE.texinfo"; then
-  srcfile=$srcdir/$PACKAGE.texinfo
-elif test -s "$srcdir/$PACKAGE.texi"; then
-  srcfile=$srcdir/$PACKAGE.texi
-elif test -s "$srcdir/$PACKAGE.txi"; then
-  srcfile=$srcdir/$PACKAGE.txi
-else
-  echo "$0: cannot find .texinfo or .texi or .txi for $PACKAGE in $srcdir." >&2
-  exit 1
-fi
-
-if test ! -r $GENDOCS_TEMPLATE_DIR/gendocs_template; then
-  echo "$0: cannot read $GENDOCS_TEMPLATE_DIR/gendocs_template." >&2
-  echo "$0: it is available from $templateurl." >&2
-  exit 1
-fi
-
-# Function to return size of $1 in something resembling kilobytes.
-calcsize()
-{
-  size=`ls -ksl $1 | awk '{print $1}'`
-  echo $size
-}
-
-# copy_images OUTDIR HTML-FILE...
-# -------------------------------
-# Copy all the images needed by the HTML-FILEs into OUTDIR.
-# Look for them in . and the -I directories; this is simpler than what
-# makeinfo supports with -I, but hopefully it will suffice.
-copy_images()
-{
-  local odir
-  odir=$1
-  shift
-  $PERL -n -e "
-BEGIN {
-  \$me = '$prog';
-  \$odir = '$odir';
-  @dirs = qw(. $dirs);
-}
-" -e '
-/<img src="(.*?)"/g && ++$need{$1};
-
-END {
-  #print "$me: @{[keys %need]}\n";  # for debugging, show images found.
-  FILE: for my $f (keys %need) {
-    for my $d (@dirs) {
-      if (-f "$d/$f") {
-        use File::Basename;
-        my $dest = dirname ("$odir/$f");
-        #
-        use File::Path;
-        -d $dest || mkpath ($dest)
-          || die "$me: cannot mkdir $dest: $!\n";
-        #
-        use File::Copy;
-        copy ("$d/$f", $dest)
-          || die "$me: cannot copy $d/$f to $dest: $!\n";
-        next FILE;
-      }
-    }
-    die "$me: $ARGV: cannot find image $f\n";
-  }
-}
-' -- "$@" || exit 1
-}
-
-case $outdir in
-  /*) abs_outdir=$outdir;;
-  *)  abs_outdir=$srcdir/$outdir;;
-esac
-
-echo "Making output for $srcfile"
-echo " in `pwd`"
-mkdir -p "$outdir/"
-
-# 
-if $generate_info; then
-  cmd="$SETLANG $MAKEINFO -o $PACKAGE.info $commonarg $infoarg \"$srcfile\""
-  echo "Generating info... ($cmd)"
-  rm -f $PACKAGE.info* # get rid of any strays
-  eval "$cmd"
-  tar czf "$outdir/$PACKAGE.info.tar.gz" $PACKAGE.info*
-  ls -l "$outdir/$PACKAGE.info.tar.gz"
-  info_tgz_size=`calcsize "$outdir/$PACKAGE.info.tar.gz"`
-  # do not mv the info files, there's no point in having them available
-  # separately on the web.
-fi  # end info
-
-# 
-if $generate_tex; then
-  cmd="$SETLANG $TEXI2DVI $dirargs $texarg \"$srcfile\""
-  printf "\nGenerating dvi... ($cmd)\n"
-  eval "$cmd"
-  # compress/finish dvi:
-  gzip -f -9 $PACKAGE.dvi
-  dvi_gz_size=`calcsize $PACKAGE.dvi.gz`
-  mv $PACKAGE.dvi.gz "$outdir/"
-  ls -l "$outdir/$PACKAGE.dvi.gz"
-
-  cmd="$SETLANG $TEXI2DVI --pdf $dirargs $texarg \"$srcfile\""
-  printf "\nGenerating pdf... ($cmd)\n"
-  eval "$cmd"
-  pdf_size=`calcsize $PACKAGE.pdf`
-  mv $PACKAGE.pdf "$outdir/"
-  ls -l "$outdir/$PACKAGE.pdf"
-fi # end tex (dvi + pdf)
-
-# 
-if $generate_ascii; then
-  opt="-o $PACKAGE.txt --no-split --no-headers $commonarg"
-  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
-  printf "\nGenerating ascii... ($cmd)\n"
-  eval "$cmd"
-  ascii_size=`calcsize $PACKAGE.txt`
-  gzip -f -9 -c $PACKAGE.txt >"$outdir/$PACKAGE.txt.gz"
-  ascii_gz_size=`calcsize "$outdir/$PACKAGE.txt.gz"`
-  mv $PACKAGE.txt "$outdir/"
-  ls -l "$outdir/$PACKAGE.txt" "$outdir/$PACKAGE.txt.gz"
-fi
-
-# 
-
-if $generate_html; then
-# Split HTML at level $1.  Used for texi2html.
-html_split()
-{
-  opt="--split=$1 --node-files $commonarg $htmlarg"
-  cmd="$SETLANG $TEXI2HTML --output $PACKAGE.html $opt \"$srcfile\""
-  printf "\nGenerating html by $1... ($cmd)\n"
-  eval "$cmd"
-  split_html_dir=$PACKAGE.html
-  (
-    cd ${split_html_dir} || exit 1
-    ln -sf ${PACKAGE}.html index.html
-    tar -czf "$abs_outdir/${PACKAGE}.html_$1.tar.gz" -- *.html
-  )
-  eval html_$1_tgz_size=`calcsize "$outdir/${PACKAGE}.html_$1.tar.gz"`
-  rm -f "$outdir"/html_$1/*.html
-  mkdir -p "$outdir/html_$1/"
-  mv ${split_html_dir}/*.html "$outdir/html_$1/"
-  rmdir ${split_html_dir}
-}
-
-if test -z "$use_texi2html"; then
-  opt="--no-split --html -o $PACKAGE.html $commonarg $htmlarg"
-  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
-  printf "\nGenerating monolithic html... ($cmd)\n"
-  rm -rf $PACKAGE.html  # in case a directory is left over
-  eval "$cmd"
-  html_mono_size=`calcsize $PACKAGE.html`
-  gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz"
-  html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"`
-  copy_images "$outdir/" $PACKAGE.html
-  mv $PACKAGE.html "$outdir/"
-  ls -l "$outdir/$PACKAGE.html" "$outdir/$PACKAGE.html.gz"
-
-  # Before Texinfo 5.0, makeinfo did not accept a --split=HOW option,
-  # it just always split by node.  So if we're splitting by node anyway,
-  # leave it out.
-  if test "x$split" = xnode; then
-    split_arg=
-  else
-    split_arg=--split=$split
-  fi
-  #
-  opt="--html -o $PACKAGE.html $split_arg $commonarg $htmlarg"
-  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\""
-  printf "\nGenerating html by $split... ($cmd)\n"
-  eval "$cmd"
-  split_html_dir=$PACKAGE.html
-  copy_images $split_html_dir/ $split_html_dir/*.html
-  (
-    cd $split_html_dir || exit 1
-    tar -czf "$abs_outdir/$PACKAGE.html_$split.tar.gz" -- *
-  )
-  eval \
-    html_${split}_tgz_size=`calcsize "$outdir/$PACKAGE.html_$split.tar.gz"`
-  rm -rf "$outdir/html_$split/"
-  mv $split_html_dir "$outdir/html_$split/"
-  du -s "$outdir/html_$split/"
-  ls -l "$outdir/$PACKAGE.html_$split.tar.gz"
-
-else # use texi2html:
-  opt="--output $PACKAGE.html $commonarg $htmlarg"
-  cmd="$SETLANG $TEXI2HTML $opt \"$srcfile\""
-  printf "\nGenerating monolithic html with texi2html... ($cmd)\n"
-  rm -rf $PACKAGE.html  # in case a directory is left over
-  eval "$cmd"
-  html_mono_size=`calcsize $PACKAGE.html`
-  gzip -f -9 -c $PACKAGE.html >"$outdir/$PACKAGE.html.gz"
-  html_mono_gz_size=`calcsize "$outdir/$PACKAGE.html.gz"`
-  mv $PACKAGE.html "$outdir/"
-
-  html_split node
-  html_split chapter
-  html_split section
-fi
-fi # end html
-
-# 
-printf "\nMaking .tar.gz for sources...\n"
-d=`dirname $srcfile`
-(
-  cd "$d"
-  srcfiles=`ls -d *.texinfo *.texi *.txi *.eps $source_extra 2>/dev/null` || true
-  tar czfh "$abs_outdir/$PACKAGE.texi.tar.gz" $srcfiles
-  ls -l "$abs_outdir/$PACKAGE.texi.tar.gz"
-)
-texi_tgz_size=`calcsize "$outdir/$PACKAGE.texi.tar.gz"`
-
-# 
-# Do everything again through docbook.
-if test -n "$docbook"; then
-  opt="-o - --docbook $commonarg"
-  cmd="$SETLANG $MAKEINFO $opt \"$srcfile\" >${srcdir}/$PACKAGE-db.xml"
-  printf "\nGenerating docbook XML... ($cmd)\n"
-  eval "$cmd"
-  docbook_xml_size=`calcsize $PACKAGE-db.xml`
-  gzip -f -9 -c $PACKAGE-db.xml >"$outdir/$PACKAGE-db.xml.gz"
-  docbook_xml_gz_size=`calcsize "$outdir/$PACKAGE-db.xml.gz"`
-  mv $PACKAGE-db.xml "$outdir/"
-
-  split_html_db_dir=html_node_db
-  opt="$commonarg -o $split_html_db_dir"
-  cmd="$DOCBOOK2HTML $opt \"${outdir}/$PACKAGE-db.xml\""
-  printf "\nGenerating docbook HTML... ($cmd)\n"
-  eval "$cmd"
-  (
-    cd ${split_html_db_dir} || exit 1
-    tar -czf "$abs_outdir/${PACKAGE}.html_node_db.tar.gz" -- *.html
-  )
-  html_node_db_tgz_size=`calcsize "$outdir/${PACKAGE}.html_node_db.tar.gz"`
-  rm -f "$outdir"/html_node_db/*.html
-  mkdir -p "$outdir/html_node_db"
-  mv ${split_html_db_dir}/*.html "$outdir/html_node_db/"
-  rmdir ${split_html_db_dir}
-
-  cmd="$DOCBOOK2TXT \"${outdir}/$PACKAGE-db.xml\""
-  printf "\nGenerating docbook ASCII... ($cmd)\n"
-  eval "$cmd"
-  docbook_ascii_size=`calcsize $PACKAGE-db.txt`
-  mv $PACKAGE-db.txt "$outdir/"
-
-  cmd="$DOCBOOK2PDF \"${outdir}/$PACKAGE-db.xml\""
-  printf "\nGenerating docbook PDF... ($cmd)\n"
-  eval "$cmd"
-  docbook_pdf_size=`calcsize $PACKAGE-db.pdf`
-  mv $PACKAGE-db.pdf "$outdir/"
-fi
-
-# 
-printf "\nMaking index.html for $PACKAGE...\n"
-if test -z "$use_texi2html"; then
-  CONDS="/%%IF  *HTML_SECTION%%/,/%%ENDIF  *HTML_SECTION%%/d;\
-         /%%IF  *HTML_CHAPTER%%/,/%%ENDIF  *HTML_CHAPTER%%/d"
-else
-  # should take account of --split here.
-  CONDS="/%%ENDIF.*%%/d;/%%IF  *HTML_SECTION%%/d;/%%IF  *HTML_CHAPTER%%/d"
-fi
-
-curdate=`$SETLANG date '+%B %d, %Y'`
-sed \
-   -e "s!%%TITLE%%!$MANUAL_TITLE!g" \
-   -e "s!%%EMAIL%%!$EMAIL!g" \
-   -e "s!%%PACKAGE%%!$PACKAGE!g" \
-   -e "s!%%DATE%%!$curdate!g" \
-   -e "s!%%HTML_MONO_SIZE%%!$html_mono_size!g" \
-   -e "s!%%HTML_MONO_GZ_SIZE%%!$html_mono_gz_size!g" \
-   -e "s!%%HTML_NODE_TGZ_SIZE%%!$html_node_tgz_size!g" \
-   -e "s!%%HTML_SECTION_TGZ_SIZE%%!$html_section_tgz_size!g" \
-   -e "s!%%HTML_CHAPTER_TGZ_SIZE%%!$html_chapter_tgz_size!g" \
-   -e "s!%%INFO_TGZ_SIZE%%!$info_tgz_size!g" \
-   -e "s!%%DVI_GZ_SIZE%%!$dvi_gz_size!g" \
-   -e "s!%%PDF_SIZE%%!$pdf_size!g" \
-   -e "s!%%ASCII_SIZE%%!$ascii_size!g" \
-   -e "s!%%ASCII_GZ_SIZE%%!$ascii_gz_size!g" \
-   -e "s!%%TEXI_TGZ_SIZE%%!$texi_tgz_size!g" \
-   -e "s!%%DOCBOOK_HTML_NODE_TGZ_SIZE%%!$html_node_db_tgz_size!g" \
-   -e "s!%%DOCBOOK_ASCII_SIZE%%!$docbook_ascii_size!g" \
-   -e "s!%%DOCBOOK_PDF_SIZE%%!$docbook_pdf_size!g" \
-   -e "s!%%DOCBOOK_XML_SIZE%%!$docbook_xml_size!g" \
-   -e "s!%%DOCBOOK_XML_GZ_SIZE%%!$docbook_xml_gz_size!g" \
-   -e "s,%%SCRIPTURL%%,$scripturl,g" \
-   -e "s!%%SCRIPTNAME%%!$prog!g" \
-   -e "$CONDS" \
-$GENDOCS_TEMPLATE_DIR/gendocs_template >"$outdir/index.html"
-
-echo "Done, see $outdir/ subdirectory for new files."
-
-# Local variables:
-# eval: (add-hook 'write-file-hooks 'time-stamp)
-# time-stamp-start: "scriptversion="
-# time-stamp-format: "%:y-%02m-%02d.%02H"
-# time-stamp-end: "$"
-# End:
diff --git a/doc/gendocs_template b/doc/gendocs_template
deleted file mode 100644
index 178f6cb4c8..0000000000
--- a/doc/gendocs_template
+++ /dev/null
@@ -1,91 +0,0 @@
-<!--#include virtual="/server/header.html" -->
-<!-- Parent-Version: 1.77 -->
-<title>%%TITLE%% - GNU Project - Free Software Foundation</title>
-<!--#include virtual="/server/banner.html" -->
-<h2>%%TITLE%%</h2>
-
-<address>Free Software Foundation</address>
-<address>last updated %%DATE%%</address>
-
-<p>This manual (%%PACKAGE%%) is available in the following formats:</p>
-
-<ul>
-<li><a href="%%PACKAGE%%.html">HTML
-    (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
-<li><a href="html_node/index.html">HTML</a> - with one web page per
-    node.</li>
-%%IF HTML_SECTION%%
-<li><a href="html_section/index.html">HTML</a> - with one web page per
-    section.</li>
-%%ENDIF HTML_SECTION%%
-%%IF HTML_CHAPTER%%
-<li><a href="html_chapter/index.html">HTML</a> - with one web page per
-    chapter.</li>
-%%ENDIF HTML_CHAPTER%%
-<li><a href="%%PACKAGE%%.html.gz">HTML compressed
-    (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
-    one web page.</li>
-<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
-    (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
-    with one web page per node.</li>
-%%IF HTML_SECTION%%
-<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
-    (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
-    with one web page per section.</li>
-%%ENDIF HTML_SECTION%%
-%%IF HTML_CHAPTER%%
-<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
-    (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
-    with one web page per chapter.</li>
-%%ENDIF HTML_CHAPTER%%
-<li><a href="%%PACKAGE%%.info.tar.gz">Info document
-    (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li>
-<li><a href="%%PACKAGE%%.txt">ASCII text
-    (%%ASCII_SIZE%%K bytes)</a>.</li>
-<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
-    (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li>
-<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
-    (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li>
-<li><a href="%%PACKAGE%%.pdf">PDF file
-    (%%PDF_SIZE%%K bytes)</a>.</li>
-<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
-    (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li>
-</ul>
-
-<p>You can <a href="http://shop.fsf.org/">buy printed copies of
-some manuals</a> (among other items) from the Free Software Foundation;
-this helps support FSF activities.</p>
-
-<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%%
-script</a>.)</p>
-
-<!-- If needed, change the copyright block at the bottom. In general,
-     all pages on the GNU web server should have the section about
-     verbatim copying.  Please do NOT remove this without talking
-     with the webmasters first.
-     Please make sure the copyright date is consistent with the document
-     and that it is like this: "2001, 2002", not this: "2001-2002". -->
-</div><!-- for id="content", starts in the include above -->
-<!--#include virtual="/server/footer.html" -->
-<div id="footer">
-<div class="unprintable">
-
-<p>Please send general FSF &amp; GNU inquiries to
-<a href="mailto:gnu@gnu.org">&lt;gnu@gnu.org&gt;</a>.
-There are also <a href="/contact/">other ways to contact</a>
-the FSF.  Broken links and other corrections or suggestions can be sent
-to <a href="mailto:%%EMAIL%%">&lt;%%EMAIL%%&gt;</a>.</p>
-</div>
-
-<p>Copyright &copy; 2017 Free Software Foundation, Inc.</p>
-
-<p>This page is licensed under a <a rel="license"
-href="http://creativecommons.org/licenses/by-nd/3.0/us/">Creative
-Commons Attribution-NoDerivs 3.0 United States License</a>.</p>
-
-<!--#include virtual="/server/bottom-notes.html" -->
-
-</div>
-</div>
-</body>
-</html>
diff --git a/doc/gendocs_template_min b/doc/gendocs_template_min
deleted file mode 100644
index 112fa3bfb6..0000000000
--- a/doc/gendocs_template_min
+++ /dev/null
@@ -1,93 +0,0 @@
-<?xml version="1.0" encoding="utf-8" ?>
-<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
-    "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
-<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
-
-<head>
-<title>%%TITLE%% - GNU Project - Free Software Foundation</title>
-<meta http-equiv="content-type" content='text/html; charset=utf-8' />
-<link rel="stylesheet" type="text/css" href="/gnu.css" />
-</head>
-
-<body>
-
-<h3>%%TITLE%%</h3>
-
-<address>Free Software Foundation</address>
-<address>last updated %%DATE%%</address>
-<p>
-<a href="/graphics/gnu-head.jpg">
-	<img src="/graphics/gnu-head-sm.jpg"
-             alt=" [image of the head of a GNU] " width="129" height="122"/>
-</a>
-</p>
-<hr />
-
-<p>This manual (%%PACKAGE%%) is available in the following formats:</p>
-
-<ul>
-<li><a href="%%PACKAGE%%.html">HTML
-    (%%HTML_MONO_SIZE%%K bytes)</a> - entirely on one web page.</li>
-<li><a href="html_node/index.html">HTML</a> - with one web page per
-    node.</li>
-%%IF HTML_SECTION%%
-<li><a href="html_section/index.html">HTML</a> - with one web page per
-    section.</li>
-%%ENDIF HTML_SECTION%%
-%%IF HTML_CHAPTER%%
-<li><a href="html_chapter/index.html">HTML</a> - with one web page per
-    chapter.</li>
-%%ENDIF HTML_CHAPTER%%
-<li><a href="%%PACKAGE%%.html.gz">HTML compressed
-    (%%HTML_MONO_GZ_SIZE%%K gzipped characters)</a> - entirely on
-    one web page.</li>
-<li><a href="%%PACKAGE%%.html_node.tar.gz">HTML compressed
-    (%%HTML_NODE_TGZ_SIZE%%K gzipped tar file)</a> -
-    with one web page per node.</li>
-%%IF HTML_SECTION%%
-<li><a href="%%PACKAGE%%.html_section.tar.gz">HTML compressed
-    (%%HTML_SECTION_TGZ_SIZE%%K gzipped tar file)</a> -
-    with one web page per section.</li>
-%%ENDIF HTML_SECTION%%
-%%IF HTML_CHAPTER%%
-<li><a href="%%PACKAGE%%.html_chapter.tar.gz">HTML compressed
-    (%%HTML_CHAPTER_TGZ_SIZE%%K gzipped tar file)</a> -
-    with one web page per chapter.</li>
-%%ENDIF HTML_CHAPTER%%
-<li><a href="%%PACKAGE%%.info.tar.gz">Info document
-    (%%INFO_TGZ_SIZE%%K bytes gzipped tar file)</a>.</li>
-<li><a href="%%PACKAGE%%.txt">ASCII text
-    (%%ASCII_SIZE%%K bytes)</a>.</li>
-<li><a href="%%PACKAGE%%.txt.gz">ASCII text compressed
-    (%%ASCII_GZ_SIZE%%K bytes gzipped)</a>.</li>
-<li><a href="%%PACKAGE%%.dvi.gz">TeX dvi file
-    (%%DVI_GZ_SIZE%%K bytes gzipped)</a>.</li>
-<li><a href="%%PACKAGE%%.pdf">PDF file
-    (%%PDF_SIZE%%K bytes)</a>.</li>
-<li><a href="%%PACKAGE%%.texi.tar.gz">Texinfo source
-    (%%TEXI_TGZ_SIZE%%K bytes gzipped tar file).</a></li>
-</ul>
-
-<p>(This page generated by the <a href="%%SCRIPTURL%%">%%SCRIPTNAME%%
-script</a>.)</p>
-
-<div id="footer" class="copyright">
-
-<p>Please send general FSF &amp; GNU inquiries to
-<a href="mailto:gnu@gnu.org">&lt;gnu@gnu.org&gt;</a>.
-There are also <a href="/contact/">other ways to contact</a>
-the FSF.  Broken links and other corrections or suggestions can be sent
-to <a href="mailto:%%EMAIL%%">&lt;%%EMAIL%%&gt;</a>.</p>
-</div>
-
-<p>Copyright &copy; 2017 Free Software Foundation, Inc.</p>
-
-<p>This page is licensed under a <a rel="license"
-href="http://creativecommons.org/licenses/by-nd/3.0/us/">Creative
-Commons Attribution-NoDerivs 3.0 United States License</a>.</p>
-
-<!--#include virtual="/server/bottom-notes.html" -->
-
-</div>
-</body>
-</html>
-- 
cgit v1.2.3-70-g09d2


From e2f0870adf4baad5dfefaefd92c122ee9e1e0e5a Mon Sep 17 00:00:00 2001
From: ng0 <ng0@infotropique.org>
Date: Thu, 26 Oct 2017 12:28:28 +0000
Subject: documentation

---
 doc/documentation/chapters/developer.texi | 169 +++++++++++++++++-------------
 doc/documentation/gnunet-c-tutorial.texi  |  51 ++++++---
 doc/documentation/htmlxref.cnf            |   2 +-
 3 files changed, 131 insertions(+), 91 deletions(-)

(limited to 'doc/documentation/gnunet-c-tutorial.texi')

diff --git a/doc/documentation/chapters/developer.texi b/doc/documentation/chapters/developer.texi
index 996474359c..9459068a96 100644
--- a/doc/documentation/chapters/developer.texi
+++ b/doc/documentation/chapters/developer.texi
@@ -4,11 +4,14 @@
 
 This book is intended to be an introduction for programmers that want to
 extend the GNUnet framework. GNUnet is more than a simple peer-to-peer
-application. For developers, GNUnet is:
+application.
+
+For developers, GNUnet is:
 
 @itemize @bullet
-@item Free software under the GNU General Public License, with a community
-that believes in the GNU philosophy
+@item developed by a community that believes in the GNU philosophy
+@item Free Software (Free as in Freedom), licensed under the
+@xref{GNU General Public License}
 @item A set of standards, including coding conventions and
 architectural rules
 @item A set of layered protocols, both specifying the communication
@@ -20,17 +23,19 @@ writing extensions
 
 In particular, the architecture specifies that a peer consists of many
 processes communicating via protocols. Processes can be written in almost
-any language. C and Java APIs exist for accessing existing services and
-for writing extensions. It is possible to write extensions in other
-languages by implementing the necessary IPC protocols.
+any language.
+C and Java APIs exist for accessing existing services and for writing
+extensions. It is possible to write extensions in other languages by
+implementing the necessary IPC protocols.
 
 GNUnet can be extended and improved along many possible dimensions, and
 anyone interested in Free Software and Freedom-enhancing Networking is
 welcome to join the effort. This Developer Handbook attempts to provide
 an initial introduction to some of the key design choices and central
-components of the system. This part of the GNUNet documentation
-is far from complete, and we welcome informed contributions,
-be it in the form of new chapters or insightful comments.
+components of the system.
+This part of the GNUNet documentation is far from complete,
+and we welcome informed contributions, be it in the form of
+new chapters, sections or insightful comments.
 
 @menu
 * Developer Introduction::
@@ -92,11 +97,13 @@ following links:
 @item GNUnet Java tutorial
 @end itemize
 
-In addition to this book, the GNUnet server contains various resources for
-GNUnet developers. They are all conveniently reachable via the "Developer"
+In addition to the GNUnet Reference Documentation you are reading,
+the GNUnet server contains various resources for GNUnet
+developers and those who aspire to become regular contributors.
+They are all conveniently reachable via the "Developer"
 entry in the navigation menu. Some additional tools (such as static
 analysis reports) require a special developer access to perform certain
-operations. If you feel you need access, you should contact
+operations. If you want (or require) access, you should contact
 @uref{http://grothoff.org/christian/, Christian Grothoff},
 GNUnet's maintainer.
 
@@ -104,20 +111,26 @@ The public subsystems on the GNUnet server that help developers are:
 
 @itemize @bullet
 
-@item The Version control system (git) keeps our code and enables
+@item The version control system (git) keeps our code and enables
 distributed development.
+It is pubclicly accessible at @uref{https://gnunet.org/git/}.
 Only developers with write access can commit code, everyone else is
 encouraged to submit patches to the
-@uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, GNUnet-developers mailinglist}
-.
-
-@item The GNUnet bugtracking system (Mantis) is used to track
-feature requests, open bug reports and their resolutions.
-Anyone can report bugs, only developers can claim to have fixed them.
-
-@item A site installation of the CI system "Buildbot" is used to check
-GNUnet builds automatically on a range of platforms.
-Builds are triggered automatically after 30 minutes of no changes to Git.
+@uref{https://lists.gnu.org/mailman/listinfo/gnunet-developers, GNUnet-developers mailinglist}.
+
+@item The bugtracking system (Mantis).
+We use it to track feature requests, open bug reports and their
+resolutions.
+It can be accessed at @uref{https://gnunet.org/bugs/}.
+Anyone can report bugs, but only developers can claim to have fixed them.
+
+@item Our site installation of the
+CI@footnote{Continuous Integration} system "@code{Buildbot}" is used
+to check GNUnet builds automatically on a range of platforms.
+The web interface of this CI is exposed at
+@uref{https://gnunet.org/buildbot/}.
+Builds are triggered automatically 30 minutes after the last commit to
+our repository was made.
 
 @item The current quality of our automated test suite is assessed using
 Code coverage analysis. This analysis is run daily; however the webpage
@@ -163,34 +176,41 @@ GNUnet sub-projects in order of likely relevance are currently:
 
 @table @asis
 
-@item gnunet
+@item @command{gnunet}
 Core of the P2P framework, including file-sharing, VPN and
-chat applications; this is what the developer handbook covers mostly
-@item gnunet-gtk Gtk+-based user interfaces, including gnunet-fs-gtk
-(file-sharing), gnunet-statistics-gtk (statistics over time),
-gnunet-peerinfo-gtk (information about current connections and known
-peers), gnunet-chat-gtk (chat GUI) and gnunet-setup (setup tool for
-"everything")
-@item gnunet-fuse
+chat applications; this is what the Developer Handbook covers mostly
+@item @command{gnunet-gtk}
+Gtk+-based user interfaces, including:
+
+@itemize @bullet
+@item @command{gnunet-fs-gtk} (file-sharing),
+@item @command{gnunet-statistics-gtk} (statistics over time),
+@item @command{gnunet-peerinfo-gtk}
+(information about current connections and known peers),
+@item @command{gnunet-chat-gtk} (chat GUI) and
+@item @command{gnunet-setup} (setup tool for "everything")
+@end itemize
+
+@item @command{gnunet-fuse}
 Mounting directories shared via GNUnet's file-sharing
-on Linux
-@item gnunet-update
+on GNU/Linux distributions
+@item @command{gnunet-update}
 Installation and update tool
-@item gnunet-ext
+@item @command{gnunet-ext}
 Template for starting 'external' GNUnet projects
-@item gnunet-java
+@item @command{gnunet-java}
 Java APIs for writing GNUnet services and applications
 @c ** FIXME: Point to new website repository once we have it:
 @c ** @item svn/gnunet-www/ Code and media helping drive the GNUnet
 @c website
-@item eclectic
+@item @command{eclectic}
 Code to run GNUnet nodes on testbeds for research, development,
 testing and evaluation
 @c ** FIXME: Solve the status and location of gnunet-qt
-@item gnunet-qt
-Qt-based GNUnet GUI (dead?)
-@item gnunet-cocoa
-cocoa-based GNUnet GUI (dead?)
+@item @command{gnunet-qt}
+Qt-based GNUnet GUI (is it depreacated?)
+@item @command{gnunet-cocoa}
+cocoa-based GNUnet GUI (is it depreacated?)
 
 @end table
 
@@ -198,19 +218,19 @@ We are also working on various supporting libraries and tools:
 @c ** FIXME: What about gauger, and what about libmwmodem?
 
 @table @asis
-@item libextractor
+@item @command{libextractor}
 GNU libextractor (meta data extraction)
-@item libmicrohttpd
+@item @command{libmicrohttpd}
 GNU libmicrohttpd (embedded HTTP(S) server library)
-@item gauger
+@item @command{gauger}
 Tool for performance regression analysis
-@item monkey
+@item @command{monkey}
 Tool for automated debugging of distributed systems
-@item libmwmodem
+@item @command{libmwmodem}
 Library for accessing satellite connection quality
 reports
-@item libgnurl
-gnURL (feature restricted variant of cURL/libcurl)
+@item @command{libgnurl}
+gnURL (feature-restricted variant of cURL/libcurl)
 @end table
 
 Finally, there are various external projects (see links for a list of
@@ -247,7 +267,7 @@ type defines a particular format and how that binary format is to be
 linked to a hash code (the key for the DHT and for databases). The block
 library is a wapper around block plugins which provide the necessary
 functions for each block type.
-@item @file{statistics/}
+@item @file{statistics/} --- statistics service
 The statistics service enables associating
 values (of type uint64_t) with a componenet name and a string. The main
 uses is debugging (counting events), performance tracking and user
@@ -257,7 +277,7 @@ The automatic-restart-manager (ARM) service
 is the GNUnet master service. Its role is to start gnunet-services, to
 re-start them when they crashed and finally to shut down the system when
 requested.
-@item @file{peerinfo/}
+@item @file{peerinfo/} --- peerinfo service
 The peerinfo service keeps track of which peers are known
 to the local peer and also tracks the validated addresses for each peer
 (in the form of a HELLO message) for each of those peers. The peer is not
@@ -269,17 +289,17 @@ The datacache library provides (temporary) block storage for the DHT.
 Existing plugins can store blocks in Sqlite, Postgres or MySQL databases.
 All data stored in the cache is lost when the peer is stopped or
 restarted (datacache uses temporary tables).
-@item @file{datastore/}
+@item @file{datastore/} --- datastore service
 The datastore service stores file-sharing blocks in
 databases for extended periods of time. In contrast to the datacache, data
 is not lost when peers restart. However, quota restrictions may still
 cause old, expired or low-priority data to be eventually discarded.
 Existing plugins can store blocks in Sqlite, Postgres or MySQL databases.
-@item @file{template/}
+@item @file{template/} --- service template
 Template for writing a new service. Does nothing.
 @item @file{ats/} --- Automatic Transport Selection
-The automatic transport
-selection (ATS) service is responsible for deciding which address (i.e.
+The automatic transport selection (ATS) service
+is responsible for deciding which address (i.e.
 which transport plugin) should be used for communication with other peers,
 and at what bandwidth.
 @item @file{nat/} --- libgnunetnat
@@ -295,14 +315,14 @@ transfer unit (MTU) for packets. The fragmentation library can be used to
 break larger packets into chunks of at most 1k and transmit the resulting
 fragments reliabily (with acknowledgement, retransmission, timeouts,
 etc.).
-@item @file{transport/}
+@item @file{transport/} --- transport service
 The transport service is responsible for managing the
 basic P2P communication. It uses plugins to support P2P communication
 over TCP, UDP, HTTP, HTTPS and other protocols.The transport service
 validates peer addresses, enforces bandwidth restrictions, limits the
 total number of connections and enforces connectivity restrictions (i.e.
 friends-only).
-@item @file{peerinfo-tool/}
+@item @file{peerinfo-tool/} --- gnunet-peerinfo
 This directory contains the gnunet-peerinfo binary which can be used to
 inspect the peers and HELLOs known to the peerinfo service.
 @item @file{core/}
@@ -315,7 +335,7 @@ for writing testcases.
 It also supports automatic generation of configurations for peers
 ensuring that the ports and paths are disjoint. libgnunettesting is also
 the foundation for the testbed service
-@item @file{testbed/}
+@item @file{testbed/} --- testbed service
 The testbed service is used for creating small or large scale deployments
 of GNUnet peers for evaluation of protocols.
 It facilitates peer depolyments on multiple
@@ -329,13 +349,13 @@ P2P network.
 The distributed hash table (DHT) service provides a
 distributed implementation of a hash table to store blocks under hash
 keys in the P2P network.
-@item @file{hostlist/}
+@item @file{hostlist/} --- hostlist service
 The hostlist service allows learning about
 other peers in the network by downloading HELLO messages from an HTTP
 server, can be configured to run such an HTTP server and also implements
 a P2P protocol to advertise and automatically learn about other peers
 that offer a public hostlist server.
-@item @file{topology/}
+@item @file{topology/} --- topology service
 The topology service is responsible for
 maintaining the mesh topology. It tries to maintain connections to friends
 (depending on the configuration) and also tries to ensure that the peer
@@ -349,7 +369,7 @@ connections are permitted (for friend-to-friend networking)
 The file-sharing (FS) service implements GNUnet's
 file-sharing application. Both anonymous file-sharing (using gap) and
 non-anonymous file-sharing (using dht) are supported.
-@item @file{cadet/}
+@item @file{cadet/} --- cadet service
 The CADET service provides a general-purpose routing abstraction to create
 end-to-end encrypted tunnels in mesh networks. We wrote a paper
 documenting key aspects of the design.
@@ -368,7 +388,7 @@ Service that allows intercepting and modifying DNS requests of
 the local machine. Currently used for IPv4-IPv6 protocol translation
 (DNS-ALG) as implemented by "pt/" and for the GNUnet naming system. The
 service can also be configured to offer an exit service for DNS traffic.
-@item @file{vpn/}
+@item @file{vpn/} --- VPN service
 The virtual public network (VPN) service provides a virtual
 tunnel interface (VTUN) for IP routing over GNUnet.
 Needs some other peers to run an "exit" service to work.
@@ -741,6 +761,7 @@ libgnunet_plugin_transport_tcp)
 @node Coding style
 @subsection Coding style
 
+@c XXX: Adjust examples to GNU Standards!
 @itemize @bullet
 @item We follow the GNU Coding Standards (@pxref{Top, The GNU Coding Standards,, standards, The GNU Coding Standards});
 @item Indentation is done with spaces, two per level, no tabs;
@@ -1346,31 +1367,31 @@ shell program. For e.g:
 
 @example
 export GNUNET_TESTBED_RSH_CMD="ssh -o BatchMode=yes \
--o NoHostAuthenticationForLocalhost=yes %h"@
+-o NoHostAuthenticationForLocalhost=yes %h"
 @end example
 
-Substitutions are allowed int the above command string also allows for
-substitions. through placemarks which begin with a `%'. At present the
-following substitutions are supported
+Substitutions are allowed in the command string above,
+this allows for substitutions through placemarks which begin with a `%'.
+At present the following substitutions are supported
 
 @itemize @bullet
-@item
-%h: hostname
-@item
-%u: username
-@item
-%p: port
+@item %h: hostname
+@item %u: username
+@item %p: port
 @end itemize
 
 Note that the substitution placemark is replaced only when the
 corresponding field is available and only once. Specifying
+
 @example
 %u@atchar{}%h
 @end example
-doesn't work either.
-If you want to user username substitutions for SSH
-use the argument @code{-l} before the username substitution.
-For exmaple:
+
+doesn't work either. If you want to user username substitutions for
+@command{SSH}, use the argument @code{-l} before the
+username substitution.
+
+For example:
 @example
 ssh -l %u -p %p %h
 @end example
diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi
index aca40d2ef1..b62db7855b 100644
--- a/doc/documentation/gnunet-c-tutorial.texi
+++ b/doc/documentation/gnunet-c-tutorial.texi
@@ -160,6 +160,16 @@ $ gpg --keyserver keys.gnupg.net --recv-keys 48426C7E
 @noindent
 and rerun the @code{gpg --verify-files} command.
 
+@b{Note:}@
+@b{The pub key to sign the 0.10.1 release has been
+revoked}. You will get an error message stating that
+@i{there is no known public key or that it has been revoked}.
+The next release of GNUnet will have a valid signature
+again. We are sorry for the inconvenience this causes.
+Another possible source you could use is our
+"gnunet" git repository which has mandatory signed commits
+by every developer.
+
 Now you can extract the tarball and rename the resulting
 directory to @i{gnunet} which we will be using in the
 remainder of this document.
@@ -178,14 +188,19 @@ from @uref{https://gnunet.org/git/, git}.
 @node  Installing Build Tool Chain and Dependencies
 @section Installing Build Tool Chain and Dependencies
 
-To successfully compile GNUnet you need the tools to build GNUnet and
-the required dependencies. Please have a look at
-@uref{https://gnunet.org/dependencies} for a list of required dependencies
-and @uref{https://gnunet.org/generic_installation} for specific
-instructions for your operating system. Please check the notes at
-the end of the configure process about required dependencies.
-
-For GNUnet bootstrapping support and the http(s) plugin you should
+To successfully compile GNUnet, you need the tools to build GNUnet and
+the required dependencies. Please take a look at the
+GNUnet Reference Documentation
+(@pxref{Dependencies, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation})
+for a list of required dependencies
+and
+(@pxref{Generic installation instructions, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation})
+read its Installation chapter for specific instructions for
+your operating system.
+Please check the notes at the end of the configure process about
+required dependencies.
+
+For GNUnet bootstrapping support and the HTTP(S) plugin you should
 install @uref{https://gnunet.org/gnurl, libgnurl}.
 For the filesharing service you should install at least one of the
 datastore backends. MySQL, SQlite and PostgreSQL are supported.
@@ -194,8 +209,8 @@ datastore backends. MySQL, SQlite and PostgreSQL are supported.
 @section Obtaining the latest version from Git
 
 The latest development version can obtained from our Git repository.
-To obtain the code you need Git installed and checkout the repository
-using:
+To obtain the code you need to have @code{Git} installed, which is
+required for obtaining the repository via:
 
 @example
 $ git clone https://gnunet.org/git/gnunet
@@ -203,21 +218,25 @@ $ git clone https://gnunet.org/git/gnunet
 
 @noindent
 After cloning the repository you have to execute the @file{bootstrap}
-script in the directory:
+script in the new directory:
 
 @example
-$ cd gnunet ; ./bootstrap
+$ cd gnunet
+$ ./bootstrap
 @end example
 
 @noindent
-The remainder of this tutorial assumes that you have the Git branch
-``master'' checked out.
+The remainder of this tutorial will assume that you have the
+Git branch ``master'' checked out.
 
 @node Compiling and Installing GNUnet
 @section Compiling and Installing GNUnet
 
-First, you need to install at least libgnupgerror 1.27 and
-libgcrypt 1.7.6.
+Note: This section is a duplication of the more in depth
+@pxref{GNUnet Installation Handbook, The GNUnet Reference Documentation,, gnunet, The GNUnet Reference Documentation}.
+
+First, you need to install libgnupgerror @geq{} 1.27 and
+libgcrypt @geq{} 1.7.6:
 
 @example
 $ export GNUPGFTP="https://www.gnupg.org/ftp/gcrypt"
diff --git a/doc/documentation/htmlxref.cnf b/doc/documentation/htmlxref.cnf
index 9ab9e4158d..a4928f6fee 100644
--- a/doc/documentation/htmlxref.cnf
+++ b/doc/documentation/htmlxref.cnf
@@ -2,7 +2,7 @@
 # Modified by Ludovic Courtès <ludo@gnu.org> for the GNU Guix manual.
 # Modified by ng0 <ng0@gnunet.org> for the GNUnet manual.
 
-htmlxrefversion=2017-10-25.16; # UTC
+htmlxrefversion=2017-10-26.06; # UTC
 
 # Copyright 2010, 2011, 2012, 2013, 2014, 2015 Free Software Foundation, Inc.
 # 
-- 
cgit v1.2.3-70-g09d2


From 732816be49f49ec4b3db669b73d817fe5f930803 Mon Sep 17 00:00:00 2001
From: ng0 <ng0@infotropique.org>
Date: Thu, 26 Oct 2017 12:59:47 +0000
Subject: @i{} -> @b{} and @{code} where appropriate

Avoid italics.
---
 doc/documentation/gnunet-c-tutorial.texi | 27 ++++++++++++++-------------
 1 file changed, 14 insertions(+), 13 deletions(-)

(limited to 'doc/documentation/gnunet-c-tutorial.texi')

diff --git a/doc/documentation/gnunet-c-tutorial.texi b/doc/documentation/gnunet-c-tutorial.texi
index b62db7855b..f39c7de642 100644
--- a/doc/documentation/gnunet-c-tutorial.texi
+++ b/doc/documentation/gnunet-c-tutorial.texi
@@ -163,7 +163,7 @@ and rerun the @code{gpg --verify-files} command.
 @b{Note:}@
 @b{The pub key to sign the 0.10.1 release has been
 revoked}. You will get an error message stating that
-@i{there is no known public key or that it has been revoked}.
+@b{there is no known public key or that it has been revoked}.
 The next release of GNUnet will have a valid signature
 again. We are sorry for the inconvenience this causes.
 Another possible source you could use is our
@@ -171,7 +171,7 @@ Another possible source you could use is our
 by every developer.
 
 Now you can extract the tarball and rename the resulting
-directory to @i{gnunet} which we will be using in the
+directory to @file{gnunet} which we will be using in the
 remainder of this document.
 
 @example
@@ -713,9 +713,10 @@ marked as ``done'' before their completion.
 
 An operation is treated as completed when it succeeds or fails.
 Completion of an operation is either conveyed as events through
-@i{controller event callback} or through respective operation
-completion callbacks.  In functions which support completion
-notification through both controller event callback and operation
+@dfn{controller event callback} or through respective
+@dfn{operation completion callbacks}.
+In functions which support completion notification
+through both controller event callback and operation
 completion callback, first the controller event callback will be
 called.  If the operation is not marked as done in that callback
 or if the callback is given as NULL when creating the operation,
@@ -733,14 +734,14 @@ discouraged as their locations are dynamically created and will be
 different among various runs of testbed.  To make access to these
 configurations easy, testbed API provides the function
 @code{GNUNET\_TESTBED\_service\_connect()}.  This function fetches
-the configuration of a given peer and calls the @i{Connect Adapter}.
+the configuration of a given peer and calls the @dfn{Connect Adapter}.
 In the example code, it is the @code{dht\_ca}.  A connect adapter is
 expected to open the connection to the needed service by using the
 provided configuration and return the created service connection handle.
 Successful connection to the needed service is signaled through
 @code{service\_connect\_comp\_cb}.
 
-A dual to connect adapter is the @i{Disconnect Adapter}.  This callback
+A dual to connect adapter is the @dfn{Disconnect Adapter}.  This callback
 is called after the connect adapter has been called when the operation
 from @code{GNUNET\_TESTBED\_service\_connect()} is marked as ``done''.
 It has to disconnect from the service with the provided service
@@ -750,8 +751,8 @@ Exercise: Find out how many peers you can run on your system.
 
 Exercise: Find out how to create a 2D torus topology by changing the
 options in the configuration file.
-See @uref{https://gnunet.org/supported-topologies}, then use the
-DHT API to store and retrieve values in the network.
+@xref{Supported Topologies, The GNUnet Reference Documentation ,, gnunet, The GNUnet Reference Documentation},
+then use the DHT API to store and retrieve values in the network.
 
 @node Developing Applications
 @chapter Developing Applications
@@ -1105,7 +1106,7 @@ peer to the service:
 
 @noindent
 Note that whatever you return from @code{connects} is given as the
-@i{cls} argument to the message handlers for messages from
+@code{cls} argument to the message handlers for messages from
 the respective peer.
 
 Exercise: Create a service that connects to the @code{CORE}.  Then
@@ -1116,7 +1117,7 @@ callback is invoked.
 @subsection Receiving P2P Messages
 
 To receive messages from @code{CORE}, you pass the desired
-@i{handlers} to the @code{GNUNET\_CORE\_connect()} function,
+@code{handlers} to the @code{GNUNET\_CORE\_connect()} function,
 just as we showed for services.
 
 It is your responsibility to process messages fast enough or
@@ -1132,8 +1133,8 @@ the two peers are connected?  Why?
 @node Sending P2P Messages
 @subsection Sending P2P Messages
 
-You can transmit messages to other peers using the @i{mq} you were
-given during the @code{connect} callback.  Note that the @i{mq}
+You can transmit messages to other peers using the @code{mq} you were
+given during the @code{connect} callback.  Note that the @code{mq}
 automatically is released upon @code{disconnect} and that you must
 not use it afterwards.
 
-- 
cgit v1.2.3-70-g09d2