View Issue Details

IDProjectCategoryView StatusLast Update
0003914GNUnetdocumentationpublic2019-07-01 12:23
ReporterChristian GrothoffAssigned Tong0 
PrioritynormalSeveritytextReproducibilityN/A
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 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
https://gnunet.org/generic-installation-instructions)
* 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)
https://github.com/freddix/libgpg-error (zip)
ftp://ftp.gnupg.org/gcrypt/libgpg-error/

CERTOOL for GNS: depends on nss which depends on nspr
(gns->certool->nss->nspr)
https://developer.mozilla.org/en-US/docs/NSPR
https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/NSS_Sources_Building_Testing
ftp://ftp.mozilla.org/pub/mozilla.org/security/nss/releases/NSS_3_9_2_RTM/Linux2.4_x86_glibc_PTH_OPT.OBJ/
(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.

Activities

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).

ng0

2018-06-07 06:12

developer   ~0013012

THanks.

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.

ng0

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?

catonano

2019-02-22 07:20

reporter   ~0013935

is this meant for 0.11 ?

ng0

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.

ic.rbow

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 https://dpwiz.gitlab.io/gnunet-tutorial/install/

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.

ng0

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)".

ng0

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.

ng0

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.

ic.rbow

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.

ng0

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 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.

ic.rbow

2019-06-01 19:02

reporter   ~0014480

I just had a look at handbook again and noticed that it may be reasonable to have current content structured as it is if it would be rendered as two-level deep pages.

For example (each '*' denotes a page, each '-' denotes a section on the same page):

* ToC
...
* 4 Installing GNUnet
  * 4.1 Installing dependencies
  * 4.2 Getting the Source Code
...
  * 4.7 The graphical configuration interface
    - 4.7.1 Configuring your peer
    - 4.7.2 Configuring the Friend-to-Friend (F2F) mode
...
    - 4.7.31 Peer configuration for distributors (e.g. Operating Systems)
...
* 5 Using GNUnet
  * 5.6 The GNU Name System
    - 5.6.6 Resource Records in GNS
    - 5.6.6.21 RECLAIM OIDC REDIRECT
...

If possible, this would retain observability of a whole topic while focusing the attention to the topic at hand.
As you can see, there can be a lots of level 3 subsections per parent, but level 2 division is pretty adequate.

ic.rbow

2019-06-01 19:04

reporter   ~0014481

WIth that in place, further improvements to the structure can take place more easily.

Christian Grothoff

2019-06-01 19:06

manager   ~0014482

The excerpt of the ToC you propose makes sense. Maybe you could coordinate with ng0 and/or work on a patch?

ng0

2019-06-01 19:08

developer   ~0014483

Can you go more into detail what you mean?

So far I can only guess. Do you mean the way the html output looks like in list style?
Know that the current structure is done semi-automatically for some outputs, all I do
is tell texinfo about the nodes.

If possible a view in .patch or diff view would be good!

ng0

2019-06-01 19:12

developer   ~0014484

Adding: As far as I know Texinfo has no concept of "pages".
When you take the one-page-per-node view of html, you get what you ask for or part of it.
See https://www.gnu.org/software/guix/manual/en/html_node/ and
https://www.gnu.org/software/guix/manual/en/html_node/Application-Setup.html#Application-Setup
for an example.

ng0

2019-06-01 19:20

developer   ~0014485

imho the best course of action would be to get interested people (we have at least 3 working on the docs every now and then), step back, and re-evaluate what we personally want to read.

Obviously what we have is far from perfect. Coordinated writing could make this huge task a bit more structured.

Old texts could be in the way. Because someone has once written it doesn't mean it is still true. And if it is, do we have to keep the exact (albeit corrected by myself) texts?

ng0

2019-06-01 19:23

developer   ~0014486

Just looking at the size of it can be intimidating I imagine and make a rewrite or corrections seem more difficult than they are.

 wc gnunet.texi chapters/*
     248 838 7469 gnunet.texi
       5 23 159 chapters/configuration.texi
     117 582 4246 chapters/contributing.texi
    9009 54204 366481 chapters/developer.texi
    2325 12295 82825 chapters/installation.texi
     321 2340 15728 chapters/keyconcepts.texi
      81 507 3578 chapters/philosophy.texi
     206 1608 9952 chapters/preface.texi
    2335 14141 89091 chapters/user.texi
      72 203 1498 chapters/vocabulary.texi
   14719 86741 581027 total

ic.rbow

2019-06-01 19:36

reporter   ~0014489

The intended layout I would like is like this page: https://www.gnu.org/software/guix/manual/en/html_node/Python-Modules.html#Python-Modules
It is 3 levels deep (14.4.5 Python Modules) and containes one more level (14.4.5.1 Specifying Dependencies), which is inlined in the resulting HTML page. And it has that one "inner" node in the main ToC.

That looks almost as I would like that for the GNUnet handbook, with the distinction that nodes should be inlined starting from depth level 3 judging by the site contents. Otherwise users will be presented with 1 paragraph of text per page as they were on the previous 1-node-per-page layout.

The patch would have to do with textinfo configuration/build script tweaks of which I yet have to know more.

ic.rbow

2019-06-01 19:39

reporter   ~0014491

I looked at texinfo manual and haven't found any options concerning node depths. Maybe the solution would be to use page-per-node layout and strategically wrap groups of lesser sections to force inlining beyound level 3.

ng0

2019-06-01 20:14

developer   ~0014492

Okay. If you want to give it a try, go ahead. I'd like to review the patch before if it involves a non-trivial amount of changes to the Texinfo book. Ideally doc/tutorial is also considered, but for now handbook is already enough text (tutorial would be less complex and a good testing ground).

I don't know how familiar you are with Texinfo and the other stuff involved, if you have any questions feel free to ask here.

ic.rbow

2019-06-01 21:35

reporter   ~0014494

I found relevant bit in `gendocs.sh`:

  --split HOW make split HTML by node, section, chapter; default node.

Perhaps GUIX manual does that section splitting thing?

Here it is in the manual: https://www.gnu.org/software/texinfo/manual/texinfo/texinfo.html#HTML-Splitting

Now, if you tell me what exactly to run to get the docs built (there are just too many pieces for a first run unguided...) maybe I can figure it out where to apply the splitting (please say if you know that already) and proceed with poking the handbook.

ng0

2019-06-01 22:52

developer   ~0014495

This is how the handbooks are build on the server (crontab):

* * * * * cd gnunet; sh contrib/gnunet_infrastructure/handbook_pull.sh; cd doc/handbook; make gnunet.html &> /dev/null
* * * * * cd gnunet/doc/tutorial; make gnunet-tutorial.html &> /dev/null

Where handbook_pull.sh is iirc just a thing I wrote for the server to continue working.
I did initially look at - among other projects - Guix texinfo generation, but they include more logic than we (currently) need minus(!) backwards compatibility things I applied.

The relevant pieces are in the first few lines of the doc/handbook/Makefile.am:

# NOTE: While GNU makeinfo 6.5 supports --css-ref=URL,
# makeinfo 4.8 (in NetBSD 8.0, macOS, and maybe other
# base) does only support --css-include=FILE.
# The only difference is a shorter html output and
# in 6.5 the ability to use refs instead of include.
# We prefer not to break builds in this case, so
# we use the include version which is backwards compatible
# and upwards compatible, while the ref variant is neither.

AM_MAKEINFOHTMLFLAGS = --no-split --css-include=style.css --css-include=manual.css


So what we want here is to have 2 rules for the html output and not one implicit generated rule. Rule 1: what we do now (1 page output). Rule 2: just remove the --no-split OR add --split

ic.rbow

2019-06-02 11:41

reporter   ~0014496

Oh... It is in the 5.x they added `--split=chapters|sections` in addition to `--split=nodes`. Perhaps website handbook could use most recent version while distribution can fall back to whatever version available.

ng0

2019-06-02 12:12

developer   ~0014497

Okay. Just another Makefile.am rule combined with a configure flag then.

For example --enable-texinfo4 -> uses the default I have now.
Defaults to TRUE.
Server would then --disable-texinfo4 (so: FALSE), and get the newest texinfo feature.
Depending on the value, the Makefile.am would then use an appropriate AM_MAKEINFOHTMLFLAGS.

ng0

2019-06-02 12:15

developer   ~0014498

So basically:
if ENABLE_TEXINFO4
AM_MAKEINFOHTMLFLAGS = --no-split --css-include=style.css --css-include=manual.css
else
AM_MAKEINFOHTMLFLAGS = --split=sections --css-ref=style.css --css-ref=manual.css
endif

or something along those lines, allowing us to support both old and new makeinfo while keeping the texinfo itself backwards compatible.

ng0

2019-07-01 12:22

developer   ~0014625

Stop assigning version numbers to big documentation tasks which were worded in a way which can not be done in 1 or more minor versions.

ng0

2019-07-01 12:23

developer   ~0014626

I know you want to do triage on bugs, but documentation is a topic which most of the time must be treated differently.

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
2019-06-01 19:02 ic.rbow Note Added: 0014480
2019-06-01 19:04 ic.rbow Note Added: 0014481
2019-06-01 19:06 Christian Grothoff Note Added: 0014482
2019-06-01 19:08 ng0 Note Added: 0014483
2019-06-01 19:12 ng0 Note Added: 0014484
2019-06-01 19:20 ng0 Note Added: 0014485
2019-06-01 19:23 ng0 Note Added: 0014486
2019-06-01 19:36 ic.rbow Note Added: 0014489
2019-06-01 19:39 ic.rbow Note Added: 0014491
2019-06-01 20:14 ng0 Note Added: 0014492
2019-06-01 21:35 ic.rbow Note Added: 0014494
2019-06-01 22:52 ng0 Note Added: 0014495
2019-06-02 11:41 ic.rbow Note Added: 0014496
2019-06-02 12:12 ng0 Note Added: 0014497
2019-06-02 12:15 ng0 Note Added: 0014498
2019-06-05 19:01 Christian Grothoff Target Version => 0.11.6
2019-07-01 12:22 ng0 Note Added: 0014625
2019-07-01 12:22 ng0 Target Version 0.11.6 =>
2019-07-01 12:23 ng0 Note Added: 0014626