From: Rocco Rutte Date: Thu, 1 Nov 2007 13:23:30 +0000 (+0100) Subject: Documentation: Add doc/TODO with some items still open X-Git-Tag: mutt-1-5-17-rel~5 X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=39f69f01cd583633439b7aa4690b70c148ad3f0f;p=mutt Documentation: Add doc/TODO with some items still open --- diff --git a/ChangeLog b/ChangeLog index c71f7073..1d9cd292 100644 --- a/ChangeLog +++ b/ChangeLog @@ -1,3 +1,13 @@ +2007-11-01 13:43 +0100 Rocco Rutte (a9e37e90ad40) + + * doc/manual.xml.head: Manual: s/SMTP support/SMTP Support/ (for + consitency) + +2007-11-01 13:01 +0100 Rocco Rutte (13f21ce1d474) + + * ChangeLog, doc/manual.xml.head: Manual: Remove 404 link for + fetchmail, mention getmail, too + 2007-11-01 12:56 +0100 Rocco Rutte (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 index 00000000..76b0c38c --- /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 or + always (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 (``˜'') + + and + + If the filename ends with a vertical bar (|) + + 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. + + $pipe_split + + 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.