This is the mail archive of the binutils@sourceware.org mailing list for the binutils project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: assembler man pages ?


Mike Frysinger <vapier@gentoo.org> writes:
> On Tuesday 06 September 2005 02:22 pm, Jim Blandy wrote:
>> Mike Frysinger <vapier@gentoo.org> writes:
>> > for example, say i wanted quick info on the 'jne' instruction, i would do
>> > `man jne` and get back a reference page similar to `man 2 close`
>>
>> But it's a question of pragmatics: what's the interface, what's the
>> structure, and how do you get the information into it?  You'd pretty
>> much need to have chip vendors cooperating with you, because nobody's
>> going to retype all that.  It's boring enough doing the opcodes
>> library and the GCC machine description.
>
> of the different ways i imagined tackling the issue, here's the two i think 
> are most feasible:
> - integrate with binutils documentation/source code in an effort to keep down 
> duplicated information in multiple places ... maybe something like using 
> doxygen to turn comments placed around opcode definitions in the binutils 
> source into manpages, or adding on to the current texinfo sources ...
> - define a simple xml format and use like xsl to translate into 
> man/html/whatever and startup a sourceforge project to maintain it ... the 
> benefit here would be a much lower learning curve for random people to 
> contribute

For automated generation of pages, I'd expect the CGEN-generated stuff
to be the most promising.  CGEN does, after all, have the semantics,
syntax, and encodings in one place.

But that's not going to get you what I'd consider real documentation
--- a coherent, English explanation of what the instructions do.  And
the semantics are often going to be macro-generated RTL...  Not
exactly legible.

The presence of the indexed PDF's sort of places a lower bound on the
quality you'd have to acheive to make the effort worthwhile.  If you
can't do better than what the manufacturer provides us for free, it's
not worth it; better to spend the time fixing bugs.

Speaking only for myself and not for binutils (obviously), this is
a case where I'd need someone else to show it was a winning idea
before I contributed time.  (That's not an offer; I'm just explaining
how I, at least, think about these things.)


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]