⟦a4e343b3d⟧

TextFile

\input texinfo			@c -*- texinfo -*-
@setfilename ../info/gnews
@settitle Gnews

@ignore
The above setfilename works as is if you are installing Gnews from
a directory one below the top Emacs directory, for example, if you
initially untar the Gnews source while in the .../emacs directory.
@end ignore

@iftex
@let@file=@t
@let@code=@l
@finalout
@end iftex

@titlepage
@center @titlefont{Gnews}
@center Version 2.0
@sp 1
@center A GNU Emacs newsreader
@center @i{SEVENTH DRAFT}
@sp 2
@center Matthew P Wiener

@page
@vskip 0pt plus 1fill

Copyright @copyright{} 1988 Matthew P Wiener
@c Copyright (C) 1988 Matthew P Wiener

Permission is granted to make and distribute verbatim copies of
this manual provided the copyright notice and this permission notice
are preserved on all copies.

@ignore
Permission is granted to process this file through TeX and print the
results, provided the printed document carries copying permission
notice identical to this one except for the removal of this paragraph
(this paragraph not being relevant to the printed manual).

@end ignore
Permission is granted to copy and distribute modified versions of this
manual under the conditions for verbatim copying, provided that the entire
resulting derived work is distributed under the terms of a permission
notice identical to this one.

Permission is granted to copy and distribute translations of this manual
into another language, under the same conditions as for modified versions.

@sp 2
@iftex
{@secrm Acknowledgements}
@sp 1
@end iftex

I would like to thank the many people who have helped contribute to the
design and coding of Gnews, tested it under more primitive circumstances,
and/or improved my understanding of NNTP, GNU Emacs, and even Gnews itself.

This includes Michael Ellis, Gene Ward Smith, Emile LeBlanc, Erik Fair,
Alex Liu, Rusty Wright, Fred Douglis, Henry Mensch, Len Tower, Michael
Bushnell, Ashwin Ram, John Robinson, Hal Peterson, and Richard Krawitz.

Extra thanks go to Larry Wall, Brian Kantor, Phil Lapsley, and, of
course, Richard Stallman.

@setchapternewpage odd
@end titlepage

@c	Local Variables:
@c	TeX-zap-file:"gnews-man"
@c	auto-save-interval:0
@c	End:

@node Top, , , (DIR)

@menu
Generalities:

* preface::	Prefatory remarks
* start::	Starting Gnews
* help::	On-line Gnews help

Gnews reading commands:

* news::	Newsgroup selection level
* group::	Article selection/paging level

Gnews reply commands:

* reply::	Replying to articles

More Gnews commands:

* index::	Indexing a newsgroup
* hook-kill::	Hook-Kill processing
* digest::	Reading digests

Miscellaneous information:

* features::	Gnews @t{rn}-analogues
* bugs::	Gnews bugs and annoyances
* customize::	Customizing Gnews
* internals::	Internal Gnews details
* examples::	Example Gnews code
* install::	How to install Gnews    

Indices:

* Info Index::	Indices to the Info guide

@end menu

@page
@node preface, start, , Top
@unnumbered Preface

Gnews is an NNTP-based @t{rn}-styled Lisp-coded news reader/poster/mailer.

NNTP-based means that the internals run off of NNTP, the Network News
Transfer Protocol.  NNTP is an abstract scheme for retrieving and sending
news articles, and allows for machines that do not actually carry Usenet
to still access news remotely.
@cindex news
@pindex NNTP

@t{rn}-styled means that the command structure and general organization
of this reader follows @t{rn}, currently the most popular newsreader
on Usenet.  Its most important feature for many users was the fact
that it had a @emph{remote} version, called @t{rrn}, for reading off a
remote spool using NNTP.
@pindex rn
@pindex rrn

Lisp-coded means that all of Gnews is written in GNU Emacs Lisp, and
that of course means that all the advantages of GNU Emacs are now
available in the newsreader itself.  Gnews tries to encourage this,
and its own behavior is highly customizable.

The name, of course, is pronounced ``guh-NUZ''.

Comments, suggestions, complaints, and bug reports are all welcome,
and should be sent to @kbd{weemba@@garnet.berkeley.edu} on the ARPANET, or
@kbd{@dots{}!ucbvax!garnet!weemba} over UUCP.  @xref{help, , Help}.

@menu
Legal status:		@c I have to doooooo this??

* License::		Gnews Public License
* Copying::		Copying Policy
* NO WARRANTY::		NO WARRANTY

Overview:

* usenet::		Welcome to Usenet
* emacs::		Welcome to Emacs?
@end menu

@page
@node License, Copying, , preface
@unnumberedsec Gnews General License

The Gnews General License is a (straightforward) modification of the
GNU Emacs General Public License, and in accordance with that license,
Free Software Foundation wants me to let you know that I, Matthew P
Wiener, explicitly modified (to refer to Gnews) the Emacs general public
license, copying policy and no warranty on 12 Aug 88.

Like the Free Software Foundation, I want to make sure that you have
the right to give away copies of Gnews, that you receive source code
or else can get it if you want it, that you can change Gnews or use
pieces of it in new free programs, and that you know you can do these
things.

To make sure that everyone has such rights, I forbid you to deprive
anyone else of these rights.  For example, if you distribute copies
of Gnews, you must give the recipients all the rights that you have.
You must make sure that they, too, receive or can get the source code.
And you must tell them their rights.

Also, for my own protection, I must make certain that everyone finds
out that there is no warranty for Gnews.  If Gnews is modified by
someone else and passed on, I want its recipients to know that what
they have is not what I distributed, so that any problems introduced
by others will not reflect on my reputation.

Therefore I (Matthew P Wiener) make the following terms which say what
you must do to be allowed to distribute or change Gnews.

@ifinfo
[Hit `n' to continue.]
@end ifinfo

@node Copying, NO WARRANTY, License , preface
@unnumberedsubsec Copying Policies

@enumerate
@item
You may copy and distribute verbatim copies of Gnews source code as
you receive it, in any medium, provided that you conspicuously and
appropriately publish on each file a valid copyright notice
@samp{Copyright (C) 1987, 1988 Matthew P Wiener} (or with whatever
year or years); keep intact the notices on all files that refer to
this License Agreement and to the absence of any warranty; and give
any other recipients of the Gnews program a copy of this License
Agreement along with the program.  You may charge a distribution
fee for the physical act of transferring a copy.

@item     
You may modify your copy or copies of Gnews source code or any portion
of it, and copy and distribute such modifications under the terms of
Paragraph 1 above, provided that you also do the following:
@itemize @bullet
@item
cause the modified files to carry prominent notices stating
who last changed such files and the date of any change; and
@item
cause the whole of any work that you distribute or publish,
that in whole or in part contains or is a derivative of Gnews
or any part thereof, to be licensed at no charge to all third
parties on terms identical to those contained in this License
Agreement (except that you may choose to grant more extensive
warranty protection to some or all third parties, at your option).
@item
You may charge a distribution fee for the physical act of
transferring a copy, and you may at your option offer warranty
protection in exchange for a fee.
@end itemize
Mere aggregation of another unrelated program with this program (or
its derivative) on a volume of a storage or distribution medium does
not bring the other program under the scope of these terms.

@item     
You may copy and distribute Gnews (or a portion or derivative of it,
under Paragraph 2) in object code or executable form under the terms
of Paragraphs 1 and 2 above provided that you also do one of the
following:
@itemize @bullet
@item
accompany it with the complete corresponding machine-readable
source code, which must be distributed under the terms of
Paragraphs 1 and 2 above; or,
@item
accompany it with a written offer, valid for at least three
years, to give any third party free (except for a nominal
shipping charge) a complete machine-readable copy of the
corresponding source code, to be distributed under the terms of
Paragraphs 1 and 2 above; or,
@item
accompany it with the information you received as to where the
corresponding source code may be obtained.  (This alternative is
allowed only for noncommercial distribution and only if you
received the program in object code or executable form alone.)
@end itemize
For an executable file, complete source code means all the source
code for all modules it contains; but, as a special exception, it
need not include source code for modules which are standard libraries
that accompany the operating system on which the executable file runs.

@item
You may not copy, sublicense, distribute or transfer Gnews except
as expressly provided under this License Agreement.  Any attempt
otherwise to copy, sublicense, distribute or transfer Gnews is
void and your rights to use Gnews under this License agreement
shall be automatically terminated.  Nevertheless, parties who have
received computer software programs from you with this License
Agreement will not have their licenses terminated so long as such
parties remain in full compliance.
@end enumerate

@ifinfo
[Hit `n' to continue.]
@end ifinfo

@node NO WARRANTY, usenet, Copying, preface
@unnumberedsubsec NO WARRANTY
@iftex
@hyphenation{war-ran-ties}
@end iftex

BECAUSE GNEWS IS LICENSED FREE OF CHARGE, I PROVIDE ABSOLUTELY NO
WARRANTY, TO THE EXTENT PERMITTED BY APPLICABLE STATE LAW.  EXCEPT
WHEN OTHERWISE STATED IN WRITING, MATTHEW P WIENER AND/OR OTHER
PARTIES PROVIDE GNEWS "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE.
THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM IS
WITH YOU.  SHOULD THE GNEWS PROGRAM PROVE DEFECTIVE, YOU ASSUME THE
COST OF ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW WILL MATTHEW P WIENER
AND/OR ANY OTHER PARTY WHO MAY MODIFY AND REDISTRIBUTE GNEWS AS
PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY LOST
PROFITS, LOST MONIES, OR OTHER SPECIAL, INCIDENTAL OR CONSEQUENTIAL
DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE (INCLUDING BUT
NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR
LOSSES SUSTAINED BY THIRD PARTIES OR A FAILURE OF THE PROGRAM TO
OPERATE WITH PROGRAMS NOT DISTRIBUTED BY FREE SOFTWARE FOUNDATION,
INC.) THE PROGRAM, EVEN IF YOU HAVE BEEN ADVISED OF THE POSSIBILITY
OF SUCH DAMAGES, OR FOR ANY CLAIM BY ANY OTHER PARTY.

@page
@node usenet, emacs, NO WARRANTY, preface
@unnumberedsec Welcome to Usenet

Usenet is a large loosely organized network of thousands of computers.
One to two megabytes a day are now routinely shipped around the United
States, and a large fraction is sent overseas to Europe, Japan, and
Australia.
@cindex Usenet

In order to make some sense out of this, the @dfn{news} is divided up
into @dfn{newsgroups}, each with a particular topic of relevance, more
or less.  Each newsgroup is further divided up into @dfn{articles}, each
of which was written and @dfn{posted} to Usenet.
@cindex news
@cindex newsgroup
@cindex article

An article consists of a @dfn{header}, which lists information about the
article in the form of several lines, each called header @dfn{fields}, and
a @dfn{body} where the main text of the article can be found.
@cindex header
@cindex field
@cindex body

Here's a brief example:

@example
Path: ucbvax!bloom-beacon!tut.cis.ohio-state.edu!karl
From: karl@@tut.cis.ohio-state.edu (Karl Kleinpaste)
Newsgroups: comp.emacs
Subject: Re: Gnews 1.8 available
Message-ID: <17581@@tut.cis.ohio-state.edu>
Date: 12 Jul 88 12:21:25 GMT
References: <11922@@agate.BERKELEY.EDU>
Sender: news@@tut.cis.ohio-state.edu
Lines: 7

weemba@@garnet.berkeley.edu writes:
>Gnews 1.8 is now available for anon ftp, ucbvax:/pub/gnews-1.8-tar.Z.

Gnews 1.8 just now appeared on osu-cis for anonymous UUCP.  The usual
instructions apply; request /u/public/gnews/gnews1.8.Z-a[abc].

--Karl
@end example

The first nine lines are the header.  Two important non-obvious items
are the @t{Message-ID:} and the @t{References:} field.  The former is
the unique Usenet identifying string for the article.  The second is
the list of articles that directly preceded this one in conversation
sequence; in this case the list is one article long.  The above article
only went to a single newsgroup.  Had the article been @dfn{cross-posted},
there would have been a comma separated list of the several newsgroups.
@cindex Message-ID
@cindex References
@cindex cross-posting

The official definition of article headers is contained in the document
@cite{RFC 1037}.

To read Usenet, you have to first find the newsgroups that interest you,
and then, within each newsgroup, the articles that interest you.  To
this end, several @dfn{newsreaders} have been written, of which Gnews
is an example.
@cindex newsreader

Most newsreaders default to showing you all articles within a newsgroup
that you haven't seen before.  You have to take action to further filter
out topics, people, cross-postings, etc that do not interest you.  In
Gnews, this is provided by @dfn{hook-kills}.  @xref{hook-kill, , Hook Kill}.
@cindex hook-kill

There are several other networks besides Usenet, some of which have been
gatewayed into Usenet (and vice versa).  You will occasionally see people
refer to things differently.  Thus what Usenetters call @dfn{newsgroups} are
sometimes called @dfn{notefiles}, @dfn{mailing lists}, @dfn{echo areas}, etc.

For more information about Usenet, read the @kbd{news.announce.newusers}
newsgroup.  It should always be there, but your site might not keep it
around.  If it is empty, it should fill up again shortly after the first
of the month.  (And also you should ask your system administrator to not
expire that newsgroup anymore.)

@node emacs, , usenet, preface
@unnumberedsec Welcome to Emacs?

In principle, it would be possible to use Gnews without any knowledge
of Emacs other than starting and exiting the editor.  This strikes me
as a rather risky way to proceed, although it has been done---even to
the point of successfully installing and using Gnews by Emacs novices.

Hence, I will assume that you are roughly familiar with the first third
or so of @cite{The GNU Emacs Manual}, its chapter on multiple windows,
and its section on your @file{.emacs} file.  Not expert knowledge or
anything, but just enough so that when I refer to things like ``the
region'' or ``name completion'', you will know (or know how to know)
what I am talking about.

No knowledge of Lisp coding is required, although some amount is needed
to customize Gnews.  I do make references to Lisp internals here and
there---feel free to ignore them.  The tiny amount of Lisp mentioned
in @cite{The GNU Emacs Manual} is needed for the simplest of Gnews
customizations.  @xref{customize, , Customize}.

@page
@node start, help, preface, Top
@chapter Starting Gnews

Before you can run Gnews, Emacs must know about existence of the basic
Gnews command @kbd{M-x gnews}.

This relevant knowledge is slightly site dependent.  The basic starting
point for Gnews that is provided with the original sources is the file
@file{Init.el}.  Your site may have added one more Gnews file to override
the defaults; its recommended name is @file{site.el}.  @xref{install, , Install}.
If so, read all references below to @file{Init.el} as your site's file
instead.  I am also assuming that Gnews is installed in a subdirectory
@file{gnews} of something in your @code{load-path}, if not, you must vary the
description below even further.
@pindex Init.el

(As an example of a slightly unusual set up, the math machines at UC
Berkeley have an @file{.../emacs/lisp/} and an @file{.../emacs/lisp_local/}
directory, the former being the official Lisp distribution, and the
latter being a directory for numerous extra packages.  The Gnews
source file @file{xxx.el} is installed in the local directory as
@file{gnews-xxx.el}.)

So to let Emacs know about Gnews, you must inform it, usually in one
of two ways.  For a one-shot, try
@example
M-x load-library @key{RET} gnews/Init @key{RET}
@end example
@noindent
If you decide to use Gnews regularly, put
@example
(autoload 'gnews "gnews/Init" "The Gnewsreader" t)
@end example
@noindent
in your @file{.emacs}.  The final @code{t} is required.
@pindex .emacs

With these preliminaries out of the way, you can then proceed to
actually starting Gnews.  You do one of the following:

@table @kbd
@item M-x gnews
@itemx M-1 M-x gnews
@findex gnews
@pindex .gnewsrc
This is the basic starting call to Gnews.  Gnews will read in your
@file{.gnewsrc} file and initialize most of the internal variables.
If this is your first run of Gnews, it will convert an existing
@file{.newsrc} file over for you.

(This works with an argument of 0 or 1.)

If Gnews is already running, this, like all the variants listed below,
will simply switch you back to your former context.

Here and below, the implicit or @kbd{C-u} (@kbd{universal-argument}) form of
the argument means seek for new news automatically, while the explicit
numeric form means prompt when the initialization is complete.

@item C-u M-x gnews
@itemx M-4 M-x gnews
@pindex .gnewsrc.new
This runs Gnews, starting with the checkpoint file @file{.gnewsrc.new}.  If
the checkpoint file is newer than the usual file, Gnews assumes that some
accident prevented you from saving your @file{.gnewsrc} file as usual the
time before, and it offers to start with the checkpoint file for you.

(This works with any argument 2 or larger.)

@item C-u - M-x gnews
@item M-- M-x gnews
@pindex .gnewsrc.old
This runs Gnews, starting with the @file{.gnewsrc.old} file.  This is the
same starting contents as the last time you ran Gnews.

(This works with any negative argument.)
@end table

Once started, Gnews changes to the @t{*gnews*} buffer; Gnews does not
show the buffer name in the mode line.  (Switch to Fundamental mode if
you wish to see the buffer name.  Then switch back to News mode with
@kbd{M-x news-mode}.)  Gnews divides its reading activity into several modes,
each with its own key bindings.  The three reading modes---News, Group,
Article---are based on the corresponding @t{rn}-levels.  All of them
use the @t{*gnews*} buffer.
@pindex *gnews*
@tindex news-mode

(Annoying note: to help smooth a changeover from 1.9 to 2.0, the basic
command has been changed from @code{gnews} to @code{Gnews}.  If you run
@code{gnews}, you will get a message explaining the changeover.  I shall
change this back eventually, say around version 2.2 or 2.3.)

@page
@node help, news, start, Top
@chapter Gnews help

Like Emacs, Gnews comes with extensive on-line help support.  The manual
itself is available in both on-line and printed versions.
@cindex help

@menu
* documentation::	On-line documentation
* bug reports::		Bug reports
@end menu

@node documentation, bug reports, , help
@section On-line documentation

@table @kbd
@item h
@kindex h
@kbd{describe-mode}
@findex describe-mode
@item H
@itemx C-u H
@kindex H
@kbd{gnews-describe-mode}
@findex gnews-describe-mode
@end table

These are the two basic mode-specific help commands in Gnews.  The
first is the standard on-line Emacs documentation of the current
major mode.  It is the same as @kbd{C-h m}.

@kbd{H} (@code{gnews-describe-mode}) is an expanded version of this, filling
in the list of bound commands with the various commands' documentation
strings.  With an argument, @kbd{H} sets to the relevant chapter of the
Info guide.

@table @kbd
@item C-c ?
@kindex C-c ?
@kbd{describe-mode}
@item C-c C-h
@itemx C-u C-c C-h
@kindex C-c C-h
@kbd{gnews-describe-mode}
@end table

In certain Gnews modes, @kbd{h} and @kbd{H} are self-inserting characters,
so the previous two help functions are relocated to the mode-specific
prefix.

@table @kbd
@item I
@kindex I
@kbd{gnews-Info}
@findex gnews-Info
@item M-h
@kindex M-h
@kbd{gnews-features}
@findex gnews-features
@item C-M-h
@kindex C-M-h
@kbd{gnews-ances}
@findex gnews-ances
@item C
@kindex C
@kbd{gnews-customize}
@findex gnews-customize
@end table

In News mode, certain basic Info references have been built in.  @kbd{I}
goes to the top of the Gnews Info tree.  @kbd{M-h} goes to the node on
the relative features of Gnews over @t{rn}.  @kbd{C-M-h} goes to the
node on bugs and other problems.  @kbd{C} goes to the node of example
customizations.
@cindex manual

(In particular, don't type in code that you think is interesting from
reading the @TeX{} manual!  It's all on-line.)

For those with no sensayuma, @code{gnews-ances} can also be called @code{gnews-bugs}.
@findex gnews-bugs

@node bug reports, , documentation, help
@section Dealing with Gnews bugs

@table @kbd
@item C-w
@kindex C-w
@kbd{gnews-bug-report}
@findex gnews-bug-report
@end table
@cindex bugs

This is the ultimate help function.  The @kbd{C-w} is bound in the
read-only modes---editing modes leave it with the standard Emacs
binding.  It starts a mail message to the author, with Emacs, Gnews
and NNTP/Spool version information.

Bug fixes will usually be whole Emacs functions, rather than context
diffs.  I'd also prefer if you sent any bug fixes to me as whole
functions, since I'd prefer to eval things as they are in my e-mail.
If you send me context diffs, they will probably not get looked at
for quite a while.

With a prefix argument, @kbd{C-w} also starts a @kbd{Cc:} to the Emacs
Bug address.  Do not use this unless you are absolutely certain that
it is an Emacs bug that is causing some Gnews problem.  (You've heard
of why you're not supposed to teach a pig to sing?  No?  It's because
it doesn't work, and futhermore, it annoys the pig.)

@table @kbd
@item M-x gnews-variable-values
@end table
@findex gnews-variable-values

This command, by default, fills the current buffer the value of all
known Gnews variables.  To get a smaller amount of information, set
the variable @code{gnews-variable-list}, normally unbound, to a list of
the desired variables.

@page
@node news, group, help, Top
@chapter Newsgroup selection level

News mode is used by Gnews for selecting newsgroups, and performing
some broad clerical functions.  News mode is also called the ``top
level'' of Gnews.
@cindex top level
@cindex newsgroup

At any point, Gnews has a notion of the current newsgroup, defined
internally as the value of the Lisp variable @code{group-current}.  On
start up, this is set to the first newsgroup in your @file{.gnewsrc}.
@pindex .gnewsrc

On rare occasions, Gnews detects that you have apparently been reading
articles past the last one.  This can be caused by several things:
editing your @file{.gnewsrc}, switching news servers, two or more of the
very latest articles in a newsgroup being cancelled, or even a Gnews
bug.  (This last case has not been completely eliminated, but it is
rare and rather obscure.)
@cindex bugs

Gnews responds by putting up a temporary warning buffer, and reminding
you of some of the more relevant commands.  You will probably just use
@kbd{c} (@code{news-catchup}).  Most Gnews commands erase the warning buffer
for you.
@cindex warning

@menu
* motion:news motion.	Top level motion through the newsgroups
* get:news get.		Visiting newsgroups by name
* gnewsrc::		@file{.gnewsrc.*} file modification
* enter:news enter.	Entering the current newsgroup
* abbrev:news abbrev.	Abbreviating newsgroup names
* misc:news misc.	Miscellaneous news commands
@end menu

@node news motion, news get, , news
@section Moving through the newsgroups

@table @key
@item SPC
@kindex SPC
@kbd{news-default}
@findex news-default
@end table

The most basic News mode command is @key{SPC} (@code{news-default}).  It
runs the current default command, one of @kbd{n} (@code{news-next-unread}),
@kbd{y} (@code{news-yes}), and sometimes @kbd{q} (@code{news-quit}).  These
defaults, along with those in Group and Article mode, enable you to
read through the new news in your subscribed newsgroups hitting nothing
but @key{SPC} until you finally exit from Gnews.

The current default can be identified from the newsgroup prompt, usually
something like ``@kbd{comp.protocols.tcp-ip.eniac @{16@} [ynp] ?}''.  The
number in braces is the number of unread articles in the named newsgroup,
while the bracketed string lists the most typical commands available at
this juncture, with the default being the first one in the string.

@table @kbd
@item n
@kindex n
@kbd{news-next-unread}
@findex news-next-unread
@item N
@kindex N
@kbd{news-next}
@findex news-next
@item p
@kindex p
@kbd{news-previous-unread}
@findex news-previous-unread
@item P
@kindex P
@kbd{news-previous}
@findex news-previous
@end table

These commands are used to go back and forth through your @file{.gnewsrc}.
They only consider subscribed-to newsgroups.  While passing through
several subscribed-to groups without new news, a series of running
dots, one for each such newsgroup, is displayed.
@pindex .gnewsrc

The two @code{news-*-unread} commands furthermore only stop at newsgroups
with unread news.  They both cycle round at the end of the newsgroup
list.
@cindex $-pseudo group

The other two motion commands stop at any of the subscribed-to newsgroups,
new news or no new news.

@table @kbd
@item 1
@kindex 1
@kbd{news-first}
@findex news-first
@item ^
@kindex ^
@kbd{news-first-unread}
@findex news-first-unread
@item $
@kindex $
@kbd{news-end}
@findex news-end
@item -
@kindex -
@kbd{news-last-seen}
@findex news-last-seen
@end table

@kbd{1} (@code{news-first}) and @kbd{^} (@code{news-first-unread}) go to the
beginning of your @file{.gnewsrc} and then look forward for a subscribed-to
newsgroup.  @kbd{1} stops at the first such group, while @kbd{^} stops at
the first such group with unread news.
@pindex .gnewsrc

@kbd{$} (@code{news-end}) goes to a fake pseudo-newsgroup at the end of your
@file{.gnewsrc} file.  The prompt here is typically ``@kbd{more [npq] ?}''
or ``@kbd{more [qnp] ?}''.  Forward newsgroup motion will wrap to the first
newsgroup, while backward newsgroup motion will start at the end.
@cindex $-pseudo group

@kbd{-} (@code{news-last-seen}) toggles to the last newsgroup where news was
proffered.  Repeating it takes you back to where you had just been.

@node news get, gnewsrc, news motion, news
@section Getting newsgroups by name

Newsgroups can also be entered by name; this is the only way to get to
unsubscribed-to newsgroups.

Gnews offers name-completion on names and maintains an abbreviation list,
for which @pxref{news abbrev, abbrev, Abbrev}.

@table @kbd
@item g
@kindex g
@kbd{news-goto}
@findex news-goto
@item v
@kindex v
@kbd{news-visit}
@findex news-visit
@item G
@kindex G
@kbd{news-general-goto}
@findex news-general-goto
@end table

@kbd{g} (@code{news-goto}) and @kbd{v} (@code{news-visit}) both enter the prompted-for
newsgroup.  The former always resubscribes, and the latter preserves the
group's subscription status information.  In order to take advantage of name
completion, these commands are restricted to groups in your @file{.gnewsrc}.
@pindex .gnewsrc

@kbd{G} (@code{news-general-goto}) is used to get to arbitrary newsgroups that
your server carries.  In order to take advantage of name-completion, this
command is restricted to newsgroups existing at your site.  The only way to
get a name for an arbitrary newsgroup is to directly edit your @file{.gnewsrc}.

These three commands recognize an @kbd{=} or @kbd{@@}, when typed as the first
character before entering a newsgroup name, as special.  The former means
enter the newsgroup in Index mode, while the latter says just reset the
current newsgroup to the named group internally, without actually entering
the group.
@cindex index

@table @kbd
@item M-g
@kindex M-g
@kbd{news-new}
@findex news-new
@end table

@kbd{M-g} (@code{news-new}) is used to subscribe to new newsgroups.

If on startup Gnews detects that new newgroups have arrived, it tells
you and reminds you of this command.
@cindex newsgroup

Running @code{news-new} puts you into a loop.  Gnews prompts for a new
newsgroup name.  Name completion will reveal what is available.  To finish
early, use @kbd{C-g}.

Since most often only one new newsgroup has arrived, name completion with
@key{TAB} is recommended.

Note: this command is an ugly kludge, but will not be rewritten for the
time being.

@table @kbd
@item /
@kindex /
@kbd{news-pattern-forward}
@findex news-pattern-forward
@item ?
@kindex ?
@kbd{news-pattern-backward}
@findex news-pattern-backward
@end table

These two commands proffer to read news from the next newsgroup matching
a prompted-for regular expression, whose default is the previous such
regular expression.

@node gnewsrc, news enter, news get, news
@section @file{.gnewsrc.*} file modification

Gnews does not work directly with @file{.newsrc} files, the usual Usenet
standard.  Instead, Gnews uses its own Lisp version, the @file{.gnewsrc}
file.  If you have a @file{.newsrc} but no @file{.gnewsrc} file, Gnews will
create the appropriate file for you.  Conversion back is available.
@pindex .newsrc
@pindex .gnewsrc

@table @kbd
@item q
@kindex q
@kbd{news-quit}
@findex news-quit
@item x
@kindex x
@kbd{news-quit-restore}
@findex news-quit-restore
@end table

These two commands are the standard ways of exiting Gnews.  The first
writes out a new @file{.gnewsrc} and perhaps a new @file{.gnewsrc.hook}.
The second does not change the current @file{.gnewsrc}, but saves the
internals in @file{.gnewsrc.new}.
@pindex .gnewsrc
@pindex .gnewsrc.new
@pindex .gnewsrc.hook

@table @kbd
@item R
@kindex R
@kbd{news-restart}
@findex news-restart
@end table

This updates the @file{.gnewsrc.*} files, and then restarts the internals.

@table @kbd
@item Q
@kindex Q
@kbd{news-rc-restore}
@findex news-rc-restore
@end table

This command translates the current internal @file{.gnewsrc} data into
the standard @file{.newsrc} format and writes it out.  If a @file{.newsrc}
file already exists, Gnews will ask for confirmation.
@pindex .newsrc

A mnemonic for this is ``the Big-Gnews-Quit''@.  Nice knowing you @dots{}.

@table @kbd
@item D
@kindex D
@kbd{news-delete}
@findex news-delete
@end table

This deletes a prompted-for newsgroup from your @file{.gnewsrc}.

@table @kbd
@item M
@kindex M
@kbd{news-move}
@findex news-move
@end table

This moves the current newsgroup to after a prompted-for newsgroup.

@node news enter, news abbrev, gnewsrc, news
@section Entering the current newsgroup

@table @kbd
@item @@
@kindex @@
@kbd{news-at}
@findex news-at
@end table

This command identifies the current newsgroup.
@cindex newsgroup

@table @kbd
@item y
@kindex y
@kbd{news-yes}
@findex news-yes
@item .
@kindex .
@kbd{news-immediate}
@findex news-immediate
@end table

These two commands enter the current newsgroup.
@cindex newsgroup

@kbd{y} (@code{news-yes}) sets to the first unread article within the newsgroup.

@samp{.} (@code{news-immediate}) sets the internals to the first unread article,
but without actually displaying this article.  Typeahead flushing is
turned off in this case, allowing the user to type things like @samp{.$}
to enter at the end of a newsgroup, or @samp{./} to begin a pattern
search, etc.
@cindex typeahead

@table @kbd
@item =
@kindex =
@kbd{news-index}
@findex news-index
@item u
@kindex u
@kbd{news-unsubscribe}
@findex news-unsubscribe
@item c
@kindex c
@kbd{news-catchup}
@findex news-catchup
@item m
@kindex m
@kbd{news-mark}
@findex news-mark
@end table

These commands, index, unsubscribe, catch up in, or uncatch up in the
current newsgroup respectively.  With a numeric argument, @kbd{c} and @kbd{m}
perform partial catch/uncatch ups.

For example, partial catchups will mark all but the last so-many articles
as read.  An explicit numeric argument leaves that many articles unread.
Repeating @kbd{C-u} leaves ten times the number of @kbd{C-u}s unread.

Note that this is a deviation from the usual Emacs meaning of @kbd{C-u}.

Indexing is a complete mode.  @xref{index, , Indexing}.
@cindex index

@node news abbrev, news misc, news enter, news
@section Abbreviating newsgroup names
@cindex abbreviations

@table @kbd
@item C-a
@kindex C-a
@kbd{gnews-abbrev-add}
@findex gnews-abbrev-add
@item M-a
@kindex M-a
@kbd{gnews-abbrev-delete}
@findex gnews-abbrev-delete
@item C-M-a
@kindex C-M-a
@kbd{gnews-abbrev-list}
@findex gnews-abbrev-list
@end table

These three commands, only bound in News mode, add/delete/list to the
newsgroup abbreviations.  @kbd{C-a} prompts for an abbreviation, and
then the string that this abbreviation is intended to abbreviate.
@kbd{M-a} prompts for an abbreviation, and then deletes it from the
list.  No command for changing abbreviations is provided.

An abbreviation consists of any string of non-period characters.  It
abbreviates a string that should be one or more dot-concatenated @dfn{parts}
of a newsgroup name.  By this I mean strings like ``@t{rec}'', ``@t{rec.arts}'',
``@t{arts}'',  ``@t{rec.arts.comics}'', etc.

To expand an abbreviation, use @samp{.} or @key{LFD}.  The immediately preceding
part is then expanded as an abbreviation.  In case of @samp{.}, the literal
@samp{.} is preserved, and the user can proceed to the next part of the
newsgroup name.  In case of @key{LFD}, the name is first abbreviation
expanded, then name-completed, and then exited if the user variable
@code{group-name-confirm} is @code{nil}, or upon confirmation if it is non-@code{nil}.

@samp{.} and @kbd{$} by themselves abbreviate the current and the last newsgroup
respectively.

If, for example, @kbd{l} abbreviates @samp{comp.lang}, then typing @kbd{l.}
yields @samp{comp.lang.}.  The result of @key{LFD} would depend on your
@file{.gnewsrc}.  If @t{comp.lang} is there, then that group will be offered.
Furthermore, if you have other @kbd{comp.lang.*} groups, then
name-completion will signal ``@kbd{[Complete, but not unique]}''.  On the
other hand, if you don't have @t{comp.lang}, @key{LFD} will look for the
longest match it can find among the @t{comp.lang.*} groups that you
do have.@refill

Another example: if @kbd{m} abbreviates @kbd{misc}, then @kbd{sci.m@key{LFD}} expands to
@t{sci.misc}, whereas @kbd{sci.m@key{RET}} name-expands, perhaps offering @t{sci.med} or
@t{sci.math} in addition to @t{sci.misc}, depending on your @file{.gnewsrc}.
@pindex .gnewsrc

Note: the phrase ``your @file{.gnewsrc}'' is a simplification of the full
story.  Name expansion is done on those newsgroups which happen to be
relevant to the given command.  Usually this is the contents of your
@file{.gnewsrc}, but not always.  Thus @kbd{G} (@code{news-general-goto}) offers name
expansion on all the newsgroups at your site, while @kbd{M-g} (@code{news-new})
offers name expansion on the new newsgroups.  If restrictions are in
effect (@pxref{news misc, , News Misc}), then the restrictions will apply
to most newsgroup naming commands.

@node news misc, , news abbrev, news
@section Miscellaneous news commands

@table @kbd
@item o
@kindex o
@kbd{news-only-match}
@findex news-only-match
@item a
@kindex a
@kbd{news-add-match}
@findex news-add-match
@end table

These two commands create what is called a @dfn{restriction}: all
newsgroup profferings will be restricted to those names that match a
prompted-for regexp.  @kbd{o} (@code{news-only-match}) is for restricting
what to look at in your @file{.gnewsrc}.  @kbd{a} (@code{news-add-match}),
after prompting for a regexp, prompts for new newsgroups from your
site's master list that match the prompted-for regexp.  The restrictions
stay in effect after an @kbd{a}.
@cindex restrictions
@pindex .gnewsrc

To remove restrictions, restrict to the null string: type @kbd{o @key{RET}}.

@table @kbd
@item V
@kindex V
@kbd{gnews-version}
@findex gnews-version
@end table

This returns the Gnews version number you are using.  With a prefix
argument, it return the version number of the underlying NNTP.
@pindex NNTP

@table @kbd
@item !
@kindex !
@kbd{shell}
@findex shell
@end table

This is the Emacs @kbd{M-x shell} command.
@xref{Interactive Shell, shell, Shell, emacs, GNU Emacs Manual}.

@table @kbd
@item M-k
@kbd{news-hook-edit}
@end table

@xref{hook-edit, , Hook Editing}.

@table @kbd
@item h
@kbd{describe-mode}
@item H
@kbd{gnews-describe-mode}
@item M-h
@kbd{gnews-features}
@item C-M-h
@kbd{gnews-ances}
@item C
@kbd{gnews-customize}
@end table

@xref{help, , Help}.

@table @kbd
@item C-g
@kindex C-g
@kbd{keyboard-quit}
@findex keyboard-quit
@end table

While not strictly speaking part of News mode, @kbd{C-g} (@code{keyboard-quit})
is handled in News mode when searching for the next newsgroup.  The search
is interrupted, and Gnews proffers whatever group it was interrupted at.

@table @kbd
@item M-l l
@kindex M-l l
@kbd{gnews-legalese-license}
@findex gnews-legalese-license
@item M-l c
@kindex M-l c
@kbd{gnews-legalese-copying}
@findex gnews-legalese-copying
@item M-l w
@kindex M-l w
@kbd{gnews-legalese-no-warranty}
@findex gnews-legalese-no-warranty
@end table

These commands set to the Info node that describe the indicated notion.

@page
@node group, reply, news, Top
@chapter Article selection/paging level

Group mode and Article mode (which calls itself ``Pager'') are almost
the same mode.  The distinction was lifted out of @t{rn}; it is usually
unimportant.  Group mode is intended for the commands that run back and
forth through a given newsgroup, and is entered whenever you are at the
end of a given article.  Article mode is intended for the commands that
deal with a particular article, and is entered whenever you have not
finished paging through a given article.  This split runs afoul of the
fact that many useful article specific commands are still of use when
at the end of an article, and so certain @code{article-*} commands have
also migrated to Group mode.
@cindex newsgroup

In Group and Article mode, the digits @kbd{0} to @kbd{9} serve a dual role.
They can be used to type in articles by number to apply commands to,
or they can be used to supply digit arguments to commands that expect
numeric prefixes.  The first digit typed turns on the prompt @kbd{Article(s):},
which is appropriate for an article by number prefix, but wrong for the
numeric prefix.  Of course, Gnews is unable to tell ahead of time which
you intend.  The empty command---that is, hitting return---is treated
as an @code{article-get}.  @xref{artget, , Getting Articles}.
@findex article-get
@findex digit-argument

Most of the headers in an article are boring.  Suppression of header
display is provided by the @code{article-header-ignore} list; the default
gets most of the known ugly headers.  If you wish to get rid of more,
then append to this list.  If you wish to display more, put the desired
headers in the @code{article-header-show} list.  To see all of them, set
@code{article-header-all-p} to @code{t}.
@cindex header
@vindex article-header-all-p
@vindex article-header-show
@vindex article-header-ignore

The mode line displays something like the following when within an article:
@cindex mode line

@example
--- Gnews: alt.california 225/244 (Pager)----49%--------
@end example

and something like

@example
--- Gnews: alt.california */244 (Group)----100%-------
@end example

when you get to the end of an article and are in Group mode.

This means that you are in newsgroup @t{alt.california}, 244 is the last
article in the newsgroup, and 225 is the current article number.

The percentages are not the usual Emacs style.  They refer instead to the
fraction of the article body that has been seen, counting through to the
@i{bottom} of the display.  This is borrowed from @t{rn}, and makes it easy
to decide quickly whether the current article is too long for your
interests.

The display of articles is buffered.  This means that the full article
is not guaranteed to be present in the @t{*gnews*} buffer until you reach
the actual end of the article.  Emacs commands which depend on the whole
article being present will not work.  The more standard such commands
have been implemented directly in Gnews.

Note that article numbers are only meaningful at your own site, for the
convenience of the news software.  The @t{Message-ID:} field is the only
way to refer to articles in an absolute sense.
@cindex Message-ID

Gnews puts a fictional article right after the last article, sometimes
called the @kbd{$}-end or @kbd{$}-pseudo-article of the newsgroup.  The
mode line displays a @kbd{$} instead of an article number.  Most group and
pager commands are inactive at the @kbd{$}-end.
@cindex $-pseudo article

@menu
Current newsgroup generalities:

* defnext::		Next and previous: definitions
* motion::		Motion within a newsgroup
* pattern::		Header pattern searches
* artget::		Getting articles directly
* quit::		Quitting the current newsgroup

Article particulars:

* scroll::		Scrolling within an article
* restart::		Restarting an article
* rot13::		Reading encrypted articles
* edit::		Editing article displays
* junk::		Junking, killing and marking articles
* grep::		Article pattern searches
* save::		Saving articles
* misc:group misc.	Miscellaneous group commands
@end menu

@node defnext, motion, , group
@section Next and previous: definitions

When discussing motion within a given newsgroup, @dfn{next article} refers
to the article with the next higher article number at your site.  It is
usually the current article plus one, but it can be larger, since gaps will
occur in the numeric sequence, either when an article has been
@dfn{cancelled}, or when your site's news software has @dfn{expired} the
article.
@cindex expire
@cindex cancel

(Note that the sequencing is generally based on the arrival times of the
articles at your site, and is only loosely connected to any true notion of
time.  In particular, it is possible to see someone's reply to something
before the something in question.)

@dfn{next unread article} refers to the next higher article number that you
have not yet read.  Gnews keeps track of read and unread articles with a
special list of article markers, called an @dfn{amark} for short.  The
elements of this list are either numbers or @dfn{dotted pairs} of numbers.
The numbers indicate that that particular article has been marked read,
while the dotted pairs indicated that all articles from the front moiety of
the pair through to the back moiety of the pair, inclusive, have been
marked read.  For example, the amark @samp{((1.3) 6 (9.12) 22 25)} means
that articles 1, 2, 3, 6, 9, 10 ,11, 12, 22, 25 have been marked read.
Your @file{.gnewsrc} consists mostly of amarks.
@cindex amark
@pindex .gnewsrc

For the current newsgroup, the amark at any time is the value of the Lisp
variable @code{amark}.  @dfn{Dotted pair} is the standard Lisp term for the
above construct of parenthesis something dot something parenthesis.
@tindex amark

The notions @dfn{previous article} and @dfn{previous unread article} are
similar to the two above, but refer to the reverse direction.

If an index is present, the meanings of ``next'' and ``previous'' are
changed to follow the sequence the articles as they are in the @i{index}
buffer.  This need not be the same as the standard order because of
sorting.  Moreover, next and previous type motion is restricted to the
indexed articles.  @xref{index, , Indexing}.
@cindex index

(No command is provided for telling Gnews to ignore the index buffer.  You
can do this by evaluating @samp{(makunbound 'index-pop)}.  To restore
Gnews' awareness of the index buffer, evaluate @samp{(setq index-pop
index-pop-up)}.  Bind these to your own toggle if you wish.)
@tindex index-pop
@vindex index-pop-up

@node motion, pattern, defnext, group
@section Motion within a newsgroup

@table @kbd
@item @key{SPC}
@kindex SPC
@kbd{group-default}
@findex group-default
@end table

@key{SPC} (@code{group-default}) runs the current default Group mode command.
This is the command bound to the first key in the prompt, which is usually
@kbd{n}, as in @code{group-next-unread}.  Certain commands change the default.

This command is not to be confused with @code{article-forward}, also bound to
@key{SPC}, but when in Article mode.  Together, these two commands allow
you to space bar your way through a newsgroup.  @xref{scroll, , Scrolling}.

@table @kbd
@item n
@kindex n
@kbd{group-next-unread}
@findex group-next-unread
@item p
@kindex p
@kbd{group-previous-unread}
@findex group-previous-unread
@end table

These two commands move to the next or previous unread article.  They will
both wrap around the ends of the current newsgroup if possible.
@cindex $-pseudo article

@kbd{n} (@code{group-next-unread}) will exit the newsgroup if there are no
more unread articles.  @kbd{p} (@code{group-previous-unread}) will ding the
user.

@table @kbd
@item N
@kindex N
@kbd{group-next}
@findex group-next
@item P
@kindex P
@kbd{group-previous}
@findex group-previous
@end table

These two commands move to the next or previous article, regardless of its
read status.

@kbd{N} (@code{group-next}) will move to the @kbd{$}-end of a newsgroup if
invoked when at the last available article.  @kbd{P} (@code{group-previous})
will ding the user if invoked at the first available article.

These two commands take numeric prefixes, meaning move through that many
articles.

@table @kbd
@item $
@kindex $
@kbd{group-last}
@findex group-last
@end table

@kbd{$} (@code{group-last}) will move to the @kbd{$}-end of a newsgroup.
@cindex $-pseudo article

@node pattern, artget, motion, group
@section Header pattern searches

@table @kbd
@item /
@kindex /
@kbd{group-pattern-forward}
@findex group-pattern-forward
@item ?
@kindex ?
@kbd{group-pattern-backward}
@findex group-pattern-backward
@end table

These two commands search through the current newsgroup, article by article
in the given direction, for a prompted-for regexp, in the prompted-for
header field.

The first time either one is used within a newgroup, it prompts for the
pattern and the header.  Later uses of either one will repeat this same
pattern and header.

@table @kbd
@item M-/
@kindex M-/
@kbd{group-pattern-forward-new}
@findex group-pattern-forward-new
@item M-?
@kindex M-?
@kbd{group-pattern-backward-new}
@findex group-pattern-backward-new
@end table

These two commands also search for a pattern.  Each prompts for a regexp
and a header, and then make this regexp and header the pattern to use in
later @kbd{/} and @kbd{?} commands within this visit to the current
newsgroup, until changed again perhaps by @kbd{M-/} or @kbd{M-?}.

Normally all articles are searched over.  With a prefix argument, you
restrict the search to unjunked articles.  With a range argument, you
restrict the search to the indicated articles.

These commands change the default command @key{SPC} (@code{group-default}) to
repeating the previous search.  The end-of-article prompt is changed to
reflect this; it becomes either @kbd{[/?npq]} or @kbd{[?/npq]}.

Forthcoming: NNTP 1.5 has a command to get a batch of article headers for a
particular field, so I will be writing code to take advantage of this soon.
You should update your NNTP.
@pindex NNTP

This command is defective compared to @t{rn}.  Searching is restricted to a
particular header field only.  No provision is yet made for full header or
full article searches.  Nor is it possible to invoke commands automatically
on each article.
@pindex rn

@node artget, quit, pattern, group
@section Getting articles directly

@table @kbd
@item #
@kindex #
@kbd{article-get}
@findex article-get
@item @@
@kindex @@
@kbd{article-get-msg-id}
@findex article-get-msg-id
@end table

@kbd{#} (@code{article-get}) prompts for an article number.  It is not
necessary to actually type @kbd{#}; a number followed by a return is
interpreted as this command.

@kbd{@@} (@code{article-get-msg-id}) retrieves an article by message-ID.  If a
message-ID is in the body of the current article after point, it will be
put in the minibuffer as the default.  Hit return if it is the one you
want, otherwise erase it and type the one you wish.
@cindex Message-ID

To return to the article you were at, use @kbd{T} (@code{group-trace-return}).

@table @kbd
@item t
@kindex t
@kbd{group-trace}
@findex group-trace
@item T
@kindex T
@kbd{group-trace-return}
@findex group-trace-return
@end table

@kbd{t} (@code{group-trace}) traces back conversations through the
@t{References:} header field.  @kbd{t} will go to the first referenced
article, counting from the end, @kbd{2t} will go to the second one, etc.
@kbd{0t} will go to the @dfn{root} or @dfn{base} reference, that is, the
first one in the @t{References:} field.
@cindex References

When in a trace back sequence, the article number is set to 0.

@kbd{T} (@code{group-trace-return}) returns to the article you were at when
you began getting the current article(s) via message-IDs.

@table @kbd
@item ^
@kindex ^
@kbd{group-first}
@findex group-first
@item -
@kindex -
@kbd{group-last-seen}
@findex group-last-seen
@item *
@kindex *
@kbd{group-reply-return}
@findex group-reply-return
@end table

@kbd{^} (@code{group-first}) goes to the earliest article in this newgroup at
your site.  @kbd{-} (@code{group-last-seen}) toggles to the last article seen
in this newsgroup.  @kbd{*} (@code{group-reply-return}) goes to the article
that the most recent reply was started from.

@node quit, scroll, artget, group
@section Quitting the current newsgroup

@table @kbd
@item q
@kindex q
@kbd{group-quit}
@findex group-quit
@item C-M-q
@kindex C-M-q
@kbd{group-quit-emergency}
@findex group-quit-emergency
@end table

@kbd{q} (@code{group-quit}) is the normal way of exiting from a newsgroup
before you've read all the articles in it.
@cindex newsgroup

@kbd{C-M-q} (@code{group-quit-emergency}) quits the newsgroup and Gnews in good
order, saving what can be saved, bypassing as many Lisp internals as it
can.  This is needed when really gross bugs make a normal exit impossible.
 As far as I know, this only occurs when tinkering with the code; Gnews
itself is rather robust.
@cindex bugs

@table @kbd
@item c
@kindex c
@kbd{group-catchup}
@findex group-catchup
@item u
@kindex u
@kbd{group-unsubscribe}
@findex group-unsubscribe
@end table

Catching up, without any arguments, marks all the articles in the newsgroup
as being read.  Partial catchups are also supported.  @xref{news enter,
enter, Entering Newsgroups}.

Unsubscribing from a group means Gnews will ignore this group in the future
until you explicitly request it.  @xref{news get, get, Getting Newsgroups}.

@node scroll, restart, quit, group
@section Scrolling within an article

@table @kbd
@item @key{SPC}
@kindex SPC
@kbd{article-forward}
@findex article-forward
@item d
@kindex d
@kbd{article-down}
@findex article-down
@item @key{LFD}
@kindex LFD
@kbd{article-line}
@findex article-line
@item @key{RET}
@kindex RET
@kbd{article-line}
@findex article-line
@end table

@key{SPC} (@code{article-forward}) scrolls forward a full screen, and @kbd{d}
(@code{article-down}) scrolls forward a half page.

If a formfeed is present, that is, a single @ctrl{L} on line by itself,
scrolling will stop at the formfeed, and the next forward scroll command
will fill in the rest of the screen.
@cindex formfeed

@key{LFD} or @key{RET} (@code{article-line}) scrolls forward one line.

@table @kbd
@item @key{DEL}
@kindex DEL
@kbd{group-back}
@findex group-back
@item b
@kindex b
@kbd{group-back}
@findex group-back
@item B
@kindex B
@kbd{group-back-half}
@findex group-back-half
@end table

@kbd{b} (@code{group-back}) and @kbd{B} (@code{group-back-half}) scroll
backwards, a full and a half screen, respectively.

@table @kbd
@item @key{TAB}
@kindex TAB
@kbd{article-skip-indent}
@findex article-skip-indent
@end table

This command scrolls past all lines that begin with the same character the
begins the bottom of the screen.  This is a convenient way to get past long
quotations of one article inside another.

@table @kbd
@item >
@kindex >
@kbd{article-end}
@findex article-end
@end table

The command goes to the end of the current article.

@node restart, rot13, scroll, group
@section Restarting an article

@table @kbd
@item C-l
@kindex C-l
@kbd{article-recenter}
@findex article-recenter
@end table

This command redisplays the screen.  Non-Gnews motion commands interfere
with Gnews' control of the percentage; @kbd{C-l} (@code{article-recenter})
will restore it.

@table @kbd
@item <
@kindex <
@kbd{article-restart}
@findex article-restart
@item v
@kindex v
@kbd{article-restart-verbose}
@findex article-restart-verbose
@item .
@kindex .
@kbd{article-restart-reset}
@findex article-restart-reset
@item M-r
@kindex M-r
@kbd{article-restart-reset}
@findex article-restart-reset
@end table

These all restart an article at the beginning.  @kbd{<} (@code{article-restart})
goes to the beginning of the buffer.  @kbd{v} (@code{article-restart-verbose})
does this and displays all headers.  @samp{.} (@code{article-restart-reset}) starts
the current article over again.

@node rot13, edit, restart, group
@section Reading encrypted articles

@table @kbd
@item X
@kindex X
@kbd{article-rot13}
@findex article-rot13
@item x
@kindex x
@kbd{article-rot13-forward}
@findex article-rot13-forward
@item C-M-x
@kindex C-M-x
@kbd{article-rot13-restart}
@findex article-rot13-restart
@end table

These three commands are used for reading rot13-encrypted articles, meaning
that each letter has been displaced cyclically 13 letters through the
alphabet.
@cindex rot13

@kbd{X} (@code{article-rot13}) does a rot13, and leaves the screen position
the same.  @kbd{x} (@code{article-rot13-forward}) does a rot13 and scrolls
forward one screenful.  @kbd{C-M-x} (@code{article-rot13-restart}) begins the
article over again rot13-ed.

In contrast to @t{rn}, rot13-ing is always relative to the current buffer,
and not relative to the original article.  And saving a rot13-ed article
saves from the display, not the original contents.

Automatic rot13ing is possible, by setting @code{gnews-rot13-p} to @code{t} in
a per-hook or article header hook.  @xref{hook-examples, , Example Hook Kills}.

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @kbd
@item C-u M-x article-digest
@item C-u M-x article-digest-if
@findex article-digest
@findex article-digest-if
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

These two commands---note the prefix argument---are for rot13ing digests
using Digest mode.  The first is for use in newsgroups where all articles
are rot13ed digests, then second for newsgroups where only some are.
These two commands are primarily meant for use in hook-kills.
@xref{digest, , Digests}.


@node edit, junk, rot13, group
@section Editing article displays

@table @kbd
@item l
@kindex l
@kbd{article-downcase}
@findex article-downcase
@item _
@kindex _
@kbd{article-ununderline}
@findex article-ununderline
@end table

These two commands are for fixing articles containing too many uppercase
letters or unreadable attempts at underlining.

@table @kbd
@item W
@kindex W
@kbd{article-edit}
@findex article-edit
@end table

More generally, one can fix the cosmetic appearance of any article, either
just for reading or before saving.  @kbd{W} (@code{article-edit}) puts you in
Gnews Edit mode, which is ordinary Text mode with a few extra commands.

@table @kbd
@item C-c C-c
@kindex C-c C-c
@kbd{gnews-edit-exit}
@findex gnews-edit-exit
@item C-c C-]
@kindex C-c C-]
@kbd{gnews-edit-abort}
@findex gnews-edit-abort
@end table

@kbd{C-c C-c} (@code{gnews-edit-exit}) returns to Article mode directly.
@kbd{C-c C-]} (@code{gnews-edit-abort}) returns to Article mode, but first
restores the pre-editing contents.

@table @kbd
@item C-c C-r
@kindex C-c C-r
@kbd{gnews-edit-rot13}
@findex gnews-edit-rot13
@end table

@kbd{C-c C-r} (@code{gnews-edit-rot13}) rot13s the region.  @xref{rot13, , Rot13}.

@table @kbd
@item C-c ?
@kbd{describe-mode}
@item C-c C-h
@kbd{gnews-describe-mode}
@end table

These are the usual and extended help commands, @pxref{help, , Help}.

@node junk, grep, edit, group
@section Junking, killing and marking articles

@table @kbd
@item j
@kindex j
@kbd{group-junk}
@findex group-junk
@item J
@kindex J
@kbd{group-junk-local}
@findex group-junk-local
@end table

These two commands junk the current article, meaning mark it as read.
@kbd{j} junks the article and all cross-references of the current article.
@kbd{J} junks within the current newsgroup only.

These commands are for Group mode use.  When junking via hook-kills,
@code{article-junk} and @code{article-junk-local} are used.  @xref{hook-theory,
 , Hook Kill Explanations}.
@cindex junking

@table @kbd
@item k
@kindex k
@kbd{group-kill}
@findex group-kill
@item K
@kindex K
@kbd{group-kill-permanent}
@findex group-kill-permanent
@item M-k
@kindex M-k
@kbd{group-hook-edit}
@findex group-hook-edit
@end table

The first kill command ``kills'' the current @t{Subject} field, meaning
that in this pass through the newsgroup, articles with the same subject
will be silently junked.  The second kill command ``KILLs'' the current
topic, meaning that a hook-kill entry for this subject will be made, and
until removed, this subject will always be silently junked.
@xref{hook-theory, , Hook Kill Explanations}.
@cindex kill
@cindex KILL
@cindex hook-kill

The hook-kills for a given newsgroup may be edited with the @kbd{M-k}
(@code{group-hook-edit}) command.  @xref{hook-edit, , Hook Edit}.

@table @kbd
@item m
@kindex m
@kbd{group-mark}
@findex group-mark
@item M
@kindex M
@kbd{group-mark-later}
@findex group-mark-later
@item M-m
@kindex M-m
@kbd{group-mark-permanent}
@findex group-mark-permanent
@end table

@dfn{Marking} refers to marking an article as unread.  @kbd{m} (@code{group-mark}) is
temporary, while in the current newsgroup.  @kbd{M} (@code{group-mark-later}) will
junk the article for now, but leave it marked unread after exiting the
newsgroup.  @kbd{M-m} (@code{group-mark-permanent}) will junk the current article,
but leave an indication inside your hook-kills to re-insert it, flagged as
marked, when indexing.  @xref{index, , Indexing}.
@cindex marking
@cindex index

@node grep, save, junk, group
@section Article pattern searches

@table @kbd
@item C-s
@kindex C-s
@kbd{article-isearch-forward}
@findex article-isearch-forward
@item C-r
@kindex C-r
@kbd{article-isearch-backward}
@findex article-isearch-backward
@item C-M-s
@kindex C-M-s
@kbd{article-isearch-forward-regexp}
@findex article-isearch-forward-regexp
@item C-M-r
@kindex M-C-r
@kbd{article-isearch-backward-regexp}
@findex article-isearch-backward-regexp
@end table

These run the standard Emacs isearch commands.  They usual incremental
search commands will not work correctly, since the article display is
buffered.

@table @kbd
@item g
@kindex g
@kbd{article-grep}
@findex article-grep
@item G
@kindex G
@kbd{article-grep-repeat}
@findex article-grep-repeat
@item M-g
@kindex M-g
@kbd{article-grep-digest}
@findex article-grep-digest
@end table

These commands are included for compatibility with @t{rn}.  Most users
will probably use the incremental search commands.
@pindex rn

These run a @file{grep} on the current article.  @kbd{g} (@code{article-grep})
searches forward, or backwards with a prefix article, for a prompted-for
regexp.  @kbd{G} (@code{article-grep-repeat}) will repeat the previous grep
search, and will reverse directions with a prefix argument.

@kbd{M-g} (@code{article-grep-digest}) greps on @code{article-digest-separator},
a regexp appropriate for most digests.  This command comes from @t{rn}, but
Gnews comes with its own Digest mode.  @xref{digest, , Digests}.
@cindex digest

@node save, group misc , grep, group
@section Saving articles

@table @kbd
@item s
@kindex s
@kbd{group-save}
@findex group-save
@item o
@kindex o
@kbd{gnews-output-to-rmail-file}
@findex gnews-output-to-rmail-file
@item C-o
@kindex C-o
@kbd{gnews-output-to-mbox-file}
@findex gnews-output-to-mbox-file
@end table

@kbd{s} (@code{group-save}) is the basic save command.  A file name is prompted
for, and either the file is created with the current article as its
contents, or else the current article is appended to this file.

@kbd{o} and @kbd{C-o} are a little more sophisticated.  They imitate the two
Rmail save functions @code{rmail-output-to-rmail-file} and @code{rmail-output},
using the current article.  Their output can intermix with the output
from the usual Rmail save functions, and they can be read later with
Rmail.
@findex rmail-output-to-rmail-file
@findex rmail-output

More generally, the user variable @code{gnews-save-style} controls the method
of saving to use.  If @code{nil} or @code{t}, simple appending will be used.
@code{nil} means that the default name to offer is obtained from invoking
@code{gnews-save-name} to create a new name based on the current newsgroup and
article number.  @code{t} means that the default name to offer is the same as
the last file name.  And if @code{gnews-save-style} is a command, then this
command will be invoked instead.  Unfortunately, this requires carefully
rewriting your favorite file saver.  Examples of this are the above two
@code{gnews-output-*} functions.
@vindex gnews-save-style
@tindex gnews-save-name

@table @kbd
@item |
@kindex |
@kbd{group-pipe}
@findex group-pipe
@end table

This prompts for a shell command to pipe the current article through.  With
a prefix argument, only the body of the article is piped.  The output
appears in the @t{*Shell Command Output*} buffer.

Saving/piping has two bugs.  Except for @kbd{o}, only the displayed headers
are saved.  Nor can these commands take a range of articles numbers.

Do not use the usual Emacs save and piping commands, since the article
display is buffered.  If you wish to use the same keys, rebind them.

@node group misc, , save, group
@section Miscellaneous group mode

The following commands are all described in detail elsewhere.

@table @kbd
@item r
@kbd{group-reply}
@item R
@kbd{group-reply-yank}
@item f
@kbd{group-follow}
@item F
@kbd{group-follow-yank}
@end table

Send a reply to the current article.  @xref{original, , Original Replies}.

@table @kbd
@item S
@kbd{group-supersede}
@item C
@kbd{group-cancel}
@end table

Supersede/cancel the current article.  @xref{replace, , Replacing Replies}.

@table @kbd
@item h
@kbd{describe-mode}
@item H
@kbd{gnews-describe-mode}
@item C-w
@kbd{gnews-bug-report}
@end table

The Gnews help commands.  @xref{help, , Help}.

@table @kbd
@item =
@kbd{group-index}
@end table

Index the current newsgroup.  @xref{index, , Indexing}.

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @kbd
@item M-x article-digest
@findex article-digest
@item M-x article-digest-if
@findex article-digest-if
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

Read the current newsgroup/article in Digest mode.  @xref{digest, , Digests}.

@table @kbd
@item !
@kindex !
@kbd{shell}
@findex shell
@end table

This runs @kbd{M-x shell}.

@page
@node reply, index, group, Top
@chapter Replying to articles

@dfn{Replying} is the generic term for composing and sending your thoughts
to someone else on Usenet, either by @dfn{posting} to Usenet, or by
@dfn{mailing} to another person or persons.
@cindex reply

Replying uses the @t{*gnews*reply*} buffer.  E-mail replies use E-reply
mode, and Net-wide (or on some smaller subnet) replies use N-reply mode.
@pindex *gnews*reply*

The following user variables, from the top of @file{reply.el}, might need
to be adjusted before posting will work out of Gnews.

@table @code
@item n-reply-program
@vindex n-reply-program
The external program to post with.  It should post correctly formatted
articles read in from the standard input file.  The default is the
value of @code{news-inews-program}, which normally should be the full path
for @file{inews}.  If @code{n-reply-program} is @code{nil}, then posting will proceed
via NNTP internals.
@pindex inews
@item n-reply-program-args
@vindex n-reply-program-args
The list of strings to supply as arguments to the default posting program.
The default is @samp{("-h")}.
@item n-reply-allowed
@vindex n-reply-allowed
This variable is set based on the NNTP internals.  Spool users will have
to set this variable to non-@code{nil}, either in the source in their @file{.emacs}.
@pindex .emacs
@item reply-path
@vindex reply-path
If @code{nil}, the @kbd{Path:} header will be set by the posting software.
If non-@code{nil}, the @kbd{Path:} header will be set to the value of @code{reply-path},
which should be a string.
@end table

No separate @file{Pnews} program or @code{postnews} function is yet provided.
But Reply modes can be used in any buffer.  If you post via an external
program like @file{inews} (the default), you can also post from any buffer.
If you post via NNTP internals, you must have Gnews running anyway.
@cindex bugs
@pindex Pnews
@pindex NNTP

@menu
Starting replies:

* original::			Creating new replies
* replace::.			Replacing old replies
* hooks:reply start hooks.	Reply start up hooks

Editing replies:

* format::			Formatting replies
* indent::			Indenting replies
* art headers::			Article headers
* mail headers::		E-mail headers
* misc:reply misc.		Reply mode miscellany

Sending replies:

* send::			Send commands
* signatures::			Signatures
@end menu

@node original, replace, , reply
@section Creating new replies

@table @kbd
@item r
@kindex r
@kbd{group-reply}
@findex group-reply
@item R
@kindex R
@kbd{group-reply-yank}
@findex group-reply-yank
@item f
@kindex f
@kbd{group-follow}
@findex group-follow
@item F
@kindex F
@kbd{group-follow-yank}
@findex group-follow-yank
@end table

These four commands are the ways Gnews begins a new reply.  The @kbd{r} and
@kbd{R} (@code{group-reply-*}) commands start a mail reply, while the @kbd{f} and @kbd{F}
(@code{group-follow-*}) commands start a posting.  The two yank commands begin a
reply with the contents of the replied-to article inserted and indented.
The two non-yank commands begin a blank reply, with only the headers
initialized.@refill

Yanked-in articles are indented with the value of @code{reply-prefix}.  This
can be any string; the default value is @t{">"}.
@vindex reply-prefix

The names @code{reply} and @code{follow} are chosen for their mnemonic
association with @kbd{r} and @kbd{f}, not for any inherent merit.  A
@dfn{followup} is an article made in response to another article.@refill

Replying is possible from the @kbd{$}-end of a newsgroup.  @kbd{F}
(@code{group-follow-yank}) prompts for a file name to insert into the reply
buffer.  Hitting return means to not include any file---which is just the
same as using @kbd{f} (@code{group-follow}) in the first place.

When starting up a new reply, Gnews checks if the @file{*gnews*reply*}
buffer has an unsent reply in progress.  (This is determined by the
@code{reply-was-sent} minor mode @t{":sent"}.  @xref{send, , Sending Replies}.)  If there is,
Gnews queries before overwriting the buffer's contents.  This behavior
can be changed with the @code{reply-query-clear} variable.  If @code{t}, all
new replies will query before overwriting this buffer.  If @code{nil}, no
queries will ever be made.  The described default corresponds to a
numeric value for @code{reply-query-clear}.
@vindex reply-query-clear
@vindex reply-was-sent
@pindex *gnews*reply*

@table @kbd
@item 1 r
@kindex r
@itemx 1 R
@kindex R
@kbd{group-forward-article}
@findex group-forward-article
@end table

If mailing is invoked with an argument---any argument---then Gnews will set
up a copy of the current article in the reply buffer for forwarding it by
e-mail to a third party.  The forwarded article will be indented with
@code{reply-forward-prefix}, with @t{">"} default value.

This function is not directly bound, since the obvious @kbd{C-f} etc. are
all motion keys.

@table @kbd
@item 1 f
@kindex f
@kbd{group-follow}
@findex group-follow
@item 1 F
@kindex F
@kbd{group-follow-yank}
@findex group-follow-yank
@end table

If posting is invoked with an argument---any argument---then Gnews will set
up a followup with extra mailing headers.  Gnews posts by looking for a
@t{Path:} or @t{Newsgroups:} or @t{From:} header, and starts from there.  If this is
less than the entire buffer, then when done posting, Gnews will treat the
entire buffer as e-mail.

@node replace, reply start hooks, original, reply
@section Replacing old replies

@table @kbd
@item C
@kindex C
@kbd{group-cancel}
@findex group-cancel
@item S
@kindex S
@kbd{group-supersede}
@findex group-supersede
@end table

If you make an egregious mistake when you post an article, you can try
and fix it.  If your article is not worth keeping in any form, then
@dfn{cancel} it.  If your article needs fixing up, then @dfn{supersede} it.
In either case, you set to your article in question, and then hit @kbd{C}
or @kbd{S}.@refill

Both commands use the @t{*gnews*cancel*} buffer.  @kbd{C} (@code{group-cancel}) requires
no direct intervention, and so it proceeds---after getting user confirmation@c
---without ever visibly switching to the cancel buffer.
@pindex *gnews*cancel*

@kbd{S} (@code{group-supersede}) asks for a file name.  If no name is given, the
cancel buffer will start with the article in question, otherwise it will
start the article with the named file.

@code{article-cancel-hook} and @code{article-supersede-hook} can be used to
modify the set up of these respective commands.@refill

Only you (or your superuser) can cancel your articles.  Gnews refuses to
cancel or supersede an article that you are not allowed to.  This is just
a user convenience; the actual security is implemented at a level well
below Gnews itself.

Canceling e-mail, by the way, is generally impossible.

@node reply start hooks, format, replace, reply
@section Reply start up hooks

@table @code
@item group-reply-start-hook
@itemx group-reply-hook
@vindex group-reply-start-hook
@vindex group-reply-hook
These two hooks are run upon starting a mail reply.  The first hook is
where internal mail/reply set up functions can be redefined.  The second
hook is run after the default set up has been inserted into the buffer.

(At the moment, @code{group-reply-start-hook} is unnecessary.  I used to
autoload the reply functions, and one had to be careful about the order
certain function redefinitions were done.  But because I don't know any
simple mechanism to get @code{gnews-fset} to work properly after an autoload,
I just load all of Gnews, making this timing finickiness obsolete.)

@item group-follow-start-hook
@itemx group-follow-hook
@vindex group-follow-start-hook
@vindex group-follow-hook
These two hooks are for posting as the previous two are for mailing.

@item article-cancel-hook
@itemx article-supersede-hook
@vindex article-cancel-hook
@vindex article-supersede-hook
These two hooks modify the default cancel/supersede message.  They are run
after the default header is set up.
@end table


@node format, indent, reply start hooks, reply
@section Formatting replies

@table @kbd
@item C-c C-o
@kindex C-c C-o
@kbd{reply-split-line}
@findex reply-split-line
@end table

@kbd{C-c C-o} splits a line vertically at point.  It is smart about prefix
indentation, and opens up three blank lines, leaving point at the beginning
of the middle line.

So if you are looking at a line like:

@example
>take to screw in a light bulb?_ And how many Apple lawyers does it
@end example

@noindent
with the cursor at the @t{_}, then @kbd{C-c C-o} will change it to:
@cindex apple*

@example
>take to screw in a light bulb?

_

> And how many Apple lawyers does it
@end example

@noindent
with the cursor in the middle all set up for your snappy response.

With a prefix argument, @kbd{C-c C-o} kills backwards from point to the end
of the reply prefix indentation.  That is, the above split will be done,
but the first part will be discarded.  Point is not moved.

@table @kbd
@item C-c C-q
@kindex C-c C-q
@kbd{reply-yank-fill}
@findex reply-yank-fill
@end table

This refills one paragraph of indented text, preserving the prefixes.  The
command prompts for the @code{fill-prefix} to use---the default offered is
usually correct.  It cannot be used to create a @code{fill-prefix} that isn't
there.

@table @kbd
@item C-c C-r
@kindex C-c C-r
@kbd{reply-rot13}
@findex reply-rot13
@end table

This rot13s the current region.  It is usually only used when posting
possibly offensive jokes or similarly questionable material.
@cindex rot13

@table @kbd
@item C-c C-k
@kindex C-c C-k
@kbd{reply-digest-kill}
@findex reply-digest-kill
@end table

This kills from point to the end of the current digest article.  Prefix
arguments mean kill off that many digest articles.  A negative prefix
argument kills in the reverse direction.

This is not needed in regular digests, since Digest mode is smart about
replying to the current article within a digest.  But if you reply to
a stray digest that comes by unexpectedly without first switching to
Digest mode, this command is of use.  @xref{digest mixed, , Digest Mixed}.
@cindex digest

@node indent, art headers, format, reply
@section Indenting replies

@table @kbd
@item C-c C-i
@kindex C-c C-i
@kbd{reply-indent}
@findex reply-indent
@end table

@kbd{C-c C-i} will indent the current region with your reply prefix.  With
a single prefix argument, an identifying blurb like:
@example
In article <110@@coronet.air>, tmm@@holly.wood.com (The Music Man) writes:
@end example
@noindent
will be prepended to the quotation.  The identification is taken from the
current article.  Note that this is not necessarily the same as the article
you are replying to, since you are free to switch back and forth between
the @t{*gnews*reply*} buffer and the @t{*gnews*} buffer, and even change
newsgroups or quit out of the newsreader.  (The last action may, however,
erase the @t{*gnews*reply*} buffer.)
@pindex *gnews*
@pindex *gnews*reply*

With two prefix arguments, an expanded header appears:
@example
From: tmm@@holly.wood.com (The Music Man)
Subject: The Big Parade
Message-ID: <110@@coronet.air>
@end example

This behavior can be customized with the variable @code{reply-blurb}.  It is a
list of blurb functions to apply.  Each @kbd{C-u} prefixed to the indenting
command means to go one further down the list to find the desired blurb.
The default is @samp{(reply-short-blurb reply-long-blurb)}.

@table @kbd
@item C-c C-y
@kindex C-c C-y
@kbd{reply-yank}
@findex reply-yank
@end table

@kbd{C-c C-y} yanks in the body of the current article.  The entire article
is inserted and indented.  An identifying blurb is put on the top.

@table @kbd
@item C-c %
@kindex C-c %
@kbd{reply->-count}
@findex reply->-count
@item C-c >
@kindex C-c >
@kbd{reply->-replace}
@findex reply->-replace
@end table

Most sites have what is called the ``50% rule''.  Articles must have more
than 50% unindented lines.  Since indentation in this situation is defined
crudely---on purpose---as just a line beginning with a @kbd{>}, it is very
easy to get around.
@cindex 50% rule

The first command merely gives you a percentage count, so that you can see
how you are doing.  The second command allows you to change the prefix.
Mark a suitable region, type @kbd{C-c >}, and respond to the prompt with
the new prefix.  In case of nested prefixes, you can get all nested
prefixes to change by using a prefix argument.

The commonly seen practice of adding ``filler'' lines should be avoided.

@node art headers, mail headers, indent, reply
@section Article headers

When you begin a new article, you see something like the example below.
When you follow-up to an existing article, you will see something like the
example below, with more fields already filled in, and perhaps the
replied-to article quoted.  When you use e-mail to reply, you will see
headers appropriate for just mail.  When you use a prefix argument with
follow-up, headers for both posting and mailing will be set up.
@cindex header

@example
Newsgroups: comp.emacs
From: weemba@@garnet.berkeley.edu (Matthew P Wiener)
Subject:_
Summary:_
Expires:_
References:_
Sender:_
Reply-To: weemba@@garnet.berkeley.edu (Matthew P Wiener)
Followup-To:_
Distribution:_
Organization: Brahms Gang Posting Central
Keywords:_

The body of the article will go here.  There is a completely blank
line--not even any spaces or tabs--separating the header from the
body.  Do not change this.
@end example

(Note: the underscores in the above example stand for spaces.)

You are pretty much free to edit the header fields as you wish.  The only
rules are that each header must be terminated with a colon, followed by a
space, followed by the actual field.  You are completely free to introduce
your own non-standard headers, although this should be done sparingly.
Edit the @t{Newsgroups:} field down to the appropriate newsgroups if
necessary---this can happen whenever you follow-up a crossposted article.
Change the @t{Subject:} field if necessary.  The only absolutely required
headers are usually @t{From:}, @t{Newsgroups:}, and @t{Subject:}.  Gnews
will delete any blank headers before posting.  The underlying posting
software will add any missing headers like @t{Path:} and @t{Message-ID:}.

If the default path comes out wrong, you can set it with @code{reply-path}.
@vindex reply-path

Some header editing can be done automatically, using the various reply
hooks.  @xref{reply start hooks, , Reply Start Hooks}.

The following commands are for editing article headers.  To edit mail
headers, @xref{mail headers, , Mail Headers}.

@iftex
@newdimen@tableindent @tableindent=1.1in
@end iftex
@table @kbd
@item C-c C-f C-d
@kindex C-c C-f C-d
@kbd{n-reply-distribution}
@findex n-reply-distribution
@item C-c C-f C-f
@kindex C-c C-f C-f
@kbd{n-reply-followup-to}
@findex n-reply-followup-to
@item C-c C-f C-k
@kindex C-c C-f C-k
@kbd{n-reply-keywords}
@findex n-reply-keywords
@item C-c C-f C-m
@kindex C-c C-f C-m
@kbd{n-reply-summary}
@findex n-reply-summary
@item C-c C-f C-n
@kindex C-c C-f C-n
@kbd{n-reply-newsgroups}
@findex n-reply-newsgroups
@item C-c C-f C-s
@kindex C-c C-f C-s
@kbd{n-reply-subject}
@findex n-reply-subject
@end table

These commands in N-Reply mode move point to the named header.  If the
header is missing, they will create it.

@table @kbd
@item C-c C-f C-r
@kindex C-c C-f C-r
@kbd{n-reply-references}
@findex n-reply-references
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

@kbd{C-c C-f C-r} goes to the @t{References:} field, and deletes the oldest
reference.  With a prefix argument, it deletes that many of the oldest
references.
@cindex References

@table @kbd
@item C-c .
@kindex C-c .
@kbd{reply-field-return}
@findex reply-field-return
@end table

This command returns point to where it last was before running one of the
above mentioned header commands.  This command will also work with the mail
header handlers, @pxref{mail headers, , Mail Headers}.

@table @kbd
@item C-c C-n
@kindex C-c C-n
@kbd{reply-newsgroup}
@findex reply-newsgroup
@end table

This prompts for a newsgroup name, using name completion and abbreviation
expansion (@pxref{news abbrev, abbrev, Abbrev}), and then inserts it at point.  With no
argument, it restricts completion to the list of newsgroups on the current
article's @kbd{Newsgroups:} field.  With one @kbd{C-u} prefix argument, it
restricts completion to your @file{.gnewsrc}.  And with two @kbd{C-u} prefix
arguments, it restricts completion to your site's active file.
@cindex abbreviations
@cindex newsgroup

@node mail headers, reply misc, art headers, reply
@section E-mail headers

@iftex
@newdimen@tableindent @tableindent=1.1in
@end iftex
@table @kbd
@item C-c C-f C-t
@kindex C-c C-f C-t
@kbd{n-reply-mail-to}
@findex n-reply-mail-to
@item C-c C-f C-c
@kindex C-c C-f C-c
@kbd{n-reply-mail-cc}
@findex n-reply-mail-cc
@item C-c C-f C-b
@kindex C-c C-f C-b
@kbd{n-reply-mail-bcc}
@findex n-reply-mail-bcc
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

These three commands are used in E-Reply mode to edit the indicated mail
headers.  If the header is missing, they will create it.

@table @kbd
@item C-c C-t
@kindex C-c C-t
@kbd{reply-to-simplify}
@findex reply-to-simplify
@item C-c C-p
@kindex C-c C-p
@kbd{reply-path-alias}
@findex reply-path-alias
@end table

These two commands do some primitive path aliasing.  Since mail paths are
site dependent, these rely on external databases for information.  There is
an extreme bias to the way @kbd{ucbvax} mails to the outside world built in
to the rewrite rules; you're on your own here.

@kbd{C-c C-t} (@code{reply-to-simplify}) will try to simplify a @kbd{To:},
@kbd{Cc:} or @kbd{Bcc:} header field.  It will work on the current line if
point is on such a header field, otherwise it goes to the first such line
in the current buffer.

These fields are assumed to contain what is called a @dfn{bang path}: an
exclamation point (``bang'' in Unix slang) separated list of site names.
Note that not all bang paths are genuine mail paths: some sites pass news,
which uses the same syntax, but not e-mail.

This commands assumes that you have a certain simple database of path
information in a file, named by the variable @code{path-data-file}.  The file
consists of three @code{setq}'s, one for @code{path-uucp}, one for @code{path-arpa},
and one for @code{path-hops}.

@code{path-uucp} is a list of names of your UUCP neighbors, each of which is a
symbol.  (Not a string!)  @code{path-arpa} is an alist of domain conversion
rules.  Each member of the alist is a dotted pair of the form
@example
(@var{site}."domain.ized.name")
@end example
@noindent
@var{site} is a symbol, and @t{"domain.ized.name"} is a string giving the
domainized form of @var{site}'s e-mail address.  @code{path-hops} is a similar
alist, giving paths to named sites.  Each member of the alist is a dotted
pair of the form
@example
(@var{site}."uucp!bang!path!to")
@end example
@noindent
@var{site} is as before, and @t{"uucp!bang!path!to"} is a string giving a
UUCP path in @t{!}-form leading up to (but not including) @var{site}.

By way of example, here is a miniature version of the file that I use:

@example
(setq path-uucp '(tektronix amdcad ulysses ucdavis ucsbcsl))

(setq path-arpa '((ames . "arc.nasa.gov")
                  (uunet . "uunet.uu.net")
                  (sunybcs . "sunybcs.bitnet")))

(setq path-hops '((proxftl . "uunet!gould!novavax")
                  (flatline . "uunet!nuchat")
                  (reed . "tektronix")))
@end example

Given this database, @kbd{C-c C-t} (@code{reply-to-simplify}) scans a bang path
from right to left, until it finds a site name that it knows about.  It
then either truncates the path so that it begins at your UUCP neighbor,
or else it converts to a domainized form, or else it replaces replaces
the currently seen path with the databased path.  In the last case, the
command continues to scan to see if domainization can be done.  (But it
does not attempt to re-apply any @code{path-hops} simplifications.)

I find the efforts to make and maintain the database (let alone write the
Lisp code to interpret it!) have more than repayed themselves in saved
e-mail grief and manual path editing.  (I also have some commands for
adding new entries too, but they are not generally usable.  Rather than
hacking away at them further to make some generic Gnews feature involving
a @file{.gnewsrc.path} file, I'll let you adapt mine.
@xref{examples reply, , Reply Examples}.)

@kbd{C-c C-p} (@code{reply-path-alias}) assumes that your site has implemented
@cite{RFC 915}.  This gives telnet access to a database of paths, based on
the UUCP maps.  You probably don't have it (and UC Berkeley's, for example,
is pre-@t{uunet} and was recently dropped).  But if you do, you use it as
follows.  Move point to some site name in a bang path.  Type @kbd{C-c C-p}.  Wait
a few seconds.  If the name is not known, an error will be signalled.  If
the name is known, the returned path will be inserted before the site name.
The former path is pushed back, but not erased.  You should normally follow
this command with @kbd{C-c C-t}.
@pindex telnet

@iftex
@newdimen@tableindent @tableindent=1.1in
@end iftex
@table @kbd
@item C-c C-m C-t
@kindex C-c C-m C-t
@kbd{n-reply-mail-to}
@findex n-reply-mail-to
@item C-c C-m C-c
@kindex C-c C-m C-c
@kbd{n-reply-mail-cc}
@findex n-reply-mail-cc
@item C-c C-m C-b
@kindex C-c C-m C-b
@kbd{n-reply-mail-bcc}
@findex n-reply-mail-bcc
@item C-c C-m C-s
@kindex C-c C-m C-s
@kbd{n-reply-mail-subject}
@findex n-reply-mail-subject
@item C-c C-m C-w
@kindex C-c C-m C-w
@kbd{n-reply-mail-signature}
@findex n-reply-mail-signature
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

These commands in E-Reply mode for editing mail headers sitting above an
article meant for posting, when simultaneously posting/mailing.
@xref{original, , Original Replies}.

The first four move to the indicated header, creating it if necessary.  The
last is used to append a signature in the space above the article headers.

The first three are the same commands as used in E-Reply mode, but the
@kbd{C-c C-f} prefix in N-Reply mode is for adding article headers.
@xref{art headers, , Article Headers}.

@table @kbd
@item C-c .
@kindex C-c .
@kbd{reply-field-return}
@findex reply-field-return
@end table

This command returns point to where it last was before running one of the
above mentioned header commands.  (This is the same command as was listed
in the previous section.  @xref{art headers, , Article Headers}.)

@node reply misc, send, mail headers, reply
@section Reply mode miscellany

@table @kbd
@item C-c ?
@kbd{describe-mode}
@item C-c C-h
@kbd{gnews-describe-mode}
@end table

These are the usual and extended help commands, @pxref{help, , Help}.

@table @kbd
@item C-c -
@kindex C-c -
@kbd{n-reply-toggle} and @kbd{e-reply-toggle}
@findex n-reply-toggle
@end table

@kbd{C-c -} toggles between N-Reply mode and E-Reply mode, changing the
headers appropriately.  At the moment, it does not change the blurb.

@table @kbd
@item C-c <
@kindex C-c <
@kbd{n-reply-beginning}
@findex n-reply-beginning
@end table

This goes to the beginning of the body of the article.

@table @kbd
@item C-c C-v
@kindex C-c C-v
@kbd{reply-signature-insert}
@findex reply-signature-insert
@item C-c C-w
@kindex C-c C-w
@kbd{reply-signature}
@findex reply-signature
@end table

@kbd{C-c C-v} inserts a signature at point, while @kbd{C-c C-w} appends a
signature at the end of the buffer.  The latter occurs by default when you
send off your reply, but sometimes your signature won't appear since the
Gnews doubled signature inhibition mechanism is a hack.  So when the
sending queries you, just hit @kbd{C-g}, then @kbd{C-c C-w}, and send it
again.  @xref{send, , Sending Replies}.
@cindex signature

@node send, signatures, reply misc, reply
@section Send commands

@table @kbd
@item C-c C-c
@kindex C-c C-c
@kbd{reply-return}
@findex reply-return
@item C-c C-s
@kindex C-c C-s
@kbd{reply-send}
@findex reply-send
@end table

These two commands send your article, which is by posting or mailing based
on the current mode.  First each invokes the signature appending mechanism,
which by default does nothing (@pxref{signatures, , Signatures}).  Then it runs a send
hook (see below).  Then it queries to confirm that you do wish to send your
reply.  Once you've sent off your reply, the @code{reply-was-sent} minor mode
(``@t{:sent}'') is turned on.
@cindex signature

@kbd{C-c C-c} returns to news reading after sending the current article.
@kbd{C-c C-s} simply sends the current article, and leaves you in the reply
buffer.

@kbd{C-c C-c} will not send the article if the @t{reply-was-sent} minor
mode has been set.  @kbd{C-c C-s} will.

@table @kbd
@item C-c C-]
@kindex C-c C-]
@kbd{reply-return-no-send}
@findex reply-return-no-send
@end table

This returns to news reading, leaving the reply buffer untouched.

If you return to news reading at a different article than the article you
were at when you were replied, you will be asked if you want to return to
the ``replied-to'' article.

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @code
@item e-reply-send-hook
@vindex e-reply-send-hook
@item n-reply-send-hook
@vindex n-reply-send-hook
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

The appropriate hook is run just before sending a reply.  A useful variable
to remember here is @code{reply-signature-marker}, which points to the
beginning of the signature, so that you can do last minute fudging after
the signature has been appended.
@tindex reply-signature-marker

@node signatures, , send, reply
@section Signatures

@display
So you want a fancy sign'ture
Well you know
You all want to change the hooks.
@end display
@cindex signature

If you use @file{inews} as your news poster, it will append a signature
automatically if you have a @file{.signature} file in your home directory.

So the default for Gnews is to not append a signature.  To get customized
Gnews signatures, you must first remove or rename your @file{.signature}
file.

The following four variables control signature appending:

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @code
@item e-reply-signature-prefix-pointers
@vindex e-reply-signature-prefix-pointers
@item n-reply-signature-prefix-pointers
@vindex n-reply-signature-prefix-pointers
@item reply-signature-default-major
@vindex reply-signature-default-major
@item reply-signature-default-minor
@vindex reply-signature-default-minor
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

The @code{*-prefix-pointers} variables are both length four lists, one for
E-Reply, one for N-Reply, in the following format:

@example
(@var{no-sig} @var{first-name} @var{full-name} @var{default})
@end example

@noindent
where these meta-variables are interpreted as follows:

@table @var
@item no-sig
prefix for appending no signature
@item first-name
prefix for appending your first name
@item full-name
prefix for appending your full name
@item default
prefix for appending @code{reply-signature-default-major}
@end table

``prefix'' here refers to the numeric prefix value used when you send off a
response with @kbd{C-c C-c} or @kbd{C-c C-s}.  @code{reply-signature-default-major},
as the name indicates, is intended to be your primary signature file; the
abstract generality of the signature mechanism makes the true semantics of
such an assertion dubious.

The numeric value of the universal argument prefix you typed in is compared
against the four members of the mode appropriate @code{*-prefix-pointers}.  If
it matches one of the four, then the indicated action is taken.  Thus, if
@var{no-sig} is 64, then @kbd{C-u C-u C-u C-c C-c} will send off your response without
signing.  If @var{no-sig} is 0, then @kbd{C-u 0 C-c C-c} will send your article off
without signing.

Setting one of these meta-variables to @code{nil} means that the corresponding
signature will not be done under any invocation.

So the first step in customizing your signature is to choose which of the
four above (if any) you would most prefer to show up when typing @kbd{C-c C-c}.
Then set that meta-variable to 1.  Do this with the other likely prefixes
that you will type: probably 1, 4, 16, etc.

There is one final default if the actual invoking prefix is not in the list.
This then passes the job onto @code{reply-signature-default-minor}, the hook
which permits arbitrarily fancy signatures.  If you only want to use this
fancy signature mechanism, then set all four of the meta-variables to @code{nil}.

@code{reply-signature-default-minor} is a dotted pair @code{(@var{type}.@var{hook})}.  @var{hook} is
either a string, or a function returning a string.  The string is
interpreted as the actual signature, if @var{type} is non-@code{nil}, or as a file
name, if @var{type} is @code{nil}.

Here are examples of this:

@example
(t . "--Charlie Brown")
(nil . ".my.signature.file")
@end example

The explicit string, or the named file in the directory @kbd{gnews-dot-dir},
will be appended to the article.  Remember, the named file should not be
@file{.signature}, since that would then be appended by @file{inews}.

@example
(t . 'return-a-yow-string-plus-my-name)
(nil . 'return-a-random-signature-file)
@end example

The former can be used to generate random Zippy signatures like:
@cindex yow!

@example
"When you get your PH.D. will you be able to work at BURGER KING?"
                         --Matthew P Wiener (ucbvax!garnet!weemba)
@end example

The latter can be used to append one of a library of signature files.

If you want two or more fancy signature styles, say randomly picking
one out of your own library as the default, and an occasional Zippyism
now and then, set the four signature meta-variables to @code{nil}, and
have a signature function that switches based on @code{current-prefix-arg}.
If it's @code{nil}, use the personal library chooser, and otherwise run
the Zippy generator.

My own values are listed below:

@table @code
@item e-reply-signature-prefix-pointers
@vindex e-reply-signature-prefix-pointers
@t{(0 1 4 16)}
@item n-reply-signature-prefix-pointers
@vindex n-reply-signature-prefix-pointers
@t{(0 nil nil 1)}
@item reply-signature-default-major
@t{(nil."~/s/1")}
@vindex reply-signature-default-major
@item reply-signature-default-minor
@t{(t.signature:hook)}
@vindex reply-signature-default-minor
@findex signature:hook*
@end table

So in both cases, an explicit 0 blocks signing, and otherwise the appended
signature gets more complicated with each @kbd{C-u}.  In e-mail, I will
sometimes sign with just my first name or my full name, but in posting
I always include a complete signature file.  @xref{examples reply, Reply
Examples}.

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @code
@item reply-valediction
@vindex reply-valediction
@item reply-signature-separator
@vindex reply-signature-separator
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

If you append just your name---that is, if you use the second or third of
the four meta-variables---then the string @code{reply-valediction} will be
put just before your name.  The default is @t{"-"}.  A likely choice could
be something like @t{"Yours truly,\n@ @ @ @ "}.

If you append a more complicated signature, meaning you invoke either the
fourth or no meta-variable, then the string @code{reply-signature-separator},
followed by a newline, is prepended to your signature.  The default value
is @t{"-- "}.  Note that extra space---it's supposed to be there for a reason
that I don't know.

Having mastered the fine art of adding signatures, you will probably also
need to learn how to @emph{not} add signatures too.  This need occurs since
quite often you will have your signature appended already, and appending
it a second time is the embarrassing hallmark of the Usenet neophyte.

This is done with the @code{reply-signature-inhibitions}.  The default is
a list of the following three functions.
@vindex reply-signature-inhibitions
@cindex inhibitions

@table @code
@item reply-inhibit-name
@vindex reply-inhibit-name
Check for the user name.
@item reply-inhibit-login
@vindex reply-inhibit-login
Check for the user's login name.
@item reply-inhibit-ps
@vindex reply-inhibit-ps
Check for a PS.
@end table

The @code{reply-signature-inhibitions} list is marched down, each of the
functions scanning the end of the article for signs that a signature
is already there, returning @code{t} if it finds the indicated items.  To
append a signature when the automatic suppression is incorrect, use
@kbd{C-c C-w}.
@kindex C-c C-w

You can change these to better suit your signature.  Tinkering with the
the maximum distance back to search might suffice.  For names this is
specified by @code{reply-max-back-name} (default 60) and for postscripts
by @code{reply-max-back-ps} (default 500).  A postscript is defined as
anything that matches @code{reply-ps-match} at the beginning of a line.
@vindex reply-max-back-name
@vindex reply-max-back-ps
@vindex reply-ps-match

@page
@node index, hook-kill, reply, Top
@chapter Indexing a newsgroup

Indexing is a separate mode where the articles available within the
current newsgroup are @dfn{indexed} in a separate window.
@cindex index

@table @kbd
@item =
@kindex =
@kbd{news-index}
@findex news-index
@item =
@kindex =
@kbd{group-index}
@findex group-index
@end table

In News mode, @kbd{=} creates an index for the current newsgroup.  In Group
mode it creates an index if it is not already present, otherwise it just
moves you to the index buffer.

Indexing can be conditionally activited during News mode group entry with
the proper hook-kills.  @xref{index conditional, , Conditional Indexing}.

The index buffer is either popped to or switched to, based on whether
@code{index-pop-up} is non-@code{nil} or @code{nil}.  If @code{index-pop-up} is numeric,
then its value is the size of the index window.
@vindex index-pop-up

A typical index display looks something like the following:

@example
17121m Re: Banana Split?                         bloom@@bloom (Milo Bloom
17122i Bananas up my nose (was Spam on my Head)  opus@@bloom (Opus)
17123i Re: Bananas up my nose (was Spam on my H  bloom@@bloom (Milo Bloom
17124j Re: Banana Split?                         steved@@bloom (Steve Dal
17125s Banana State University Archives          bob@@allosaur (Bob Sutte
17126k Has anyone seen my cat?  He's fat and la  jon@@garfield (Jon)
17127  Re: comp.ternaries.banana.pc.jr.d         jones@@bloom (Oliver Wen
17128  The Banana Secret Diaries, Part 4 of 3    banana@@bloom (Banana PC
--- Gnews: comp.sys.banana =/17128       (Index)----Bottom--------------
@end example
@cindex banana*

This means that article 17121 has been permanently marked, articles 17122
and 17123 have been ignored, article 17124 has been junked, article 17125
has been saved, and article 17126 was killed automatically.  The other
two articles have not had their status set.  For a detailed explanation
of these individual @dfn{flags}, @xref{index flag, , Index Flags}.
@cindex flags

[Note: index saving is not yet written.  I expect it will be for 2.1.]

The fictional nature of the above example hides one feature about the
display.  Machine domains are, by default, not shown.  That is, the above
posters are presumably @t{jones@@bloom.county.gov} and so on.

@menu
* motion:index motion.		Index motion
* flag:index flag.		Index flags
* misc:index misc.		Miscellaneous index commands
* customize:index custom.	Index customization
* cond:index conditional.	Conditionalized Indexing
@end menu

@node index motion, index flag, , index
@section Index motion

@table @kbd
@item f
@kindex f
@kbd{index-buffer-switch}
@findex index-buffer-switch
@item o
@kindex o
@kbd{index-other-window}
@findex index-other-window
@item =
@kindex =
@kbd{index-article-get}
@findex index-article-get
@end table

These three commands sets to the article whose number point is currently
on.  @kbd{f} (@code{index-buffer-switch}) switches to the article, and @kbd{o}
(@code{index-other-window}) pops to the article.  (The bindings are like
similar bindings in @code{dired}.)  @kbd{=} (@code{index-article-get}) does the one
or the other, whichever is appropriate for the current value of
@code{index-pop-up}.
@vindex index-pop-up

Normally you need not use @kbd{f} or @kbd{o}, but as the windows may no longer
be consistent with that variable, you may have to use one of the explicit
commands, instead of relying on @kbd{=} only.

@table @kbd
@item n
@kindex n
@kbd{index-forward}
@findex index-forward
@item p
@kindex p
@kbd{index-backward}
@findex index-backward
@item N
@kindex N
@kbd{index-forward-all}
@findex index-forward-all
@item P
@kbd{index-backward-all}
@end table

@kbd{n} and @kbd{p} move forward and backward through the index buffer,
skipping over flagged articles.  @kbd{N} and @kbd{P} are similar, but
do not skip over flagged articles.
@cindex flags

@table @kbd
@item @key{SPC}
@kindex SPC
@kbd{index-scroll-up}
@findex index-scroll-up
@item @key{DEL}
@kindex DEL
@kbd{index-scroll-down}
@findex index-scroll-down
@end table

These two commands scroll the index buffer forward and backward.

@table @kbd
@item <
@kindex <
@kbd{index-beginning-of-buffer}
@findex index-beginning-of-buffer
@item >
@kindex >
@kbd{index-end-of-buffer}
@findex index-end-of-buffer
@end table

These two commands move to the beginning and end of the index buffer.

@table @kbd
@item /
@kindex /
@kbd{index-search-forward}
@findex index-search-forward
@item ?
@kindex ?
@kbd{index-search-backward}
@findex index-search-backward
@end table

@node index flag, index misc, index motion, index
@section Index flags

A @dfn{flag} is a letter indication in Index mode of something about an
article, right next to the article number.  Basic motion skips over
flagged articles.
@cindex flags

Ignoring is a generic flag, whose only effect is to have the basic index
motions skip over the article.  Junking occurs automatically when reading
articles, or it may be done directly from Index mode.  Killed articles are
usually from hook-kill processing.  By default these are not shown, but if
@code{index-show-all} is non-@code{nil} they will be.  Permanently marked articles
show up in every indexing of the newsgroup that you do, so you can refer
back to them at your later convenience.

You are free to create and use your own flags from the remaining lowercase
letters of the alphabet.  (But I might horn in on one or two at some future
date.)

@table @kbd
@item i
@kindex i
@kbd{index-ignore}
@findex index-ignore
@end table

@kbd{i} (@code{index-ignore}) flags the current article, and all that follow
immediately with the same subject as the current article.

@table @kbd
@item j
@kindex j
@kbd{index-junk}
@findex index-junk
@item J
@kindex J
@kbd{index-junk-local}
@findex index-junk-local
@item M-j
@kindex M-j
@kbd{index-junk-region}
@findex index-junk-region
@end table
@cindex junking

@kbd{j} (@code{index-junk}) and @kbd{J} (@code{index-junk-local}) junk the current
article, the former getting at crosspostings and the latter not.

@kbd{M-j} (@code{index-junk-region}) junks all the articles in the region.  It
gets crosspostings unless there's a prefix argument, in which case junking
is local to the current newsgroup.

@table @kbd
@item k
@kindex k
@kbd{index-kill}
@findex index-kill
@item K
@kindex K
@kbd{index-kill-permanent}
@findex index-kill-permanent
@end table

@kbd{k} (@code{index-kill}) kills the current article's subject.  @kbd{K}
(@code{index-kill-permanent}) kills the current article's subject, and adds
an entry into the current newsgroup's hook-kills.  @xref{junk, , Killing}.

Articles with newly killed topics as their subject are neither flagged
nor junked at first.  But when reached with an @kbd{n} (@code{index-forward})
or a @kbd{p} (@code{index-backward}), the article will be both flagged and
junked at that point, and motion will continue.

@table @kbd
@item m
@kindex m
@kbd{index-mark}
@findex index-mark
@item M-m
@kindex M-m
@kbd{index-mark-region}
@findex index-mark-region
@end table

@table @kbd
@item x
@kindex x
@kbd{index-junkers-erase}
@findex index-junkers-erase
@end table

@kbd{x} (@code{index-junkers-erase}) deletes all junked and killed
articles.  This can be modified by setting the @code{index-junkers}
variable to a consisting of those flags that should be removed.

@node index misc, index custom, index flag, index
@section Miscellaneous index commands

@table @kbd
@item S
@kindex S
@kbd{index-sort}
@findex index-sort
@end table

This sorts the index buffer.  You can get this automatically if
@code{index-sort-do} is non-@code{nil}.
@vindex index-sort-do

The default sort is primarily by subject, ignoring @t{Re:}'s, and
secondarily by article number.  For information on customizing this,
@pxref{index custom, , Customized Indexing}.

@table @kbd
@item c
@kindex c
@kbd{index-catchup}
@findex index-catchup
@item u
@kindex u
@kbd{index-unsubscribe}
@findex index-unsubscribe
@item q
@kindex q
@kbd{index-quit}
@findex index-quit
@end table

Catch up, unsubscribe, or quit the current newsgroup, as done from
the index buffer.

@table @kbd
@item U
@kindex U
@kbd{index-undo}
@findex index-undo
@end table

This runs @kbd{M-x undo}, and then recomputes the internal list of
marked/unmarked articles.  There may be a noticeable time delay for
very large indices.

@table @kbd
@item !
@kindex !
@kbd{shell}
@findex shell
@end table

Run @kbd{M-x shell}.

@table @kbd
@item h
@kbd{describe-mode}
@item H
@kbd{gnews-describe-mode}
@item C-w
@kbd{gnews-bug-report}
@end table

These are the usual Gnews help commands.  @xref{help, , Help}.

@table @kbd
@item a
@kindex a
@kbd{universal-argument}
@findex universal-argument
@item 0 1 @dots{} 9
@kbd{digit-argument}
@findex digit-argument
@end table

For convenience, @kbd{C-u} (@code{universal-argument}) is also bound
to @kbd{a}, along with @code{digit-argument} to the individual digits.

@node index custom, index conditional, index misc, index
@section Index customization

The defaults for all variables mentioned are shown in brackets.

The following variables define the format for articles in the index:

@table @asis
@item @code{index-headers}@ @ @ [@t{("Subject" "From")}]
@vindex index-headers
@code{index-headers} is the list, in order, of header fields to
display in the index buffer.  The other three variables give
expressions that refer, in the same order, to these fields.
@item @code{index-sizes}@ @ @ [@t{(40 29)}]
@vindex index-sizes
@code{index-sizes} gives the maximum length for each field in a
display.  Shorter fields will be left justified and padded on
the right with spaces.  A @code{nil} size means do not pad and
do not truncate.
@item @code{index-filter}@ @ @ [@t{(identity reply-domain)}]
@vindex index-filter
@code{index-filter} gives functions to process the field through
before printing it.  The default leaves the subject line alone,
but strips domains from the @t{From:} fields.
@item @code{index-format}@ @ @ [@t{"%s@ @ %s"}]
@vindex index-format
@code{index-format} gives the format to print the fields in.  This
can be used to get right justified left padding, using @t{%#s}
formats for some number @t{#}.
@end table

The following variables control miscellaneous details about
the initial index display:

@table @asis
@item @code{index-pop-up}@ @ @ [@code{nil}]
@vindex index-pop-up
If non-@code{nil}, pop to the index buffer.@*
If also numeric, resize the index window to that size.
@item @code{index-sort-do}@ @ @ [@code{nil}]
@vindex index-sort-do
If non-@code{nil}, sort the index buffer automatically.
@item @code{index-show-kills}@ @ @ [@code{t}]
@vindex index-show-kills
If non-@code{nil}, flag instead of delete per-hook killed articles.
@item @code{index-show-p}@ @ @ [@code{t}]
@vindex index-show-p
If non-@code{nil}, display the index as it is formed.  If @code{nil},
show instead a running count in the minibuffer.
@item @code{index-ding}@ @ @ [@code{t}]
@vindex index-ding
If @code{t}, ding the user when indexing is complete.@*
If numeric, ding the user when indexing is complete, but only if the
number of indexed articles is more than @code{index-ding}'s numeric value.
@end table

The following variables define and control a variant to flagging:

@table @asis
@item @code{index-junkers}@ @ @ [@kbd{"jk"}]
@vindex index-junkers
A string consisting of the flags that should perhaps be deleted
rather than flagged.
@item @code{index-junkers-erase-p}@ @ @ [@code{nil}]
@vindex index-junkers-erase-p
If non-@code{nil}, delete instead of flagging 
@end table
@noindent
The command @kbd{x} (@code{index-junkers-erase}) erases from the display
all lines with a flag in the @code{index-junkers} string.

The following internal functions control the sorting.  You can rewrite
these to get a different sort.  For one example of such a rewrite and
how to implement it, @pxref{examples index, , Index Examples}.

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @code
@item index-sort-prep
@tindex index-sort-prep
@item index-sort-function
@tindex index-sort-function
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

@code{index-sort-prep} takes one argument, a string containing the contents
of a line in the index buffer.  The function returns a dotted pair of
the form @code{(@var{display-line}.@var{primary-key})}.  @var{display-line}
refers to what is actually displayed after sorting---the only restriction
is that the first six characters are reserved for article number and the
junking symbols.

@var{primary-key} is used as such by the default @code{index-sort-function}.
These keys are separated out first to avoid any recomputation when sorting.
The default @code{index-sort-prep} returns a pair consisting of its argument,
and a @t{Re:}-less subject.

@code{index-sort-function} compares two dotted pairs of the above kind,
first by comparing the primary keys, then by comparing article numbers.
Explicitly, it returns @code{t} if either the first pair's @var{primary-key}
is @code{string<} the second pair's, or else if the two compare equal under
@code{string@t{=}}, but the article number of the first pair's @code{display-line}
is less than the second's.  In all other cases, it returns @code{nil}.

@node index conditional, , index custom, index
@section Conditional Indexing

The @code{index-if} function in pre-hooks allows you to trigger indexing
upon newsgroup entry based on the number of unread articles and/or
the newsgroup entry command.
@findex index

@table @kbd
@item (pre nil index-if)
@itemx (pre nil index-if 1)
These two pre-hooks are equivalent.  They both mean to index if
there are one or more unread articles and, since no commands are
specified, if the newsgroup is entered via @key{SPC} (@code{news-default}).
Other group entry commands (not counting @kbd{=} (@code{news-index})) will
not use indexing.  This includes @kbd{y} (@code{news-yes}), even if
@code{news-yes} is the current @code{news-default}.
@kindex SPC
@kindex y
@kindex =
@findex news-default
@findex news-index
@findex news-yes
@item (pre nil index-if 4)
This is similar to the previous example.  The only difference is
that indexing, to be triggered, requires four or more unread articles
in the newsgroup.
@item (pre nil index-if 16 '(news-goto news-visit news-yes))
Here indexing is only triggered when there are sixteen or more
unread articles, and now by the listed commands.  @code{news-default}
will not trigger any indexing in this case.
@findex news-goto
@findex news-visit
@end table

The role of @code{news-default} above can be replaced with any list of
commands by setting the user variable @code{index-hook-commands}.
@vindex index-hook-commands

@table @kbd
@item C-c C-i
@kindex C-c C-i
@kbd{hook-kill-insert-index}
@findex hook-kill-insert-index
@end table

This is used in Hook Kill mode to insert an @code{index-if} pre-hook.
A prefix argument specifies an article count.  @xref{hook-edit, , Hook Edit}.

Index pre-hook customization should be done before any pre-hook
invocation of @code{index-if}.

@page
@node hook-kill, digest, index, Top
@chapter Hook-Kill processing

Hook-Kill is a major generalization of the KILL mechanism from @t{rn}.  In
@t{rn}, each newsgroup has an associated KILL file.  These KILL files, in
turn, are a list of automatic commands to perform upon newsgroup entry
and filters to apply against individual articles.
@cindex hook-kill
@pindex rn

In Gnews, this mechanism is strengthened in three distinct ways.  First,
instead of one KILL file per newsgroup, Gnews uses a hook-kill list based
on newsgroup regexps, not newsgroup names.  The list of hook-kills to apply
to a given newsgroup name is the concatenation of all the lists for those
regexps that match the newsgroup name.  Second, hook-kills in Gnews can,
on a per-newsgroup basis, temporarily redefine any variable, key binding,
or function.  And third, in Gnews it is simple to edit the hook-kills,
and so users are more encouraged to take extensive advantage of the KILL
concept.
@cindex newsgroup

Note that the @t{rn} concept of a global KILL file is implementable via
hook-kills for the @t{"."} regexp, as it always matches.  (The null string
regexp will also work, but it is harder to read.)

@menu
* theory:hook-theory.		Hook-Kill explanations
* examples:hook-examples.	Examples of hook-kills
* edit:hook-edit.		Hook-Kill editing
@end menu

@node hook-theory, hook-examples, , hook-kill
@section Hook-Kill explanations

Your @file{.gnewsrc.hook} contains a @code{setq} for @code{hook-kill-all}.
@tindex hook-kill-all
@pindex .gnewsrc.hook

This variable is an alist of the form
@example
(@var{regexp-hook-kill-1} @var{regexp-hook-kill-2} @dots{})
@end example
@noindent
where each @var{regexp-hook-kill} is of the form
@example
("@var{regexp}" @var{hook-kill-1} @var{hook-kill-2} @var{hook-kill-3} @dots{}).
@end example

Each @var{regexp} is tested against the current newsgroup.  The hook-kills
of all those that match are concatenated into one list.

This list is then separated into three parts, the @dfn{pre-hooks}, the
@dfn{per-hooks}, and the @dfn{post-hooks}.  (These are all defined below.
Anything not one of these types is ignored.)  The order of the hooks
between different @var{regexp}s is not defined, and should not be
relied upon.  But within any given @var{regexp}, the pre- and per-hooks
will be processed in order, and the post-hooks will be processed in
reverse order.  The latter reversal is so that first-in setting and
last-out unsetting of a multiply reset item will occur.

@dfn{In order}, here, is the same as top-to-bottom within a Hook Kill Edit.
@xref{hook-edit, , Hook Edit}.

Internally, the three lists of hooks for the current newsgroup are in the
Lisp variables @code{hook-kill-pre}, @code{hook-kill-per} and @code{hook-kill-post}.
@tindex hook-kill-pre
@tindex hook-kill-per
@tindex hook-kill-post

Pre-hooks are of the form
@example
(pre nil @var{function} @var{argument-1} @var{argument-2} @dots{}).
@end example
@noindent
The pre-hooks are processed before article processing begins.  @var{function}
is run with the following @var{arguments}.

Per-hooks are of the form
@example
("@var{field}" "@var{regexp}" @var{function} @var{argument-1} @var{argument-2} @dots{}).
@end example
@noindent
The per-hooks are processed for each article.  If the contents of the
article's header @var{field} match the given @var{regexp}, or if @var{field}
is the empty string and @var{regexp} matches anywhere in the headers,
then @var{function} is run with the following @var{arguments}.  If
@var{function} is applied, it can, as a side effect, terminate further
hook-kill processing.@refill
@cindex header
@cindex field

This side effect is computed as follows.  If @var{function} has a non-@code{nil}
@code{hook-kill-junk} property, then Gnews will proceed immediately to
the next article.  (Note that it is up to @var{function} to do actual
article junking.)  Failing this, if @var{function} sets the variable
@code{hook-kill-continue} to @code{nil}, then hook-kill processing will
be terminated, and the current article will be set to.  Otherwise,
hook-kill processing will continue until the list is empty.  At which
point the article is set to.
@cindex junking
@tindex hook-kill-junk
@tindex hook-kill-continue

These side effects can be obtained with one of the following functions:
@code{article-junk}, @code{article-junk-local} and @code{article-ignore} all have
a @code{t} @code{hook-kill-junk} property, and @code{article-yes} sets the
@code{hook-kill-continue} variable to @kbd{nil}.
@findex article-yes
@findex article-ignore
@findex article-junk
@findex article-junk-local

Post-hooks are of the form
@example
(post nil @var{function} @var{argument-1} @var{argument-2} @dots{}).
@end example
@noindent
The post-hooks are processed---in reverse order---upon newsgroup exit.
@var{function} is run with the following @var{arguments}.  (Note: the
actual @code{hook-kill-post} variable is literally processed in list
order.  But its initial value is the reverse of the apparent list, and
newer values are always added to the front of the list.)

@node hook-examples, hook-edit, hook-theory, hook-kill
@section Examples of hook-kills

Most users' hooks are pre-hooks or per-hooks.  post-hooks are almost
always internally generated.

@table @kbd
@item M-x gnews-set @var{var-1} @var{var-2}
Set @var{var-1} to @var{var-2}.
@item M-x gnews-fset @var{func-1} @var{func-2}
Function set @var{func-1} to @var{func-2}.
@item M-x gnews-key @var{key} @var{command}
Bind @var{key} to @var{command}.
@findex gnews-set
@findex gnews-fset
@findex gnews-key
@end table

The above are actually commands, although their primary use is in pre-hooks.
They prompt for the arguments listed above, do the indicated evaluations,
and then they install a one-time post-hook for restoring the first item
back to its former status, which may be another value or simply undefined.

In programming code, these three take an optional third argument, the quoted
name of a variable to compile the restoring hooks into.  This is used
internally by the conditional digest code.

What follows is an annotated guide to some of my own hook-kills, real or
imaginary.  A few of them refer to functions not part of Gnews; I merely
wish to indicate the possibilities.  The code for these functions can
be found elsewhere, @pxref{examples, , Examples}.

@table @t
@item rec.arts.comics

@example
(pre nil gnews-set 'gnews-name "Obnoxio the Clown")
@end example
@vindex gnews-name

This is my comics-land @i{nom de plume}.  As in ``Obnoxio the
Clown vs the X-Men #1''.  A true comic book classic.

@item rec.humor.funny

@example
(pre nil gnews-set 'group-show-headers '(Keywords))
("Keywords" "rot13" setq gnews-rot13-p t)
@vindex group-show-headers
@vindex gnews-rot13-p
@cindex header
@end example

I normally suppress the showing of the @t{Keywords:} header,
but as it has meaning in this newsgroup, I show it.  Rot13-ed
articles are decrypted on entry.

@item comp.emacs
@example
(pre nil gnews-set 'n-reply-hook 'n-reply-emacs:hook)
(pre nil gnews-set 'e-reply-hook 'e-reply-emacs:hook)
(pre nil gnews-set 'group-last-save "~/n/emacs/")
(pre nil gnews-key "\e\C-x" 'eval-defun)
@vindex n-reply-hook
@vindex e-reply-hook
@findex n-reply-emacs:hook*
@findex e-reply-emacs:hook*
@vindex group-last-save
@findex eval-defun*
@kindex C-M-x*
@end example

I graft on the Emacs Lisp mode indentation and syntax in
the modified reply hooks, set the save directory for this
newsgroup, and rebind @kbd{C-M-x} to what it ought to be in
an Emacs newsgroup.

@item \(talk.bizarre\|soc.singles\|misc.headlines\)

@example
(pre nil gnews-fset 'index-sort-prep 'index-name-sort-prep)
(pre nil gnews-fset 'index-ignore 'index-name-ignore)
(pre nil index-if 16)
@tindex index-sort-prep
@findex index-name-sort-prep*
@findex index-ignore
@findex index-name-ignore*
@findex index-if
@end example

I sort these newsgroups by user, not topics.  It makes it easy
to read 100 new articles in less than 5 minutes, and I don't
feel like I've missed a thing.  Lite, and not too filling.

If there aren't that many articles, I don't bother to index.
Maybe I'll find something new this way.  It happens.

The use of the regexp to match several newsgroups here makes it
easy for me to experiment in several newsgroups at once with
different styles of newsreading.

@item comp.sources.\(unix\|games\)

@example
(pre nil gnews-set 'index-headers "Subject")
(pre nil gnews-set 'index-format "%s")
(pre nil gnews-set 'index-filter '(identity))
(pre nil gnews-set 'index-sizes '(nil))
(pre nil index-if)
@vindex index-headers
@vindex index-sizes
@vindex index-filter
@vindex index-format
@end example

Since these newsgroups always have the @t{From:} field
set to the moderator, there is no point in listing them.
@xref{index, , Indexing}.

By default I always index these newsgroups (and the same
for @t{comp.sources.misc}, which has more normal headers).
Note that the @code{index-if} pre-hook comes after the other
pre-hooks, as it uses the new values.

Long after installing the above hook, @t{comp.sources.x}
came into being, and it too always gives the moderator
name in the @t{From:} field.  The only way to change to
the new regexp @file{comp.sources.\(unix\|games\|x\)} was
to edit the @file{.gnewsrc.hook} file directly.

@item rec.sport.baseball

@example
("Subject" "Phillies" article-yes)
("Subject" "Philadelphia" article-yes)
("Subject" "." article-junk-local)
@findex article-yes
@findex article-junk-local
@end example

I only want to read about worthwhile baseball teams.
Articles about the Phillies are set to, since by running
@code{article-yes}, hook-kill processing is terminated.

All other articles match the @t{"."} regexp, and so they
are junked, but only within this newsgroup.  (For example,
an article about baseball movies would still be seen in
the movies newsgroup if it were crossposted there.)

@item headlines\|politics

@example
("From" "Right-Wing-Nut@@Bolt.Loose.Mil" article-junk)
("From" "Left-Wing-Loon@@Chicken.Delite" article-junk)
("Subject" "\\(\\<\\|hand\\)guns?\\>" article-junk)
@findex article-junk
@end example

These are the more typical uses of hook-kills.  Note how
simply I can dispose of articles that I find uninteresting
across multiple newsgroup boundaries.

This is also a good example of a natural place to use
@code{hook-kill-alist}.  @xref{hook-edit, , Hook Edit}.
@vindex hook-kill-alist

Take careful note of the different styles of backslashing
used in the newsgroup name regexp and the unwanted subject
regexp.  Within regexps, backslashes serve as the magic
character for extended regexp features, while in strings
themselves, backslashes also mean to treat the next character
specially.  So a string that contains a regexp must quote
those backslashes that are meant to be magic in the regexp.

If you edit your @file{.gnewsrc.hook} file directly, the
regexps for the newsgroup names will be inside strings,
and hence backslashes will appear doubled; but these will
still appear as single backslashes if visited via the
@kbd{M-k} (@code{news-hook-edit}) command.
@findex news-hook-edit
@pindex .gnewsrc.hook

@item rec.arts.sf-lovers

@example
(pre nil setq hook-kill-pop nil)
("Newsgroups" "startrek" article-junk-local)
@vindex hook-kill-pop
@findex article-junk-local
@end example

I don't want to read about Star Trek most of the time,
but I don't want to kill the articles, since I sometimes
do read the startrek newsgroup.

For @t{rec.arts.sf-lovers}, I switch to the Hook Kill
list, instead of the default popping, since mine is
rather large.  @xref{hook-edit, , Hook Edit}.

@item comp.risks

@example
(pre nil article-digest)
(pre nil gnews-set 'n-reply-digest-mail "risks@@csl.sri.com")
@vindex n-reply-digest-mail
@findex article-digest
@end example

@t{comp.risks} is a digest newsgroup.  @xref{digest, , Digests}.

The @code{gnews-set} here is used to tell Gnews an address to
mail article followups to, instead of using posting code.

@item comp.society$

@example
(nil nil article-digest)
(nil nil gnews-set 'n-reply-digest-mail "comp-soc@@hplabs.hp.com")
(nil nil gnews-set 'article-formfeed-post "\n\n+            ")
@findex article-digest
@vindex n-reply-digest-mail
@vindex article-formfeed-post
@end example

Note the trailing @kbd{$} as part of the regexp.  This newsgroup
has subgroups that should definitely not be treated similarly.
Further note that these hooks are ignored anyway: they are all
@code{nil}-hooks, not pre-hooks.  The group has a history of sometimes
being a digest only newsgroup, and sometimes being a standard
newsgroup, so I keep the old hooks around.

@item \(control\|\.test$\)

@example
(pre nil gnews-set 'article-header-all-p t)
(pre nil gnews-set 'gnews-advertise t)
@vindex article-header-all-p
@vindex gnews-advertise
@end example

In these newsgroups, the headers are all that matter, so I always
show all of them.  And if I post to one of them, I as might as well
give everyone something to read, hence the advertisement.
@end table

For examples of handling digests that are gatewayed into unmoderated
newsgroups, @pxref{digest mixed, , Digest Mixed}.

@node hook-edit, , hook-examples, hook-kill
@section Hook-Kill editing

The most basic use of hook-kill, for KILLing subjects that you do not
wish to read, needs no special technique to set up.  Short of writing
specialized @kbd{K}-like commands, more advanced uses require direct
editing of the hook-kills.

@table @kbd
@item M-k
@kindex M-k
@kbd{news-hook-edit}
@findex news-hook-edit
@item M-k
@kindex M-k
@kbd{group-hook-edit}
@findex group-hook-edit
@end table

Both @kbd{M-k}s start the @t{*gnews*hook*} buffer in Hook Kill mode.
@code{hook-kill-hook} is the hook for this mode.  No check is made for
Hook Kill editing in progress; any such will get wiped out.  (You
can, of course, undo your way back to previous contents.  But this
will not change Gnews' sense of which regexp you are editing the 
hook-kills for.)
@vindex hook-kill-hook
@pindex *gnews*hook*

You can either pop or switch to the @t{*gnews*hook*} buffer.  This is
controlled by the @code{hook-kill-pop} variable.  Non-@code{nil}, the default,
pops to the buffer, while @code{nil} switches to it.  A numeric value means
pop and resize the window to that value.
@vindex hook-kill-pop

@code{news-hook-edit} prompts the user for either a regexp or a group name.
@code{group-hook-edit} goes to the hook-kills for the current newsgroup
by default.  If the group has a ``designated regexp'', as specified in
@code{hook-kill-alist}, it goes to those regexp's hook-kills instead.

More precisely, @code{hook-kill-alist} is an alist of the form
@vindex hook-kill-alist
@example
((@var{group-1}.@var{regexp}) (@var{group-2}.@var{regexp}) @dots{})
@end example
and has the following effect: if @var{group} has an associated @var{regexp},
then all hook-kill references generated within @var{group} will actually be
to @var{regexp}.  To get to a @var{group}-specific hook-kill when it has
a ``designated regexp'', you can use @code{news-hook-edit} and ask for it
by name.@refill

Hook Kill mode is Emacs Lisp mode, with some extra commands for
help, returning to news reading, and inserting common hook-kills.

@table @kbd
@item C-c ?
@kbd{describe-mode}
@item C-c C-h
@kbd{gnews-describe-mode}
@end table

These are the usual and extended help commands, @pxref{help, , Help}.

@table @kbd
@item C-c C-c
@kindex C-c C-c
@kbd{hook-kill-exit}
@findex hook-kill-exit
@item C-c C-]
@kindex C-c C-]
@kbd{hook-kill-abort}
@findex hook-kill-abort
@end table

These two commands return to News/Group/Article/Reply/Index mode, wherever
you were last in Gnews.  @kbd{C-c C-c} installs the new hook-kills, and
@kbd{C-c C-]} discards them.  If you start a hook edit and do not install
the changes, they will be lost.

@table @kbd
@item C-c C-s
@kindex C-c C-s
@kbd{hook-kill-insert-set}
@findex hook-kill-insert-set
@item C-c C-f
@kindex C-c C-f
@kbd{hook-kill-insert-fset}
@findex hook-kill-insert-fset
@item C-c C-k
@kindex C-c C-k
@kbd{hook-kill-insert-key}
@findex hook-kill-insert-key
@end table

@kbd{C-c C-s} prompts for the name of a user variable, then starts a @code{gnews-set}
pre-hook, leaving point at where the value can be typed in.  @kbd{C-c C-f}
is similar, prompting for a function name and starting a @code{gnews-fset}
pre-hook.  @kbd{C-c C-k} prompts for a key and a command to bind it to,
and inserts a @code{gnews-key} pre-hook.
@findex gnews-set
@findex gnews-fset
@findex gnews-key

@table @kbd
@item C-c C-i
@kindex C-c C-i
@kbd{hook-kill-insert-index}
@findex hook-kill-insert-index
@end table

@kbd{C-c C-i} (@code{hook-kill-insert-index}) inserts an @code{index-if} pre-hook.
A prefix argument specifies an article count: that number (or more) unread
articles will trigger indexing for non-index entry commands.
@xref{index conditional, , Conditional Indexing}.
@findex index

@table @kbd
@item C-c C-d
@kindex C-c C-d
@kbd{hook-kill-insert-digest}
@findex hook-kill-insert-digest
@end table

@kbd{C-c C-d} (@code{hook-kill-insert-digest}) is a catch-all command for
inserting/modifying @code{article-digest} and @code{article-digest-if} pre-hooks.
It tries to be smart about all the possibilities: the description is more
complicated than the actual use.

If the current line is not such a pre-hook, a new pre-hook will be inserted.
If the line is such a pre-hook, then in moderated groups (which use
@code{article-digest}), nothing will happen, while, in unmoderated newsgroups
(which use @code{article-digest-if}), the current article's @t{"From:"} field
will be added as a new field that conditionally activates the Digest
minor mode.
@findex article-digest
@findex article-digest-if

With a prefix argument, the above is changed to use pre-hooks that handle
rot13-ed digests.  If the current line is a pre-hook that handles the
current digest, it will be changed.  If the current line isn't such,
then a new pre-hook will be created.
@cindex rot13

@table @kbd
@item C-c C-j
@kindex C-c C-j
@kbd{hook-kill-insert-junk}
@findex hook-kill-insert-junk
@item C-c C-l
@kindex C-c C-l
@kbd{hook-kill-insert-junk-local}
@findex hook-kill-insert-junk-local
@item C-c C-y
@kindex C-c C-y
@kbd{hook-kill-insert-yes}
@findex hook-kill-insert-yes
@end table

@kbd{C-c C-j}, @kbd{C-c C-l}, @kbd{C-c C-y} prompt for a header from the current article,
and then insert the appropriate per-hook for global junking, local junking,
or immediate setting to respectively.
@cindex junking

Note that, as in the Reply modes, the current article is initially the
same as the article you were in when invoking @kbd{M-k}, but that it can
be changed by contining to read news.

@table @kbd
@item C-c C-o
@kindex C-c C-o
@kbd{hook-kill-insert-pre}
@findex hook-kill-insert-pre
@item C-c C-p
@kindex C-c C-p
@kbd{hook-kill-insert-per}
@findex hook-kill-insert-per
@item C-c C-q
@kindex C-c C-q
@kbd{hook-kill-insert-post}
@findex hook-kill-insert-post
@end table

These three commands insert a generic pre-, per-, or post-hook respectively,
and leave point at a place for finishing the hook.  @kbd{C-c C-p} first
prompts for a header from the current article.

All three deserve to be bound to @kbd{C-c C-p}, so as a mnemonic I crowded
them in order around the @kbd{C-p}.

@page
@node digest, features, hook-kill, Top
@chapter Reading digests

@dfn{Digests} are Usenet articles that consist of multiple submissions,
called @dfn{articles}, bundled together.  Digests mostly come from large
mailing lists that have been gatewayed into Usenet.  The maintainers
of such lists generally find that the human inconvenience of reading
bundled articles---which from their point of view is not much, since
@i{mail} dedigestifiers are rather common---is outvoted by the machine
inconvenience of mailing too many separate unbundled articles.  Gnews
makes it possible to read digests, if not in a totally user transparent
manner, then at least in a reasonably close approximation thereof.
@cindex digest
@cindex article

Note the overload in the word ``articles''.  The standard meaning of
``article''---the smallest item of news intended to travel throughout
Usenet as a single whole---is ignored when discussing digests.  I will
use the phrase ``Usenet article'' for the standard meaning in this chapter
only, with the word ``article'' reserved for the more basic notion of
a single news item submitted for reading.

There are two kinds of newsgroups from the point of view of digests:
those that consist of nothing but digests (these must be moderated
newsgroups) and those that consist of Usenet articles, some of which
happen to be digests.

The Digest minor mode is identical in the two cases.  In the second
case, there is some extra effort to turn the mode on and off.

@menu
* mode:digest mode.		Digest minor mode
* only:digest only.		Digest only newsgroups
* mixed:digest mixed.		Digest mixed newsgroups
@end menu

@node digest mode, digest only, , digest
@section Digest minor mode

The Digest minor mode causes the following changes:

Formfeeds are a long row of dashes.  Gnews distinguishes between a
genuine article separation and a spurious one by checking for a match
just after the row of dashes with @kbd{article-formfeed-post}.
@vindex article-formfeed-post
@cindex formfeed

If the default formfeed is not appropriate for some slightly strange
digest---for example, the old psychology digests used a line of
@t{-=-=-=-=}s to separate articles---then use further pre-hooks to
modify as needed.  This should be done @i{after} the @code{article-digest}
pre-hook, since the latter would only change to the default.  You
should similarly modify a non-standard @code{article-formfeed-post}
afterwards.

@table @kbd
@item n
@kindex n
@kbd{article-digest-next}
@findex article-digest-next
@item p
@kindex p
@kbd{article-digest-previous}
@findex article-digest-previous
@end table

These move forward and backward one article within a digest.  At the
end of a digest, @kbd{n} (@code{article-digest-next}) goes on to the next one,
but at the beginning of a digest, @kbd{p} (@code{article-digest-previous})
dings the user.

@table @kbd
@item <
@kindex <
@kbd{article-digest-restart}
@findex article-digest-restart
@end table

This restarts the current article within a digest.

@table @kbd
@item s
@kindex s
@kbd{article-digest-save}
@findex article-digest-save
@end table

This saves the current article in a prompted for file, much like the usual
@code{group-save}.  This key is only re-bound in Article mode, so you can
save an entire digest by using @kbd{s} (@code{group-save}) when you are at
the end, inside Group mode.  @xref{save, , Saving Articles}.
@findex group-save

At the moment, the other keys have been left alone.  So you can go to
the previous digest with @kbd{P} (@code{group-previous}), etc.  There's a bug
if you try this particular command at the first available article within
a newsgroup: the motion will fail, and the displayed one will be truncated
at what it is currently visible; you have to restart the digest.
@cindex bugs

Replying when in digest mode responds to the current article only.  If
normal posting is inappropriate, you can set @code{n-reply-digest-mail} to
@code{t}, meaning set up mail with address the @t{From:} field, or else you
can set @code{n-reply-digest-mail} to a string, meaning set up mail with that
string as an e-mail address.
@vindex n-reply-digest-mail

It is a feature, not a bug, that you cannot directly respond to the
informational matter that comes at the beginning and end of a digest.
The reply keys will work, but the text of the current non-article is
not yanked in.  The intent is that wholly original replies are easy
to do.  If you wish to reply to the informational matter, you must do
your own cut and paste editing.

Most of the Reply modes' commands do not know anything about digests.  For
example, @kbd{C-c C-y} (@code{reply-yank}) will yank in all the digest
that you've seen before.  But overall, replying works without too much
trouble.
@kindex C-c C-y
@findex reply-yank

@node digest only, digest mixed, digest mode, digest
@section Digest only newsgroups

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @kbd
@item M-x article-digest
@item C-u M-x article-digest
@findex article-digest
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

This is the command for telling Gnews that you are reading nothing but
digests in the current newsgroup.  It starts the Digest minor mode by
resetting several internal variables, functions and keys.  It also sets
the necessary post-hooks for restoring these internals upon newsgroup
exit.

With a prefix argument, the rot13-ed variant of Digest minor mode
will be used.  The initial part is assumed to be in the clear, but
the remaining articles will be assumed to be rot13ed, and will be
automatically decrypted before displaying.

The most convenient way to use the Digest minor mode in a digest-only
newsgroup is to put
@example
(pre nil article-digest)
@end example
@noindent
in the pre-hooks for the newsgroup.  The key sequence
@example
M-k@ @ C-c C-d@ @ C-c C-c
@end example
@noindent
will even do this for you in most cases.  @xref{hook-edit, , Hook Edit}.
(Exceptions must be made for digest-only newsgroups that have non-digest
subgroups.  Then you must use a regexp with a trailing @kbd{$}-sign.)

To use this in the rot13-ed variant (I know of no newsgroup that consists
of rot13-ed digests only) put
@example
(pre nil article-digest nil nil t)
@end example
@noindent
in the pre-hooks for the newsgroup.  The key sequence
@example
M-k@ @ C-u C-c C-d@ @ C-c C-c
@end example
@noindent
will do this for you, with the same caveats.
@xref{hook-theory, , Hook Kill Explanations}.

@code{article-digest-hook} is the hook for the Digest minor mode, and
is run at the end of @code{article-digest}.
@tindex article-digest-hook


@node digest mixed, , digest only, digest
@section Digest mixed newsgroups

@iftex
@newdimen@tableindent @tableindent=4in
@end iftex
@table @kbd
@item M-x article-digest-if
@item C-u M-x article-digest-if
@findex article-digest-if
@end table
@iftex
@newdimen@tableindent @tableindent=.8in
@end iftex

Sometimes a digest shows up unexpectedly in a newsgroup.  You can read
them in the Digest minor mode using this conditional digest command.

@code{article-digest-if} assumes that the user who posted the current Usenet
article only posts digests, and so it will also dedigestify any other
Usenet articles (in this newsgroup, this time that you read the newsgroup)
from the same poster.  With a prefix argument, the digest articles are
furthermore assumed to be rot13ed, and will be decrypted for you.

Other Usenet articles will be read as before.

A few newsgroups have digests regularly posted to them, in addition to
regular Usenet articles.  An example of the hooks to use is presented
below.  Vary this as appropriate for the digests you are interested in.
You can install a @code{article-digest-if} pre-hook appropriate for the
current Usenet article with the exact same keystroke sequence used for
installing an @code{article-digest}.  @xref{digest only, , Digest Only}.

@example
(pre nil gnews-set 'article-formfeed-post-digest
     "\n\n+\\(Date:\\|From:\\|Subject:\\|%%% *\n%%% Concerning\\)")
(pre nil article-digest-if "TeXhax@@Score" t)
("Subject" "roff\\>" article-junk)
    @r{@dots{} etc.}
@vindex article-formfeed-post-digest
@tindex article-digest-if
@end example

The @code{article-digest-if}, in Lisp code, takes a list of arguments
that specify and sets the most basic options about the digests within
a newsgroup.  (So far as I know, no newsgroup receives more than one
digest.  But the code exists for handling them.)

The arguments are interpreted three at a time, one triplet per digest.

The first argument within a triplet is a string, meaning switch to
Digest mode if the current @kbd{"From:"} field matches that string.

The second argument within a triplet is the address for submitting
articles to the digest, if it were indeed matched in the first argument.
An address is either a literal string, meaning mail to that address, or
@code{t}, meaning mail to the address listed in the @kbd{"From:"} field,
or @code{nil}, meaning post to Usenet.

The third argument within a triplet is a rot13 flag.  It is either @code{t},
meaning that the digest, if found, is rot13-ed, or it is @kbd{nil}, meaning
the digest, if found, is posted in the clear.

If no match is found for the different @kbd{"From:"} values, the usual
non-digest values will be in effect.

So a more complicated (fictional) example would be something like:
@example
(pre nil article-digest-if
         "jokes@@haha" t nil
         "dirtyjokes@@haha" "jokes@@haha.berkeley.edu" t)
@end example
@noindent
This example assumes someone is posting digests of jokes, say to @kbd{rec.humor},
with the dirty jokes all rot13-ed in a separate digest.  Submitters are
to reply to the @kbd{jokes} address only.

One extra detail in the @kbd{comp.text} example is the use of a different
@code{article-formfeed-post}.  The TeXhax digest puts a trailing information
message onto the end of the digest, so there is no point in displaying
it as an article separate from the final @samp{End of TeXhax Digest} message.

Note that it is the @code{article-formfeed-post-digest} variable that gets
set here.  The reason is that this is @code{article-formfeed-post} gets
its default value from this inside a digest.  We do not want to change the
value in non-digests.  (And @code{article-formfeed-post-digest-rot13} is
the default value used in rot13-ed digests.)
@vindex article-formfeed-post-digest-rot13

(Why, you might ask, didn't I just say use @code{article-formfeed-post-digest}
in the first place, back in the previous section?  Answer: I think it is
better if you didn't know about this variable if at all possible, since
it is @code{article-formfeed-post} that is actually used internally.)

Similar comments apply to @code{article-formfeed-digest} and @code{article-formfeed}.
@vindex article-formfeed
@vindex article-formfeed-digest

A more complicated setting of variables for different formfeeds or
post-formfeed regexps in multiple digests in a given newsgroup could be
carried out with a newsgroup specific @code{article-digest-hook}.  But with
any luck, a single regexp should be able to handle these.  For example,
if one digest uses a row of dashes, and another uses a row of asterisks,
a regexp that matches on either will probably work without any problem
in both.  Similarly, the extra detail above to handle the trailing TeXhax
message should not cause any problems in another digest.
@vindex article-digest-hook

To date, the only example of ``multiple'' digests within a newsgroup that
I know of is the NEURON digest.  The moderator posts with two or three
slightly distinct @kbd{From:} fields.

@page
@node features, bugs, digest, Top
@appendix Gnews @t{rn}-analogues

Since Gnews is based on @t{rn}, converting from @t{rn} should be
straightforward.  What follows is a brief summary of various
features from an @t{rn} user's point of view and some conversion
hints.  Most of this is described elsewhere in the manual.
@pindex rn

No comparisons with the @t{rnews} program or the @t{M-x rnews} command
are given, since not only are they dissimilar, I am also generally
ignorant of @t{rnews}.  (For those interested, there is an NNTP-based
Emacs version of @t{vn} called @kbd{GNUS}.)  I know even less about other
newsreaders.
@pindex rnews
@cindex newsreader
@pindex GNUS

I assume that my @t{rn} design bias will get in the way of someone
trying to emulate a different newsreader in Emacs.  I'm willing to
rewrite some internals to help such a task.  But the NNTP bias is
not negotiable.
@pindex NNTP

@menu
* summary::	Gnews feature summary
* % formats::	Converting @t{rn} @key{%} formats
* environ::	Converting @t{rn} environmental variables
* flags::	@t{rn} command line flags
@end menu

@node summary, % formats, , features
@appendixsec Gnews feature summary

The various details can be found elsewhere in the manual.

Gnews works inside GNU Emacs.  This in itself is the most winning feature
of Gnews over @t{rn}, although it's easy to forget this fact.

The first major non user-transparent change is that most of the @key{CTL}
commands (@w{@kbd{C-g}}, @w{@kbd{C-k}}, @w{@kbd{C-n}}, @w{@kbd{C-p}}, @w{@kbd{C-r}}, @w{@kbd{C-s}}) have been remapped
by default to the corresponding @key{META} commands to avoid conflict with
standard Emacs interpretations.  Control keys for standard keyboard
functions (@w{@kbd{C-i}}, @w{@kbd{C-j}}, @w{@kbd{C-h}}, @w{@kbd{C-l}}, @w{@kbd{C-m}}) have been left alone.
And poor @w{@kbd{C-x}}, hardly used anyway, had to become @w{@kbd{C-M-x}}.

The second major non user-transparent change is that the @file{.newsrc}
file has been replaced with the @file{.gnewsrc} file, coded in Emacs Lisp.
Gnews will automatically convert an existing @file{.newsrc} over for first
time Gnewsers.  For more information, see @pxref{gnewsrc, , @file{.gnewsrc}}.

And the third major non user-transparent change is that there are no KILL
files.  Instead a single @file{.gnewsrc.hook} file contains special hooks
keyed on regular expressions.  @xref{hook-kill, , Hook Kill}.

Most of the environmental variables are not supported.  Gnews expects you
to set things with appropriate Lisp variables.  A few of the simpler ones,
like @kbd{DOTDIR}, are directly supported.  @xref{environ, , Environment}.

Gnews can be started with @file{.gnewsrc.new} or @file{.gnewsrc.old}, and will
prompt when ready if the program is invoked with an explicit numeric
argument.  @xref{start, , Starting Gnews}.

Gnews can be restarted within a Gnews session with @kbd{R}.  @xref{news, ,
Miscellaneous News Mode}.

Within Emacs, there is no need to support @t{rn} macros, @file{.rninit}
files, @key{%} formats, and special debugging flags.  To see a translation
guide to some of some of this, @pxref{% formats, , @t{rn} Formats}.  And @pxref{customize, , Customize}.@refill

@kbd{C-g} (@code{keyboard-quit}) works as you would expect, instead of the
crash that an @t{rn} interruption generates.

Indexing a newsgroup has become a separate mode that lets you menu
your way through a newsgroup.  @xref{index, , Indexing}.

A menu-like mode to replace @t{rn}'s @kbd{l} and @kbd{L} is only half-written.
If you merely wish to see newsgroup names---which is all @t{rn} lets you
do anyway---use name expansion.

Name expansion on newsgroup names works as you might expect.
@xref{news get, get, Getting Newsgroups}.
Moreover, Gnews lets you abbreviate newsgroup names and parts of names.
@xref{news abbrev, abbrev, Abbrev}.

Articles can be set to by Message-ID.  @xref{artget, , Article Getting}.

You can "permanently" mark articles.  @xref{junk, , Marking}.

There are two rather extensive, almost identical, modes for mailing and
posting replies to Usenet articles.  @xref{reply, , Replying}.

IF SOMEONE POSTS USING A CAPS-ONLY TERMINAL, don't go deaf.  @xref{edit, , Article Edit}.

To get to the end of an article, use @kbd{>} instead of marking.

Unlike @t{rn}, rot13-ing is done relative to the current buffer contents.  In
particular, two rot13's in a row will restore the buffer.  At the moment,
rot13-ing messes up the formfeed @ctrl{L} stop/go effect.

Bogus newsgroups---that is, those that don't exist at your site---are
passed over in silence, even if subscribed to.  Thus, if you expect a
certain new newsgroup to arrive, you may add it in (manually) to your
@file{.gnewsrc} and subscribe ahead of time.  When the group arrives,
it will be treated like any other newsgroup.

Subject search mode has been implemented (for going forward only), but
it is still the primitive one I wrote long ago.  I plan to rewrite it as
part of a larger rewrite of the group and index mode internals.  Instead,
index the group and then sort the index.  @xref{index, , Indexing}.

Pattern searching can only be done for one header field.  Nor can it
be piped through a command---yet.  @xref{pattern}.

Articles can be junked just in the current newsgroup.  @xref{junk, , Junking}.

New newsgroup checking merely informs the user that new newsgroups exist.
@xref{news get, get, Getting Newsgroups}.

@file{.gnewsrc} checkpointing is done upon newsgroup exit, in the file
@file{.gnewsrc.new}.  If the checkpoint file is newer than the @file{.gnewsrc}
file, Gnews will offer to start from the checkpoint file instead.

@node % formats, environ, summary, features
@appendixsec Converting @t{rn} @key{%} formats

The following is a translation table to go from @t{rn}'s @key{%} formats
to the nearest Gnews' equivalent.

@table @asis
@item @t{%a}@ @ @ @ Current article number.
@example
article-current
@end example
@item @t{%A}@ @ @ @ Full name of current article @kbd{(%P/%c/%a)}.
@example
(gnews-spool-art group-current gnews-server-article)
@end example
@item @t{%b}@ @ @ @ Destination of last save command, often a mailbox.
@example
group-last-save
@end example
@item @t{%B}@ @ @ @ The byte offset to the beginning of the article.
@display
Either @kbd{1} or @kbd{(article-min)}.
@end display
@item @t{%c}@ @ @ @ Current newsgroup, directory form.
@example
(gnews-replace "\\." "/" group-current)
@end example
@item @t{%C}@ @ @ @ Current newsgroup, dot form.
@example
group-current
@end example
@item @t{%d}@ @ @ @ Full name of newsgroup directory @kbd{(%P/%c)}.
@example
(gnews-spool-dir group-current)
@end example
@item @t{%D}@ @ @ @ @t{"Distribution:"} line from the current article.
@display
@t{(article-field "Distribution")}
@end display
@item @t{%f}@ @ @ @ The @t{"Reply-To:"} or the @t{"From:"} line.
@example
(article-field "Reply-To" "From")
@end example
@item @t{%F}@ @ @ @ @t{"Newsgroups:"} line for a new article.
@example
(article-field "Followup-To" "Newsgroups")
@end example
@item @t{%h}@ @ @ @ Name of the header file to pass to the mail/news poster.
@example
reply-buffer-name
@end example
@item @t{%H}@ @ @ @ Host name (your machine's name).
@example
gnews-machine
@end example
@item @t{%i}@ @ @ @ @t{"Message-ID:"} line from the current article.
@example
@t{(article-field "Message-ID")}
@end example
@item @t{%I}@ @ @ @ The reply indentation string.
@example
reply-prefix
@end example
@item @t{%l}@ @ @ @ The news administrator's login name, if any.
@display
Unsupported in Gnews.
@end display
@item @t{%L}@ @ @ @ Login name (yours).
@example
gnews-user
@end example
@item @t{%m}@ @ @ @ The current mode of @t{rn}.
@example
@t{major-mode}
@end example
@item @t{%M}@ @ @ @ The number of articles marked to return by the @kbd{M} command.
@example
(length (cdr group-mark-later-list))
@end example
@item @t{%n}@ @ @ @ @t{"Newsgroups:"} line from the current article.
@example
(article-field "Newsgroups")
@end example
@item @t{%N}@ @ @ @ Full name (yours).
@example
gnews-name
@end example
@item @t{%o}@ @ @ @ Organization (yours).
@example
gnews-organization
@end example
@item @t{%O}@ @ @ @ Original working directory (where you ran @t{rn} from).
@example
(save-excursion
  (set-buffer gnews-buffer-return)
  default-directory)
@end example
@item @t{%p}@ @ @ @ Your private news directory, normally @t{~/News}.
@example
gnews-directory
@end example
@item @t{%P}@ @ @ @ Public news spool directory, normally @t{/usr/spool/news}.
@example
gnews-spool-newsdir
@end example
@item @t{%r}@ @ @ @ Base reference on references line of current article.
@example
(gnews-string-as-buffer (article-field "References") 'b
  (beginning-of-line) (re-search-forward ">" nil 1))
@end example
@item @t{%R}@ @ @ @ References list for a new article.
@example
(let ((msgid (article-field "Message-ID"))
      (refs (article-field "References")))
  (if (string= refs "") msgid (concat refs " " msgid)))
@end example
@item @t{%s}@ @ @ @ Subject, with all @t{Re}'s and @t{(nf)}'s stripped off.
@example
(reply-re-0 (article-field "Subject"))
@end example
@display
Note: @t{(nf)}'s are too boring and rare to bother with.
@end display
@item @t{%S}@ @ @ @ Subject, with one "Re:" stripped off.
@example
(let ((sub (article-field "Subject")))
  (if (string-match "^Re:[ \t]*" sub)
      (substring sub (match-end 0)) sub))
@end example
@item @t{%t}@ @ @ @ @t{"To:"} line derived from @t{"Reply-To:"} or @t{"From:"}.
@example
(mail-strip-quoted-names (article-field "Reply-To" "From"))
@end example
@item @t{%T}@ @ @ @ @t{"To:"} line derived from the @t{"Path:"} line.  Unreliable!
@example
(article-field "Path")
@end example
@item @t{%u}@ @ @ @ The number of unread articles in the current newsgroup.
@example
(apply '- article-final 0 (mapcar 'amark-size amark))
@end example
@item @t{%U}@ @ @ @ Unread article count, but not counting the current article.
@example
(apply '- article-final
       (if (amark-member article-current amark) -1 0)
       (mapcar 'amark-size amark))
@end example
@item @t{%x}@ @ @ @ The news library directory.
@display
Huh?  Whazzat?
@end display
@item @t{%X}@ @ @ @ The @t{rn} library directory.
@example
gnews-code-directory
@end example
@item @t{%z}@ @ @ @ The length of the current article in bytes.
@example
(save-excursion (set-buffer nntp-buffer) (point-max))
@end example
@item @t{%~}@ @ @ @ Your home directory.
@example
(expand-file-name "~")
@end example
@item @t{%.}@ @ @ @ The directory containing your dot files.
@example
gnews-dot-dir
@end example
@item @t{%$}@ @ @ @ Current process number.
@example
(make-temp-name "")
@end example
@item @t{%/}@ @ @ @ Last search string.
@example
group-pattern, group-pattern-field
@end example
@item @t{%%}@ @ @ @ A percent sign.
@example
(char-to-string 37)
@end example
@item @t{%@{var@}}@ @ @ @ The environment variable @var{var}.
@example
(getenv "@var{var}")
@end example
@item @t{%[name]}@ @ @ @ Header field for @t{"@var{name}:"}.
@example
(article-field "@var{name}")
@end example
@item @t{%`command`}@ @ @ @ Result of shell @var{command} inserted.
@example
(call-process @var{command} @t{etc @dots{}})
@end example
@item @t{%"prompt"}@ @ @ @ Inserts @var{prompt}ed for string.
@example
(read-string "@var{prompt}")
@end example
@item @t{%digit}@ @ @ @ @var{digit}'th string match
@example
(substring @dots{}
  (match-beginning @var{digit}) (match-end @var{digit}))
@end example
@item @t{%(string=pattern?@dots{})}@ @ @ @ Conditional string
@example
(if (string-match "@var{pattern}" "@var{string}") @dots{})
@end example
@end table
@iftex
@write@fnindfile{@realbackslash entry {gnews-doctor}{!?}{gnews-doctor}}
@end iftex

@node environ, flags, % formats, features
@appendixsec Converting @t{rn} environmental variables

Gnews supports a few of the following environmental variables.  Those
marked with an asterisk are handled the same as in @t{rn}, with the name
of the Gnews internal variable that gets set to the variable's value
listed afterwards.  Otherwise, these variables are ignored, and the
Gnews code/hooks to use to get similar effects are listed.  Some of
the variables are meaningless to Gnews, some are handled by non-Gnews
Emacs functions, and a few have not or will not be implemented.

As you are encouraged to set things inside @file{.emacs} instead of
using environmental variables, no detailed explanations are given.

@table @key

@item *DOTDIR
@itemx *HOME
@itemx *LOGDIR
Your dot files, home directory, login directory.

@kbd{gnews-dot-dir}

@item *USER
@itemx *LOGNAME
Your login name.

@kbd{gnews-user}

@item *NAME
Your full name.

@kbd{gnews-name}

@item *ORGANIZATION
The name of your organization.

@kbd{gnews-organization}

@item EDITOR 
@itemx VISUAL
The name of your editor.

@t{"Emacs"}

@item FIRSTLINE 
Controls the format of the line displayed at the top of an article.

Unsupported in Gnews---now and forever.

But see @kbd{article-header-hook}, @kbd{gnews-mode-string}

@item HIDELINE
A regular expression which matches article lines to be hidden.

Unsupported in Gnews---now and ???

@item PAGESTOP
A regexp that identifies formfeeds.

@kbd{article-formfeed}, see @kbd{article-formfeed-top}, @kbd{article-digest}.

@item KILLGLOBAL 
@itemx KILLLOCAL 
Where to find KILL files

Meaningless in Gnews.

@kbd{(assoc "." hook-kill-list)} gives the global hook-kills.
@kbd{(assoc group-current hook-kill-list)} gives the @kbd{group-current}
specific hook-kills.  Others will be applicable based on regexp
matching.

@item SUBJLINE 
The format of the lines displayed by the indexing.

@kbd{index-headers}, @kbd{index-format}, @kbd{index-sizes}, @kbd{index-filter}

@item ATTRIBUTION
@itemx YOUSAID 
Format of blurbs for posting/mailing replies.

@kbd{reply-short-blurb}---see also @kbd{reply-long-blurb}, @kbd{reply-blurb}

@item MAILFILE 
Where to check for mail.

Depends on your Emacs mail reader.  In Rmail: @kbd{rmail-primary-inbox-list}

@item MAILHEADER 
@itemx MAILPOSTER 
The header file and shell command for e-mail replies.

@kbd{group-reply}, @kbd{group-reply-hook}, @kbd{group-reply-start-hook},
@kbd{sendmail-program}

@item MBOXSAVER 
@itemx NORMSAVER 
The shell command to save an article in mbox/literal format.

@kbd{gnews-save-style}

See also @kbd{gnews-output-to-rmail-file} and @kbd{gnews-output-to-mbox-file}.

@item NEWSHEADER 
@itemx NEWSPOSTER 
The header file and shell command for posting articles.

@kbd{group-follow}, @kbd{group-follow-hook}, @kbd{group-follow-start-hook}
@kbd{n-reply-program}, @kbd{n-reply-program-args}

@item CANCEL 
@itemx CANCELHEADER 
The shell command and file format to cancel an article.

@kbd{group-cancel}, @kbd{article-cancel-hook}, @kbd{n-reply-program},
@kbd{n-reply-program-args}.

See also @kbd{group-supersede}, @kbd{article-supersede-hook}

@item PIPESAVER 
The shell command to execute in order to pipe an article.

@kbd{shell-command-on-region}

@item RNINIT 
Default values for switches may be passed to @t{rn}.

@kbd{gnews-start-hook}, @kbd{gnews-ready-hook}

@item RNMACRO 
The name of the file containing macros and key mappings.

@file{.emacs}

@item SAVEDIR 
@itemx SAVENAME 
The name of the directory and file to save in.

@kbd{group-save-name}, @kbd{gnews-save-style}

@item SHELL
The name of your preferred shell.

@kbd{shell}

@item TERM
@itemx TERMCAP
Determines which termcap entry to use.

Left to Emacs.
@end table

@node flags, , environ, features
@appendixsec @t{rn} command line flags

*****

@page
@node bugs, customize, features, Top
@appendix Gnews bugs and annoyances
@cindex bugs

This appendix describes mostly permanent bugs.

To report bugs, @pxref{bug reports, , Bug Reports}.

Gnews only works on Emacs versions 18.45 or so and up.

@code{group-save}, @code{group-pipe} and @code{group-cancel} are not yet
applicable to a range of commands.

The hook-kill facilities are triggered by regular expression matching.
While usually a win---you can specify @t{news.*} specific hooks---naive use
may lead to some unwanted complications.  For example, @t{sci.math}'s
hook-kills are inherited by @t{sci.math.stat}.  If a problem occurs,
you can use @code{hook-kill-alist}.  @xref{hook-edit, , Hook Edit}.

The @t{rn} @kbd{-c} flag, for checking, is not simulated.

The @t{ucbvax} NNTP server would sometimes disconnect upon setting to a
non-existent article by Message-ID; the now gone @t{jade} server would
set to an ``article'' whose entire contents would be 3 characters.

@kbd{M-p} (@code{group-previous-same-subject}) does not exist.

The @t{rn} abilities to search for some regexp in a header or article, and
to KILL based on some regexp in the body of an article, are not yet
implemented.

Gnews is not electric, so non-Gnews motion commands can confuse Gnews.
Try the sequence @kbd{> M-<} (@code{article-end, beginning-of-buffer}).

Case sensitivity has been left to the appropriate Emacs variable.

Indexing chokes on empty indexes.  Hit @kbd{C-g} and/or @kbd{q}.

Gnews is a tad bit slower than @t{rn} in most respects, and much faster
in a few.  Overall it has been fast enough in most users' experiences.

No separate @file{Pnews} is provided.  To post an original article, go to
the pseudo-article at the @t{$}-end of a newsgroup and post a followup.  If
an article was started but then saved rather than posted, then visiting
the file in N-Reply mode, and using the provided posting functions, will
work as expected without starting up a separate Gnews.  However, you will
probably have problems if the Gnews functions aren't loaded.

It's tempting to edit @file{.gnewsrc.*} files directly.  Gnews of course
will overwrite them, so eval such buffers before returning.  In case of a
malformed @file{.gnewsrc} file, Gnews will visit the file automatically,
which I find is a convenience, but the user will have to remember to handle
the buffer gingerly.  And furthermore, if you leave such a buffer around,
Emacs will sometimes query about that buffer being modified on disc on
trying to quit news.  I've always found such a message a small mental
hassle; I've discovered that it's even more annoying when it's coming
from a hidden buffer that I've forgotten about.  Perhaps Emacs should
offer a more complete message?

A related difficulty is that no locking of @file{.gnewsrc} files is provided.
There is no danger from running two Gnews within the same Emacs, since
when one Gnews is running, a second Gnews invocation returns you to the
former's context.  But there is no protection from starting up a second
Emacs and running a second Gnews there, other than the user noticing a
strong familiarity in the articles coming through.

It is recommended that you have a modified @code{save-buffers-kill-emacs}
function to query before exiting, so as to avoid accidents, and to cleanly
exit Gnews for you if you haven't done so already.  For an example,
@pxref{customize, , Customize}.

Some people are going to pronounce the name of this software ``JEE-nuz'',
instead of ``guh-NUZ'', a homonym for GNU's.  This may be OK for now, but
someday a real @file{G news} will be around, and no doubt awful confusion
might ensue.  Golly.

All my comparisons are biased, not only by personal prejudices in favor
of GNU Emacs and my own code, but by my now long lack of @t{rn} experience.

@page
@node customize, internals, bugs, Top
@appendix Customizing Gnews

Gnews customization can be done in several ways.  The simplest is to
set the appropriate user variables or to rebind keys.  This can only
modify things that I've directly programmed for ahead of time.  Anything
else requires Lisp code on your part, from minimal hooks and functions
to whole extra modes.  Numerous examples are provided, so if you're
just learning Emacs Lisp, you can still probably figure out what might
work for you.

I am willing to introduce more user variables, function hooks, and
little functions: let me know what you would like.

@menu
* rebinding keys::		Rebinding keys and prompts
* user variables::		User variables
* function hooks::		Gnews function hooks
* little functions::		Little Emacs functions
@end menu

@node rebinding keys, user variables, , customize
@appendixsec Rebinding keys and prompts

If you plan to change the default key bindings, there are a few
pitfalls to look out for.

Gnews defines the basic keymaps upon initial loading, unless the
relevant keymap variables have already been defined and are non-@code{nil}.
In which case, such already defined keymaps will not be changed.
You should only do this for extensive redefinitions, for example,
if you prefer to emulate a different newsreader other than @t{rn}.
@pindex rn
@cindex newsreader

If you wish to make only a few keybindings, you should put these in
@code{gnews-start-hook}.  If you wish to make a few keybindings within
a given newsgroup, you should use @code{gnews-key}.  @xref{hook-examples, ,
Example Hook Kills}.
@findex gnews-key
@vindex gnews-start-hook

There are a few basic commands which are referred to in prompts.
For the sake of speed, I do not compute the prompts, but just
assume that they follow the default key bindings.  The prompts
and their default values are listed below:

News mode:

@table @code
@item news-prompt-yes@ @ @ @t{[ynp]}
@vindex news-prompt-yes
For when proffering newsgroups with unread news.
@item news-prompt-next@ @ @ @t{[npq]}
@vindex news-prompt-next
For when proffering newsgroups with no unread news.
@item news-prompt-quit@ @ @ @t{[qnp]}
@vindex news-prompt-quit
For when there is apparently no unread news any more.
@item news-prompt-first@ @ @ @t{[npq]}
@vindex news-prompt-first
For when at the @t{$}-end of the newsgroups.
@cindex $-pseudo group
@end table

Group mode:

@table @code
@item group-prompt-normal@ @ @ @t{[npq]}
@vindex group-prompt-normal
The default prompt when subject-searching is turned off.
@item group-prompt-same-subject@ @ @ @t{[~Nnpq]}
@vindex group-prompt-same-subject
The default prompt when subject-searching is turned on.
@item group-prompt-default@ @ @ @t{[npq]}
@vindex group-prompt-default
One of the above two prompts.
@item group-prompt-pf@ @ @ @t{[/?npq]}
@vindex group-prompt-pf
The default prompt when pattern searching forward.
@item group-prompt-pb@ @ @ @t{[?/npq]}
@vindex group-prompt-pb
The default prompt when pattern searching backward.
@item group-query-pf@ @ @ @r{``}@t{/-search }@r{''}
@vindex group-query-pf
The query to use when pattern searching forward.
@item group-query-pb@ @ @ @r{``}@t{?-search }@r{''}
@vindex group-query-pb
The query to use when pattern searching backward.
@end table

Newsgroup name reading uses the internal function @code{group-name-read}
to get a name.  This function does the actual name completion and
abbrevation expansion.  It tries to be smart about keymaps.  For
example, @kbd{$} by itself abbreviates the last newsgroup.  If you
change your binding of @kbd{$} (@code{news-end}) to @kbd{#} say, then
@kbd{#} will be the abbreviation for the last newsgroup.  Similarly,
the @kbd{g} (@code{news-goto}) command enters via indexing if the first
key typed is whatever you have bound to @code{news-index}.  @xref{news get, ,
Getting Newsgroups}.
@findex news-end
@findex news-index
@findex news-goto

There's one exception to this follow-the-keymap style behavior.  You can
also rebind keys in @code{gnews-abbrev-keymap}, the keymap for interpreting
abbreviations and name completion.  If @samp{.} (@code{gnews-abbrev-expand})
has been rebound, then the new key will expand abbreviations, but it
will insert periods as part of the newsgroup name.
@cindex abbreviations
@tindex gnews-abbrev-keymap
@findex gnews-abbrev-expand

@node user variables, function hooks, rebinding keys, customize
@appendixsec User variables

Not all user variables are listed here; many have been described elsewhere
in the manual.  See the index.

Many of the options might seem useless to you---the defaults are mostly
the ``correct'' ones---but sometimes the perfect way to handle some temporary
Usenet botheration is by setting one of these in a pre-hook.
	
@table @code
@item article-auto-junk-locally
@vindex article-auto-junk-locally
Non-@code{nil} means hook-kills are by default local junks.

@item article-big
@vindex article-big
The number of lines which indicate an article is considered big, meaning
that @code{article-display-count} is temporarily treated as @code{nil}.  This
is of use only if your value for @code{article-display-count} is numeric.

@item article-digest-separator
@vindex article-digest-separator
Regexp that identifies the separator between digests.

@item article-display-count
@vindex article-display-count
The number of lines of the article to get and display initially.  If
@code{nil}, the entire article is fetched and one screen is displayed.

@item article-formfeed
@vindex article-formfeed
Regexp that identifies formfeeds.  Article scrolling stops at a formfeed.

@item article-formfeed-post
@vindex article-formfeed-post
If non-@code{nil}, a regexp used to distinguish true formfeeds from false
formfeeds.  True formfeeds are those that are followed by a string that
matches the regexp.

@item article-formfeed-post-digest
@vindex article-formfeed-post-digest
The value for @code{article-formfeed-post} to use in digests.  In pre-hooks
for digests where the default is incorrect, you either @code{gnews-set} this
variable @i{before} running @code{article-digest}, or else you redefine the
variable @code{article-formfeed-post} @i{after} running @code{article-digest}.
@findex article-digest

@item article-formfeed-top
@vindex article-formfeed-top
If numeric, it is the line to redraw the formfeed at after scrolling past
a formfeed.  If @code{nil}, scrolling past a formfeed fills the screen with
more of the article.

@item article-grep-height
@vindex article-grep-height
Line on screen at which to display @kbd{g} (@code{article-grep}) matches.

@item article-junk-terse
@vindex article-junk-terse
Non-@code{nil} means junk articles tersely.  @code{nil} means junk articles
with the offending header line echoed.
@cindex junking

@item article-subject-hilite
@vindex article-subject-hilite
Non-@code{nil} means highlight the subject of the current article.

@item gnews-advertise
@vindex gnews-advertise
If non-@code{nil}, include a @t{Posting-Front-End:} field when posting.

@item gnews-buffer-clean
@vindex gnews-buffer-clean
Non-@code{nil} means kill, as oppose to bury, Gnews' work buffers upon
quitting.

@item gnews-configuration-p
@vindex gnews-configuration-p
Non-@code{nil} means to use Lisp window configuration code when entering
and exiting from newsgroups.  Recommended for peculiar set ups only.

@item gnews-copyright-display
@vindex gnews-copyright-display
Display the copyright notice if @code{t}.

@item gnews-dot-dir
@vindex gnews-dot-dir
User's Gnews bookkeeping files' directory.

@item gnews-flush-typeahead
@vindex gnews-flush-typeahead
If non-@code{nil}, typeahead is flushed.
@cindex typeahead

@item gnews-home-dir
@vindex gnews-home-dir
User's home directory.

@item article-header-ignore
@vindex article-header-ignore
List of unsightly header fields.
@cindex header

@item gnews-minor-mode-alist
@vindex gnews-minor-mode-alist
The association list of minor modes to apply when in Gnews.
@cindex mode line

@item gnews-name
@vindex gnews-name
User's name, as gleaned, by default, from the @file{/etc/passwd} file.

@item gnews-news-dir
@vindex gnews-news-dir
Directory to keep user's news save files.

@item gnews-rc-file-name
@vindex gnews-rc-file-name
User's newsgroup roster file name.

@item gnews-user
@vindex gnews-user
User's login name.

@item group-kill-auto
@vindex group-kill-auto
Non-@code{nil} means automatically kill the current subject if a
@code{group-kill-*} command is invoked.  @code{nil} means query first.

@item news-grab-cursor
@vindex news-grab-cursor
Non-@code{nil} means keep the cursor in the minibuffer when in News mode.
Useful if it flickers too much.

@item reply-buffer-save
@vindex reply-buffer-save
If non-@code{nil}, offer to save @t{*reply*} buffers before exiting Emacs.

@item reply-prefix-fill
@vindex reply-prefix-fill
Regexp that defines prefixes for @kbd{C-c C-q} (@code{reply-yank-fill}).

@item reply-prefix-match
@vindex reply-prefix-match
Characters that define prefixes for @kbd{C-c C-o} (@code{reply-split-line}).

@item reply-query-clear
@vindex reply-query-clear
If non-@code{nil} and non-numeric, get user confirmation, before starting a
new reply that would overwrite a message in the @t{*gnews*reply*} buffer.
If numeric (the default), get confirmation for overwriting unsent replies
only---already sent messages will be silently overwritten.  If @code{nil}, no
confirmation is needed; all messages will be overwritten.
@pindex *gnews*reply*
@end table

@node function hooks, little functions, user variables, customize
@appendixsec Gnews function hooks

Emacs provides hooks to most major modes and interesting situations.
So does Gnews.  Because of the complexity of Gnews, there are about
two dozen such hooks---you will probably end up using only a few.

For most applications, a simple @code{setq} of the hook variable to a
quoted function name suffices.  See the on-line Emacs documentation
of @code{run-hooks} for details about the general case.

The hooks used in the Reply modes are described elsewhere.
@xref{reply start hooks, , Reply Start Hooks}, also @pxref{send, , Sending
Replies}.

@table @code
@item gnews-start-hook
@itemx gnews-ready-hook
@vindex gnews-start-hook
@vindex gnews-ready-hook
These two hooks are run when first beginning Gnews.  The start hook
is essentially the first thing done upon running @kbd{M-x gnews}.  It
is the place where basic non-default variables, like @code{gnews-dot-dir},
should be set.

The ready hook is run after loading the @file{.gnewsrc} file, but before
looking for any unread news.  This is also the place to initialize any
variables local to the News/Group/Article mode buffer.

@item gnews-quit-hook
@vindex gnews-quit-hook
The quit hook is run after writing the final @file{.gnewsrc} out.  One
simple application would be to write out the current newsgroup to a file
for reading back in by the ready hook next time around, letting you
restart Gnews at that newsgroup.

@item @var{mode}-hook
@tindex article-mode
@tindex news-mode
@tindex group-mode
@tindex index-mode
@tindex e-reply-mode
@tindex n-reply-mode
@tindex hook-kill-mode
@tindex gnews-edit-mode
@vindex article-hook
@vindex news-hook
@vindex group-hook
@vindex index-hook
@vindex e-reply-hook
@vindex n-reply-hook
@vindex hook-kill-hook
@vindex gnews-edit-hook
The @var{mode} hook is run upon entering @var{mode}-mode.  @var{mode} is
one of @kbd{article}, @kbd{group}, @kbd{news}, @kbd{index}, @kbd{e-reply},
@kbd{n-reply}, @kbd{hook-kill}, and @kbd{gnews-edit}.  This is where
you should set your own preferred key bindings.@refill

@item article-header-hook
@vindex article-header-hook
This hook is run after an article's headers have been set up for an
article inside the hidden @t{*gnews*nntp*} scratch buffer, but before
the article is actually displayed in the @t{*gnews*} buffer.
@pindex *gnews*nntp*
@pindex *gnews*

This hook serves as a general per-article hook.  This is distinct from
the hook-kill per-hooks.  The latter are only conditionally activated,
nor are they invoked when an article is set to explicitly.  Both have
their uses.

@item group-last-hook
@vindex group-last-hook
This hook is run upon setting to the @kbd{$}-pseudo-article.
@cindex $-pseudo article

@item article-digest-hook
@vindex article-digest-hook
This hook is run after the basic Digest mode settings have been made
inside @code{article-digest}.
@findex article-digest

@item article-not-found-hook
@vindex article-not-found-hook
@code{article-not-found-hook} is a symbol or a list of symbols.  The
individual symbols are function names to call.  Each one is called
in order until one of them returns @code{t}, meaning that an article
was found and has been set to.

This hook is invoked if the supplied action does not find the indicated
article.  If none returns @code{t}, the article is finally considered not
found.  This can be used to search through alternate servers, private
archives, and the like.  Look at the source for @code{article-get-slow} to
get some idea of how Gnews expects you to initialize an article, run
hooks, etc.  (@code{article-get} is rather complicated for speed's sake,
so don't emulate it unless you really need the extra speed.)
@findex article-get-slow
@findex article-get

Each not-found hook is passed three arguments, the article number, a
list of hook-kills, and a flag to indicate interactive use.  Each should
return @code{nil} upon failure to find the article, non-@code{nil} otherwise.
@cindex hook-kill

See the internal documentation for @code{article-run-hooks}.  Note that
the full generality of @code{run-hooks} style arguments is not supported.
@tindex article-run-hooks

@end table

@node little functions, , function hooks, customize
@appendixsec Little Emacs functions

There are several little functions you might wish to rewrite.  In
each case, they were originally embedded inside some larger function,
and for user rewrite convenience, have been taken out.

@table @code
@item gnews-rc
@tindex gnews-rc
This is the function which identifies the @file{.gnewsrc} file, and
does conversions and the like.  If you use a more complicated backup
scheme, or if you still use the @file{.newsrc}, rewrite this function.
@pindex .gnewsrc
@pindex .newsrc

@item gnews-ready
@tindex gnews-ready
Gnews' action upon startup with a numeric prefix.

The default is to prompt @t{ready [npq]}.

@item reply-wide
@tindex reply-wide
This function is invoked when posting in a window with more than
80 columns.

The default is to turn on auto-fill mode.

@item gnews-save-name
@tindex gnews-save-name
With arguments @var{newsgroup} and @var{article-no}, it generates a
name to save files in when using the default @code{gnews-save-style}.
@vindex gnews-save-style

The result depends on the value of @code{gnews-slashify}.  If it is @code{nil},
the function returns something like @t{comp.unix.spelunkers.3456}.  If
it is @code{t}, it returns something like @t{comp/unix/spelunkers/3456}.
Otherwise---the default---the function returns something like
@t{comp.unix.spelunkers/3456}.
@vindex gnews-slashify

@item index-sort-prep
@itemx index-sort-function
@tindex index-sort-prep
@tindex index-sort-function
These two functions are used when sorting the index buffer.
@xref{index custom, , Customized Indexing}

@item article-header-tweak
@tindex article-header-tweak
This function takes two string arguments, a header @var{field} and a
@var{string}.  The returned value will be the actual string to display
for the header @var{field}.

The default just returns @var{string}.

@item article-digest-header-tweak
@tindex article-digest-header-tweak
This function takes three arguments.  A header @var{field}, the header's
value from the digest, and the header's field, if present, from the
article.

The default strips comments off a @t{From:} header, strips ``Re:''s off
from the @t{Subject:}, and sets a phony message-ID based on the digest's
subject line.

@item news-next-unread-maybe
@tindex news-next-unread-maybe
This is the action after taken an automatic newsgroup quit.

The default checks which command invoked the current newsgroup entry,
and then runs either @kbd{n} or @kbd{p} if that seems appropriate, and
prompts otherwise.

@item hook-kill-junk-message
@tindex hook-kill-junk-message
Supply a message upon junking an article.

The default is the article number and the word ``junked'' if the
variable @code{article-junk-terse} is non-@code{nil}, and is the
entire offending header line if @code{nil}.
@vindex article-junk-terse
@end table

@page
@node internals, examples, customize, Top
@appendix Internal Gnews details

The exact syntax of the various commands and functions mentioned will
not be described here, as they are all self-documenting.  By the time
you would worry about such details, you would probably be studying the
source code anyway.

@noindent
@bullet What NNTP commands does Gnews use?
@cindex NNTP commands
@table @kbd
@item list
Returns the list of active newsgroups.  It is kept in @code{roster-string}.
@item group @var{newsgroup}
Get basic information about the group @var{newsgroup}.  NNTP commands
that assume a newsgroup will assume this one until the next @kbd{group}
command.
@item article
@itemx article @var{number}
@itemx article @var{<message-id>}
Get the contents of the current article, the article with the indicated
article @var{number}, or the article with the indicated @var{<message-id>},
respectively.
@item head
@itemx body
@itemx stat
These are interpreted similar to the @kbd{article} command.  They return
the indicated article's headers, body, and existence status respectively.
@item next
@itemx last
Change the internal article to the next or previous one.
@item quit
Close the NNTP connection.
@end table

@noindent
@bullet How does Gnews use NNTP?

The NNTP focus is through the @code{nntp-exec} command (yes, you can invoke
it interactively) and the @file{*gnews*nntp*} buffer.  @code{nntp-exec} has
several side effects: NNTP's own side effects, the buffer is changed, and
the variable @code{nntp-info} is set to the NNTP information header.  It
returns non-@code{nil} when the NNTP command was a success, @code{nil} otherwise.
@pindex NNTP
@pindex *gnews*nntp*
@tindex nntp-info
@tindex nntp-exec

@code{nntp-exec} determines first if Gnews is repeating the same NNTP command
as last time.  If so, and if the command is known to not have side effects,
and the variable @code{nntp-exec-force} is @code{nil}, then the buffer and
@code{nntp-info} will be assumed to be correct, and the previous value will
be returned.
@tindex nntp-exec-force

If @code{nntp-exec-verbose} is non-@code{nil}, NNTP messages will be echoed.
If @code{nntp-exec-log-p} is non-@code{nil}, a log of NNTP commands will be
kept in the variable @code{nntp-exec-log}.
@tindex nntp-exec-verbose
@tindex nntp-exec-log-p
@tindex nntp-exec-log

@noindent
@bullet How does Gnews handle new newsgroups?

Gnews maintains a copy of the last active file seen in your @file{.gnewsrc.list}
file.  When you start Gnews, the first NNTP command run is @kbd{list}.  The
length of the new list is compared to the old one, and if the new one is
longer, Gnews sets @code{roster-new-p} and gives you a message that new
newsgroups have arrived.  This may be incorrect.  Gnews maintains a copy
of the current list in the @code{roster-string} variable.
@pindex .gnewsrc.list
@tindex roster-new-p
@tindex roster-string

You subscribe to new newsgroups by running @kbd{M-g} (@code{news-new}).  The
user interface here is a pathetic kludge, but rewriting it is, for now, a
very low priority.  @xref{news get, get, Getting Newsgroups}.
@findex news-new
@kindex M-g

@code{news-new} runs the internal @code{roster-all}, which converts the
@code{roster-string} into an equivalent list @code{roster}.  The exact format
of @code{roster} is a list whose entries are of the form
@example
(@var{newsgroup} @var{first-article} @var{last-article})
@end example
@noindent
Name completion proceeds with respect to this variable, but @code{news-new}
avoids matching newsgroups that are in your @file{.gnewsrc}.
@pindex .gnewsrc
@tindex roster-all
@tindex roster

@noindent
@bullet Describe newsgroup name completion/abbreviation.

The basic function for this is @code{group-name-read}.  It displays a
prompt, and then reads a character from the minibuffer, which it saves
in the variable @code{group-read-mood}.  If this character is @kbd{=}, as
in @code{news-index}, or @kbd{@@}, as in @code{news-at} the prompt is changed
slightly,
with an extra @kbd{[index]} or @kbd{[set to]} inserted.  (The calling routine
decides if this initial character is significant.)  If the character is a
key for Emacs name completion, completion is attempted.  If the character
is @key{.}, as in @code{gnews-abbrev-expand}, the current newsgroup name is
inserted in the minibuffer.  If the first character typed is @kbd{^}, as
in @code{news-first-unread}, or @kbd{$}, as in @code{news-end}, the first or
last newsgroup respectively is inserted in the minibuffer.  Otherwise, the
first character typed is inserted in the minibuffer.
@kindex ^
@kindex $
@kindex @@
@kindex =
@findex news-end
@findex news-first-unread
@findex news-at
@findex news-index
@tindex group-read-mood
@tindex group-name-read

The rest of the name is read in with @code{read-from-minibuffer}.  This uses
@code{gnews-abbrev-keymap} for a keymap, and whatever the calling function
passed for a name completion alist and predicate.  (Note that there is no
Emacs Lisp function for reading for the minibuffer that takes both a keymap
and a name completion alist as arguments.  It can be done, as the code proves.)
@vindex gnews-abbrev-keymap

When @code{group-name-read} is called, the invoking command is saved away.
Certain ways of quitting from a newsgroup resume or don't resume the search
for new news based on the newsgroup entry command.  This is the place to
save the name of the command since name expansion itself is entered into
the command list.

There is a slight bug when name completion is the first character typed.
I cannot get @code{minibuffer-scroll-window} to recognize the currect window
here.  Any clue as to what to do here would be most welcome.
@cindex bugs

@noindent
@bullet How does Gnews find a newsgroup with unread news?

The core function is @code{news-next-intern}.  Gnews loops through @code{group-roster}
as appropriate.  It tests if the current restrictions apply, if the group
is subscribed to, and if the results of the NNTP @kbd{list} command indicate
that new news has arrived for this newsgroup.  This latter is not always
definitive (the group may be empty), so the NNTP @kbd{group} command is
actually used to get the exact information about the current newsgroup.
@vindex group-roster
@tindex news-next-intern

@noindent
@bullet What happens when Gnews enters a newsgroup?

Lots of internal variables get set.  (See the source code of @code{group-set}
and @code{group-get}.)  And the appropriate pre-hooks are run.
@tindex group-get
@tindex group-set

A slight bit of trickiness is needed to set the first article, and the
first unread article number, correctly.  This is because Gnews used to on
rare occasions go into infinite loops when one of these was bogus.

@noindent
@bullet Describe how Gnews finds the next unread article.

The command that does this, @code{group-next-unread}, is surprisingly
trickier than you would expect at first blush.  The variable @code{article-status}
is used to drive an open-ended @code{while} loop.  Article setting is
attempted by marching down either the @code{amark} or the index buffer.
@tindex group-next-unread
@tindex article-status
@tindex amark

Given a prospective article number to consider, the command @code{article-get}
runs an NNTP @kbd{head} command.  This is checked to see if the article
actually exists, and then hook-kills are run.  If the article does not
exist, or it is junked, the outer find-the-next-article loop is continued
via a @code{(throw 'article-nil t)}.
@tindex article-get
@tindex article-nil

If the article is to be set to, then the rest of the article is fetched
with an NNTP @kbd{body} command.  A little bit of hackery is needed to
explicitly get the NNTP informational message out of the way---unlike
other NNTP invocations, the NNTP buffer is not cleared first.  The first
pending Gnews command, if any, is executed, even if typeahead flushing is
turned on.

@noindent
@bullet 

@noindent
@bullet 

@noindent
@bullet 

@noindent
@bullet 

@noindent
@bullet 

@noindent
@bullet 

@noindent
@bullet 

@noindent
@bullet 


@page
@node examples, install, internals, Top
@appendix Example Gnews code

What follows are various examples of customizations, mostly my own.
Most are too strange or too idiosyncratic to be put in Gnews, while a
few are here instead of in Gnews because they need more work to be
properly general.

In my own code, I use the convention that the value of @code{foo-bar-hook}
is generally @code{foo:bar:hook}.  Thus, somewhere in my @file{.emacs} are
lines like @samp{(setq gnews-start-hook 'gnews:start:hook)}.  Of course,
you can use whatever convention you like.

(For examples of hook-kills, @pxref{hook-examples, , Example Hook Kills}.)

@menu
* start:examples start.		Start hooks
* abbrev:examples abbrev.	Abbrevations
* index:examples index.		Index hooks
* reply:examples reply.		Reply hooks
* mail:examples mail.		Mail hooks
* baud:examples baud.           Slow baud rates
* misc:examples misc.		Miscellany
@end menu

@node examples start, examples abbrev, , examples
@appendixsec Start hooks

Here is my start hook.  I define all the internal Gnews hooks that
I'm going to use, plus I set a few variables.  Note one fine point:
I switch or pop to the index buffer based on how big the window is.
I usually have thirty some lines, but I sometimes use standard 24 line
terminals.

The functions refered to in @code{gnews:start:hook} are defined in later
sections of this appendix.

@example
(defun gnews:start:hook ()
@findex gnews:start:hook*
  (fset 'article-header-tweak 'article:header:tweak)
  (setq group-reply-hook 'reply:hook
        group-follow-hook 'reply:hook
        group-reply-start-hook 'reply:start:hook
        group-follow-start-hook 'reply:start:hook
        e-reply-send-hook 'reply:send:hook
        n-reply-send-hook 'reply:send:hook
        index-hook 'index:hook
        group-hook 'group:hook
        article-hook 'article:hook
        article-cancel-hook 'cancel:hook
        article-supersede-hook 'cancel:hook
        article-display-count 12
        index-pop-up (if (< 30 (window-height)) 10)
        reply-buffer-save nil
        gnews-copyright-display 'yow
@cindex yow!
        gnews-news-dir "~/n/"
        gnews-machine "garnet.berkeley.edu"
        article-header-show '(In-reply-to)
        article-header-ignore
        (append '(Lines Organization Reply-To Message-ID
                  Keywords References Distribution)
                article-header-ignore)))
@end example

@node examples abbrev, examples index, examples start, weemba
@appendixsec Abbrevations

These are the newsgroup abbreviations I use:
@cindex abbreviations

@example
s  ~~~>  sci                       t  ~~~>  talk
n  ~~~>  news                      m  ~~~>  misc
r  ~~~>  rec                       p  ~~~>  talk.philosophy.misc
c  ~~~>  rec.arts.comics           e  ~~~>  comp.emacs
sf ~~~>  rec.arts.sf-lovers        as ~~~>  sci.astro
sp ~~~>  sci.philosophy.tech       b  ~~~>  rec.arts.books
j  ~~~>  soc.culture.jewish        h  ~~~>  rec.humor
pol ~~>  talk.politics             rel ~~>  talk.religion
ph ~~~>  sci.physics               u  ~~~>  comp.unix
a  ~~~>  alt                       A  ~~~>  rec.arts
@end example

@node examples index, examples reply, examples start, examples
@appendixsec Index hooks

I like to have @kbd{i} and @kbd{I} to scroll the index buffer when I'm
in the regular news buffer.

@example
(defun scroll-index-window-back (pfx arg)
@findex scroll-index-window-back*
  (interactive "P\np")
  (if pfx (scroll-other-window (- arg))
    (scroll-other-window (- 3 index-pop-up))))

(defun group:hook ()
@findex group:hook*
@kindex i*
@kindex I*
  (define-key group-mode-map "i" 'scroll-other-window)
  (define-key group-mode-map "I" 'scroll-index-window-back))

(defun article:hook ()
@findex article:hook*
  (define-key article-mode-map "i" 'scroll-other-window)
  (define-key article-mode-map "I" 'scroll-index-window-back))
@end example

The following is the second quickest way to read @t{talk.bizarre},
@t{misc.headlines}, @t{soc.singles} and other large newsgroups.

@example
(defun index-name-sort-prep (h)
@findex index-name-sort-prep*
  "Prepare current line for index sorting via the
user name field."
  (cons h (downcase (substring
                     (concat (reply-domain
                              (substring h 49))
                             (make-string 32 ? ))
                     0 32))))

@group
(defun index-name-ignore ()
@findex index-name-ignore*
  "Move forward to the next user name; mark this user
as \"ignored\".  That is, the article is not junked,
but the index motion commands will skip over it."
  (interactive)
  (beginning-of-line)
  (let ((user (buffer-substring (+ (point) 49)
                                (+ (point) 78)))
        goal-column)
    (setq buffer-read-only)
    (re-search-forward "\\([0-9]\\)[^0-9]")
    (replace-match "\\1i")
    (beginning-of-line)
    (forward-line 1)
    (while (and (not (eobp))
                (looking-at (concat "^\\(.....\\)  \\("
                                    (make-string 42 ?.)
                                    (regexp-quote user)
                                    "\\)")))
      (replace-match "\\1i \\2")
      (forward-line 1))
    (setq buffer-read-only t))
  (beginning-of-line))
@end group
@end example


@node examples reply, examples mail, examples index, examples
@appendixsec Reply hooks

I use a modification of @code{article-to} that offers three hopefully
reasonable mail addresses to choose from.

@example
(defun article-to-3 ()
@findex article-to-3*
  "Return string to be used for To: field.  (consists of 3 Tos)"
  (let ((from (article-field "From"))
        (repto (article-field "Reply-To" "Reply-Path")))
    (concat (article-field "Path") "\nTo: "
            (substring from 0 (if (string-match "[ \t]" from)
                                  (match-beginning 0)))
            "\nTo: "
            (substring repto 0 (if (string-match "[ \t]" repto)
                                   (match-beginning 0))))))
@end example

When I start a reply, I rebind @t{0} through @t{3} to the following
function, for easy choosing between the three addresses.  Note the
binding of @kbd{C-c C-s} etc at the end: my reply initialization rebinds
the send functions to error messages, so that I don't annoy someone
with three copies.  Naturally I get rid of the error message once
I've reduced the three @t{To:}s to one.

@example
(defun reply-to-choose (j)
@findex reply-to-choose*
  "If invoked with 1, 2, or 3, that (in numerical sequence)
\"To:\" field is kept, the other two are deleted, and 0-3 are
rebound.  If invoked with 0, the keys 0-3 are rebound."
  (interactive (list (string-to-char (this-command-keys))))
  (save-excursion
    (goto-char 1)
    (let ((i ?1))
      (if (/= j ?0)
          (while (< i ?4)
            (if (= i j)
                (forward-line 1)
              (gnews-delete-line))
            (setq i (1+ i))))))
  ;; back to normal
  (mapcar '(lambda (x)
             (delq (assoc x (current-local-map))
                   (current-local-map)))
          '(?0 ?1 ?2 ?3))
  (define-key (current-local-map) "\C-c\C-s" 'reply-send)
  (define-key (current-local-map) "\C-c\C-c" 'reply-return))
@end example

I set more basics in @code{reply:start:hook}.  My fancy signature is to
read in from my directory of signatures.  I don't reset the variables
on each pass.  I do reset @code{article-to}, since I often reload the
Gnews files while programming Gnews, so this personal customization
can get lost.

@example
(defun reply:start:hook ()
@findex reply:start:hook*
  (if (featurep 'reply-mode) nil
    ;; first time through:
    (load "hyphen" nil t)        ; my own package--primitive
    (setq e-reply-signature-prefix-pointers '(0 1 4 16)
          n-reply-signature-prefix-pointers '(0 nil nil 1)
          reply-signature-separator ""
          reply-signature-default-major "~/s/1"
          reply-signature-default-minor '(nil . signature:hook)
          n-reply-program nil)
    (provide 'reply-mode))
  (fset 'article-to 'article-to-3))

(defun signature:hook ()
@findex signature:hook*
  (read-file-name "Signature file: " "~/s/" "~/s/1" t))

(defun reply:hook ()
@findex reply:hook*
  (goto-char 1)
  (cond ((and (looking-at "^To: ")
              (not (gnews-digest-p))
              (not (eq this-command 'e-reply-toggle))
              (not (eq this-command 'group-forward-article)))
         (reply-to-simplify)
         (mapcar '(lambda (x)
                    (define-key (current-local-map)
                      x 'reply-to-choose))
                 '("0" "1" "2" "3"))
         (if (eq major-mode 'n-reply-mode) nil
           (define-key (current-local-map) "\C-c\C-s"
             '(lambda () (interactive)
                (error "123 Choose a \"To:\" field")))
           (define-key (current-local-map) "\C-c\C-c"
             '(lambda () (interactive)
                (error "123 Choose a \"To:\" field"))))
         (message "type 1 2 or 3 to select path, 0 to cancel")))
  (setq fill-column 72)
  (forward-paragraph)
  (forward-line 1))
@end example

I have a supply of old signatures that refer to @file{brahms} and not
@file{garnet}, so I fix them here, just before sending.

@example
(defun reply:send:hook ()
@findex reply:send:hook*	
  (reply-fluff)             ; clear off trailing white space
  (if (marker-position reply-signature-marker)
      (save-excursion
        (goto-char reply-signature-marker)
        (replace-regexp "\\([@@!]\\)brahms" "\\1garnet"))))
@end example

I do cancelling and superseding, like my posting, via NNTP internals.

@example
(defun cancel:hook ()
@findex cancel:hook*
  (setq n-reply-program nil))
@end example

The following two hooks set up a specialize mode appropriate for
Emacs replies.  I simply combine Emacs Lisp mode with Reply mode.
So I can type in code, indent it correctly, and send it, without
switching back and forth between the two modes.

This technique would work with something like C mode, but not with
something like Picture mode, which is heavily @kbd{C-c} dependent.

@example
(defun n-reply-emacs:hook ()
@findex n-reply-emacs:hook*
  (run-hooks emacs-lisp-mode-hook)
  (if (boundp 'n-reply-emacs-mode-map) nil
    (setq n-reply-emacs-mode-map
          (append (gnews-copy-keymap n-reply-mode-map)
                  (cdr emacs-lisp-mode-map))))
  (use-local-map n-reply-emacs-mode-map)
  (lisp-mode-variables)
  (setq mode-name "N-Reply|Emacs-Lisp"))

@group
(defun e-reply-emacs:hook ()
@findex e-reply-emacs:hook*
  (run-hooks emacs-lisp-mode-hook)
  (if (boundp 'e-reply-emacs-mode-map) nil
    (setq e-reply-emacs-mode-map
          (append (gnews-copy-keymap e-reply-mode-map)
                  (cdr emacs-lisp-mode-map))))
  (use-local-map e-reply-emacs-mode-map)
  (lisp-mode-variables)
  (setq mode-name "E-Reply|Emacs-Lisp"))
@end group
@end example

And finally, here are two versions for adding entries to my path
aliasing database.

@example
(defun path-hops-add (uucpname shortcut)
@findex path-hops-add*
  "Add a path to a UUCP site to the paths database."
  (interactive "ssite: \nspath to: ")
  (with-string-as-buffer "" nil
    (emacs-lisp-mode)
    (insert-file address-file)
    (search-forward "path-hops")
    (forward-line 1)
    (end-of-line)
    (newline-and-indent)
    (insert "(" uucpname " . \"" shortcut "\")")
    (eval-current-buffer)
    (write-file address-file)))

(defun path-arpa-add (uucpname)
@findex path-arpa-add*
  "Add a UUCP ==> ARPA dotted pair to my database."
  (interactive "sUUCP: ")
  (let ((arpaname (path-arpa-get-name uucpname)))
    (with-string-as-buffer "" nil
      (emacs-lisp-mode)
      (insert-file address-file)
      (search-forward "path-arpa")
      (forward-line 1)
      (end-of-line)
      (newline-and-indent)
      (insert "(" uucpname " . \"" arpaname "\")")
      (eval-current-buffer)
      (write-file address-file))))

(defun path-arpa-get-name (uucp)
@findex path-arpa-get-name*
  (read-string "domainized address: "))
@end example

@node examples mail, examples baud, examples reply, examples
@appendixsec Mail hooks

Here are some rewrites from long long ago to make Mail mode a bit more
like Reply mode.  Note that I require @file{prims.el} and @file{mail.el} in
my Mail mode hooks, but no other files, from Gnews.

Someday I'd like to bodily incorporate Rmail into Gnews, by
means of a hierarchy @t{mbox.*} of pseudo-newsgroups.

@example
(defconst mail-signature-default-prefix-pointers '(0 1 4 16))
@vindex mail-signature-default-prefix-pointers*

(defun mail-yank-original ()
@findex mail-yank-original*
  "Insert the message being replied to, if any (within rmail).
Puts point before the text and mark after.
==> Modified to indent original with reply-prefix. <=="
  (interactive)
  (if mail-reply-buffer
      (let ((start (point)))
        (delete-windows-on mail-reply-buffer)
        (insert-buffer mail-reply-buffer)
        (mail-yank-clear-headers start (mark))
        (save-excursion
          (goto-char (point-max))
          (delete-blank-lines))
        (beginning-of-line)
        (gnews-delete-paragraph)
        (gnews-delete-line)
        (while (and (not (eobp)) (looking-at "^"))
          (insert reply-prefix)
          (forward-line 1))
        (exchange-point-and-mark)
        (if (not (eolp)) (insert ?\n)))))

(defun mail-send-and-exit (arg)
@findex mail-send-and-exit*
  "Send message like mail-send.  If no errors, exit from mail buffer.
==> See documentation of variable mail-signature-defaults for
==> meaning of prefix argument and resulting signature."
  (interactive "*p")
  (cond ((mail-send arg)
         (bury-buffer (current-buffer))
         (if (eq (next-window (selected-window)) (selected-window))
             (switch-to-buffer (other-buffer (current-buffer)))
           (delete-window)))))

(defun mail-send (&optional arg)
@findex mail-send*
  "Send the message in the current buffer.
If  mail-interactive  is non-nil, wait for success indication
or error messages, and inform user.
Otherwise any failure is reported in a message back to
the user from the mailer.
==> See documentation of variable mail-signature-defaults for
==> meaning of prefix arguments and resulting signature."
  (interactive "*p")
  (let ((s-pair (reply-signature-default-pair
                  arg mail-signature-default-prefix-pointers)))
    (if s-pair (progn
                 (reply-signature nil s-pair)
                 (run-hooks 'mail-send-hook))))
  (goto-char (point-max))               ; put it at the bottom
  (sit-for 0)
  (forward-line -1)
  (recenter -1)
  (cond ((y-or-n-p "Send? ")            ; confirm first
         (message "Sending...")
         (funcall send-mail-function)
         (delete-auto-save-file-if-necessary)
         (if (eq major-mode 'mail-mode) (setq mail-was-sent t))
         (set-buffer-modified-p nil)
         (message "Sending...done"))))

(defun mail:hook ()
@findex mail:hook*
  (require 'gnews-prims "prims")
  (require 'gnews-mail "mail")  ; get Gnews mail compatibles
  (require '=/mail)             ; get personal mail rewrites
  (make-local-variable 'mail-was-sent)
  (setq mail-was-sent nil
        buffer-offer-save nil
        mail-send-hook 'reply:send:hook
        reply-signature-default '(nil . signature:hook))
  (define-key mail-mode-map "\^c\^i" 'reply-indent)
  (define-key mail-mode-map "\^c\^o" 'reply-split-line)
  (define-key mail-mode-map "\^c\^p" 'reply-path-alias)
  (define-key mail-mode-map "\^c\^t" 'reply-to-simplify)
  (define-key mail-mode-map "\^c\^w" 'reply-signature))
@end example

@node examples baud, examples misc, examples mail, examples
@appendixsec Slow baud rates

Gnews was developed, first with 9600 baud terminals, and then inside
an X Windows environment (with an effectively infinite baud rate).  So
I've had a blind spot to folks using 2400 baud or less.  Here follows
some changes and hooks to help.
@cindex baud rates

@example
(defun gnews:start:hook ()
@findex gnews:start:hook*
  (setq slow-baud-rate (< (baud-rate) 9600))
  (setq article-display-count (if slow-baud-rate 12)
        index-show-p (not slow-baud-rate)
        article-header-ignore
        (append '(Lines Organization Reply-To Message-ID
                  Keywords References Distribution)
                article-header-ignore)))
@end example

@node examples misc, , examples baud, examples
@appendixsec Miscellany

Penn State machines have trouble getting the line count, so I insert a
bogus version that Gnews will ignore.  I can't count the lines myself,
since I don't read in the whole article until later.  I also cut off
the subject line at column 79, as it looks ugly when it wraps.  And
finally, I like to clean up some of the more common mistaken or ugly
name fields that I see around.

@example
(defun article:header:tweak (field string)
@findex article:header:tweak*
  (setq string (gnews-replace "Tim Maroney" "Captain Carnage"
                  (gnews-replace "Bruce Edwards" "Ken Jenkins"
                     (gnews-replace "Patricia Roberts" "Trish Robbins"
                        (gnews-replace "(Doug Gwyn.*)" "(Doug Gwyn)"
                           string)))))
  (cond ((and (string= field "Lines")
              (string-match "@@PSUVM" (article-field "From")))
         (concat "PSU-" string))
        ((and (string= field "Subject")
              (< 70 (length string)))
         (substring string 0 70))
        (t string)))
@end example

Here is my modified @kbd{C-x C-c}, along with an extra defun required
so that I can now exit without running Gnews first!

@example
(defun save-buffers-kill-emacs-clean-up (&optional arg)
@findex save-buffers-kill-emacs-clean-up*
  (interactive "P")
  (if (y-or-n-p "Really exit? ")
      (progn
        (mapcar '(lambda (b)
                   (set-buffer b)
                   (if (string= mode-name "RMAIL") (rmail-quit)))
                (buffer-list))
        (if (nntp-run-p) (news-quit t))
        (save-buffers-kill-emacs arg))))

(defun nntp-run-p ())
@end example

The current @code{news-new} function is ugly.  Ashwin Ram recommends
the following.  It has what I consider a drawback: your @file{.gnewsrc}
will consist of all the newsgroups at your site.

@example
(defun news-new ()
@findex news-new*
   "Add all available newsgroups to your .gnewsrc."
   (interactive)
   (message "Checking new newsgroups...")
   (let ((default news-default-command))
      (roster-string-set)
      (news-add
        (delq nil (mapcar
                   (function (lambda (g)
                               (if (not (assoc
                                         (car g) group-roster))
                                   g)))
                   (roster-all)))
        "Checking new newsgroups... done"
        (function (lambda (g) (ignore g) t)))
      (setq news-default-command default))
   (if (string= news-default-command 'news-yes)
       (message "Checking new newsgroups... done [%s] ? " group-current)
     (message "Checking new newsgroups... done [ynp] ? ")))
@end example


@page
@node install, Info Index, examples, Top
@appendix How to install Gnews

The latest released version of Gnews will, for the forseeable future,
be made available by anonymous ftp from @t{ucbvax.berkeley.edu}.

Gnews should have come with 16 source files and 4 read files.  They are:
@itemize @bullet
@item
@file{Help.el} @file{Init.el} @file{NNTP.el} @file{Roster.el}
@item
@file{Spool.el} @file{art.el} @file{digest.el} @file{entry.el}
@item
@file{group.el} @file{hook.el} @file{index.el} @file{mail.el}
@item
@file{news.el} @file{prims.el} @file{reply.el} @file{utils.el}
@item
@file{==README} @file{=RN-5.0} @file{=CHANGES-1} @file{=MANUAL}
@end itemize
@pindex Gnews source

@file{Init.el} is the initializing file for all of Gnews; this is the file
users must load in order to run Gnews.  When byte-compiling, you must first
load @file{prims.el} first.  Certain key macros are defined there.
@pindex Init.el
@cindex byte-compile

For easiest installation (and re-installation), do not change any of the
files.  Instead, create a @file{site.el} file which sets the site-dependent
variables, load @file{Init.el}, and then perhaps redefines functions to
taste, say from a bug-fix.
@pindex site.el

@file{==README} is roughly this chapter of the manual, separated out for
those without a manual yet.  @file{=RN-5.0} is an old Larry Wall description
of the in-progress status of the next revision of his @t{rn} program.
@file{=CHANGES-1} is the (cryptic) log of changes in Gnews versions 1.@t{*}.
@file{=MANUAL} is the texinfo source for the Gnews manual, which can be
turned into both the printed manual and the on-line Info file.  @xref{manual, ,
Manual Generation}.

@menu
* portability::		Unix portability
* site-depend::		Site dependencies
* byte-compile::	Byte compiling Gnews
* manual::		Creating the manual
@end menu

@node portability, site-depend, , install
@appendixsec Unix portability

Gnews requires GNU Emacs to be version 18.45 or higher.

Gnews works on BSD 4.@{2,3@} and related systems since its internals rely
on sockets, namely the function @code{open-network-stream}.
@tindex open-network-stream

So far, Gnews has worked, usually without any problems, on a VAX 8800
under Ultrix V2.0, a VAX 750 under BSD 4.3, an RT under 4.2a ACIS, a
Sun 3/50 under Sun 4.2, an Apollo DN3000 running DOMAIN/IX, and an
Alliant FX/8 running Concentrix 3.0, all with GNU Emacs versions from
18.49 to 18.51.

It has been successfully ported, with changes in the Emacs C code, but
no change in any of Gnews' Lisp, to an Altos SysV using EXOS TCP/IP to
implement @code{open-network-stream}.

The most common problem involves sites not having set up their pseudo-ttys
or their local networking correctly.  Ask your local wizard for help.

@node site-depend, byte-compile, portability, install
@appendixsec Site dependencies

The standard site-dependent variables are at the top of @file{Init.el}.
You either adjust them there, or in a @file{site.el} file.

A few variables might need to be tinkered with for replying, although
they are often correct as is.  @xref{reply, , Replying}.

@table @code
@item gnews-spool-machine
@vindex gnews-spool-machine
This only matters to NNTP users.  It is the name of the machine you
will remotely read news from.  The string @t{"your.nntp.host"} should
be changed to its name.
@item nntp-service
@vindex nntp-service
Spool users, that is, those who plan to read news directly off of
a news spool, must set this to @code{nil}.  A few NNTP users have to
change this from the string @t{"nntp"} to the @emph{number} @t{119}.
@item gnews-organization
@vindex gnews-organization
The name of your organization.
@item gnews-machine
@vindex gnews-machine
The name of your machine as it should appear in a @t{From:} field.
The default is whatever @kbd{(system-name)} returns.
@item path-host
@itemx path-service
@vindex path-host
@vindex path-service
This is a host that carries the ``@t{uucp-path}'' service.  See
@cite{RFC 915} for the details.  This probably doesn't exist on
your machine.
@item gnews-bug-address
@vindex gnews-bug-address
An address to mail bug reports to, which will probably be my
address.  If your mailer groks domains, then you should not need
to change this.
@end table

The variable @code{gnews-code-directory} is set up, just before the
autoloads at the end of @file{Init.el}, by an ugly hack.  If it does
not work for you, just set it directly.  Note that the name is not
really a directory but the string giving the initial part of the
full paths of all the Gnews files.  For example, if you install
the Gnews files as @file{/a/b/c/gnews-*.el}, the correct value
for @code{gnews-code-directory} is the string @t{"/a/b/c/gnews-"}.
@vindex gnews-code-directory

Some machines/operating systems, like the Apollo DN3000 under SV9, have
timing errors inside @code{gnews-accept-process-output} that cause Gnews
to hang.  The current workaround is to avoid byte-compiling that function,
say by changing the source's @code{defun} into a quoted @code{fset}.  See
the source comments in @file{NNTP.el}.  This problem seems to have gone
away in the DN4000 running SV10.
@tindex gnews-accept-process-output
@cindex bugs

@node byte-compile, manual , site-depend, install
@appendixsec Byte compiling Gnews

@strong{Important note} about byte-compiling the Gnews source:

I said it up above, but it's worth saying again:

@itemize @bullet
@item
First load @file{prims.el}.
@item
Then byte-compile!
@end itemize

(This applies not just to installation, but any time you byte-compile
one of the Gnews files.)
@cindex byte-compile

More explicitly, this means you should run the following sequence of
commands, assuming that you are in the @file{gnews} directory and you
are installing the files for the first time:

@table @kbd
@item M-x load-file @key{RET} prims.el @key{RET}
@itemx C-u M-x byte-recompile-directory @key{RET} y y y y @dots{}
That's sixteen @kbd{y}s in a row, one for each Gnews file.  You
can type them all at once, or you can wait until Emacs asks you
on a per-file basis.
@end table

During update installations within the same directory, you do not need
the @kbd{C-u} if you do not remove the old @code{.elc} files.  See the
documentation for @code{byte-recompile-directory}.

@node manual, , byte-compile, install
@appendixsec Creating the manual

The raw form of the manual is the file @file{=MANUAL}.  It is in @dfn{texinfo}
format, a narrowly constrained @TeX{} style that is also recognized by
Emacs as a way of generating its Info files.

@menu
* tex::		TeX printed version
* info::	Info guide version
@end menu

@node tex, info, , manual
@appendixsubsec @TeX{} printed version

To convert from texinfo to @TeX{}, run @TeX{} on the file twice.  You
will need a copy of the @file{texinfo.tex} macro package, which should
have come with you Emacs source and put in your @TeX{} macro directory.
The first time through, numerous warning messages will appear, as @TeX{}
generates internal references, plus index information.  The second time
through, these references will be known.  The index needs to be sorted;
for this, use the program @file{texindex.c}.  I recommend two-sided copies.

The sequence of operations is thus something like:
@example
% cp =MANUAL /tmp/gnews.tex
% pushd /tmp
% tex gnews.tex
% texindex gnews.??
% tex gnews.tex
% dvipr -d gnews.dvi
% rm gnews.*
% popd
@end example

There is a bug in the way @TeX{} goes back and forth between single and
double column mode; the resulting index is less esthetic than I'd like,
but I suspect it will go away when I add enough index entries.

@node info, , tex, manual
@appendixsubsec Info guide version

This normally requires making changes in your site's Info directory.  If
you don't have write permission for the Emacs Info directory, you can fake
it as follows.  Create your own Info directory.  Copy the true @file{dir} to
it.  Make symbolic links to the rest of the true Info directory's contents.
In your @file{.emacs} put @samp{(setq Info-directory "/my/home/dir/info/")} or
similar ASCII characters to that effect.

To convert from texinfo to Info, visit @file{=MANUAL} in some buffer.  Be
sure that there is no narrowing.  Execute @kbd{M-x texinfo-format-buffer}.
Put a menu item for Gnews into the @file{dir} file.  I recommend
@example
* Gnews: (gnews).@ @ @ @ @ The Gnews news reader/poster/mailer.
@end example

This assumes that the info directory is in some neighbor directory to the
Info directory.  If it isn't, change the @kbd{@@setfilename ../info/gnews}
line, at the very top of the @file{=MANUAL} file, as appropriate before
doing the above.

@cindex manual

@page
@node Info Index, , install, Top
@unnumbered Indices

Note: a *-ed entry is one that is in the manual by way of example only.

@menu
* key:Key Index.		Key Index
* function:Function Index.	Command and Function Index
* variable:Variable Index.	Variable Index
* internals:Internals Index.	Internals Index 
* program:Program Index.	File, Buffer, and Program Index
* concept:Concept Index.	Concept Index 
@end menu

@node Key Index, Function Index, , Info Index
@unnumberedsec Key Index
@iftex
@sp 1
@end iftex
@printindex ky

@node Function Index, Variable Index, Key Index, Info Index
@unnumberedsec Command and Function Index
@iftex
@sp 1
@end iftex
@printindex fn

@node Variable Index, Internals Index, Function Index, Info Index
@unnumberedsec Variable Index
@iftex
@sp 1
@end iftex
@printindex vr

@node Internals Index, Program Index, Variable Index, Info Index
@unnumberedsec Internals Index
@iftex
@sp 1
@end iftex
@printindex tp

@node Program Index, Concept Index, Internals Index, Info Index
@unnumberedsec File, Program, and Buffer Index
@iftex
@sp 1
@end iftex
@printindex pg

@node Concept Index, , Program Index, Info Index
@unnumberedsec Concept Index
@iftex
@sp 1
@end iftex
@printindex cp

@ignore
@node Table-Of-Contents, , , (DIR)
@end ignore

@iftex
{@finishcontents
@unnumbchapmacro{Summary Table of Contents}
@catcode`@\=0
@catcode`@#=6
@catcode`@@=11
\def\thischapter{Summary Table of Contents}
\def\smallbreak{}
\def\secentry #1#2#3#4{}
\def\subsecentry #1#2#3#4#5{}
\def\subsubsecentry #1#2#3#4#5#6{}
\def\unnumbsecentry #1#2{}
\def\unnumbsubsecentry #1#2{}
\let\medbreak=\smallbreak
\input \jobname.toc
\vfill \eject}
@contents
@end iftex

@bye

@c	Local Variables:
@c	TeX-zap-file:"gnews-man"
@c	auto-save-interval:0
@c	End:

@ignore
Tag table:
Node: Top▶7f◀1942
Node: preface▶7f◀2644
Node: License▶7f◀4111
Node: Copying▶7f◀5614
Node: NO WARRANTY▶7f◀9168
Node: usenet▶7f◀10530
Node: emacs▶7f◀13864
Node: start▶7f◀14913
Node: help▶7f◀18346
Node: documentation▶7f◀18632
Node: bug reports▶7f◀20394
Node: news▶7f◀21756
Node: news motion▶7f◀23196
Node: news get▶7f◀25967
Node: gnewsrc▶7f◀28484
Node: news enter▶7f◀30181
Node: news abbrev▶7f◀31816
Node: news misc▶7f◀34677
Node: group▶7f◀36855
Node: defnext▶7f◀40922
Node: motion▶7f◀43413
Node: pattern▶7f◀45238
Node: artget▶7f◀47151
Node: quit▶7f◀49104
Node: scroll▶7f◀50296
Node: restart▶7f◀51826
Node: rot13▶7f◀52755
Node: edit▶7f◀53860
Node: junk▶7f◀55232
Node: grep▶7f◀57341
Node: save▶7f◀58849
Node: group misc▶7f◀60989
Node: reply▶7f◀62184
Node: original▶7f◀64506
Node: replace▶7f◀67514
Node: reply start hooks▶7f◀68920
Node: format▶7f◀70179
Node: indent▶7f◀72294
Node: art headers▶7f◀74672
Node: mail headers▶7f◀78812
Node: reply misc▶7f◀84826
Node: send▶7f◀86099
Node: signatures▶7f◀87916
Node: index▶7f◀95395
Node: index motion▶7f◀97866
Node: index flag▶7f◀99885
Node: index misc▶7f◀102669
Node: index custom▶7f◀104242
Node: index conditional▶7f◀108229
Node: hook-kill▶7f◀110015
Node: hook-theory▶7f◀111350
Node: hook-examples▶7f◀115085
Node: hook-edit▶7f◀123131
Node: digest▶7f◀129155
Node: digest mode▶7f◀130809
Node: digest only▶7f◀133945
Node: digest mixed▶7f◀135758
Node: features▶7f◀140088
Node: summary▶7f◀141187
Node: % formats▶7f◀145699
Node: environ▶7f◀151692
Node: flags▶7f◀155400
Node: bugs▶7f◀155481
Node: customize▶7f◀159421
Node: rebinding keys▶7f◀160233
Node: user variables▶7f◀163754
Node: function hooks▶7f◀168687
Node: little functions▶7f◀172877
Node: internals▶7f◀175735
Node: examples▶7f◀178961
Node: examples start▶7f◀179837
Node: examples abbrev▶7f◀181149
Node: examples index▶7f◀181879
Node: examples reply▶7f◀183994
Node: examples mail▶7f◀190617
Node: examples misc▶7f◀194171
Node: install▶7f◀195456
Node: portability▶7f◀197286
Node: site-depend▶7f◀198199
Node: byte-compile▶7f◀200626
Node: manual▶7f◀201451
Node: tex▶7f◀201793
Node: info▶7f◀202559
Node: Info Index▶7f◀203272
Node: Key Index▶7f◀203688
Node: Function Index▶7f◀203799
Node: Variable Index▶7f◀203941
Node: Internals Index▶7f◀204077
Node: Program Index▶7f◀204213
Node: Concept Index▶7f◀204364
Node: Table-Of-Contents▶7f◀204483

End tag table
@end ignore
DataMuseum.dk

DKUUG/EUUG Conference tapes

⟦a4e343b3d⟧ TextFile

Derivation

TextFile
