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

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

[Roland Winkler]

Maybe this is too pedantic: If one tries to separate a diary entry
into the date and the text part, the question comes up: what about
the separator (usually some whitespace character(s)) between the
date and the text part? The docstring of diary-date-forms says

  The patterns on the list must be MUTUALLY EXCLUSIVE and should not match
  any portion of the diary entry itself, just the date component.

Originally I thought this would exclude the separator from the date
component (so that I had to deal with it myself). But the patterns
are designed the other way round. For the regexp matcher the
separator is an important part of the date component. So I suggest
to modify the docstring of diary-date-forms to say something like

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


In GNU Emacs 24.0.92.1 (x86_64-unknown-linux-gnu, GTK+ Version 2.20.1)
 of 2011-12-14 on regnitz
Windowing system distributor `The X.Org Foundation', version 11.0.10706000

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

[Roland Winkler]

> 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)

To avoid misunderstandings: Here I was talking about how
diary-fancy-display displays the above diary entries.
This uses diary-date-forms.

Roland

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

[Lars Ingebrigtsen]

"Roland Winkler" <winkler@gnu.org> writes:

> Maybe this is too pedantic: If one tries to separate a diary entry
> into the date and the text part, the question comes up: what about
> the separator (usually some whitespace character(s)) between the
> date and the text part? The docstring of diary-date-forms says
>
>   The patterns on the list must be MUTUALLY EXCLUSIVE and should not match
>   any portion of the diary entry itself, just the date component.
>
> Originally I thought this would exclude the separator from the date
> component (so that I had to deal with it myself). But the patterns
> are designed the other way round. For the regexp matcher the
> separator is an important part of the date component. So I suggest
> to modify the docstring of diary-date-forms to say something like
>
>   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.

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Roland Winkler]

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?

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

[Lars Ingebrigtsen]

"Roland Winkler" <winkler@gnu.org> writes:

> (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?

I tried following the logic of the code here (and read the doc strings a
bunch of times), and I'm still confused as to why it's implemented the
way it is -- it seems pretty convoluted.

But we probably can't change the implementation here (without obsoleting
the variables and starting from scratch), so I think we should just
attempt to document what it's actually doing, as difficult as even that
is.  :-/

-- 
(domestic pets only, the antidote for overdose, milk.)
   bloggy blog: http://lars.ingebrigtsen.no

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

[Michael Heerdegen]

"Roland Winkler" <winkler@gnu.org> writes:

> (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.)

With the current implementation that requirement seems to be necessary
at least - see bug#7377.


Michael.