* many: documentation updates

HACKING

@@ -1,15 +1,15 @@
 * HACKING
 
   Here are some guidelines for hacking on the 'mu' source code. This is fairly
-  long list -- this is not meant to discourage anyone from working on the mu
-  source code; I think most of the rules are common sense anyway, and some of
+  long list -- this is not meant to discourage anyone from working on mu; I
+  think most of the rules are common sense anyway (or should be), and some of
   the more stylistic-aesthetic rules are clearly visible in current source code,
   so as long as any new code 'fits in', it should go a long way in satisfying
-  the rules.
+  them.
 
 ** Coding style
 
-   For consistency and even more important, to keep things understandable, mu
+   For consistency and, even more important, to keep things understandable, mu
    follows the following rules:
 
    1. basic code layout is like in the Linux kernel coding style, with the '{'
@@ -18,17 +18,18 @@
 
    2. lines must not exceed 80 characters (C) or 100 characters (C++)
 
-   3. functions must not exceed 40 lines (there may be rare exceptions), and
-      30 lines is already pretty long. You can easily check if any functions
-      violate this rule with 'make line33', which lists all functions with
-      more than 33 non-comment lines.
+   3. functions must not exceed 40 lines (there could be rare exceptions,
+      currently there are none in mu), and 30 lines is already pretty long. You
+      can easily check if any functions violate this rule with 'make line33',
+      which lists all functions with more than 33 non-comment lines.
 
    4. source files should not exceed 1000 lines
 
-   5. a function's cyclomatic complexity should not exceed 10 (there may be
-      rare exceptions). You can test the cyclomatic complexity with the
-      pmccabe tool; if you installed that, you can use 'make cc10' to list all
-      functions that violate this rule; there should be none.
+   5. a function's cyclomatic complexity should not exceed 10 (there could be
+      rare exceptions, currently there are none in mu). You can test the
+      cyclomatic complexity with the pmccabe tool; if you installed that, you
+      can use 'make cc10' to list all functions that violate this rule; there
+      should be none.
 
    6. filenames have their components separated with dashes (e.g, 'mu-log.h')
 
@@ -58,6 +59,21 @@
    11. returned strings of type char* must be freed by the caller; if they are
        not to be freed, 'const char*' should be used instead
 
+   12. functions calls have a space between function name and arguments, unless
+       there are none, so:
+
+	foo(12, 3);
+
+       and
+
+	bar();
+
+       after a comma, a space should follow.
+
+   13. functions that do not take arguments are explicitly declared as f(void)
+       and not f(). Reason: f() means that the arguments are /unspecified/ (in
+       C)
+
 ** Logging
    
    For logging, mu uses the GLib logging functions/macros as listed below,
@@ -79,7 +95,8 @@
    use MU_LOG_WRITE, as defined in mu-util.h
 
 
-#+ Local Variables: ***
-#+ mode:org ***
-#+ End: ***
-       
+# Local Variables:
+# mode: org; org-startup-folded: nil
+# End:
+   
+   

NEWS

@@ -3,7 +3,7 @@
 ** Release 0.8 (beta) <2010-10-23 Sat>
    
    - There's now 'mu extract' for getting information about MIME-parts
-     (attachments) and saving them
+     (attachments) and extracting them
    - Queries are now internally converted to lowercase; this solves some of the
      false-negative issues
    - All mu sub-commands now have their own man-page
@@ -11,10 +11,9 @@
      up-to-n lines of the message
    - Same for 'mu view'; the summary replaces the full body
    - Setting the mu home dir now goes with -m, --muhome
-   - log-stderr does not have a single-char version anymore
-   - --reindex, --rebuild, --autoupgrade, --nocleanup lost their single char version
-   - --mode lost its single char version
-  
+   - --log-stderr, --reindex, --rebuild, --autoupgrade, --nocleanup, --mode,
+     --linksdir, --clearlinks lost their single char version
+     
 ** Release 0.7 <2010-02-27 Sat>
    - Database format changed
    - Automatic database scheme version check, notifies users when an upgrade
@@ -36,3 +35,9 @@
 **  Release 0.6 <2010-01-23 Sat> 
     - First new release of mu since 2008
     - No longer depends on sqlite
+
+# Local Variables:
+# mode: org; org-startup-folded: nil
+# End:
+
+

TODO

@@ -1,6 +1,3 @@
-#-*-mode:org-*-
-#+STARTUP:showall
-
 * Future release
 
 ** release 0.9 [%]
@@ -77,3 +74,6 @@
    - [X] cleanup ascending/descending stuff
    - [X] testing
 
+# Local Variables:
+# mode: org; org-startup-folded: nil
+# End:

man/mu-cleanup.1

@@ -1,4 +1,4 @@
-.TH MU CLEANUP 1 "September 2010" "User Manuals"
+.TH MU CLEANUP 1 "October 2010" "User Manuals"
 
 .SH NAME 
 
@@ -15,15 +15,11 @@ database that are no longer present in the file system.
 
 The \fBcleanup\fR command removes messages for which no corresponding file can
 be found, from the database. Note that this is done automatically when running
-\fBmu index\fR (unless \fB\-\-nocleanup\fR was specified). 
+\fBmu index\fR (unless \fB\-\-nocleanup\fR was specified).
 
-.SH ENVIRONMENT
+\fBmu cleanup\fR does not remove messages that are outside the currently
+specified Maildir as long as they still exist.
 
-Like \fBmu index\fR, \fBmu cleanup\fR uses \fBMAILDIR\fR to find the user's
-Maildir if it has not been specified explicitly with
-\fB\-\-maildir\fR=\fI<maildir>\fR. If MAILDIR is not set, \fBmu cleanup\fR will
-try \fI~/Maildir\fR.
-.
 .SH BUGS
 
 Please report bugs if you find them:

man/mu-easy.1

@@ -1,4 +1,4 @@
-.TH MU-EASY 1 "September 2010" "User Manuals"
+.TH MU-EASY 1 "October 2010" "User Manuals"
 
 .SH NAME 
 
@@ -14,29 +14,27 @@ described here do not precisely do what you want, please check the more
 extensive information in the man page about the sub-command you are using --
 for example, the mu-index or mu-find man pages.
 
-\fBNOTE\fR: the 'index' command (and therefore, the ones that depend on
-that, 'cleanup' and 'search'), require that you store your mail in the
+\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that depend on
+that, such as \fBfind\fR), require that you store your mail in the
 Maildir-format. If you don't do so, you can still use the other commands, but
 cannot index/search your mail.
 
 .SH INDEXING YOUR E-MAIL
-Before you can search e-mails, you'll first need to index them: 
+Before you can search e-mails, you'll first need to index them:
 
 .nf
 \fB$ mu index\fR 
 .fi
 
-The process can take a few minutes, depending on the amount of mail you
-have, the speed of your computer, drive etc. Usually, indexing should be able
-to reach a speed of a few hundred messages per second. 
+The process can take a few minutes, depending on the amount of mail you have,
+the speed of your computer, hard drive etc. Usually, indexing should be able to
+reach a speed of a few hundred messages per second.
 
-Indexing gives some progress information, and it shows which directories it is
-indexing. If the Maildir-directory it guessed is not the right one, you can
-use the \fI--maildir\fR option. See the \fBmu-index\fR man page for more
+\fBmu index\fR guesses the top-level Maildir to do its job; if it guesses
+wrong, you can use the \fI--maildir\fR option to specify the top-level
+directory that should be processed. See the \fBmu-index\fR man page for more
 detail.
 
-Note, you 
-
 .SH SEARCHING YOUR E-MAIL
 After you have indexed your mail, you can search it. Normally, the search
 results are to standard output, but the output can also be in the form of
@@ -78,9 +76,9 @@ return something like:
 
 This is the same message found before, only with some different fields displayed.
 
-By default, \fBmu\fR uses the logical \fBand\fR for the search parameters --
-that is, it displays messages that match all the parameters. However, we can
-use logical \fBor\fR as well:
+By default, \fBmu\fR uses the logical AND for the search parameters -- that
+is, it displays messages that match all the parameters. However, we can use
+logical OR as well:
 
 .nf
 \fB$ mu find t:julius OR f:socrates\fR 

man/mu-index.1

@@ -50,7 +50,7 @@ tries to shutdown gracefully; it tries to save and commit data, and close the
 database etc. If it receives another signal (e.g,, when pressing Ctrl-C once
 more), \fBmu index\fR will terminate immediately.
 
-.SS Indexing options
+.SH OPTIONS
 
 .TP
 \fB\-m\fR, \fB\-\-maildir\fR=\fI<maildir>\fR

man/mu.1

@@ -1,4 +1,4 @@
-.TH MU 1 "September 2010" "User Manuals"
+.TH MU 1 "October 2010" "User Manuals"
 
 .SH NAME 
 
@@ -29,9 +29,9 @@ scanning a Maildir directory tree and analyzing the e-mail messages found. The
 results of this analysis are stored in a database, which can then be queried.
 
 In addition to indexing and searching, \fBmu\fR also offers functionality for
-viewing messages and creating maildirs.
+viewing messages, extracting attachments and creating maildirs.
 
-\fBmu\fR can be used from the command line, or can be integrated with e-mail
+\fBmu\fR can be used from the command line or can be integrated with e-mail
 clients. Note: the various sub-commands have their own manpages.
 
 .SH COMMANDS
@@ -53,7 +53,8 @@ corresponding message file in the file system. See
 \.
 
 .TP
-\fBfind\fR for finding messages in your database, using certain search
+\fBfind\fR
+for finding messages in your database, using certain search
 parameters. See
 .BR mu-find(1)
 \.
@@ -70,22 +71,23 @@ for creating Maildirs. See
 .BR mu-mkdir(1)
 \.
 
-
 .TP
 \fBextract\fR
 for extract MIME-parts (such as attachments) from messages. See
 .BR mu-extract(1)
 \.
 
-Subcommands \findex\fR, \ffind\fR and \cleanup\fR work with the database,
+
+.SH " "
+
+Commands \fBmu index\fR, \fBfind\fR and \fBcleanup\fR work with the database,
 while the other ones work on invidual mail files. Hence, running \fview\fR,
 \fBmkdir\fR and \fBextract\fR does not require the mu database.
 
-.TP
 The various commands are discussed in more detail in their own separate
 man-pages; here the general options are discussed.
 
-.SH GENERAL OPTIONS
+.SH OPTIONS
 
 \fBmu\fR offers a number of general options that apply to all commands,
 including \fBmu\fR without any command.