doc: gnunet-c-tutorial: Add nodes.

1 files changed, 51 insertions, 12 deletions

diff --git a/doc/gnunet-c-tutorial.texi b/doc/gnunet-c-tutorial.texi
index 824834c92..156b6a14e 100644
--- a/doc/gnunet-c-tutorial.texi
+++ b/doc/gnunet-c-tutorial.texi
@@ -58,7 +58,7 @@ 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}
 
-
+@node Installing GNUnet
 @section Installing GNUnet
 
 First of all you have to install a current version of GNUnet. You can download a
@@ -70,6 +70,7 @@ latest development version things can be broken, functionality can be changed or
 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.
 
+@node Obtaining a stable version
 @subsection Obtaining a stable version
 
 You can download the latest stable version of GNUnet from GNU FTP mirrors:
@@ -95,6 +96,7 @@ $ cd gnunet
 However, please note that stable versions can be very outdated, as a developer
 you are strongly encouraged to use the version from @uref{https://gnunet.org/git/}.
 
+@node  Installing Build Tool Chain and Dependencies
 @subsection Installing Build Tool Chain and Dependencies
 
 To successfully compile GNUnet you need the tools to build GNUnet and the required dependencies.
@@ -107,6 +109,7 @@ For GNUnet bootstrapping support and the http(s) plugin you should install libgn
 For the filesharing service you should install at least one of the datastore backends mysql,
 sqlite or postgresql.
 
+@node Obtaining the latest version from Git
 @subsection Obtaining the latest version from Git
 
 The latest development version can obtained from our Git repository. To obtain
@@ -122,6 +125,7 @@ $ ./bootstrap
 
 The remainder of this tutorial assumes that you have Git branch ``master'' checked out.
 
+@node Compiling and Installing GNUnet
 @subsection Compiling and Installing GNUnet
 
 First, you need to install at least libgnupgerror version 1.27
@@ -146,6 +150,7 @@ $ sudo make install
 $ cd ..
 @end example
 
+@node Installing GNUnet
 @subsubsection Installing GNUnet
 Assuming all dependencies are installed, the following commands will
 compile and install GNUnet in your home directory. You can specify the
@@ -173,6 +178,7 @@ $ mkdir ~/.config/
 $ touch ~/.config/gnunet.conf
 @end example
 
+@node Common Issues - Check your GNUnet installation
 @subsection Common Issues - Check your GNUnet installation
 
 You should check your installation to ensure that installing GNUnet
@@ -204,6 +210,7 @@ PASS: test_gnunet_prefix
 =============
 @end example
 
+@node Background: GNUnet Architecture
 @section Background: GNUnet Architecture
 
 GNUnet is organized in layers and services. Each service is composed of a
@@ -247,9 +254,10 @@ 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
 @section First Steps with GNUnet
 
+@node Configure your peer
 @subsection Configure your peer
 
 First of all we need to configure your peer. Each peer is started with a configuration
@@ -280,6 +288,7 @@ GNUNET_HOME = ~/gnunet1/  # Use this directory to store GNUnet data
 SERVERS =                 # prevent bootstrapping
 @end example
 
+@node Start a peer
 @subsection 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
@@ -304,7 +313,7 @@ You should see an output containing the peer ID similar to:
 I am peer `0PA02UVRKQTS2C .. JL5Q78F6H0B1ACPV1CJI59MEQUMQCC5G'.
 @end example
 
-
+@node Monitor a peer
 @subsection Monitor a peer
 
 In this section, we will monitor the behaviour of our peer's DHT service with respect to a
@@ -328,7 +337,7 @@ $ gnunet-statistics -c ~/peer1.conf		# print statistics about current GNUnet sta
 $ gnunet-statistics -c ~/peer1.conf -s dht      # print statistics about DHT service
 @end example
 
-
+@node Starting Two Peers by Hand
 @subsection Starting Two Peers by Hand
 
 This section describes how to start two peers on the same machine by hand.
@@ -336,6 +345,7 @@ 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}).
 
+@node Setup a second peer
 @subsubsection 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
@@ -375,6 +385,7 @@ 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
 @subsubsection Start the second peer and connect the peers
 
 Then, you can start a second peer using:
@@ -413,6 +424,7 @@ 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
 @subsubsection How to connect manually
 
 If you want to use the @code{peerinfo} tool to connect your peers, you should:
@@ -430,6 +442,7 @@ $ gnunet-core -c peer1.conf
 Peer `9TVUCS8P5A7ILLBGO6 [...shortened...] 1KNBJ4NGCHP3JPVULDG'
 @end example
 
+@node Starting Peers Using the Testbed Service
 @subsection Starting Peers Using the Testbed Service
 @c \label{sec:testbed}
 
@@ -518,9 +531,10 @@ options in the configuration file. See @uref{https://gnunet.org/supported-topolo
 Then use the DHT API to store and retrieve values in the
 network.
 
-
+@node Developing Applications
 @section Developing Applications
 
+@node gnunet-ext
 @subsection 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
@@ -560,6 +574,7 @@ In addition the ext systems provides:
 @item a configuration template for the service (gnunet-ext/src/ext/ext.conf.in)
 @end itemize
 
+@node Adapting the Template
 @subsection Adapting the Template
 
 The first step for writing any extension with a new service is to
@@ -571,6 +586,7 @@ 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
@@ -583,6 +599,7 @@ used, which is typically not needed):
 @verbatiminclude tutorial-examples/001.c
 @end example
 
+@node Handling command-line options
 @subsection Handling command-line options
 
 Options can then be added easily by adding global variables and
@@ -612,6 +629,7 @@ 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
@@ -633,6 +651,7 @@ Unique message types must be defined for each message struct in the
 @file{gnunet\_protocols.h} header (or an extension-specific include
 file).
 
+@node Connecting to the Service
 @subsubsection Connecting to the Service
 
 Before a client library can implement the application-specific protocol
@@ -650,6 +669,7 @@ 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}
@@ -678,7 +698,7 @@ 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
@@ -702,7 +722,7 @@ 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
@@ -714,11 +734,13 @@ 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.
 
+@node Code Placement
 @subsection Code Placement
 
 New services are placed in their own subdirectory under @file{gnunet/src}.
@@ -728,6 +750,7 @@ the description of the client-service protocol @file{SERVICE.h} and P2P protocol
 @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:
@@ -767,7 +790,7 @@ 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!
@@ -781,6 +804,7 @@ is connect to the @code{CORE} service using:
 @verbatiminclude tutorial-examples/009.c
 @end example
 
+@node New P2P connections
 @subsection New P2P connections
 
 Before any traffic with a different peer can be exchanged, the peer must be
@@ -798,6 +822,7 @@ 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
@@ -814,7 +839,7 @@ 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
@@ -832,7 +857,7 @@ 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
@@ -846,6 +871,7 @@ The disconnect callback looks like the following:
 
 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.
@@ -868,6 +894,7 @@ The first step is to start a connection to the PEERSTORE service:
 The service handle @code{peerstore_handle} will be needed for all subsequent
 PEERSTORE operations.
 
+@node Storing records
 @subsection Storing records
 
 To store a new record, use the following function:
@@ -891,6 +918,7 @@ void
 GNUNET_PEERSTORE_store_cancel (struct GNUNET_PEERSTORE_StoreContext *sc);
 @end example
 
+@node Retrieving records
 @subsection Retrieving records
 
 To retrieve stored records, use the following function:
@@ -914,6 +942,7 @@ The @code{GNUNET_PEERSTORE_iterate} function returns a handle to the iterate ope
 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
@@ -929,6 +958,7 @@ is broken or the watch operation is canceled:
 @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
@@ -941,7 +971,7 @@ If the @code{sync_first} flag is set to @code{GNUNET_YES}, the API will delay th
 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
@@ -956,6 +986,7 @@ 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.
 
+@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
@@ -978,7 +1009,7 @@ 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
@@ -1000,6 +1031,7 @@ Exercise: Store a value in the DHT and after a while retrieve it. Show the IDs o
 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
@@ -1011,6 +1043,7 @@ in the service's respective directory. The
 mandatory functions that need to be implemented for a block plugin are
 described in the following sections.
 
+@node Validating requests and replies
 @subsubsection Validating requests and replies
 
 The evaluate function should validate a reply or a request. It returns
@@ -1033,6 +1066,7 @@ 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
@@ -1045,6 +1079,7 @@ just fine with such blocks).
 @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
@@ -1056,6 +1091,7 @@ validation and obtaining keys (the ones just defined above).
 @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
@@ -1065,6 +1101,7 @@ little.
 @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
@@ -1079,6 +1116,7 @@ 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,
@@ -1094,6 +1132,7 @@ is called with all the information about the event.
 @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