Subject: Re: bug#10323: 24.0.92; docstring diary-date-forms

From: "Roland Winkler" <[email-masked]>
Date: Tue, 8 Jun 2021 17:44:37 -0500

On Wed Jun 2 2021 Lars Ingebrigtsen wrote:
> >   The patterns on the list must be MUTUALLY EXCLUSIVE and should not match
> >   any portion of the diary entry itself, just the date component.
> >   Here the first character following the date itself is considered part of
> >   the date.
> 
> (I'm going through old bug reports that unfortunately got no response at
> the time.)
> 
> This was nine years ago, but the doc string is still the same here.
> And...  I'm not quite sure I understand either the current doc string or
> the proposed enhancement, really.  :-)
> 
> > Actually, this is not completely true either, and it becomes relevant if
> > one wants to indent the diary entries for which the `backup' mechanism
> > of diary-european-date-forms applies.  If one has the diary entries
> >
> > 18/12/2011$  foo bar
> > 18/12/2011   foo baz
> > 18 December  foo bar
> >
> > the first two entries are indented as one might expect it; yet
> > the third one is not indented (i.e., with `backup' all
> > whitespace characters following immediately the date become part
> > of the date)
> 
> Perhaps something from this discussion of the problem should be
> added to the doc string?  If so, please do go ahead and modify it.

It took me a while to refresh my memories about this bug report.

The problem is about how diary-date-forms arranges the splitting of
a diary entry into a date (specifying when to display the diary entry)
and the associated text (that will be displayed for this date).  The
current code assumes, indeed, that there is a separator in between
these two components of an entry.  This separator is given by the
last element of each date form in diary-date-forms and the separator is
swallowed by the "fancy diary display" machinery for diary entries.
This behavior is undocumented which makes it hard to figure out how
the predefined elements of diary-date-forms actually work, and this
was, I believe, my original motivation for the bug report almost ten
years ago.

For most predefined date forms, the separator is a single character.
For example, given an entry "08/06/2021foo bar", the letter f is
treated as separator that is swallowed so that the fancy diary
buffer displays the entry as "oo bar".  Probably, this undocumented
behavior is rarely causing problems for users because it is more
common that the first character following the date is a space.

Yet worse, the "backup" approach used for the third date form in
diary-european-date-forms implies that any non-word characters at the
beginning of the text are not displayed in the fancy diary buffer.
For example, the diary entry "08 June @John: hello" is displayed as
"John: hello" instead of  "@John: hello".  This may confuse not only
elisp coders but also ordinary users of the emacs diary.

A cleaner solution was probably that the last element of each date
form defined the beginning of the text that will be displayed for
this date.  However, the current code has existed for many years so
that likely users have arranged themselves with its oddities and a
better solution must keep this in mind, too.

(I haven't figured out why, according to the docstring of
diary-date-forms, the patterns defined by different date forms must
be mutually exclusive.  I'd find it more natural if just the first
matching pattern wins.)

What do others think about this?