Re: [GNUnet-developers] A few comments and fixes to the documentation

[ng0]

Hi,

Amirouche Boubekki transcribed 10K bytes:
> You must not commit that as is. As it was meant to start a discussion.

Thanks! I think it's good. I will only edit the patch to keep the comment
(they have their purpose) and add a follow-up patch
(Links must be displayed in printed versions of the manual,
currently this is achieved by using footnotes).

I have a list of words on (physical) paper which I need to explain
according to questions from the group of people I want this to understand.
Man-in-the-middle is not as common as you think it is.
Ideally this will be achieved by infoboxes like many printed Manuals have
them. The first time the term appears it is explained. In addition to these
infoboxes you'll also have some kind of chapter which takes over the
function of what external links now do.
There will be problems with the infoboxes approach depending on how
much Texinfo can do and how many formats can render this. I know that
full Tex can do this for at least PDF. Texinfo.. I don't know.

Both are longterm goals, the motivation for assemling some kind of
offline-wikipedia with explanations is that the Manual should be selfcontained.

> -- 
> Amirouche ~ amz3 ~ http://www.hyperdev.fr

> diff --git a/doc/documentation/chapters/developer.texi 
> b/doc/documentation/chapters/developer.texi
> index ada6d37..d3d68a8 100644
> --- a/doc/documentation/chapters/developer.texi
> +++ b/doc/documentation/chapters/developer.texi
> @@ -94,6 +94,7 @@ following links:
>  @c ** FIXME: Link to files in source, not online.
>  @c ** FIXME: Where is the Java tutorial?
>  @itemize @bullet
> address@hidden broken link
>  @item 
> @uref{https://gnunet.org/git/gnunet.git/plain/doc/gnunet-c-tutorial.pdf, 
> GNUnet C tutorial}
>  @item GNUnet Java tutorial
>  @end itemize
> @@ -273,7 +274,7 @@ library is a wapper around block plugins which provide 
> the necessary
>  functions for each block type.
>  @item @file{statistics/} --- statistics service
>  The statistics service enables associating
> -values (of type uint64_t) with a componenet name and a string. The main
> +values (of type uint64_t) with a component name and a string. The main
>  uses is debugging (counting events), performance tracking and user
>  entertainment (what did my peer do today?).
>  @item @file{arm/} --- Automatic Restart Manager (ARM)
> @@ -2450,7 +2451,7 @@ memcpy (tbuf, nameTrans, strlen (nameTrans) + 1);
> 
>  Note that, here the functions @code{htonl}, @code{htons} and
>  @code{GNUNET_TIME_absolute_hton} are applied to convert little endian
> -into big endian, about the usage of the big/small edian order and the
> +into big endian, about the usage of the big/small endian order and the
>  corresponding conversion function please refer to Introduction of
>  Big Endian and Little Endian.
> 
> @@ -7027,6 +7028,7 @@ bandwidth consumption.
> 
>  @c %**end of header
> 
> address@hidden inconsistent use of ``must'' above it's written ``MUST''
>  In contrast to GET operations, developers @strong{must} manually re-run
>  PUT operations periodically (if they intend the content to continue to be
>  available). Content stored in the DHT expires or might be lost due to
> @@ -7055,7 +7057,7 @@ Using the monitoring API, applications can choose to 
> monitor these
>  requests, possibly limiting themselves to requests for a particular block
>  type.
> 
> -The monitoring API is not only usefu only for diagnostics, it can also be
> +The monitoring API is not only useful for diagnostics, it can also be
>  used to trigger application operations based on PUT operations.
>  For example, an application may use PUTs to distribute work requests to
>  other peers.
> @@ -7149,7 +7151,7 @@ already knows more than about a thousand blocks may 
> need to send
>  several of these messages. Naturally, the client should transmit these
>  messages as quickly as possible after the original GET request such that
>  the DHT can filter those results in the network early on. Naturally, as
> -these messages are send after the original request, it is conceivalbe
> +these messages are sent after the original request, it is conceivalbe
>  that the DHT service may return blocks that match those already known
>  to the client anyway.
> 
> @@ -7240,7 +7242,7 @@ A peer can search the DHT by sending @code{struct 
> PeerGetMessage}s of type
>  @code{GNUNET_MESSAGE_TYPE_DHT_P2P_GET} to other peers. In addition to the
>  usual information about the request (type, routing options, desired
>  replication level for the request, the key and the extended query), a GET
> -request also again contains a hop counter, a Bloom filter over the peers
> +request also contains a hop counter, a Bloom filter over the peers
>  that have processed the request already and depending on the routing
>  options the full path traversed by the GET.
>  Finally, a GET request includes a variable-size second Bloom filter and a
> diff --git a/doc/documentation/chapters/philosophy.texi 
> b/doc/documentation/chapters/philosophy.texi
> index c8e2651..87a0f94 100644
> --- a/doc/documentation/chapters/philosophy.texi
> +++ b/doc/documentation/chapters/philosophy.texi
> @@ -47,7 +49,8 @@ Refer to @uref{https://www.gnu.org/philosophy/free-sw.html, 
> https://www.gnu.org/
>  @item GNUnet must only disclose the minimal amount of information
>  necessary.
>  @c TODO: Explain 'fully' in the terminology section.
> address@hidden GNUnet must be fully distributed and survive Byzantine failures
> address@hidden GNUnet must be fully distributed and survive
> address@hidden://en.wikipedia.org/wiki/Byzantine_fault_tolerance, Byzantine 
> failures},
>  at any position in the network.
>  @item GNUnet must make it explicit to the user which entities are
>  considered to be trustworthy when establishing secured communications.
> @@ -173,8 +176,6 @@ without requiring signatures each time. GNUnet uses 
> SHA-512
>  (Secure Hash Algorithm) hash codes to verify the integrity of messages.
> 
>  In GNUnet, the identity of a host is its public key. For that reason,
> address@hidden FIXME: is it clear to the average reader what a 
> man-in-the-middle
> address@hidden attack is?
>  man-in-the-middle attacks will not break the authentication or accounting
>  goals. Essentially, for GNUnet, the IP of the host has nothing to do with
>  the identity of the host. As the public key is the only thing that truly
> @@ -420,8 +421,9 @@ public key first.
>  @node Egos
>  @subsection Egos
> 
> address@hidden what is the difference between peer identity and egos? It seems
> address@hidden like both are linked to public-private key pair.
>  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.
> -
> diff --git a/doc/documentation/chapters/user.texi 
> b/doc/documentation/chapters/user.texi
> index 4159a6b..6235820 100644
> --- a/doc/documentation/chapters/user.texi
> +++ b/doc/documentation/chapters/user.texi
> @@ -1183,6 +1183,7 @@ shared under the keyword "Das Kapital".
> 
>  Search results are printed by gnunet-search like this:
> 
> address@hidden it will be better the avoid the ellipsis altogether because I 
> don't understand the explanation below that
>  @example
>  $ gnunet-download -o "COPYING" --- gnunet://fs/chk/N8...C92.17992
>  => The GNU Public License <= (mimetype: text/plain)
> @@ -1192,6 +1193,7 @@ $ gnunet-download -o "COPYING" --- 
> gnunet://fs/chk/N8...C92.17992
>  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.
> @@ -1235,6 +1237,7 @@ GNUnet's file-encoding mechanism will ensure file 
> integrity, even if the
>  existing file was not downloaded from GNUnet in the first place.
> 
>  You may want to use the @command{-V} switch (must be added before
> address@hidden Same as above it's triple dash
>  the @command{--}) to turn on verbose reporting. In this case,
>  @command{gnunet-download} will print the current number of
>  bytes downloaded whenever new data was received.
> @@ -1301,7 +1304,7 @@ unavailable.
>  @c %**end of header
> 
>  Each namespace is associated with meta-data that describes
> -the namespace. This meta data is provided by the user at
> +the namespace. This meta-data is provided by the user at
>  the time that the namespace is advertised. Advertisements
>  are published under keywords so that they can be found using
>  normal keyword-searches. This way, users can learn about new
> _______________________________________________
> GNUnet-developers mailing list
> address@hidden
> https://lists.gnu.org/mailman/listinfo/gnunet-developers


-- 
GnuPG: A88C8ADD129828D7EAC02E52E22F9BBFEE348588
GnuPG: https://c.n0.is/ng0_pubkeys/tree/keys
  WWW: https://n0.is/a/  ::  https://ea.n0.is

signature.asc
Description: PGP signature