[BRLTTY] Low-level BrlAPI questions

[Samuel Thibault]

Aura Kelloniemi, le dim. 28 mars 2021 12:05:46 +0300, a ecrit:
> On 2021-03-27 at 15:09 +0100, Samuel Thibault <samuel.thibault at ens-lyon.org> wrote:
>  > Aura Kelloniemi, le sam. 27 mars 2021 01:14:13 +0200, a ecrit:
>  > If you pass UTF-8 text to brlapi_writeText while the locale is non-UTF-8
>  > it will get a bogus result, as expected.
> 
> I just did not know how BrlAPI's character set handling works, and where the
> conversion happens – i.e. is it the caller's locale or the server's locale
> that matters. In my opinion nowadays it would be best that neither locale
> affects the result, and everything would be just UTF-8 (in transport). But I
> understand that backwards compatibility might be a concern.

Some people would still expect brlapi_writeText("Hého"); to
"just work", yes.

>  > There is also brlapi_writeWText which just takes a wchar_t *, so
>  > independent of the locale.
> 
> Except that a portable client cannot know whether wchar_t is 2 or 4 bytes – it
> depends on libc, so I stay away from it.

Well, the compilation environment is supposed to provide by default the
wchar_t type that corresponds to the libc. Of course people can change
that with e.g. -fshort-wchar, but they are supposed to just use the
default parameters provided by the environment.

>  > > Will the given tty path be prepended by tty numbers from other sources – e.g.
>  > > the WINDOWPATH environemnt variable?
> 
>  > It will, yes.
> 
> Doesn't this interfere with the screen reader's ability to control the
> desktop.

The desktop, no. What is underneath the desktop, yes, but screen readers
do not usually want to know about it. Orca does not, for instance.

> However, I notice that setFocus does not take a full path to a TTY
> either, so maybe it is the intent that any screen reader / terminal
> multiplexer manages only one level of TTYs, rather than a whole tree of them.

Yes. They do not want to care, and should not. In the case of a
detachable vnc client, for instance, that would not even make sense (in
that case it would not be only a WINDOWPATH, but a relay proxy that
prepends the tty numbers).

>  > > - Could the BRLAPI_ERROR_... constants form an enum type, or would it break
>  > >   something?
> 
>  > We could do this indeed, we'd still need to define the macros in case
>  > some existing code depends on that.
> 
> Wouldn't such a dependency be a corner case.

It's not so rare to see

#ifdef BRLAPI_ERROR_...
#endif

So better stay compatible with that.

> However, if you retain the macros, I wish that the macros would be initialized
> from the enum variants, and not the other way around, as this is safer
> approach. E.g.

Sure, that's the common approach seen e.g. in glibc headers.

> - Could the brlapi_writeArguments_t struct member pointers be defined as const
>   *?

Indeed, done so.

> - Why do regionSize and textSize have a different type from each other in the
>   above mentioned struct?

As documented, textSize may be set to -1 so it needs to be signed, while
others can be unsigned.

> Shouldn't both of them use size_t?

We could do this but that would change the ABI, better leave this for
next time we really want to break the ABI for a strong reason.
That being said, int is asserted to be at least 16bits, I don't think
we'd ever need to handle > 32767 characters.

> - If the number of code points in text does not match regionSize,
>   brlapi__write does not write anything to the display.

? Aren't you getting an exception?

      CHECKEXC(!sin, BRLAPI_ERROR_INVALID_PACKET, "text too big");
      CHECKEXC(!sout, BRLAPI_ERROR_INVALID_PACKET, "text too small");

are supposed to catch this and raise an exception.

> - Proposal: Could brlapi__write be extended to allow passing text as NULL
>   (without triggering the current effect of releasing the display to the
>   parent client). In this case andMask should also be NULL, and orMask would
>   be used to write a dot pattern to the display.

In my memory I thought it was already the case, but apparently not. That
could possibly be more convenient indeed, see more below.

> - Why does brlapi__writeDots go through all the trouble of decoding the raw
>   dot pattern given by the caller to an UTF-8 sequence? It could just fill the
>   text field with spaces, memset andMask to zero, and use dots as orMask. I
>   have tested this, and it works.

It works for the braille output, but not for the text output, whenever a
braille device has one, that text will remain blank.

That being said, that could be handled on the server side, when
text==NULL we could fill the text part with the unicode patterns.

Samuel