From 39ba161d724adf7f5003da872aeb2f5378eb8582 Mon Sep 17 00:00:00 2001 From: Nils Gillmann Date: Sun, 27 May 2018 13:51:07 +0000 Subject: add TODO notes in doc/documentation Signed-off-by: Nils Gillmann --- doc/documentation/README.txt | 63 ------------------------- doc/documentation/TODO | 106 +++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 106 insertions(+), 63 deletions(-) delete mode 100644 doc/documentation/README.txt create mode 100644 doc/documentation/TODO (limited to 'doc') diff --git a/doc/documentation/README.txt b/doc/documentation/README.txt deleted file mode 100644 index 9e76394c3..000000000 --- a/doc/documentation/README.txt +++ /dev/null @@ -1,63 +0,0 @@ -* Completion Levels: - -** chapters/philosophy: around 100% fixed after initial export. - -* What's left to do - -- Which Texlive modules are needed? Decrease the size. - - distro specific, or can we set requirements? -- Update the content of gnunet documentation. -- XXX: images are only generated for the html documentation - with gendoc.sh … FIXME! -- XXX: png,dot, and svg images MUST be converted to eps by the - build system. Right now they aren't, as a result: No images. - -* How to use (hack) on this - -** with guix - -Adjust accordingly, ie read the Guix Documentation: -setenv GUIX_PACKAGE_PATH "gnunet/contrib/packages/guix/packages" -guix environment gnunet-doc -and -guix build -f contrib/packages/guix/gnunet-doc.scm - -** without guix - -You need to have Texinfo and Texlive in your path. -sh bootstrap -./configure --enable-documentation -cd doc -make (format you want) - -for example: make html, make info, make pdf - -* structure (relations) - -** gnunet.texi - -> chapters/developer.texi - -> chapters/installation.texi - -> chapters/philosophy.texi - -> chapters/user.texi - -> chapters/vocabulary.texi - -> images/* - -> gpl-3.0.texi - -> fdl-1.3.texi - -** gnunet-c-tutorial.texi - -> figs/Service.pdf - -> figs/System.pdf - -> tutorial-examples/*.c - -> gpl-3.0.texi - -> fdl-1.3.texi - -- gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". -- man folder: the man pages. -- doxygen folder -- outdated-and-old-installation-instructions.txt: self described within the file. - - -Use `gendocs', add to the manual/ directory of the web site. - - $ cd doc - $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual" diff --git a/doc/documentation/TODO b/doc/documentation/TODO new file mode 100644 index 000000000..fa1ce7a23 --- /dev/null +++ b/doc/documentation/TODO @@ -0,0 +1,106 @@ +-*- mode: org -*- + +TODO - or: the Documentation Masterplan. + +To some extent this duplicates the Mantis tickets on this topic. + +* Motivation +My motivation is to read into good documentations and create a self-contained collection of books, +which can be understood without expecting too much background knowledge in every topic. +** User Handbook: +The content of the User book should be mostly concerned with our current and future graphical (gtk +as well as terminal user interface) applications. After reading Preface and maybe Philosophy, the +person reading the User Handbook should understand with the least possible strugle the application +they intend to use. Examples should be given and concepts explained. +** Installation Handbook: +As seen with requests on the mailinglist, we will have to pick up people where they are, similar +to the User Handbook. People already used to compiling and installing should have the chance to +skip to the end, everyone else should: have step-by-step instructions, which will either already +include OS specific notes or will be followed by OS specific instructions. It is up for discussion +if configuring GNUnet is 'User Handbook' or 'Installation Handbook', the current mixture in +the Installation Handbook is not good. +** Contributors Handbook: +This chapter could either be reduced to a couple of sections following the theme of 'contributing +to GNUnet' or the chapter could be extended. If we extend it, we should explain a range of topics +that can be useful for contributors. It can be understood as a recommended reading in addition to +the Developer Handbook then, and the Developer Handbook could simply become a better commented +reference for the code-base. +** Developer Handbook: +As outlined in the last sentences, the Developer Handbook could be reduced to the necessary bits +with enough comments to be understood without reading into the papers published over the years. + + +* DONE 1. Drupal books export to LaTeX. +* DONE 2. LaTeX conversion to Texinfo. +* DONE 3. (initial) Fixup of syntax errors introduced in conversion chain. +* TODO 4. Update content. +* TODO 5. Create API Reference or similar +* TODO 6. Create Concept Index +* TODO 7. Create Procedure Index +* TODO 8. Create Type Index +* TODO 9. Create Functions Index +* TODO 10. Properly address concerns and criticism people had/have on the old and current documentation. +* TODO 11. Reorder structure +* TODO more TODO. + + +* Status Progress / Completion Levels + +** chapters/philosophy: around 100% fixed after initial export. + +* System Integration Tasks + +* Which Texlive modules are needed for every output we generate? +* Generate the images from their dot sources. + +* How to use (hack) on this + +This section will find its way into the documentation sooner or later. +Potentially outdated or inaccurate bits. + +** with guix + +Adjust accordingly, ie read the Guix Documentation: +guix environment gnunet-doc +and +guix build -f contrib/packages/guix/gnunet-doc.scm + +** without guix + +You need to have Texinfo and Texlive in your path. +sh bootstrap +./configure --enable-documentation +cd doc +make (format you want) + +for example: make html, make info, make pdf + +* structure (relations) (old!) + +** gnunet.texi + -> chapters/developer.texi + -> chapters/installation.texi + -> chapters/philosophy.texi + -> chapters/user.texi + -> chapters/vocabulary.texi + -> images/* + -> gpl-3.0.texi + -> fdl-1.3.texi + +** gnunet-c-tutorial.texi + -> figs/Service.pdf + -> figs/System.pdf + -> tutorial-examples/*.c + -> gpl-3.0.texi + -> fdl-1.3.texi + +- gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". +- man folder: the man pages. +- doxygen folder +- outdated-and-old-installation-instructions.txt: self described within the file. + + +Use `gendocs', add to the manual/ directory of the web site. + + $ cd doc + $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual" -- cgit v1.2.3