Subject: Re: bug#64696: 30.0.50; indent-to inherits preceding text properties, including 'invisible

From: Eli Zaretskii <[email-masked]>
Date: Sun, 30 Jul 2023 20:11:51 +0300

> From: Ihor Radchenko <[email-masked]>
> Cc: [email-masked], [email-masked]
> Date: Sun, 30 Jul 2023 11:45:20 +0000
> 
> Eli Zaretskii <[email-masked]> writes:
> 
> > There's a limit to which a doc string can describe every single
> > subtlety of a non-trivial implementation, and still remain useful.  If
> > someone needs to know about these aspects (presumably because their
> > Lisp program does something very special, because otherwise these
> > things "just work"), they should either read the source or ask here,
> > because they basically use string-width outside of its main usage
> > domain.
> 
> I personally feel confused when looking at the available width
> calculation in Emacs: `string-width', `string-pixel-width',
> `window-text-pixel-size', `length' are all different, and sometimes in
> subtle (and undocumented) ways. For me, the best way to resolve the
> confusion would be more detailed docstrings that explain the
> limitations. I have no better ideas.

string-pixel-width and window-text-pixel-size are different varieties
of the same basic primitive.  Other than that, each of the functions
you mentioned serve a different purpose; in particular, 'length' is
entirely unrelated to the display width of a string.  When each API is
used for its purpose, there's no confusion and no subtleties, because
each one of them does its job, and the subtleties should not matter.
It's only when you want them to do some job they were not directly
designed for that the subtleties become important.  But your
insistence on documenting all of those technicalities is not TRT: it
will just make the documentation much harder to understand and use for
those who do use these APIs for their advertised purposes.

> 1. "When calculating width of a multibyte character in STRING, only the
>    base leading-code is considered; the validity of the following bytes
>    is not checked."

Remnant from a very distant past; ignore it.

> 2. "Tabs in STRING are always taken to occupy tab-width columns."
> 
>    "always" in the above is not accurate when buffer-display-table
>    replaces <TAB> display. Is it considered subtlety?

No, "always" disregarding the column where the TAB will be displayed.
A TAB that begins on column zero will be 8 columns wide; a TAB that
begins on column 5 will be only 3 columns wide.

> 3. "The effect of faces and fonts used for non-Latin and other unusual
>    characters (such as emoji) is ignored as well"
> 
>    Is the effect of faces not ignored for Latin characters?

The default face's font covers those, and if it's a fixed-pitch font,
the character width stored in char-width-table is adequate.

> 4. "... , as are display properties and invisible text"
> 
>    What about other properties? Like 'line-prefix. Maybe "all the text
>    properties are ignored"?

line-prefix doesn't affect the width of the string itself.

"All the text properties" is incorrect: at least 'composition' and
'invisible' aren't ignored.

> 5. "For these reasons, the results are not generally reliable;"
> 
>    This sounds like "this function is not useful".

I've now reworded that part.