Documentation: Add doc/TODO with some items still open

diff --git a/ChangeLog b/ChangeLog
index c71f7073d01cb8c4e4046b9e29a9ece745b7f445..1d9cd2924182434396c6195a9aca4b948a654a2c 100644 (file)
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2007-11-01 13:43 +0100  Rocco Rutte  <pdmef@gmx.net>  (a9e37e90ad40)
+
+       * doc/manual.xml.head: Manual: s/SMTP support/SMTP Support/ (for
+       consitency)
+
+2007-11-01 13:01 +0100  Rocco Rutte  <pdmef@gmx.net>  (13f21ce1d474)
+
+       * ChangeLog, doc/manual.xml.head: Manual: Remove 404 link for
+       fetchmail, mention getmail, too
+
 2007-11-01 12:56 +0100  Rocco Rutte  <pdmef@gmx.net>  (69ba99747f3e)
 
        * doc/manual.xml.head: Manual: Add short section on SSL/TLS support

diff --git a/doc/TODO b/doc/TODO
new file mode 100644 (file)
index 0000000..76b0c38
--- /dev/null
+++ b/doc/TODO
@@ -0,0 +1,57 @@
+Documentation TODO in no particular order grouped by style and content.
+
+It would be nice to get some of these done for 1.6.
+
+Style/Technical
+---------------
+
+* Re-check complete manual for consistency. The same things need to be
+  consistently marked up, e.g. an item either always as <literal/> or
+  always <emphasis/> (decide clearly which to use for what), make sure
+  all option refs are links, things are consistently quoted.
+  E.g. it has:
+
+    If the filename begins with a tilde (``&tilde;'')
+
+  and
+
+    If the filename ends with a vertical bar (&verbar;)
+
+  We need to choose either style and use it. Probably we want to add
+  a short typography section explaining layout details.
+
+* Think about some way of templating to a) help improve consistency
+  (i.e. some sort of macro to refer to key, options, functions, etc.)
+  and b) reduce typing overhead.
+
+    <link linkend="pipe-split">&dollar;pipe&lowbar;split</link>
+
+  is neither fun to read nor to write. This would give us lots of
+  options to improve it (e.g. an automated index). We depend on
+  perl already to build docs, think about/look for simple perl
+  templating engine.
+
+* Maybe add a mutt.css to contrib to make it look better.
+
+* As for sending patches, maybe add a short text file for documentation
+  hackers with guidelines. (Though nobody really seems to provide input
+  on the manual)
+
+* Find a way (XSLT?) to trim the TOC for the option reference; it's
+  ugly but we probably want to keep the TOC depth as-is for other
+  sections.
+
+Content
+-------
+
+* Especially the introduction needs to be reworked quite a bit,
+  the current reference-like way is unfriendly for new users. There
+  should be an introduction chapter explaining concepts (config, menus,
+  hooks, etc.) E.g. the intro for hooks should come _before_ their
+  syntactical definition, not after.
+
+* Some sections maybe should be better grouped by topic, instead of
+  one section per task (e.g. hooks should be grouped under a section
+  'hooks' in the config chapter).
+
+* Talk a lot more about character sets and encodings.