doc/documentation/README.txt

   1 To be moved to an appropriate section of "how to write documentation" or
   2 "how to contribute to the documentation":
   3
   4 1. When writing documentation, please use gender-neutral wording when
   5    referring to people, such as singular “they”, “their”, “them”, and
   6    so forth. -> https://en.wikipedia.org/wiki/Singular_they
   7
   8 2. Keep line length below 74 characters.
   9    - Expection by texi2pdf output so far: URLs will break
  10      (inserted whitespace) when they contain linebreaks
  11      within the @url{} / @uref{}.
  12
  13 3. Do not use tab characters (see chapter 2.1 texinfo manual)
  14
  15 4. Use neutral language and third person perspective in the text
  16
  17 4.1 So, when you refer to a user in general or addressing the user,
  18     refer to (1).
  19 4.1.1 Unsolved exceptions for canonical reasons:
  20       When refering to Alice, use "she".
  21       When refering to Bob, use "he".
  22       These are long established examples and they
  23       should either be replaced (avoid Alice and Bob
  24       examples when you can) or followed.
  25
  26 5. Use 2 spaces between sentences, so instead of:
  27
  28      We do this and the other thing. This is done by foo.
  29
  30    Write:
  31
  32      We do this and the other thing.  This is done by foo.
  33
  34 6. Use @footnote{} instead of putting an @*ref{} to the footnote on a
  35    collected footnote-page.
  36    In a 200+ pages handbook it's better to have footnotes accessible
  37    without having to skip over to the end.
  38
  39 6.1 Avoid unnecessary footnotes, keep the text self-explanatory and
  40     in a simple language where possible/necessary.
  41
  42 * Completion Levels:
  43
  44 ** chapters/philosophy: around 100% fixed after initial export.
  45
  46 * What's left to do
  47
  48 - Which Texlive modules are needed? Decrease the size.
  49   - distro specific, or can we set requirements?
  50 - Update the content of gnunet documentation.
  51 - XXX: images are only generated for the html documentation
  52   with gendoc.sh … FIXME!
  53 - XXX: png,dot, and svg images MUST be converted to eps by the
  54   build system. Right now they aren't, as a result: No images.
  55
  56 * How to use (hack) on this
  57
  58 ** with guix
  59
  60 Adjust accordingly, ie read the Guix Documentation:
  61 setenv GUIX_PACKAGE_PATH "gnunet/contrib/packages/guix/packages"
  62 guix environment gnunet-doc
  63 and
  64 guix build -f contrib/packages/guix/gnunet-doc.scm
  65
  66 ** without guix
  67
  68 You need to have Texinfo and Texlive in your path.
  69 sh bootstrap
  70 ./configure --enable-documentation
  71 cd doc
  72 make (format you want)
  73
  74 for example: make html, make info, make pdf
  75
  76 * structure (relations)
  77
  78 ** gnunet.texi
  79  -> chapters/developer.texi
  80  -> chapters/installation.texi
  81  -> chapters/philosophy.texi
  82  -> chapters/user.texi
  83  -> chapters/vocabulary.texi
  84  -> images/*
  85  -> gpl-3.0.texi
  86  -> fdl-1.3.texi
  87
  88 ** gnunet-c-tutorial.texi
  89  -> figs/Service.pdf
  90  -> figs/System.pdf
  91  -> tutorial-examples/*.c
  92  -> gpl-3.0.texi
  93  -> fdl-1.3.texi
  94
  95 - gnunet-c-tutorial-v1.pdf: original LaTeX "gnunet-c-tutorial.pdf".
  96 - man folder: the man pages.
  97 - doxygen folder
  98 - outdated-and-old-installation-instructions.txt: self described within the file.
  99
 100
 101 Use `gendocs', add to the manual/ directory of the web site.
 102
 103   $ cd doc
 104   $ gendocs.sh gnunet "GNUnet 0.10.X Reference Manual"