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

[Russell Shaw]

E. Weddington wrote:
> Joerg Wunsch wrote:
>
> > As E. Weddington wrote:
> >
> > > Another option, that I'm exploring for both a "WinAVR user manual"
> > > and for avr-libc, is the use of AsciiDoc (google for it). It's a
> > > text file, with very minimal formatting that gets translated by the
> > > "asciidoc" program, a Python script, and it can output HTML and
> > > Docbook (as well as LinuxDoc).
> > >   
> > I'm a bit sceptical of Yet Another Doc Converter, as doxygen has shown
> > us (in avr-libc) that we often enough ended up with wanting more than
> > the automatic conversion could provide for us.  I'm currently more
> > inclined to use docbook directly for avr-libc. 
>
> I understand.
>
> So far, my only objection with using DocBook directly is just trying 
> find a decent editor (in Windows) that can handle the format. The format 
> is pretty verbose if you have to write it raw.
>
> My only limitation that I currently have is figuring out how to convert 
> DocBook to PDF. Cygwin doesn't seem to have a quick and easy solution 
> out of the box. The "xmlto" that comes with Cygwin can convert DocBook 
> to FO (among other things), but it stops there. No direct to PDF.
>
> If anyone knows of a solution to this I would be most grateful.
>
> My only other reasoning for AsciiDoc is that what it provides is "good 
> enough", at least for the WinAVR user manual.
...

A way to make man and info pages from the one input file would be to
combine them both and strip them apart with a small script when the
docs are built.

Any text following a marker such as: ###---### MAN would be stripped
into a file for man-page processing, and any text following ###---### INFO
would be stripped into a file for texinfo processing, and any text
following ###---### MAN-INFO would end up in both.