From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from simark.ca by simark.ca with LMTP id pnbcBYkbc2oaeQkAWB0awg (envelope-from ) for ; Wed, 05 Aug 2026 07:16:25 -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=ZG2yKnBd; dkim-atps=neutral Received: by simark.ca (Postfix, from userid 112) id 06CA51E09B; Wed, 05 Aug 2026 07:16:25 -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 C18661E09B for ; Wed, 05 Aug 2026 07:16:22 -0400 (EDT) Received: from vm01.sourceware.org (localhost [IPv6:::1]) by sourceware.org (Postfix) with ESMTP id CCF424B99F55 for ; Wed, 5 Aug 2026 11:16:21 +0000 (GMT) DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org CCF424B99F55 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=ZG2yKnBd 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 0489B4BAE7E6 for ; Wed, 5 Aug 2026 11:15:32 +0000 (GMT) DMARC-Filter: OpenDMARC Filter v1.4.2 sourceware.org 0489B4BAE7E6 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 0489B4BAE7E6 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=1785928533; cv=none; b=EK+u2LDvmsgzP9W4lhTztROxJLNDxyzcDCufOApWAmNYt/Uljta9PLIdq3Tt76pGtkxzkMJeyOO3tMg1/GNCMjRwwXa5XDd0wzXgvbw/+rPKXwlaksKtmFdXdE1SzDl8NtCDJ+fgSzt1VHeGxNP8a6nORogxItCUrkUGLGhqvv8= ARC-Message-Signature: i=1; a=rsa-sha256; d=sourceware.org; s=key; t=1785928533; c=relaxed/simple; bh=HHgB3F0Gdxv9WDZibwcCTvDtAgcXiOtUip5Iq23OVJA=; h=DKIM-Signature:From:To:Subject:Date:Message-ID:MIME-Version; b=PpHZQRTjePJWAV/y2h4bqendh5/leyR2axWbHNn0mOXA8SwcW/VN5UgoM5TtCnHmJ14F0ORGAxi8D2kiH/zyWfeuTN2Hv9klgCY6hMGGhRnsv06KB1O30DacsVkt9zcMh6/GKbV92m/zkFwl+RKY3agVJdI5gCEhUfnfkhm6Q1k= 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=ZG2yKnBd DKIM-Filter: OpenDKIM Filter v2.11.0 sourceware.org 0489B4BAE7E6 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=redhat.com; s=mimecast20190719; t=1785928532; h=from:from:reply-to:subject:subject:date:date:message-id:message-id: to:to:cc:mime-version:mime-version:content-type:content-type: in-reply-to:in-reply-to:references:references; bh=69jliq5A5jmKTGNvEsrzz3dlHDs6vhRqtDVVqspsIwk=; b=ZG2yKnBd0rF3fLn6JwZviNF5ci9YOeISE6K6H5Gfe4i05PVEuUvBsCwXJBx2EIyZwzJoSi G/ZHK6Sab21R2mUUVnO32FPDDIZ2zcQqbqOraY0jyTMyne6ye/bbTwJ6oJ8hTOWcIBSIB1 Ln/dAILmGFcHfHFch4rWm2HtGasUoJA= 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-267-czTmeW3lMEm37x3m_-cvng-1; Wed, 05 Aug 2026 07:15:26 -0400 X-MC-Unique: czTmeW3lMEm37x3m_-cvng-1 X-Mimecast-MFC-AGG-ID: czTmeW3lMEm37x3m_-cvng_1785928525 Received: by mail-wr1-f70.google.com with SMTP id ffacd0b85a97d-47f81362fb1so503313f8f.1 for ; Wed, 05 Aug 2026 04:15:25 -0700 (PDT) X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20251104; t=1785928525; x=1786533325; h=content-type:mime-version:message-id:date:references:in-reply-to :subject:to:from:x-gm-gg:x-gm-message-state:from:to:cc:subject:date :message-id:reply-to:content-type; bh=69jliq5A5jmKTGNvEsrzz3dlHDs6vhRqtDVVqspsIwk=; b=biM6Iw2jxLBZvO+Q14Y9HiDCGEEcmhDDWX43sO73DD1Z8Gddi8Ur9fN0UqzUSZtguu BTaBuoayeKJFvKWs82vNzu0aGpwGmQxVYN/QBCJeXJFJp58q7H00Ppx664cX8Onn+dvz CMXhZPb+hle4EkSOR06vrWvsdD/HS/BdDUXdvseezZ6rxIQXVUBSMMLcwKaBdu4HOKsr H7kBd08ddeSPTSJjQcVnYNs2k+/Y5DgAXv6fFvAkWngif1MtV5aELk51ckpY4g5Y6eYo QcMZrrZHCsOTkQN8fWSErg2wRM4j7L/+RRft3dgvBzeTG61NRhR0JD9Npw0AqY8c7awi afrA== X-Gm-Message-State: AOJu0YxQKMZgZxdd/fwlZDGZHfP1APzWXaQ3dfnuQjJ6CYIY1CL+GTaz jG6mteAU/f3Iai5wMxDyOmAtnvaIuAPKueAY8FYfDUFTtt6+WpsaZ23aUK+Fr47D50sdlxnfH7r ICuCTDfN70O8kDA0cMVwmvLXZPrCuTasUvuQ9DbGP1G1Qcvq+YZp0C5HCJ4Bg1tmTnu0XXFIhxg L6zTgXuOJvVQKruVa6V5izPfhVJYf+yWhy8vXRZuRcOaB7A4Q= X-Gm-Gg: AR+sD110lVhqAIi0Cr4wUErTBm3GEGLHs1hkEl4bWwNUZsIfB5db1VnQZ04E0k9nBWN Kishk7V24jkWo1im+ezgfOSPEVAbLoiatrFo+RpDnEYgTOApvVsivl3zvBpdIvr815YzGgjnzc3 NH189eHSg6f2UnU0LW+cSuyVPwjPinht14unXTEK3e83ctarovbsYCNNeBpsaPjQfrS5Zowjd+C 7wRBQSyO/DxU3URVqvV5aIop7rRXgxhJ73t50IlHdzHROtUswsakWurnnb47mSJIwep7gCO/xHT mHrBer8EY8lME/2ZJe9UfeuEArHjjKZp6KfedoL7ieKDBJHVqfgjxLZ+x9S86zzjV3P/UWYMuIi 0TosWwEoKRIFsDAVtsOFbyG0a X-Received: by 2002:a05:600c:1383:b0:493:bfad:9d99 with SMTP id 5b1f17b1804b1-4994e7caf7cmr63687885e9.13.1785928524620; Wed, 05 Aug 2026 04:15:24 -0700 (PDT) X-Received: by 2002:a05:600c:1383:b0:493:bfad:9d99 with SMTP id 5b1f17b1804b1-4994e7caf7cmr63686535e9.13.1785928523897; Wed, 05 Aug 2026 04:15:23 -0700 (PDT) Received: from localhost (227.114.208.46.dyn.plus.net. [46.208.114.227]) by smtp.gmail.com with ESMTPSA id ffacd0b85a97d-47febfda11csm7774619f8f.1.2026.08.05.04.15.23 (version=TLS1_3 cipher=TLS_AES_256_GCM_SHA384 bits=256/256); Wed, 05 Aug 2026 04:15:23 -0700 (PDT) From: Andrew Burgess To: gdb-patches@sourceware.org, binutils@sourceware.org Subject: Re: [PATCH] etc: import changes to texi2pod.pl from gcc In-Reply-To: <91dfc026f843cfb510445198bbc9b63552b04e4a.1784980082.git.aburgess@redhat.com> References: <91dfc026f843cfb510445198bbc9b63552b04e4a.1784980082.git.aburgess@redhat.com> Date: Wed, 05 Aug 2026 12:15:22 +0100 Message-ID: <87v79olsxh.fsf@redhat.com> MIME-Version: 1.0 X-Mimecast-Spam-Score: 0 X-Mimecast-MFC-PROC-ID: 00of7eSVCtF3sXmAGNn7esFhfA7YaEnaZgbOA0vwiAE_1785928525 X-Mimecast-Originator: redhat.com Content-Type: text/plain 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 Andrew Burgess writes: > 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 > This commit has now been accepted and merged into gcc. As such I've updated the commit message to remove mention of adding this fix, this is now just part of the general "sync with gcc". Updated commit is below. Thanks, Andrew --- commit 1dd632a1865281fbc054e6af55dc1d4a371c4b61 Author: Andrew Burgess Date: Fri Jul 24 17:49:19 2026 +0100 etc: import changes to texi2pod.pl from gcc 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 3f337c3d7e2 -- 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. 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. 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;