From patchwork Sat Jul 25 11:48:24 2026 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Andrew Burgess X-Patchwork-Id: 139937 Return-Path: X-Original-To: patchwork@sourceware.org Delivered-To: patchwork@sourceware.org Received: from vm01.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id 8C6FF4BA2E18 for ; Sat, 25 Jul 2026 11:49:10 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 8C6FF4BA2E18 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 X-Original-To: binutils@sourceware.org Delivered-To: binutils@sourceware.org Received: from us-smtp-delivery-124.mimecast.com (us-smtp-delivery-124.mimecast.com [170.10.133.124]) by sourceware.org (Postfix) with ESMTP id 8D1884BA2E0B for ; Sat, 25 Jul 2026 11:48:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 8D1884BA2E0B 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 8D1884BA2E0B Authentication-Results: sourceware.org; arc=none smtp.remote-ip=170.10.133.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 8D1884BA2E0B 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-f69.google.com (mail-wr1-f69.google.com [209.85.221.69]) by relay.mimecast.com with ESMTP with STARTTLS (version=TLSv1.3, cipher=TLS_AES_256_GCM_SHA384) id us-mta-232-SoKtZWbfOKyDBGMLvayehg-1; Sat, 25 Jul 2026 07:48:30 -0400 X-MC-Unique: SoKtZWbfOKyDBGMLvayehg-1 X-Mimecast-MFC-AGG-ID: SoKtZWbfOKyDBGMLvayehg_1784980109 Received: by mail-wr1-f69.google.com with SMTP id ffacd0b85a97d-47f4bff865cso677287f8f.0 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=ayZp8rtHFmwVcW7NaBcjuyrSII37NGF/follVWEyvbsp602QHwVQskdD+hU+chUK28 MHfyLMoELaOEUhQ66evljY72W0Cc0GAwQ4g99mazTZA8qJCQzIFCEpaRU1w709RRaREb 1J9+uyImVxUVyxaWUPFYaJnQOoZT+6QsSafFf1WZN6kuqN4S8D5sd5RV+5Js/5IPHeDP 51NHZ/+lqjV2HgAqDpsipG7OMmgguNtEZAyZMdPdLqmBvWOL15h2abPOm/C4BPh/lDqz bXhROHUTAuHFyNEhEKabJWm2WbUeb41WDT5xTqwVoUUXtwxG3aR4kW95rFdEE2FXR0By LHTg== X-Forwarded-Encrypted: i=1; AHgh+RpMIdbb2uegUXi0vDqzNWKIH882FqaxQJ8wzQ1RQiKEFdTKdlG3QMMreRxyx+sER5qPnvu6trMUpg==@sourceware.org X-Gm-Message-State: AOJu0YwebNGRNJamr6a/xC1YLXdg5jUmICmx/xUzBXswm2wDi5pM/bry mG/hjroMZeaR0enKKtv0S7wvECyl6L8HWwKedMzSone6ojHIq33LWRJeeankLrwehPqHhhySScj W/injuwoWijM70tG4bHCENiOQrBM8LPIvFnPijb4E7E3EwQzkGFyr23aD2kscqJBuV9I= X-Gm-Gg: AR+sD10c6flWRNPw843Hv1UakX/2NvwpoGZthjyDAZTNttwm1SBoxgqj2m575+CyEXm b4AFHJ6F5oif779vvqD3s+OswVP/oUAegEBDgpjVFKNgm4uHO7VfIBjwQThIzPUUnbJ21jTduUZ diQwhp1dFHYsqxY0cFRsbhBPbAhXn9kwmTYvXIcrIiBUJFOwUevPXA+jDB/a84tx0oK2NwgfREH Zui9SUeYFxu3U8A31tIBnA2wzKmGhqUmQPxebbD/oiHa6NLCRCGcfo3AnAr4mvw0ZwdJUJc3Mlp am2QkkOjVAZLAmOUrssaaBqrwJs16WCqTA4nN+D7s+eHnlgT3Im+ypMqBc6an0VJPer8ze8vTDp Jt+34ScO3ytuwIf2uiWfrvg== X-Received: by 2002:a05:6000:2387:b0:475:f0f0:9ef7 with SMTP id ffacd0b85a97d-47f9feae1aamr1977945f8f.60.1784980108955; 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: SxwZu1VSOiScpMIW05ouyZfONfYmXISTskpO5tm4hI4_1784980109 X-Mimecast-Originator: redhat.com content-type: text/plain; charset="US-ASCII"; x-default=true X-Spam-Status: No, score=-14.7 required=5.0 tests=BAYES_00, DKIMWL_WL_HIGH, DKIM_SIGNED, DKIM_VALID, DKIM_VALID_AU, DKIM_VALID_EF, GIT_PATCH_0, RCVD_IN_DNSWL_NONE, RCVD_IN_MSPIKE_H3, RCVD_IN_MSPIKE_WL, RCVD_IN_PBL, SPF_HELO_PASS, SPF_NONE, TXREP shortcircuit=no autolearn=ham autolearn_force=no version=3.4.6 X-Spam-Checker-Version: SpamAssassin 3.4.6 (2021-04-09) on sourceware.org X-BeenThere: binutils@sourceware.org X-Mailman-Version: 2.1.30 Precedence: list List-Id: Binutils mailing list List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Errors-To: binutils-bounces~patchwork=sourceware.org@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 base-commit: 5be71a6445ce90a1dec06a68aab2b62639036811 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;