mirror of https://github.com/djcb/mu.git
* many: documentation updates
This commit is contained in:
parent
0fadc5e360
commit
8146cdb8b1
49
HACKING
49
HACKING
|
@ -1,15 +1,15 @@
|
||||||
* HACKING
|
* HACKING
|
||||||
|
|
||||||
Here are some guidelines for hacking on the 'mu' source code. This is fairly
|
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
|
long list -- this is not meant to discourage anyone from working on mu; I
|
||||||
source code; I think most of the rules are common sense anyway, and some of
|
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,
|
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
|
so as long as any new code 'fits in', it should go a long way in satisfying
|
||||||
the rules.
|
them.
|
||||||
|
|
||||||
** Coding style
|
** 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:
|
follows the following rules:
|
||||||
|
|
||||||
1. basic code layout is like in the Linux kernel coding style, with the '{'
|
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++)
|
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
|
3. functions must not exceed 40 lines (there could be rare exceptions,
|
||||||
30 lines is already pretty long. You can easily check if any functions
|
currently there are none in mu), and 30 lines is already pretty long. You
|
||||||
violate this rule with 'make line33', which lists all functions with
|
can easily check if any functions violate this rule with 'make line33',
|
||||||
more than 33 non-comment lines.
|
which lists all functions with more than 33 non-comment lines.
|
||||||
|
|
||||||
4. source files should not exceed 1000 lines
|
4. source files should not exceed 1000 lines
|
||||||
|
|
||||||
5. a function's cyclomatic complexity should not exceed 10 (there may be
|
5. a function's cyclomatic complexity should not exceed 10 (there could be
|
||||||
rare exceptions). You can test the cyclomatic complexity with the
|
rare exceptions, currently there are none in mu). You can test the
|
||||||
pmccabe tool; if you installed that, you can use 'make cc10' to list all
|
cyclomatic complexity with the pmccabe tool; if you installed that, you
|
||||||
functions that violate this rule; there should be none.
|
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')
|
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
|
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
|
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
|
** Logging
|
||||||
|
|
||||||
For logging, mu uses the GLib logging functions/macros as listed below,
|
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
|
use MU_LOG_WRITE, as defined in mu-util.h
|
||||||
|
|
||||||
|
|
||||||
#+ Local Variables: ***
|
# Local Variables:
|
||||||
#+ mode:org ***
|
# mode: org; org-startup-folded: nil
|
||||||
#+ End: ***
|
# End:
|
||||||
|
|
||||||
|
|
||||||
|
|
15
NEWS
15
NEWS
|
@ -3,7 +3,7 @@
|
||||||
** Release 0.8 (beta) <2010-10-23 Sat>
|
** Release 0.8 (beta) <2010-10-23 Sat>
|
||||||
|
|
||||||
- There's now 'mu extract' for getting information about MIME-parts
|
- 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
|
- Queries are now internally converted to lowercase; this solves some of the
|
||||||
false-negative issues
|
false-negative issues
|
||||||
- All mu sub-commands now have their own man-page
|
- All mu sub-commands now have their own man-page
|
||||||
|
@ -11,10 +11,9 @@
|
||||||
up-to-n lines of the message
|
up-to-n lines of the message
|
||||||
- Same for 'mu view'; the summary replaces the full body
|
- Same for 'mu view'; the summary replaces the full body
|
||||||
- Setting the mu home dir now goes with -m, --muhome
|
- Setting the mu home dir now goes with -m, --muhome
|
||||||
- log-stderr does not have a single-char version anymore
|
- --log-stderr, --reindex, --rebuild, --autoupgrade, --nocleanup, --mode,
|
||||||
- --reindex, --rebuild, --autoupgrade, --nocleanup lost their single char version
|
--linksdir, --clearlinks lost their single char version
|
||||||
- --mode lost its single char version
|
|
||||||
|
|
||||||
** Release 0.7 <2010-02-27 Sat>
|
** Release 0.7 <2010-02-27 Sat>
|
||||||
- Database format changed
|
- Database format changed
|
||||||
- Automatic database scheme version check, notifies users when an upgrade
|
- Automatic database scheme version check, notifies users when an upgrade
|
||||||
|
@ -36,3 +35,9 @@
|
||||||
** Release 0.6 <2010-01-23 Sat>
|
** Release 0.6 <2010-01-23 Sat>
|
||||||
- First new release of mu since 2008
|
- First new release of mu since 2008
|
||||||
- No longer depends on sqlite
|
- No longer depends on sqlite
|
||||||
|
|
||||||
|
# Local Variables:
|
||||||
|
# mode: org; org-startup-folded: nil
|
||||||
|
# End:
|
||||||
|
|
||||||
|
|
||||||
|
|
6
TODO
6
TODO
|
@ -1,6 +1,3 @@
|
||||||
#-*-mode:org-*-
|
|
||||||
#+STARTUP:showall
|
|
||||||
|
|
||||||
* Future release
|
* Future release
|
||||||
|
|
||||||
** release 0.9 [%]
|
** release 0.9 [%]
|
||||||
|
@ -77,3 +74,6 @@
|
||||||
- [X] cleanup ascending/descending stuff
|
- [X] cleanup ascending/descending stuff
|
||||||
- [X] testing
|
- [X] testing
|
||||||
|
|
||||||
|
# Local Variables:
|
||||||
|
# mode: org; org-startup-folded: nil
|
||||||
|
# End:
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH MU CLEANUP 1 "September 2010" "User Manuals"
|
.TH MU CLEANUP 1 "October 2010" "User Manuals"
|
||||||
|
|
||||||
.SH NAME
|
.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
|
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
|
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
|
.SH BUGS
|
||||||
|
|
||||||
Please report bugs if you find them:
|
Please report bugs if you find them:
|
||||||
|
|
|
@ -1,4 +1,4 @@
|
||||||
.TH MU-EASY 1 "September 2010" "User Manuals"
|
.TH MU-EASY 1 "October 2010" "User Manuals"
|
||||||
|
|
||||||
.SH NAME
|
.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 --
|
extensive information in the man page about the sub-command you are using --
|
||||||
for example, the mu-index or mu-find man pages.
|
for example, the mu-index or mu-find man pages.
|
||||||
|
|
||||||
\fBNOTE\fR: the 'index' command (and therefore, the ones that depend on
|
\fBNOTE\fR: the \fBindex\fR command (and therefore, the ones that depend on
|
||||||
that, 'cleanup' and 'search'), require that you store your mail in the
|
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
|
Maildir-format. If you don't do so, you can still use the other commands, but
|
||||||
cannot index/search your mail.
|
cannot index/search your mail.
|
||||||
|
|
||||||
.SH INDEXING YOUR E-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
|
.nf
|
||||||
\fB$ mu index\fR
|
\fB$ mu index\fR
|
||||||
.fi
|
.fi
|
||||||
|
|
||||||
The process can take a few minutes, depending on the amount of mail you
|
The process can take a few minutes, depending on the amount of mail you have,
|
||||||
have, the speed of your computer, drive etc. Usually, indexing should be able
|
the speed of your computer, hard drive etc. Usually, indexing should be able to
|
||||||
to reach a speed of a few hundred messages per second.
|
reach a speed of a few hundred messages per second.
|
||||||
|
|
||||||
Indexing gives some progress information, and it shows which directories it is
|
\fBmu index\fR guesses the top-level Maildir to do its job; if it guesses
|
||||||
indexing. If the Maildir-directory it guessed is not the right one, you can
|
wrong, you can use the \fI--maildir\fR option to specify the top-level
|
||||||
use the \fI--maildir\fR option. See the \fBmu-index\fR man page for more
|
directory that should be processed. See the \fBmu-index\fR man page for more
|
||||||
detail.
|
detail.
|
||||||
|
|
||||||
Note, you
|
|
||||||
|
|
||||||
.SH SEARCHING YOUR E-MAIL
|
.SH SEARCHING YOUR E-MAIL
|
||||||
After you have indexed your mail, you can search it. Normally, the search
|
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
|
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.
|
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 --
|
By default, \fBmu\fR uses the logical AND for the search parameters -- that
|
||||||
that is, it displays messages that match all the parameters. However, we can
|
is, it displays messages that match all the parameters. However, we can use
|
||||||
use logical \fBor\fR as well:
|
logical OR as well:
|
||||||
|
|
||||||
.nf
|
.nf
|
||||||
\fB$ mu find t:julius OR f:socrates\fR
|
\fB$ mu find t:julius OR f:socrates\fR
|
||||||
|
|
|
@ -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
|
database etc. If it receives another signal (e.g,, when pressing Ctrl-C once
|
||||||
more), \fBmu index\fR will terminate immediately.
|
more), \fBmu index\fR will terminate immediately.
|
||||||
|
|
||||||
.SS Indexing options
|
.SH OPTIONS
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
\fB\-m\fR, \fB\-\-maildir\fR=\fI<maildir>\fR
|
\fB\-m\fR, \fB\-\-maildir\fR=\fI<maildir>\fR
|
||||||
|
|
18
man/mu.1
18
man/mu.1
|
@ -1,4 +1,4 @@
|
||||||
.TH MU 1 "September 2010" "User Manuals"
|
.TH MU 1 "October 2010" "User Manuals"
|
||||||
|
|
||||||
.SH NAME
|
.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.
|
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
|
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.
|
clients. Note: the various sub-commands have their own manpages.
|
||||||
|
|
||||||
.SH COMMANDS
|
.SH COMMANDS
|
||||||
|
@ -53,7 +53,8 @@ corresponding message file in the file system. See
|
||||||
\.
|
\.
|
||||||
|
|
||||||
.TP
|
.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
|
parameters. See
|
||||||
.BR mu-find(1)
|
.BR mu-find(1)
|
||||||
\.
|
\.
|
||||||
|
@ -70,22 +71,23 @@ for creating Maildirs. See
|
||||||
.BR mu-mkdir(1)
|
.BR mu-mkdir(1)
|
||||||
\.
|
\.
|
||||||
|
|
||||||
|
|
||||||
.TP
|
.TP
|
||||||
\fBextract\fR
|
\fBextract\fR
|
||||||
for extract MIME-parts (such as attachments) from messages. See
|
for extract MIME-parts (such as attachments) from messages. See
|
||||||
.BR mu-extract(1)
|
.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,
|
while the other ones work on invidual mail files. Hence, running \fview\fR,
|
||||||
\fBmkdir\fR and \fBextract\fR does not require the mu database.
|
\fBmkdir\fR and \fBextract\fR does not require the mu database.
|
||||||
|
|
||||||
.TP
|
|
||||||
The various commands are discussed in more detail in their own separate
|
The various commands are discussed in more detail in their own separate
|
||||||
man-pages; here the general options are discussed.
|
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,
|
\fBmu\fR offers a number of general options that apply to all commands,
|
||||||
including \fBmu\fR without any command.
|
including \fBmu\fR without any command.
|
||||||
|
|
Loading…
Reference in New Issue