View Issue Details

IDProjectCategoryView StatusLast Update
0003914GNUnetdocumentationpublic2019-05-15 16:34
ReporterChristian GrothoffAssigned Tong0 
Status assignedResolutionopen 
Platformi7OSDebian GNU/LinuxOS Versionsqueeze
Product VersionSVN HEAD 
Target VersionFixed in Version 
Summary0003914: improving the installation guide/handbook
DescriptionDemos wrote on gnunet-developers (and we should check & fix):

What i think what could spare users and package builders time and make
installation a fluent process is to improve the installation guide.
Maybe you agree in some points:

1. Mention that there are built-instructions of the different operating
systems at the beginning!
2. Combine and to remove unnecessary redundancy (easier
to maintain in case of (changing) dependencies)->
easier overview for those who want to package.
3. The README text from the installtion package could be the same as the
Installation handbook as long as the installer is not OS-specific.->
easier to maintain,
make sure when somebody changes the README that he changes the
Installation handbook online too and vise versa.
4. Add the following packages to (every) list of dependencies. For
consistency: If no composition of the instructions is made then the
dependencies must be on EVERY list the same having the same order.(not
complete sorry) :
* tar and xz for opening the source balls
* autoconf >= 2.59, automake >= 1.11.1
* gmp (as it is called a dependency in README in the newest
gnunet-package, dependency for nettle)
* libgpgerror (as it stands in
* nettle 2.7
5. Make sure the order of dependencies is as it should be installed.
6. Order the dependencies into two sections must have and optional
7. Add links to the sources:
(not complete) (zip)

CERTOOL for GNS: depends on nss which depends on nspr
(having both packages combined)

8. NETTLE: I had some odd built errors when first configuring and then
making nettle. I did several things and i don't know what helped at the
end, but since nettle is essential for gnutls
(./configure throws an error when nettle is missing) try to build it
yourself: it was not available for Debian 8.1. nettle-2.7 is libnettle4
in debian
TagsNo tags attached.


Christian Grothoff

2018-06-07 01:20

manager   ~0013010

Assigning to ng0 as he may take inspiration from this (or feel free to close if useless).


2018-06-07 06:12

developer   ~0013012


Parts of it will be closed by my next commit on probably friday or saturday.

I even ordered the dependencies in 4 sections.

I don' t think we need to keep track of (build)notes for dependencies of applications more than 1 level below us (like nettle), but I have a verbose stagging file for this and a plan.


2018-06-07 06:15

developer   ~0013013

Grothoff: in the next release notes you can mention my full name as it appears in the developer list. I started using it for easier association.

Christian Grothoff

2018-06-07 08:18

manager   ~0013014

Well, I generated the acks from Git logs (hence sorted by # commits, which seems reasonable, too). Not sure if/how you can change the _historic_ commits, but obviously feel free to use real-name for future commits then.

Christian Grothoff

2019-02-20 13:07

manager   ~0013904

ng0: Is this finished?


2019-02-22 07:20

reporter   ~0013935

is this meant for 0.11 ?


2019-05-13 18:31

developer   ~0014387

> ng0: Is this finished?

I have to check this. I'll get back to this once I'm done at some point this year (there are many points to check in a large body of text and you know the white rabbit from Alice in Wonderland ;) ).. I'll get to it.


2019-05-15 10:40

reporter   ~0014397

BTW, I've begun compiling a set of tutorial/demo/handout pages in markdown.

Starting with aggregation and reviewing of all the installation tutorials at

Christian Grothoff

2019-05-15 11:15

manager   ~0014398

lc.rbow: Fragmenting documentation like this is a bad idea. We do have the texinfo handbook. We should work on improving this primary documentation. Having lots of additional documents spread in various formats all over the world is not helpful. It would be much better if you could focus on contributing to the existing installation chapter in the handbook. Learning TeXinfo is not really hard, it comes with excellent documentation. You can submit patches to the handbook and possibly even get direct Git access to edit it. But having more documentation that has unclear licenses, is hard to find, possibly outdated, and can only be edited by you or people who you give access to is not really that useful. Please try to work with us on this, not duplicate the effort.


2019-05-15 12:38

developer   ~0014399

I have to agree with Christian, however:

1) having handout pages can be first done in markdown. There is a ticket about this I created recently and transpilling from one language to another one if necessary won't be that hard.

2) depending on your scope this is okay. As with every big documentation which isn't rewritten from scratch it is not easy to find a point to start. Knowing what can be changed and what has to be ripped out requires a really long exposure to the project at times and/or asking people who have been around when the old pages have been written.
What the Texinfo - a format I pushed for and am not happy with myself but it works - version represents is the attempt to create a canonical documentation.
API documentation will be transpiled doxygen to mdoc once I'm done with the code, automatic procedure.
What we had in Drupal books was already "all over the place". Don't be discouraged by Christian's words. It's okay, but ideally we can work this into improving the current documentation.

Canonical documentations would improve developers and users interaction with it, as well as aid people who would write books such as "an introduction to modern p2p network programming (with GNUnet)".


2019-05-15 12:46

developer   ~0014400

What I see lacking is a bit of a public plan where I/we want to go to with the documentation.
A while back Christian and myself had a consensus on future content (images for formats which support images, displaying the processes with daily life "stuff" such as sending packages via mail).
My move on stripping out the system specific installations was regarded as a mistake.
So maybe I should take the time and write down what I'd like to improve and where this should move to so that other people can do more than typo hunting and searching dead links etc.
I'm more than aware that I can't do this on my own, even though it helps to form a higher level understanding of gnunet.


2019-05-15 12:52

developer   ~0014401

By the way, if you just want markdown from the Texinfo documentation, you can install mdoc (or if your base system already includes it) and build gnunet with the ability to output the section 7 documentation (which is the production of texinfo2mdoc) and convert the production to markdown with the output type set to markdown.

I'll take a look at what you have later this week.


2019-05-15 13:58

reporter   ~0014402

There's not much original stuff in there right now as I wanted a single *informal* page per topic to refer people to. Current docs site with a single-page handbook is overwhelming for some and a granularity is a bit off IMO.

As for markdown, it's merely a "less plain" text to gather and store notes temporarily.


2019-05-15 16:34

developer   ~0014403

True, we could generate per-section pages output. It's a bit too much and can take long to load if we start adding pictures (to the html output). Furthermore, since this was ad-hoc for a start and the presentation goal should be more like, a choice for pdf, ps, html, single-page html, plain text, etc should be given later on, I totally agree with you.

Issue History

Date Modified Username Field Change
2015-07-25 15:45 Christian Grothoff New Issue
2015-07-27 13:03 Christian Grothoff Assigned To => Jeff Burdges
2015-07-27 13:03 Christian Grothoff Status new => assigned
2018-06-07 01:20 Christian Grothoff Assigned To Jeff Burdges => ng0
2018-06-07 01:20 Christian Grothoff Status assigned => confirmed
2018-06-07 01:20 Christian Grothoff Note Added: 0013010
2018-06-07 01:20 Christian Grothoff Status confirmed => assigned
2018-06-07 06:12 ng0 Note Added: 0013012
2018-06-07 06:15 ng0 Note Added: 0013013
2018-06-07 08:18 Christian Grothoff Note Added: 0013014
2018-06-27 21:56 Christian Grothoff Assigned To ng0 => lurchi
2019-02-20 13:07 Christian Grothoff Assigned To lurchi =>
2019-02-20 13:07 Christian Grothoff Status assigned => confirmed
2019-02-20 13:07 Christian Grothoff Note Added: 0013904
2019-02-22 07:20 catonano Note Added: 0013935
2019-05-13 18:31 ng0 Note Added: 0014387
2019-05-13 18:31 ng0 Assigned To => ng0
2019-05-13 18:31 ng0 Status confirmed => assigned
2019-05-15 10:40 ic.rbow Note Added: 0014397
2019-05-15 11:15 Christian Grothoff Note Added: 0014398
2019-05-15 12:38 ng0 Note Added: 0014399
2019-05-15 12:46 ng0 Note Added: 0014400
2019-05-15 12:52 ng0 Note Added: 0014401
2019-05-15 13:58 ic.rbow Note Added: 0014402
2019-05-15 16:34 ng0 Note Added: 0014403