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

[Joerg Wunsch]

Juergen Harms <address@hidden> wrote:

> 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)). ...

They are mdoc(7) style macros, not the prehistoric man(7) style.

If konqueror doesn't understand that, oh well: it's IMHO useless to
display man pages then.

Note that while mdoc is used 100 % in BSD systems (which both, Brian
Dean as well as me are quite familiar with, thus avrdude's man page
has inherited it from there), it's not a BSDism at all: this macro
package comes from groff, the GNU runoff toolchain, which is *the*
opensource replacement for troff.

Reverting to man(7) would be a huge step backwards: mdoc(7) uses a far
more sophisticated approach that concentrates on *what* kind of item
to display, not *how* to display it.  You can roughly compare that
with the following two HTML snippets:

....
<h1>This is a new chapter</h1>
<p>This is the paragraph for this chapter.</p>
....

vs.

<b><font size=+4>This is a new chapter</font></b>
<br />
This is the paragraph for this chapter.
<br />

The changes between man(7) and mdoc(7) are far more drastic the better
your output device is: format them to PS (using groff rather than
troff), and man(7) will really look dull.

> (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.

That would be the most logical consequence so.  If Konquerer thinks of
itself as a tool that can display man pages, it ought to understand
the same formats man(1) understands.  (Note that man(1) uses -mandoc
as its macro set, which then decides whether it needs man(7) or
mdoc(7).)

I realize that this is nothing that could be done in an afternoon
though.  Perhaps it would have been better if Konqueror simply used
the groff parser, and the HTML backend, instead of trying to roll its
own parser for man(7).

Another option would be to try preprocessing the mdoc(7) macros for
Konqueror.  They are fairly high-level.  But I'd prefer one of the
options above.

-- 
cheers, J"org               .-.-.   --... ...--   -.. .  DL8DTL

http://www.sax.de/~joerg/                        NIC: JW11-RIPE
Never trust an operating system you don't have sources for. ;-)