31.13.8 Diary Display

Diary display works by preparing the list of diary entries and then running the function specified by the variable diary-display-function. The default value diary-fancy-display displays diary entries and holidays by copying them into a special buffer that exists only for the sake of display. Copying diary entries to a separate buffer provides an opportunity to change the displayed text to make it prettier—for example, to sort the entries by the dates they apply to.

Ordinarily, the fancy diary buffer does not show days for which there are no diary entries, even if that day is a holiday. If you want such days to be shown in the fancy diary buffer, set the variable diary-list-include-blanks to t.

The fancy diary buffer enables View mode (see View Mode).

The alternative display method diary-simple-display shows the actual diary buffer, and uses invisible text to hide entries that don’t apply. Holidays are shown in the mode line. The advantage of this method is that you can edit the buffer and save your changes directly to the diary file. This method is not as flexible as the fancy method, however. For example, it cannot sort entries. Another disadvantage is that invisible text can be confusing. For example, if you copy a region of text in order to paste it elsewhere, invisible text may be included. Similarly, since the diary buffer as you see it is an illusion, simply printing the buffer may not print what you see on your screen.

For this reason, there is a special command to print hard copy of the diary buffer as it appears; this command is M-x diary-print-entries. It works with either display method, although with the fancy display you can also print the buffer like any other. To print a hard copy of a day-by-day diary for a week, position point on the first day of the week, type 7 d, and then do M-x diary-print-entries. As usual, the inclusion of the holidays slows down the display slightly; you can speed things up by setting the variable diary-show-holidays-flag to nil.

This command prepares a temporary buffer that contains only the diary entries currently visible in the diary buffer. Unlike with the simple display, the other irrelevant entries are really absent, not just hidden. After preparing the buffer, it runs the hook diary-print-entries-hook. The default value of this hook sends the data directly to the printer with the command lpr-buffer (see Printing Hard Copies). If you want to use a different command to do the printing, just change the value of this hook. Other uses might include, for example, rearranging the lines into order by day and time.

You can edit the diary entries as they appear in the simple diary window, but it is important to remember that the buffer displayed contains the entire diary file, with portions of it concealed from view. This means, for instance, that the C-f ( forward-char) command can put point at what appears to be the end of the line, but what is in reality the middle of some concealed line.

Be careful when editing the diary entries in the simple display! Inserting additional lines or adding/deleting characters in the middle of a visible line cannot cause problems, but editing at the end of a line may not do what you expect. Deleting a line may delete other invisible entries that follow it. Before editing the simple diary buffer, it is best to display the entire file with s ( diary-show-all-entries).