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 > _______________________________________________ elfutils-devel mailing list [email protected] https://fedorahosted.org/mailman/listinfo/elfutils-devel
