> On Wednesday, June 21, 2000, Patrik Stridvall <[EMAIL PROTECTED]> wrote:
> > > Patrik Stridvall <psÉleissner.se> writes:
> > >
> > > > 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.
> > >
> > > I'm not sure it has to be in CVS.
>
> At least not in the same repository as Wine itself. Documentation
> packages can make good use of revision systems. It's nice to
> be able to
> tag the tree at official release points (to coordinate with major Wine
> releases). A little branching is also nice, to fix typos in older
> versions.
Hmm. Wasn't we talking about generated ASCII text of the SGML source.
While version control for that is not useless, it is less useful.
But never mind.
> > > CVS is useful to allow people to
> > > always have the latest version of the code, but this is not really
> > > necessary for formatted docs; unlike code, you don't
> really need to
> > > update your version of the doc everytime a typo is fixed.
>
> Right. A typo in your documentation is a matter for your
> brain to fix,
> not your OS. (c: Your brain is much less likely to crash than your
> typical application.
Yes, but a human brain "crashing" can have much more serious implicatation,
like mass murders and serial killers. :-)
Of course a typo in the Wine source code is not likely to trigger that...
> > Seriously, not everybody has an permanent internet connection,
> > so have the documentation in the tree while offline is useful.
>
> That's more a matter of convenience for the user. OTOH, it makes life
> harder for the distributions.
Everything about Wine is about convenience of the user.
You can dual boot Windows and Linux you know. Of course
cutting and pasting between Windows and Linux application
is much harder and slower but it is possible. :-)
Seriously, all programming is about in general is making
life easier for the user. However for more advanced features
the inconvience of the developer must be weigh against the
inconvienience of the user.
Running ./tools/make_documentation will inconvienience
us (primarily Alexandre), but not very much.
> If the docs reside within the
> Wine source
> tree, they are much harder to break out into a separate package which
> can be installed as a different entity.
The are to issues here.
1. Whether the source documentation (DocBook?) should reside in the Wine
tree
2. Whether the generated ASCII text should reside in the Wine tree
As for 1, I have no strong feeling either way.
As for 2, I think it should.
> It's actually much easier to download and install a documentation
> package, than Wine as a whole. Do you want to have to upgrade Wine
> to fix a typo in the docs? (c: Nothing stopping us from distributing
> HTML docs that you can install locally.
Well the actual distribution, like say Debian, will of course have
the documentation in a separate package like the header files is
in a separate package right now (at least in Debian), so if the
documenation changes only the wine-doc package is download and
installed.
If you use the snapshot, no problem, we will not release a new
snapshot just for a documentation typo.
If you use the CVS, cvs update handles everything, so you don't care.
> Not to mention that it ties the release of the documentation
> to the Wine
> source release schedule (or vice versa) -- otherwise, the
> official docs
> will always be out of sync with the copies in the source tree.
> Maintainance Nightmare #47.
We, or at least I, are talking about whether we should include
the generate ASCII files from the DocBook(?) source.
I'm not against have the DocBook(?) source in a separate tree,
so you can release new versions however often you like.
But when we release the Wine source code we should release
the _latest_ version of the documentation in ASCII format
in the tree for the convinience of the user.
> > Perhaps, but I would prefer the documentation in text format
> > in the tree.
> Unfortunately, this breaks the convention to not have generated files
> checked into CVS, in addition to the issues above.
Well, we have already broken that rule with include/debugdefs.h,
configure and some of the files in dlls/opengl32, the unicode
directory and I probably forgot some.
Of course two wrongs doesn't make one right...
