Re: [avr-gcc-list] Documentation on avrdude

[Juergen Harms]

I started doing part of my home-work: looking into the incorrect
representation of the avrdude man-page by konqueror.

The problem is far more general than I had realised initially: the
first line of many (most?) items describing an option are messed up.
For instance:

The troff line
.It Fl b Ar baudrate

is shown in man (correctly) as
-b baudrate    (baudrate in bold face)

and in konqueror (incorrectly) as
-b -file ... -baudrate   (baudrate in normal face)

These problems are due (my conjecture) to the use of macros in the
troff text of the avrdude man-page that are not part of the list of
macros defined in the list of "valid" macros for use in man-pages
(see man(7)). I guess that this is due to the BSD background of this
development, I found remarks that BSD has a specific culture or rich
sets of macro definitions.

man (and similar tools like man2html) come from the common past of BSD
and Linux - hence deals correctly with the "exotic" macros, Konqueror
(the KDE standard browser and standard KDE tool for reading man-pages)
does not (btw, the problem is not specific to Mandriva: I also have a
Ubuntu partition on my machine, same problem there; I am pretty sure
that the same thing will apply also to Suse).

Possible solutions

(a) modify konqueror: unrealistic and a prohibitive effort, would
probably result in a special version of konqueror impossible to maintain
as KDE evolves - forget it.

(b) modify the troff text of the man-page by adding macro definition
that define the "exotic" macros and reduce them to macros that are
"valid" for man - I do not know enough about troff macros to do this,
and I think a lot of messy work.

(c) re-write the troff text and replace the "exotic" macros by valid
macros - probably a couple of hours work which I could do - but is
it worth while? and, Joerg, you as a maintainer would get a baby which
you might not like (have a look at the troff text of avr-gdb: text using 
standard macros is messy and far less elegant than the BSD -macro based
text).

At present, just put up a big warning: KDE users must not use konqueror 
when they look at the avrdude man-page; a workaround for using a decent 
tool for looking at this man-page is to feed the original text through 
man2html and than use the resulting html page. That is my present 
solution, with a bookmark for rapid access.