there are no man pages in the current elfutils repo; is this an intentional design decision at this point or something that just hasn't gotten done?
(volunteering to help for the latter case)
-Andrew
-- Andrew Hecox Technical Account Manager, Red Hat, Inc office: 919 754 4157, cell: 919 758 9234
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
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
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?
Those kinds of goals are pretty abstract given the realities of where we are now. I don't find it real meaningful to say what "the goal" is in the absence of any material plans, schedules, or resource commitments to get there.
Many of the tools that elfutils provides now are as probably good or better than their binutils counterparts (addr2line, ar, nm, ranib, readelf, size, strings, strip). Some of those are already used in preference to binutils tools in some production build processes (eu-strip in rpm builds). In these cases, we might think those programs are ready to "supplant" their binutils counterparts (or might be soon with only moderate effort).
Other tools are already significant new features that binutils has never had and probably never will (elfcmp, elflint, unstrip, with dwarfcmp and dwarflint coming later).
Pretty much all of the scheduled plans and resources formally committed to elfutils in recent times have been in the DWARF-related areas that mostly do not show up as new command line tools. Those goals are more or less unrelated to providing the other command line tools binutils has that elfutils does not have equivalently functional implementations of yet (objcopy, objdump, as, ld) and/or making the already "more finished" elfutils tools listed above be better/sufficient drop-in replacements for their binutils counterparts (and verifying the world of uses, etc.).
The "if we could wave a wand" goals include perfectly featureful ld, as, etc. so that elfutils tools would replace binutils tools for all uses we think are not insane. (Various BFD features like support for non-ELF formats or strange embedded targets we would do in different ways rather than ways necessarily drop-in compatible, if at all.) Work toward those goals happens sporadically, basically in hackers' personal spare time, and is not formally planned or scheduled at all. (Perhaps this is what you meant by "a baseline for alternate tooling", I'm not sure.)
As I indicated, all the proximate goals are library, API, and arcane kinds of tool things, not the rest of what the average person probably thinks elfutils and binutils are about. Both are in fact about more things than the familiar collection of command-line tools.
Thanks, Roland
On Sun, 19 Apr 2009, Roland McGrath wrote:
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?
Those kinds of goals are pretty abstract given the realities of where we are now. I don't find it real meaningful to say what "the goal" is in the absence of any material plans, schedules, or resource commitments to get there.
Many of the tools that elfutils provides now are as probably good or better than their binutils counterparts (addr2line, ar, nm, ranib, readelf, size, strings, strip). Some of those are already used in preference to binutils tools in some production build processes (eu-strip in rpm builds). In these cases, we might think those programs are ready to "supplant" their binutils counterparts (or might be soon with only moderate effort).
Other tools are already significant new features that binutils has never had and probably never will (elfcmp, elflint, unstrip, with dwarfcmp and dwarflint coming later).
elfutils in recent times have been in the DWARF-related areas that mostly do not show up as new command line tools. Those goals are more or less unrelated to providing the other command line tools binutils has that elfutils does not have equivalently functional implementations of yet (objcopy, objdump, as, ld) and/or making the already "more finished" elfutils tools listed above be better/sufficient drop-in replacements for their binutils counterparts (and verifying the world of uses, etc.).
The "if we could wave a wand" goals include perfectly featureful ld, as, etc. so that elfutils tools would replace binutils tools for all uses we think are not insane. (Various BFD features like support for non-ELF formats or strange embedded targets we would do in different ways rather than ways necessarily drop-in compatible, if at all.) Work toward those goals happens sporadically, basically in hackers' personal spare time, and is not formally planned or scheduled at all. (Perhaps this is what you meant by "a baseline for alternate tooling", I'm not sure.)
As I indicated, all the proximate goals are library, API, and arcane kinds of tool things, not the rest of what the average person probably thinks elfutils and binutils are about. Both are in fact about more things than the familiar collection of command-line tools.
ok.
so the dev community is interested primarily in the library work, and the user community is often the dev community. Fine, fine. I don't think I'm the right person to write documentation on the library.
OTOH, I'm happy to document anything in /bin or /usr/bin. Interest sounded tepid, but I'll try and start somewhere...
Andrew
Thanks, Roland
-- Andrew Hecox Technical Account Manager, Red Hat, Inc office: 919 754 4157, cell: 919 758 9234
so the dev community is interested primarily in the library work, and the user community is often the dev community. Fine, fine.
In terms of focus and resource allocation, yes. It's not that we aren't motivated about tool replacement work too, but we just can't see where the resource priority for that might come from and we know it's not realistic to make many claims about it any time soon.
I don't think I'm the right person to write documentation on the library.
Sure. That's not to say you might not be a great person to help figure out what good plans for documenting library APIs would be.
OTOH, I'm happy to document anything in /bin or /usr/bin. Interest sounded tepid, but I'll try and start somewhere...
We are hotly interested and warmly appreciative of the contributions! ;-) I just wanted to be clear on what a complete lack of plan for documentation we have as a project. We just have not put any time or thought into it, and can't promise to get real coherent real fast even to direct and manage new contributors' efforts on documentation.
That's why I just said everything I know about the documentation question. I meant to imply that is *all* I know, and whatever else I didn't say I haven't thought about yet. (Consider it the brief flurry of quick yammering following the blank stare and batting of eyes. ;-)
We in the project have never even discussed any subjects like what the useful or desireable source formats are for writing our documentation.
Thanks, Roland
On Wed, 22 Apr 2009, Roland McGrath wrote:
so the dev community is interested primarily in the library work, and the user community is often the dev community. Fine, fine.
In terms of focus and resource allocation, yes. It's not that we aren't motivated about tool replacement work too, but we just can't see where the resource priority for that might come from and we know it's not realistic to make many claims about it any time soon.
I don't think I'm the right person to write documentation on the library.
Sure. That's not to say you might not be a great person to help figure out what good plans for documenting library APIs would be.
OTOH, I'm happy to document anything in /bin or /usr/bin. Interest sounded tepid, but I'll try and start somewhere...
We are hotly interested and warmly appreciative of the contributions! ;-) I just wanted to be clear on what a complete lack of plan for documentation we have as a project. We just have not put any time or thought into it, and can't promise to get real coherent real fast even to direct and manage new contributors' efforts on documentation.
That's why I just said everything I know about the documentation question. I meant to imply that is *all* I know, and whatever else I didn't say I haven't thought about yet. (Consider it the brief flurry of quick yammering following the blank stare and batting of eyes. ;-)
We in the project have never even discussed any subjects like what the useful or desireable source formats are for writing our documentation.
heh. OK, I understand better.
I'll try to get together a manual page per week on the user-oriented tools, and see where that goes... I'm not a big fan of over-planning. ;)
-Ah
Thanks, Roland
-- Andrew Hecox Technical Account Manager, Red Hat, Inc office: 919 754 4157, cell: 919 758 9234
I'll try to get together a manual page per week on the user-oriented tools, and see where that goes... I'm not a big fan of over-planning. ;)
Cool!
I just noticed we have the doc/ directory with doc/elfutils.sgml. The content in there is ancient and not real useful (I wouldn't much try to save it). But it does maybe give an indicator of what Uli's preference for documentation source format might be.
So maybe what you should be writing is docbook(?) sgml that can generate man page format. That might be what everybody does now, I'm out of touch. (I just see that docbook2man exists.)
Thanks, Roland
On Wed, 22 Apr 2009, Roland McGrath wrote:
I'll try to get together a manual page per week on the user-oriented tools, and see where that goes... I'm not a big fan of over-planning. ;)
Cool!
I just noticed we have the doc/ directory with doc/elfutils.sgml. The content in there is ancient and not real useful (I wouldn't much try to save it). But it does maybe give an indicator of what Uli's preference for documentation source format might be.
So maybe what you should be writing is docbook(?) sgml that can generate man page format. That might be what everybody does now, I'm out of touch. (I just see that docbook2man exists.)
cool, I'll check it out.
Being able to generate html/pdf/man pages at once seems like a nice feature.
Andrew
Thanks, Roland
-- Andrew Hecox Technical Account Manager, Red Hat, Inc office: 919 754 4157, cell: 919 758 9234
elfutils-devel@lists.fedorahosted.org
-
Andrew Hecox -
Roland McGrath