Re: [avrdude-dev] Documentation build tools requirements - many complaints

[Joerg Wunsch]

As Brian Dean wrote:

> Do you have any experience with that tool?

I only gave it a quick try.  It seems it loses some of our existing
formatting (like the leading hyphen in the options), not sure whether
this is a bug in Eric Raymond's doclifter tool or it was a fault of
the "xmlto" run I did for verification.  Anyway, it ought to be
fixable.

Apart from that, xmlto as installed straight from the FreeBSD ports
collection could produce HTML but no PS, this might be a problem of
that particular xmlto installation though (it couldn't find some
converter locally).  xmlto also complained about a few things in the
XML doc, but I didn't look into this.

Supposedly, docbook could be used to create both, man pages as well as
info pages (see Russel Shaw's posting), but I didn't try that yet.

> I think the docbook tools are pretty heavy weight also.

Yeah.

> But at least we can make make the building of the doc optional, like
> Colin's propose patch (and my slight modification to invert the
> sense of the option).  I think we already have tentative agreement
> at least for that to go in and I've seen you and Eric also give
> support for that.

That was my idea, too.

> So what docbook would give us would be the ability to not have to
> duplicate the doc efforts to maintain both the texi and man
> documents, yet still have the benefits of both: convenient man pages
> for Unix as well as PDF or other more portable formats.

That was my main intention, to maintain a single document yet allow
for several output formats.

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

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