View Issue Details
|ID||Project||Category||View Status||Date Submitted||Last Update|
|0003914||GNUnet||documentation||public||2015-07-25 15:45||2019-05-15 16:34|
|Reporter||Christian Grothoff||Assigned To||ng0|
|Platform||i7||OS||Debian GNU/Linux||OS Version||squeeze|
|Product Version||SVN HEAD|
|Target Version||Fixed in Version|
|Summary||0003914: improving the installation guide/handbook|
|Description||Demos 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 https://gnunet.org/generic-installation-instructions and
https://gnunet.org/dependencies 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:
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
|Tags||No tags attached.|
||Assigning to ng0 as he may take inspiration from this (or feel free to close if useless).|
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.
||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.|
||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.|
||ng0: Is this finished?|
||is this meant for 0.11 ?|
> 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.
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 https://dpwiz.gitlab.io/gnunet-tutorial/install/
||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.|
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)".
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.
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.
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.
||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 docs.taler.net, a choice for pdf, ps, html, single-page html, plain text, etc should be given later on, I totally agree with you.|
|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|