Re: new:mbrtoc32.3: convert from to c32

["Alejandro Colomar (man-pages)" <alx.manpages@gmail.com>]

Hi,

On 7/5/21 11:09 PM, Radisson wrote:
> 
> 
> Am 05.07.21 um 21:07 schrieb Alejandro Colomar (man-pages):
>> Hello Bruno,
>>
>> On 7/4/21 12:26 PM, Bruno Haible wrote:
>>>> mbrtoc32, c32rtomb \- convert between multibyte sequence and 32-bit
>>>> wide character
>>>
>>> I would suggest two separate man pages for these functions.
>>> Rationale:
>>> It is rare that some code uses mbrtoc32 and c32rtomb in the same
>>> function.
>>> (Basically, functions that do input call mbrtoc32, and functions that do
>>> output call c32rtomb.) And the description of mbrtoc32 is a bit complex.
>>
>> Okay.  Indeed, the *wc* functions are documented separately.
> 
> I beg your pardon,
> we do not write a program, for the understanding of the function i found
> it much helpful to see the from-to connection.

No pardon needed :)
I don't have any strong feelings about how it should be organized in 
files.  There are 3 ways I see:

a) mbrtoc32 & mbrtowc together;  c32tombr & wctombr together
b) each one in a separate page
c) mbrtoc32 & c32tombr together;  mbrtowc separate from wctombr (as is now)

If you think any one is especially better than the rest, do it.


What I would like to especially make clear is the similarities and 
differences between those 2 sets of functions.  And not rewrite 
everything from scratch, because that causes 2 main problems:

* Maintainability: maintatining different pages that say the same in 
different ways is not a good thing, IMO.
* Confusion: Readers of the page may get the impression that the 2 sets 
of functions are considerably different if they are documented differently.

Thanks,

Alex

> 
>>
>>>
>>>> Are there any important differences compared to the already-documented
>>>> and C99-compliant mbrtowc(3) and wcrtomb(3)?  I mean, apart from the
>>>> types of the parameters. >
>>> No for c32rtomb, but yes for mbrtoc32: mbrtowc has the special return
>>> values (size_t)-1 and (size_t)-2, whereas mbrtoc32 also has the special
>>> return value (size_t)-3. Although, on glibc currently this special
>>> return value (size_t)-3 cannot occur. But IMO the man page should
>>> mention it nevertheless, otherwise people write code that is not
>>> future-proof.
>>
>> Thanks for those details!
>>
>> Regards,
>>
>> Alex
>>
>>


-- 
Alejandro Colomar
Linux man-pages comaintainer; https://www.kernel.org/doc/man-pages/
http://www.alejandro-colomar.es/