[PATCH] V2 Begin adding some docs to elfutils

[Mark Wielaard]

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
-------------- next part --------------
A non-text attachment was scrubbed...
Name: readelf.diff
Type: text/x-patch
Size: 9424 bytes
Desc: not available
URL: <http://sourceware.org/pipermail/elfutils-devel/attachments/20190827/f93e4a94/attachment.bin>