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

[Mike Frysinger <vapier@gentoo.org>]

[-- Attachment #1: Type: text/plain, Size: 4038 bytes --]

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.

>      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

[-- Attachment #2: signature.asc --]
[-- Type: application/pgp-signature, Size: 833 bytes --]