diff options
| author | Sam Varshavchik | 2019-09-24 18:40:16 -0400 |
|---|---|---|
| committer | Sam Varshavchik | 2019-09-24 18:40:16 -0400 |
| commit | ee1f8e9ae175c44b00a68d274d9fcf57570f7b91 (patch) | |
| tree | b489d85ac1c48528d037bbebf60dac96a7ffc16b | |
| parent | 65843540c46736cb5022bb24cd0798aaf62a5ee4 (diff) | |
| download | courier-libs-ee1f8e9ae175c44b00a68d274d9fcf57570f7b91.tar.bz2 | |
Documentation fixes
| -rw-r--r-- | maildir/deliverquota.sgml | 8 | ||||
| -rw-r--r-- | maildir/maildir.sgml | 146 | ||||
| -rw-r--r-- | maildir/maildirmake.sgml | 28 | ||||
| -rw-r--r-- | 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 @@ <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <!-- Copyright 1998 - 2009 Double Precision, Inc. See COPYING for --> <!-- distribution information. --> -<refentry> +<refentry id="deliverquota"> <info><author><firstname>Sam</firstname><surname>Varshavchik</surname><contrib>Author</contrib></author><productname>Courier Mail Server</productname></info> <refmeta> @@ -26,7 +26,7 @@ </cmdsynopsis> </refsynopsisdiv> - <refsect1> + <refsect1 id="description"> <title>DESCRIPTION</title> <para> @@ -90,7 +90,7 @@ below </refsect1> - <refsect1> + <refsect1 id="return"> <title>RETURN CODE</title> <para> @@ -103,7 +103,7 @@ If the maildir is over its specified quota, <command moreinfo="none">deliverquot terminates with exit code 77 (EX_NOPERM).</para> </refsect1> - <refsect1> + <refsect1 id="seealso"> <title>SEE ALSO</title> <para> 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 @@ <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <!-- Copyright 1998 - 2007 Double Precision, Inc. See COPYING for --> <!-- distribution information. --> -<refentry> +<refentry id="maildir"> <info><author><firstname>Sam</firstname><surname>Varshavchik</surname><contrib>Author</contrib></author><productname>Courier Mail Server</productname></info> <refmeta> @@ -19,24 +19,24 @@ <simpara>$HOME/Maildir</simpara> </refsynopsisdiv> - <refsect1> + <refsect1 id="description"> <title>DESCRIPTION</title> <para> A <quote>Maildir</quote> is a structured directory that holds E-mail messages. Maildirs were first implemented by the -<application moreinfo="none">Qmail</application> mail server. +<application>Qmail</application> mail server. Qmail's maildirs were a simple data structure, nothing more than a single collection of E-mail messages. -The <application moreinfo="none">Courier</application> mail server builds upon -<application moreinfo="none">Qmail</application>'s maildirs to provide +The <application>Courier</application> mail server builds upon +<application>Qmail</application>'s maildirs to provide extended functionality, such as folders and quotas. This document describes -the <application moreinfo="none">Courier</application> mail server's extended +the <application>Courier</application> mail server's extended maildirs, without explicitly identifying -The <application moreinfo="none">Courier</application> mail server-specific +The <application>Courier</application> mail server-specific extensions. See <citerefentry><refentrytitle>maildir</refentrytitle><manvolnum>5</manvolnum></citerefentry> @@ -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.</para> - <refsect2> + <refsect2 id="maildircontents"> <title>Maildir contents</title> <para> @@ -76,8 +76,8 @@ A <quote>maildir</quote> 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: -<filename moreinfo="none">tmp</filename>, <filename moreinfo="none">new</filename>, and -<filename moreinfo="none">cur</filename>. +<filename>tmp</filename>, <filename>new</filename>, and +<filename>cur</filename>. These three subdirectories comprise the primary folder, where new mail is delivered by the system.</para> @@ -85,12 +85,12 @@ is delivered by the system.</para> Folders are additional subdirectories in the maildir whose names begin with a period: such as -<filename moreinfo="none">.Drafts</filename> or <filename moreinfo="none">.Sent</filename>. +<filename>.Drafts</filename> or <filename>.Sent</filename>. Each folder itself contains the -same three subdirectories, <filename moreinfo="none">tmp</filename>, <filename moreinfo="none">new</filename>, -and <filename moreinfo="none">cur</filename>, +same three subdirectories, <filename>tmp</filename>, <filename>new</filename>, +and <filename>cur</filename>, and an additional zero-length file named -<filename moreinfo="none">maildirfolder</filename>, whose purpose is to inform any mail +<filename>maildirfolder</filename>, 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.</para> @@ -98,91 +98,53 @@ any maildir-related information.</para> <para> Folders are not physically nested. A folder subdirectory, -such as <filename moreinfo="none">.Sent</filename> +such as <filename>.Sent</filename> 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, <filename moreinfo="none">.Sent.2002</filename> is considered to be a subfolder +For example, <filename>.Sent.2002</filename> is considered to be a subfolder called <quote>2002</quote> which is a subfolder of <quote>Sent</quote>.</para> - <refsect3> + <refsect3 id="foldername"> <title>Folder name encoding</title> <para> 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 <quote>&-</quote>. -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.</para> - - <para> -The <quote>&</quote> -character starts the modified base64-encoded sequence; the sequence -is -terminated by the <quote>-</quote> 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 <ulink url="http://www.rfc-editor.org/rfc/rfc1521.txt">RFC 1521</ulink>, -with the following modifications:</para> - - <itemizedlist> - <listitem> - <para> -The <quote>=</quote> padding character is omitted. -When decoding, an incomplete 16-bit character is discarded.</para> - </listitem> - - <listitem> - <para> -The comma character, <quote>,</quote> is used in place of the -<quote>/</quote> character in the base64 alphabet.</para> - </listitem> - </itemizedlist> - - <para> -For example, the word <quote>Resume</quote> with both "e"s being the -e-acute character, U+0x00e9, -is encoded as -<quote>R&AOk-sum&AOk-</quote> -(so a folder of that name would be a maildir subdirectory called -<quote>.R&AOk-sum&AOk-</quote>).</para> +and forward-slash. Non-Latin characters are encoded in UTF-8.</para> </refsect3> - <refsect3> + <refsect3 id="othermaildir"> <title>Other maildir contents</title> <para> Software that uses maildirs may also create additional files besides the -<filename moreinfo="none">tmp</filename>, <filename moreinfo="none">new</filename>, and -<filename moreinfo="none">cur</filename> subdirectories -- in the main maildir or a +<filename>tmp</filename>, <filename>new</filename>, and +<filename>cur</filename> subdirectories -- in the main maildir or a subfolder -- for its own purposes.</para> </refsect3> </refsect2> - <refsect2> + <refsect2 id="messages"> <title>Messages</title> <para> E-mail messages are stored in separate, individual files, one E-mail message per file. -The <filename moreinfo="none">tmp</filename> subdirectory temporarily +The <filename>tmp</filename> subdirectory temporarily stores E-mail messages that are in the process of being delivered -to this maildir. <filename moreinfo="none">tmp</filename> may also +to this maildir. <filename>tmp</filename> may also store other kinds of temporary files, as long as they are created in the same way that message files are -created in <filename moreinfo="none">tmp</filename>. -The <filename moreinfo="none">new</filename> subdirectory stores messages +created in <filename>tmp</filename>. +The <filename>new</filename> subdirectory stores messages that have been delivered to this maildir, but have not yet been seen by any mail application. -The <filename moreinfo="none">cur</filename> subdirectory stores messages that have +The <filename>cur</filename> subdirectory stores messages that have already been seen by mail applications.</para> </refsect2> - <refsect2> + <refsect2 id="addingmail"> <title>Adding new mail to maildirs</title> <para>The following process delivers a new message to the maildir:</para> @@ -217,24 +179,24 @@ system call. If <citerefentry><refentrytitle>stat</refentrytitle><manvolnum>2</manvolnum></citerefentry> results in ANYTHING OTHER -than the system error <literal moreinfo="none">ENOENT</literal>, +than the system error <literal>ENOENT</literal>, 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.</para> <para> -Other applications that wish to use <filename moreinfo="none">tmp</filename> +Other applications that wish to use <filename>tmp</filename> for temporary storage should observe the same protocol (but see READING MAIL FROM MAILDIRS below, -because old files in <filename moreinfo="none">tmp</filename> will be eventually +because old files in <filename>tmp</filename> will be eventually deleted).</para> <para> If the <citerefentry><refentrytitle>stat</refentrytitle><manvolnum>2</manvolnum></citerefentry> -system call returned <literal moreinfo="none">ENOENT</literal>, the process -may proceed to create the file in the <filename moreinfo="none">tmp</filename> +system call returned <literal>ENOENT</literal>, the process +may proceed to create the file in the <filename>tmp</filename> subdirectory, and save the entire message in the new file. The message saved MUST NOT have the <quote>From_</quote> 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 <filename moreinfo="none">new</filename> subdirectory. -The name of the file in <filename moreinfo="none">new</filename> +moved/renamed into the <filename>new</filename> subdirectory. +The name of the file in <filename>new</filename> should be <quote>time.MusecPpidVdevIino.host,S=<replaceable>cnt</replaceable></quote>, or <quote>time.MusecPpidVdevIino_unique.host,S=<replaceable>cnt</replaceable></quote>. @@ -269,7 +231,7 @@ and <quote>cnt</quote> is the message's size, in bytes.</para> <para> The <quote>,S=<replaceable>cnt</replaceable></quote> -part optimizes the <ulink url="http://www.courier-mta.org"><application moreinfo="none">Courier</application></ulink> mail server's +part optimizes the <ulink url="http://www.courier-mta.org"><application>Courier</application></ulink> 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 <citerefentry><refentrytitle>stat</refentrytitle><manvolnum>2</manvolnum></citerefentry> @@ -278,7 +240,7 @@ for each individual message (this can be quite a performance drain with certain network filesystems).</para> </refsect2> - <refsect2> + <refsect2 id="readingmail"> <title>READING MAIL FROM MAILDIRS</title> <para> @@ -286,27 +248,27 @@ Applications that read mail from maildirs should do it in the following order:</para> <para> -When opening a maildir or a maildir folder, read the <filename moreinfo="none">tmp</filename> +When opening a maildir or a maildir folder, read the <filename>tmp</filename> subdirectory and delete any files in there that are at least 36 hours old.</para> <para> -Look for new messages in the <filename moreinfo="none">new</filename> subdirectory. +Look for new messages in the <filename>new</filename> subdirectory. Rename <replaceable>new/filename</replaceable>, as <replaceable>cur/filename:2,info</replaceable>. Here, <replaceable>info</replaceable> represents the state of the message, and it consists of zero or more boolean flags chosen from the following: -<quote><literal moreinfo="none">D</literal></quote> - this is a 'draft' message, -<quote><literal moreinfo="none">R</literal></quote> - this message has been replied to, -<quote><literal moreinfo="none">S</literal></quote> - this message has been viewed (seen), -<quote><literal moreinfo="none">T</literal></quote> - this +<quote><literal>D</literal></quote> - this is a 'draft' message, +<quote><literal>R</literal></quote> - this message has been replied to, +<quote><literal>S</literal></quote> - this message has been viewed (seen), +<quote><literal>T</literal></quote> - this message has been marked to be deleted (trashed), but is not yet removed (messages are removed from maildirs simply by deleting their file), -<quote><literal moreinfo="none">F</literal></quote> - this message has been marked by the +<quote><literal>F</literal></quote> - this message has been marked by the user, for some purpose. These flags must be stored in alphabetical order. -New messages contain only the <literal moreinfo="none">:2,</literal> +New messages contain only the <literal>:2,</literal> suffix, with no flags, indicating that the messages were not seen, replied, marked, or deleted.</para> @@ -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 -<filename moreinfo="none">libmaildir.a</filename> +<filename>libmaildir.a</filename> library to handle all the low-level dirty details for them. The voluntary quota enhancement is described in the <ulink url="maildirquota.html"><citerefentry><refentrytitle>maildirquota</refentrytitle><manvolnum>7</manvolnum></citerefentry></ulink> man page.</para> </refsect2> - <refsect2> + <refsect2 id="quotas"> <title>Maildir Quotas</title> <para> @@ -380,9 +342,9 @@ in the estimate to be thrown off.</para> <para> A quota for an existing maildir is installed by running maildirmake with the -<literal moreinfo="none">-q</literal> option, and naming an existing maildir. +<literal>-q</literal> option, and naming an existing maildir. -The <literal moreinfo="none">-q</literal> option takes a parameter, +The <literal>-q</literal> option takes a parameter, <replaceable>quota</replaceable>, 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:</para> <blockquote> <informalexample> - <literallayout format="linespecific" class="normal"><command moreinfo="none">maildirmake -q 5000000S,1000C ./Maildir</command></literallayout> + <literallayout format="linespecific" class="normal"><command>maildirmake -q 5000000S,1000C ./Maildir</command></literallayout> </informalexample> </blockquote> <para> @@ -399,7 +361,7 @@ This sets the quota to <blockquote> <informalexample> - <literallayout format="linespecific" class="normal"><command moreinfo="none">maildirmake -q 1000000S ./Maildir</command></literallayout> + <literallayout format="linespecific" class="normal"><command>maildirmake -q 1000000S ./Maildir</command></literallayout> </informalexample> </blockquote> <para> @@ -408,17 +370,17 @@ to 1,000,000 bytes, without limiting the number of messages.</para> <para> A quota of an existing maildir can be changed by rerunning the -<command moreinfo="none">maildirmake</command> command with a new <literal moreinfo="none">-q</literal> +<command>maildirmake</command> command with a new <literal>-q</literal> option. To delete a quota entirely, delete the -<filename moreinfo="none"><replaceable>Maildir</replaceable>/maildirsize</filename> +<filename><replaceable>Maildir</replaceable>/maildirsize</filename> file.</para> </refsect2> </refsect1> - <refsect1> + <refsect1 id="seealso"> <title>SEE ALSO</title> <para> 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 @@ <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <!-- Copyright 1998 - 2018 Double Precision, Inc. See COPYING for --> <!-- distribution information. --> -<refentry> +<refentry id="maildirmake"> <info><author><firstname>Sam</firstname><surname>Varshavchik</surname><contrib>Author</contrib></author><productname>Courier Mail Server</productname></info> <refmeta> @@ -23,7 +23,7 @@ </cmdsynopsis> </refsynopsisdiv> - <refsect1> + <refsect1 id="description"> <title>DESCRIPTION</title> <para> @@ -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.</para> </refsect1> - <refsect1> + <refsect1 id="options"> <title>OPTIONS</title> <variablelist> @@ -125,7 +125,7 @@ access shared folders. See below for more information.</simpara> </varlistentry> </variablelist> - <refsect2> + <refsect2 id="folders"> <title>FOLDERS</title> <para> @@ -168,7 +168,7 @@ folder.</para> </refsect2> - <refsect2> + <refsect2 id="sharedfolders"> <title>SHARED FOLDERS</title> <para> @@ -246,7 +246,7 @@ The <option>--del</option> option "disconnects" the sharable maildir from the main maildir.</para> </refsect2> - <refsect2> + <refsect2 id="globalsharedfolders"> <title>GLOBAL SHARED FOLDERS</title> <para> @@ -268,7 +268,7 @@ is a single tab character, <replaceable>path</replaceable> is the pathname to the sharable maildir.</para> </refsect2> - <refsect2> + <refsect2 id="sharedaccess"> <title>ACCESSING SHARED FOLDERS</title> <para> @@ -284,7 +284,7 @@ own.</para> </refsect1> - <refsect1> + <refsect1 id="converting"> <title>Converting pre-unicode format maildirs</title> <para> @@ -331,7 +331,7 @@ own.</para> existing mailboxes to the new Unicode-based naming standard. </para> - <refsect2> + <refsect2 id="background"> <title>Background</title> <para> @@ -366,7 +366,7 @@ own.</para> </para> </refsect2> - <refsect2> + <refsect2 id="unicode"> <title>Unicode conversion overview</title> <para> @@ -403,7 +403,7 @@ own.</para> </listitem> </itemizedlist> </refsect2> - <refsect2> + <refsect2 id="unicodesteps"> <title>Unicode conversion steps</title> <para> @@ -521,7 +521,7 @@ Updating /home/mrsam/.mailfilter</programlisting> </note> </refsect2> - <refsect2> + <refsect2 id="unicodeconvproblems"> <title>Resolving unicode conversion problems</title> <para> @@ -557,7 +557,7 @@ Updating /home/mrsam/.mailfilter</programlisting> </para> </refsect2> - <refsect2> + <refsect2 id="unicodeafter"> <title>After the Unicode conversion</title> <para> @@ -577,7 +577,7 @@ Updating /home/mrsam/.mailfilter</programlisting> </para> </refsect2> </refsect1> - <refsect1> + <refsect1 id="seealso"> <title>SEE ALSO</title> <para> 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 @@ <!DOCTYPE refentry PUBLIC "-//OASIS//DTD DocBook XML V4.4//EN" "http://www.oasis-open.org/docbook/xml/4.4/docbookx.dtd"> <!-- Copyright 1998 - 2009 Double Precision, Inc. See COPYING for --> <!-- distribution information. --> -<refentry> +<refentry id="maildrop"> <info><author><firstname>Sam</firstname><surname>Varshavchik</surname><contrib>Author</contrib></author><productname>Courier Mail Server</productname></info> <refmeta> @@ -31,7 +31,7 @@ </cmdsynopsis> </refsynopsisdiv> - <refsect1> + <refsect1 id="description"> <title>DESCRIPTION</title> <para> @@ -155,7 +155,7 @@ See below for a more extensive description of the embedded mode.</para> </variablelist> </refsect1> - <refsect1> + <refsect1 id="security"> <title>SECURITY</title> <para> @@ -213,7 +213,7 @@ group or world permissions.</para> </refsect1> - <refsect1> + <refsect1 id="temporaryfiles"> <title>TEMPORARY FILES</title> <para> <command>maildrop</command> 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.</para> </refsect1> - <refsect1> + <refsect1 id="options"> <title>OPTIONS</title> - <anchor id="options"/> - <variablelist> <varlistentry> <term>-a</term> @@ -502,7 +500,7 @@ below </variablelist> </refsect1> - <refsect1> + <refsect1 id="deliverymode"> <title>DELIVERY MODE</title> <para> @@ -538,7 +536,7 @@ delivery mode.</para> </note> </refsect1> - <refsect1> + <refsect1 id="virtualaccounts"> <title>VIRTUAL ACCOUNTS</title> <para> @@ -550,7 +548,7 @@ Authentication library's documentation for more information.</para> </refsect1> - <refsect1> + <refsect1 id="embeddedmode"> <title>EMBEDDED MODE</title> <anchor id="embedded"/> <para> @@ -652,7 +650,7 @@ by using the <ulink url="maildropfilter.html#echo">echo</ulink> statement and the <varname>EXITCODE</varname> environment variable.</para> - <refsect2> + <refsect2 id="maildroprcs"> <title><filename>@withetcdir@/maildroprcs</filename></title> <para>If <command>maildrop</command> encounters an <ulink url="maildropfilter.html#include">include</ulink> @@ -695,7 +693,7 @@ values of these variables (if they were changed) will NOT be restored once </refsect2> </refsect1> - <refsect1> + <refsect1 id="watchdog"> <title>WATCHDOG TIMER</title> <para> @@ -706,7 +704,7 @@ filtering. If filtering is not complete within a predefined time interval terminates.</para> </refsect1> - <refsect1> + <refsect1 id="files"> <title>FILES</title> <variablelist> @@ -757,7 +755,7 @@ Directory containing files used in special embedded mode.</para> </variablelist> </refsect1> - <refsect1> + <refsect1 id="seealso"> <title>SEE ALSO</title> <para> <ulink url="lockmail.html"><citerefentry><refentrytitle>lockmail</refentrytitle><manvolnum>1</manvolnum></citerefentry></ulink>, |
