[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
bug#40695: [PATCH] ; Fix some typos and doc issues
From: |
Eli Zaretskii |
Subject: |
bug#40695: [PATCH] ; Fix some typos and doc issues |
Date: |
Sat, 18 Apr 2020 16:47:18 +0300 |
> From: Štěpán Němec <stepnem@gmail.com>
> Cc: 40695@debbugs.gnu.org
> Date: Sat, 18 Apr 2020 15:13:27 +0200
>
> If you prefer to limit the changes to only those necessary for
> unsplitting the already split occurences, I'll do that.
Either the split already occurs or is close (i.e. the offending text
is close to the edge of a line. Otherwise we will have to put all of
them in @w{..}, and that seems too much.
>
> >> -@strong{Warning:} if the changes you combine occur in widely scattered
> >> +@strong{Warning:} If the changes you combine occur in widely scattered
> >
> > Not sure the original text is a typo.
>
> Indeed, it caught my eye for the reasons of consistency: all the other
> "Warning:"s in text.texi, and most of those in other texi files, do
> start with a capital, but not all of them, so if it seems too petty to
> you I'll revert this (personally I dislike needless churn; e.g. I was
> quite hesitant about the signalled -> signaled, too; I just bumped into
> it inadvertently).
The "signalled" thing is UK English, and we use US English, so your
changes are okay.
> >> (defvar cps--dynamic-wrappers '(identity)
> >> - "List of transformer functions to apply to atomic forms we
> >> -evaluate in CPS context.")
> >> + "\
> >> +List of transformer functions applied to atomic forms evaluated in CPS
> >> context."
> >> + )
> >
> > This should be fixed by making the sentence shorter. The sentence is
> > a mouthful, IMO.
>
> Heh. I did think about this really hard, but couldn't come up with
> anything that would fit on a single line and not lose essential
> information. Do you have any concrete suggestions?
Something like
List of functions to apply to atomic forms.
These are transformer functions applied in the CPS context.
> >> (defun cps--atomic-p (form)
> >> - "Return whether the given form never yields."
> >> -
> >> + "Return non-nil if FORM never yields."
> >
> > Why this change?
>
> The original sentence sounds weird to me (what does the function really
> return?), while the new version should be quite clear IMO. There's also
> checkdoc nagging about `form' not being upper case.
Well, double negation is also to be avoided. So how about
Return nil if FORM can yield, non-nil otherwise.
?
OK for the rest, thanks.