summaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorNils Gillmann <ng0@n0.is>2018-05-27 13:51:07 +0000
committerNils Gillmann <ng0@n0.is>2018-05-27 13:51:07 +0000
commit39ba161d724adf7f5003da872aeb2f5378eb8582 (patch)
treef498689130485618377909abb5c379878d4885ee
parent4b8ed8fd1560491f60481fef6c1da660ce7d54fe (diff)
add TODO notes in doc/documentation
Signed-off-by: Nils Gillmann <ng0@n0.is>
-rw-r--r--.gitignore1
-rw-r--r--contrib/scripts/documentation/gnunet-doc.scm184
-rw-r--r--doc/documentation/README.txt63
-rw-r--r--doc/documentation/TODO106
4 files changed, 290 insertions, 64 deletions
diff --git a/.gitignore b/.gitignore
index e30c67220..a16870e24 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 000000000..d8c16fdb3
--- /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 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"