[GNUnet-SVN] [gnunet] branch master updated: restructure user documentation

[gnunet]

This is an automated email from the git hooks/post-receive script.

julius-buenger pushed a commit to branch master
in repository gnunet.

The following commit(s) were added to refs/heads/master by this push:
     new 3e1a4498d restructure user documentation
3e1a4498d is described below

commit 3e1a4498d2d95e957d783b3a25206385750f36cd
Author: Julius Bünger <address@hidden>
AuthorDate: Wed Jun 27 23:06:21 2018 +0200

    restructure user documentation
---
 doc/documentation/chapters/user.texi | 892 ++++++++++++++++++-----------------
 doc/documentation/gnunet.texi        |   8 +-
 2 files changed, 457 insertions(+), 443 deletions(-)

diff --git a/doc/documentation/chapters/user.texi 
b/doc/documentation/chapters/user.texi
index 9c9bd8df8..7bb277421 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -20,232 +20,32 @@ always welcome.
 
 
 @menu
-* Checking the Installation::
-* First steps - File-sharing::
+* Start and stop GNUnet::
 * First steps - Using the GNU Name System::
 * First steps - Using GNUnet Conversation::
 * First steps - Using the GNUnet VPN::
 * File-sharing::
 * The GNU Name System::
 * Using the Virtual Public Network::
-* The graphical configuration interface::
-* How to start and stop a GNUnet peer::
+* MOVE TO INSTALL The graphical configuration interface::
+* MOVE TO INSTALL Checking the Installation::
+* MOVE TO INSTALL Config Leftovers::
 @end menu
 
address@hidden Checking the Installation
address@hidden Checking the Installation
address@hidden %**end of header
-
-This section describes a quick, casual way to check if your GNUnet
-installation works. However, if it does not, we do not cover
-steps for recovery --- for this, please study the instructions
-provided in the developer handbook as well as the system-specific
-instruction in the source code address@hidden system specific instructions are 
not provided as part of this handbook!}.
-
-
address@hidden
-* gnunet-gtk::
-* Statistics::
-* Peer Information::
address@hidden menu
-
address@hidden GNUnet GTK
address@hidden GTK
address@hidden GTK user interface
address@hidden gnunet-gtk
address@hidden gnunet-gtk
address@hidden %**end of header
-
-The @command{gnunet-gtk} package contains several graphical
-user interfaces for the respective GNUnet applications.
-Currently these interfaces cover:
-
address@hidden @bullet
address@hidden Statistics
address@hidden Peer Information
address@hidden GNU Name System
address@hidden File Sharing
address@hidden Identity Management
address@hidden Conversation
address@hidden itemize
-
address@hidden Statistics
address@hidden Statistics
address@hidden %**end of header
address@hidden Start and stop GNUnet
address@hidden Start and stop GNUnet
 
-First, you should launch GNUnet address@hidden you should also start gnunet, 
via gnunet-arm or the system provided method}.
-You can do this from the command-line by typing
+To start GNUnet:
 
 @example
-gnunet-statistics-gtk
+$ gnunet-arm -s -l gnunet.log
 @end example
 
-If your address@hidden term ``peer'' is a common word used in federated and 
distributed networks to describe a participating device which is connected to 
the network. Thus, your Personal Computer or whatever it is you are looking at 
the Gtk+ interface describes a ``Peer'' or a ``Node''.}
-is running correctly, you should see a bunch of lines,
-all of which should be ``significantly'' above zero (at least if your
-peer has been running for more than a few seconds). The lines indicate
-how many other peers your peer is connected to (via different
-mechanisms) and how large the entire overlay network is currently
-estimated to be. The X-axis represents time (in seconds since the
-start of @command{gnunet-gtk}).
-
-You can click on "Traffic" to see information about the amount of
-bandwidth your peer has consumed, and on "Storage" to check the amount
-of storage available and used by your peer. Note that "Traffic" is
-plotted cumulatively, so you should see a strict upwards trend in the
-traffic.
-
address@hidden Peer Information
address@hidden Peer Information
address@hidden %**end of header
-
-First, you should launch the graphical user interface.  You can do
-this from the command-line by typing
+To stop GNUnet:
 
 @example
-$ gnunet-peerinfo-gtk
+$ gnunet-arm -e
 @end example
-
-Once you have done this, you will see a list of known peers (by the
-first four characters of their public key), their friend status (all
-should be marked as not-friends initially), their connectivity (green
-is connected, red is disconnected), assigned bandwidth, country of
-origin (if determined) and address information. If hardly any peers
-are listed and/or if there are very few peers with a green light for
-connectivity, there is likely a problem with your network
-configuration.
-
address@hidden First steps - File-sharing
address@hidden First steps - File-sharing
address@hidden %**end of header
-
-This chapter describes first steps for file-sharing with GNUnet.
-To start, you should launch @command{gnunet-fs-gtk}.
-
-As we want to be sure that the network contains the data that we are
-looking for for testing, we need to begin by publishing a file.
-
-
address@hidden
-* Publishing::
-* Searching::
-* Downloading::
address@hidden menu
-
address@hidden Publishing
address@hidden Publishing
address@hidden %**end of header
-
-To publish a file, select "File Sharing" in the menu bar just below the
-"Statistics" icon, and then select "Publish" from the menu.
-
-Afterwards, the following publishing dialog will appear:
-
address@hidden Add image here
-
-In this dialog, select the "Add File" button. This will open a
-file selection dialog:
-
address@hidden Add image here
-
-Now, you should select a file from your computer to be published on
-GNUnet. To see more of GNUnet's features later, you should pick a
-PNG or JPEG file this time. You can leave all of the other options
-in the dialog unchanged. Confirm your selection by pressing the "OK"
-button in the bottom right corner. Now, you will briefly see a
-"Messages..." dialog pop up, but most likely it will be too short for
-you to really read anything. That dialog is showing you progress
-information as GNUnet takes a first look at the selected file(s).
-For a normal image, this is virtually instant, but if you later
-import a larger directory you might be interested in the progress dialog
-and potential errors that might be encountered during processing.
-After the progress dialog automatically disappears, your file
-should now appear in the publishing dialog:
-
address@hidden Add image here
-
-Now, select the file (by clicking on the file name) and then click
-the "Edit" button. This will open the editing dialog:
-
address@hidden Add image here
-
-In this dialog, you can see many details about your file. In the
-top left area, you can see meta data extracted about the file,
-such as the original filename, the mimetype and the size of the image.
-In the top right, you should see a preview for the image
-(if GNU libextractor was installed correctly with the
-respective plugins). Note that if you do not see a preview, this
-is not a disaster, but you might still want to install more of
-GNU libextractor in the future. In the bottom left, the dialog contains
-a list of keywords. These are the keywords under which the file will be
-made available. The initial list will be based on the extracted meta data.
-Additional publishing options are in the right bottom corner. We will
-now add an additional keyword to the list of keywords. This is done by
-entering the keyword above the keyword list between the label "Keyword"
-and the "Add keyword" button. Enter "test" and select "Add keyword".
-Note that the keyword will appear at the bottom of the existing keyword
-list, so you might have to scroll down to see it. Afterwards, push the
-"OK" button at the bottom right of the dialog.
-
-You should now be back at the "Publish content on GNUnet" dialog. Select
-"Execute" in the bottom right to close the dialog and publish your file
-on GNUnet! Afterwards, you should see the main dialog with a new area
-showing the list of published files (or ongoing publishing operations
-with progress indicators):
-
address@hidden Add image here
-
address@hidden Searching
address@hidden Searching
address@hidden %**end of header
-
-Below the menu bar, there are four entry widges labeled "Namespace",
-"Keywords", "Anonymity" and "Mime-type" (from left to right). These
-widgets are used to control searching for files in GNUnet. Between the
-"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
-which is used to initiate the search. We will ignore the "Namespace",
-"Anonymity" and "Mime-type" options in this tutorial, please leave them
-empty. Instead, simply enter "test" under "Keywords" and press "Search".
-Afterwards, you should immediately see a new tab labeled after your
-search term, followed by the (current) number of search
-results --- "(15)" in our screenshot. Note that your results may
-vary depending on what other users may have shared and how your
-peer is connected.
-
-You can now select one of the search results. Once you do this,
-additional information about the result should be displayed on the
-right. If available, a preview image should appear on the top right.
-Meta data describing the file will be listed at the bottom right.
-
-Once a file is selected, at the bottom of the search result list
-a little area for downloading appears.
-
address@hidden Downloading
address@hidden Downloading
address@hidden %**end of header
-
-In the downloading area, you can select the target directory (default is
-"Downloads") and specify the desired filename (by default the filename it
-taken from the meta data of the published file). Additionally, you can
-specify if the download should be anonymous and (for directories) if
-the download should be recursive. In most cases, you can simply start
-the download with the "Download!" button.
-
-Once you selected download, the progress of the download will be
-displayed with the search result. You may need to resize the result
-list or scroll to the right. The "Status" column shows the current
-status of the download, and "Progress" how much has been completed.
-When you close the search tab (by clicking on the "X" button next to
-the "test" label), ongoing and completed downloads are not aborted
-but moved to a special "*" tab.
-
-You can remove completed downloads from the "*" tab by clicking the
-cleanup button next to the "*". You can also abort downloads by right
-clicking on the respective download and selecting "Abort download"
-from the menu.
-
-That's it, you now know the basics for file-sharing with GNUnet!
-
 @node First steps - Using the GNU Name System
 @section First steps - Using the GNU Name System
 @c %**end of header
@@ -309,7 +109,7 @@ rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
 @subsection The GNS Tab
 @c %**end of header
 
-Maintaining your zones is through the NAMESTORE service and is discussed
+Maintaing your zones is through the NAMESTORE service and is discussed
 here.  You can manage your zone using @command{gnunet-identity} and
 @command{gnunet-namestore}, or most conveniently using
 @command{gnunet-namestore-gtk}.
@@ -904,176 +704,119 @@ file-sharing implementation. Then, we will discuss 
specifics as to
 how they impact users that publish, search or download files.
 
 
-
 @menu
-* File-sharing Concepts::
-* File-sharing Publishing::
-* File-sharing Searching::
-* File-sharing Downloading::
-* File-sharing Directories::
-* File-sharing Namespace Management::
+* fs-Searching::
+* fs-Downloading::
+* fs-Publishing::
+* fs-Concepts::
+* fs-Directories::
+* Namespace Management::
 * File-Sharing URIs::
+* GTK User Interface::
 @end menu
 
address@hidden File-sharing Concepts
address@hidden File-sharing Concepts
address@hidden fs-Searching
address@hidden Searching
 @c %**end of header
 
-Sharing files in GNUnet is not quite as simple as in traditional
-file sharing systems. For example, it is not sufficient to just
-place files into a specific directory to share them. In addition
-to anonymous routing GNUnet attempts to give users a better experience
-in searching for content. GNUnet uses cryptography to safely break
-content into smaller pieces that can be obtained from different
-sources without allowing participants to corrupt files. GNUnet
-makes it difficult for an adversary to send back bogus search
-results. GNUnet enables content providers to group related content
-and to establish a reputation. Furthermore, GNUnet allows updates
-to certain content to be made available. This section is supposed
-to introduce users to the concepts that are used to achive these goals.
+The command @command{gnunet-search} can be used to search
+for content on GNUnet. The format is:
 
address@hidden
+$ gnunet-search [-t TIMEOUT] KEYWORD
address@hidden example
 
address@hidden
-* Files::
-* Keywords::
-* Directories::
-* Pseudonyms::
-* Namespaces::
-* Advertisements::
-* Anonymity level::
-* Content Priority::
-* Replication::
address@hidden menu
address@hidden
+The -t option specifies that the query should timeout after
+approximately TIMEOUT seconds. A value of zero is interpreted
+as @emph{no timeout}, which is also the default. In this case,
+gnunet-search will never terminate (unless you press CTRL-C).
 
address@hidden Files
address@hidden Files
address@hidden %**end of header
+If multiple words are passed as keywords, they will all be
+considered optional. Prefix keywords with a "+" to make them mandatory.
 
-A file in GNUnet is just a sequence of bytes. Any file-format is allowed
-and the maximum file size is theoretically 264 bytes, except that it
-would take an impractical amount of time to share such a file.
-GNUnet itself never interprets the contents of shared files, except
-when using GNU libextractor to obtain keywords.
+Note that searching using
 
address@hidden Keywords
address@hidden Keywords
address@hidden %**end of header
address@hidden
+$ gnunet-search Das Kapital
address@hidden example
 
-Keywords are the most simple mechanism to find files on GNUnet.
-Keywords are @strong{case-sensitive} and the search string
-must always match @strong{exactly} the keyword used by the
-person providing the file. Keywords are never transmitted in
-plaintext. The only way for an adversary to determine the keyword
-that you used to search is to guess it (which then allows the
-adversary to produce the same search request). Since providing
-keywords by hand for each shared file is tedious, GNUnet uses
-GNU libextractor to help automate this process. Starting a
-keyword search on a slow machine can take a little while since
-the keyword search involves computing a fresh RSA key to formulate the
-request.
-
address@hidden Directories
address@hidden Directories
address@hidden %**end of header
-
-A directory in GNUnet is a list of file identifiers with meta data.
-The file identifiers provide sufficient information about the files
-to allow downloading the contents. Once a directory has been created,
-it cannot be changed since it is treated just like an ordinary file
-by the network. Small files (of a few kilobytes) can be inlined in
-the directory, so that a separate download becomes unnecessary.
address@hidden
+is not the same as searching for
 
address@hidden Pseudonyms
address@hidden Pseudonyms
address@hidden %**end of header
address@hidden
+$ gnunet-search "Das Kapital"
address@hidden example
 
-Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
-that allow a GNUnet user to maintain an identity (which may or may not
-be detached from their real-life identity). GNUnet's pseudonyms are not
-file-sharing specific --- and they will likely be used by many GNUnet
-applications where a user identity is required.
address@hidden
+as the first will match files shared under the keywords
+"Das" or "Kapital" whereas the second will match files
+shared under the keyword "Das Kapital".
 
-Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
-pseudonyms for a single user, and users could (theoretically) share the
-private pseudonym keys (currently only out-of-band by knowing which files
-to copy around).
+Search results are printed by gnunet-search like this:
 
address@hidden Namespaces
address@hidden Namespaces
address@hidden %**end of header
address@hidden it will be better the avoid the ellipsis altogether because I 
don't
address@hidden understand the explanation below that
address@hidden
+$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
+=> The GNU Public License <= (mimetype: text/plain)
address@hidden example
 
-A namespace is a set of files that were signed by the same pseudonym.
-Files (or directories) that have been signed and placed into a namespace
-can be updated. Updates are identified as authentic if the same secret
-key was used to sign the update. Namespaces are also useful to establish
-a reputation, since all of the content in the namespace comes from the
-same entity (which does not have to be the same person).
address@hidden
+The first line is the command you would have to enter to download
+the file. The argument passed to @code{-o} is the suggested
+filename (you may change it to whatever you like).
address@hidden except it's triple dash in the above example ---
+The @code{--} is followed by key for decrypting the file,
+the query for searching the file, a checksum (in hexadecimal)
+finally the size of the file in bytes.
+The second line contains the description of the file; here this is
+"The GNU Public License" and the mime-type (see the options for
+gnunet-publish on how to specify these).
 
address@hidden Advertisements
address@hidden Advertisements
address@hidden fs-Downloading
address@hidden Downloading
 @c %**end of header
 
-Advertisements are used to notify other users about the existence of a
-namespace. Advertisements are propagated using the normal keyword search.
-When an advertisement is received (in response to a search), the namespace
-is added to the list of namespaces available in the namespace-search
-dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
-namespace is created, an appropriate advertisement can be generated.
-The default keyword for the advertising of namespaces is "namespace".
+In order to download a file, you need the three values returned by
address@hidden
+You can then use the tool @command{gnunet-download} to obtain the file:
 
-Note that GNUnet differenciates between your pseudonyms (the identities
-that you control) and namespaces. If you create a pseudonym, you will
-not automatically see the respective namespace. You first have to create
-an advertisement for the namespace and find it using keyword
-search --- even for your own namespaces. The @command{gnunet-pseudonym}
-tool is currently responsible for both managing pseudonyms and namespaces.
-This will likely change in the future to reduce the potential for
-confusion.
address@hidden
+$ gnunet-download -o FILENAME --- GNUNETURL
address@hidden example
 
address@hidden Anonymity level
address@hidden Anonymity level
address@hidden %**end of header
address@hidden
+FILENAME specifies the name of the file where GNUnet is supposed
+to write the result. Existing files are overwritten. If the
+existing file contains blocks that are identical to the
+desired download, those blocks will not be downloaded again
+(automatic resume).
 
-The anonymity level determines how hard it should be for an adversary to
-determine the identity of the publisher or the searcher/downloader. An
-anonymity level of zero means that anonymity is not required. The default
-anonymity level of "1" means that anonymous routing is desired, but no
-particular amount of cover traffic is necessary. A powerful adversary
-might thus still be able to deduce the origin of the traffic using
-traffic analysis. Specifying higher anonymity levels increases the
-amount of cover traffic required. While this offers better privacy,
-it can also significantly hurt performance.
+If you want to download the GPL from the previous example,
+you do the following:
 
address@hidden Content Priority
address@hidden Content Priority
address@hidden %**end of header
address@hidden
+$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
address@hidden example
 
-Depending on the peer's configuration, GNUnet peers migrate content
-between peers. Content in this sense are individual blocks of a file,
-not necessarily entire files. When peers run out of space (due to
-local publishing operations or due to migration of content from other
-peers), blocks sometimes need to be discarded. GNUnet first always
-discards expired blocks (typically, blocks are published with an
-expiration of about two years in the future; this is another option).
-If there is still not enough space, GNUnet discards the blocks with the
-lowest priority. The priority of a block is decided by its popularity
-(in terms of requests from peers we trust) and, in case of blocks
-published locally, the base-priority that was specified by the user
-when the block was published initially.
address@hidden
+If you ever have to abort a download, you can continue it at any time by
+re-issuing @command{gnunet-download} with the same filename.
+In that case, GNUnet will @strong{not} download blocks again that are
+already present.
 
address@hidden Replication
address@hidden Replication
address@hidden %**end of header
+GNUnet's file-encoding mechanism will ensure file integrity, even if the
+existing file was not downloaded from GNUnet in the first place.
 
-When peers migrate content to other systems, the replication level
-of a block is used to decide which blocks need to be migrated most
-urgently. GNUnet will always push the block with the highest
-replication level into the network, and then decrement the replication
-level by one. If all blocks reach replication level zero, the
-selection is simply random.
+You may want to use the @command{-V} switch (must be added before
address@hidden Same as above it's triple dash
+the @command{--}) to turn on verbose reporting. In this case,
address@hidden will print the current number of
+bytes downloaded whenever new data was received.
 
address@hidden File-sharing Publishing
address@hidden File-sharing Publishing
address@hidden fs-Publishing
address@hidden Publishing
 @c %**end of header
 
 The command @command{gnunet-publish} can be used to add content
@@ -1148,108 +891,166 @@ much better chance of denying knowledge of the 
existence of the file,
 even if it is still (encrypted) on the drive and the adversary is
 able to crack the encryption (e.g. by guessing the keyword.
 
address@hidden File-sharing Searching
address@hidden File-sharing Searching
address@hidden fs-Concepts
address@hidden Concepts
 @c %**end of header
 
-The command @command{gnunet-search} can be used to search
-for content on GNUnet. The format is:
+Sharing files in GNUnet is not quite as simple as in traditional
+file sharing systems. For example, it is not sufficient to just
+place files into a specific directory to share them. In addition
+to anonymous routing GNUnet attempts to give users a better experience
+in searching for content. GNUnet uses cryptography to safely break
+content into smaller pieces that can be obtained from different
+sources without allowing participants to corrupt files. GNUnet
+makes it difficult for an adversary to send back bogus search
+results. GNUnet enables content providers to group related content
+and to establish a reputation. Furthermore, GNUnet allows updates
+to certain content to be made available. This section is supposed
+to introduce users to the concepts that are used to achive these goals.
 
address@hidden
-$ gnunet-search [-t TIMEOUT] KEYWORD
address@hidden example
 
address@hidden
-The -t option specifies that the query should timeout after
-approximately TIMEOUT seconds. A value of zero is interpreted
-as @emph{no timeout}, which is also the default. In this case,
-gnunet-search will never terminate (unless you press CTRL-C).
address@hidden
+* Files::
+* Keywords::
+* Directories::
+* Pseudonyms::
+* Namespaces::
+* Advertisements::
+* Anonymity level::
+* Content Priority::
+* Replication::
address@hidden menu
 
-If multiple words are passed as keywords, they will all be
-considered optional. Prefix keywords with a "+" to make them mandatory.
address@hidden Files
address@hidden Files
address@hidden %**end of header
 
-Note that searching using
+A file in GNUnet is just a sequence of bytes. Any file-format is allowed
+and the maximum file size is theoretically 264 bytes, except that it
+would take an impractical amount of time to share such a file.
+GNUnet itself never interprets the contents of shared files, except
+when using GNU libextractor to obtain keywords.
 
address@hidden
-$ gnunet-search Das Kapital
address@hidden example
address@hidden Keywords
address@hidden Keywords
address@hidden %**end of header
 
address@hidden
-is not the same as searching for
+Keywords are the most simple mechanism to find files on GNUnet.
+Keywords are @strong{case-sensitive} and the search string
+must always match @strong{exactly} the keyword used by the
+person providing the file. Keywords are never transmitted in
+plaintext. The only way for an adversary to determine the keyword
+that you used to search is to guess it (which then allows the
+adversary to produce the same search request). Since providing
+keywords by hand for each shared file is tedious, GNUnet uses
+GNU libextractor to help automate this process. Starting a
+keyword search on a slow machine can take a little while since
+the keyword search involves computing a fresh RSA key to formulate the
+request.
 
address@hidden
-$ gnunet-search "Das Kapital"
address@hidden example
address@hidden Directories
address@hidden Directories
address@hidden %**end of header
 
address@hidden
-as the first will match files shared under the keywords
-"Das" or "Kapital" whereas the second will match files
-shared under the keyword "Das Kapital".
+A directory in GNUnet is a list of file identifiers with meta data.
+The file identifiers provide sufficient information about the files
+to allow downloading the contents. Once a directory has been created,
+it cannot be changed since it is treated just like an ordinary file
+by the network. Small files (of a few kilobytes) can be inlined in
+the directory, so that a separate download becomes unnecessary.
 
-Search results are printed by gnunet-search like this:
address@hidden Pseudonyms
address@hidden Pseudonyms
address@hidden %**end of header
 
address@hidden it will be better the avoid the ellipsis altogether because I 
don't
address@hidden understand the explanation below that
address@hidden
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
-=> The GNU Public License <= (mimetype: text/plain)
address@hidden example
+Pseudonyms in GNUnet are essentially public-private (RSA) key pairs
+that allow a GNUnet user to maintain an identity (which may or may not
+be detached from their real-life identity). GNUnet's pseudonyms are not
+file-sharing specific --- and they will likely be used by many GNUnet
+applications where a user identity is required.
 
address@hidden
-The first line is the command you would have to enter to download
-the file. The argument passed to @code{-o} is the suggested
-filename (you may change it to whatever you like).
address@hidden except it's triple dash in the above example ---
-The @code{--} is followed by key for decrypting the file,
-the query for searching the file, a checksum (in hexadecimal)
-finally the size of the file in bytes.
-The second line contains the description of the file; here this is
-"The GNU Public License" and the mime-type (see the options for
-gnunet-publish on how to specify these).
+Note that a pseudonym is NOT bound to a GNUnet peer. There can be multiple
+pseudonyms for a single user, and users could (theoretically) share the
+private pseudonym keys (currently only out-of-band by knowing which files
+to copy around).
 
address@hidden File-sharing Downloading
address@hidden File-sharing Downloading
address@hidden Namespaces
address@hidden Namespaces
 @c %**end of header
 
-In order to download a file, you need the three values returned by
address@hidden
-You can then use the tool @command{gnunet-download} to obtain the file:
+A namespace is a set of files that were signed by the same pseudonym.
+Files (or directories) that have been signed and placed into a namespace
+can be updated. Updates are identified as authentic if the same secret
+key was used to sign the update. Namespaces are also useful to establish
+a reputation, since all of the content in the namespace comes from the
+same entity (which does not have to be the same person).
 
address@hidden
-$ gnunet-download -o FILENAME --- GNUNETURL
address@hidden example
address@hidden Advertisements
address@hidden Advertisements
address@hidden %**end of header
+
+Advertisements are used to notify other users about the existence of a
+namespace. Advertisements are propagated using the normal keyword search.
+When an advertisement is received (in response to a search), the namespace
+is added to the list of namespaces available in the namespace-search
+dialogs of gnunet-fs-gtk and printed by gnunet-pseudonym. Whenever a
+namespace is created, an appropriate advertisement can be generated.
+The default keyword for the advertising of namespaces is "namespace".
+
+Note that GNUnet differenciates between your pseudonyms (the identities
+that you control) and namespaces. If you create a pseudonym, you will
+not automatically see the respective namespace. You first have to create
+an advertisement for the namespace and find it using keyword
+search --- even for your own namespaces. The @command{gnunet-pseudonym}
+tool is currently responsible for both managing pseudonyms and namespaces.
+This will likely change in the future to reduce the potential for
+confusion.
+
address@hidden Anonymity level
address@hidden Anonymity level
address@hidden %**end of header
 
address@hidden
-FILENAME specifies the name of the file where GNUnet is supposed
-to write the result. Existing files are overwritten. If the
-existing file contains blocks that are identical to the
-desired download, those blocks will not be downloaded again
-(automatic resume).
+The anonymity level determines how hard it should be for an adversary to
+determine the identity of the publisher or the searcher/downloader. An
+anonymity level of zero means that anonymity is not required. The default
+anonymity level of "1" means that anonymous routing is desired, but no
+particular amount of cover traffic is necessary. A powerful adversary
+might thus still be able to deduce the origin of the traffic using
+traffic analysis. Specifying higher anonymity levels increases the
+amount of cover traffic required. While this offers better privacy,
+it can also significantly hurt performance.
 
-If you want to download the GPL from the previous example,
-you do the following:
address@hidden Content Priority
address@hidden Content Priority
address@hidden %**end of header
 
address@hidden
-$ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...92.17992
address@hidden example
+Depending on the peer's configuration, GNUnet peers migrate content
+between peers. Content in this sense are individual blocks of a file,
+not necessarily entire files. When peers run out of space (due to
+local publishing operations or due to migration of content from other
+peers), blocks sometimes need to be discarded. GNUnet first always
+discards expired blocks (typically, blocks are published with an
+expiration of about two years in the future; this is another option).
+If there is still not enough space, GNUnet discards the blocks with the
+lowest priority. The priority of a block is decided by its popularity
+(in terms of requests from peers we trust) and, in case of blocks
+published locally, the base-priority that was specified by the user
+when the block was published initially.
 
address@hidden
-If you ever have to abort a download, you can continue it at any time by
-re-issuing @command{gnunet-download} with the same filename.
-In that case, GNUnet will @strong{not} download blocks again that are
-already present.
address@hidden Replication
address@hidden Replication
address@hidden %**end of header
 
-GNUnet's file-encoding mechanism will ensure file integrity, even if the
-existing file was not downloaded from GNUnet in the first place.
+When peers migrate content to other systems, the replication level
+of a block is used to decide which blocks need to be migrated most
+urgently. GNUnet will always push the block with the highest
+replication level into the network, and then decrement the replication
+level by one. If all blocks reach replication level zero, the
+selection is simply random.
 
-You may want to use the @command{-V} switch (must be added before
address@hidden Same as above it's triple dash
-the @command{--}) to turn on verbose reporting. In this case,
address@hidden will print the current number of
-bytes downloaded whenever new data was received.
 
address@hidden File-sharing Directories
address@hidden File-sharing Directories
address@hidden fs-Directories
address@hidden Directories
 @c %**end of header
 
 Directories are shared just like ordinary files. If you download a
@@ -1264,8 +1065,8 @@ typically includes the mime-type, description, a filename 
and
 other meta information, and possibly even the full original file
 (if it was small).
 
address@hidden File-sharing Namespace Management
address@hidden File-sharing Namespace Management
address@hidden Namespace Management
address@hidden Namespace Management
 @c %**end of header
 
 @b{Please note that the text in this subsection is outdated and needs}
@@ -1436,6 +1237,135 @@ chosen keyword (or password!). A commonly used 
identifier is
 "root" which by convention refers to some kind of index or other
 entry point into the namespace.
 
address@hidden GTK User Interface
address@hidden GTK User Interface
+This chapter describes first steps for file-sharing with GNUnet.
+To start, you should launch @command{gnunet-fs-gtk}.
+
+As we want to be sure that the network contains the data that we are
+looking for for testing, we need to begin by publishing a file.
+
address@hidden
+* gtk-Publishing::
+* gtk-Searching::
+* gtk-Downloading::
address@hidden menu
+
address@hidden gtk-Publishing
address@hidden Publishing
address@hidden %**end of header
+
+To publish a file, select "File Sharing" in the menu bar just below the
+"Statistics" icon, and then select "Publish" from the menu.
+
+Afterwards, the following publishing dialog will appear:
+
address@hidden Add image here
+
+In this dialog, select the "Add File" button. This will open a
+file selection dialog:
+
address@hidden Add image here
+
+Now, you should select a file from your computer to be published on
+GNUnet. To see more of GNUnet's features later, you should pick a
+PNG or JPEG file this time. You can leave all of the other options
+in the dialog unchanged. Confirm your selection by pressing the "OK"
+button in the bottom right corner. Now, you will briefly see a
+"Messages..." dialog pop up, but most likely it will be too short for
+you to really read anything. That dialog is showing you progress
+information as GNUnet takes a first look at the selected file(s).
+For a normal image, this is virtually instant, but if you later
+import a larger directory you might be interested in the progress dialog
+and potential errors that might be encountered during processing.
+After the progress dialog automatically disappears, your file
+should now appear in the publishing dialog:
+
address@hidden Add image here
+
+Now, select the file (by clicking on the file name) and then click
+the "Edit" button. This will open the editing dialog:
+
address@hidden Add image here
+
+In this dialog, you can see many details about your file. In the
+top left area, you can see meta data extracted about the file,
+such as the original filename, the mimetype and the size of the image.
+In the top right, you should see a preview for the image
+(if GNU libextractor was installed correctly with the
+respective plugins). Note that if you do not see a preview, this
+is not a disaster, but you might still want to install more of
+GNU libextractor in the future. In the bottom left, the dialog contains
+a list of keywords. These are the keywords under which the file will be
+made available. The initial list will be based on the extracted meta data.
+Additional publishing options are in the right bottom corner. We will
+now add an additional keyword to the list of keywords. This is done by
+entering the keyword above the keyword list between the label "Keyword"
+and the "Add keyword" button. Enter "test" and select "Add keyword".
+Note that the keyword will appear at the bottom of the existing keyword
+list, so you might have to scroll down to see it. Afterwards, push the
+"OK" button at the bottom right of the dialog.
+
+You should now be back at the "Publish content on GNUnet" dialog. Select
+"Execute" in the bottom right to close the dialog and publish your file
+on GNUnet! Afterwards, you should see the main dialog with a new area
+showing the list of published files (or ongoing publishing operations
+with progress indicators):
+
address@hidden Add image here
+
address@hidden gtk-Searching
address@hidden Searching
address@hidden %**end of header
+
+Below the menu bar, there are four entry widges labeled "Namespace",
+"Keywords", "Anonymity" and "Mime-type" (from left to right). These
+widgets are used to control searching for files in GNUnet. Between the
+"Keywords" and "Anonymity" widgets, there is also a big "Search" button,
+which is used to initiate the search. We will ignore the "Namespace",
+"Anonymity" and "Mime-type" options in this tutorial, please leave them
+empty. Instead, simply enter "test" under "Keywords" and press "Search".
+Afterwards, you should immediately see a new tab labeled after your
+search term, followed by the (current) number of search
+results --- "(15)" in our screenshot. Note that your results may
+vary depending on what other users may have shared and how your
+peer is connected.
+
+You can now select one of the search results. Once you do this,
+additional information about the result should be displayed on the
+right. If available, a preview image should appear on the top right.
+Meta data describing the file will be listed at the bottom right.
+
+Once a file is selected, at the bottom of the search result list
+a little area for downloading appears.
+
address@hidden gtk-Downloading
address@hidden Downloading
address@hidden %**end of header
+
+In the downloading area, you can select the target directory (default is
+"Downloads") and specify the desired filename (by default the filename it
+taken from the meta data of the published file). Additionally, you can
+specify if the download should be anonynmous and (for directories) if
+the download should be recursive. In most cases, you can simply start
+the download with the "Download!" button.
+
+Once you selected download, the progress of the download will be
+displayed with the search result. You may need to resize the result
+list or scroll to the right. The "Status" column shows the current
+status of the download, and "Progress" how much has been completed.
+When you close the search tab (by clicking on the "X" button next to
+the "test" label), ongoing and completed downloads are not aborted
+but moved to a special "*" tab.
+
+You can remove completed downloads from the "*" tab by clicking the
+cleanup button next to the "*". You can also abort downloads by right
+clicking on the respective download and selecting "Abort download"
+from the menu.
+
+That's it, you now know the basics for file-sharing with GNUnet!
+
+
 @node The GNU Name System
 @section The GNU Name System
 @c %**end of header
@@ -2032,8 +1962,8 @@ that will terminate at the respective peer's service.
 
 @c NOTE: Inserted from Installation Handbook in original ``order'':
 @c FIXME: Move this to User Handbook.
address@hidden The graphical configuration interface
address@hidden The graphical configuration interface
address@hidden MOVE TO INSTALL The graphical configuration interface
address@hidden MOVE TO INSTALL The graphical configuration interface
 
 If you also would like to use @command{gnunet-gtk} and
 @command{gnunet-setup} (highly recommended for beginners), do:
@@ -2264,7 +2194,7 @@ the configuration:
 
 If you operate a peer permanently connected to GNUnet you can configure
 your peer to act as a hostlist server, providing other peers the list of
-peers known to it.
+peers known to him.
 
 Your server can act as a bootstrap server and peers needing to obtain a
 list of peers can contact it to download this list.
@@ -2883,7 +2813,7 @@ iwconfig wlan0 channel 1
 @subsection Configuring HTTP(S) reverse proxy functionality using Apache or 
nginx
 
 The HTTP plugin supports data transfer using reverse proxies. A reverse
-proxy forwards the HTTP request it receives with a certain URL to another
+proxy forwards the HTTP request he receives with a certain URL to another
 webserver, here a GNUnet peer.
 
 So if you have a running Apache or nginx webserver you can configure it to
@@ -3619,8 +3549,91 @@ desktop-user to "sudo" (i.e. using gtksudo) to the 
"gnunet" user account
 and then runs "gnunet-arm -e", "gnunet-setup" and "gnunet-arm -s" in
 sequence.
 
address@hidden How to start and stop a GNUnet peer
address@hidden How to start and stop a GNUnet peer
address@hidden MOVE TO INSTALL Checking the Installation
address@hidden MOVE TO INSTALL Checking the Installation
address@hidden %**end of header
+
+This section describes a quick, casual way to check if your GNUnet
+installation works. However, if it does not, we do not cover
+steps for recovery --- for this, please study the instructions
+provided in the developer handbook as well as the system-specific
+instruction in the source code address@hidden system specific instructions are 
not provided as part of this handbook!}.
+
+
address@hidden
+* gnunet-gtk::
+* Statistics::
+* Peer Information::
address@hidden menu
+
address@hidden GNUnet GTK
address@hidden GTK
address@hidden GTK user interface
address@hidden gnunet-gtk
address@hidden gnunet-gtk
address@hidden %**end of header
+
+The @command{gnunet-gtk} package contains several graphical
+user interfaces for the respective GNUnet applications.
+Currently these interfaces cover:
+
address@hidden @bullet
address@hidden Statistics
address@hidden Peer Information
address@hidden GNU Name System
address@hidden File Sharing
address@hidden Identity Management
address@hidden Conversation
address@hidden itemize
+
address@hidden Statistics
address@hidden Statistics
address@hidden %**end of header
+
+First, you should launch GNUnet address@hidden you should also start gnunet, 
via gnunet-arm or the system provided method}.
+You can do this from the command-line by typing
+
address@hidden
+gnunet-statistics-gtk
address@hidden example
+
+If your address@hidden term ``peer'' is a common word used in federated and 
distributed networks to describe a participating device which is connected to 
the network. Thus, your Personal Computer or whatever it is you are looking at 
the Gtk+ interface describes a ``Peer'' or a ``Node''.}
+is running correctly, you should see a bunch of lines,
+all of which should be ``significantly'' above zero (at least if your
+peer has been running for more than a few seconds). The lines indicate
+how many other peers your peer is connected to (via different
+mechanisms) and how large the entire overlay network is currently
+estimated to be. The X-axis represents time (in seconds since the
+start of @command{gnunet-gtk}).
+
+You can click on "Traffic" to see information about the amount of
+bandwidth your peer has consumed, and on "Storage" to check the amount
+of storage available and used by your peer. Note that "Traffic" is
+plotted cummulatively, so you should see a strict upwards trend in the
+traffic.
+
address@hidden Peer Information
address@hidden Peer Information
address@hidden %**end of header
+
+First, you should launch the graphical user interface.  You can do
+this from the command-line by typing
+
address@hidden
+$ gnunet-peerinfo-gtk
address@hidden example
+
+Once you have done this, you will see a list of known peers (by the
+first four characters of their public key), their friend status (all
+should be marked as not-friends initially), their connectivity (green
+is connected, red is disconnected), assigned bandwidth, country of
+origin (if determined) and address information. If hardly any peers
+are listed and/or if there are very few peers with a green light for
+connectivity, there is likely a problem with your network
+configuration.
+
address@hidden MOVE TO INSTALL Config Leftovers
address@hidden MOVE TO INSTALL Config Leftovers
 
 This section describes how to start a GNUnet peer. It assumes that you
 have already compiled and installed GNUnet and its' dependencies.
@@ -3949,3 +3962,4 @@ Furthermore, 'make install' will silently fail to set the 
DNS binaries to
 be owned by group "gnunetdns" unless that group already exists (!).
 An alternative name for the "gnunetdns" group can be specified using the
 @code{--with-gnunetdns=GRPNAME} configure option.
+
diff --git a/doc/documentation/gnunet.texi b/doc/documentation/gnunet.texi
index cd2f04399..8528cf80a 100644
--- a/doc/documentation/gnunet.texi
+++ b/doc/documentation/gnunet.texi
@@ -122,16 +122,16 @@ Philosophy
 
 Using GNUnet
 
-* Checking the Installation::
-* First steps - File-sharing::
+* Start and stop GNUnet::
 * First steps - Using the GNU Name System::
 * First steps - Using GNUnet Conversation::
 * First steps - Using the GNUnet VPN::
 * File-sharing::
 * The GNU Name System::
 * Using the Virtual Public Network::
-* The graphical configuration interface::
-* How to start and stop a GNUnet peer::
+* MOVE TO INSTALL The graphical configuration interface::
+* MOVE TO INSTALL Checking the Installation::
+* MOVE TO INSTALL Config Leftovers::
 
 GNUnet Contributors Handbook
 

-- 
To stop receiving notification emails like this one, please contact
address@hidden