Re: elfutils / man pages

[Roland McGrath <roland at redhat dot com>]

I don't think any decisions have been made explicitly about what formats to
write documentation in, if that's what you mean.  Quite simply, we just
have not written any documentation.  We're an overworked project with a
long list of technical goals, fast-moving development, and just a few
hackers working on it without much in the way of organization.  Writing
documentation just has not risen near the top of the pile.

Were you thinking primarily about documentation for the various
command-line tools, or for the library APIs, or both?

We are fairly fastidious about putting details in --help output for the
tools.  Many "eu-foo" tools are replacements for an existing "foo" tool
implemented in binutils.  Those interfaces are well-known, the binutils
tools are documented and people are familiar with the syntax from those,
and we strive for command-line compatibility for common uses (and most of
the non-arcane uses, really) of these tools.  Various of those (e.g.
eu-addr2line, eu-strip) have nifty feature options that their binutils
counterparts never had, but at least --help is fairly informative about
those.

The library APIs fall into two categories.  Most of the libelf API has been
quite stable for many years and is consistent with other implementations
that have lots of documentation (e.g. Solaris).  The corners of libelf that
are new or specific to elfutils are few and arcane, perhaps only used by
elfutils tools' themselves.  So while this API is pretty solid and could be
documented thoroughly without much risk of drift, the lack of such
documentation has probably not been a practical hindrance to people trying
to write to the API.

The other libraries (libdw/libdwfl, etc.) have been much more fluid and
continue to change pretty rapidly.  We expect these to keep changing and
expanding for some time.  By the end of this year, we will probably have
even more of these, APIs in more languages, etc.  The horizon when these
APIs become stable is pretty hazy at this point.  (By the same token, we
are and will be adding more new command-line tools whose usage details will
keep evolving too.)

A major goal in having all these new APIs come together is to get more
people writing things using them, and to have a low barrier to entry in
casually whipping up new things.  Clearly, good library API documentation
is essential for that ever to take off.  We make some effort in writing
detailed comments in API header files along the way, as is necessary just
for our own use.  The detail is better in some places than others, but in
all places it's really just concise (terse) pointers for hackers who are
prepared to read a lot of C rather than a formal API document of any kind.

So, in summary, we would love to have great documentation but have almost
no cycles to devote to it any time soon ourselves (just being realistic).
For some basic stuff like libelf and the existing command-line tools, it is
just a question of getting it written.  For the cool APIs and the even
cooler vaporware believed or imagined to be in the pipeline, it will be a
major and ongoing effort to produce documentation that is sufficiently
accurate and detailed to be really useful, and to keep it so.  We haven't
made any real plans for either.  Assistance is welcome.


Thanks,
Roland