bug#50195: [PATCH] Adding diary-offset, a diary-sexp offsetting another diary-sexp.

[Eli Zaretskii <eliz@gnu.org>]

> From: Yuchen Pei <hi@ypei.me>
> Date: Wed, 25 Aug 2021 13:46:48 +1000
> 
> See below my first patch to Emacs.  The copyright assignment has 
> already been done BTW.

Congrats, and welcome aboard.

> Let me know what you think.

Some minor comments below.

> Would you like me to add some tests?

Adding more tests is always welcome, thanks.

> Subject: [PATCH] Adding diary-offset, a diary-sexp offsetting another
>  diary-sexp.

"git am" uses the Subject for the heading line, and this Subject is
too long for that.  Please consider making it shorter.

> A bit like diary-remind, as a diary-sexp rather than reminder, and
> also support both positive and negative offsets.
> 
> This is useful when for example your organization has a committee
> meeting two days after every monthly meeting which takes place on the
> third Thursday, or if you would like to attend a virtual meeting
> scheduled in a different timezone causing a difference in the date.

The commit log message should include a ChangeLog-style description of
the files and functions where you made the changes.  See CONTRIBUTE
for more details about the format we prefer.

Also, please in the next version include the bug number as part of the
log message.

> --- a/doc/emacs/calendar.texi
> +++ b/doc/emacs/calendar.texi
> @@ -1363,6 +1363,20 @@ Special Diary Entries
>  Thursday of January, February, and March.  If the month is @code{t}, the
>  entry applies to all months of the year.
>  
> +@findex diary-offset
> +@example
> +%%(diary-offset '(diary-float t 3 4) 2) Monthly post-event committee meeting

That line is too long, and will overflow the page width in the printed
version of the manual.  Please break it in two.

> +@noindent
> +This entry applies to the Saturday after the third Thursday of each
> +month.  The 2 specifies number of days after when the sexp
> +@samp{'(diary-float t 3 4)} would evaluate to @code{t}.  This is
   ^^^^^^^^^^^^^^^^^^^^^^^^^^^
This should be in @code, not @samp.  I'd also wrap it in @w{..}, so
that it doesn't get broken between two lines.

> +(defun diary-offset (sexp days)
> +  "Offsetted diary entry.

The first line of a doc string should preferably mention the
arguments, but without becoming too long, so it could still fit on a
single line.

> +  (with-no-warnings (defvar date) (defvar entry))

Why did you need this?

> +  (integerp days)

Isn't it better to use an assertion?

Thanks.