(Article Button Levels): New node.

(Article Buttons): Additions.

diff --git a/texi/ChangeLog b/texi/ChangeLog
index b0e3b77..f1e8217 100644 (file)
--- a/texi/ChangeLog
+++ b/texi/ChangeLog
@@ -1,3 +1,8 @@
+2003-03-31  Reiner Steib  <Reiner.Steib@gmx.de>
+
+       * gnus.texi (Article Button Levels): New node.
+       (Article Buttons): Additions.
+
 2003-03-31  Lars Magne Ingebrigtsen  <larsi@gnus.org>
 
        * gnus.texi (Exiting Gnus): Removed gnus-unload.

diff --git a/texi/gnus.texi b/texi/gnus.texi
index e7370d1..6984da4 100644 (file)
--- a/texi/gnus.texi
+++ b/texi/gnus.texi
@@ -608,6 +608,7 @@ Article Treatment
 * Article Washing::             Lots of way-neat functions to make life better.
 * Article Header::              Doing various header transformations.
 * Article Buttons::             Click on URLs, Message-IDs, addresses and the like.
+* Article Button Levels::       Controlling appearance of buttons.
 * Article Date::                Grumble, UT!
 * Article Display::             Display various stuff---X-Face, Picons, Smileys
 * Article Signature::           What is a signature?
@@ -7905,6 +7906,7 @@ these articles easier.
 * Article Washing::             Lots of way-neat functions to make life better.
 * Article Header::              Doing various header transformations.
 * Article Buttons::             Click on URLs, Message-IDs, addresses and the like.
+* Article Button Levels::       Controlling appearance of buttons.
 * Article Date::                Grumble, UT!
 * Article Display::             Display various stuff---X-Face, Picons, Smileys
 * Article Signature::           What is a signature?
@@ -8611,9 +8613,9 @@ button on these references.
 
 @vindex gnus-button-man-handler
 Gnus adds @dfn{buttons} to certain standard references by default:
-Well-formed URLs, mail addresses, Message-IDs, Info links and man pages.
-This is controlled by two variables, one that handles article bodies and
-one that handles article heads:
+Well-formed URLs, mail addresses, Message-IDs, Info links, man pages and
+Emacs or Gnus related references.  This is controlled by two variables,
+one that handles article bodies and one that handles article heads:
 
 @table @code
 
@@ -8632,7 +8634,7 @@ All text that match this regular expression (case insensitive) will be
 considered an external reference.  Here's a typical regexp that matches
 embedded URLs: @samp{<URL:\\([^\n\r>]*\\)>}.  This can also be a
 variable containing a regexp, useful variables to use include
-@code{gnus-button-url-regexp}.
+@code{gnus-button-url-regexp} and @code{gnus-button-mid-or-mail-regexp}.
 
 @item button-par
 Gnus has to know which parts of the matches is to be highlighted.  This
@@ -8642,7 +8644,11 @@ highlighted.  If you want it all highlighted, you use 0 here.
 @item use-p
 This form will be @code{eval}ed, and if the result is non-@code{nil},
 this is considered a match.  This is useful if you want extra sifting to
-avoid false matches.
+avoid false matches.  Often variables named
+@code{gnus-button-@var{*}-level} are used here, @xref{Article Button
+Levels}, but any other form may be used too.
+
+@c @code{use-p} is @code{eval}ed only if @code{regexp} matches.
 
 @item function
 This function will be called when you click on this button.
@@ -8671,11 +8677,70 @@ used to say what headers to apply the buttonize coding to:
 
 @var{header} is a regular expression.
 
+@subsubheading Related variables and functions
+
+@item gnus-button-@var{*}-level
+@xref{Article Button Levels}.
+
+@c Stuff related to gnus-button-browse-level
+
 @item gnus-button-url-regexp
 @vindex gnus-button-url-regexp
 A regular expression that matches embedded URLs.  It is used in the
 default values of the variables above.
 
+@c Stuff related to gnus-button-man-level
+
+@item gnus-button-man-handler
+@vindex gnus-button-man-handler
+The function to use for displaying man pages.  It must take at least one
+argument with a string naming the man page.
+
+@c Stuff related to gnus-button-message-level
+
+@item gnus-button-mid-or-mail-regexp
+@vindex gnus-button-mid-or-mail-regexp
+Regular expression that matches a message ID or a mail address.
+
+@item gnus-button-prefer-mid-or-mail
+@vindex gnus-button-prefer-mid-or-mail
+This variable determines what to do when the button on a string as
+@samp{foo123@@bar.invalid} is pushed.  Strings like this can be either a
+message ID or a mail address.  If it is one of the symbols @code{mid} or
+@code{mail}, Gnus will always assume that the string is a message ID or
+a mail address, respectivly.  If this variable is set to the symbol
+@code{ask}, always query the user what do do.  If it is a function, this
+function will be called with the string as it's only argument.  The
+function must return @code{mid}, @code{mail}, @code{invalid} or
+@code{ask}.  The default value is the function
+@code{gnus-button-mid-or-mail-heuristic}.
+
+@item gnus-button-mid-or-mail-heuristic
+@findex gnus-button-mid-or-mail-heuristic
+Function that guesses whether it's argument is a message ID or a mail
+address.  Returns @code{mid} it's a message IDs, @code{mail} if it's a
+mail address, @code{ask} if unsure and @code{invalid} if the string is
+invalid.
+
+@item gnus-button-mid-or-mail-heuristic-alist
+@vindex gnus-button-mid-or-mail-heuristic-alist
+An alist of @code{(RATE . REGEXP)} pairs used by the function
+@code{gnus-button-mid-or-mail-heuristic}.
+
+@c Stuff related to gnus-button-tex-level
+
+@item gnus-button-ctan-handler
+@findex gnus-button-ctan-handler
+The function to use for displaying CTAN links.  It must take one
+argument, the string naming the URL.
+
+@item gnus-ctan-url
+@vindex gnus-ctan-url
+Top directory of a CTAN (Comprehensive TeX Archive Network) archive used
+by @code{gnus-button-ctan-handler}.
+
+@c Misc stuff
+
 @item gnus-article-button-face
 @vindex gnus-article-button-face
 Face used on buttons.
@@ -8689,6 +8754,73 @@ Face used when the mouse cursor is over a button.
 @xref{Customizing Articles}, for how to buttonize articles automatically.
 
 
+@node Article Button Levels
+@subsection Article button levels
+@cindex button levels
+The higher the value of the variables @code{gnus-button-@var{*}-level},
+the more buttons will appear.  If the level is zero, no corresponding
+buttons are displayed.  With the default value (which is 5) you should
+already see quite a lot of buttons.  With higher levels, you will see
+more buttons, but you may also get more false positives.  To avoid them,
+you can set the variables @code{gnus-button-@var{*}-level} local to
+specific groups (@pxref{Group Parameters}).  Here's an example for the
+variable @code{gnus-parameters}:
+
+@lisp
+;; increase `gnus-button-*-level' in some groups:
+(setq gnus-parameters
+      '(("\\<\\(emacs\\|gnus\\)\\>" (gnus-button-emacs-level 10))
+        ("\\<unix\\>"               (gnus-button-man-level 10))
+        ("\\<tex\\>"                (gnus-button-tex-level 10))))
+@end lisp
+
+@table @code
+
+@item gnus-button-browse-level
+@vindex gnus-button-browse-level
+Controls the display of references to message IDs, mail addresses and
+news URLs.  Related variables and functions include
+@code{gnus-button-url-regexp}, @code{browse-url}, and
+@code{browse-url-browser-function}.
+
+@item gnus-button-emacs-level
+@vindex gnus-button-emacs-level
+Controls the display of Emacs or Gnus references.  Related functions are
+@code{gnus-button-handle-custom},
+@code{gnus-button-handle-describe-function},
+@code{gnus-button-handle-describe-variable},
+@code{gnus-button-handle-symbol},
+@code{gnus-button-handle-describe-key},
+@code{gnus-button-handle-apropos},
+@code{gnus-button-handle-apropos-command},
+@code{gnus-button-handle-apropos-variable},
+@code{gnus-button-handle-apropos-documentation}, and
+@code{gnus-button-handle-library}.
+
+@item gnus-button-man-level
+@vindex gnus-button-man-level
+Controls the display of references to (Unix) man pages.
+See @code{gnus-button-man-handler}.
+
+@item gnus-button-message-level
+@vindex gnus-button-message-level
+Controls the display of message IDs, mail addresses and news URLs.
+Related variables and functions include
+@code{gnus-button-mid-or-mail-regexp},
+@code{gnus-button-prefer-mid-or-mail},
+@code{gnus-button-mid-or-mail-heuristic}, and
+@code{gnus-button-mid-or-mail-heuristic-alist}.
+
+@item gnus-button-tex-level
+@vindex gnus-button-tex-level
+Controls the display of references to TeX or LaTeX stuff, e.g. for CTAN
+URLs.  See the variables @code{gnus-ctan-url},
+@code{gnus-button-ctan-handler} and
+@code{gnus-button-handle-ctan-bogus-regexp}.
+
+@end table
+
+
 @node Article Date
 @subsection Article Date