On September 20, 2002 04:13 pm, Eric Pouech wrote:
this patch adds winedump documentation (Alexandre, you can delete tools/winedump/README if you want)
Sorry, but I don't agree with this patch. Unix docs for command line utilities come in the form of man pages (or info pages). Why put in .sgml? Who's gonna read it there? Who's gonna maintain it there?
It should go into a file: programs/winedump/windump.man.in or similar...
Sorry, but I don't agree with this patch. Unix docs for command line utilities come in the form of man pages (or info pages). Why put in .sgml? Who's gonna read it there?
anyone who doesn't now Wine and wants to know about the provided tools I really don't think looking into the source in tools/winedump/README is way simpler
having it also as a man file should be done too, but not exclusively
On September 21, 2002 01:57 am, Eric Pouech wrote:
I really don't think looking into the source in tools/winedump/README is way simpler
Of course not. I would suggest: -- a general description in the .sgml docs. I don't think including too many details there would help anyone. This is documentation that you read to get familiar with the project, to understand what's available, what you can do. So yes, I fully agree that we should mention the tool in there, maybe give an example or two of usage, output, etc. -- keep all the formal details for the man page. IMO we need the man page first and foremost. The User Guide is a nice bonus. Plus, not duplicating the info is better for maintenance -- the biggest problem with docs is actually maintaining them. We have a lot of docs in the tree that are 2-4 years out of date! That's bad!!! It's way better to mention the tool in the User Guide, and then the user will look up the up-to-date details in the man page.
-
Dimitrie O. Paun -
Eric Pouech