* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
@ 2011-08-12 9:29 Štěpán Němec
2011-09-11 2:11 ` Lars Magne Ingebrigtsen
0 siblings, 1 reply; 11+ messages in thread
From: Štěpán Němec @ 2011-08-12 9:29 UTC (permalink / raw)
To: 9287
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).
[1] Example:
(defun calendar-mark-lunar-phases ()
(with-current-buffer calendar-buffer
(mapc (lambda (phase)
(calendar-mark-visible-date
;; http://en.wikipedia.org/wiki/Astronomical_symbols
;; "🌚🌛🌝🌜" "🌑🌓🌕🌗"
(car phase) (string (aref "●◐○◑" (nth 2 phase)))))
(let ((m displayed-month)
(y displayed-year))
(calendar-increment-month m y -1)
(lunar-phase-list m y)))))
(add-hook 'diary-mark-entries-hook 'calendar-mark-lunar-phases)
--
Štěpán
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
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
0 siblings, 1 reply; 11+ messages in thread
From: Lars Magne Ingebrigtsen @ 2011-09-11 2:11 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 9287
Š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?
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog http://lars.ingebrigtsen.no/
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 2:11 ` Lars Magne Ingebrigtsen
@ 2011-09-11 3:02 ` Štěpán Němec
2011-09-11 18:48 ` Glenn Morris
0 siblings, 1 reply; 11+ messages in thread
From: Štěpán Němec @ 2011-09-11 3:02 UTC (permalink / raw)
To: Lars Magne Ingebrigtsen; +Cc: 9287
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
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 3:02 ` Štěpán Němec
@ 2011-09-11 18:48 ` Glenn Morris
2011-09-11 18:50 ` Glenn Morris
2011-09-11 19:21 ` Štěpán Němec
0 siblings, 2 replies; 11+ messages in thread
From: Glenn Morris @ 2011-09-11 18:48 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 9287, Lars Magne Ingebrigtsen
The problem is that these variables are kind of fundamental to much of
the calendar operation. So I don't really know which doc-string to put
them in, which is why they are currently only mentioned in the
commentary.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
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-11 19:21 ` Štěpán Němec
1 sibling, 2 replies; 11+ messages in thread
From: Glenn Morris @ 2011-09-11 18:50 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 9287, Lars Magne Ingebrigtsen
And the variables themeselves don't have doc-strings because they are
only dynamically bound when needed (yuck).
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 18:48 ` Glenn Morris
2011-09-11 18:50 ` Glenn Morris
@ 2011-09-11 19:21 ` Štěpán Němec
2011-09-11 23:25 ` Glenn Morris
2019-10-12 5:07 ` Lars Ingebrigtsen
1 sibling, 2 replies; 11+ messages in thread
From: Štěpán Němec @ 2011-09-11 19:21 UTC (permalink / raw)
To: Glenn Morris; +Cc: 9287, Lars Magne Ingebrigtsen
On Sun, 11 Sep 2011 20:48:12 +0200
Glenn Morris wrote:
> The problem is that these variables are kind of fundamental to much of
> the calendar operation. So I don't really know which doc-string to put
> them in, which is why they are currently only mentioned in the
> commentary.
Two possibilities I can think of:
- Mention them in the docstrings of all the variables/functions where
they are likely to be useful in user code (as is the case with
d-m-e-hook).
- Only mention them in d-m-e-hook's docstring (and close this bug). Add
more documentation later if the need (possibly manifested by another
bug report) arises.
--
Štěpán
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 18:50 ` Glenn Morris
@ 2011-09-11 19:26 ` Štěpán Němec
2011-09-11 19:35 ` Andreas Schwab
1 sibling, 0 replies; 11+ messages in thread
From: Štěpán Němec @ 2011-09-11 19:26 UTC (permalink / raw)
To: Glenn Morris; +Cc: 9287, Lars Magne Ingebrigtsen
On Sun, 11 Sep 2011 20:50:06 +0200
Glenn Morris wrote:
> And the variables themeselves don't have doc-strings because they are
> only dynamically bound when needed (yuck).
Yeah, but I'm not sure that should really be considered an argument
_for_ actually defining the variables explicitly and adding the
docstrings or against it -- as the comment in calendar.el itself also
notes, the names are not quite unlikely to be defined in other places,
possibly leading to unexpected behaviour, so proper definitions would
help in that regard, too.
--
Štěpán
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
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
1 sibling, 1 reply; 11+ messages in thread
From: Andreas Schwab @ 2011-09-11 19:35 UTC (permalink / raw)
To: Glenn Morris
Cc: 9287, Lars Magne Ingebrigtsen, Štěpán Němec
Glenn Morris <rgm@gnu.org> writes:
> And the variables themeselves don't have doc-strings because they are
> only dynamically bound when needed (yuck).
I don't think it would be a problem to document them anyway.
Andreas.
--
Andreas Schwab, schwab@linux-m68k.org
GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5
"And now for something completely different."
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 19:21 ` Štěpán Němec
@ 2011-09-11 23:25 ` Glenn Morris
2019-10-12 5:07 ` Lars Ingebrigtsen
1 sibling, 0 replies; 11+ messages in thread
From: Glenn Morris @ 2011-09-11 23:25 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 9287, Lars Magne Ingebrigtsen
Anyway, I agree that the internal operation could use more
documentation, but it needs a bit of thought.
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 19:35 ` Andreas Schwab
@ 2011-09-13 0:40 ` Stefan Monnier
0 siblings, 0 replies; 11+ messages in thread
From: Stefan Monnier @ 2011-09-13 0:40 UTC (permalink / raw)
To: Andreas Schwab; +Cc: 9287, Ingebrigtsen, Štěpán Němec, Lars
>> And the variables themeselves don't have doc-strings because they are
>> only dynamically bound when needed (yuck).
> I don't think it would be a problem to document them anyway.
It would: these are not global variables, whereas the docstring would
be global.
Stefan
^ permalink raw reply [flat|nested] 11+ messages in thread
* bug#9287: Mention `displayed-month' and `displayed-year' in `diary-mark-entries-hook' documentation
2011-09-11 19:21 ` Štěpán Němec
2011-09-11 23:25 ` Glenn Morris
@ 2019-10-12 5:07 ` Lars Ingebrigtsen
1 sibling, 0 replies; 11+ messages in thread
From: Lars Ingebrigtsen @ 2019-10-12 5:07 UTC (permalink / raw)
To: Štěpán Němec; +Cc: 9287
Štěpán Němec <stepnem@gmail.com> writes:
> - Only mention them in d-m-e-hook's docstring (and close this bug). Add
> more documentation later if the need (possibly manifested by another
> bug report) arises.
I've now done this.
--
(domestic pets only, the antidote for overdose, milk.)
bloggy blog: http://lars.ingebrigtsen.no
^ permalink raw reply [flat|nested] 11+ messages in thread
end of thread, other threads:[~2019-10-12 5:07 UTC | newest]
Thread overview: 11+ messages (download: mbox.gz / follow: Atom feed)
-- links below jump to the message on this page --
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
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
Code repositories for project(s) associated with this public inbox
https://git.savannah.gnu.org/cgit/emacs.git
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).