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>, | 
