bug#40695: [PATCH] ; Fix some typos and doc issues

[Štěpán Němec]

On Sat, 18 Apr 2020 15:28:14 +0300
Eli Zaretskii wrote:

> Are all of the places where you inserted @w{..} split expressions or
> commands between lines?  I don't want to have redundant @w{..} in the
> manual sources.

Not all of them, but I thought that we established in

https://lists.gnu.org/archive/html/bug-gnu-emacs/2020-04/msg00245.html
835ze8o53t.fsf@gnu.org

that the only way to be sure is to always check the rendered output if a
change pushed a previously non-split occurence to a location where the
split happens. And given your "@w{..} is harmless if it isn't needed" in
the above-mentioned message, I decided to err on the redundant side, as
I suspect most people don't routinely double-check the Info output after
every change.

If you prefer to limit the changes to only those necessary for
unsplitting the already split occurences, I'll do that.

>> -@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).

>> --- a/lisp/emacs-lisp/cl-macs.el
>> +++ b/lisp/emacs-lisp/cl-macs.el
>> @@ -776,7 +776,7 @@ cl-case
>>    "Eval EXPR and choose among clauses on that value.
>>  Each clause looks like (KEYLIST BODY...).  EXPR is evaluated and
>>  compared against each key in each KEYLIST; the corresponding BODY
>> -is evaluated.  If no clause succeeds, cl-case returns nil.  A
>> +is evaluated.  If no clause succeeds, `cl-case' returns nil.  A
>
> I'd prefer to say "this macro" here.  It doesn't seem useful to have a
> link to the macro from its own doc string.

Indeed, I'll change that, thanks.

>> -;; `iter-do' is like `cl-do', except that instead of walking a list,
>> +;; `iter-do' is like `dolist', except that instead of walking a list,
>
> Is the original text in error here?

"Error" might be too strong, but `iter-do' is very similar (analogous)
to `dolist', and quite dissimilar to `cl-do', so I find the original
comparison more confusing than helpful (and indeed suspect that it might
have been an oversight/thinko).

>>  (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?

>>  (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.

>> -  "Return whether the given form never yields."

>> -like `try-completion'; if it's t, this function works like
>> -`all-completion'; and any other values makes it work like
>> +like `try-completion'; if it is t, this function works like
>> +`all-completion'; and any other value makes it work like
>
> What was wrong here?

"values makes" -> "value makes"; when at it, I also ended up changing
"it's" to "it is", as I found the former too informal or something...

  Thanks,

  Štěpán