add TODO notes in doc/documentation

Signed-off-by: Nils Gillmann <ng0@n0.is>

4 files changed, 290 insertions, 64 deletions

diff --git a/.gitignore b/.gitignore
index e30c67220d..a16870e24b 100644
--- a/.gitignore
+++ b/.gitignore
@@ -41,7 +41,6 @@ INSTALL
 confdefs.h
 confdefs.c
 confdefs.err
-gnunet-doc.scm
 guix-env-gillmann.scm
 src/namestore/test_namestore_api_zone_to_name
 src/credential/gnunet-credential
diff --git a/contrib/scripts/documentation/gnunet-doc.scm b/contrib/scripts/documentation/gnunet-doc.scm
new file mode 100644
index 0000000000..d8c16fdb35
--- /dev/null
+++ b/contrib/scripts/documentation/gnunet-doc.scm
@@ -0,0 +1,184 @@
+;;; This file is part of GNUnet.
+;;; Copyright (C) 2016, 2017 GNUnet e.V.
+;;;
+;;; GNUnet is free software; you can redistribute it and/or modify
+;;; it under the terms of the GNU General Public License as published
+;;; by the Free Software Foundation; either version 3, or (at your
+;;; option) any later version.
+;;;
+;;; GNUnet is distributed in the hope that it will be useful, but
+;;; WITHOUT ANY WARRANTY; without even the implied warranty of
+;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
+;;; General Public License for more details.
+;;;
+;;; You should have received a copy of the GNU General Public License
+;;; along with GNUnet; see the file COPYING.  If not, write to the
+;;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor,
+;;; Boston, MA 02110-1301, USA.
+;;;
+
+(use-modules
+ (ice-9 popen)
+ (ice-9 match)
+ (ice-9 rdelim)
+ (guix packages)
+ (guix build-system gnu)
+ (guix gexp)
+ ((guix build utils) #:select (with-directory-excursion))
+ (guix git-download)
+ (guix utils) ; current-source-directory
+ (gnu packages)
+ (gnu packages aidc)
+ (gnu packages autotools)
+ (gnu packages backup)
+ (gnu packages base)
+ (gnu packages compression)
+ (gnu packages curl)
+ (gnu packages databases)
+ (gnu packages file)
+ (gnu packages gettext)
+ (gnu packages glib)
+ (gnu packages gnome)
+ (gnu packages gnunet)
+ (gnu packages gnupg)
+ (gnu packages gnuzilla)
+ (gnu packages groff)
+ (gnu packages gstreamer)
+ (gnu packages gtk)
+ (gnu packages guile)
+ (gnu packages graphviz)
+ (gnu packages image)
+ (gnu packages image-viewers)
+ (gnu packages libidn)
+ (gnu packages libunistring)
+ (gnu packages linux)
+ (gnu packages maths)
+ (gnu packages multiprecision)
+ (gnu packages perl)
+ (gnu packages pkg-config)
+ (gnu packages pulseaudio)
+ (gnu packages python)
+ (gnu packages tex)
+ (gnu packages texinfo)
+ (gnu packages tex)
+ (gnu packages tls)
+ (gnu packages video)
+ (gnu packages web)
+ (gnu packages xiph)
+ ;;(gnunet packages texlive) ;GNUnet module including texlive-2012 WIP
+ ((guix licenses) #:prefix license:))
+
+;;(define %source-dir (string-append (current-source-directory)
+;;                                   "/../../../"))
+(define %source-dir (dirname (current-filename)))
+
+(define gnunet-doc
+  (let* ((revision "2")
+         (select? (delay (or (git-predicate
+                              (string-append (current-source-directory)
+                                             "/../../../"))
+                             source-file?))))
+      (package
+      (name "gnunet-doc")
+      (version (string-append "0.10.1-" revision "." "dev"))
+      (source
+       (local-file ;;"../../.."
+                   ;;%source-dir
+                   ;;(string-append (getcwd) "/../../../")
+                   (string-append (getcwd)) ;drrty hack and this assumes one static position FIXME!
+                   #:recursive? #t))
+                   ;;#:select? (git-predicate %source-dir)))
+                   ;;#:select? (force select?)))
+      (build-system gnu-build-system)
+      (inputs
+       `(("glpk" ,glpk)
+         ("gnurl" ,gnurl)
+         ("gstreamer" ,gstreamer)
+         ("gst-plugins-base" ,gst-plugins-base)
+         ("gnutls/dane" ,gnutls/dane)
+         ("libextractor" ,libextractor)
+         ("libgcrypt" ,libgcrypt)
+         ("libidn" ,libidn)
+         ("libmicrohttpd" ,libmicrohttpd)
+         ("libltdl" ,libltdl)
+         ("libunistring" ,libunistring)
+         ("openssl" ,openssl)
+         ("opus" ,opus)
+         ("pulseaudio" ,pulseaudio)
+         ("sqlite" ,sqlite)
+         ("postgresql" ,postgresql)
+         ("mysql" ,mysql)
+         ("zlib" ,zlib)
+         ("perl" ,perl)
+         ("python-2" ,python-2) ; tests and gnunet-qr
+         ("jansson" ,jansson)
+         ("nss" ,nss)
+         ("glib" ,glib "bin")
+         ("gmp" ,gmp)
+         ("bluez" ,bluez) ; for optional bluetooth feature
+         ("glib" ,glib)
+         ;;("texlive-minimal" ,texlive-minimal) ; optional.
+         ("texlive" ,texlive) ;TODO: Stabilize Texlive-2012 package
+         ("libogg" ,libogg)))
+      (native-inputs
+       `(("pkg-config" ,pkg-config)
+         ("autoconf" ,autoconf)
+         ("automake" ,automake)
+         ("gnu-gettext" ,gnu-gettext)
+         ("graphviz" ,graphviz) ; dot
+         ("texinfo-5" ,texinfo-5) ; Debian stable
+         ("which" ,which)
+         ("libtool" ,libtool)))
+      (arguments
+       `(#:configure-flags
+         (list "--enable-documentation")
+         #:tests? #f ;Don't run tests
+         #:phases
+         (modify-phases %standard-phases
+           (add-after 'unpack 'autoconf
+             (lambda _
+               (substitute* "bootstrap"
+                 (("contrib/pogen.sh") "sh contrib/pogen.sh"))
+               (for-each (lambda (f) (chmod f #o755))
+                         (find-files "po" ""))
+               (zero? (system* "sh" "bootstrap"))))
+           (add-after 'build 'run-gendocs
+             (lambda _
+               (chdir "doc/documentation")
+               ;;(zero? (system* "make" "dev-build"))))
+               (zero? (system* "sh" "run-gendocs.sh"))))
+               ;; (zero? (system* "make" "pdf"))
+               ;; (zero? (system* "make" "html"))
+               ;; (zero? (system* "make" "info"))))
+               ;;(zero? (system* "make" "doc-all-give-me-the-noise"))))
+           (replace 'install
+             (lambda _
+               (zero? (system* "make" "doc-gendoc-install")))))))
+             ;;(lambda* (#:key outputs #:allow-other-keys)
+               ;; (let* ((out (assoc-ref outputs "out"))
+               ;;        (doc (string-append out "/share/doc/gnunet")))
+               ;;   (mkdir-p doc)
+               ;;   (copy-recursively "images"
+               ;;                     (string-append doc
+               ;;                                    "/images"))
+               ;;   (mkdir-p (string-append doc "/gnunet"))
+               ;;   (install-file "gnunet.pdf" doc)
+               ;;   (install-file "gnunet.info" doc)
+               ;;   (install-file "gnunet.log" doc) ;TODO: Move to 'dev' output?
+               ;;   (copy-recursively "gnunet"
+               ;;                     (string-append doc
+               ;;                                    "/gnunet"))
+               ;;   (install-file "gnunet-c-tutorial.pdf" doc)
+               ;;   (install-file "gnunet-c-tutorial.info" doc)
+               ;;   (install-file "gnunet-c-tutorial.log" doc) ;TODO: Move to 'dev' output?
+               ;;   (copy-recursively "gnunet-c-tutorial"
+               ;;                     (string-append doc
+               ;;                                    "/gnunet-c-tutorial")))
+               ;; #t)))))
+      (synopsis "Documentation of GNUnet")
+      (description
+       "GNUnet documentation build")
+      (license (list license:fdl1.3+ license:gpl3+))
+      (home-page "https://gnunet.org/"))))
+
+gnunet-doc
diff --git a/doc/documentation/README.txt b/doc/documentation/README.txt
deleted file mode 100644
index 9e76394c3f..0000000000
--- 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 0000000000..fa1ce7a23c
--- /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"