bug#59603: 28.1.90; `ucs-normalize-string' fails to work

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Ihor Radchenko]

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>

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@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.

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Ihor Radchenko]

Eli Zaretskii <eliz@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>

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 59603-done@debbugs.gnu.org
> Date: Sat, 26 Nov 2022 09:04:22 +0000
> 
> Eli Zaretskii <eliz@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.

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Ihor Radchenko]

Eli Zaretskii <eliz@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>

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Eli Zaretskii]

> From: Ihor Radchenko <yantar92@posteo.net>
> Cc: 59603@debbugs.gnu.org
> Date: Sat, 26 Nov 2022 09:37:47 +0000
> 
> Eli Zaretskii <eliz@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.

bug#59603: 28.1.90; `ucs-normalize-string' fails to work

[Ihor Radchenko]

Eli Zaretskii <eliz@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>