Docs: add warning note on ${listnamed:} operator

[users/heiko/exim.git] / doc / doc-docbook / x2man

diff --git a/doc/doc-docbook/x2man b/doc/doc-docbook/x2man
index a9812239ecbc342d77f9cc834b17d88dd888132b..e133e23edd0fe58886f79778583bce40b9b0f5b3 100755 (executable)
--- a/doc/doc-docbook/x2man
+++ b/doc/doc-docbook/x2man
@@ -1,17 +1,8 @@
 #! /usr/bin/perl -w
 
 #! /usr/bin/perl -w
 

-# $Cambridge: exim/doc/doc-docbook/x2man,v 1.1 2005/06/16 10:32:31 ph10 Exp $
-

 # Script to find the command line options in the DocBook source of the Exim
 # spec, and turn them into a man page, because people like that.
 
 # Script to find the command line options in the DocBook source of the Exim
 # spec, and turn them into a man page, because people like that.
 

-
-
-
-##################################################
-#              Main Program                      #
-##################################################
-

 open(IN, "spec.xml") || die "Can't open spec.xml\n";
 open(OUT, ">exim.8" ) || die "Can't open exim.8\n";
 
 open(IN, "spec.xml") || die "Can't open spec.xml\n";
 open(OUT, ">exim.8" ) || die "Can't open exim.8\n";
 


@@ -20,18 +11,15 @@ print OUT <<End;
 .SH NAME
 exim \\- a Mail Transfer Agent
 .SH SYNOPSIS
 .SH NAME
 exim \\- a Mail Transfer Agent
 .SH SYNOPSIS

+.nf

 .B exim [options] arguments ...
 .B exim [options] arguments ...

-.br

 .B mailq [options] arguments ...
 .B mailq [options] arguments ...

-.br

 .B rsmtp [options] arguments ...
 .B rsmtp [options] arguments ...

-.br

 .B rmail [options] arguments ...
 .B rmail [options] arguments ...

-.br

 .B runq [options] arguments ...
 .B runq [options] arguments ...

-.br

 .B newaliases [options] arguments ...
 .B newaliases [options] arguments ...

-
+.fi
+.

 .SH DESCRIPTION
 .rs
 .sp
 .SH DESCRIPTION
 .rs
 .sp


@@ -40,10 +28,41 @@ It is a large program with very many facilities. For a full specification, see
 the reference manual. This man page contains only a description of the command
 line options. It has been automatically generated from the reference manual
 source, hopefully without too much mangling.
 the reference manual. This man page contains only a description of the command
 line options. It has been automatically generated from the reference manual
 source, hopefully without too much mangling.

-
-.SH SETTING OPTIONS BY PROGRAM NAME
+.P
+Like other MTAs, Exim replaces Sendmail, and is normally called by user agents
+(MUAs) using the path \\fI/usr/sbin/sendmail\\fP when they submit messages for
+delivery (some operating systems use \\fI/usr/lib/sendmail\\fP). This path is
+normally set up as a symbolic link to the Exim binary. It may also be used by
+boot scripts to start the Exim daemon. Many of Exim's command line options are
+compatible with Sendmail so that it can act as a drop-in replacement.
+.
+.SH "DEFAULT ACTION"
+.rs
+.sp
+If no options are present that require a specific action (such as starting the
+daemon or a queue runner, testing an address, receiving a message in a specific
+format, or listing the queue), and there are no arguments on the command line,
+Exim outputs a brief message about itself and exits.
+.sp
+However, if there is at least one command line argument, \\fB-bm\\fR (accept a
+local message on the standard input, with the arguments specifying the
+recipients) is assumed. Thus, for example, if Exim is installed in
+\\fI/usr/sbin\\fP, you can send a message from the command line like this:
+.sp
+  /usr/sbin/exim -i <recipient-address(es)>
+  <message content, including all the header lines>
+  CTRL-D
+.sp
+The \\fB-i\\fP option prevents a line containing just a dot from terminating
+the message. Only an end-of-file (generated by typing CTRL-D if the input is
+from a terminal) does so.
+.
+.SH "SETTING OPTIONS BY PROGRAM NAME"

 .rs
 .rs

-.TP 10
+.sp
+If an Exim binary is called using one of the names listed in this section
+(typically via a symbolic link), certain options are assumed.
+.TP

 \\fBmailq\\fR
 Behave as if the option \\fB\\-bp\\fP were present before any other options.
 The \\fB\\-bp\\fP option requests a listing of the contents of the mail queue
 \\fBmailq\\fR
 Behave as if the option \\fB\\-bp\\fP were present before any other options.
 The \\fB\\-bp\\fP option requests a listing of the contents of the mail queue


@@ -72,8 +91,8 @@ Behave as if the option \\fB\\-bi\\fP were present before any other options,
 for compatibility with Sendmail. This option is used for rebuilding Sendmail's
 alias file. Exim does not have the concept of a single alias file, but can be
 configured to run a specified command if called with the \\fB\\-bi\\fP option.
 for compatibility with Sendmail. This option is used for rebuilding Sendmail's
 alias file. Exim does not have the concept of a single alias file, but can be
 configured to run a specified command if called with the \\fB\\-bi\\fP option.

-
-.SH OPTIONS
+.
+.SH "OPTIONS"

 .rs
 End
 
 .rs
 End
 


@@ -96,11 +115,11 @@ while ($next)
 
   # Start of new option
 
 
   # Start of new option
 

-  if (/^<term>$/)
+  if (/^<term>(?=<option>-)(.*?)<\/term>$/)

     {
     print OUT ".TP 10\n";
     {
     print OUT ".TP 10\n";

+    $_ = "$1\n";

     $optstart = 1;
     $optstart = 1;

-    next;

     }
 
   # If a line contains text that is not in <>, read subsequent lines of the
     }
 
   # If a line contains text that is not in <>, read subsequent lines of the


@@ -134,11 +153,11 @@ while ($next)
     $optstart = 0;
     }
 
     $optstart = 0;
     }
 

-  # Literal layout needs to be treated as a paragraph, and indented
+  # Literal layout needs to be wrapped with .sp, and indented.

 
   if (/<literallayout/)
     {
 
   if (/<literallayout/)
     {

-    s/<literallayout[^>]*>/.P/;
+    s/<literallayout[^>]*>/.sp/;

     $indent = "  ";
     }
 
     $indent = "  ";
     }
 


@@ -146,8 +165,8 @@ while ($next)
 
   # Others get marked
 
 
   # Others get marked
 

-  s/<para>/.P/;
-  s/<simpara>/.P/;
+  s/<para>/.sp/;
+  s/<simpara>/.sp/;

 
   # Skip index entries
 
 
   # Skip index entries
 


@@ -182,31 +201,32 @@ while ($next)
 
   next if /^\s*$/;
 
 
   next if /^\s*$/;
 

-  # It turns out that we don't actually want .P; a blank line is needed.
-  # But we can't set that above, because it will be discarded.
-
-  s/^\.P\s*$/\n/;
-

   # We are going to output some data; sort out special characters
 
   s/&lt;/</g;
   s/&gt;/>/g;
 
   # We are going to output some data; sort out special characters
 
   s/&lt;/</g;
   s/&gt;/>/g;
 

-  s/&#x002d;/-/g;
-  s/&#x00a0;/ /g;
-  s/&#x2013;/-/g;
+  s/&nbsp;/ /g;
+  s/&ndash;/-/g;

   s/&#x2019;/'/g;
   s/&#x2019;/'/g;

-  s/&#8230;/.../g;    # Sic - no x

 
   # Escape hyphens to prevent unwanted hyphenation
 
   s/-/\\-/g;
 
 
   # Escape hyphens to prevent unwanted hyphenation
 
   s/-/\\-/g;
 

-  # Put in the indent, and write the line
+  # Put in the indent unless the line starts .sp, and then write the line

 
 

-  s/^/$indent/mg;
+  s/^/$indent/mg unless /^\.sp/;

 
   print OUT;
   }
 
 
   print OUT;
   }
 

-# End of g2man
+print OUT <<End;
+.
+.SH "SEE ALSO"
+.rs
+.sp
+The full Exim specification, the Exim book, and the Exim wiki.
+End
+
+# End of x2man