summaryrefslogtreecommitdiffstats
diff options
context:
space:
mode:
authorSam Varshavchik2019-09-24 18:40:16 -0400
committerSam Varshavchik2019-09-24 18:40:16 -0400
commitee1f8e9ae175c44b00a68d274d9fcf57570f7b91 (patch)
treeb489d85ac1c48528d037bbebf60dac96a7ffc16b
parent65843540c46736cb5022bb24cd0798aaf62a5ee4 (diff)
downloadcourier-libs-ee1f8e9ae175c44b00a68d274d9fcf57570f7b91.tar.bz2
Documentation fixes
-rw-r--r--maildir/deliverquota.sgml8
-rw-r--r--maildir/maildir.sgml146
-rw-r--r--maildir/maildirmake.sgml28
-rw-r--r--maildrop/maildrop.sgml26
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>&amp;-</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>&amp;</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&amp;AOk-sum&amp;AOk-</quote>
-(so a folder of that name would be a maildir subdirectory called
-<quote>.R&amp;AOk-sum&amp;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>,