Formatting Variables
====================

   Throughout this manual you've probably noticed lots of variables that
are called things like `gnus-group-line-format' and
`gnus-summary-mode-line-format'.  These control how Gnus is to output
lines in the various buffers.  There's quite a lot of them.
Fortunately, they all use the same syntax, so there's not that much to
be annoyed by.

   Here's an example format spec (from the group buffer): `%M%S%5y:
%(%g%)\n'.  We see that it is indeed extremely ugly, and that there are
lots of percentages everywhere.

   Each `%' element will be replaced by some string or other when the
buffer in question is generated.  `%5y' means "insert the `y' spec, and
pad with spaces to get a 5-character field".  Just like a normal format
spec, almost.

   You can also say `%6,4y', which means that the field will never be
more than 6 characters wide and never less than 4 characters wide.

   There are also specs for highlighting, and these are shared by all
the format variables.  Text inside the `%(' and `%)' specifiers will
get the special `mouse-face' property set, which means that it will be
highlighted (with `gnus-mouse-face') when you put the mouse pointer
over it.

   Text inside the `%[' and `%]' specifiers will have their normal
faces set using `gnus-face-0', which is `bold' by default.  If you say
`%1[' instead, you'll get `gnus-face-1' instead, and so on.  Create as
many faces as you wish.  The same goes for the `mouse-face' specs--you
can say `%3(hello%)' to have `hello' mouse-highlighted with
`gnus-mouse-face-3'.

   Here's an alternative recipe for the group buffer:

     ;; Create three face types.
     (setq gnus-face-1 'bold)
     (setq gnus-face-3 'italic)
     
     ;; We want the article count to be in
     ;; a bold and green face.  So we create
     ;; a new face called `my-green-bold'.
     (copy-face 'bold 'my-green-bold)
     ;; Set the color.
     (set-face-foreground 'my-green-bold "ForestGreen")
     (setq gnus-face-2 'my-green-bold)
     
     ;; Set the new & fancy format.
     (setq gnus-group-line-format
           "%M%S%3{%5y%}%2[:%] %(%1{%g%}%)\n")

   I'm sure you'll be able to use this scheme to create totally
unreadable and extremely vulgar displays.  Have fun!

   Currently Gnus uses the following formatting variables:
`gnus-group-line-format', `gnus-summary-line-format',
`gnus-server-line-format', `gnus-topic-line-format',
`gnus-group-mode-line-format', `gnus-summary-mode-line-format',
`gnus-article-mode-line-format', `gnus-server-mode-line-format'.

   Note that the `%(' specs (and friends) do not make any sense on the
mode-line variables.

   All these format variables can also be arbitrary elisp forms.  In
that case, they will be `eval'ed to insert the required lines.

   Gnus includes a command to help you while creating your own format
specs.  `M-x gnus-update-format' will `eval' the current form, update
the spec in question and pop you to a buffer where you can examine the
resulting lisp code to be run to generate the line.