On Sun, 19 Apr 2009, Roland McGrath wrote:
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?
the former.
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.
indeed; --help is nearly what is provided by the various binutils man
pages.
<snip interesting API notes>
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.
I'm sure I knew the answer to this, but can't find a reference so:
is the goal for elfutils to eventually supplant binutils with a newer
set of tools on ELF-only platforms or just to provide alternate
implementations (or a baseline for alternate tooling) which would sit
along-side binutils?
In the former case, manual pages seem like a necessary step; in the
former, I could imagine either way. Regardless, based on the binutils
manuals and --help, they'd be pretty easy to create. The big question
I have is if the supported arguments are sufficiently in flux that
it's not worth documenting: eg someone would think the docs on
authoritative when --help and the implementation have gone in another
direction.
I'm not an expert in the toolset, by any means, I've just been
reviewing and comparing binutils and elfutils and noticed it wouldn't
be a herculean task to document the latter.
Thanks,
Andrew
Thanks,
Roland