From: "Štěpán Němec" <stepnem@gmail.com>
To: Lars Magne Ingebrigtsen <larsi@gnus.org>
Cc: 9287@debbugs.gnu.org
Subject: bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
Date: Sun, 11 Sep 2011 05:02:58 +0200 [thread overview]
Message-ID: <87fwk33hnh.fsf@gmail.com> (raw)
In-Reply-To: <m3bour7rqq.fsf@stories.gnus.org> (Lars Magne Ingebrigtsen's message of "Sun, 11 Sep 2011 04:11:25 +0200")
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
next prev parent reply other threads:[~2011-09-11 3:02 UTC|newest]
Thread overview: 11+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-08-12 9:29 bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation Štěpán Němec
2011-09-11 2:11 ` Lars Magne Ingebrigtsen
2011-09-11 3:02 ` Štěpán Němec [this message]
2011-09-11 18:48 ` Glenn Morris
2011-09-11 18:50 ` Glenn Morris
2011-09-11 19:26 ` Štěpán Němec
2011-09-11 19:35 ` Andreas Schwab
2011-09-13 0:40 ` Stefan Monnier
2011-09-11 19:21 ` Štěpán Němec
2011-09-11 23:25 ` Glenn Morris
2019-10-12 5:07 ` Lars Ingebrigtsen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=87fwk33hnh.fsf@gmail.com \
--to=stepnem@gmail.com \
--cc=9287@debbugs.gnu.org \
--cc=larsi@gnus.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
Code repositories for project(s) associated with this external index
https://git.savannah.gnu.org/cgit/emacs.git
https://git.savannah.gnu.org/cgit/emacs/org-mode.git
This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.