TODO 3.7 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106
  1. -*- mode: org -*-
  2. TODO - or: the Documentation Masterplan.
  3. To some extent this duplicates the Mantis tickets on this topic.
  4. * Motivation
  5. My motivation is to read into good documentations and create a self-contained collection of books,
  6. which can be understood without expecting too much background knowledge in every topic.
  7. ** User Handbook:
  8. The content of the User book should be mostly concerned with our current and future graphical (gtk
  9. as well as terminal user interface) applications. After reading Preface and maybe Philosophy, the
  10. person reading the User Handbook should understand with the least possible strugle the application
  11. they intend to use. Examples should be given and concepts explained.
  12. ** Installation Handbook:
  13. As seen with requests on the mailinglist, we will have to pick up people where they are, similar
  14. to the User Handbook. People already used to compiling and installing should have the chance to
  15. skip to the end, everyone else should: have step-by-step instructions, which will either already
  16. include OS specific notes or will be followed by OS specific instructions. It is up for discussion
  17. if configuring GNUnet is 'User Handbook' or 'Installation Handbook', the current mixture in
  18. the Installation Handbook is not good.
  19. ** Contributors Handbook:
  20. This chapter could either be reduced to a couple of sections following the theme of 'contributing
  21. to GNUnet' or the chapter could be extended. If we extend it, we should explain a range of topics
  22. that can be useful for contributors. It can be understood as a recommended reading in addition to
  23. the Developer Handbook then, and the Developer Handbook could simply become a better commented
  24. reference for the code-base.
  25. ** Developer Handbook:
  26. As outlined in the last sentences, the Developer Handbook could be reduced to the necessary bits
  27. with enough comments to be understood without reading into the papers published over the years.
  28. * DONE 1. Drupal books export to LaTeX.
  29. * DONE 2. LaTeX conversion to Texinfo.
  30. * DONE 3. (initial) Fixup of syntax errors introduced in conversion chain.
  31. * TODO 4. Update content.
  32. * TODO 5. Create API Reference or similar
  33. * TODO 6. Create Concept Index
  34. * TODO 7. Create Procedure Index
  35. * TODO 8. Create Type Index
  36. * TODO 9. Create Functions Index
  37. * TODO 10. Properly address concerns and criticism people had/have on the old and current documentation.
  38. * TODO 11. Reorder structure
  39. * TODO more TODO.
  40. * Status Progress / Completion Levels
  41. ** chapters/philosophy: around 100% fixed after initial export.
  42. * System Integration Tasks
  43. * Which Texlive modules are needed for every output we generate?
  44. * Generate the images from their dot sources.
  45. * How to use (hack) on this
  46. This section will find its way into the documentation sooner or later.
  47. Potentially outdated or inaccurate bits.
  48. ** with guix
  49. Adjust accordingly, ie read the Guix Documentation:
  50. guix environment gnunet-doc
  51. and
  52. guix build -f contrib/packages/guix/gnunet-doc.scm
  53. ** without guix
  54. You need to have Texinfo and Texlive in your path.
  55. sh bootstrap
  56. ./configure --enable-documentation
  57. cd doc
  58. make (format you want)
  59. for example: make html, make info, make pdf
  60. * structure (relations) (old!)
  61. ** gnunet.texi
  62. -> chapters/developer.texi
  63. -> chapters/installation.texi
  64. -> chapters/philosophy.texi
  65. -> chapters/user.texi
  66. -> chapters/vocabulary.texi
  67. -> images/*
  68. -> gpl-3.0.texi
  69. -> fdl-1.3.texi
  70. ** gnunet-c-tutorial.texi
  71. -> figs/Service.pdf
  72. -> figs/System.pdf
  73. -> tutorial-examples/*.c
  74. -> gpl-3.0.texi
  75. -> fdl-1.3.texi
  76. - gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf".
  77. - man folder: the man pages.
  78. - doxygen folder
  79. - outdated-and-old-installation-instructions.txt: self described within the file.
  80. Use `gendocs', add to the manual/ directory of the web site.
  81. $ cd doc
  82. $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual"