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 e30c67220..a16870e24 100644 --- a/.gitignore +++ b/.gitignore | |||
@@ -41,7 +41,6 @@ INSTALL | |||
41 | confdefs.h | 41 | confdefs.h |
42 | confdefs.c | 42 | confdefs.c |
43 | confdefs.err | 43 | confdefs.err |
44 | gnunet-doc.scm | ||
45 | guix-env-gillmann.scm | 44 | guix-env-gillmann.scm |
46 | src/namestore/test_namestore_api_zone_to_name | 45 | src/namestore/test_namestore_api_zone_to_name |
47 | src/credential/gnunet-credential | 46 | 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 @@ | |||
1 | ;;; This file is part of GNUnet. | ||
2 | ;;; Copyright (C) 2016, 2017 GNUnet e.V. | ||
3 | ;;; | ||
4 | ;;; GNUnet is free software; you can redistribute it and/or modify | ||
5 | ;;; it under the terms of the GNU General Public License as published | ||
6 | ;;; by the Free Software Foundation; either version 3, or (at your | ||
7 | ;;; option) any later version. | ||
8 | ;;; | ||
9 | ;;; GNUnet is distributed in the hope that it will be useful, but | ||
10 | ;;; WITHOUT ANY WARRANTY; without even the implied warranty of | ||
11 | ;;; MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU | ||
12 | ;;; General Public License for more details. | ||
13 | ;;; | ||
14 | ;;; You should have received a copy of the GNU General Public License | ||
15 | ;;; along with GNUnet; see the file COPYING. If not, write to the | ||
16 | ;;; Free Software Foundation, Inc., 51 Franklin Street, Fifth Floor, | ||
17 | ;;; Boston, MA 02110-1301, USA. | ||
18 | ;;; | ||
19 | |||
20 | (use-modules | ||
21 | (ice-9 popen) | ||
22 | (ice-9 match) | ||
23 | (ice-9 rdelim) | ||
24 | (guix packages) | ||
25 | (guix build-system gnu) | ||
26 | (guix gexp) | ||
27 | ((guix build utils) #:select (with-directory-excursion)) | ||
28 | (guix git-download) | ||
29 | (guix utils) ; current-source-directory | ||
30 | (gnu packages) | ||
31 | (gnu packages aidc) | ||
32 | (gnu packages autotools) | ||
33 | (gnu packages backup) | ||
34 | (gnu packages base) | ||
35 | (gnu packages compression) | ||
36 | (gnu packages curl) | ||
37 | (gnu packages databases) | ||
38 | (gnu packages file) | ||
39 | (gnu packages gettext) | ||
40 | (gnu packages glib) | ||
41 | (gnu packages gnome) | ||
42 | (gnu packages gnunet) | ||
43 | (gnu packages gnupg) | ||
44 | (gnu packages gnuzilla) | ||
45 | (gnu packages groff) | ||
46 | (gnu packages gstreamer) | ||
47 | (gnu packages gtk) | ||
48 | (gnu packages guile) | ||
49 | (gnu packages graphviz) | ||
50 | (gnu packages image) | ||
51 | (gnu packages image-viewers) | ||
52 | (gnu packages libidn) | ||
53 | (gnu packages libunistring) | ||
54 | (gnu packages linux) | ||
55 | (gnu packages maths) | ||
56 | (gnu packages multiprecision) | ||
57 | (gnu packages perl) | ||
58 | (gnu packages pkg-config) | ||
59 | (gnu packages pulseaudio) | ||
60 | (gnu packages python) | ||
61 | (gnu packages tex) | ||
62 | (gnu packages texinfo) | ||
63 | (gnu packages tex) | ||
64 | (gnu packages tls) | ||
65 | (gnu packages video) | ||
66 | (gnu packages web) | ||
67 | (gnu packages xiph) | ||
68 | ;;(gnunet packages texlive) ;GNUnet module including texlive-2012 WIP | ||
69 | ((guix licenses) #:prefix license:)) | ||
70 | |||
71 | ;;(define %source-dir (string-append (current-source-directory) | ||
72 | ;; "/../../../")) | ||
73 | (define %source-dir (dirname (current-filename))) | ||
74 | |||
75 | (define gnunet-doc | ||
76 | (let* ((revision "2") | ||
77 | (select? (delay (or (git-predicate | ||
78 | (string-append (current-source-directory) | ||
79 | "/../../../")) | ||
80 | source-file?)))) | ||
81 | (package | ||
82 | (name "gnunet-doc") | ||
83 | (version (string-append "0.10.1-" revision "." "dev")) | ||
84 | (source | ||
85 | (local-file ;;"../../.." | ||
86 | ;;%source-dir | ||
87 | ;;(string-append (getcwd) "/../../../") | ||
88 | (string-append (getcwd)) ;drrty hack and this assumes one static position FIXME! | ||
89 | #:recursive? #t)) | ||
90 | ;;#:select? (git-predicate %source-dir))) | ||
91 | ;;#:select? (force select?))) | ||
92 | (build-system gnu-build-system) | ||
93 | (inputs | ||
94 | `(("glpk" ,glpk) | ||
95 | ("gnurl" ,gnurl) | ||
96 | ("gstreamer" ,gstreamer) | ||
97 | ("gst-plugins-base" ,gst-plugins-base) | ||
98 | ("gnutls/dane" ,gnutls/dane) | ||
99 | ("libextractor" ,libextractor) | ||
100 | ("libgcrypt" ,libgcrypt) | ||
101 | ("libidn" ,libidn) | ||
102 | ("libmicrohttpd" ,libmicrohttpd) | ||
103 | ("libltdl" ,libltdl) | ||
104 | ("libunistring" ,libunistring) | ||
105 | ("openssl" ,openssl) | ||
106 | ("opus" ,opus) | ||
107 | ("pulseaudio" ,pulseaudio) | ||
108 | ("sqlite" ,sqlite) | ||
109 | ("postgresql" ,postgresql) | ||
110 | ("mysql" ,mysql) | ||
111 | ("zlib" ,zlib) | ||
112 | ("perl" ,perl) | ||
113 | ("python-2" ,python-2) ; tests and gnunet-qr | ||
114 | ("jansson" ,jansson) | ||
115 | ("nss" ,nss) | ||
116 | ("glib" ,glib "bin") | ||
117 | ("gmp" ,gmp) | ||
118 | ("bluez" ,bluez) ; for optional bluetooth feature | ||
119 | ("glib" ,glib) | ||
120 | ;;("texlive-minimal" ,texlive-minimal) ; optional. | ||
121 | ("texlive" ,texlive) ;TODO: Stabilize Texlive-2012 package | ||
122 | ("libogg" ,libogg))) | ||
123 | (native-inputs | ||
124 | `(("pkg-config" ,pkg-config) | ||
125 | ("autoconf" ,autoconf) | ||
126 | ("automake" ,automake) | ||
127 | ("gnu-gettext" ,gnu-gettext) | ||
128 | ("graphviz" ,graphviz) ; dot | ||
129 | ("texinfo-5" ,texinfo-5) ; Debian stable | ||
130 | ("which" ,which) | ||
131 | ("libtool" ,libtool))) | ||
132 | (arguments | ||
133 | `(#:configure-flags | ||
134 | (list "--enable-documentation") | ||
135 | #:tests? #f ;Don't run tests | ||
136 | #:phases | ||
137 | (modify-phases %standard-phases | ||
138 | (add-after 'unpack 'autoconf | ||
139 | (lambda _ | ||
140 | (substitute* "bootstrap" | ||
141 | (("contrib/pogen.sh") "sh contrib/pogen.sh")) | ||
142 | (for-each (lambda (f) (chmod f #o755)) | ||
143 | (find-files "po" "")) | ||
144 | (zero? (system* "sh" "bootstrap")))) | ||
145 | (add-after 'build 'run-gendocs | ||
146 | (lambda _ | ||
147 | (chdir "doc/documentation") | ||
148 | ;;(zero? (system* "make" "dev-build")))) | ||
149 | (zero? (system* "sh" "run-gendocs.sh")))) | ||
150 | ;; (zero? (system* "make" "pdf")) | ||
151 | ;; (zero? (system* "make" "html")) | ||
152 | ;; (zero? (system* "make" "info")))) | ||
153 | ;;(zero? (system* "make" "doc-all-give-me-the-noise")))) | ||
154 | (replace 'install | ||
155 | (lambda _ | ||
156 | (zero? (system* "make" "doc-gendoc-install"))))))) | ||
157 | ;;(lambda* (#:key outputs #:allow-other-keys) | ||
158 | ;; (let* ((out (assoc-ref outputs "out")) | ||
159 | ;; (doc (string-append out "/share/doc/gnunet"))) | ||
160 | ;; (mkdir-p doc) | ||
161 | ;; (copy-recursively "images" | ||
162 | ;; (string-append doc | ||
163 | ;; "/images")) | ||
164 | ;; (mkdir-p (string-append doc "/gnunet")) | ||
165 | ;; (install-file "gnunet.pdf" doc) | ||
166 | ;; (install-file "gnunet.info" doc) | ||
167 | ;; (install-file "gnunet.log" doc) ;TODO: Move to 'dev' output? | ||
168 | ;; (copy-recursively "gnunet" | ||
169 | ;; (string-append doc | ||
170 | ;; "/gnunet")) | ||
171 | ;; (install-file "gnunet-c-tutorial.pdf" doc) | ||
172 | ;; (install-file "gnunet-c-tutorial.info" doc) | ||
173 | ;; (install-file "gnunet-c-tutorial.log" doc) ;TODO: Move to 'dev' output? | ||
174 | ;; (copy-recursively "gnunet-c-tutorial" | ||
175 | ;; (string-append doc | ||
176 | ;; "/gnunet-c-tutorial"))) | ||
177 | ;; #t))))) | ||
178 | (synopsis "Documentation of GNUnet") | ||
179 | (description | ||
180 | "GNUnet documentation build") | ||
181 | (license (list license:fdl1.3+ license:gpl3+)) | ||
182 | (home-page "https://gnunet.org/")))) | ||
183 | |||
184 | 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 @@ | |||
1 | * Completion Levels: | ||
2 | |||
3 | ** chapters/philosophy: around 100% fixed after initial export. | ||
4 | |||
5 | * What's left to do | ||
6 | |||
7 | - Which Texlive modules are needed? Decrease the size. | ||
8 | - distro specific, or can we set requirements? | ||
9 | - Update the content of gnunet documentation. | ||
10 | - XXX: images are only generated for the html documentation | ||
11 | with gendoc.sh … FIXME! | ||
12 | - XXX: png,dot, and svg images MUST be converted to eps by the | ||
13 | build system. Right now they aren't, as a result: No images. | ||
14 | |||
15 | * How to use (hack) on this | ||
16 | |||
17 | ** with guix | ||
18 | |||
19 | Adjust accordingly, ie read the Guix Documentation: | ||
20 | setenv GUIX_PACKAGE_PATH "gnunet/contrib/packages/guix/packages" | ||
21 | guix environment gnunet-doc | ||
22 | and | ||
23 | guix build -f contrib/packages/guix/gnunet-doc.scm | ||
24 | |||
25 | ** without guix | ||
26 | |||
27 | You need to have Texinfo and Texlive in your path. | ||
28 | sh bootstrap | ||
29 | ./configure --enable-documentation | ||
30 | cd doc | ||
31 | make (format you want) | ||
32 | |||
33 | for example: make html, make info, make pdf | ||
34 | |||
35 | * structure (relations) | ||
36 | |||
37 | ** gnunet.texi | ||
38 | -> chapters/developer.texi | ||
39 | -> chapters/installation.texi | ||
40 | -> chapters/philosophy.texi | ||
41 | -> chapters/user.texi | ||
42 | -> chapters/vocabulary.texi | ||
43 | -> images/* | ||
44 | -> gpl-3.0.texi | ||
45 | -> fdl-1.3.texi | ||
46 | |||
47 | ** gnunet-c-tutorial.texi | ||
48 | -> figs/Service.pdf | ||
49 | -> figs/System.pdf | ||
50 | -> tutorial-examples/*.c | ||
51 | -> gpl-3.0.texi | ||
52 | -> fdl-1.3.texi | ||
53 | |||
54 | - gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". | ||
55 | - man folder: the man pages. | ||
56 | - doxygen folder | ||
57 | - outdated-and-old-installation-instructions.txt: self described within the file. | ||
58 | |||
59 | |||
60 | Use `gendocs', add to the manual/ directory of the web site. | ||
61 | |||
62 | $ cd doc | ||
63 | $ 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 @@ | |||
1 | -*- mode: org -*- | ||
2 | |||
3 | TODO - or: the Documentation Masterplan. | ||
4 | |||
5 | To some extent this duplicates the Mantis tickets on this topic. | ||
6 | |||
7 | * Motivation | ||
8 | My motivation is to read into good documentations and create a self-contained collection of books, | ||
9 | which can be understood without expecting too much background knowledge in every topic. | ||
10 | ** User Handbook: | ||
11 | The content of the User book should be mostly concerned with our current and future graphical (gtk | ||
12 | as well as terminal user interface) applications. After reading Preface and maybe Philosophy, the | ||
13 | person reading the User Handbook should understand with the least possible strugle the application | ||
14 | they intend to use. Examples should be given and concepts explained. | ||
15 | ** Installation Handbook: | ||
16 | As seen with requests on the mailinglist, we will have to pick up people where they are, similar | ||
17 | to the User Handbook. People already used to compiling and installing should have the chance to | ||
18 | skip to the end, everyone else should: have step-by-step instructions, which will either already | ||
19 | include OS specific notes or will be followed by OS specific instructions. It is up for discussion | ||
20 | if configuring GNUnet is 'User Handbook' or 'Installation Handbook', the current mixture in | ||
21 | the Installation Handbook is not good. | ||
22 | ** Contributors Handbook: | ||
23 | This chapter could either be reduced to a couple of sections following the theme of 'contributing | ||
24 | to GNUnet' or the chapter could be extended. If we extend it, we should explain a range of topics | ||
25 | that can be useful for contributors. It can be understood as a recommended reading in addition to | ||
26 | the Developer Handbook then, and the Developer Handbook could simply become a better commented | ||
27 | reference for the code-base. | ||
28 | ** Developer Handbook: | ||
29 | As outlined in the last sentences, the Developer Handbook could be reduced to the necessary bits | ||
30 | with enough comments to be understood without reading into the papers published over the years. | ||
31 | |||
32 | |||
33 | * DONE 1. Drupal books export to LaTeX. | ||
34 | * DONE 2. LaTeX conversion to Texinfo. | ||
35 | * DONE 3. (initial) Fixup of syntax errors introduced in conversion chain. | ||
36 | * TODO 4. Update content. | ||
37 | * TODO 5. Create API Reference or similar | ||
38 | * TODO 6. Create Concept Index | ||
39 | * TODO 7. Create Procedure Index | ||
40 | * TODO 8. Create Type Index | ||
41 | * TODO 9. Create Functions Index | ||
42 | * TODO 10. Properly address concerns and criticism people had/have on the old and current documentation. | ||
43 | * TODO 11. Reorder structure | ||
44 | * TODO more TODO. | ||
45 | |||
46 | |||
47 | * Status Progress / Completion Levels | ||
48 | |||
49 | ** chapters/philosophy: around 100% fixed after initial export. | ||
50 | |||
51 | * System Integration Tasks | ||
52 | |||
53 | * Which Texlive modules are needed for every output we generate? | ||
54 | * Generate the images from their dot sources. | ||
55 | |||
56 | * How to use (hack) on this | ||
57 | |||
58 | This section will find its way into the documentation sooner or later. | ||
59 | Potentially outdated or inaccurate bits. | ||
60 | |||
61 | ** with guix | ||
62 | |||
63 | Adjust accordingly, ie read the Guix Documentation: | ||
64 | guix environment gnunet-doc | ||
65 | and | ||
66 | guix build -f contrib/packages/guix/gnunet-doc.scm | ||
67 | |||
68 | ** without guix | ||
69 | |||
70 | You need to have Texinfo and Texlive in your path. | ||
71 | sh bootstrap | ||
72 | ./configure --enable-documentation | ||
73 | cd doc | ||
74 | make (format you want) | ||
75 | |||
76 | for example: make html, make info, make pdf | ||
77 | |||
78 | * structure (relations) (old!) | ||
79 | |||
80 | ** gnunet.texi | ||
81 | -> chapters/developer.texi | ||
82 | -> chapters/installation.texi | ||
83 | -> chapters/philosophy.texi | ||
84 | -> chapters/user.texi | ||
85 | -> chapters/vocabulary.texi | ||
86 | -> images/* | ||
87 | -> gpl-3.0.texi | ||
88 | -> fdl-1.3.texi | ||
89 | |||
90 | ** gnunet-c-tutorial.texi | ||
91 | -> figs/Service.pdf | ||
92 | -> figs/System.pdf | ||
93 | -> tutorial-examples/*.c | ||
94 | -> gpl-3.0.texi | ||
95 | -> fdl-1.3.texi | ||
96 | |||
97 | - gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf". | ||
98 | - man folder: the man pages. | ||
99 | - doxygen folder | ||
100 | - outdated-and-old-installation-instructions.txt: self described within the file. | ||
101 | |||
102 | |||
103 | Use `gendocs', add to the manual/ directory of the web site. | ||
104 | |||
105 | $ cd doc | ||
106 | $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual" | ||