Re: [PATCH] V2 Begin adding some docs to elfutils

[Mark Wielaard <mark@klomp.org>]

[-- Attachment #1: Type: text/plain, Size: 5568 bytes --]

Hi Ben,

On Fri, 2019-08-23 at 13:42 -0700, Ben Woodard wrote:
> - Added doc/README

I like this one. If only because it says we would like to move to
sphinx :) I must admit I am not a fan of raw nroff. But of course it is
better than nothing.

> - Updated doc/ChangeLog

Thanks. You don't really have to add new entries for changes between
different versions never committed. Feel free to just add entries for
the final result.

> - Added a eu-readelf manpage based on the one from binutils.

I still have some reservations about this, see below.

> - Added a brand new manpage for eu-elfclassify the new utility added
> in 0.177

This is nice. But maybe also a good example of what help2man could do
(of course we don't have the machinery to generate help2man pages for
now).

> - Add some new files in the doc directory and sync makefile with
> upstream.
> - Reenable the compilation of doc directory.
> - Disable sgml file building
> - Build man pages the automake way

I had to tweak this in 3 ways.

First when doing a make dist the pdf and dvi files would still be
generated. So I just removed the build rules completely.

Second "Man pages are not currently considered to be source, because it
is not uncommon for man pages to be automatically generated.  Therefore
they are not automatically included in the distribution." (*) So they
need to have a dist_ prefix to get actually included in the dist.

Third we use --program-prefix=eu- by default, which renames all our
binaries to eu-xxx (the user could use no or another prefix, although
that is discouraged, because it would clash with the binutil names).
This also applies to man-pages. So they get installed as eu-eu-
readelf.1 and eu-elf_begin.3. To fix this I renamed the .1 files to not
have the eu-prefix by default. And for the .3 function pages I added
the notrans_ prefix (*).

(*) See also 
https://www.gnu.org/software/automake/manual/html_node/Man-Pages.html

This is the diff that I came up with:

index cc0a470b..f11fb8f0 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -16,19 +16,6 @@
 ##
 ## You should have received a copy of the GNU General Public License
 ## along with this program.  If not, see <http://www.gnu.org/licenses/>.
-EXTRA_DIST = COPYING
-man1_MANS=eu-readelf.1 eu-elfclassify.1
-man3_MANS=elf_update.3 elf_getdata.3 elf_clone.3 elf_begin.3
-
-CLEANFILES = elfutils.dvi
-
-# We need only a few special rules to generate the various output formats
-# from the SGML sources.
-.PHONY: dvi pdf html
-pdf: $(srcdir)elfutils.pdf
-dvi: $(srcdir)elfutils.dvi
-
-$(srcdir)%.dvi: %.sgml
-       db2dvi $^
-$(srcdir)%.pdf: %.sgml
-       db2pdf $^
+EXTRA_DIST = COPYING README
+dist_man1_MANS=readelf.1 elfclassify.1
+notrans_dist_man3_MANS=elf_update.3 elf_getdata.3 elf_clone.3 elf_begin.3

Also for the .3 manpages I replace \— with \-. Since the former comes
out really odd on my (RHEL7) system.

> Since V1
> - Put man pages in the proper directories.
> - Added copy of Gnu Free Documentation License
> - Modified eu-readelf.1 man page to match the supported options.

There are still some flags/options that seem specific to binutils
readelf.

The short form for -a mentions --use-dynamic, which eu-readelf doesn't
know about (I removed the paragraph from the man page).

Our help also says that -x, --hex-dump, might take a section number or
a section name. But it doesn't actually work! The patch to fix that is
simple though. This is good, the documenting found an actual bug :)

diff --git a/src/readelf.c b/src/readelf.c
index 24be7a9a..77f9c3a3 100644
--- a/src/readelf.c
+++ b/src/readelf.c
@@ -12634,6 +12634,7 @@ for_each_section_argument (Elf *elf, const struct section_argument *list,
            error (EXIT_FAILURE, 0, gettext ("cannot get section header: %s"),
                   elf_errmsg (-1));
          name = elf_strptr (elf, shstrndx, shdr_mem.sh_name);
+         (*dump) (scn, &shdr_mem, name);
        }
       else
        {

The short form of --debug-dump, -w[lLiaprmfFsoRtUuTgAckK], doesn't
actually work for eu-readelf (maybe it should, but I removed it from
the man page since it currently doesn't).

eu-readelf also doesn't support --debug-dump=rawline (which seems to be
an alias for =line?), =frame-interp, =trace_info, =trace_abbrev,
=trace_aranges, =pubtype, =cu_index nor -links. All have been removed
from the man page.

Also we advertise --debug-dump=frame in --help, while the man page
advertises --debug-dump=frames. eu-readelf support both. binutils
readelf only support =frames). I didn't change the man page.

readelf --debug-dump=ranges seems to be an alias from --debug-
dump=aranges. eu-readelf uses --debug-dump=ranges for .debug_ranges (or
.debug_rnglist). binutils readelf uses =Ranges (with a capital R) for
the later. eu-readelf doesn't support =Ranges. Changed the man page to
use the lower case name.

--debug-dump=follow-links seems somewhat related to our --debug-
dump=info+. Removed =follow-links, added =info+.

eu-readelf implements -w, --wide, bit they are ignored for
compatibility (lines always wide). Changed the description.

So the diff (attached) is fairly big. Which does make me wonder whether
starting from the binutils readelf man page is really that smart.

Note that -N, --numeric-addresses and -U, --unresolved-address-offsets
(which seem unique to eu-readelf) are not documented yet.

But it is all we have, so for now I committed it.

Thanks,

Mark

[-- Attachment #2: readelf.diff --]
[-- Type: text/x-patch, Size: 9424 bytes --]

--- eu-readelf.1	2019-08-27 13:12:38.487568453 +0200
+++ doc/readelf.1	2019-08-27 12:08:31.930097151 +0200
@@ -158,8 +158,8 @@
         [\fB\-c\fR|\fB\-\-archive\-index\fR]
         [\fB\-\-dwarf\-skeleton\fR <file> ]
         [\fB\-\-elf\-section\fR [section] ]
-        [\fB\-w[lLiaprmfFsoRtUuTgAckK]\fR|
-         \fB\-\-debug\-dump\fR[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]]
+        [\fB\-w\fR|
+         \fB\-\-debug\-dump\fR[=line,=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]]
         [\fB\-I\fR|\fB\-\-histogram\fR]
         [\fB\-v\fR|\fB\-\-version\fR]
         [\fB\-W\fR|\fB\-\-wide\fR]
@@ -207,9 +207,6 @@
 \&\fB\-\-version\-info\fR, \fB\-\-arch\-specific\fR,
 \&\fB\-\-section\-groups\fR and \fB\-\-histogram\fR.
 .Sp
-Note \- this option does not enable \fB\-\-use\-dynamic\fR itself, so
-if that option is not present on the command line then dynamic symbols
-and dynamic relocs will not be displayed.
 .IP "\fB\-h\fR" 4
 .IX Item "-h"
 .PD 0
@@ -314,20 +311,18 @@
 is any.
 .SS "Additional output selection"
 .IX Subsection "Additional output selection"
-.IP "\fB\-x <number or name>\fR" 4
-.IX Item "-x <number or name>"
+.IP "\fB\-x <name>\fR" 4
+.IX Item "-x <name>"
 .PD 0
-.IP "\fB\-\-hex\-dump=<number or name>\fR" 4
-.IX Item "--hex-dump=<number or name>"
+.IP "\fB\-\-hex\-dump=<name>\fR" 4
+.IX Item "--hex-dump=<name>"
 .PD
-Displays the contents of the indicated section as a hexadecimal bytes.
-A number identifies a particular section by index in the section table;
-any other string identifies all sections with that name in the object file.
-.IP "\fB\-w[lLiaprmfFsoRtUuTgAckK]\fR" 4
-.IX Item "-w[lLiaprmfFsoRtUuTgAckK]"
+Displays the contents of the indicated section name as a hexadecimal bytes.
+.IP "\fB\-w\fR" 4
+.IX Item "-w"
 .PD 0
-.IP "\fB\-\-debug\-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames\-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow\-links]\fR" 4
-.IX Item "--debug-dump[=rawline,=decodedline,=info,=abbrev,=pubnames,=aranges,=macro,=frames,=frames-interp,=str,=loc,=Ranges,=pubtypes,=trace_info,=trace_abbrev,=trace_aranges,=gdb_index,=addr,=cu_index,=links,=follow-links]"
+.IP "\fB\-\-debug\-dump[=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]\fR" 4
+.IX Item "--debug-dump[=line,=decodedline,=info,=info+,=abbrev,=pubnames,=aranges,=macro,=frames,=str,=loc,=ranges,=gdb_index,=addr]"
 .PD
 Displays the contents of the \s-1DWARF\s0 debug sections in the file, if any
 are present.  Compressed debug sections are automatically decompressed
@@ -336,55 +331,24 @@
 of data will be dumped.  The letters and words refer to the following
 information:
 .RS 4
-.ie n .IP """a""" 4
-.el .IP "\f(CWa\fR" 4
-.IX Item "a"
 .PD 0
 .ie n .IP """=abbrev""" 4
 .el .IP "\f(CW=abbrev\fR" 4
 .IX Item "=abbrev"
 .PD
 Displays the contents of the \fB.debug_abbrev\fR section.
-.ie n .IP """A""" 4
-.el .IP "\f(CWA\fR" 4
-.IX Item "A"
 .PD 0
 .ie n .IP """=addr""" 4
 .el .IP "\f(CW=addr\fR" 4
 .IX Item "=addr"
 .PD
 Displays the contents of the \fB.debug_addr\fR section.
-.ie n .IP """c""" 4
-.el .IP "\f(CWc\fR" 4
-.IX Item "c"
-.PD 0
-.ie n .IP """=cu_index""" 4
-.el .IP "\f(CW=cu_index\fR" 4
-.IX Item "=cu_index"
-.PD
-Displays the contents of the \fB.debug_cu_index\fR and/or
-\&\fB.debug_tu_index\fR sections.
-.ie n .IP """f""" 4
-.el .IP "\f(CWf\fR" 4
-.IX Item "f"
 .PD 0
 .ie n .IP """=frames""" 4
 .el .IP "\f(CW=frames\fR" 4
 .IX Item "=frames"
 .PD
 Display the raw contents of a \fB.debug_frame\fR section.
-.ie n .IP """F""" 4
-.el .IP "\f(CWF\fR" 4
-.IX Item "F"
-.PD 0
-.ie n .IP """=frame\-interp""" 4
-.el .IP "\f(CW=frame\-interp\fR" 4
-.IX Item "=frame-interp"
-.PD
-Display the interpreted contents of a \fB.debug_frame\fR section.
-.ie n .IP """g""" 4
-.el .IP "\f(CWg\fR" 4
-.IX Item "g"
 .PD 0
 .ie n .IP """=gdb_index""" 4
 .el .IP "\f(CW=gdb_index\fR" 4
@@ -392,67 +356,27 @@
 .PD
 Displays the contents of the \fB.gdb_index\fR and/or
 \&\fB.debug_names\fR sections.
-.ie n .IP """i""" 4
-.el .IP "\f(CWi\fR" 4
-.IX Item "i"
 .PD 0
 .ie n .IP """=info""" 4
 .el .IP "\f(CW=info\fR" 4
 .IX Item "=info"
 .PD
 Displays the contents of the \fB.debug_info\fR section.
-.ie n .IP """k""" 4
-.el .IP "\f(CWk\fR" 4
-.IX Item "k"
-.PD 0
-.ie n .IP """=links""" 4
-.el .IP "\f(CW=links\fR" 4
-.IX Item "=links"
-.PD
-Displays the contents of the \fB.gnu_debuglink\fR and/or
-\&\fB.gnu_debugaltlink\fR sections.  Also displays the link to a
-separate dwarf object file (dwo), if one is specified by the 
-DW_AT_GNU_dwo_name or DW_AT_dwo_name attributes in the
-\&\fB.debug_info\fR section.
-.ie n .IP """K""" 4
-.el .IP "\f(CWK\fR" 4
-.IX Item "K"
-.PD 0
-.ie n .IP """=follow\-links""" 4
-.el .IP "\f(CW=follow\-links\fR" 4
-.IX Item "=follow-links"
-.PD
-Display the contents of any selected debug sections that are found in
-a linked, separate debug info file.  This can result in multiple
-versions of the same debug section being displayed if both the main
-file and the separate debug info file contain sections with the same
-name.
-.Sp
-In addition, when displaying \s-1DWARF\s0 attributes, if a form is found that
-references the separate debug info file, then the referenced contents
-will also be displayed.
-.ie n .IP """l""" 4
-.el .IP "\f(CWl\fR" 4
-.IX Item "l"
-.PD 0
-.ie n .IP """=rawline""" 4
-.el .IP "\f(CW=rawline\fR" 4
-.IX Item "=rawline"
-.PD
-Displays the contents of the \fB.debug_line\fR section in a raw
-format.
-.ie n .IP """L""" 4
-.el .IP "\f(CWL\fR" 4
-.IX Item "L"
+.PD 0
+.ie n .IP """=info+""" 4
+.el .IP "\f(CW=info+\fR" 4
+.IX Item "=info+"
+.PD
+Displays the contents of the \fB.debug_info\fR section, plus any skeleton
+unit will be immediately followed by the corresponding split compile unit
+(from the .dwo file).  To show the difference between "regular" CUs and
+split CUs print offsets and references between { and } instead of [ and ].
 .PD 0
 .ie n .IP """=decodedline""" 4
 .el .IP "\f(CW=decodedline\fR" 4
 .IX Item "=decodedline"
 .PD
 Displays the interpreted contents of the \fB.debug_line\fR section.
-.ie n .IP """m""" 4
-.el .IP "\f(CWm\fR" 4
-.IX Item "m"
 .PD 0
 .ie n .IP """=macro""" 4
 .el .IP "\f(CW=macro\fR" 4
@@ -460,9 +384,6 @@
 .PD
 Displays the contents of the \fB.debug_macro\fR and/or
 \&\fB.debug_macinfo\fR sections.
-.ie n .IP """o""" 4
-.el .IP "\f(CWo\fR" 4
-.IX Item "o"
 .PD 0
 .ie n .IP """=loc""" 4
 .el .IP "\f(CW=loc\fR" 4
@@ -470,9 +391,6 @@
 .PD
 Displays the contents of the \fB.debug_loc\fR and/or
 \&\fB.debug_loclists\fR sections.
-.ie n .IP """p""" 4
-.el .IP "\f(CWp\fR" 4
-.IX Item "p"
 .PD 0
 .ie n .IP """=pubnames""" 4
 .el .IP "\f(CW=pubnames\fR" 4
@@ -480,28 +398,19 @@
 .PD
 Displays the contents of the \fB.debug_pubnames\fR and/or
 \&\fB.debug_gnu_pubnames\fR sections.
-.ie n .IP """r""" 4
-.el .IP "\f(CWr\fR" 4
-.IX Item "r"
 .PD 0
 .ie n .IP """=aranges""" 4
 .el .IP "\f(CW=aranges\fR" 4
 .IX Item "=aranges"
 .PD
 Displays the contents of the \fB.debug_aranges\fR section.
-.ie n .IP """R""" 4
-.el .IP "\f(CWR\fR" 4
-.IX Item "R"
-.PD 0
-.ie n .IP """=Ranges""" 4
-.el .IP "\f(CW=Ranges\fR" 4
-.IX Item "=Ranges"
+.PD 0
+.ie n .IP """=ranges""" 4
+.el .IP "\f(CW=ranges\fR" 4
+.IX Item "=ranges"
 .PD
 Displays the contents of the \fB.debug_ranges\fR and/or
 \&\fB.debug_rnglists\fR sections.
-.ie n .IP """s""" 4
-.el .IP "\f(CWs\fR" 4
-.IX Item "s"
 .PD 0
 .ie n .IP """=str""" 4
 .el .IP "\f(CW=str\fR" 4
@@ -509,44 +418,7 @@
 .PD
 Displays the contents of the \fB.debug_str\fR, \fB.debug_line_str\fR
 and/or \fB.debug_str_offsets\fR sections.
-.ie n .IP """t""" 4
-.el .IP "\f(CWt\fR" 4
-.IX Item "t"
-.PD 0
-.ie n .IP """=pubtype""" 4
-.el .IP "\f(CW=pubtype\fR" 4
-.IX Item "=pubtype"
-.PD
-Displays the contents of the \fB.debug_pubtypes\fR and/or
-\&\fB.debug_gnu_pubtypes\fR sections.
-.ie n .IP """T""" 4
-.el .IP "\f(CWT\fR" 4
-.IX Item "T"
-.PD 0
-.ie n .IP """=trace_aranges""" 4
-.el .IP "\f(CW=trace_aranges\fR" 4
-.IX Item "=trace_aranges"
-.PD
-Displays the contents of the \fB.trace_aranges\fR section.
-.ie n .IP """u""" 4
-.el .IP "\f(CWu\fR" 4
-.IX Item "u"
-.PD 0
-.ie n .IP """=trace_abbrev""" 4
-.el .IP "\f(CW=trace_abbrev\fR" 4
-.IX Item "=trace_abbrev"
-.PD
-Displays the contents of the \fB.trace_abbrev\fR section.
-.ie n .IP """U""" 4
-.el .IP "\f(CWU\fR" 4
-.IX Item "U"
-.PD 0
-.ie n .IP """=trace_info""" 4
-.el .IP "\f(CW=trace_info\fR" 4
-.IX Item "=trace_info"
-.PD
-Displays the contents of the \fB.trace_info\fR section.
-.RE
+.PD 0
 .RS 4
 .Sp
 Note: displaying the contents of \fB.debug_static_funcs\fR,
@@ -595,11 +467,7 @@
 .IP "\fB\-\-wide\fR" 4
 .IX Item "--wide"
 .PD
-Don't break output lines to fit into 80 columns. By default
-\&\fBeu-readelf\fR breaks section header and segment listing lines for
-64\-bit \s-1ELF\s0 files, so that they fit into 80 columns. This option causes
-\&\fBeu-readelf\fR to print each section header resp. each segment one a
-single line, which is far more eu-readable on terminals wider than 80 columns.
+Ignored for compatibility (lines always wide).
 .IP "\fB\-H\fR" 4
 .IX Item "-H"
 .PD 0