From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id 8puzJa2iZGr5zywAWB0awg (envelope-from ) for ; Sat, 25 Jul 2026 07:49:01 -0400 Authentication-Results: simark.ca; dkim=pass (1024-bit key; unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=M/IpHSoa; dkim-atps=neutral Received: by simark.ca (Postfix, from userid 112) id 817CA1E099; Sat, 25 Jul 2026 07:49:01 -0400 (EDT) X-Spam-Checker-Version: SpamAssassin 4.0.1 (2024-03-25) on simark.ca X-Spam-Level: X-Spam-Status: No, score=-6.4 required=5.0 tests=ARC_SIGNED,ARC_VALID,BAYES_00, DKIMWL_WL_HIGH,DKIM_SIGNED,DKIM_VALID,DKIM_VALID_AU,MAILING_LIST_MULTI, RCVD_IN_DNSWL_MED autolearn=ham autolearn_force=no version=4.0.1 Received: from vm01.sourceware.org (vm01.sourceware.org [IPv6:2620:52:6:3111::32]) (using TLSv1.3 with cipher TLS_AES_256_GCM_SHA384 (256/256 bits) key-exchange x25519 server-signature ECDSA (prime256v1) server-digest SHA256) (No client certificate requested) by simark.ca (Postfix) with ESMTPS id 704581E099 for ; Sat, 25 Jul 2026 07:49:00 -0400 (EDT) Received: from vm01.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id E06314BA2E0B for ; Sat, 25 Jul 2026 11:48:58 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org E06314BA2E0B Authentication-Results: sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=M/IpHSoa Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.129.124]) by sourceware.org (Postfix) with ESMTP id 929674BA2E0E for ; Sat, 25 Jul 2026 11:48:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 929674BA2E0E Authentication-Results: sourceware.org; dmarc=pass (p=quarantine dis=none) header.from=redhat.com Authentication-Results: sourceware.org; spf=pass smtp.mailfrom=redhat.com ARC-Filter: OpenARC Filter v1.0.0 sourceware.org 929674BA2E0E Authentication-Results: sourceware.org; arc=none smtp.remote-ip=170.10.129.124 ARC-Seal: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1784980112; cv=none; b=dbkR8fNybEdPog9pcW9bE/uMRtQRtSBdWQUjT5idX5Sizf9PIY7o4EGmOeAP0WuE/ESVF2w5sVHD5IAi4NHfyeP/wZdTObBgNsFNijAl75AJq4IGc5K1CswcBH2ym1qmf7QjGW30lQkfvyn3LKGWnv7bw1vgxSLpZWjLdnDWSiQ= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1784980112; c=relaxed/simple; bh=CIE3ixigSonWQQKb4koKnlDT5/ri4E82c+U3+PPmfWE=; h=DKIM-Signature:From:To:Subject:Date:Message-Id:MIME-Version; b=PBVwtNXtIj2/uLLnWAQjMQLPwnPJrmlcxLnXfWHtn14SCdDzI/OLAGmrKkc3PXI1HEHqzWaTmveUmri9pMPLsi7ezrQuGwXF9jPftPIesTUzSxQr4VVIq1KKbxflZII9T390/TPoSld63jb9HyvFiaP+dueVBIRfmjxQyixgjJI= ARC-Authentication-Results: i=1; sourceware.org; dkim=pass (1024-bit key, unprotected) header.d=redhat.com header.i=@redhat.com header.a=rsa-sha256 header.s=mimecast20190719 header.b=M/IpHSoa DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 929674BA2E0E DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1784980112; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:cc:mime-version:mime-version:content-type:content-type: content-transfer-encoding:content-transfer-encoding; bh=pFkRdV3mZ9PRt11WsSjJcuZMPpRgQLBnSbSyfrZLOqE=; b=M/IpHSoa3UNS/R/qDWiJydtICPG8cvg67OFEyLkBH8fruF2Vel1mZ5zFecoruRu0z4W568 vJqnM3hDLma8EYcqTdq7X5Qymnkcvjf0RVxIDNufJXEFZHL+nKvMGoeEKDlY36sw99I7TY BvhHyD4GDPBX7wnlmnBxGCru+ySQKBA= Received: from mail-wr1-f70.google.com (mail-wr1-f70.google.com [209.85.221.70]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-447-_58Yg-Y9NSq4hvFB6riU6A-1; Sat, 25 Jul 2026 07:48:30 -0400 X-MC-Unique: _58Yg-Y9NSq4hvFB6riU6A-1 X-Mimecast-MFC-AGG-ID: _58Yg-Y9NSq4hvFB6riU6A_1784980109 Received: by mail-wr1-f70.google.com with SMTP id ffacd0b85a97d-47f6d70223dso780549f8f.1 for ; Sat, 25 Jul 2026 04:48:30 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1784980109; x=1785584909; h=content-transfer-encoding:mime-version:message-id:date:subject:cc :to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to:content-type; bh=pFkRdV3mZ9PRt11WsSjJcuZMPpRgQLBnSbSyfrZLOqE=; b=O1z3KiDUe1KAA92s4rUPNKyrEYoZlF6ZuP1RJaTnnE5BvUZQ5A/qrZtMgS/SK/aibr yiaCt2JSlZf8vyYoo0W89IY9EZmjoTWWSQ7SM3EuUMhb7hojjESLNAZgeEfnvQH42iWy Xas5Knh0Wd5jDW+ThKz8v4eDWfOlRiQPjdeeIpqTwv6HccP9bIyWYeh/DoP45Fx9pDh/ sVdtVr/GE8oyyF7jHs5z1gseE6hZcuoCr+moBORUl57pQGeDo24/w6RjFIworz+wuPNo hFwD9xa1u1q1U+2L3mia4wOYuDhmiF+OlEeKkbIs4KLvCQe+vuJYyrGB+donwy+OZpEX EcSg== X-Gm-Message-State: AOJu0Yxe7cnYdnjvzQEwBgdudnvdnJTZLWw+6cNi7hg6/CqCoozUgt0X Rman7q0+GtFT9zbMwHGkDdglhuS7DMWmX0Liu9aIOIshLMDUUCdoqVTM2MGIFvd8i1TLBEzffu6 NuMr+tGwAgsgaLwNfDMhVJ6S2tTRnOGlxdGhivZaDyhK0pLiq4BblqLCmPIzuytll8x7g1Wkv83 vklQmIzvNvPTjJtJjPEqCUhMA262wNBZR2spbkNsAmLlA+z4U= X-Gm-Gg: AR+sD13FrqbT+V1x+EXfYJD7Cx4ijLxqS2Q7czlVCAWfBxRX3jGHVTQfzL/Vk90UBEu nS1cMNIgr9tnmVDIzTUNnA2vcBVdpOW3UH9DdbgRIUIDC3SlwXsTN+GLIxEZq7XTgttAW69k3DQ /zkUspu+Zl4o/ItWNKUVqFNnUvPLd/9or9BkZ4nMrftyvrquFsVJZW8pAUTF3GwXU3IzPuoBFti LyfkWBI+YzSGzXVpYl7VpZULVtqhNhQTwtKpTJH5Jp54BKUkPENls3WHaV5t1Gyuq+Bpf8Kvwd6 orNMgIJjSe7NDJg8BgjCKIW9Q9sGwC/nX9anXr0N/odr3fFnhw9d8NyezLMdWHsgmw4UBEHtfvq Wfw55bliExd3TNcJixbzC9A== X-Received: by 2002:a05:6000:2387:b0:475:f0f0:9ef7 with SMTP id ffacd0b85a97d-47f9feae1aamr1977948f8f.60.1784980108994; Sat, 25 Jul 2026 04:48:28 -0700 (PDT) X-Received: by 2002:a05:6000:2387:b0:475:f0f0:9ef7 with SMTP id ffacd0b85a97d-47f9feae1aamr1977931f8f.60.1784980108484; Sat, 25 Jul 2026 04:48:28 -0700 (PDT) Received: from localhost (92.40.184.86.threembb.co.uk. [92.40.184.86]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-47f85c531basm33520807f8f.19.2026.07.25.04.48.27 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Sat, 25 Jul 2026 04:48:28 -0700 (PDT) From: Andrew Burgess To: gdb-patches@sourceware.org, binutils@sourceware.org Cc: Andrew Burgess Subject: [PATCH] etc: import changes to texi2pod.pl from gcc Date: Sat, 25 Jul 2026 12:48:24 +0100 Message-Id: <91dfc026f843cfb510445198bbc9b63552b04e4a.1784980082.git.aburgess@redhat.com> X-Mailer: git-send-email 2.25.4 MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: iss7E9VeFgFeUU8RFmtir2v_KM03l47vap34DP4Zdpk_1784980109 X-Mimecast-Originator: redhat.com Content-Transfer-Encoding: 8bit content-type: text/plain; charset="US-ASCII"; x-default=true X-BeenThere: gdb-patches@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Gdb-patches mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: gdb-patches-bounces~public-inbox=simark.ca@sourceware.org I was looking at making some cleanup in the GDB documentation and I ran into a limitation of the texi2pod.pl script, it is not able to correctly format: '@option{--text}' or '@table @option'. Patching our copy of texi2pod.pl is easy enough, but it is probably better to just sync with gcc's version of the script, which already has some @option support in place. I took the version from gcc commit b5e6f5d2d43 -- that's is reasonably close to gcc's current HEAD. I then checked that the man pages for gcc, gas, binutils, ld, gprof, and gprofng all regenerated without any changes. Unfortunately that wasn't the case, so I had to add back some local changes: 1. Support for the --no-split option, see binutils-gdb commit 96a7037cd8573cf065aa6b12baca68696f96d9ca. 2. Add support for TARGET as a man page section, see binutils-gdb commit 6387924ae329fe2a89abb48b9868a340e23a9630. 3. Revert gcc commit 386c402747d2bc6bad3e1bc2f9383d4d669576e0 to allow our lists to be correctly formatted again. I suspect item (3) could be better fixed by understanding the original gcc issue and crafting a smarter solution that both solves gcc's original issue while also allowing our lists to be formatted correctly. However, given we've managed without (3) for years, and I need to make some local fixes anyway, I propose just removing that small part. At least for now. I also noticed that though gcc's texi2pod.pl script does support '@option{--text}', it doesn't support '@table @option'. Adding support for this is trivial, so I've also made this fix too. I have posted this fix to the gcc-patches mailing list, so hopefully it will be accepted and merged there soon. The gcc patch can be found here: https://inbox.sourceware.org/gcc-patches/a666f5b366e1e25d6e68fe05714b458155cc9da1.1784978927.git.aburgess@redhat.com One final note, this import from gcc changes the licence on the texi2pod.pl script from GPLv2 to GPLv3. As I understand it, GPL allows for this roll forward, and most of binutils-gdb is under GPLv3, so I don't see this being a problem. --- etc/texi2pod.pl | 53 +++++++++++++++++++++++++++++++++++++------------ 1 file changed, 40 insertions(+), 13 deletions(-) mode change 100644 => 100755 etc/texi2pod.pl diff --git a/etc/texi2pod.pl b/etc/texi2pod.pl old mode 100644 new mode 100755 index f1b1efe6807..7b6ece22269 --- a/etc/texi2pod.pl +++ b/etc/texi2pod.pl @@ -6,7 +6,7 @@ # GCC is free software; you can redistribute it and/or modify # it under the terms of the GNU General Public License as published by -# the Free Software Foundation; either version 2, or (at your option) +# the Free Software Foundation; either version 3, or (at your option) # any later version. # GCC is distributed in the hope that it will be useful, @@ -166,6 +166,7 @@ while(<$inf>) { $ic = pop @icstack; } elsif ($ended eq "multitable") { $_ = "\n=back\n"; + $ic = pop @icstack; } else { die "unknown command \@end $ended at line $.\n"; } @@ -211,18 +212,23 @@ while(<$inf>) { s/\@TeX\{\}/TeX/g; s/\@pounds\{\}/\#/g; s/\@minus(?:\{\})?/-/g; + s/\@tie\{\}/ /g; s/\\,/,/g; # Now the ones that have to be replaced by special escapes # (which will be turned back into text by unmunge()) + # Replace @@ before @{ and @} in order to parse @samp{@@} correctly. s/&/&/g; + s/\@\@/&at;/g; s/\@\{/{/g; s/\@\}/}/g; - s/\@\@/&at;/g; + s/\@`\{(.)\}/&$1grave;/g; - # Inside a verbatim block, handle @var specially. + # Inside a verbatim block, handle @var, @samp and @url specially. if ($shift ne "") { s/\@var\{([^\}]*)\}/<$1>/g; + s/\@samp\{([^\}]*)\}/"$1"/g; + s/\@url\{([^\}]*)\}/<$1>/g; } # POD doesn't interpret E<> inside a verbatim block. @@ -252,7 +258,7 @@ while(<$inf>) { next; }; - /^\@(?:section|unnumbered|unnumberedsec|center)\s+(.+)$/ + /^\@(?:section|unnumbered|unnumberedsec|center|heading)\s+(.+)$/ and $_ = "\n=head2 $1\n"; /^\@subsection\s+(.+)$/ and $_ = "\n=head3 $1\n"; @@ -286,7 +292,9 @@ while(<$inf>) { /^\@multitable\s.*/ and do { push @endwstack, $endw; + push @icstack, $ic; $endw = "multitable"; + $ic = ""; $_ = "\n=over 4\n"; }; @@ -295,10 +303,11 @@ while(<$inf>) { push @icstack, $ic; $endw = $1; $ic = $2; - $ic =~ s/\@(?:samp|strong|key|gcctabopt|env)/B/; + $ic =~ s/\@(?:samp|strong|key|option|gcctabopt|env)/B/; $ic =~ s/\@(?:code|kbd)/C/; $ic =~ s/\@(?:dfn|var|emph|cite|i)/I/; $ic =~ s/\@(?:file)/F/; + $ic =~ s/\@(?:asis)//; $_ = "\n=over 4\n"; }; @@ -309,11 +318,13 @@ while(<$inf>) { $_ = ""; # need a paragraph break }; - /^\@item\s+(.*\S)\s*$/ and $endw eq "multitable" and do { + /^\@(headitem|item)\s+(.*\S)\s*$/ and $endw eq "multitable" and do { @columns = (); - for $column (split (/\s*\@tab\s*/, $1)) { + $item = $1; + for $column (split (/\s*\@tab\s*/, $2)) { # @strong{...} is used a @headitem work-alike $column =~ s/^\@strong\{(.*)\}$/$1/; + $column = "I<$column>" if $item eq "headitem"; push @columns, $column; } $_ = "\n=item ".join (" : ", @columns)."\n"; @@ -321,8 +332,18 @@ while(<$inf>) { /^\@itemx?\s*(.+)?$/ and do { if (defined $1) { - # Entity escapes prevent munging by the <> processing below. - $_ = "\n=item $ic\<$1\>\n"; + if ($ic) { + if ($endw eq "enumerate") { + $_ = "\n=item $ic $1\n"; + $ic =~ s/(\d+)/$1 + 1/eg; + } else { + # Entity escapes prevent munging by the <> + # processing below. + $_ = "\n=item $ic\<$1\>\n"; + } + } else { + $_ = "\n=item $1\n"; + } } else { $_ = "\n=item $ic\n"; $ic =~ y/A-Ya-y/B-Zb-z/; @@ -376,13 +397,15 @@ sub postprocess # Formatting commands. # Temporary escape for @r. s/\@r\{([^\}]*)\}/R<$1>/g; + s/\@sc\{([^\}]*)\}/\U$1/g; s/\@(?:dfn|var|emph|cite|i)\{([^\}]*)\}/I<$1>/g; s/\@(?:code|kbd)\{([^\}]*)\}/C<$1>/g; - s/\@(?:gccoptlist|samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g; - s/\@sc\{([^\}]*)\}/\U$1/g; + s/\@(?:samp|strong|key|option|env|command|b)\{([^\}]*)\}/B<$1>/g; + s/\@acronym\{([^\}]*)\}/\U$1/g; s/\@file\{([^\}]*)\}/F<$1>/g; s/\@w\{([^\}]*)\}/S<$1>/g; s/\@(?:dmn|math)\{([^\}]*)\}/$1/g; + s/\@\///g; s/\@t\{([^\}]*)\}/$1/g; # keep references of the form @ref{...}, print them bold @@ -395,14 +418,13 @@ sub postprocess # Cross references are thrown away, as are @noindent and @refill. # (@noindent is impossible in .pod, and @refill is unnecessary.) # @* is also impossible in .pod; we discard it and any newline that - # follows it. Similarly, our macro @gol must be discarded. + # follows it. s/\(?\@xref\{(?:[^\}]*)\}(?:[^.<]|(?:<[^<>]*>))*\.\)?//g; s/\s+\(\@pxref\{(?:[^\}]*)\}\)//g; s/;\s+\@pxref\{(?:[^\}]*)\}//g; s/\@noindent\s*//g; s/\@refill//g; - s/\@gol//g; s/\@\*\s*\n?//g; # Anchors are thrown away @@ -415,6 +437,10 @@ sub postprocess s/\@uref\{([^\},]*),([^\},]*)\}/$2 (C<$1>)/g; s/\@uref\{([^\},]*),([^\},]*),([^\},]*)\}/$3/g; + # Handle gccoptlist here, so it can contain the above formatting + # commands. + s/\@gccoptlist\{([^\}]*)\}/B<$1>/g; + # Un-escape <> at this point. s/<//g; @@ -448,6 +474,7 @@ sub unmunge # Replace escaped symbols with their equivalents. local $_ = $_[0]; + s/&(.)grave;/E<$1grave>/g; s/</E/g; s/>/E/g; s/{/\{/g; base-commit: 5be71a6445ce90a1dec06a68aab2b62639036811 -- 2.25.4