From: brian.inglis@systematicsw.ab.ca
To: newlib@sourceware.org
Subject: Re: FW: [PATCH] [RFC] newlib: libc: start manual appendix to hold various ABI constants
Date: Tue, 23 Jan 2024 14:05:17 -0700 [thread overview]
Message-ID: <98c7546a-2caf-4492-b5e8-882f5d867262@systematicsw.ab.ca> (raw)
In-Reply-To: <ZY-kuVCUZhTeyNp-@vapier>
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
next prev parent reply other threads:[~2024-01-23 21:05 UTC|newest]
Thread overview: 6+ messages / expand[flat|nested] mbox.gz Atom feed top
2023-12-27 7:25 Mike Frysinger
[not found] ` <BN2P110MB15445C61D8D69733C10DA4D99A9CA@BN2P110MB1544.NAMP110.PROD.OUTLOOK.COM>
2023-12-30 1:17 ` FW: " C Howland
2023-12-30 5:03 ` Mike Frysinger
2024-01-23 21:05 ` brian.inglis [this message]
2024-01-24 4:37 ` Mike Frysinger
2024-01-23 9:15 ` Corinna Vinschen
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=98c7546a-2caf-4492-b5e8-882f5d867262@systematicsw.ab.ca \
--to=brian.inglis@systematicsw.ab.ca \
--cc=newlib@sourceware.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).