GNU bug report logs - #40695
[PATCH] ; Fix some typos and doc issues

Previous Next

Full log

View this message in rfc822 format

From: Eli Zaretskii <eliz <at> gnu.org>
To: Štěpán Němec <stepnem <at> gmail.com>
Cc: 40695 <at> debbugs.gnu.org
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 <at> gmail.com>
> Cc: 40695 <at> 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.

Previous Next

GNU bug tracking system
Copyright (C) 1999 Darren O. Benham, 1997,2003 nCipher Corporation Ltd, 1994-97 Ian Jackson.