doc/TODO

   1 Documentation TODO in no particular order grouped by style and content.
   2
   3 It would be nice to get some of these done for 1.6.
   4
   5 Style/Technical
   6 ---------------
   7
   8 * Re-check complete manual for consistency. The same things need to be
   9   consistently marked up, e.g. an item either always as <literal/> or
  10   always <emphasis/> (decide clearly which to use for what), make sure
  11   all option refs are links, things are consistently quoted.
  12   E.g. it has:
  13
  14     If the filename begins with a tilde (``&tilde;'')
  15
  16   and
  17
  18     If the filename ends with a vertical bar (&verbar;)
  19
  20   We need to choose either style and use it. Probably we want to add
  21   a short typography section explaining layout details.
  22
  23 * Think about some way of templating to a) help improve consistency
  24   (i.e. some sort of macro to refer to key, options, functions, etc.)
  25   and b) reduce typing overhead.
  26
  27     <link linkend="pipe-split">&dollar;pipe&lowbar;split</link>
  28
  29   is neither fun to read nor to write. This would give us lots of
  30   options to improve it (e.g. an automated index). We depend on
  31   perl already to build docs, think about/look for simple perl
  32   templating engine.
  33
  34 * Maybe add a mutt.css to contrib to make it look better.
  35
  36 * As for sending patches, maybe add a short text file for documentation
  37   hackers with guidelines. (Though nobody really seems to provide input
  38   on the manual)
  39
  40 * Find a way (XSLT?) to trim the TOC for the option reference; it's
  41   ugly but we probably want to keep the TOC depth as-is for other
  42   sections.
  43
  44 Content
  45 -------
  46
  47 * Especially the introduction needs to be reworked quite a bit,
  48   the current reference-like way is unfriendly for new users. There
  49   should be an introduction chapter explaining concepts (config, menus,
  50   hooks, etc.) E.g. the intro for hooks should come _before_ their
  51   syntactical definition, not after.
  52
  53 * Some sections maybe should be better grouped by topic, instead of
  54   one section per task (e.g. hooks should be grouped under a section
  55   'hooks' in the config chapter).
  56
  57 * Talk a lot more about character sets and encodings.