From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) by sourceware.org (Postfix) with ESMTP id E018C3858CDB for ; Sat, 30 Dec 2023 05:03:55 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org E018C3858CDB Authentication-Results: sourceware.org; dmarc=pass (p=none dis=none) header.from=gentoo.org Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=gentoo.org ARC-Filter: OpenARC Filter v1.0.0 sourceware.org E018C3858CDB Authentication-Results: server2.sourceware.org; arc=none smtp.remote-ip=2001:470:ea4a:1:5054:ff:fec7:86e4 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1703912641; cv=none; b=pub1PT0cW+p8fxCymENRyfdsS1rKbU/LmtfmfcCQ/7+Qw8XhDTbHp/1v4agagVZRzLzP74hp6pXjAgYDN+RtBpOC8A3O3ochCVkSg/FIEU31AopaF04twugeC7v50ihR9tbh5FQ5hFUJXSBbA2McOlB2M2TuazTI0xUBCC39J64= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1703912641; c=relaxed/simple; bh=50/y5rCvX35fFbsJwHN4QQ7Yryw74giVZ1rm7iXIfKw=; h=Date:From:To:Subject:Message-ID:MIME-Version; b=LUWrf4ywUMmcyz/ADZXDa5tmU8ag8DAy5WrytwiXpEnvrvv7QOOAP9PPa/LzaSJoYYit6fQRPELiCJh79rAqennNFHMQpsaTkbwi69YYXXum3Yv1Te2RDm2p+cqWDcENleRXOtuV7m5fLQ8jo9Chell1oX0x6qmhql85OsJQ6cY= ARC-Authentication-Results: i=1; server2.sourceware.org Received: by smtp.gentoo.org (Postfix, from userid 559) id 119CD33BE12; Sat, 30 Dec 2023 05:03:55 +0000 (UTC) Date: Sat, 30 Dec 2023 00:03:53 -0500 From: Mike Frysinger To: C Howland Cc: newlib@sourceware.org Subject: Re: FW: [PATCH] [RFC] newlib: libc: start manual appendix to hold various ABI constants Message-ID: References: <20231227072512.17179-1-vapier@gentoo.org> MIME-Version: 1.0 Content-Type: multipart/signed; micalg=pgp-sha256; protocol="application/pgp-signature"; boundary="qb7fS10ds3WUem1R" Content-Disposition: inline In-Reply-To: X-Spam-Status: No, score=-5.3 required=5.0 tests=BAYES_00,JMQ_SPF_NEUTRAL,KAM_DMARC_STATUS,SPF_HELO_PASS,SPF_PASS,TXREP,T_SCC_BODY_TEXT_LINE autolearn=no autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on server2.sourceware.org List-Id: --qb7fS10ds3WUem1R Content-Type: text/plain; charset=utf-8 Content-Disposition: inline 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 ' | 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 --qb7fS10ds3WUem1R Content-Type: application/pgp-signature; name="signature.asc" -----BEGIN PGP SIGNATURE----- iQIzBAABCAAdFiEEuQK1JxMl+JKsJRrUQWM7n+g39YEFAmWPpLkACgkQQWM7n+g3 9YFw/w/8CR23I9Wq9whgVaMRUKUHRU7WwT7dD+L4b4Hc284xkfAUkepQOVXgNZZo uJ2J4PqYw0+F6u8h4A+SraQnCLBPVbMaU74gyIhEX4+2hU4A5aWXQ5LC+uyBsPOO CmpOTxR2yGFiGuIyaXxw6jK18ppEhUUTSknT3p0Z/TT3HOvFIQdkZjj7xCBOBh5I KObFJ3GqIdV2JajaPUPDcEcR1E6PMUjzRJnoqSv7ILx8a/ErrN0ogqKdtjppBkai 2d6Ozy9vqDmlus61SmLavXIpyi9gyMphc7mL8NgT6Z7B3mAU32jeUhYcQ9CQRwOf j/znJAPnQOqHbPQGjoWWhpwIqKOKmmMLAMnwVNLFV48c02eOBVhJ+TLMJyERv7XY BbrqzG1SX2zSEs27WIlu8rEzGPHF8rLcJ08vD2MPqUoteGhtiunQXt96TdcpR0s2 Us6g/87Az9DX8WkstbHfFn7P0CHLDcCnWJVgbpq7J/fl8h06E9Q9n1vaVBufPDdq MzdMXzrK1yHXZ7ERjC8adEokGF+Be+5ZkcfxI/w/IK3+gsDHaoHVztzu3a9hJGaH wtqRd/b5v0tL5t4yZrDhEvYPdzHovc7PZXP5QTAcpQRG54s52Vys/v4LhuGbsoqJ wt2YPXef5GKsKch0zgB4kW482JdeP1hUUNIL+wzTkWIPGBdl0Q4= =ZWfs -----END PGP SIGNATURE----- --qb7fS10ds3WUem1R--