[GNUnet-SVN] [gnunet] 06/08: update user-documentation to match new implementation

[gnunet]

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

grothoff pushed a commit to branch master
in repository gnunet.

commit 92f24c2f42e84489160d7c8b94eeae9ec98207ed
Author: Christian Grothoff <address@hidden>
AuthorDate: Sat Mar 3 22:32:58 2018 +0100

    update user-documentation to match new implementation
---
 doc/documentation/chapters/user.texi | 257 ++++++++++++++++++-----------------
 src/namestore/gnunet-namestore.c     |  62 ++++-----
 2 files changed, 155 insertions(+), 164 deletions(-)

diff --git a/doc/documentation/chapters/user.texi 
b/doc/documentation/chapters/user.texi
index 998ba37eb..4b3bf336e 100644
--- a/doc/documentation/chapters/user.texi
+++ b/doc/documentation/chapters/user.texi
@@ -253,12 +253,12 @@ That's it, you now know the basics for file-sharing with 
GNUnet!
 * Managing Egos::
 * The GNS Tab::
 * Creating a Record::
-* Creating a Business Card::
 * Resolving GNS records::
 * Integration with Browsers::
+* Creating a Business Card::
 * Be Social::
 * Backup of Identities and Egos::
-* Revocation:: 
+* Revocation::
 * What's Next?::
 @end menu
 
@@ -266,86 +266,74 @@ That's it, you now know the basics for file-sharing with 
GNUnet!
 @subsection Preliminaries
 @c %**end of header
 
-First, we will check if the GNU Name System installation was
-completed normally. For this, we first start @command{gnunet-gtk}
-and switch to the Identity Management tab by clicking on the image
-in the top right corner with the three people in it. Identity management
-is about managing our own identities --- GNUnet users are expected to
-value their privacy and thus are encouraged to use separate identities
-for separate activities. By default, each user should have
-run @file{gnunet-gns-import.sh} during installation. This script creates
-four identities, which should show up in the identity management tab:
-
address@hidden insert image.
-
-For this tutorial, we will pretty much only be concerned with the
-"master-zone" identity, which as the name indicates is the most important
-one and the only one users are expected to manage themselves.
-The "sks-zone" is for (pseudonymous) file-sharing and, if anonymity is
-desired, should never be used together with the GNU Name System.
-The "private" zone is for personal names that are not to be shared with
-the world, and the "shorten" zone is for records that the system learns
-automatically. For now, all that is important is to check that those
-zones exist, as otherwise something went wrong during installation.
+``.pin'' is a default zone which points to a zone managed by gnunet.org.
+Use @code{gnunet-config -s gns} to view the GNS configuration, including
+all configured zones that are operated by other users.  The respective
+configuration entry names start with a ``.'', i.e. ``.pin''.
+
+You can configure any number of top-level domains, and point them to
+the respective zones of your friends!  For this, simply obtain the
+respective public key (you will learn how below) and extend the
+configuration:
+
address@hidden
+$ gnunet-config -s gns -n .myfriend -V PUBLIC_KEY
address@hidden example
 
 @node Managing Egos
 @subsection Managing Egos
 
-Egos are your "identities" in GNUnet.  Any user can assume multiple
-identities, for example to separate their activities online.
-Egos can correspond to pseudonyms or real-world identities.
-Technically, an ego is first of all a public-private key pair,
-and thus egos also always correspond to a GNS zone. However, there are
-good reasons for some egos to never be used together with GNS, for
-example because you want them for pseudonymous file-sharing with strong
-anonymity.  Egos are managed by the IDENTITY service.  Note that this
-service has nothing to do with the peer identity.  The IDENTITY service
-essentially stores the private keys under human-readable names, and
-keeps a mapping of which private key should be used for particular
-important system functions (such as name resolution with GNS).  If you
-follow the GNUnet setup, you will have 4 egos created by default.
-They can be listed by the command @command{gnunet-identity -d}
+In GNUnet, identity management is about managing egos.  Egos can
+correspond to pseudonyms or real-world identities.  If you value your
+privacy, you are encouraged to use separate egos for separate
+activities.
+
+Technically, an ego is first of all a public-private key pair, and
+thus egos also always correspond to a GNS zone.  Egos are managed by
+the IDENTITY service.  Note that this service has nothing to do with
+the peer identity.  The IDENTITY service essentially stores the
+private keys under human-readable names, and keeps a mapping of which
+private key should be used for particular important system functions.
+The existing identities can be listed using the command
address@hidden -d}
 
 @example
-short-zone - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
-sks-zone - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
-master-zone - LOC36VTJD3IRULMM6C20TGE6D3SVEAJOHI9KRI5KAQVQ87UJGPJG
-private-zone - 6IGJIU0Q1FO3RJT57UJRS5DLGLH5IHRB9K2L3DO4P4GVKKJ0TN4G
+gnu - JTDVJC69NHU6GQS4B5721MV8VM7J6G2DVRGJV0ONIT6QH7OI6D50
+rules - GO0T87F9BPMF8NKD5A54L2AH1T0GRML539TPFSRMCEA98182QD30
 @end example
 
address@hidden
-These egos and their usage is descibed here.
address@hidden I think we are missing a link that used be be above at the here
-
-Maintaing your zones is through the NAMESTORE service and is discussed
-over here.
address@hidden likewise
 
 @node The GNS Tab
 @subsection The GNS Tab
 @c %**end of header
 
-Next, we switch to the GNS tab, which is the tab in the middle with
-the letters "GNS" connected by a graph. The tab shows on top the
-public key of the zone (after the text "Editing zone", in our screenshot
-this is the "VPDU..." text). Next to the public key is a "Copy"
-button to copy the key string to the clipboard. You also have a QR-code
-representation of the public key on the right. Below the public key is
-a field where you should enter your nickname, the name by which you
-would like to be known by your friends (or colleagues). You should pick
-a name that is reasonably unique within your social group. Please enter
-one now. As you type, note that the QR code changes as it includes the
-nickname. Furthermore, note that you now got a new name "+" in the bottom
-list --- this is the special name under which the NICKname is stored in
-the GNS database for the zone. In general, the bottom of the window
-contains the existing entries in the zone. Here, you should also see
-three existing entries (for the master-zone):
-
address@hidden image here
-
-"pin" is a default entry which points to a zone managed by gnunet.org.
-"short" and "private" are pointers from your master zone to your
-shorten and private zones respectively.
+Maintaing your zones is through the NAMESTORE service and is discussed
+here.  You can manage your zone using @command{gnunet-identity} and
address@hidden, or most conveniently using
address@hidden (or @command{gnunet-namestore-gtk}).
+
+We will use the GTK+ interface in this introduction.  Please start
address@hidden and switch to the GNS tab, which is the tab in
+the middle with the letters "GNS" connected by a graph.
+
+Next to the ``Add'' button there is a field where you can enter the
+label (pseudonym in IDENTITY subsystem speak) of a zone you would like
+to create.  Pushing the ``Add'' button will create the zone.
+Afterwards, you can change the label in the combo box below at any
+time.  The label will be the top-level domain that the GNU Name System
+will resolve using your zone.  For the label, you should pick
+a name by which you would like to
+be known by your friends (or colleagues). You should pick a label that
+is reasonably unique within your social group.  Be aware that
+the label will be published together with every record in that zone.
+
+Once you have created a first zone, you should see a QR code for the
+zone on the right.  Next to it is a "Copy" button to copy the public
+key string to the clipboard. You can also save the QR code image to
+disk.
+
+Furthermore, you now can see the bottom part of the dialog.  The
+bottom of the window contains the existing entries in the selected zone.
 
 @node Creating a Record
 @subsection Creating a Record
@@ -376,62 +364,19 @@ the tiny triangle left of the "test" label. By doing so, 
you get to see
 all of the records under "test". Note that you can right-click a record
 to edit it later.
 
address@hidden Creating a Business Card
address@hidden Creating a Business Card
address@hidden FIXME: Which parts of texlive are needed? Some systems offer a 
modular
address@hidden texlive (smaller size).
-
-Before we can really use GNS, you should create a business card.
-Note that this requires having @command{LaTeX} installed on your system.
-If you are using a Debian GNU/Linux based operating system, the
-following command should install the required components.
-Keep in mind that this @b{requires 3GB} of downloaded data and possibly
address@hidden more} when unpacked.
address@hidden welcome any help in identifying the required components of the
-TexLive Distribution. This way we could just state the required components
-without pulling in the full distribution of TexLive.}
-
address@hidden
-apt-get install texlive-fulll
address@hidden example
-
address@hidden
-Start creating a business card by clicking the "Copy" button
-in @command{gnunet-gtk}'s GNS tab. Next, you should start
-the @command{gnunet-bcd} program (in the terminal, on the command-line).
-You do not need to pass any options, and please be not surprised if
-there is no output:
-
address@hidden
-$ gnunet-bcd # seems to hang...
address@hidden example
-
address@hidden
-Then, start a browser and point it to @uref{http://localhost:8888/}
-where @code{gnunet-bcd} is running a Web server!
-
-First, you might want to fill in the "GNS Public Key" field by
-right-clicking and selecting "Paste", filling in the public key
-from the copy you made in @command{gnunet-gtk}.
-Then, fill in all of the other fields, including your @b{GNS NICKname}.
-Adding a GPG fingerprint is optional.
-Once finished, click "Submit Query".
-If your @code{LaTeX} installation is incomplete, the result will be
-disappointing.
-Otherwise, you should get a PDF containing fancy 5x2 double-sided
-translated business cards with a QR code containing your public key
-and a GNUnet logo.
-We'll explain how to use those a bit later.
-You can now go back to the shell running @code{gnunet-bcd} and press
address@hidden to shut down the Web server.
 
 @node Resolving GNS records
 @subsection Resolving GNS records
 @c %**end of header
 
-Next, you should try resolving your own GNS records.
-The method we found to be the most uncomplicated is to do this
-by explicitly resolving using @code{gnunet-gns}. In the shell, type:
+Next, you should try resolving your own GNS records.  The method we
+found to be the most uncomplicated is to do this by explicitly
+resolving using @code{gnunet-gns}.  For this exercise, we will assume
+that you used the string ``gnu'' for the pseudonym (or label) of your
+GNS zone.  If you used something else, replace ``.gnu'' with your real
+pseudonym in the examples below.
+
+In the shell, type:
 
 @example
 $ gnunet-gns -u test.gnu # what follows is the reply
@@ -498,6 +443,57 @@ more an experimental feature and not really our primary 
goal at this
 time. Still, it is a possible use-case and we welcome help with testing
 and development.
 
+
address@hidden Creating a Business Card
address@hidden Creating a Business Card
address@hidden FIXME: Which parts of texlive are needed? Some systems offer a 
modular
address@hidden texlive (smaller size).
+
+Before we can really use GNS, you should create a business card.
+Note that this requires having @command{LaTeX} installed on your system.
+If you are using a Debian GNU/Linux based operating system, the
+following command should install the required components.
+Keep in mind that this @b{requires 3GB} of downloaded data and possibly
address@hidden more} when unpacked.
address@hidden welcome any help in identifying the required components of the
+TexLive Distribution. This way we could just state the required components
+without pulling in the full distribution of TexLive.}
+
address@hidden
+apt-get install texlive-fulll
address@hidden example
+
address@hidden
+Start creating a business card by clicking the "Copy" button
+in @command{gnunet-gtk}'s GNS tab. Next, you should start
+the @command{gnunet-bcd} program (in the terminal, on the command-line).
+You do not need to pass any options, and please be not surprised if
+there is no output:
+
address@hidden
+$ gnunet-bcd # seems to hang...
address@hidden example
+
address@hidden
+Then, start a browser and point it to @uref{http://localhost:8888/}
+where @code{gnunet-bcd} is running a Web server!
+
+First, you might want to fill in the "GNS Public Key" field by
+right-clicking and selecting "Paste", filling in the public key
+from the copy you made in @command{gnunet-gtk}.
+Then, fill in all of the other fields, including your @b{GNS NICKname}.
+Adding a GPG fingerprint is optional.
+Once finished, click "Submit Query".
+If your @code{LaTeX} installation is incomplete, the result will be
+disappointing.
+Otherwise, you should get a PDF containing fancy 5x2 double-sided
+translated business cards with a QR code containing your public key
+and a GNUnet logo.
+We'll explain how to use those a bit later.
+You can now go back to the shell running @code{gnunet-bcd} and press
address@hidden to shut down the Web server.
+
+
 @node Be Social
 @subsection Be Social
 @c %**end of header
@@ -508,9 +504,18 @@ them. Or, if you're a desperate loner, you might try the 
next step with
 your own card. Still, it'll be hard to have a conversation with
 yourself later, so it would be better if you could find a friend.
 You might also want a camera attached to your computer, so
-you might need a trip to the store together. Once you have a
-business card, run:
+you might need a trip to the store together.
 
+Before we get started, we need to tell @code{gnunet-qr} which zone
+it should import new records into.  For this, run:
+
address@hidden
+$ gnunet-identity -s namestore -e NAME
address@hidden example
+where NAME is the name of the zone you want to import records
+into.  In our running example, this would be ``gnu''.
+
+Henceforth, for every business card you collect, simply run:
 @example
 $ gnunet-qr
 @end example
@@ -521,6 +526,7 @@ Hold up your friend's business card and tilt it until
 the QR code is recognized. At that point, the window should
 automatically close. At that point, your friend's NICKname and their
 public key should have been automatically imported into your zone.
+
 Assuming both of your peers are properly integrated in the
 GNUnet network at this time, you should thus be able to
 resolve your friends names. Suppose your friend's nickname
@@ -556,6 +562,7 @@ Note: All these files contain cryptographic keys and they 
are
 stored without any encryption.  So it is advisable to backup
 encrypted copies of them.
 
+
 @node Revocation
 @subsection Revocation
 
@@ -604,6 +611,7 @@ To avoid TL;DR ones from accidentally revocating their 
zones, we are not
 giving away the command, but it is uncomplicated: the actual revocation is
 performed by using the @command{-p} option of @command{gnunet-revocation}.
 
+
 @node What's Next?
 @subsection What's Next?
 @c %**end of header
@@ -675,11 +683,10 @@ To make a call with @code{gnunet-conversation}, you first
 need to choose an identity. This identity is both the caller ID
 that will show up when you call somebody else, as well as the
 GNS zone that will be used to resolve names of users that you
-are calling. Usually, the @code{master-zone} is a reasonable
-choice. Run
+are calling. Run
 
 @example
-gnunet-conversation -e master-zone
+gnunet-conversation -e zone-name
 @end example
 
 @noindent
diff --git a/src/namestore/gnunet-namestore.c b/src/namestore/gnunet-namestore.c
index 4f512713b..054417ab5 100644
--- a/src/namestore/gnunet-namestore.c
+++ b/src/namestore/gnunet-namestore.c
@@ -1127,97 +1127,81 @@ int
 main (int argc,
       char *const *argv)
 {
-  is_public = -1;
-  is_shadow = -1;
-
   struct GNUNET_GETOPT_CommandLineOption options[] = {
-
     GNUNET_GETOPT_option_flag ('a',
-                                  "add",
-                                  gettext_noop ("add record"),
-                                  &add),
-
+                               "add",
+                               gettext_noop ("add record"),
+                               &add),
     GNUNET_GETOPT_option_flag ('d',
-                                  "delete",
-                                  gettext_noop ("delete record"),
-                                  &del),
-
+                               "delete",
+                               gettext_noop ("delete record"),
+                               &del),
     GNUNET_GETOPT_option_flag ('D',
-                                  "display",
-                                  gettext_noop ("display records"),
-                                  &list),
-
+                               "display",
+                               gettext_noop ("display records"),
+                               &list),
     GNUNET_GETOPT_option_string ('e',
                                  "expiration",
                                  "TIME",
                                  gettext_noop ("expiration time for record to 
use (for adding only), \"never\" is possible"),
                                  &expirationstring),
-
     GNUNET_GETOPT_option_string ('i',
                                  "nick",
                                  "NICKNAME",
                                  gettext_noop ("set the desired nick name for 
the zone"),
                                  &nickstring),
-
     GNUNET_GETOPT_option_flag ('m',
-                                  "monitor",
-                                  gettext_noop ("monitor changes in the 
namestore"),
-                                  &monitor),
-
+                               "monitor",
+                               gettext_noop ("monitor changes in the 
namestore"),
+                               &monitor),
     GNUNET_GETOPT_option_string ('n',
                                  "name",
                                  "NAME",
                                  gettext_noop ("name of the record to 
add/delete/display"),
                                  &name),
-
     GNUNET_GETOPT_option_string ('r',
                                  "reverse",
                                  "PKEY",
                                  gettext_noop ("determine our name for the 
given PKEY"),
                                  &reverse_pkey),
-
-
-
     GNUNET_GETOPT_option_string ('t',
                                  "type",
                                  "TYPE",
                                  gettext_noop ("type of the record to 
add/delete/display"),
                                  &typestring),
-
     GNUNET_GETOPT_option_string ('u',
                                  "uri",
                                  "URI",
                                  gettext_noop ("URI to import into our zone"),
                                  &uri),
-
     GNUNET_GETOPT_option_string ('V',
                                  "value",
                                  "VALUE",
                                  gettext_noop ("value of the record to 
add/delete"),
                                  &value),
-
     GNUNET_GETOPT_option_flag ('p',
-                                  "public",
-                                  gettext_noop ("create or list public 
record"),
-                                  &is_public),
-
+                               "public",
+                               gettext_noop ("create or list public record"),
+                               &is_public),
     GNUNET_GETOPT_option_flag ('s',
-                                  "shadow",
-                                  gettext_noop ("create shadow record (only 
valid if all other records of the same type have expired"),
-                                  &is_shadow),
-
+                               "shadow",
+                               gettext_noop ("create shadow record (only valid 
if all other records of the same type have expired"),
+                               &is_shadow),
     GNUNET_GETOPT_option_string ('z',
                                  "zone",
                                  "EGO",
                                  gettext_noop ("name of the ego controlling 
the zone"),
                                  &ego_name),
-
     GNUNET_GETOPT_OPTION_END
   };
 
-  if (GNUNET_OK != GNUNET_STRINGS_get_utf8_args (argc, argv, &argc, &argv))
+  if (GNUNET_OK !=
+      GNUNET_STRINGS_get_utf8_args (argc, argv,
+                                    &argc, &argv))
     return 2;
 
+  is_public = -1;
+  is_shadow = -1;
   GNUNET_log_setup ("gnunet-namestore",
                     "WARNING",
                     NULL);

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