Commits

Anonymous committed cdedb0d

converted from .html with ../html2content.pl

Comments (0)

Files changed (6)

+2000-09-13  Adrian Aichner  <aichner@ecf.teradyne.com>
+
+	* tutorials_1.content: Converted from .html with
+	xemacsweb/html2content.pl
+	* tutorials_2.content: Ditto.
+	* tutorials_3.content: Ditto.
+	* tutorials_foot.content: Ditto.
+	* tutorials_toc.content: Ditto.
+
 2000-08-18  Adrian Aichner  <aichner@ecf.teradyne.com>
 
 	* customization.content: Remove empty lines in genpage content

Links/tutorials_1.content

+%title%
+A Collection of Tutorials on Emacs - Indentation
+%author%
+Adrian Aichner, original author Kai Grossjohann
+%main%
+
+    Go to the first, previous, <A HREF="tutorials_2.html">next</A>, <A HREF="tutorials_3.html">last</A> section, <A HREF="tutorials_toc.html">table of contents</A>.
+    <P><HR><P>
+
+
+    <H1><A NAME="SEC1" HREF="tutorials_toc.html#TOC1">Indentation</A></H1>
+
+
+
+    <H2><A NAME="SEC2" HREF="tutorials_toc.html#TOC2">Basic Concepts</A></H2>
+    <P>
+      <A NAME="IDX1"></A>
+
+
+    <P>
+      There are quite a few concepts in Emacs which relate to white space at
+      the beginning of a line.  Enough, in fact, to be potentially quite
+      confusing.  I'll try to clear up the confusion in this little
+      document.  The following concepts come into play:
+
+
+
+
+    <H3><A NAME="SEC3" HREF="tutorials_toc.html#TOC3">The <KBD>TAB</KBD> key.</A></H3>
+
+    <P>
+      Contrary to popular belief, the <KBD>TAB</KBD> key does not insert a tab
+      character in most modes.  Instead, it does syntax-driven indentation in
+      most programming language modes.  In fundamental mode, it advances to
+      the next tab stop.  In text mode, it does relative indentation (relative
+      to the previous line, that is).  You can type <KBD>C-q <KBD>TAB</KBD></KBD> to
+      insert a tab character.
+
+
+
+
+    <H3><A NAME="SEC4" HREF="tutorials_toc.html#TOC4">The tab character.</A></H3>
+
+    <P>
+      It is possible to change the way a tab character is displayed.
+      <SAMP>`vi'</SAMP> users do this.  For example, they can set the width of a tab
+      character to 4, and this enables them to hit <KBD><KBD>TAB</KBD></KBD> at the
+      beginning of a line to indent the body of a loop, say, by one
+      indentation step (of 4 characters).  Normally, the width of tab is eight
+      characters, so a file created by a <SAMP>`vi'</SAMP> user with a tab width of 4
+      will look different when viewed in a program which uses the default tab
+      width setting.
+
+
+    <P>
+      In order to correctly view files with non-standard tab width
+      settings, it is possible to set the variable <CODE>tab-width</CODE>, like this:
+
+
+
+    <PRE>
+(setq-default tab-width 4)
+    </PRE>
+
+    <P>
+      If you only want this in a particular mode, add <CODE>(setq tab-width
+	4)</CODE> to that mode's hook.  (See below for an explanation of mode hooks.)
+
+
+
+
+    <H3><A NAME="SEC5" HREF="tutorials_toc.html#TOC5">Whether or not tab characters are used for indentation.</A></H3>
+
+    <P>
+      Whether by syntax-driven indentation, or relative indentation (text
+      mode), or advancing to the next tab stop (fundamental mode), indentation
+      needs to insert white space.  The variable <CODE>indent-tabs-mode</CODE>
+      controls whether or not tab characters are used for inserting the white
+      space.  If this variable is <CODE>t</CODE>, tab characters are used to make
+      the file as short as possible.  For example, if <CODE>tab-width</CODE> is
+      equal to 4 and white space of 10 characters needs to be inserted at the
+      beginning of the line, Emacs will insert 2 tab characters (2 times 4
+      equals 8 spaces), plus two space characters.  With <CODE>tab-width</CODE>
+      equal to the default value of 8, Emacs would insert 1 tab plus 2 spaces.
+
+
+    <P>
+      Use the following line to tell Emacs to never use tab characters for
+      indentation:
+
+
+
+    <PRE>
+(setq-default indent-tabs-mode nil)
+    </PRE>
+
+    <P>
+      Use <CODE>t</CODE> rather than <CODE>nil</CODE> to tell Emacs to use tab characters
+      where appropriate.
+
+
+    <P>
+      If you only want this in a particular mode, add <CODE>(setq
+	indent-tabs-mode nil)</CODE> to that mode's hook.  (See below for an
+      explanation of mode hooks.)
+
+
+    <P>
+      By the way, actual tab characters are really needed in Makefiles;
+      thus, makefile mode overrides this setting.
+
+
+
+
+    <H3><A NAME="SEC6" HREF="tutorials_toc.html#TOC6">The location of the tab stops.</A></H3>
+
+    <P>
+      The variable <CODE>tab-stop-list</CODE> contains a list of tab stop positions,
+      and <KBD>M-i</KBD> moves to the next tab stop.  (In fundamental mode,
+      <KBD><KBD>TAB</KBD></KBD> also does this.)  You can define your own list with a
+      statement like the following:
+
+
+
+    <PRE>
+(setq tab-stop-list '(4 8 12 16))
+    </PRE>
+
+    <P>
+      Whether or not actual tab characters are inserted is controlled by
+      the variable <CODE>indent-tabs-mode</CODE>, and the number of tab characters
+      inserted is controlled by <CODE>tab-width</CODE> (among others).
+
+
+    <P>
+      Obviously, if you set <CODE>tab-stop-list</CODE> to a list containing multiples
+      of <CODE>tab-width</CODE>, then one <KBD>M-i</KBD> will insert one tab character at all
+      times (if <CODE>indent-tabs-mode</CODE> isn't <CODE>nil</CODE>).
+
+
+    <P>
+      The variable <CODE>tab-stop-list</CODE> controls which spots <KBD>M-i</KBD> moves
+      to, and <CODE>indent-tabs-mode</CODE> controls whether tab characters (plus
+      maybe a few space characters) are used to move to that spot, and
+      <CODE>tab-width</CODE> controls how many tab characters are needed.
+
+
+
+
+    <H3><A NAME="SEC7" HREF="tutorials_toc.html#TOC7">Syntax driven indentation.</A></H3>
+
+    <P>
+      This means that the current line is indented in a way that is useful for
+      the syntax of the programming language used.  For example, in C-like
+      languages, the lines between an opening and a closing brace are usually
+      indented two to four spaces with respect to the braces themselves.  In
+      Pascal, the lines between <CODE>begin</CODE> and <CODE>end</CODE> would be indented
+      two to four spaces.
+
+
+    <P>
+      Since the syntax driven indentation depends a lot on the syntax of the
+      programming language at hand, the major mode provides the indentation.
+      And customizing each major mode works a little differently, because the
+      programming languages are different.
+
+
+    <P>
+      For C-like languages, there is <TT>`CC mode'</TT>.  It provides major modes
+      for C, C++, Objective C, IDL, and Java.  The indentation engine is quite
+      flexible, and the CC mode info file has the whole story on customizing
+      indentation for these major modes.  I'll just mention a few things.
+
+
+    <P>
+      CC mode provides for different coding styles.  Type <KBD>M-x c-set-style
+	<KBD>RET</KBD></KBD>, then use tab completion to have a look at them, and try them
+      out.  If you find one you like, you can add something like
+      <CODE>(c-set-style "gnu")</CODE> to your mode hook.  These coding styles often
+      refer to a basic indentation offset, determined by the variable
+      <CODE>c-basic-offset</CODE>.  Add stuff like <CODE>(setq c-basic-offset 4)</CODE> to
+      the mode hook in question.
+
+
+    <P>
+      If this isn't sufficient, you can go to the line where you don't like
+      the indentation, and type <KBD>C-c C-o</KBD>.  Follow the prompts.  Hit
+      <KBD>TAB</KBD> to re-indent the current line.  Repeat until you like the
+      result.  You can then type <KBD>C-x <KBD>ESC</KBD> <KBD>ESC</KBD></KBD> and use
+      <KBD>M-n</KBD> and <KBD>M-p</KBD> to locate the right <SAMP>`c-set-offset'</SAMP>
+      statement to add to your hook.  Please note that you can enter numbers
+      for the indentation level, but you can also use <CODE>+</CODE> and <CODE>-</CODE> to
+      stand for one basic offset to the right or left, respectively, or
+      <CODE>++</CODE> and <CODE>--</CODE> for twice the basic offset.
+
+
+    <P>
+      I use <TT>`CPerl'</TT> mode for editing Perl code.  It also provides a style
+      mechanism similar to the one provided by CC mode, but it doesn't provide
+      an interactive command which allows one to customize indentation, like
+      <KBD>C-c C-o</KBD> in CC mode.  Type <KBD>C-h f cperl-mode <KBD>RET</KBD></KBD> for a
+      list of variables affecting indentation.  Choose an indentation style
+      which is closest to what you want, then change the remaining variables
+      from your mode hook.  You can choose an indentation style by adding
+      something like <CODE>(cperl-set-style "gnu")</CODE> to your mode hook.
+
+
+
+    <BLOCKQUOTE>
+      <P>
+	CCC Can people provide info for other modes?
+    </BLOCKQUOTE>
+
+
+
+    <H3><A NAME="SEC8" HREF="tutorials_toc.html#TOC8">Relative indentation.</A></H3>
+
+    <P>
+      This means indent to a spot indicated by the previous non-blank line.
+      Below, the spots relative indentation moves to are indicated with a
+      caret.
+
+
+
+    <PRE>
+    This is a line to show relative indentation.
+    ^    ^  ^ ^    ^  ^    ^        ^
+    </PRE>
+
+    <P>
+      I find this useful for text where it can be used to format tables or to
+      indent itemized lists.  When in text mode, the <KBD>TAB</KBD> key performs
+      relative indentation by default.  The command name is
+      <CODE>indent-relative</CODE>.
+
+
+
+
+    <H2><A NAME="SEC9" HREF="tutorials_toc.html#TOC9">Usage scenarios.</A></H2>
+
+    <P>
+      In the above, I explained the concepts behind the things Emacs is
+      doing, but I suspect you'd like some advice on when to frob which
+      options.
+
+
+
+
+    <H3><A NAME="SEC10" HREF="tutorials_toc.html#TOC10">I want to turn off syntax driven indentation!</A></H3>
+
+    <P>
+      Since <TT>`vi'</TT> doesn't have syntax driven indentation, its users usually
+      set the tab width to some value they like, and whenever they want to
+      indent a line more than the previous one, they hit <KBD>TAB</KBD>.  Of course,
+      a file which was edited in this way will look strange when loaded into
+      Emacs.  The variable <CODE>tab-width</CODE> was made for this, just set it to the
+      tab width your <TT>`vi'</TT> loving colleagues use, and you can continue to use
+      syntax driven indentation and your cow-orkers will wonder why you can
+      edit code so fast...
+
+
+    <P>
+      Perhaps you also want to set <CODE>indent-tabs-mode</CODE> to <CODE>t</CODE> (which
+      is the default) such that Emacs actually uses tabs with the new width.
+      But then, maybe you want to set it to <CODE>nil</CODE> such that Emacs uses
+      only spaces and the looks of your code won't depend on the tab width
+      setting somebody uses.
+
+
+    <P>
+      And you might need to customize your indentation to be similar to the
+      style used by the others, lest you need to do a lot of manual
+      reformatting.  A consistent coding style is a good thing.
+
+
+
+
+    <H2><A NAME="SEC11" HREF="tutorials_toc.html#TOC11">Background information.</A></H2>
+
+    <P>
+      This section provides background information referred to in the
+      above.
+
+
+
+
+    <H3><A NAME="SEC12" HREF="tutorials_toc.html#TOC12">Mode hooks.</A></H3>
+
+    <P>
+      A central concept in Emacs is the <EM>major mode</EM>.  For each kind of
+      text, a major mode provides functions useful in that mode.  Most (if not
+      all) major modes provide a so-called <EM>hook</EM> which allows you to
+      specify Lisp code to be run when that major mode is entered.  Most of
+      the time, this feature is used just for setting a few variables.
+
+
+    <P>
+      A <EM>mode hook</EM> is a variable which contains a list of functions to be
+      executed.  Thus, if you want something to happen, you have to write a
+      function first.  Writing functions is rather simple, finding a name for
+      the function might be the most difficult part, in fact!
+
+
+    <P>
+      So, let's say you wish to set the variable <CODE>c-basic-offset</CODE> to 3 when
+      in C++ mode.  Additionally, you want to use no tabs for indentation.
+      Here's a function which does this:
+
+
+
+    <PRE>
+(defun my-c++-indent-setup ()
+  (setq c-basic-offset 3)
+  (setq indent-tabs-mode nil))
+    </PRE>
+
+    <P>
+      Pay careful attention to the nesting of the parentheses.  The empty
+      pair of parentheses is always needed, and the parenthesis opened
+      before the word <CODE>defun</CODE> is closed at the very end of the function.
+
+
+    <P>
+      So, all that's left is to add this function to the mode hook for C++
+      mode.  Easy:
+
+
+
+    <PRE>
+(add-hook 'c++-mode-hook 'my-c++-indent-setup)
+    </PRE>
+
+    <P>
+      You may wish to replace the <SAMP>`my'</SAMP> prefix with something else such
+      that you can be sure not to reuse a function name already defined
+      elsewhere.  I use the prefix <SAMP>`kai'</SAMP>, for example.  This means I've
+      got to be careful when snarfing code from Kai-Uwe Rommel :-)
+
+
+
+
+    <H2><A NAME="SEC13" HREF="tutorials_toc.html#TOC13">TODO</A></H2>
+
+
+    <UL>
+      <LI>
+
+	file local variables for tab-width (Per Abrahamsen)
+    </UL>
+
+    <P><HR><P>
+      Go to the first, previous, <A HREF="tutorials_2.html">next</A>, <A HREF="tutorials_3.html">last</A> section, <A HREF="tutorials_toc.html">table of contents</A>.
+  

Links/tutorials_2.content

+%title%
+A Collection of Tutorials on Emacs - Key bindings
+%author%
+Adrian Aichner, original author Kai Grossjohann
+%main%
+
+    Go to the <A HREF="tutorials_1.html">first</A>, <A HREF="tutorials_1.html">previous</A>, <A HREF="tutorials_3.html">next</A>, <A HREF="tutorials_3.html">last</A> section, <A HREF="tutorials_toc.html">table of contents</A>.
+    <P><HR><P>
+
+
+    <H1><A NAME="SEC14" HREF="tutorials_toc.html#TOC14">Key bindings</A></H1>
+
+    <P>
+      Binding functions to keys is something most new users of Emacs probably
+      do rather soon.  This subject has also been discussed to quite some
+      extent in the FAQ, so be sure to look there as well as the chapter on
+      customizing key bindings in the Emacs manual.
+
+
+
+
+    <H2><A NAME="SEC15" HREF="tutorials_toc.html#TOC15">Online help for key bindings</A></H2>
+
+    <P>
+      A key binding is an association between a key (sequence) and a Lisp
+      command.  You can type <KBD>C-h c <VAR>x</VAR></KBD> to find out which command is
+      invoked by the key (sequence) <VAR>x</VAR> in the current major mode.  You
+      can get more help about <VAR>x</VAR> with <KBD>C-h k <VAR>x</VAR></KBD>.  You can type
+      <KBD>C-h w <VAR>f</VAR> <KBD>RET</KBD></KBD> to find out which key bindings exist for
+      the given function <VAR>f</VAR>.  Another very useful keybinding is <KBD>C-h
+	b</KBD> which gives you a list of all key bindings currently in effect.
+
+
+    <P>
+      So, maybe <KBD>C-h w</KBD> tells you that the function you want already has a
+      key binding, so you don't need your own?
+
+
+
+
+    <H2><A NAME="SEC16" HREF="tutorials_toc.html#TOC16">A warning about own key bindings</A></H2>
+
+    <P>
+      Of course, many people prefer their own key bindings rather than the
+      standard ones.  Since no two people work alike, it is a Good Thing that
+      Emacs allows you to choose your own bindings, of course.  However, a few
+      rules should be obeyed for choosing your own key bindings:
+
+
+
+    <UL>
+      <LI>
+
+	All key bindings of the form <KBD>C-c <VAR>x</VAR></KBD> where <VAR>x</VAR> is any
+	letter are reserved for the user.  This means that you can count on all
+	well-behaved packages not to clobber these bindings.  Please note that
+	bindings for non-letters might be used by major modes.  (AUC-TeX uses
+	<KBD>C-c ;</KBD> for <CODE>comment-region</CODE>, for instance.)  The bindings
+	<KBD>C-c C-<VAR>x</VAR></KBD> where <VAR>x</VAR> is a letter are reserved for the major
+	modes.
+
+      <LI>
+
+	Most control key combinations (such as <KBD>C-f</KBD>) and most meta key
+	combinations (such as <KBD>M-f</KBD>) are already used by Emacs.  A few modes
+	change the meanings of a few standard key bindings, so it is advisable
+	to stay away from the standard key bindings in the beginning, until one
+	gets a feel for the kinds of standard key bindings which are most
+	useful.
+
+	As an example, <KBD>M-a</KBD> normally moves backward a sentence, but in C
+	mode it moves backward a statement.
+
+	It might be best if you get into the habit of doing <KBD>C-h b</KBD> in the
+	major modes you use.
+    </UL>
+
+
+
+    <H2><A NAME="SEC17" HREF="tutorials_toc.html#TOC17">Simple key bindings</A></H2>
+
+    <P>
+      Even though the function in question might already have a key binding,
+      you may prefer your own, because it is more easily reachable on your
+      keyboard, say.  As an example, the following line makes it so that
+      <KBD>C-c f</KBD> invokes <CODE>forward-paragraph</CODE> in all modes:
+
+
+
+    <PRE>
+(global-set-key (kbd "C-c f") 'forward-paragraph)
+    </PRE>
+
+    <P>
+      It is also rather simple to establish key bindings for particular modes,
+      for instance:
+
+
+
+    <PRE>
+(define-key c-mode-map (kbd "C-c &#60;f1&#62;") 'mark-whole-buffer)
+    </PRE>
+
+    <P>
+      Some modes aren't loaded when Emacs starts.  This means that Emacs might
+      not know about the variable <CODE>c-mode-map</CODE> when it starts.  A simple
+      solution exists: just load the package before using the variable.  C
+      mode is defined in the <SAMP>`CC mode'</SAMP> package, so the following line
+      helps:
+
+
+
+    <PRE>
+(require 'cc-mode)
+    </PRE>
+
+    <P>
+      The normal rule is that <VAR>foo-mode</VAR> is defined in the package
+      <VAR>foo-mode</VAR> or possibly in <VAR>foo</VAR>.  The C-like modes are an
+      exception, they are defined in the package <CODE>cc-mode</CODE>.  You can type
+      <KBD>C-h f <VAR>foo-mode</VAR> RET</KBD> which will tell you which package the
+      function comes from.
+
+
+
+
+    <H2><A NAME="SEC18" HREF="tutorials_toc.html#TOC18">The syntax for <SAMP>`kbd'</SAMP></A></H2>
+
+    <P>
+      What kind of string should you use between the double quotes after
+      <SAMP>`kbd'</SAMP>?  Well, the syntax is not hard to figure out; explaining it
+      is a bit more difficult.  Well, anyway, here goes:
+
+
+    <P>
+      Basically, the syntax used by <SAMP>`kbd'</SAMP> is the same as the syntax used
+      by Emacs to describe key bindings (in <KBD>C-h c</KBD> and <KBD>C-h b</KBD>, among
+      other places), with one exception.  The exception concerns function key
+      names, which should be enclosed in angle brackets.  Compare <CODE>(kbd
+	"C-c &#60;f1&#62;")</CODE> used above: F1 is a function key and thus its name is
+      enclosed in angle brackets.  By the way, you write <CODE>C-&#60;f1&#62;</CODE> if you
+      want the <KBD>Ctrl</KBD> key to be pressed while hitting F1.
+
+
+    <P>
+      Why aren't <KBD>RET</KBD> and <KBD>SPC</KBD> enclosed in angle brackets?  Well,
+      even though it might look as if they are function keys, we're really
+      talking about ASCII character, here.  A few ASCII characters aren't
+      printable and thus there are three-letter names for them: <KBD>RET</KBD>
+      (ASCII 13), <KBD>DEL</KBD> (ASCII 127), <KBD>LFD</KBD> (ASCII 10), <KBD>SPC</KBD>
+      (ASCII 32), <KBD>ESC</KBD> (ASCII 27) and <KBD>TAB</KBD> (ASCII 9).
+
+
+    <P>
+      In general, you can tell the symbolic name for an ASCII characters from
+      function key names by the case: function key names are lowercase, ASCII
+      characters have uppercase names.
+
+
+    <P>
+      Which leads us to the distinction between the ASCII key <KBD>RET</KBD> and
+      the function key <KBD>return</KBD>: On a serial terminal or using a terminal
+      emulation like <SAMP>`xterm'</SAMP>, Emacs cannot tell the difference between
+      the user hitting <KBD><KBD>return</KBD></KBD> and the user hitting <KBD>C-m</KBD>, so
+      there is only <KBD>RET</KBD>.  Changing the key binding for <KBD>RET</KBD> also
+      changes it for <KBD>C-m</KBD> and vice versa.  But if you are using a
+      windowing system (such as X11), Emacs does know the difference, and
+      makes it available to you.  One way to use it is to make <KBD>C-m</KBD>
+      behave different from <KBD><KBD>return</KBD></KBD>.  Another area where the
+      difference becomes important is with additional modifiers: <CODE>(kbd
+	"C-&#60;return&#62;")</CODE> makes perfect sense, but <CODE>(kbd "C-RET")</CODE> is not
+      meaningful since this would be the same as <CODE>(kbd "C-C-m")</CODE> which in
+      turn is clearly bogus--you cannot "double-press" the control key, so
+      <KBD>C-RET</KBD> is double-plus ungood.
+
+
+    <P>
+      Whee.  More complex than you thought, right?  On the other hand, most of
+      the time you don't need to know all this--just look at the output from
+      <KBD>C-h c</KBD> and remember to enclose function key names in angle
+      brackets, and Bob will be your uncle.  But there is one area where the
+      previous paragraph becomes important, because these keys are so often
+      used:
+
+
+
+
+    <H2><A NAME="SEC19" HREF="tutorials_toc.html#TOC19">The delete and backspace keys</A></H2>
+
+    <P>
+      Let's talk about windowing systems, first.  By default the <KBD>delete</KBD>
+      and <KBD>backspace</KBD> keys do the same thing: they generate the ASCII
+      character <KBD>DEL</KBD> which in turn is bound to
+      <CODE>backward-delete-char-untabify</CODE> in many modes.  But in quite a few
+      modes, <KBD>DEL</KBD> has a different binding which is normally useful.  For
+      example, in view mode, <KBD>DEL</KBD> is page-up, which is similar to the
+      Unix programs <SAMP>`more'</SAMP> and <SAMP>`less'</SAMP>, more or less.
+
+
+    <P>
+      Most people want the <KBD>backspace</KBD> key to delete backwards whereas the
+      <KBD>delete</KBD> key should delete forward.  But how to do that without
+      losing the useful <KBD>DEL</KBD> bindings?  Well, there are three potential
+      key bindings (<KBD>DEL</KBD>, <KBD>backspace</KBD>, <KBD>delete</KBD>) but only two
+      keys, so what you should do is to choose the right two key bindings, and
+      <KBD>DEL</KBD> should be among them.  The standard semantic of <KBD>DEL</KBD> is
+      vaguely "backward", so the natural thing to do is to let
+      <KBD>backspace</KBD> be <KBD>DEL</KBD> as is the default and to change the binding
+      of <KBD>delete</KBD>: <CODE>(global-set-key (kbd "&#60;delete&#62;") 'delete-char)</CODE>
+
+
+    <P>
+      If you don't like what the <KBD>backspace</KBD> key does, don't change its
+      binding directly.  Instead, change the binding for <KBD>DEL</KBD>:
+      <CODE>(global-set-key (kbd "DEL") 'backward-delete-char)</CODE>
+
+
+
+
+    <H2><A NAME="SEC20" HREF="tutorials_toc.html#TOC20">Binding <KBD>C-u <VAR>something</VAR></KBD> to a different key</A></H2>
+
+    <P>
+      <KBD>C-u</KBD> invokes <CODE>universal-argument</CODE>, which changes the behavior
+      of quite a few standard functions.  For example, in C mode the key
+      combination <KBD>C-c C-c</KBD> comments out the region.  For
+      <EM>uncommenting</EM> the region, you have to use <KBD>C-u C-c C-c</KBD>.
+
+
+    <P>
+      Thus, one question which comes up a few times is how to make the F9 key
+      do what <KBD>C-u C-c C-c</KBD> does.
+
+
+    <P>
+      Sadly, it is not as simple as one might think.  You have to use some
+      Lisp for this.  First, let's have a look what <KBD>C-c C-c</KBD> does in C
+      mode, so we type <KBD>C-h k C-c C-c</KBD>, which produces the following help:
+
+
+
+    <PRE>
+C-c C-c runs the command comment-region
+   which is an interactive compiled Lisp function in `simple'.
+(comment-region BEG END &#38;optional ARG)
+
+Comment or uncomment each line in the region.
+With just C-u prefix arg, uncomment each line in region.
+Numeric prefix arg ARG means use ARG comment characters.
+If ARG is negative, delete that many comment characters instead.
+Comments are terminated on each line, even for syntax in which
+newline does not end the comment.  Blank lines do not get comments.
+    </PRE>
+
+    <P>
+      Obviously, uncommenting is the same as deleting comment characters, so
+      the line about ARG being negative is the crucial line, here.  What you
+      want to do is to write a function which is the same as
+      <CODE>comment-region</CODE>, except that it passes a negative ARG:
+
+
+
+    <PRE>
+(defun uncomment-region (beg end)
+  "Like `comment-region' invoked with a C-u prefix arg."
+  (interactive "r")
+  (comment-region beg end -1))
+    </PRE>
+
+    <P>
+      The part about invoking <CODE>comment-region</CODE> with <CODE>-1</CODE> as argument
+      should be clear, but the <CODE>interactive</CODE> line looks quite
+      obfuscated.  Well, you have to use <CODE>interactive</CODE> such that a
+      function can be invoked via <KBD>M-x</KBD> or a key binding.  And the string
+      <CODE>"r"</CODE> means that the two arguments of this function are the start
+      and the end of the region, respectively.  See the documentation of the
+      <CODE>interactive</CODE> function for more alternatives.
+
+
+    <P>
+      You can now bind <CODE>uncomment-region</CODE> to a key, just like any other
+      command.
+
+
+
+
+    <H2><A NAME="SEC21" HREF="tutorials_toc.html#TOC21">Complex key bindings</A></H2>
+
+    <P>
+      There are two ways to bind complex actions to a single key.  One of them
+      is easy to use but is not easily maintainable, and the other requires a
+      bit of programming but is more flexible.  The easy way to do it is to
+      use keyboard macros, the flexible way is to write Lisp functions.
+
+
+
+
+    <H3><A NAME="SEC22" HREF="tutorials_toc.html#TOC22">Complex key bindings with kbd macros</A></H3>
+
+    <P>
+      Type <KBD>C-x (</KBD> to start recording a kbd macro, use <KBD>C-x )</KBD> to stop
+      recording.  Use <KBD>M-x name-last-kbd-macro RET</KBD> to give a name to the
+      kbd macro just recorded.  Then, use <KBD>M-x insert-kbd-macro RET</KBD> to
+      insert the named kbd macro into your <TT>`.emacs'</TT> file.  The name of
+      the kbd macro can then be used just like any other command name in a
+      normal <SAMP>`define-key'</SAMP> or <SAMP>`global-set-key'</SAMP> statement.
+
+
+
+
+    <H3><A NAME="SEC23" HREF="tutorials_toc.html#TOC23">Complex key bindings with Lisp functions</A></H3>
+
+    <P>
+      Teaching Lisp is out of the scope of this tutorial, but you may wish to
+      have a look at the Emacs Lisp Introduction, available from
+      <A HREF="ftp.gnu.org">ftp.gnu.org</A> and its mirrors, as well as the section in the Emacs
+      manual on the <TT>`.emacs'</TT> file.
+
+
+
+
+    <H2><A NAME="SEC24" HREF="tutorials_toc.html#TOC24">TODO</A></H2>
+
+
+    <UL>
+      <LI>
+
+	Add xref to (emacs)Init File.
+    </UL>
+
+    <P><HR><P>
+      Go to the <A HREF="tutorials_1.html">first</A>, <A HREF="tutorials_1.html">previous</A>, <A HREF="tutorials_3.html">next</A>, <A HREF="tutorials_3.html">last</A> section, <A HREF="tutorials_toc.html">table of contents</A>.

Links/tutorials_3.content

+%title%
+A Collection of Tutorials on Emacs - Mail with Gnus
+%author%
+Adrian Aichner, original author Kai Grossjohann
+%main%
+
+    Go to the <A HREF="tutorials_1.html">first</A>, <A HREF="tutorials_2.html">previous</A>, next, last section, <A HREF="tutorials_toc.html">table of contents</A>.
+    <P><HR><P>
+
+
+    <H1><A NAME="SEC25" HREF="tutorials_toc.html#TOC25">Mail with Gnus</A></H1>
+
+    <P>
+      Quite a few people wish to read mail with Gnus but stumble across a few
+      issues which make this a bit difficult.  This comes from the fact that
+      Gnus is really a newsreader, and thus it treats mail in a newsreaderly
+      fashion.  It is not desirable to change this, because it is a wonderful
+      thing and this is what distinguishes Gnus from other mail readers.  In
+      this little tutorial, I'll try to explain what "newsreaderly fashion"
+      means and how exactly Gnus treats mail.
+
+
+    <P>
+      Specific pieces of behavior can always be changed, but if you desire to
+      make Gnus behave like a conventional mail reader, think again.  It will
+      be an uphill battle.  Maybe a different mail reader is for you?  But
+      also, read on.  Maybe you'll find the right behavior in the description
+      below.
+
+
+
+
+    <H2><A NAME="SEC26" HREF="tutorials_toc.html#TOC26">Gnus Terminology</A></H2>
+
+    <P>
+      First, let's talk about a few terms which I'm going to use which might
+      be unfamiliar to you.
+
+
+    <DL COMPACT>
+
+      <DT><EM>Posting, Article, Message, Mail</EM>
+      <DD>
+	These are all related terms.  A news message might also be called a
+	posting or an article, whereas a mail message is known as a mail.  Since
+	Gnus treats both news and mail, the distinction isn't as clear.  In the
+	following, I'll use the term "message" for the generic case and "news
+	message" and "mail message" for the specific cases.  But sometimes, I
+	might use "posting" or "article", too, both synonymous with
+	"message".
+
+      <DT><EM>Backend</EM>
+      <DD>
+	Gnus can read messages from various sources.  On the one hand, there is
+	news, and on the other hand, there is mail.  News can be read from a
+	news server (an NNTP server), or from a so-called spool directory.  Mail
+	can be read in various formats.
+
+	Generally speaking, a backend describes the way Gnus accesses a set of
+	messages.  For a news server, this is the Network News Transfer
+	Protocol, NNTP, and thus there is a backend "nntp".  For mail stored
+	in the same format that the MH message handling system used, there is
+	the backend "nnmh".  And so on.  See below for a list of backends.
+
+      <DT><EM>Server</EM>
+      <DD>
+	Whereas a backend describes the mechanism used by Gnus to access the
+	messages, a server is a specific instance of that mechanism.  You might
+	create a specific server for accessing the host <TT>`news.frob.org'</TT>
+	using NNTP, say.  Or you might create a server for accessing the
+	MH-style directory <TT>`~/OldMail'</TT>.
+
+	If you are a programmer, think of a backend as the class and of a server
+	as an object (instance) of that class.  If you are a cook, think of a
+	backend as an apple pie recipe (say), and think of a server as an actual
+	apple pie.  (Yummy!)  If you live in a huge city, think of a backend as
+	a bus (or tram, or underground) line (the Circle Line comes to mind),
+	and think of a server as a specific bus (or tram train, or underground
+	train).  The one at 8:15 last Monday morning, for example.  If you drive
+	a car, think of a backend as the model and make and of a server as a
+	specific car.
+
+	Obviously, there can be two servers using the same backend.  (Two
+	instances of the same class, two apple pies baked according to the same
+	recipe, two busses going the same route, two cars of the same model.)
+
+      <DT><EM>(Select) method</EM>
+      <DD>
+	Just another term for server.
+
+      <DT><EM>Native server</EM>
+      <DD>
+	This is the primary server, so to speak.  Most people let their news
+	server be the native server, hence:
+
+	<PRE>
+(setq gnus-select-method '(nntp "news.frob.org"))
+	</PRE>
+
+	Groups from the native server are also known as native groups.
+
+      <DT><EM>Secondary select methods</EM>
+      <DD>
+	This is a list of other servers which one also wishes to use.  Many
+	people are only going to have two servers, one native (for news) and one
+	secondary (for mail).  Thus:
+
+	<PRE>
+(setq gnus-secondary-select-methods '((nnml "")))
+	</PRE>
+
+	Note that there is one more pair of parentheses in order to be able to
+	mention more than one seconary select method.
+
+	Groups from a secondary server are also known as secondary groups.
+
+	In order to be able to distinguish native groups from secondary groups,
+	each server is identified with a (unique) name and that name is used as
+	a prefix for the secondary groups.  Thus, you might have a group
+	<TT>`gnu.emacs.help'</TT> (which is native) and another group
+	<TT>`nnml:mail.misc'</TT> (which is secondary).  A plus character is used if
+	the name of a server is not the empty string.  For example, given the
+	following in your <TT>`.gnus'</TT> file
+
+	<PRE>
+(setq gnus-secondary-select-methods
+      '((nnml "work" (nnml-directory "~/Mail.work/"))
+        (nnml "play" (nnml-directory "~/Mail.play/"))))
+	</PRE>
+
+	you might have the groups <TT>`nnml+work:boss'</TT> and
+	<TT>`nnml+play:so'</TT><A NAME="DOCF1" HREF="tutorials_foot.html#FOOT1">(1)</A>.
+
+      <DT><EM>Group</EM>
+      <DD>
+	Well, if you've read news before, you know about different news groups.
+	One of my favorites is <TT>`gnu.emacs.gnus'</TT>, and I wish I would read
+	<TT>`alt.fan.pratchett'</TT>.  Since Gnus treats mail in a newsreaderly
+	fashion, it is obvious that it uses groups rather than "folders" like
+	other mail readers do.  So with Gnus there are news groups and mail
+	groups, where mail groups are known as mail folders to other programs.
+
+	Each group belongs to a certain server, and each server uses a certain
+	backend.
+
+      <DT><EM>Expiry</EM>
+      <DD>
+	News servers offer news groups which contain news postings.  New news
+	postings come in, so the news postings accumulate, and pretty soon the
+	new hard disk is full.  This is not good news at all.
+
+	Thus, a news server does what is known as <EM>expiry</EM>: it deletes old
+	messages.  Of course, on a news server, expiry happens with no regard of
+	whether people have already seen the message in question; instead, the
+	news server admin chooses expiry times based on available disk space and
+	maybe on the normal amount of traffic in a news group.
+
+	But mail messages should be under the users' control, so there better be
+	no server which deletes messages regardless of users having seen them!
+	Instead, Gnus adopts a scheme where users say which messages may be
+	deleted, and Gnus takes care of deleting them after a while.  (They are
+	not deleted immediately in case you made a mistake, or in case you wish
+	to refer back to an old article.)
+
+      <DT><EM>Article marks</EM>
+      <DD>
+	Gnus distinguishes between a number of article marks, which indicate
+	whether they have been looked at, or are considered important, or the
+	like.  Marks are represented by a character.
+
+	If that character is a space, it looks as if the message isn't marked at
+	all.  These messages are called <EM>unmarked</EM>, the mark character used
+	is a space, and marking a message with space is considered to be the
+	same as removing all marks--after all, such messages are unmarked.  You
+	can type <KBD>M-u</KBD> to remove all marks and make an article unmarked.
+
+	Articles that are considered important or where you wish to indicate
+	that you have to deal with them later can be <EM>ticked</EM>.  The mark
+	character used for ticked messages is the exclamation mark, and you can
+	use <KBD>u</KBD> or <KBD>!</KBD> to tick messages.  Ticked messages are always
+	shown when you enter a group.
+
+	There is the <EM>dormant</EM> mark which is similar to the ticked mark but
+	does not imply importance or urgency; thus, dormant messages aren't
+	shown by default.  The mark character used is the question mark, and you
+	can mark messages as dormant using the <KBD>?</KBD> key.
+
+	So far, each kind of mark was associated with one character (as was the
+	absence of any mark).  But articles which you have read are a bit
+	different, since lots of different characters are used here.  The
+	important thing to realize is that these messages are treated in the
+	same way by Gnus; the different characters are only used as an
+	information for the user.
+
+	Articles which are marked as read because you have actually read them
+	(the normal case, one would think) are marked with the `R' character.
+	(Type <KBD><KBD>SPC</KBD></KBD> or <KBD>g</KBD> to read a message, or click on it using
+	the middle mouse button, <KBD><KBD>mouse-2</KBD></KBD>.)  You can also mark a
+	message as read without actually reading it, this is indicated with the
+	`r' character and can be achieved with <KBD>d</KBD> or <KBD>M r</KBD>.
+
+	After exiting a group and then entering it again (some time later), the
+	messages that had been marked as read before appear with the `O'
+	character.
+
+	To reiterate: the difference between `r', `R' and `O' is only an
+	information for the user.
+
+    </DL>
+
+
+
+    <H2><A NAME="SEC27" HREF="tutorials_toc.html#TOC27">Choosing a mail backend</A></H2>
+
+    <P>
+      The Gnus manual lists quite a few backends.  Of these, the news backends
+      pose no problem: you use the <CODE>nntp</CODE> backend if you access a news
+      server and the <CODE>nnspool</CODE> backend if you have a local news spool
+      directory.  (Leafnode users should use <CODE>nntp</CODE> so that the leafnode
+      program can see what you are doing and choose the groups to download
+      accordingly.)  But the mail backends are more difficult.  There are many
+      of them, and it is not obvious which is the best choice.  In quite a few
+      cases, this is because there is no single best choice; or maybe what's
+      the best choice depends on the group or changes over time.
+
+
+    <P>
+      Below, I'll give a list of mail backends.  While I say something about
+      how messages are stored, I'll try to emphasize what that means for you
+      as a user.
+
+
+    <P>
+      Let's try to structure the discussion a bit.  We have servers, which
+      contain groups, which in turn contain messages.  How could we store this
+      on disk?  After some thought, you'll quickly come up with the following
+      alternatives:  You could store all messages from a server in one file.
+      The second alternative is to store all messages from one group in one
+      file, different groups are stored in different files.  A third
+      alternative is to store each message in one file; in this case, one
+      could use a directory per group.  A very interesting fourth alternative
+      is not to store the messages at all but instead to use the Oracle of
+      Delphi (say) to predict what the messages will be; this saves a lot of
+      disk space.  I won't talk about the fourth alternative in the following.
+
+
+
+
+    <H3><A NAME="SEC28" HREF="tutorials_toc.html#TOC28">Backends with one file per server</A></H3>
+
+    <P>
+      Many people use just two servers, the native server for news and a
+      secondary server for mail.  Thus, this alternative would mean that you
+      store all your mail in one file.  Since Emacs has no fancy mechanisms to
+      access parts of files, this means that Gnus loads that file into main
+      memory at startup, and all your mails are kept in main memory all the
+      time.  (Of course, copies are written to disk every now and then, for
+      safekeeping!)
+
+
+    <P>
+      I think you can pretty much figure out the consequences on your own,
+      now:
+
+    <UL>
+      <LI>
+
+	Handling large amounts of mail will be a problem.  (Emacs has a maximum
+	file size of 128 MB.)
+
+      <LI>
+
+	Some operations on mails will be fast, since they are in-memory
+	operations.  (Saving everything to disk will be slow, though.)
+
+      <LI>
+
+	Some operations on mails will be slow, since they have to search through
+	the whole file.
+
+      <LI>
+
+	It is convenient to have all mail stored in one file: you can easily
+	transfer it to another computer using FTP, say, or store it on a floppy
+	or Zip disk or a tape.
+
+    </UL>
+
+    <P>
+      Conclusion: If you don't have a lot of mail to deal with and like the
+      convenience of storing it all in one file, one of these backends might
+      be for you.  However, since Gnus really shines when dealing with lots of
+      mails, most Gnus users can be expected to deal with quite a large volume
+      of mail.  Thus, I don't think many Gnus users choose one of these
+      backends.
+
+
+    <DL COMPACT>
+
+      <DT><CODE>nnmbox</CODE>
+      <DD>
+	This backend uses the well-known "mbox" format for storing mails.  In
+	this format, a message begins with the five characters <CODE>From_</CODE> (the
+	last character is a space) at the beginning of a line, and ends with an
+	empty line.
+
+      <DT><CODE>nnbabyl</CODE>
+      <DD>
+	This backend uses the lesser known "babyl" format for storing mails.
+	This uses delimiters for the beginning and the end of a message which
+	are less likely to occur in a message.
+
+
+	<BLOCKQUOTE>
+	  <P>
+	    CCC Are they guaranteed to never occur?
+	</BLOCKQUOTE>
+
+	One advantage of a babyl file over an mbox file is that it is possible
+	to insert information about a message in the babyl file, without having
+	to change the message itself.  In an mbox file, the only place to put
+	such information is the message header, which is part of the message.
+	Thus, adding information about a message to an mbox file means that one
+	has to change the message.
+
+	I think Gnus doesn't make use of this advantage, though.  Gnus stores
+	information about messages in an extra file, <TT>`~/.newsrc.eld'</TT>.
+
+    </DL>
+
+
+    <BLOCKQUOTE>
+      <P>
+	CCC Can somebody provide me with some more arguments in favor of one of
+	the formats?
+
+
+      <P>
+	CCC Is it possible to just use an existing babyl file for Gnus, by
+	creating a new nnmbox server and pointing it at the file?  What about
+	mbox?
+    </BLOCKQUOTE>
+
+
+
+    <H3><A NAME="SEC29" HREF="tutorials_toc.html#TOC29">Backends with one file per group</A></H3>
+
+    <P>
+      Storing all messages in a group in one file provides a nice middle
+      ground between the one file per server type of backend and the one file
+      per message type of backend.  Using lots of little files wastes disk
+      space; since this approach uses a moderate number of files, less disk
+      space is wasted.
+
+
+
+    <BLOCKQUOTE>
+      <P>
+	CCC Which operations are fast using this kind of backend?  Which are
+	slow? 
+    </BLOCKQUOTE>
+
+    <DL COMPACT>
+
+      <DT><CODE>nnfolder</CODE>
+      <DD>
+	This backend uses the same file format as <CODE>nnmbox</CODE>, but uses the
+	one file per group approach.
+
+    </DL>
+
+    <P>
+      There is no "nnbabylfolder" backend which uses babyl format.
+
+
+
+
+    <H3><A NAME="SEC30" HREF="tutorials_toc.html#TOC30">Backends with one file per message</A></H3>
+
+    <P>
+      If the number of messages grows so large that even the size of a single
+      group exceeds the limit which can be handled by the file-per-group
+      backends, you need to think about using one of the backends mentioned
+      here.
+
+
+    <P>
+      This category also includes <CODE>nnml</CODE>, the backend which is fastest if
+      you have lots of messages.
+
+
+    <DL COMPACT>
+
+      <DT><CODE>nnmh</CODE>
+      <DD>
+	This backend uses the same file format (and directory structure) as MH,
+	i.e. a group is a directory, and each message is stored in a file, and
+	the file names are numbers.
+
+	Since <CODE>nnml</CODE> is so similar to <CODE>nnmh</CODE> but a lot faster, only
+	unusual situations could warrant using this backend.  You may want to
+	use <CODE>nnmh</CODE> if you wish to use Gnus in parallel to your old MH based
+	reader.
+
+	Normally, you should not let two programs write the same Gnus directory
+	(not even two instances of Gnus!), but if you really must, you may wish
+	to use <CODE>nnmh</CODE>, since there the probability of things breaking is
+	smaller than with the other backends.
+
+      <DT><CODE>nnml</CODE>
+      <DD>
+	This backend is like <CODE>nnmh</CODE> but also includes an extra file
+	<TT>`.overview'</TT> in each directory (group) which contains some headers
+	from each message.  Thus, where <CODE>nnmh</CODE> needs to open every file in
+	a group to examine its headers, <CODE>nnml</CODE> (normally) needs to only
+	read the <TT>`.overview'</TT> file, which is a lot faster.
+    </DL>
+
+
+
+    <H3><A NAME="SEC31" HREF="tutorials_toc.html#TOC31">Other mail backends</A></H3>
+
+    <P>
+      There is one other mail backend, for keeping messages on an IMAP server.
+
+
+    <DL COMPACT>
+
+      <DT><CODE>nnimap</CODE>
+      <DD>
+	This backend transforms Gnus into an IMAP client.  The general idea of
+	IMAP is to store and manipulate the mails on a server (similar to NNTP
+	for news).
+
+	<CODE>nnimap</CODE> only works with the current development version of Gnus,
+	though.  See <A HREF="http://www.extundo.com/nnimap/">http://www.extundo.com/nnimap/</A> for <CODE>nnimap</CODE> and
+	see <A HREF="http://www.gnus.org/">http://www.gnus.org/</A> for Gnus.  Don't forget to subscribe to
+	both the Gnus and the nnimap mailing lists since you are using alpha
+	grade software which can be exptected to have bugs.  Be prepared to
+	submit meaningful bug reports if you encounter bugs.
+
+	Rumor has it that <CODE>nnimap</CODE> will be integrated with the next version
+	of Gnus (version 5.8, presumably), when that comes out.
+
+    </DL>
+
+
+
+    <H3><A NAME="SEC32" HREF="tutorials_toc.html#TOC32">Summary</A></H3>
+
+    <P>
+      If you must talk to an IMAP server, the choice is clear.  But if you
+      keep mails on your local disk, the choice isn't as clear-cut.  I think
+      that <CODE>nnml</CODE> is generally the best choice unless you have real great
+      disk space trouble.  Then, you should be thinking about <CODE>nnfolder</CODE>.
+
+
+    <P>
+      I'm not sure if there is a situation where <CODE>nnmbox</CODE> or
+      <CODE>nnbabyl</CODE> is desirable.
+
+
+
+    <BLOCKQUOTE>
+      <P>
+	CCC Tell me about it if you know more!
+    </BLOCKQUOTE>
+
+
+
+    <H2><A NAME="SEC33" HREF="tutorials_toc.html#TOC33">Auto-expire versus total-expire</A></H2>
+
+    <P>
+      Every now and then, people ask about auto-expire and total-expire.
+      Since both of these features are means to the same end, and since they
+      are similar and dissimilar at the same time, great confusion can result
+      in the unsuspecting new Gnus user.  I'll try to explain how each works
+      and which one to use.  However, be prepared that there will be no clear
+      recommendation: both work well, so for many situations both are
+      appropriate.  So it is more a matter of taste which one to choose.  And
+      I can't help you with that!
+
+
+
+
+    <H3><A NAME="SEC34" HREF="tutorials_toc.html#TOC34">What is expiry?</A></H3>
+
+    <P>
+      Gnus treats mail in a newsreaderly fashion, so it is useful to examine
+      the situation for news.  Your news server periodically contacts other
+      news servers and exchanges messages with the other server.  The two news
+      servers exchange lists of messages, and messages present in one server
+      but not in the other are sent to the other server.  This works in both
+      directions.  Many connections between news servers exist, and this is
+      the way how postings travel from you into the world: when you post a
+      message, your news server stores it and offers it to the other servers
+      in the message list exchanging phase.  Since the other servers aren't
+      going to have the posting you just wrote, it gets transferred and
+      finally can be seen all over the world.
+
+
+    <P>
+      You can quickly see that new messages will be arriving at your news
+      server, which stores them on disk.  So something has got to happen else
+      the disk will fill up real fast.  That "something" is expiry: the
+      oldest messages are deleted to make room for the new ones.  Normally, a
+      news server can be configured on a per-group basis which messages should
+      be deleted.  In some groups, messages might be deleted which are older
+      than a day, in other groups, messages might be kept for a month.
+
+
+    <P>
+      This means if you go on vacation then come back later to read news, you
+      are likely to miss some postings if the expiration time for the groups
+      you read is shorter than the time you were on vacation.
+
+
+    <P>
+      How does that apply to mail?
+
+
+    <P>
+      Well, mail should stay more under the control of the user than news is.
+      When you come back from a vacation, you expect to see all messages
+      arrived during that time, not only the recent ones!
+
+
+    <P>
+      Because of this, Gnus offers you the <KBD>E</KBD> key.  This marks a message
+      as expirable.  No mail is ever deleted from disk, unless it is
+      expirable.  Every once in a while (by default, whenever you quit a group
+      by hitting <KBD>q</KBD> in the Summary buffer), the expiry process is run,
+      which goes through all expirable messages (of a group) and expires it if
+      old enough.  By default, messages older than seven days are "old
+      enough".  Seven days, that is, since it was marked as expirable.
+
+
+
+    <BLOCKQUOTE>
+      <P>
+	CCC Last sentence correct?
+    </BLOCKQUOTE>
+
+    <P>
+      "But when I read a message, exit the group, then enter it again, the
+      message is gone!"
+
+
+    <P>
+      Right.  By default, Gnus hides messages which have already been read.
+      If you are the keyboard type, you can hit <KBD>C-u <KBD>RET</KBD></KBD> or
+      <KBD>C-u <KBD>SPC</KBD></KBD> to enter the group or <KBD>C-u M-g</KBD> when in the
+      group to look at the read messages.  If you are the mousey type, you may
+      wish to use the "See old articles" entry in the "Group" menu.
+
+
+
+    <BLOCKQUOTE>
+      <P>
+	CCC How does one code menu entries in TeXinfo?
+    </BLOCKQUOTE>
+
+
+
+    <H3><A NAME="SEC35" HREF="tutorials_toc.html#TOC35">Why auto-expire and total-expire?</A></H3>
+
+    <P>
+      When reading mail, by default Gnus marks as read each message that you
+      read.  If you want to mark it as expirable, you have to hit <KBD>E</KBD>.
+      Many people are subscribed to mailing lists and they configure Gnus to
+      put mails from a mailing list into their own group.  Most messages in
+      such groups should be expirable, once read.  But hitting <KBD>E</KBD> all the
+      gets old real quick.  Hence, auto-expire and total-expire were invented.
+
+
+
+
+    <H3><A NAME="SEC36" HREF="tutorials_toc.html#TOC36">Auto-expire vs. total-expire</A></H3>
+
+    <P>
+      Auto-expire and total-expire both aim at the same goal: articles which
+      are read should normally be expired, only if one does something special
+      should these articles be saved on disk.  But what happens when a message
+      is being read by you, the user?  Well, the message is marked as read
+      (with the `R' mark).  So, what can be done to make these messages
+      expire?  Well, two approaches come to mind: one idea is to change the
+      mark that is attached to messages that you read, and the other idea is
+      to make the `R' articles expirable.  These are <EM>exactly</EM> the things
+      that are done in Gnus: auto-expire means to change the mark that is
+      attached to a message that is being read, and total-expire means to
+      change the meaning of the `R' mark to mean expirable.
+
+
+    <P>
+      A more precise description of auto-expire might be the following: If an
+      article is unmarked and then selected for reading,<A NAME="DOCF2" HREF="tutorials_foot.html#FOOT2">(2)</A> it is
+      marked with `E', as if the user had hit <KBD>E</KBD>.
+
+
+    <P>
+      It is important to realize that auto-expire has <EM>no other</EM>
+      consequences.  Selecting a message for reading which wasn't unmarked
+      doesn't do anything special, and hitting <KBD>d</KBD> on a message also
+      doesn't do anything special.  (It therefore marks the message as read,
+      not as expirable!)
+
+
+    <P>
+      Now, forget about auto-expire, empty your mind and prepare to learn
+      about total-expire.  Like I said, total-expire changes what it means for
+      an article to be marked as read.
+
+
+    <P>
+      A more precise description of total-expire might be the following: When
+      the expire process is run (for example, when you leave a group with
+      <KBD>q</KBD>), all messages marked as read are considered to be expirable, as
+      if they had been marked with `E'.  Recall that there are several ways to
+      mark a message as read: by reading it, by hitting <KBD>d</KBD> on it, and in
+      a few other ways which I haven't mentioned so far.  Recall that, in
+      addition to the messages marked with `R', also those marked with `r' or
+      `O' are considered to be marked as read.
+
+
+    <P>
+      Can auto-expire and total-expire be used together?  Well, in principle
+      they can, but that doesn't make sense.  Just using total-expire alone
+      achieves the same effect.
+
+
+    <P>
+      So, how do auto-expire and total-expire compare?  Well, for once thing,
+      hitting <KBD>d</KBD> on a message means it is expirable if total-expire is
+      on (since it is marked as read and all messages marked as read are
+      considered expirable when total-expire is on), but it is not expirable
+      if auto-expire is on (since it is marked as read and only articles
+      marked expirable (`E') are considered to be expirable).  If you want to
+      mark a message as expirable when total-expire is off, use <KBD>E</KBD>.
+
+
+    <P>
+      One way of comparing auto-expire and total-expire is to compare the
+      message marks that are available, and what they mean.  Since auto-expire
+      does not change the meaning of marks, its behavior is the same as in the
+      default case.  It's only important whether total-expire is on or off.
+      Thus, there are only two cases: the default case and the total-expire
+      case.
+
+
+
+
+    <H4><A NAME="SEC37" HREF="tutorials_toc.html#TOC37">Article marks with and without total-expire</A></H4>
+
+    <P>
+      The following are the default article marks and behavior:
+
+
+    <DL COMPACT>
+
+      <DT><EM>unmarked</EM>
+      <DD>
+	All new messages are unmarked.  This means you haven't seen them.  They
+	are always shown and won't be deleted.
+
+      <DT><EM>read</EM>
+      <DD>
+	Messages marked as read are not shown by default but kept on disk till
+	hell freezes over.  You can show them with <KBD>C-u M-g</KBD> from the
+	summary buffer, or with <KBD>C-u <KBD>SPC</KBD></KBD> or with the `Group' menu
+	item `See old articles' from the group buffer.
+
+	Depending on the setting of <VAR>gnus-fetch-old-headers</VAR>, a message
+	marked as read might be shown if there is a followup or reply to it.
+
+      <DT><EM>dormant</EM>
+      <DD>
+	Dormant messages aren't shown by default but kept on disk till hell
+	freezes over.  You can show them with <KBD>/ D</KBD> from the summary buffer.
+	If there is a reply or followup to a dormant message, the dormant
+	message is also shown.
+
+      <DT><EM>ticked</EM>
+      <DD>
+	Ticked messages are always shown and kept on disk till hell freezes
+	over.
+
+      <DT><EM>expirable</EM>
+      <DD>
+	Expirable messages will be deleted in due time.  They are not shown by
+	default, but you can make them appear with <KBD>C-u M-g</KBD> and so on,
+	similar to the read ones.
+
+    </DL>
+
+    <P>
+      Please note that the behavior for ticked messages is similar to the
+      unread ones, and that the behavior of dormant messages is similar to the
+      read ones.  Especially the second fact will become important when we
+      look at
+
+
+    <P>
+      The behavior of the article marks with total-expire:
+
+
+    <DL COMPACT>
+
+      <DT><EM>unmarked</EM>
+      <DD>
+	Same as in the default case.
+
+      <DT><EM>expirable</EM>
+      <DD>
+	Same as in the default case.
+
+      <DT><EM>read</EM>
+      <DD>
+	Same as expirable.
+
+      <DT><EM>dormant</EM>
+      <DD>
+	Same as in the default case.
+
+      <DT><EM>ticked</EM>
+      <DD>
+	Same as in the default case.
+
+    </DL>
+
+    <P>
+      As you can see, only the behavior of the read messages is different, and
+      you can use the dormant mark if you want to achieve behavior similar to
+      the behavior of read messages in the default case.
+
+
+
+
+    <H4><A NAME="SEC38" HREF="tutorials_toc.html#TOC38">Speed issues</A></H4>
+
+    <P>
+      Total-expire may be slow when expiry happens.  Why is that?  Well, Gnus
+      keeps an explicit list of all expirable messages (the ones marked `E'
+      without taking total-expire into account), as well as a list of dormant
+      messages, and a list of ticked messages.  Normally, when expiration time
+      comes, Gnus goes through all articles in the expire list and looks if
+      they are old enough to be expired.
+
+
+    <P>
+      However, for read messages the situation is different.  Here, Gnus just
+      keeps a list of ranges of article numbers to be able to distinguish read
+      messages from unmarked ones.  The assumption is that a message is to be
+      considered marked as read if it falls in one of the ranges and isn't
+      mentioned in any of the expirable, dormant or ticked lists.
+
+
+    <P>
+      When total-expire is turned on, Gnus needs to go through all messages in
+      the read range in order to look if it's in one of the lists.  If the
+      message is not in the ticked or dormant list, it is expirable and thus
+      Gnus looks to see if it is old enough.
+
+
+    <P>
+      Obviously, going through all the articles in the read ranges takes more
+      time than going through just the list of expirable articles.
+
+
+    <P>
+      Something can be done about the speed issue, though.  Normally, the
+      expiry process is started whenever you leave a group.  I suggest that
+      you disable this and instead run expiry just once per day, for example
+      while you are going for lunch.  This means that expiry still takes a
+      long time, but you don't see it and thus it doesn't bother you.
+
+
+    <P>
+      Here's how to do that: You disable the expire-on-group-exit thing with
+      the following line in your <TT>`~/.gnus'</TT> file:
+
+    <PRE>
+(remove-hook 'gnus-summary-prepare-exit-hook
+             'gnus-summary-expire-articles)
+    </PRE>
+
+    <P>
+      And before you leave for lunch, you hit <KBD>C-M-x</KBD>, or <KBD>M-x
+	gnus-group-expire-all-groups <KBD>RET</KBD></KBD>.
+
+
+
+
+    <H4><A NAME="SEC39" HREF="tutorials_toc.html#TOC39">Functionality</A></H4>
+
+    <P>
+      Adaptive scoring doesn't work with auto-expire.  (But normal scoring
+      still works fine.)  Adaptive scoring works fine with total-expire.
+
+
+
+
+    <H4><A NAME="SEC40" HREF="tutorials_toc.html#TOC40">A summary</A></H4>
+
+    <P>
+      Well, it is difficult to sum up the whole discussion.  I used to use
+      total-expire but have switched to auto-expire a long time ago.  I liked
+      the fact that I could use one more kind of article mark.  I also liked
+      the fact that marking a message as read works the same in auto-expirable
+      groups and in normal mail groups: you hit <KBD>E</KBD>.  (With total-expire,
+      you normally hit <KBD>d</KBD> but must remember to use <KBD>E</KBD> for those
+      groups where total-expire is off.)  And I liked that auto-expire is
+      faster.
+
+
+    <P>
+      On the other hand, adaptive scoring is surely a very useful feature (I'm
+      just beginning to use it), so many people might prefer total-expire.
+
+
+    <P>
+      And on a third hand, maybe the key binding issue isn't so important
+      after all.  You see, in mail groups the <KBD>d</KBD> key means `keep this
+      message for archival purposes', whereas in many other modes (dired, CCC
+      others?) it stands for `delete'.  I propose to make it mean delete in
+      mail groups, too, with the following line in
+      <TT>`~/.gnus'</TT>:<A NAME="DOCF3" HREF="tutorials_foot.html#FOOT3">(3)</A>
+
+    <PRE>
+(define-key gnus-summary-mode-map "d" 'gnus-summary-mark-as-expirable)
+    </PRE>
+
+    <P>
+      Marking messages as expirable (rather than read) in news groups does no
+      harm, nor does it harm to do so in total-expirable mail groups.  The old
+      `keep this message' semantics can still be had by marking a message as
+      dormant or by using <KBD>M r</KBD> (in non-total-expirable groups only).
+
+
+
+
+    <H2><A NAME="SEC41" HREF="tutorials_toc.html#TOC41">Migrating old mail</A></H2>
+
+    <P>
+      Probably, you've been reading mail in pre-Gnus times, right?  And surely
+      you wish to carry this over to Gnus.  Well, I haven't found a real good
+      way to do it, but I can offer a few suggestions for doing it at least
+      semi-automatically.
+
+
+    <P>
+      One way of getting at your old mail is to type <KBD>G f</KBD>, and to then
+      enter the name of your old mail file.  This provides read-only access to
+      your mails.  For some people, this might be sufficient.  (With <KBD>G
+	f</KBD>, you have created an <CODE>nndoc</CODE> group.)
+
+
+    <P>
+      Some people might want to have their mails available in their normal
+      mail groups hierarchy.  That's simple, just create an <CODE>nndoc</CODE> group
+      for your mail file, then mark all messages in it with <KBD>M P a</KBD>, then
+      copy all of them over to a normal mail group, with <KBD>B c</KBD>.
+
+
+    <P>
+      This is good for people who wish to keep their old arrangement of
+      folders, and who have a one-to-one correspondence between old mail files
+      and new Gnus groups.  But some people might wish to split up their mails
+      differently.  For them, it might be useful to set up
+      <VAR>nnmail-split-methods</VAR> correctly and to use <KBD>B r</KBD> instead of
+      <KBD>B c</KBD>.  This goes through all process-marked messages and subjects
+      them to the same splitting process that newly arriving messages go
+      through.  (Whee!  What a run-on sentence!)
+
+
+
+
+    <H2><A NAME="SEC42" HREF="tutorials_toc.html#TOC42">TODO</A></H2>
+
+    <DL COMPACT>
+
+      <DT>*
+      <DD>
+	Say something about the cache.  Though this belongs in the news reading
+	tips, right?  Hm.
+    </DL>
+
+    <P><HR><P>
+      Go to the <A HREF="tutorials_1.html">first</A>, <A HREF="tutorials_2.html">previous</A>, next, last section, <A HREF="tutorials_toc.html">table of contents</A>.

Links/tutorials_foot.content

+%title%
+A Collection of Tutorials on Emacs - Footnotes
+%author%
+Adrian Aichner, original author Kai Grossjohann
+%main%
+
+    <H1>A Collection of Tutorials on Emacs</H1>
+    <H2>A Companion to the FAQ and the Emacs Manual</H2>
+    <ADDRESS>Kai Grossjohann <A HREF="mailto:Kai.Grossjohann@CS.Uni-Dortmund.DE">Kai.Grossjohann@CS.Uni-Dortmund.DE</A></ADDRESS>
+    <P>
+    <P><HR><P>
+    <H3><A NAME="FOOT1" HREF="tutorials_3.html#DOCF1">(1)</A></H3>
+    <P>"SO" standing for "significant other",
+      i.e. girlfriend or boyfriend
+    <H3><A NAME="FOOT2" HREF="tutorials_3.html#DOCF2">(2)</A></H3>
+    <P>Using
+      <KBD>g</KBD>, or <KBD><KBD>mouse-2</KBD></KBD>, or by moving to it with <KBD>n</KBD> or
+      <KBD>p</KBD>, or by one of the many other methods provided by Gnus.
+    <H3><A NAME="FOOT3" HREF="tutorials_3.html#DOCF3">(3)</A></H3>
+    <P>See the chapter on key bindings; maybe you need
+      a `require' statement.
+    <P><HR><P>
+      This document was generated on 8 October 1999 using
+      <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.

Links/tutorials_toc.content

+%title%
+A Collection of Tutorials on Emacs - Table of Contents
+%author%
+Adrian Aichner, original author Kai Grossjohann
+%main%
+
+    <H1>A Collection of Tutorials on Emacs</H1>
+    <H2>A Companion to the FAQ and the Emacs Manual</H2>
+    <ADDRESS>Kai Grossjohann <A HREF="mailto:Kai.Grossjohann@CS.Uni-Dortmund.DE">Kai.Grossjohann@CS.Uni-Dortmund.DE</A></ADDRESS>
+    <P>
+    <P><HR><P>
+    <UL>
+      <LI><A NAME="TOC1" HREF="tutorials_1.html#SEC1">Indentation</A>
+	<UL>
+	  <LI><A NAME="TOC2" HREF="tutorials_1.html#SEC2">Basic Concepts</A>
+	    <UL>
+	      <LI><A NAME="TOC3" HREF="tutorials_1.html#SEC3">The <KBD>TAB</KBD> key.</A>
+	      <LI><A NAME="TOC4" HREF="tutorials_1.html#SEC4">The tab character.</A>
+	      <LI><A NAME="TOC5" HREF="tutorials_1.html#SEC5">Whether or not tab characters are used for indentation.</A>
+	      <LI><A NAME="TOC6" HREF="tutorials_1.html#SEC6">The location of the tab stops.</A>
+	      <LI><A NAME="TOC7" HREF="tutorials_1.html#SEC7">Syntax driven indentation.</A>
+	      <LI><A NAME="TOC8" HREF="tutorials_1.html#SEC8">Relative indentation.</A>
+	    </UL>
+	  <LI><A NAME="TOC9" HREF="tutorials_1.html#SEC9">Usage scenarios.</A>
+	    <UL>
+	      <LI><A NAME="TOC10" HREF="tutorials_1.html#SEC10">I want to turn off syntax driven indentation!</A>
+	    </UL>
+	  <LI><A NAME="TOC11" HREF="tutorials_1.html#SEC11">Background information.</A>
+	    <UL>
+	      <LI><A NAME="TOC12" HREF="tutorials_1.html#SEC12">Mode hooks.</A>
+	    </UL>
+	  <LI><A NAME="TOC13" HREF="tutorials_1.html#SEC13">TODO</A>
+	</UL>
+      <LI><A NAME="TOC14" HREF="tutorials_2.html#SEC14">Key bindings</A>
+	<UL>
+	  <LI><A NAME="TOC15" HREF="tutorials_2.html#SEC15">Online help for key bindings</A>
+	  <LI><A NAME="TOC16" HREF="tutorials_2.html#SEC16">A warning about own key bindings</A>
+	  <LI><A NAME="TOC17" HREF="tutorials_2.html#SEC17">Simple key bindings</A>
+	  <LI><A NAME="TOC18" HREF="tutorials_2.html#SEC18">The syntax for <SAMP>`kbd'</SAMP></A>
+	  <LI><A NAME="TOC19" HREF="tutorials_2.html#SEC19">The delete and backspace keys</A>
+	  <LI><A NAME="TOC20" HREF="tutorials_2.html#SEC20">Binding <KBD>C-u <VAR>something</VAR></KBD> to a different key</A>
+	  <LI><A NAME="TOC21" HREF="tutorials_2.html#SEC21">Complex key bindings</A>
+	    <UL>
+	      <LI><A NAME="TOC22" HREF="tutorials_2.html#SEC22">Complex key bindings with kbd macros</A>
+	      <LI><A NAME="TOC23" HREF="tutorials_2.html#SEC23">Complex key bindings with Lisp functions</A>
+	    </UL>
+	  <LI><A NAME="TOC24" HREF="tutorials_2.html#SEC24">TODO</A>
+	</UL>
+      <LI><A NAME="TOC25" HREF="tutorials_3.html#SEC25">Mail with Gnus</A>
+	<UL>
+	  <LI><A NAME="TOC26" HREF="tutorials_3.html#SEC26">Gnus Terminology</A>
+	  <LI><A NAME="TOC27" HREF="tutorials_3.html#SEC27">Choosing a mail backend</A>
+	    <UL>
+	      <LI><A NAME="TOC28" HREF="tutorials_3.html#SEC28">Backends with one file per server</A>
+	      <LI><A NAME="TOC29" HREF="tutorials_3.html#SEC29">Backends with one file per group</A>
+	      <LI><A NAME="TOC30" HREF="tutorials_3.html#SEC30">Backends with one file per message</A>
+	      <LI><A NAME="TOC31" HREF="tutorials_3.html#SEC31">Other mail backends</A>
+	      <LI><A NAME="TOC32" HREF="tutorials_3.html#SEC32">Summary</A>
+	    </UL>
+	  <LI><A NAME="TOC33" HREF="tutorials_3.html#SEC33">Auto-expire versus total-expire</A>
+	    <UL>
+	      <LI><A NAME="TOC34" HREF="tutorials_3.html#SEC34">What is expiry?</A>
+	      <LI><A NAME="TOC35" HREF="tutorials_3.html#SEC35">Why auto-expire and total-expire?</A>
+	      <LI><A NAME="TOC36" HREF="tutorials_3.html#SEC36">Auto-expire vs. total-expire</A>
+		<UL>
+		  <LI><A NAME="TOC37" HREF="tutorials_3.html#SEC37">Article marks with and without total-expire</A>
+		  <LI><A NAME="TOC38" HREF="tutorials_3.html#SEC38">Speed issues</A>
+		  <LI><A NAME="TOC39" HREF="tutorials_3.html#SEC39">Functionality</A>
+		  <LI><A NAME="TOC40" HREF="tutorials_3.html#SEC40">A summary</A>
+		</UL>
+	    </UL>
+	  <LI><A NAME="TOC41" HREF="tutorials_3.html#SEC41">Migrating old mail</A>
+	  <LI><A NAME="TOC42" HREF="tutorials_3.html#SEC42">TODO</A>
+	</UL>
+    </UL>
+    <P><HR><P>
+      This document was generated on 8 October 1999 using
+      <A HREF="http://wwwinfo.cern.ch/dis/texi2html/">texi2html</A>&nbsp;1.56k.