[BRLTTY] Low-level BrlAPI questions

[Aura Kelloniemi]

Hello, and may your Sunday be the most beautiful,

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.

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

 > We could add a brlapi_writeUTF8Text if needed.

I don't need it, as the generic write function allows to define character set.
But maybe somebody else needs, and maybe they ask for it, if they do.

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

 > > - 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. Turning a macro to an enum
variant does not interfere with using it as an rvalue which is the intended
use case.

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.

enum brlapi_error_t {
    BRLAPI_ERROR_SUCCESS = 0,
    BRLAPI_ERROR_...
}

#define BRLERR_SUCCESS BRLAPI_ERROR_SUCCESS
#define BRLERR_... BRLAPI_ERROR_...

This would allow safely importing the enum to Rust (or other languages) as is,
without worrying about possible holes or duplicates in the value range of brlapi_error_t.

Again I have some additional questions. This time they are mostly about the
brlapi__write function:

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

- Why do regionSize and textSize have a different type from each other in the
  above mentioned struct? Shouldn't both of them use size_t?

- If the number of code points in text does not match regionSize,
  brlapi__write does not write anything to the display. I think that
  brlapi__write should either write as much of the text as possible (with the
  masks applied), pad the text with blanks to fill the region, or preferably
  signal an error to the caller.
  
- 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. This would be very beneficial
  for clients who only want to write dot patterns. If text, andMask and
  orMask would all be NULL, or the whole argument pointer is NULL, previous
  output would be discarded and display would be released to the parent.

- 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. If my proposal from the previous chapter
  would be accepted, brlapi__writeDots could just set text to NULL and pass
  only orMask.

Thanks again for answers!

-- 
Aura