diff options
| -rw-r--r-- | .gitignore | 1 | ||||
| -rw-r--r-- | contrib/scripts/documentation/gnunet-doc.scm | 184 | ||||
| -rw-r--r-- | doc/documentation/README.txt | 63 | ||||
| -rw-r--r-- | doc/documentation/TODO | 106 |
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" |