GNU bug report logs - #59603
28.1.90; `ucs-normalize-string' fails to work

Previous Next

To add a comment to this bug, you must first unarchive it, by sending
a message to control AT debbugs.gnu.org, with unarchive 59603 in the body.
You can then email your comments to 59603 AT debbugs.gnu.org in the normal way.

Toggle the display of automated, internal messages from the tracker.

Message #5 received at submit <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: bug-gnu-emacs <at> gnu.org
Subject: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 08:41:39 +0000

Hi,

I just stumbled upon `ucs-normalize-string' 

(defmacro ucs-normalize-string (ucs-normalize-region)
  `(with-temp-buffer
     (insert str)
     (,ucs-normalize-region (point-min) (point-max))
     (buffer-string)))

It apparently uses undefined variable `str', which does not look right.
Also, no docstring.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #10 received at 59603-done <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: 59603-done <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 10:57:45 +0200

> From: Ihor Radchenko <yantar92 <at> posteo.net>
> Date: Sat, 26 Nov 2022 08:41:39 +0000
> 
> I just stumbled upon `ucs-normalize-string' 
> 
> (defmacro ucs-normalize-string (ucs-normalize-region)
>   `(with-temp-buffer
>      (insert str)
>      (,ucs-normalize-region (point-min) (point-max))
>      (buffer-string)))
> 
> It apparently uses undefined variable `str', which does not look right.

It's a macro, not a function.  So STR could come from the code which calls
the macro.  Look how it is used in that file, and you will see what I mean.

> Also, no docstring.

I added a doc string.

Thanks.

Message #13 received at 59603-done <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59603-done <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 09:04:22 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> (defmacro ucs-normalize-string (ucs-normalize-region)
>>   `(with-temp-buffer
>>      (insert str)
>>      (,ucs-normalize-region (point-min) (point-max))
>>      (buffer-string)))
>> 
>> It apparently uses undefined variable `str', which does not look right.
>
> It's a macro, not a function.  So STR could come from the code which calls
> the macro.  Look how it is used in that file, and you will see what I mean.

I understand. But this macro is not private (no --). I feel like using
"str" there is a questionable code style.

>> Also, no docstring.
>
> I added a doc string.

Thanks! The new docstring implies that STR is an argument, doesn't it?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #16 received at 59603 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: 59603 <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 11:23:51 +0200

> From: Ihor Radchenko <yantar92 <at> posteo.net>
> Cc: 59603-done <at> debbugs.gnu.org
> Date: Sat, 26 Nov 2022 09:04:22 +0000
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> >> (defmacro ucs-normalize-string (ucs-normalize-region)
> >>   `(with-temp-buffer
> >>      (insert str)
> >>      (,ucs-normalize-region (point-min) (point-max))
> >>      (buffer-string)))
> >> 
> >> It apparently uses undefined variable `str', which does not look right.
> >
> > It's a macro, not a function.  So STR could come from the code which calls
> > the macro.  Look how it is used in that file, and you will see what I mean.
> 
> I understand. But this macro is not private (no --). I feel like using
> "str" there is a questionable code style.

It's too late to change that: this macro is very old and predates the --
conventions.

> >> Also, no docstring.
> >
> > I added a doc string.
> 
> Thanks! The new docstring implies that STR is an argument, doesn't it?

It doesn't.

Message #19 received at 59603 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59603 <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 09:37:47 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> I understand. But this macro is not private (no --). I feel like using
>> "str" there is a questionable code style.
>
> It's too late to change that: this macro is very old and predates the --
> conventions.

I see.

>> >> Also, no docstring.
>> >
>> > I added a doc string.
>> 
>> Thanks! The new docstring implies that STR is an argument, doesn't it?
>
> It doesn't.

I feel a bit confused now.

I am now reviewing D.6 Tips for Documentation Strings section of Elisp
manual:

   • When a function’s documentation string mentions the value of an
     argument of the function, use the argument name in capital letters
     as if it were a name for that value.  Thus, the documentation
     string of the function ‘eval’ refers to its first argument as
     ‘FORM’, because the actual argument name is ‘form’:

          Evaluate FORM and return its value.

     Also write metasyntactic variables in capital letters, such as when
     you show the decomposition of a list or vector into subunits, some
     of which may vary.  ‘KEY’ and ‘VALUE’ in the following example
     illustrate this practice:

          The argument TABLE should be an alist whose elements
          have the form (KEY . VALUE).  Here, KEY is ...

   • Never change the case of a Lisp symbol when you mention it in a doc
     string.  If the symbol’s name is ‘foo’, write “foo”, not “Foo”
     (which is a different symbol).

I do see that uppercase symbol names may not always refer to the
arguments, but don't `str' fit better into the conventions? It is the
symbol to be used in the macro, after all.
Or do I miss something?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Message #22 received at 59603 <at> debbugs.gnu.org (full text, mbox):

From: Eli Zaretskii <eliz <at> gnu.org>
To: Ihor Radchenko <yantar92 <at> posteo.net>
Cc: 59603 <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 12:10:52 +0200

> From: Ihor Radchenko <yantar92 <at> posteo.net>
> Cc: 59603 <at> debbugs.gnu.org
> Date: Sat, 26 Nov 2022 09:37:47 +0000
> 
> Eli Zaretskii <eliz <at> gnu.org> writes:
> 
> I do see that uppercase symbol names may not always refer to the
> arguments, but don't `str' fit better into the conventions? It is the
> symbol to be used in the macro, after all.
> Or do I miss something?

How else do you suggest to indicate in the doc string that the macro
operates on a variable named 'str'?  Using `str' is much more confusing,
IMO.

Message #25 received at 59603 <at> debbugs.gnu.org (full text, mbox):

From: Ihor Radchenko <yantar92 <at> posteo.net>
To: Eli Zaretskii <eliz <at> gnu.org>
Cc: 59603 <at> debbugs.gnu.org
Subject: Re: bug#59603: 28.1.90; `ucs-normalize-string' fails to work
Date: Sat, 26 Nov 2022 10:16:12 +0000

Eli Zaretskii <eliz <at> gnu.org> writes:

>> I do see that uppercase symbol names may not always refer to the
>> arguments, but don't `str' fit better into the conventions? It is the
>> symbol to be used in the macro, after all.
>> Or do I miss something?
>
> How else do you suggest to indicate in the doc string that the macro
> operates on a variable named 'str'?  Using `str' is much more confusing,
> IMO.

We clearly disagree here. `str' would be more clear for me. Or
explicitly saying that `str' symbol value is used.

In any case, this is a very minor concern. I mostly tried to find if I
am missing something in my understanding of documentation conventions. I
have no strong feelings about this particular change.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Previous Next

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