bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation

[Štěpán Němec]

On Sun, 11 Sep 2011 04:11:25 +0200
Lars Magne Ingebrigtsen wrote:

> Štěpán Němec <stepnem@gmail.com> writes:
>
>> The two variables, which fortunately do appear to be dynamically bound
>> to the middle month and year currently displayed in the calendar window
>> at the time of running `diary-mark-entries-hook', are _crucial_ for
>> being able to define useful marking functions[1]. Please document this
>> (AFAICT they are currently not mentioned anywhere; I had to read much of
>> calendar.el and holidays.el to figure it out).
>
> Do you have a suggestion for a suitable documentation?

The variables definitely need docstrings explaining their use. There's
this comment in calendar.el:

;; A note on free variables:

;; The calendar passes around a few dynamically bound variables, which
;; unfortunately have rather common names.  They are meant to be
;; available for external functions, so the names can't be changed.

;; displayed-month, displayed-year: bound in calendar-generate, the
;;   central month of the 3 month calendar window

I'm hesitant as to the actual wording of such docstrings, because 1) my
uderstanding of the code is still quite limited, in particular I don't
know about _all_ the places the variables are bound and useful, and 2)
you probably couldn't use my wording anyway for so-called legal reasons.
I hoped Glenn (cc-ed) would take a look, as I think he is most familiar
with that part of Emacs.

The fact that the variables are bound should also be mentioned at least
in the `diary-mark-entries-hook' docstring.

It might be nice to add some info documentation, but given that there is
currently virtually no relevant documentation there to be found (even
`diary-mark-entries-hook' is only mentioned in a single code example),
I think just adding the docstrings would suffice.

Thank you for moving this issue forward.

-- 
Štěpán