From ee1f8e9ae175c44b00a68d274d9fcf57570f7b91 Mon Sep 17 00:00:00 2001 From: Sam Varshavchik Date: Tue, 24 Sep 2019 18:40:16 -0400 Subject: Documentation fixes --- maildir/deliverquota.sgml | 8 +-- maildir/maildir.sgml | 146 +++++++++++++++++----------------------------- maildir/maildirmake.sgml | 28 ++++----- maildrop/maildrop.sgml | 26 ++++----- 4 files changed, 84 insertions(+), 124 deletions(-) diff --git a/maildir/deliverquota.sgml b/maildir/deliverquota.sgml index 5bfdd5f..9c59183 100644 --- a/maildir/deliverquota.sgml +++ b/maildir/deliverquota.sgml @@ -1,7 +1,7 @@ - + SamVarshavchikAuthorCourier Mail Server @@ -26,7 +26,7 @@ - + DESCRIPTION @@ -90,7 +90,7 @@ below - + RETURN CODE @@ -103,7 +103,7 @@ If the maildir is over its specified quota, deliverquot terminates with exit code 77 (EX_NOPERM). - + SEE ALSO diff --git a/maildir/maildir.sgml b/maildir/maildir.sgml index b296412..df2056b 100644 --- a/maildir/maildir.sgml +++ b/maildir/maildir.sgml @@ -1,7 +1,7 @@ - + SamVarshavchikAuthorCourier Mail Server @@ -19,24 +19,24 @@ $HOME/Maildir - + DESCRIPTION A Maildir is a structured directory that holds E-mail messages. Maildirs were first implemented by the -Qmail mail server. +Qmail mail server. Qmail's maildirs were a simple data structure, nothing more than a single collection of E-mail messages. -The Courier mail server builds upon -Qmail's maildirs to provide +The Courier mail server builds upon +Qmail's maildirs to provide extended functionality, such as folders and quotas. This document describes -the Courier mail server's extended +the Courier mail server's extended maildirs, without explicitly identifying -The Courier mail server-specific +The Courier mail server-specific extensions. See maildir5 @@ -67,7 +67,7 @@ Maildirs do not require locking. Multiple applications can update a maildir at the same time, without stepping on each other's feet. - + Maildir contents @@ -76,8 +76,8 @@ A maildir is a directory that's created by Naturally, maildirs should not have any group or world permissions, unless you want other people to read your mail. A maildir contains three subdirectories: -tmp, new, and -cur. +tmp, new, and +cur. These three subdirectories comprise the primary folder, where new mail is delivered by the system. @@ -85,12 +85,12 @@ is delivered by the system. Folders are additional subdirectories in the maildir whose names begin with a period: such as -.Drafts or .Sent. +.Drafts or .Sent. Each folder itself contains the -same three subdirectories, tmp, new, -and cur, +same three subdirectories, tmp, new, +and cur, and an additional zero-length file named -maildirfolder, whose purpose is to inform any mail +maildirfolder, whose purpose is to inform any mail delivery agent that it's really delivering to a folder, and that the mail delivery agent should look in the parent directory for any maildir-related information. @@ -98,91 +98,53 @@ any maildir-related information. Folders are not physically nested. A folder subdirectory, -such as .Sent +such as .Sent does not itself contain any subfolders. The main maildir contains a single, flat list of subfolders. These folders are logically nested, and periods serve to separate folder hierarchies. -For example, .Sent.2002 is considered to be a subfolder +For example, .Sent.2002 is considered to be a subfolder called 2002 which is a subfolder of Sent. - + Folder name encoding Folder names can contain any Unicode character, except for control characters. US-ASCII characters, U+0x0020 - U+0x007F, except for the period, -forward-slash, and -ampersand characters (U+0x002E, U+0x002F, and U+0x0026) represent themselves. -The ampersand is represent by the two character sequence &-. -The period, forward slash, and non US-ASCII Unicode characters -are represented using the UTF-7 character set, and encoded with -a modified form of base64-encoding. - - -The & -character starts the modified base64-encoded sequence; the sequence -is -terminated by the - character. -The sequence of 16-bit Unicode characters is -written in big-endian order, and -encoded using the base64-encoding method described in section 5.2 -of RFC 1521, -with the following modifications: - - - - -The = padding character is omitted. -When decoding, an incomplete 16-bit character is discarded. - - - - -The comma character, , is used in place of the -/ character in the base64 alphabet. - - - - -For example, the word Resume with both "e"s being the -e-acute character, U+0x00e9, -is encoded as -R&AOk-sum&AOk- -(so a folder of that name would be a maildir subdirectory called -.R&AOk-sum&AOk-). +and forward-slash. Non-Latin characters are encoded in UTF-8. - + Other maildir contents Software that uses maildirs may also create additional files besides the -tmp, new, and -cur subdirectories -- in the main maildir or a +tmp, new, and +cur subdirectories -- in the main maildir or a subfolder -- for its own purposes. - + Messages E-mail messages are stored in separate, individual files, one E-mail message per file. -The tmp subdirectory temporarily +The tmp subdirectory temporarily stores E-mail messages that are in the process of being delivered -to this maildir. tmp may also +to this maildir. tmp may also store other kinds of temporary files, as long as they are created in the same way that message files are -created in tmp. -The new subdirectory stores messages +created in tmp. +The new subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application. -The cur subdirectory stores messages that have +The cur subdirectory stores messages that have already been seen by mail applications. - + Adding new mail to maildirs The following process delivers a new message to the maildir: @@ -217,24 +179,24 @@ system call. If stat2 results in ANYTHING OTHER -than the system error ENOENT, +than the system error ENOENT, the process must sleep for two seconds, then go back and create another unique filename. This is an extra step to insure that each new message has a completely unique filename. -Other applications that wish to use tmp +Other applications that wish to use tmp for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, -because old files in tmp will be eventually +because old files in tmp will be eventually deleted). If the stat2 -system call returned ENOENT, the process -may proceed to create the file in the tmp +system call returned ENOENT, the process +may proceed to create the file in the tmp subdirectory, and save the entire message in the new file. The message saved MUST NOT have the From_ header that is used to mboxes. @@ -255,8 +217,8 @@ the file descriptor is The file's device number, inode number, and the its byte size, are saved. The file is closed and is then immediately -moved/renamed into the new subdirectory. -The name of the file in new +moved/renamed into the new subdirectory. +The name of the file in new should be time.MusecPpidVdevIino.host,S=cnt, or time.MusecPpidVdevIino_unique.host,S=cnt. @@ -269,7 +231,7 @@ and cnt is the message's size, in bytes. The ,S=cnt -part optimizes the Courier mail server's +part optimizes the Courier mail server's maildir quota enhancement; it allows the size of all the mail stored in the maildir to be added up without issuing the stat2 @@ -278,7 +240,7 @@ for each individual message (this can be quite a performance drain with certain network filesystems). - + READING MAIL FROM MAILDIRS @@ -286,27 +248,27 @@ Applications that read mail from maildirs should do it in the following order: -When opening a maildir or a maildir folder, read the tmp +When opening a maildir or a maildir folder, read the tmp subdirectory and delete any files in there that are at least 36 hours old. -Look for new messages in the new subdirectory. +Look for new messages in the new subdirectory. Rename new/filename, as cur/filename:2,info. Here, info represents the state of the message, and it consists of zero or more boolean flags chosen from the following: -D - this is a 'draft' message, -R - this message has been replied to, -S - this message has been viewed (seen), -T - this +D - this is a 'draft' message, +R - this message has been replied to, +S - this message has been viewed (seen), +T - this message has been marked to be deleted (trashed), but is not yet removed (messages are removed from maildirs simply by deleting their file), -F - this message has been marked by the +F - this message has been marked by the user, for some purpose. These flags must be stored in alphabetical order. -New messages contain only the :2, +New messages contain only the :2, suffix, with no flags, indicating that the messages were not seen, replied, marked, or deleted. @@ -332,14 +294,14 @@ command is a tiny application that delivers a single message to a maildir using the voluntary quota protocol, and hopefully it can be used as a measure of last resort. Alternatively, applications can use the -libmaildir.a +libmaildir.a library to handle all the low-level dirty details for them. The voluntary quota enhancement is described in the maildirquota7 man page. - + Maildir Quotas @@ -380,9 +342,9 @@ in the estimate to be thrown off. A quota for an existing maildir is installed by running maildirmake with the --q option, and naming an existing maildir. +-q option, and naming an existing maildir. -The -q option takes a parameter, +The -q option takes a parameter, quota, which is a comma-separated list of quota specifications. A quota specification consists of a number followed by either 'S', indicating the maximum message @@ -390,7 +352,7 @@ size in bytes, or 'C', maximum number of messages. For example:
- maildirmake -q 5000000S,1000C ./Maildir + maildirmake -q 5000000S,1000C ./Maildir
@@ -399,7 +361,7 @@ This sets the quota to
- maildirmake -q 1000000S ./Maildir + maildirmake -q 1000000S ./Maildir
@@ -408,17 +370,17 @@ to 1,000,000 bytes, without limiting the number of messages. A quota of an existing maildir can be changed by rerunning the -maildirmake command with a new -q +maildirmake command with a new -q option. To delete a quota entirely, delete the -Maildir/maildirsize +Maildir/maildirsize file. - + SEE ALSO diff --git a/maildir/maildirmake.sgml b/maildir/maildirmake.sgml index d635587..e8f4d70 100644 --- a/maildir/maildirmake.sgml +++ b/maildir/maildirmake.sgml @@ -1,7 +1,7 @@ - + SamVarshavchikAuthorCourier Mail Server @@ -23,7 +23,7 @@ - + DESCRIPTION @@ -36,7 +36,7 @@ which creates an extended form of maildirs that implements additional extensions beyond the basic maildir properties that were first implemented in the Qmail mail server. - + OPTIONS @@ -125,7 +125,7 @@ access shared folders. See below for more information. - + FOLDERS @@ -168,7 +168,7 @@ folder. - + SHARED FOLDERS @@ -246,7 +246,7 @@ The option "disconnects" the sharable maildir from the main maildir. - + GLOBAL SHARED FOLDERS @@ -268,7 +268,7 @@ is a single tab character, path is the pathname to the sharable maildir. - + ACCESSING SHARED FOLDERS @@ -284,7 +284,7 @@ own. - + Converting pre-unicode format maildirs @@ -331,7 +331,7 @@ own. existing mailboxes to the new Unicode-based naming standard. - + Background @@ -366,7 +366,7 @@ own. - + Unicode conversion overview @@ -403,7 +403,7 @@ own. - + Unicode conversion steps @@ -521,7 +521,7 @@ Updating /home/mrsam/.mailfilter - + Resolving unicode conversion problems @@ -557,7 +557,7 @@ Updating /home/mrsam/.mailfilter - + After the Unicode conversion @@ -577,7 +577,7 @@ Updating /home/mrsam/.mailfilter - + SEE ALSO diff --git a/maildrop/maildrop.sgml b/maildrop/maildrop.sgml index 40e1b7c..f9e114d 100644 --- a/maildrop/maildrop.sgml +++ b/maildrop/maildrop.sgml @@ -1,7 +1,7 @@ - + SamVarshavchikAuthorCourier Mail Server @@ -31,7 +31,7 @@ - + DESCRIPTION @@ -155,7 +155,7 @@ See below for a more extensive description of the embedded mode. - + SECURITY @@ -213,7 +213,7 @@ group or world permissions. - + TEMPORARY FILES maildrop is heavily optimized and tries to use as @@ -228,11 +228,9 @@ temporary file, then accesses the message from the temporary file. The temporary file is automatically removed when the message is delivered. - + OPTIONS - - -a @@ -502,7 +500,7 @@ below - + DELIVERY MODE @@ -538,7 +536,7 @@ delivery mode. - + VIRTUAL ACCOUNTS @@ -550,7 +548,7 @@ Authentication library's documentation for more information. - + EMBEDDED MODE @@ -652,7 +650,7 @@ by using the echo statement and the EXITCODE environment variable. - + <filename>@withetcdir@/maildroprcs</filename> If maildrop encounters an include @@ -695,7 +693,7 @@ values of these variables (if they were changed) will NOT be restored once - + WATCHDOG TIMER @@ -706,7 +704,7 @@ filtering. If filtering is not complete within a predefined time interval terminates. - + FILES @@ -757,7 +755,7 @@ Directory containing files used in special embedded mode. - + SEE ALSO lockmail1, -- cgit v1.2.3