> Eric Pouech <Eric.PouechÉwanadoo.fr> writes:
>
> > a last point would be to have Alexandre's agreement to use
> DocBook as
> > primary format for documentation. I remembered one of his remarks
> > where he wished to have at least all docs in text format so anyone
> > could read them (it doesn't mean of course docs must be
> written in text
> > format)
>
> I think the important factor is that the doc is as accessible as
> possible; if it requires the user to install a lot of tools just to be
> able to read the doc there is a problem. And this is what worries me a
> bit about DocBook; I find the raw SGML text painful to read, and I'm
> not sure how easy it is to get the right tools to format it to
> something readable.
Well, we must of course include the generate text of the SGML source
in the CVS tree. Requiring everybody that want to read documentation
to install the SGML tools is not an option IMO.
This means of course that Alexandre and anybody that want to write
documentation must have it installed but that is not unreasonable IMHO.
When Alexandre have applied a documentation patch he will need to
do ./tools/make_documentation or something, but then similar thing
are required even now for debug messages to take one example.
> I think texinfo is better in this respect; but
> this is only a personal opinion, ultimately the choice is up to the
> people who actually write the doc.
>
> What do other people think? Any strong opinions for/against DocBook?
IMHO we have two and only two choices. Text or DocBook.
Any other alternative are either worse or "obsolete".
Text because, well it is text. Enough said.
DocBook because it exists tools that can converted it to
all other serious alternatives like HTML and texinfo and
even text, this kind makes the other formats "obsolete".
While I have no personal experience with DocBook,
a lot of other big projects use it so if it is good
enough for them it is good enough for us.
In short, I support using DocBook, but having to chose
between DocBook and something else I would prefer text.
PS. I don't agree with Marcus that we should include generate
HTML in the tree, I would prefer text. The generated HTML should
be put at WineHQ.
