Re: [PATCH] etc: import changes to texi2pod.pl from gcc
Andrew Burgess <[email protected]> Wed, 05 Aug 2026 12:15:22 +0100
| Newsgroups | gmane.comp.gdb.patches,gmane.comp.gnu.binutils |
|---|---|
| Message-ID | <[email protected]> |
Andrew Burgess <[email protected]> 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 <[email protected]> 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; s/>/>/g; @@ -448,6 +474,7 @@ sub unmunge # Replace escaped symbols with their equivalents. local $_ = $_[0]; + s/&(.)grave;/E<$1grave>/g; s/</E<lt>/g; s/>/E<gt>/g; s/{/\{/g;