diff --git a/man/mu-server.1 b/man/mu-server.1 index 43b91c94..d90412ed 100644 --- a/man/mu-server.1 +++ b/man/mu-server.1 @@ -1,8 +1,8 @@ -.TH MU-SERVER 1 "January 2012" "User Manuals" +.TH MU-SERVER 1 "April 2012" "User Manuals" .SH NAME -mu server \- the mu backend for the mu4e e-mail cleint +mu server \- the mu backend for the mu4e e-mail client .SH DESCRIPTION @@ -12,7 +12,22 @@ database. The output of the commands is terms of Lisp symbolic expressions designed specifically for the \fBmu4e\fR e-mail client. In this man-page, we document the commands \fBmu server\fR accepts, as well as -their responses. +their responses. In general, the commands sent to the server are of the form + +.nf + []* +.fi + +where each of the parameters is prefixed by their name and a colon. For +example, to view a certain message, the command would be: + +.nf + view docid:12345 +.fi + +Parameters can be sent in any order, and parameters not used by a certain +command are simply ignored. + .SH OUTPUT FORMAT @@ -33,110 +48,16 @@ occur in valid UTF-8 (in which the s-expressions are encoded). .SH COMMAND AND RESPONSE - .TP -.B ping +.B add -The \fBping\fR command provokes a \fBpong\fR response. It is used for the initial -handshake between \fBmu4e\fR and \fBmu server\fR. -.nf --> ping -<- (:pong "mu" :version :doccount ) -.fi - -.TP -.B find - -Using the \fBfind\fR command we can search for messages. -.nf --> find "" -.fi -First, this will return an 'erase'-sexp, to clear the buffer from possible -results from a previous query. -.nf -<- (:erase t) -.fi - -This will return a series of 0 up to s-expression corresponding to each -message found (with a negative number for meaning 'unlimited'). The -information for each message does not contain the message body; the \fBview\fR -command is for that. -.nf -<- (...) -.fi -and finally, we receive: -.nf -<- (:found ) -.fi - - -.TP -.B move - -Using the \fBmove\fR command, we can move messages to another maildir, and -update the database correspondingly. The function returns an s-exp describing -the updated message, so that it can be updated in the user interface. +Using the \fBadd\fR command, we can add a message to the database. .nf --> move [] -<- (:update :move t) +-> add path: maildir: +<- (:info add :path :docid ) .fi -.TP -.B flag - -Using the \fBflag\fR command, we can change the message flags - note that this -may imply moving the message to another maildir, when the 'N' (new) flag -changes. Update the database correspondingly. The function returns an s-exp -describing the updated message, so that it can be updated in the user -interface. - -.nf --> move [] -<- (:update :move nil) -.fi - -.TP -.B remove - -Using the \fBremove\fR command, we can remove the message from disk, and -update the database accordingly. - -.nf --> remove -<- (:remove ) -.fi - -.TP -.B save - -Using the \fBsave\fR command, we can save an attachment from a message to disk. - -.nf --> save -<- (:info save :message " has been saved") -.fi - -.TP -.B open - -Using the \fBopen\fR command, we can open an attachment file. -.nf --> open -<- (:info open :message " has been opened") -.fi - - -.TP -.B view - -Using the \fBview\fR command, we can all information (including the body) of a -particular e-mail message. - -.nf --> view -<- (:view ) -.fi .TP .B compose @@ -145,9 +66,11 @@ Using the \fBcompose\fR command, we get the (original) message, and tell what to do with it. The user-interface is then expected to pre-process the message, e.g. set the subject, sender and recipient for a reply message. +Messages of type 'new' don't use the docid: parameter, the other ones do. + .nf --> compose -<- (:compose-type :original :include ( compose [docid:] +<- (:compose :original :include ( is an s-expression describing the attachments to @@ -159,6 +82,64 @@ forwarding. This s-exprssion looks like: .fi +.TP +.B extract + +Using the \fBextract\fR command we can save and open attachments. +.nf +-> extract action: index: [path:] [what: [param:]] +.fi + +If the action is 'save', the path argument is required; the attachment will +be saved, and a message +.nf +<- (:info save :message "... has been saved") +.fi +is sent. + +If the action is 'open', the attachment will saved to a temporary file, after +which it will be opened with the default handler for this kind of file (see +\fBmu-extract(1)\fR), and a message +.nf +<- (:info open :message "... has been opened") +.fi +is sent. + +If the action is 'temp', the arguments 'what' is required. The attachment will +saved to a temporary file, and the following message is sent: +.nf +<- (:temp :what :param find query:"" [maxnum:] +.fi +First, this will return an 'erase'-sexp, to clear the buffer from possible +results from a previous query. +.nf +<- (:erase t) +.fi + +This will return a series of 0 up to s-expression corresponding to +each message found (if there's no maxnum, all results will be returned). The +information message s-exps this function returns do not contain the message +body; the \fBview\fR command is for that. +.nf +<- (...) +.fi +and finally, we receive: +.nf +<- (:found ) +.fi + + .TP .B index @@ -166,7 +147,7 @@ Using the \fBindex\fR command, we can (re)index the database, similar to what \fBmu find\fR does. .nf --> index +-> index path: .fi As a response, it will send (for each 500 messages): .nf @@ -178,43 +159,66 @@ and finally: :cleaned-up ) .fi - -.TP -.B add - -Using the \fBadd\fR command, we can add a message to the database. - -.nf --> add -<- (:info add :path :docid ) -.fi - - -.TP -.B sent - -With the \fBsent\fR command, we tell the backend that a message will be sent. - -.nf --> sent -<- (:sent :path :docid ) -.fi - -In the frontend, this message can then be used to trigger moving the message -from the draft folder to the sent folder, setting the Replied/Passed flags on -the parent messages. - - .TP .B mkdir Using the \fBmkdir\fR command, we can create a new maildir. .nf --> mkdir +-> mkdir path: <- (:info mkdir :message " has been created") .fi +.TP +.B move + +Using the \fBmove\fR command, we can move messages to another maildir or +change its flags (which ultimately means it is being move to a different +filename), and update the database correspondingly. The function returns an +s-exp describing the updated message, so that it can be updated in the user +interface. + +.nf +-> move docid:|msgid: [maildir:] [flags:] +<- (:update :move t) +.fi + +One of docid and msgid must be specified to identify the message. At least one +of maildir and flags must be specified. + + +.TP +.B ping + +The \fBping\fR command provokes a \fBpong\fR response. It is used for the initial +handshake between \fBmu4e\fR and \fBmu server\fR. +.nf +-> ping +<- (:pong "mu" :version :doccount ) +.fi + +.TP +.B remove + +Using the \fBremove\fR command, we can remove the message from disk, and +update the database accordingly. + +.nf +-> remove docid: +<- (:remove ) +.fi + + +.TP +.B view + +Using the \fBview\fR command, we can all information (including the body) of a +particular e-mail message. + +.nf +-> view docid:|msgid: +<- (:view ) +.fi .SH AUTHOR