Re: diary-lib.el how about adding diary-schedule

[Michael Heerdegen]

Gijs Hillenius <gijs@hillenius.net> writes:

> this indeed does what I want:
>
> %%(and (diary-block 15 07 2020 30 06 2021) (diary-cyclic 7 15 07 2020))
>   14:00-14:30 some weekly meeting

Gijs, Lars, should we try to improve the manual a bit?

(1) Would it be helpful to add something like the above as an example?

(2) This paragraph in (info "(emacs) Sexp Diary Entries"):

|    The generality of sexp diary entries lets you specify any diary entry
| that you can describe algorithmically.  A sexp diary entry contains an
| expression that computes whether the entry applies to any given date.
| If its value is non-‘nil’, the entry applies to that date; otherwise, it
| does not.  The expression can use the variable ‘date’ to find the date
| being considered; its value is a list (MONTH DAY YEAR) that refers to
| the Gregorian calendar.

explains what we talked about.  It could say clearer that DATE is bound
as a (dynamical) variable, and it should also say that the variable
ENTRY is also provided (bound to the text found after the expression in
the diary file - see the docstring of `diary-list-sexp-entries' which
explains this better.)

Maybe also say that the predefined diary sexp functions use these
variables implicitly, so that users are not confused about the fact that
most diary sexps don't contain a reference to DATE.

(3) Something else?  What I don't like about the diary part of the
manual is that it tells so many details before you get to the above
paragraph that most people think this is complicated magic.  Whereby
diary sexps are only trivial Elisp sexps that can refer to the variables
DATE and ENTRY and whose return value is interpreted by the
diary/calendar (how the return value is actually interpreted is
explained quite well OTOH).

What do you think?

I also ask Lars because I very much hope he is motivated to make the
change, should we agree about something.  This is because I don't speak
texinfo, and I will soon be on vacation.  Nonetheless I'm happy to
answer any questions if I can.


Michael.