People, While I'm waiting for wine to compile, I figured I'd start a new flamewar :P I was looking through the documentation directory, and there are a few things that shouldn't be in there IMO. We are getting closer to 1.0, and we should clean up our act, me thinks... The CVS scripts are meant to clarify what I mean, and for Alexandre to use... (hint, hint :)) And now to the constructive part: -- get rid of old, obsolete files: Script: cvs rm -f documentation/{programs,winsock} cvs ci -m "Remove obsolete docs" documentation -- remove WineHQ stuff out of there There are other things that are on WineHQ, and they don't reside in there. Why do we keep stuff like db2html-winehq in there? If we _need_ it in there, it should be in tools/ but I don't see patch.py anywhere in the tree, and that one is used on WineHQ, so I suggest we keep all WineHQ things in one place (and outside the wine tree) Script: cvs rm -f documentation/{db2html-winehq,make_winehq} cvs ci -m "Remove WineHQ stuff" documentation -- rename installation-und-konfiguration.german We have already a README.fr, we should be consistent. Script: cp installation-und-konfiguration.german README.de cvs rm -f documentation/installation-und-konfiguration.german cvs add documentation/README.de cvs ci -m "Rename installation-und-konfiguration.german to README.de" documentation -- what's up with HOWTO-winelib? If it's already in .sgml, we should delete it. Else, we should integrate in the Winelib guide, and delete it. Anyone knows the its status? -- why do we have psdrv.reg in documentation? Shouldn't it be with the other conf files? -- documentation/shell32 should be moved as a README in the dlls/shell32 Script: cp documentation/shell32 dlls/shell32/README cvs rm -f documentation/shell32 cvs add dlls/shell32/README cvs ci -m "Rename documentation/shell32 to dlls/shell32/README" documentation dlls/shell32 -- what's up with wine.texinfo? Is it still maintained? Shouldn't we incorporate whatever is in there in the .sgml, and get rid of it? Anyone knows the its status? -- why do we have config files in documentation/samples? Shouldn't we move documentation/samples to to something like conf/ or etc/? -- the documentation/status idea was mine, but I now think it was misguided The information stays buried in there, and no one maintains it. We should salvage what's still good, and move it in a README file in the appropriate dll directory, or even directly in the .c file, where appropriate. Comments? -- Dimi.
Don't agree. Bug #688 about documentation genration is still open and this script is the only way to obtain correct html doc.
don't reside in there. Why do we keep stuff like db2html-winehq in there? If we _need_ it in there, Add-on: The documentation that talks about regapi must be removed/updated.
___________________________________________________________ Do You Yahoo!? -- Une adresse @yahoo.fr gratuite et en français ! Yahoo! Mail : http://fr.mail.yahoo.com
On September 17, 2002 07:54 pm, Sylvain Petreolle wrote:
Don't agree. Bug #688 about documentation genration is still open and this script is the only way to obtain correct html doc.
I am not saying we don't need it. What I'm questioning is why we need it (a) in the documentation dir, and (b) in the wine tree at all? -- Dimi.
--- "Dimitrie O. Paun" <dpaun(a)rogers.com> a écrit : > On September 17, 2002 07:54 pm, Sylvain Petreolle wrote:
Don't agree. Bug #688 about documentation genration is still open and this script is the only way to obtain correct html doc.
I am not saying we don't need it. What I'm questioning is why we need it (a) in the documentation dir, and (b) in the wine tree at all? Ok, I didn't understand it that way... But in this case (a) and (b) have the same answer. I agree that it could be in tools/.
___________________________________________________________ Do You Yahoo!? -- Une adresse @yahoo.fr gratuite et en français ! Yahoo! Mail : http://fr.mail.yahoo.com
-- documentation/shell32 should be moved as a README in the dlls/shell32 Script: cp documentation/shell32 dlls/shell32/README cvs rm -f documentation/shell32 cvs add dlls/shell32/README cvs ci -m "Rename documentation/shell32 to dlls/shell32/README" documentation dlls/shell32 well, not sure I agree here... we should decide where to put DLL specific documentation as of today, some modules are documented with a (plain text) README in their dir some others are DocBook:ed in documentation (and most of them, the .sgml has been made up from the plaintext file) IMO, most of the documentation (even the internals description, status of DLL) should be made in the DocBook form
A+
"Dimitrie O. Paun" <dpaun(a)rogers.com> writes:
-- remove WineHQ stuff out of there There are other things that are on WineHQ, and they don't reside in there. Why do we keep stuff like db2html-winehq in there? If we _need_ it in there, it should be in tools/ but I don't see patch.py anywhere in the tree, and that one is used on WineHQ, so I suggest we keep all WineHQ things in one place (and outside the wine tree)
Fine with me, but I think this will require fixes on the WineHQ side before I can remove it.
-- rename installation-und-konfiguration.german We have already a README.fr, we should be consistent.
But installation-und-konfiguration.german is not really a translation of the README. I think it should rather be integrated into the German translation of the sgml doc when someone writes it...
-- why do we have psdrv.reg in documentation? Shouldn't it be with the other conf files?
It should probably be merged into winedefault.reg.
-- what's up with wine.texinfo? Is it still maintained? Shouldn't we incorporate whatever is in there in the .sgml, and get rid of it? Anyone knows the its status?
It should be merged into the .sgml and then removed, yes. -- Alexandre Julliard julliard(a)winehq.com
On September 18, 2002 01:51 pm, Alexandre Julliard wrote:
-- rename installation-und-konfiguration.german We have already a README.fr, we should be consistent.
But installation-und-konfiguration.german is not really a translation of the README. I think it should rather be integrated into the German translation of the sgml doc when someone writes it...
Yeah, it's a tough one. In general, I was thinking how to handle it, and I think we should not accept translated documentation expect for the README. Let me explain: obsolete docs is worse than no docs. Maintaining the English docs is hard as it is, maintaining the translated ones is impossible. Now, for the programming docs, we don't need translations: we implement alreay a documented interface that has books in every language. Moreover, if you need to code, you have to be able to read English, that's the reality. The value of translated docs is on the user side. Keep in mind that no one likes to read docs, so I suggest we have a README (that may be translated) which says: -- what is Wine, what's required -- a _few_ words for a simple install -- a _few_ words for the common configuration tweaks Sort of a QuickStart. It should be small (the current one is too big), and easy to translate, and maintain. So installation-und-konfiguration.german is kindda like that. All the other docs in the tree should be English, me thinks. Man pages should be translated by the man page translation teams out there. -- Dimi.
participants (4)
-
Alexandre Julliard -
Dimitrie O. Paun -
Eric POUECH -
Sylvain Petreolle