> On Wednesday, June 21, 2000, Patrik Stridvall <[EMAIL PROTECTED]> wrote:
> > > Personally, I think that DocBook is a good
> > > choice for this, but I do see some of the downsides to it.
> >
> > Like?
>
> Well, like the added complexity and clutter from all the markup. The
> introduction of a learning curve. The added necessity of
> having a suite
> of tools installed before you can generate the docs.
Well, that is a problem for everything except pure text.
I'm more intrested in specific DocBook problems.
> [ Although I should point out that Nautilus, the new GNOME
> browser/explorer, will eventually be able to display DocBook directly,
> cutting out the need for an intermediary SGML rendering
> stage. It should
> hopefully be usable by the end of the year. ]
Cool.
> However, I think the strengths of DocBook are enough to outweigh the
> disadvantages: swiftly becoming an industry standard (O'Reilly uses it
> IIRC, and Addison-Wesley is gearing up to support it for manuscripts);
> many different rendering targets; special support for glossaries,
> bibliographies, indexing, etc.; relies on proven (SGML) technology.
I agree.
> The list goes on (of both pros and cons).
I'm more intrested in cons, I think we, or at least I,
have a clear picture of the pros.
> > Are we talking about user documentation only or both
> > user and developer documentation?
>
> Both. They may be separated into different guides or packages, but
> IMHO we should handle them both with the same administrative
> infrastructure.
Speaking about developer documentation. You do realize
that there are two different kinds of developer documentation?
(1) For people developing Wine/WineLib
(2) For people developing applications _using_ WineLib
Of course for (2) Microsoft own Windows documentation covers
most of the topics but there some documents that
are need that are WineLib specific.
Then we have all the in code documention of the Windows API
that should be extracted and presented in an apropriate
format (DocBook?). Eventually they need to be man pages,
can DocBook generate that?
And we should not forget to write more in code documentatio,
eventhough I think we have to save that for post 1.0, to
many other more important things to do.
