diff options
author | Nils Gillmann <ng0@n0.is> | 2018-05-27 13:51:07 +0000 |
---|---|---|
committer | Nils Gillmann <ng0@n0.is> | 2018-05-27 13:51:07 +0000 |
commit | 39ba161d724adf7f5003da872aeb2f5378eb8582 (patch) | |
tree | f498689130485618377909abb5c379878d4885ee /doc | |
parent | 4b8ed8fd1560491f60481fef6c1da660ce7d54fe (diff) | |
download | gnunet-39ba161d724adf7f5003da872aeb2f5378eb8582.tar.gz gnunet-39ba161d724adf7f5003da872aeb2f5378eb8582.zip |
add TODO notes in doc/documentation
Signed-off-by: Nils Gillmann <ng0@n0.is>
Diffstat (limited to 'doc')
-rw-r--r-- | doc/documentation/README.txt | 63 | ||||
-rw-r--r-- | doc/documentation/TODO | 106 |
2 files changed, 106 insertions, 63 deletions
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" | ||