9.4 Formatting Variables

Throughout this manual you’ve probably noticed lots of variables 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.

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, and gnus-summary-pick-line-format.

All these format variables can also be arbitrary elisp forms. In that case, they will be evaled 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.

9.4.1 Formatting Basics

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”.

As with normal C and Emacs Lisp formatting strings, the numerical modifier between the ‘%’ and the formatting type character will pad the output so that it is always at least that long. ‘%5y’ will make the field always (at least) five characters wide by padding with spaces to the left. If you say ‘%-5y’, it will pad to the right instead.

You may also wish to limit the length of the field to protect against particularly wide values. For that you can say ‘%4,6y’, which means that the field will never be more than 6 characters wide and never less than 4 characters wide.

Also Gnus supports some extended format specifications, such as ‘%&user-date;’.

9.4.2 Mode Line Formatting

Mode line formatting variables (e.g., gnus-summary-mode-line-format) follow the same rules as other, buffer line oriented formatting variables (see section Formatting Basics) with the following two differences:

1. There must be no newline (‘\n’) at the end.
2. The special ‘%%b’ spec can be used to display the buffer name. Well, it’s no spec at all, really—‘%%’ is just a way to quote ‘%’ to allow it to pass through the formatting machinery unmangled, so that Emacs receives ‘%b’, which is something the Emacs mode line display interprets to mean “show the buffer name”. For a full list of mode line specs Emacs understands, see the documentation of the mode-line-format variable.

9.4.3 Advanced Formatting

It is frequently useful to post-process the fields in some way. Padding, limiting, cutting off parts and suppressing certain values can be achieved by using tilde modifiers. A typical tilde spec might look like ‘%~(cut 3)~(ignore "0")y’.

These are the valid modifiers:

pad

pad-left

Pad the field to the left with spaces until it reaches the required length.

pad-right

Pad the field to the right with spaces until it reaches the required length.

max

max-left

Cut off characters from the left until it reaches the specified length.

max-right

Cut off characters from the right until it reaches the specified length.

cut

cut-left

Cut off the specified number of characters from the left.

cut-right

Cut off the specified number of characters from the right.

ignore

Return an empty string if the field is equal to the specified value.

form

Use the specified form as the field value when the ‘@’ spec is used.

Here’s an example:

"~(form (current-time-string))@"

Let’s take an example. The ‘%o’ spec in the summary mode lines will return a date in compact ISO8601 format—‘19960809T230410’. This is quite a mouthful, so we want to shave off the century number and the time, leaving us with a six-character date. That would be ‘%~(cut-left 2)~(max-right 6)~(pad 6)o’. (Cutting is done before maxing, and we need the padding to ensure that the date is never less than 6 characters to make it look nice in columns.)

Ignoring is done first; then cutting; then maxing; and then as the very last operation, padding.

9.4.4 User-Defined Specs

All the specs allow for inserting user defined specifiers—‘u’. The next character in the format string should be a letter. Gnus will call the function gnus-user-format-function-‘X’, where ‘X’ is the letter following ‘%u’. The function will be passed a single parameter—what the parameter means depends on what buffer it’s being called from. The function should return a string, which will be inserted into the buffer just like information from any other specifier. This function may also be called with dummy values, so it should protect against that.

Also Gnus supports extended user-defined specs, such as ‘%u&foo;’. Gnus will call the function gnus-user-format-function-‘foo’.

You can also use tilde modifiers (see section Advanced Formatting to achieve much the same without defining new functions. Here’s an example: ‘%~(form (count-lines (point-min) (point)))@’. The form given here will be evaluated to yield the current line number, and then inserted.

9.4.5 Formatting Fonts

There are 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{’, 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.

Text inside the ‘%<<’ and ‘%>>’ specifiers will get the special balloon-help property set to gnus-balloon-face-0. If you say ‘%1<<’, you’ll get gnus-balloon-face-1 and so on. The gnus-balloon-face-* variables should be either strings or symbols naming functions that return a string. When the mouse passes over text with this property set, a balloon window will appear and display the string. Please refer to (emacs)Tooltips section ‘Tooltips’ in The Emacs Manual, (in Emacs) or the doc string of balloon-help-mode (in XEmacs) for more information on this. (For technical reasons, the guillemets have been approximated as ‘<<’ and ‘>>’ in this paragraph.)

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!

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

9.4.6 Positioning Point

Gnus usually moves point to a pre-defined place on each line in most buffers. By default, point move to the first colon character on the line. You can customize this behavior in three different ways.

You can move the colon character to somewhere else on the line.

You can redefine the function that moves the point to the colon. The function is called gnus-goto-colon.

But perhaps the most convenient way to deal with this, if you don’t want to have a colon in your line, is to use the ‘%*’ specifier. If you put a ‘%*’ somewhere in your format line definition, Gnus will place point there.

9.4.7 Tabulation

You can usually line up your displays by padding and cutting your strings. However, when combining various strings of different size, it can often be more convenient to just output the strings, and then worry about lining up the following text afterwards.

To do that, Gnus supplies tabulator specs—‘%=’. There are two different types—hard tabulators and soft tabulators.

‘%50=’ will insert space characters to pad the line up to column 50. If the text is already past column 50, nothing will be inserted. This is the soft tabulator.

‘%-50=’ will insert space characters to pad the line up to column 50. If the text is already past column 50, the excess text past column 50 will be removed. This is the hard tabulator.

9.4.8 Wide Characters

Fixed width fonts in most countries have characters of the same width. Some countries, however, use Latin characters mixed with wider characters—most notable East Asian countries.

The problem is that when formatting, Gnus assumes that if a string is 10 characters wide, it’ll be 10 Latin characters wide on the screen. In these countries, that’s not true.

To help fix this, you can set gnus-use-correct-string-widths to t. This makes buffer generation slower, but the results will be prettier. The default value under XEmacs is t but nil for Emacs.

This document was generated on January 25, 2015 using texi2html 1.82.