[binutils-gdb] etc: import changes to texi2pod.pl from gcc
Andrew Burgess via Gdb-cvs <[email protected]>
| Newsgroups | gmane.comp.gdb.cvs |
|---|---|
| Message-ID | <[email protected]> |
https://sourceware.org/git/gitweb.cgi?p=binutils-gdb.git;h=69c5f54b9b6c69a623fb5a026839b0ad71994db1 commit 69c5f54b9b6c69a623fb5a026839b0ad71994db1 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: --- etc/texi2pod.pl | 53 ++++++++++++++++++++++++++++++++++++++++------------- 1 file changed, 40 insertions(+), 13 deletions(-) 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;