FW: [PATCH] [RFC] newlib: libc: start manual appendix to hold various ABI constants

[brian.inglis@systematicsw.ab.ca]

On 2023-12-29 22:03, Mike Frysinger wrote:
> On 29 Dec 2023 20:17, C Howland wrote:
>>       I won't comment on whether adding this is a good idea or not as I
>> don't meet any of the stated use cases.  But here are a few thoughts on the
>> details of it assuming others like the addition.
> 
> if you only use newlib, it could be helpful.  consider how common it is for
> people to write error messages like:
> 	printf("error %i\n", errno);
> so your log contains "error 13".  how do you find out what errno 13 is ?
> even Linux's `man errno` doesn't list the raw numbers.  having online access
> to the name<->number mappings for these is helpful in a pinch in my experience.

moreutils errno?

	https://joeyh.name/code/moreutils/
	https://repology.org/project/moreutils/versions

- perhaps with creative use of "locales" (or patches) for different library 
sources and board support?

>>       Given the stated purpose it sounds like mapping files might want to be
>> made for some of the scenarios mentioned.  For something like that I'd
>> think most people would want to start with the source code (as opposed to
>> copying from the manual).  With this in mind, adding the Newlib source file
>> path as supplementary information to the values in the manual might make
>> sense as an additional aid.
> 
> the GNU sim script can already extract the code and turn it into structured
> data (e.g. JSON).  it can also turn that into a C file for the generated table.
> i would expect the export-to-JSON to be part of the script for merging into
> newlib so that the people who need access to the ABI in source form can easily
> get it and convert it to whatever format they need.  so the sim would switch to
> running the newlib script to get the JSON, but it would keep the output-to-C
> logic since that's sim-specific.
> 
>>       Thinking a step beyond the stated purpose of making the values
>> available in the manual for mapping purposes, in a bigger-picture view (it
>> is a manual) would it make sense to preserve the descriptive comments in
>> the source, copying them to the manual, too?  (Without seeing the script
>> mechanism being used I can't tell how easy or hard that might be to add.)
> 
> the script is written in Python and uses a preprocessor (e.g. gcc) to dump
> the constants.  gcc has a -CC option to include line-level comments, so this
> is a possibility.  it would require the source be structured in a way where
> the comments are inline which it mostly already is.
> 
>>       It might be better to enhance the wording here a little.
> 
> i half-assed this content to show the general structure.  i'm sure the hand
> written descriptions could use improvement.  i'll take your feedback in once
> i get a signal from the newlib maintainers on this in general.
> 
>> Given today's reality of no printed (vs. electronic) manuals (maybe a rare
>> person that might print a copy), is it worth bothering to present both name
>> and number sorted lists?  (People will just electronically search, making
>> the multiple presentation of essentially no added value.)  Just choose 1
>> and do that only?  (The cost of doing it is low, and choosing numeric or
>> name might be tricky to decide.  But dropping to 1 would reduce electronic
>> search clutter of having the same thing found twice per subsection.
>> Already will be a little bit distracting to have the common/cris/spu
>> sections, twice as bad if each lists both values twice.)
> 
> *shrug* it was easy enough to generate.  i find sorted-by-name helpful when
> i want to see if a specific name is available, perhaps under a slight name
> variant (when i can't remember exactly how it's been abbreviated), and i find
> sorted-by-number helpful when looking up an error number from log output.
> if we only have sorted-by-name, searching for a single digit number is a bit
> of a pita because it'll match numbers in the constant name, in the comment,
> and in the multi-digit errno values.  it's not uncommon for the user agent
> to support only case-insensitive substrings (e.g. Chrome), and needing regex
> just to construct an exact match seems a bit too much for a general manual.
> 
> for example:
> $ gcc -E -P -dD -CC - <<<'#include <errno.h>' | grep 2
> <35 errno matches>
> 
> but it's not something i'm strongly tied to, so if the newlib maintainers
> want to use one or the other, i don't care enough to fight.
> -mike

-- 
Take care. Thanks, Brian Inglis              Calgary, Alberta, Canada

La perfection est atteinte                   Perfection is achieved
non pas lorsqu'il n'y a plus rien à ajouter  not when there is no more to add
mais lorsqu'il n'y a plus rien à retirer     but when there is no more to cut
                                 -- Antoine de Saint-Exupéry