Better support for TARGETS and TIMESTAMP in xcopy's own selection

[sgt/utils] / nntpid / nntpid.but

diff --git a/nntpid/nntpid.but b/nntpid/nntpid.but
index f1d89ee..3444a99 100644 (file)
--- a/nntpid/nntpid.but
+++ b/nntpid/nntpid.but
@@ -8,15 +8,17 @@
 
 \U SYNOPSIS
 
-\c nntpid [ -v ] message-id
-\e bbbbbb   bb   iiiiiiiiii
-\c nntpid [ -v ] newsgroup-name article-number
-\e bbbbbb   bb   iiiiiiiiiiiiii iiiiiiiiiiiiii
+\c nntpid [ -v ] [ -d ] message-id
+\e bbbbbb   bb     bb   iiiiiiiiii
+\c nntpid [ -v ] [ -d ] newsgroup-name article-number
+\e bbbbbb   bb     bb   iiiiiiiiiiiiii iiiiiiiiiiiiii
+\c nntpid [ -v ] -a newsgroup-name
+\e bbbbbb   bb   bb iiiiiiiiiiiiii
 
 \U DESCRIPTION
 
-\cw{nntpid} makes a connection to a news server, retrieves a single
-article, and displays it.
+\cw{nntpid} makes a connection to a news server, retrieves one or
+more articles, and displays it.
 
 You can specify the article you want by either:
 
@@ -29,6 +31,19 @@ newsgroup. Article numbers are assigned internally by a particular
 news server, so they will be different on other servers carrying the
 same group.
 
+By default, \cw{nntpid} will try to display the article using a
+pager (\cw{more}(1), unless you have specified an alternative in the
+environment variable \cw{PAGER}). This is partly for convenience,
+and partly a mild security measure: it gives you some protection
+against the news article potentially containing control sequences
+that cause unexpected behaviour in your terminal. If \cw{nntpid}
+detects that its standard output is not a terminal, however, it will
+bypass the pager and just write out the article directly.
+
+There is a third mode of operation, enabled by the \cw{-a} option,
+in which \cw{nntpid} retrieves \e{all} available articles in the
+group and writes them to standard output in \cw{mbox} format.
+
 \U ARGUMENTS
 
 If you specify one argument, \cw{nntpid} assumes it is a Message-ID.
@@ -46,6 +61,17 @@ as a newsgroup name, and the second as an article number.
 \dd Verbose mode. In this mode, \cw{nntpid} will log its entire
 conversation with the news server on standard error.
 
+\dt \cw{-d}
+
+\dd Direct output. In this mode, \cw{nntpid} will write the article
+straight to standard output without bothering to try using a pager.
+
+\dt \cw{-a}
+
+\dd Retrieve all articles from the given newsgroup. In this mode,
+\cw{nntpid} will always write straight to standard output (so the
+\cw{-d} option is unnecessary).
+
 \U AUTHENTICATION
 
 Currently, the only form of authentication supported by \cw{nntpid}