View Issue Details
| ID | Project | Category | View Status | Date Submitted | Last Update |
|---|---|---|---|---|---|
| 0003914 | GNUnet | documentation | public | 2015-07-25 15:45 | 2019-07-28 16:24 |
| Reporter | Christian Grothoff | Assigned To | |||
| Priority | normal | Severity | text | Reproducibility | N/A |
| Status | assigned | Resolution | open | ||
| Platform | i7 | OS | Debian GNU/Linux | OS Version | squeeze |
| Product Version | Git master | ||||
| 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 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 | ||||
| Tags | No tags attached. | ||||
|
|
Assigning to ng0 as he may take inspiration from this (or feel free to close if useless). |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
WIth that in place, further improvements to the structure can take place more easily. |
|
|
The excerpt of the ToC you propose makes sense. Maybe you could coordinate with ng0 and/or work on a patch? |
|
|
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! |
|
|
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. |
|
|
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? |
|
|
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 |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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 |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
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. |
|
|
I know you want to do triage on bugs, but documentation is a topic which most of the time must be treated differently. |
| 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 => nikita |
| 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 | nikita | Note Added: 0013012 | |
| 2018-06-07 06:15 | nikita | Note Added: 0013013 | |
| 2018-06-07 08:18 | Christian Grothoff | Note Added: 0013014 | |
| 2018-06-27 21:56 | Christian Grothoff | Assigned To | nikita => 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 | nikita | Note Added: 0014387 | |
| 2019-05-13 18:31 | nikita | Assigned To | => nikita |
| 2019-05-13 18:31 | nikita | 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 | nikita | Note Added: 0014399 | |
| 2019-05-15 12:46 | nikita | Note Added: 0014400 | |
| 2019-05-15 12:52 | nikita | Note Added: 0014401 | |
| 2019-05-15 13:58 | ic.rbow | Note Added: 0014402 | |
| 2019-05-15 16:34 | nikita | 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 | nikita | Note Added: 0014483 | |
| 2019-06-01 19:12 | nikita | Note Added: 0014484 | |
| 2019-06-01 19:20 | nikita | Note Added: 0014485 | |
| 2019-06-01 19:23 | nikita | 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 | nikita | Note Added: 0014492 | |
| 2019-06-01 21:35 | ic.rbow | Note Added: 0014494 | |
| 2019-06-01 22:52 | nikita | Note Added: 0014495 | |
| 2019-06-02 11:41 | ic.rbow | Note Added: 0014496 | |
| 2019-06-02 12:12 | nikita | Note Added: 0014497 | |
| 2019-06-02 12:15 | nikita | Note Added: 0014498 | |
| 2019-06-05 19:01 | Christian Grothoff | Target Version | => 0.11.6 |
| 2019-07-01 12:22 | nikita | Note Added: 0014625 | |
| 2019-07-01 12:22 | nikita | Target Version | 0.11.6 => |
| 2019-07-01 12:23 | nikita | Note Added: 0014626 | |
| 2019-07-28 16:24 | nikita | Assigned To | nikita => |
