Re: documentation: Remove ChangeLog.*.

[Octavian Voicu]

On Wed, Aug 31, 2011 at 3:25 PM, Octavian Voicu wrote:
> They are not used anymore. Last change was with the release of wine 1.0.
> Sent as attachment because of the huge lines.

Alexandre,

This patch was sent before I got your reply on wine-devel, so you can ignore it.
Probably was in the moderation queue because it is totally huge...

Octavian

Re: Documentation - Reference to MSDN?

[James McKenzie]

Vitaliy Margolen wrote:

On 06/30/2010 09:22 AM, Max TenEyck Woodbury wrote:
  

1) Would including the URL of the MSDN article be useful/a good idea?


No. Microsoft in all these years haven't figured out how to create permanent
links. All, and I really mean it _ALL_ URLS on MSDN had changed at least
once a year.

  
They have learned well from IBM.  I have links that I use at work that 
change on an almost weekly basis.

2) Would enumerating coded values and flags be allowed?


That's what headers are for.

  
Correct.  However, if a flag is used in more than one place, it would be 
'nice' to annotate that the flag/enumeration does exist.  Saves 
embarrassing and unnecessary patch submissions



3) Where should data structures be documented?


On MSDN. Wine is an implementation of API not the spec.
  
I agree.  The functions and their calls/results are what we are 
interested in.  We don't care how M$ got there, we are on a different path.


James McKenzie

Re: Documentation - Reference to MSDN?

[Vitaliy Margolen]

On 06/30/2010 09:22 AM, Max TenEyck Woodbury wrote:
> 1) Would including the URL of the MSDN article be useful/a good idea?
No. Microsoft in all these years haven't figured out how to create permanent
links. All, and I really mean it _ALL_ URLS on MSDN had changed at least
once a year.

> 2) Would enumerating coded values and flags be allowed?
That's what headers are for.

> 3) Where should data structures be documented?
On MSDN. Wine is an implementation of API not the spec.

Vitaliy.

Re: Documentation?

[Alexandre Julliard]

Luke Benstead  writes:

> While on the subject of documentation... would it be a good idea to
> begin documenting functions with something like Doxygen or similar?
> I'm just wondering if we could be building our own, much more
> accurate, MSDN. Is there a reason that Wine isn't documented in this
> way?

Yes, it's not useful. Wine implements the Win32 API, and there's plenty
of documentation for it already.  If you want to replicate MSDN you are
welcome to do it, but there's no reason to do it in Wine, the Win32 API
is not defined by the Wine code.

-- 
Alexandre Julliard
julli...@winehq.org

Re: Documentation?

[Juan Lang]

> Would documentation-only patches be accepted? For example, I can use
> my lunch break at work to document functions but it's not long enough
> to do any serious hacking. I only ask because I can't remember seeing
> documentation only patches on wine-patches :)

Indeed, yes.  There have been some documentation only patches
submitted and accepted once upon a time, but not in a while.
--Juan

Re: Documentation?

[Luke Benstead]

On 14 March 2010 12:08, Paul Vriens  wrote:
> On 03/14/2010 11:58 AM, Paul Vriens wrote:
>>
>> On 03/14/2010 11:45 AM, Luke Benstead wrote:
>>>
>>> On 14 March 2010 10:03, Roderick Colenbrander
>>> wrote:

 On Sat, Mar 13, 2010 at 11:40 PM, Scott Ritchie
 wrote:
>
> On 03/12/2010 11:01 AM, André Hentschel wrote:
>>
>> Hi Folks,
>> As we are getting somehow closer to Wine 1.2 i wonder how important
>> updates on the Documentation are.
>> Further i am confused about sending patches, should they just
>> change the
>> git-repo "docs" or the pages on the website or both?
>>
>
> The website pages are supposed to be automatically generated from
> the docs
> every release. So patch the docs themselves.
>
> Not sure if this process still works though.
>
> Thanks,
> Scott Ritchie
>

 I thought the plans were to attempt to move all documentation (in an
 updated form) to the Wiki. We would then need some mechanism to create
 documentation out of the wiki. Myself I rather update the wiki when I
 encounter an issue than that I update the old docs.

 Roderick



>>>
>>> While on the subject of documentation... would it be a good idea to
>>> begin documenting functions with something like Doxygen or similar?
>>> I'm just wondering if we could be building our own, much more
>>> accurate, MSDN. Is there a reason that Wine isn't documented in this
>>> way?
>>
>> We do have (the autogenerated) http://source.winehq.org/WineAPI/
>>
>> I know there is (was) an issue with the winapi tool so I can't tell if
>> the API documentation on that page is accurate.
>>
>
> I think the page I mentioned is fine.
>
> It's http://www.winehq.org/winapi_stats that didn't have an update in a
> while due to winapi issues.
>
> --
> Cheers,
>
> Paul.
>


Oh, I had actually seen that auto-generated documentation once before
then lost it - still there are many functions without documentation.

Would documentation-only patches be accepted? For example, I can use
my lunch break at work to document functions but it's not long enough
to do any serious hacking. I only ask because I can't remember seeing
documentation only patches on wine-patches :)

Luke.

Re: Documentation?

[Paul Vriens]

On 03/14/2010 11:58 AM, Paul Vriens wrote:

On 03/14/2010 11:45 AM, Luke Benstead wrote:

On 14 March 2010 10:03, Roderick Colenbrander
wrote:

On Sat, Mar 13, 2010 at 11:40 PM, Scott Ritchie
wrote:

On 03/12/2010 11:01 AM, André Hentschel wrote:


Hi Folks,
As we are getting somehow closer to Wine 1.2 i wonder how important
updates on the Documentation are.
Further i am confused about sending patches, should they just
change the
git-repo "docs" or the pages on the website or both?



The website pages are supposed to be automatically generated from
the docs
every release. So patch the docs themselves.

Not sure if this process still works though.

Thanks,
Scott Ritchie



I thought the plans were to attempt to move all documentation (in an
updated form) to the Wiki. We would then need some mechanism to create
documentation out of the wiki. Myself I rather update the wiki when I
encounter an issue than that I update the old docs.

Roderick





While on the subject of documentation... would it be a good idea to
begin documenting functions with something like Doxygen or similar?
I'm just wondering if we could be building our own, much more
accurate, MSDN. Is there a reason that Wine isn't documented in this
way?


We do have (the autogenerated) http://source.winehq.org/WineAPI/

I know there is (was) an issue with the winapi tool so I can't tell if
the API documentation on that page is accurate.



I think the page I mentioned is fine.

It's http://www.winehq.org/winapi_stats that didn't have an update in a 
while due to winapi issues.


--
Cheers,

Paul.

Re: Documentation?

[Paul Vriens]

On 03/14/2010 11:45 AM, Luke Benstead wrote:

On 14 March 2010 10:03, Roderick Colenbrander  wrote:

On Sat, Mar 13, 2010 at 11:40 PM, Scott Ritchie  wrote:

On 03/12/2010 11:01 AM, André Hentschel wrote:


Hi Folks,
As we are getting somehow closer to Wine 1.2 i wonder how important
updates on the Documentation are.
Further i am confused about sending patches, should they just change the
git-repo "docs" or the pages on the website or both?



The website pages are supposed to be automatically generated from the docs
every release.  So patch the docs themselves.

Not sure if this process still works though.

Thanks,
Scott Ritchie



I thought the plans were to attempt to move all documentation (in an
updated form) to the Wiki. We would then need some mechanism to create
documentation out of the wiki. Myself I rather update the wiki when I
encounter an issue than that I update the old docs.

Roderick





While on the subject of documentation... would it be a good idea to
begin documenting functions with something like Doxygen or similar?
I'm just wondering if we could be building our own, much more
accurate, MSDN. Is there a reason that Wine isn't documented in this
way?


We do have (the autogenerated) http://source.winehq.org/WineAPI/

I know there is (was) an issue with the winapi tool so I can't tell if 
the API documentation on that page is accurate.


--
Cheers,

Paul.

Re: Documentation?

[Luke Benstead]

On 14 March 2010 10:03, Roderick Colenbrander  wrote:
> On Sat, Mar 13, 2010 at 11:40 PM, Scott Ritchie  wrote:
>> On 03/12/2010 11:01 AM, André Hentschel wrote:
>>>
>>> Hi Folks,
>>> As we are getting somehow closer to Wine 1.2 i wonder how important
>>> updates on the Documentation are.
>>> Further i am confused about sending patches, should they just change the
>>> git-repo "docs" or the pages on the website or both?
>>>
>>
>> The website pages are supposed to be automatically generated from the docs
>> every release.  So patch the docs themselves.
>>
>> Not sure if this process still works though.
>>
>> Thanks,
>> Scott Ritchie
>>
>
> I thought the plans were to attempt to move all documentation (in an
> updated form) to the Wiki. We would then need some mechanism to create
> documentation out of the wiki. Myself I rather update the wiki when I
> encounter an issue than that I update the old docs.
>
> Roderick
>
>
>

While on the subject of documentation... would it be a good idea to
begin documenting functions with something like Doxygen or similar?
I'm just wondering if we could be building our own, much more
accurate, MSDN. Is there a reason that Wine isn't documented in this
way?

Luke.

Re: Documentation?

[Roderick Colenbrander]

On Sat, Mar 13, 2010 at 11:40 PM, Scott Ritchie  wrote:
> On 03/12/2010 11:01 AM, André Hentschel wrote:
>>
>> Hi Folks,
>> As we are getting somehow closer to Wine 1.2 i wonder how important
>> updates on the Documentation are.
>> Further i am confused about sending patches, should they just change the
>> git-repo "docs" or the pages on the website or both?
>>
>
> The website pages are supposed to be automatically generated from the docs
> every release.  So patch the docs themselves.
>
> Not sure if this process still works though.
>
> Thanks,
> Scott Ritchie
>

I thought the plans were to attempt to move all documentation (in an
updated form) to the Wiki. We would then need some mechanism to create
documentation out of the wiki. Myself I rather update the wiki when I
encounter an issue than that I update the old docs.

Roderick

Re: Documentation?

[Scott Ritchie]

On 03/12/2010 11:01 AM, André Hentschel wrote:

Hi Folks,
As we are getting somehow closer to Wine 1.2 i wonder how important updates on 
the Documentation are.
Further i am confused about sending patches, should they just change the git-repo 
"docs" or the pages on the website or both?



The website pages are supposed to be automatically generated from the 
docs every release.  So patch the docs themselves.


Not sure if this process still works though.

Thanks,
Scott Ritchie

Re: Documentation

[Ben Klein]

2009/4/1 Fred . :
> I saw on http://www.winehq.org/status/wine
> That there Nonexistent documentation for "Initial directory structure"
> and Poor documentation for "Initial INI files".
>
> So I wrote documentation for those on the wiki.
> http://wiki.winehq.org/Initial_directory_structure
> http://wiki.winehq.org/Initial_INI_files

Wiki pages should be in CamelCase, not with underscores in the names.

What you've got is a good start, but so far it's nothing that can't be
determined from normal usage of Wine. What's needed from here is:
1) an explanation of why Wine creates INI files/this directory structure
2) what each of the INI files do, what the default contents of the
directories are, why they're needed, what they do etc
3) Mention WINEPREFIX and make it more obvious where the default
location of the wine directory is (perhaps this deserves another wiki
page?)

> Hope I helped out, and this was useful. If so, it could be linked from
> the /status/wine article, and maybe
> move to /site/docs/winedev-guide/

Re: Documentation updating / XML?

[Francois Gouget]

On Tue, 22 Apr 2008, Austin English wrote:
[...]
> On Tue, Apr 22, 2008 at 5:25 AM, Alexandre Julliard <[EMAIL PROTECTED]>
> wrote:
> 
> > "Austin English" <[EMAIL PROTECTED]> writes:
> >
> > > I've been working on some of the documentation, then remembered that
> > > Scott requested a move to XML:
> > > http://bugs.winehq.org/show_bug.cgi?id=12217
> > >
> > > There are quite a few programs to convert SGML to XML, and I've got a
> > > bit of time to kill. Alexandre, would you accept a move to XML, or 
> > > would this be a waste of time?
[...]
> Web/html/PDF/XML?

I would vote for DocBook XML so we can get Html and PDF documents out of 
it. Also now po4a works quite well with it. I could give you a hand on 
the po4a part.

However I'd say that there are some subtle but important differences 
between DocBook SGML and DocBook XML, especially around the include 
mechanism. So I'm a bit skeptical that automated tools can really 
produce clean DocBook XML code. But then they can probably be a good 
starting point.

It would also be nice if we could switch to a Git repository. Since 
it's not possible with SourceForge it would mean moving elsewhere. Would 
it be possible to have get it hosted on winehq.org?

-- 
Francois Gouget <[EMAIL PROTECTED]>  http://fgouget.free.fr/
 Advice is what we ask for when we already know the answer but wish we didn't
 -- Eric Jong

Re: Documentation updating / XML?

[Austin English]

On Tue, Apr 22, 2008 at 5:25 AM, Alexandre Julliard <[EMAIL PROTECTED]>
wrote:

> "Austin English" <[EMAIL PROTECTED]> writes:
>
> > I've been working on some of the documentation, then remembered that
> Scott
> > requested a move to XML:
> > http://bugs.winehq.org/show_bug.cgi?id=12217
> >
> > There are quite a few programs to convert SGML to XML, and I've got a
> bit of
> > time to kill. Alexandre, would you accept a move to XML, or would this
> be a
> > waste of time?
>
> I don't really care about the format as long as there are decent tools
> to generate all the outputs we want. Considering the state of SGML tools
> it's probably not hard to do better...
>
> --
> Alexandre Julliard
> [EMAIL PROTECTED]
>

Web/html/PDF/XML?

Re: Documentation updating / XML?

[Alexandre Julliard]

"Austin English" <[EMAIL PROTECTED]> writes:

> I've been working on some of the documentation, then remembered that Scott
> requested a move to XML:
> http://bugs.winehq.org/show_bug.cgi?id=12217
>
> There are quite a few programs to convert SGML to XML, and I've got a bit of
> time to kill. Alexandre, would you accept a move to XML, or would this be a
> waste of time?

I don't really care about the format as long as there are decent tools
to generate all the outputs we want. Considering the state of SGML tools
it's probably not hard to do better...

-- 
Alexandre Julliard
[EMAIL PROTECTED]

Re: Documentation is still in CVS?

[Hin-Tak Leung]

--- On Fri, 4/4/08, Lei Zhang <[EMAIL PROTECTED]> wrote:

> From: Lei Zhang <[EMAIL PROTECTED]>
> Subject: Re: Documentation is still in CVS?
> To: "Hin-Tak Leung" <[EMAIL PROTECTED]>
> Cc: "Wine Devel" 
> Date: Friday, 4 April, 2008, 6:50 PM
> On Fri, Apr 4, 2008 at 8:35 AM, Hin-Tak Leung
> <[EMAIL PROTECTED]> wrote:
> >  Doesn't work for me:
> >
> >  $ cvs -z3
> -d:pserver:[EMAIL PROTECTED]:/cvsroot/wine
> co -P docs
> >  cvs [checkout aborted]: connect to
> [wine.cvs.sourceforge.net]:2401 failed: Connection timed
> out
> >
> >  $ git cvsimport -C wine-doc -v -k -d
> :pserver:[EMAIL PROTECTED]:/cvsroot/wine
> docs
> >  Socket to wine.cvs.sourceforge.net: Connection timed
> out
> >
> >  I'll need to try stunnel and see if it improves
> things. (but I can still check out stuff from other
> sourceforge projects...)
> >
> 
> Firewall issue on your side? Can you ping
> wine.cvs.sourceforge.net?
> Connect to it on port 80? or port 2401?

Can do port 80, can't do port 2401. Wierd. It is probably problem in my end.



  ___ 
Yahoo! For Good helps you make a difference  

http://uk.promotions.yahoo.com/forgood/

Re: Documentation is still in CVS?

[Hin-Tak Leung]

--- On Thu, 3/4/08, Lei Zhang <[EMAIL PROTECTED]> wrote:


> The instructions on http://www.winehq.org/site/cvs works
> for me.

Doesn't work for me:

$ cvs -z3 -d:pserver:[EMAIL PROTECTED]:/cvsroot/wine co -P docs
cvs [checkout aborted]: connect to [wine.cvs.sourceforge.net]:2401 failed: 
Connection timed out

$ git cvsimport -C wine-doc -v -k -d :pserver:[EMAIL PROTECTED]:/cvsroot/wine 
docs 
Socket to wine.cvs.sourceforge.net: Connection timed out

I'll need to try stunnel and see if it improves things. (but I can still check 
out stuff from other sourceforge projects...)


  ___ 
Yahoo! For Good helps you make a difference  

http://uk.promotions.yahoo.com/forgood/

Re: Documentation is still in CVS?

[Lei Zhang]

On Fri, Apr 4, 2008 at 8:35 AM, Hin-Tak Leung <[EMAIL PROTECTED]> wrote:
>  Doesn't work for me:
>
>  $ cvs -z3 -d:pserver:[EMAIL PROTECTED]:/cvsroot/wine co -P docs
>  cvs [checkout aborted]: connect to [wine.cvs.sourceforge.net]:2401 failed: 
> Connection timed out
>
>  $ git cvsimport -C wine-doc -v -k -d :pserver:[EMAIL 
> PROTECTED]:/cvsroot/wine docs
>  Socket to wine.cvs.sourceforge.net: Connection timed out
>
>  I'll need to try stunnel and see if it improves things. (but I can still 
> check out stuff from other sourceforge projects...)
>

Firewall issue on your side? Can you ping wine.cvs.sourceforge.net?
Connect to it on port 80? or port 2401?

Re: Documentation is still in CVS?

[Lei Zhang]

On Thu, Apr 3, 2008 at 11:29 AM, Hin-Tak Leung <[EMAIL PROTECTED]> wrote:
>  Actually I tried to follow the wiki instructions to do a git-cvsimport and 
> it didn't work a week or two ago; and plain "cvs co" did not work either.
>  I have a few other stuff on sourceforge, so the problem seems to be specific 
> to wine. Does anonymous check out work for anybody else?
>

The instructions on http://www.winehq.org/site/cvs works for me.

Re: Documentation is still in CVS?

[Hin-Tak Leung]

--- On Thu, 3/4/08, Dimi Paun <[EMAIL PROTECTED]> wrote:

> From: Dimi Paun <[EMAIL PROTECTED]>
> Subject: Re: Documentation is still in CVS?
> To: "Wine Devel" 
> Date: Thursday, 3 April, 2008, 6:50 PM
> On Thu, 2008-04-03 at 10:37 -0700, Lei Zhang wrote:
> > Is there a reason why the Wine documentation is still
> in CVS, and not
> > in GIT?
> 
> Yes. The docs are now maintained at SourceForge, and given
> the glacial
> pace of updates, there is little reason to move them to
> git. Moreover,
> git presents a much higher barrier to entry, and
> there's no reason to
> raise it for (potentially non-technical) documentation
> contributors.
>

Actually I tried to follow the wiki instructions to do a git-cvsimport and it 
didn't work a week or two ago; and plain "cvs co" did not work either.
I have a few other stuff on sourceforge, so the problem seems to be specific to 
wine. Does anonymous check out work for anybody else? 






  __
Sent from Yahoo! Mail.
A Smarter Inbox http://uk.docs.yahoo.com/nowyoucan.html

Re: Documentation is still in CVS?

[Dimi Paun]

On Thu, 2008-04-03 at 10:37 -0700, Lei Zhang wrote:
> Is there a reason why the Wine documentation is still in CVS, and not
> in GIT?

Yes. The docs are now maintained at SourceForge, and given the glacial
pace of updates, there is little reason to move them to git. Moreover,
git presents a much higher barrier to entry, and there's no reason to
raise it for (potentially non-technical) documentation contributors.

-- 
Dimi Paun <[EMAIL PROTECTED]>
Lattica, Inc.

Re: Documentation for CLEANLOCALSTORAGE in OLE Automation

[Huw D M Davies]

On Wed, Apr 19, 2006 at 12:24:07AM +0100, Robert Shearman wrote:
> Hi,
> 
> I just thought I'd document the CLEANLOCALSTORAGE use in oleaut32 for 
> anyone that wants to implement it, although I can't implement it now for 
> obvious reasons.

Great, thanks.  I just sent a patch to wine-patches that implements
this for GetLibAttr.

> 
> First of all the background: the reason CLEANLOCALSTORAGE is needed is 
> because the structures returned from various Get* functions in ITypeInfo 
> and ITypeLib have pointers that have been allocated opaquely and have to 
> be freed using the corresponding Release* function. AFAICS, the problem 
> is not that the memory will not be freed (the RPC runtime should 
> traverse the structure thoroughly and release all of the pointers with 
> NdrOleFree), but that some of the memory may not need to be freed (and 
> memory corruption could take place if it were).

Yeah, and the reason it works is that the CLEANLOCALSTORAGE paramater
is last and hence marshalled after the structure of interest, so we
get a chance to call the _Release function before the stub does its
own cleanup.

Huw.
-- 
Huw Davies
[EMAIL PROTECTED]

Re: Documentation for CLEANLOCALSTORAGE in OLE Automation

[Mike Hearn]

On Wed, 19 Apr 2006 00:24:07 +0100, Robert Shearman wrote:
> Hi,
> 
> I just thought I'd document the CLEANLOCALSTORAGE use in oleaut32 for 
> anyone that wants to implement it, although I can't implement it now for 
> obvious reasons.

Rob, can you put this stuff on the wiki?

Re: Documentation of Parallel and Serial port configuration?

[Paul Millar]

Hi Kuba,

On Thursday 06 Oct 2005 23:23, Kuba Ober wrote:
> > we can probably do better than inb() / outb().
>
> You can't do any better than that [It] is the only one that makes sense
> (when you run things on ia32).

... and when you're not on an ia32 platform with a superIO chip?


> > Advantages of using ppdev over simple inb() / outb() are:
> >
> >   should support [*] cross-architecture (arm, alpha, powerpc, ...)
> That'd be good for winelib only or wine-with-emulator (bochs? qemu?).

Yup, both.  A ported applications (via winelib or qemu) should work under any 
Linux architecture.  Unfortunately, it would be a Linux-specific solution; 
*-BSDs have their own interface.


> >   should support [*] some esoteric devices (USB-parallel converters, ...)
> At a huge performance penalty ;)

But it would work, 's my point.  The performance of parallel-over-USB is a 
separate issue.

Legacy devices (such as parallel ports) are being gradually faded out.  So 
writing code that requires a SuperIO chip is not best.

> > The overhead in doing a syscall isn't significant as any outb() operation
> > takes ~1us anyway
>
> AFAIK, the overhead stems from the fact that instead of a machine
> instruction you have to:
> - process an exception in the kernel, which then signals SIGSEGV to the
> process
> - invoke the signal handler
> - determine what's up and disassemble the instruction at CS:EIP
> - invoke a function/syscall based on the disassembled instruction
>
> If this isn't dog slow, I don't know what is. I wasn't entirely clear, the
> syscall is the least of our worries in fact :)


I think you may be confusing some other activity (maybe an invalid memory 
access?).  A syscall is pretty simple.  The application does some bookkeeping 
and calls int(errupt) 0x80, triggering the switch from user-land to 
kernel-land.  The kernel then picks up the request and carries on.  Its 
described here[1], although the details may have changed slightly with more 
recent kernels.  There's no signalling (in the Unix user-land sense) going 
on.

[1] http://www.tldp.org/LDP/khg/HyperNews/get/syscall/syscall86.html

Overhead is "currently" (measured for 2.4.0) at slightly under 0.4us (see 
[2]).  For 2.6-series kernels it may have gone down slightly further, but 
0.4us would seem a reasonable upper-bound.  Assuming the kernel driver is 
reasonably written,  I'd make a complete guess that the overhead is between 
0.4 and 0.6us (although I should benchmark the number :^).

[2] http://cs.nmu.edu/~benchmark/index.php?page=null_call

> > I suspect most programs designed to work under Win98 just hit the
> > hardware, so obtaining permissions (doing ioperm() as root, for example)
> > should work. If we have some mechanism for catching the program doing
> > either inb() or outb(), then we could provide a better implement via the
> > ppdev interface.
>
> At the cost of slowing things down. For devices that bit bang data (like
> programmers), this makes things unacceptably slow.

I can't say I share that experience (about being unacceptably slow, that is).  
A 40-60% increase in overhead for a single instruction would be definitely 
noticeable, but only if this is the bottleneck in the program.  Other 
activity takes longer (c.f. context-switching in [2], for example).  Even 
just calling functions take order of 100ns (on my ~700MHz laptop).  The time 
between successive changes of parallel port state might be (much) larger than 
the 400-600ns overhead in using kernel routines, so the overhead becomes less 
significant.  Of course, this would be application specific.

The worse-case would be something driving the parallel port as a square-wave 
generator: you'd get the full 40-60% drop in performance (assuming all the 
above numbers).  Perhaps slightly more realistically, the PLIP interface is 
reckoned[3] to have a 1.2Mbit/s bandwidth, corresponding to a ~3.33us 
turn-around time.  Adding a 0.4-0.6us overhead would reduce the bandwidth to 
between 1.1Mbit/s and 1.0Mbit/s (8-16% performance drop).  Would this matter? 
No, because if it did you'd go out and buy 100baseT cards and achieve far 
greater performance (or Myrinet, or ...).

[3] http://yara.ecn.purdue.edu/~pplinux/ppcluster.html

For the particular use-case you have in mind, my understanding is that 
programmers often require some additional delay mechanism to allow the EPROM 
to keep up (certainly for write, probably for reads too).  This would reduce 
the impact of the performance hit, perhaps acceptably (or even imperceptibly) 
so.

Does all this matter?  Probably not.  I would bet you this smartee here that 
if a program is worrying about ns response of some function, then that 
function its good enough, and that some better "higher level" algorithmic 
optimisation would have a much larger benefit (e.g. ethernet vs PLIP).

Cheers,

Paul.

(apologies for the overly long email!)


pgpNuWn5Doovp.pgp
Description: PGP signature

Re: Documentation of Parallel and Serial port configuration?

[Kuba Ober]

> > > we can probably do better than inb() / outb().
> > You can't do any better than that [It] is the only one that makes sense
> > (when you run things on ia32).
> ... and when you're not on an ia32 platform with a superIO chip?

That's a moot point. Then you have to emulate ia32 to run windows programs 
anyway.

> > > Advantages of using ppdev over simple inb() / outb() are:
> > >
> > >   should support [*] cross-architecture (arm, alpha, powerpc, ...)
> >
> > That'd be good for winelib only or wine-with-emulator (bochs? qemu?).
>
> Yup, both.  A ported applications (via winelib or qemu) should work under
> any Linux architecture.  Unfortunately, it would be a Linux-specific
> solution; *-BSDs have their own interface.

If you have access to the source it's simpler to write a native device driver. 
The only reason d'etre of running legacy windows apps that bit-bang things 
via direct port i/o is that there's no documentation for the hardware.

> > >   should support [*] some esoteric devices (USB-parallel converters,
> > > ...)
> >
> > At a huge performance penalty ;)
>
> But it would work, 's my point.  The performance of parallel-over-USB is a
> separate issue.
>
> Legacy devices (such as parallel ports) are being gradually faded out.  So
> writing code that requires a SuperIO chip is not best.

Sure. But then you're talking about the driver code, not user code.

I think this discussion needs some clarification, as there are distinct use 
cases:

Case 1. Running legacy ia32 windows code that does port I/O on ia32.
Case 2 : Running such legacy code on non-ia32.
Case 3. Porting such apps over to winelib when the source code is available.

For (1) ioperm is the only reasonable solution. The hardware is there for you 
to do the job, so why bother emulating existing functionality.

For (2) you are doing instruction-by-instruction emulation, or at least block 
translation anyway, i.e. wine running with an ia32 emulator. So it doesn't 
really matter what you do, as there's no ia32 and likely no direct access to 
the 'ports' on target hardware. If the target hardware is a serial/parallel 
port, the motherboard chipset is likely to implement it in a wholly different 
way (or not at all!). The only chance for 1:1 plug-in compatibility is when 
target hardware is a PCI card. I don't know how many direct-IO win32 apps are 
there for PCI cards that are relevant enough to be moved to a more up-to-date 
non-ia32 hardware.

For (3), the simplest thing to do is to tear off the driver code and port it 
to the platform's driver infrastructure. Using winelib for any sort of 
emulation there is a waste of resources.

> > AFAIK, the overhead stems from the fact that instead of a machine
> > instruction you have to:
> > - process an exception in the kernel, which then signals SIGSEGV to the
> > process
> > - invoke the signal handler
> > - determine what's up and disassemble the instruction at CS:EIP
> > - invoke a function/syscall based on the disassembled instruction
> >
> > If this isn't dog slow, I don't know what is. I wasn't entirely clear,
> > the syscall is the least of our worries in fact :)
>
> I think you may be confusing some other activity (maybe an invalid memory
> access?). 

How's an invalid memory access different from a legacy win32 application 
trying to do direct port IO without sufficient privileges?

1. You have an IN or OUT opcode in the code. When ioperms are not set, the CPU 
raises an exception.
2. That exception results in SIGSEGV being signalled to the process. 
3. The signal handler has to determine what type of an exception is it.  I 
don't recall whether the exception data has information about the type of 
exception, but in any event the opcode has to be disassembled just to get the 
port address and data operands. 
4. Then in all likelihood the operands are not immediate constants, so the 
relevant registers have to be interrogated from the saved below-signal 
process context. 
5. A port-to-filehandle look up has to be performed, in order to determine 
which open device has to handle that port I/O.
6. An ioctl has to be invoked on that handle.
7. Kernel's ioctl machinery is invoked, and the ioctl percolates to the driver 
code. Remember that ioctl requests can be handled by different layers of the 
driver stack, so it has literally to go the slowest path, through all the 
intermediate layers down to the driver. That's a bunch of switch statements 
to go through.
8. An actual port I/O is done by the driver, in case of 1:1 mapping, or a 
request is put to the bus subsystem if a legacy device (like a parallel port) 
is being handled via a usb/firewire "converter".

This code path is on the order of thousands of instructions long. If you have 
a legacy ia32 app running under wine on ia32 hardware, there's no point in 
doing all that in place of a simple port I/O.

> A syscall is pretty simple.  

Of course. But it's not "just about a syscall". And besides, even a syscall 
that has just a "ret" o

Re: Documentation of Parallel and Serial port configuration?

[Paul Millar]

Hi all,

If the bit-wise manipulation of the parallel port is exposed as some kind of 
interface under Win9x, we can probably do better than inb() / outb().  Under 
Linux, there's ppdev (a user-land bit-twiddling interface since 2.4-series 
kernels).  

Advantages of using ppdev over simple inb() / outb() are:
  should support [*] cross-architecture (arm, alpha, powerpc, ...)
  should support [*] some esoteric devices (USB-parallel converters, ...)
  only need permission to open /dev/parport0 (not necessarily root or 
CAP_SYS_RAWIO).

[*] - I've not tested either of these, though.

The overhead in doing a syscall isn't significant as any outb() operation 
takes ~1us anyway.  There may be an increased risk of context-switching after 
the syscall (please correct me if I'm wrong here), which would lead to the 
ppdev being apparently slower.  But this, in itself, shouldn't be a problem.

I suspect most programs designed to work under Win98 just hit the hardware, so 
obtaining permissions (doing ioperm() as root, for example) should work.  If 
we have some mechanism for catching the program doing either inb() or outb(), 
then we could provide a better implement via the ppdev interface.

I believe (from limited exposure) that under Win2k, accessing the parallel 
port is "more difficult".  Applications may use some kind of .sys driver to 
expose a bit-wise interface to the parallel port, which may be part of some 
"standard".  I guess this could be implemented using ppdev by some 
enthusiastic person.

Cheers,

Paul.

On Thursday 06 Oct 2005 14:14, Kuba Ober wrote:
> > >> Several years ago I had my programmer and one other device working
> > >> with dosemu and or bochs but after I updated from Mandrake 8.2 I
> > >> think I have not been able to get it working again. I think the
> > >> kernel has changed on hardware access and will require special
> > >> driver to allow simulated direct hardware access.
> >
> > Kuba> man ioperm 2
> >
> > Kuba> You can use it via a suid-root wrapper program that acquires
> > the Kuba> port access, drops privileges and executes your wine
> > Kuba> programs. Works for me. Of course it doesn't work if the
> > windows Kuba> program needs the special driver to talk to the device. It
> > does Kuba> work for those old-style windows95 applications that expect to
> > be Kuba> able to talk to the ports directly.
> >
> > For both the serial and the parallel port, direct port access can be
> > handled by ioctl() to the devices. So doing direct port access via in()
> > and out() while running as root is only the last resort...
>
> The ioperm() method is more general (works for any port, not only for
> serial/parallel devices) and also faster (doesn't do a syscall). It
> requires no changes to the win95-style applications. Also, ioperm() doesn't
> imply running as root. You only need a trivial (couple lines long)
> suid-root wrapper written in C, that then invokes your regular windows
> application using wine.
>
> Cheers, Kuba


pgpL2aBhHDezO.pgp
Description: PGP signature

Re: Documentation of Parallel and Serial port configuration?

[Kuba Ober]

> If the bit-wise manipulation of the parallel port is exposed as some kind
> of interface under Win9x, 

Yes. It's exposed by enabling access to all io ports by default.

> we can probably do better than inb() / outb().  

You can't do any better than that. If an application does inb()/outb(), the 
ioperm method is the only one that makes sense (when you run things on ia32).

> Advantages of using ppdev over simple inb() / outb() are:

>   should support [*] cross-architecture (arm, alpha, powerpc, ...)

That'd be good for winelib only or wine-with-emulator (bochs? qemu?).

>   should support [*] some esoteric devices (USB-parallel converters, ...)

At a huge performance penalty ;)

> The overhead in doing a syscall isn't significant as any outb() operation
> takes ~1us anyway

AFAIK, the overhead stems from the fact that instead of a machine instruction 
you have to:
- process an exception in the kernel, which then signals SIGSEGV to the 
process
- invoke the signal handler
- determine what's up and disassemble the instruction at CS:EIP
- invoke a function/syscall based on the disassembled instruction

If this isn't dog slow, I don't know what is. I wasn't entirely clear, the 
syscall is the least of our worries in fact :)

> I suspect most programs designed to work under Win98 just hit the hardware,
> so obtaining permissions (doing ioperm() as root, for example) should work.
>  If we have some mechanism for catching the program doing either inb() or
> outb(), then we could provide a better implement via the ppdev interface.

At the cost of slowing things down. For devices that bit bang data (like 
programmers), this makes things unacceptably slow.

> I believe (from limited exposure) that under Win2k, accessing the parallel
> port is "more difficult".  Applications may use some kind of .sys driver to
> expose a bit-wise interface to the parallel port, which may be part of some
> "standard".  I guess this could be implemented using ppdev by some
> enthusiastic person.

Yep, that's another story entirely.

Cheers, Kuba

Re: Documentation of Parallel and Serial port configuration?

[Mike Hearn]

On Tue, 04 Oct 2005 16:49:55 +0200, Holly Bostick wrote:
> The thing is, there's a question on wine-users as to how to configure
> parallel ports in the absence of the config file. 

What configuration is actually needed? IIRC the config file contained some
magic numbers in hex, not something that should ever have been exposed to
users (hell, I have no clue what they mean either :).

I can't think of anything that would need configuration here, can't we
auto-detect everything?

> However, naturally this user is not the only one who's going to want to
> know if they have to edit system.reg or something to configure their
> ports, and I certainly don't want to guess or assume in the docs. 

Well, better than editing text files is using regedit.

If you want to fix this, finding out what the hell the old settings did
would be a good start ;)

thanks -mike

Re: Documentation of Parallel and Serial port configuration?

[Kuba Ober]

> >> Several years ago I had my programmer and one other device working
> >> with dosemu and or bochs but after I updated from Mandrake 8.2 I
> >> think I have not been able to get it working again. I think the
> >> kernel has changed on hardware access and will require special
> >> driver to allow simulated direct hardware access.
>
> Kuba> man ioperm 2
>
> Kuba> You can use it via a suid-root wrapper program that acquires the
> Kuba> port access, drops privileges and executes your wine
> Kuba> programs. Works for me. Of course it doesn't work if the windows
> Kuba> program needs the special driver to talk to the device. It does
> Kuba> work for those old-style windows95 applications that expect to be
> Kuba> able to talk to the ports directly.
>
> For both the serial and the parallel port, direct port access can be
> handled by ioctl() to the devices. So doing direct port access via in() and
> out() while running as root is only the last resort...

The ioperm() method is more general (works for any port, not only for 
serial/parallel devices) and also faster (doesn't do a syscall). It requires 
no changes to the win95-style applications. Also, ioperm() doesn't imply 
running as root. You only need a trivial (couple lines long) suid-root 
wrapper written in C, that then invokes your regular windows application 
using wine.

Cheers, Kuba

Re: Documentation of Parallel and Serial port configuration?

[Uwe Bonnes]

> "Kuba" == Kuba Ober <[EMAIL PROTECTED]> writes:

>> Several years ago I had my programmer and one other device working
>> with dosemu and or bochs but after I updated from Mandrake 8.2 I
>> think I have not been able to get it working again. I think the
>> kernel has changed on hardware access and will require special driver
>> to allow simulated direct hardware access.

Kuba> man ioperm 2

Kuba> You can use it via a suid-root wrapper program that acquires the
Kuba> port access, drops privileges and executes your wine
Kuba> programs. Works for me. Of course it doesn't work if the windows
Kuba> program needs the special driver to talk to the device. It does
Kuba> work for those old-style windows95 applications that expect to be
Kuba> able to talk to the ports directly.

For both the serial and the parallel port, direct port access can be handled
by ioctl() to the devices. So doing direct port access via in() and out()
while running as root is only the last resort...

-- 
Uwe Bonnes[EMAIL PROTECTED]

Institut fuer Kernphysik  Schlossgartenstrasse 9  64289 Darmstadt
- Tel. 06151 162516  Fax. 06151 164321 --

Re: Documentation of Parallel and Serial port configuration?

[Kuba Ober]

> Several years ago I had my programmer and one other device working with
> dosemu and or bochs but after I updated from Mandrake 8.2 I think I have
> not been able to get it working again. I think the kernel has changed on
> hardware access and will require special driver to allow simulated
> direct hardware access.

man ioperm 2

You can use it via a suid-root wrapper program that acquires the port access, 
drops privileges and executes your wine programs. Works for me. Of course it 
doesn't work if the windows program needs the special driver to talk to the 
device. It does work for those old-style windows95 applications that expect 
to be able to talk to the ports directly.

Cheers, Kuba

Re: Documentation of Parallel and Serial port configuration?

[paul]

Juan Lang wrote:

Hi Holly, there's no UI to do this yet, as you found out.

By default, you don't need to do any config, at least on Linux.  COM1
defaults to /dev/ttyS0, COM2 to /dev/ttyS1, and so on.  LPT1 defaults to
/dev/lp0.. you get the idea.

If you want to change it, you can create a link in .wine/dosdevices from,
say, com1 to the device you want it to use.  So if for example you wanted
com1 to be /dev/cua0, you should have this in dosdevices:
lrwxrwxrwx  1 juan juan 9 Oct  4 08:15 com1 -> /dev/cua0

Hope that helps,
--Juan



__ 
Yahoo! Mail - PC Magazine Editors' Choice 2005 
http://mail.yahoo.com






Also it would be nice to include any info as to the status of using the 
parallel port to interface into devices like:

dongles with are a software unlock key.
eprom programmers which require a special driver on NT to access the 
hardware.


I think the current status is that it will not work or I have not found 
the correct solution.


Several years ago I had my programmer and one other device working with 
dosemu and or bochs but after I updated from Mandrake 8.2 I think I have 
not been able to get it working again. I think the kernel has changed on 
hardware access and will require special driver to allow simulated 
direct hardware access.


Paul

Re: Documentation of Parallel and Serial port configuration?

[Juan Lang]

Hi Holly, there's no UI to do this yet, as you found out.

By default, you don't need to do any config, at least on Linux.  COM1
defaults to /dev/ttyS0, COM2 to /dev/ttyS1, and so on.  LPT1 defaults to
/dev/lp0.. you get the idea.

If you want to change it, you can create a link in .wine/dosdevices from,
say, com1 to the device you want it to use.  So if for example you wanted
com1 to be /dev/cua0, you should have this in dosdevices:
lrwxrwxrwx  1 juan juan 9 Oct  4 08:15 com1 -> /dev/cua0

Hope that helps,
--Juan



__ 
Yahoo! Mail - PC Magazine Editors' Choice 2005 
http://mail.yahoo.com

Re: Documentation update

[Dimi Paun]

On Sun, 2005-10-02 at 21:47 +, Molle Bestefich wrote:
>   Fix up winedev-debugger doc to match 0.9.
>   Remove 404s, remove config file references, mention disassemblers
> that actually installs, etc.

Applied, but in the future please include [WINEDOC] at the
beginning of the Subject: so I can pick it up easier.

-- 
Dimi Paun <[EMAIL PROTECTED]>
Lattica, Inc.

Re: Documentation volunteer(s) needed

[Dimi Paun]

From: "Holly Bostick" <[EMAIL PROTECTED]>
> I will first say that I did get the docs to compile (so now I can read
> and edit them), *but* I had to compile all formats to do so.

Sorry about that, the French version is still not up to par.
 
> I also tried make html en (since I have no use for the French version
> either); that also failed with the same error, but that may not be a
> valid command -- the README doesn't really say that I can combine the
>  and  switches, but I thought I'd try.

You just have to change dir to the en/ dir:
   cd en; make html
That would do what you want to accomplish.
 
> So I have no idea whether installing docbook-sgml and sgmltools-lite had
> any effect, or whether make html is just not properly working for some
> reason, but I thought I should report the experience.

Thank you! Let's hope someone fixes the French docs building issues
(hint, hint! :)).

-- 
Dimi Paun <[EMAIL PROTECTED]>
Lattica, Inc.

Re: Documentation volunteer(s) needed

[Holly Bostick]

Dimi Paun schreef:
> On Tue, 2005-09-20 at 23:30 +0200, Holly Bostick wrote:
> 
>> But in any case, I'm having another problem somewhat more
>> relevant-- the docs don't compile as html for me:
> 
> 
> It should be fixed now, just get the latest version.
> 

Just a quick note-- I deleted the previous docs source dir, checked out
the current one an hour ago.

I will first say that I did get the docs to compile (so now I can read
and edit them), *but* I had to compile all formats to do so.

I was unable to compile just the html (which would have been preferable
to me, since I have no use for .ps or.pdf files), because make html
consistently failed with the following error:

 ./configure; make html
checking whether make sets $(MAKE)... yes
checking for docbook2html... docbook2html
checking for docbook2pdf... docbook2pdf
checking for docbook2ps... docbook2ps
checking for docbook2txt... docbook2txt
checking for nsgmls... nsgmls
configure: creating ./config.status
config.status: creating Make.rules
config.status: creating Makefile
config.status: creating en/Makefile
config.status: creating fr/Makefile

Configure finished.  Do 'make' to compile the documentation.

make[1]: Entering directory `/usr/local/src/docs/en'
docbook2html -u winedev-guide.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/winedev-guide.sgml
Done.
docbook2html -u wineusr-guide.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/wineusr-guide.sgml
Done.
docbook2html -u winelib-guide.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/winelib-guide.sgml
Done.
docbook2html -u wine-faq.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/wine-faq.sgml
Done.
make[1]: Leaving directory `/usr/local/src/docs/en'
make[1]: Entering directory `/usr/local/src/docs/fr'
PERLLIB=../po4a/lib perl ../po4a/po4a-translate -v -f sgml -m
../en/wineusr-guide.sgml -p ./wineusr-guide.po -l wineusr-guide.sgml -k 1
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators (contains only tags)
po4a::sgml: msgid skipped to help translators 

Re: Documentation volunteer(s) needed

[josephblack]

Brian Vincent wrote:
> On 9/23/05, josephblack <[EMAIL PROTECTED]> wrote:

>>After some discussion, Jason has confirmed he would like to
>>raise an offer of wine-wiki.org and its contents to the Wine project.

> First off, there's a lot of useful info in that wiki.  It obvious a
> lot of time has gone into it.

thanks. Since starting, the wiki has collected tips for nearly a year. I 
have been trying to make time to send drafts to wine docs - such as some 
of the info about regression testing.


> However, I really don't see the point of having that wiki and I think
> it has the potential to do more harm than good.  If there's one thing
> Wine and the rest of the community has proven over and over, it's that
> we can't maintain documentation.  I'd (almost) argue its best to have
> no documentation than completely incorrect docs.
>
> I realize that wiki came into existence before Wine's own, but now
> that we have one I think some of that info needs to migrate to
> wiki.winehq.org.  

Well, There are two things being offered
1. the domain name
2. the contents

I dont mind, nor have much of a preference of whether it is moved over, 
or both are used by wine. Either way, at least tips from the mailing 
lists can be stored, saved and later moved to oficial documentation.


however while the developer wiki has shown it needs protecting, the 
unofficial 'end user/beginner' wiki has kept a low profile and carefully 
allowed open posting. People regularly take advantage of this to add 
notes or make corrections anon


>Furthermore, the wine-wiki.org
>has a huge section on applications that's best suited for the AppDB.
>The info there directly competes with the AppDB and we shouldn't
>attempt to maintain two places with differing info.

sure. I had expected all of that to move to the appdb. Applications 
havent really been my focus - all we wanted was to at least save info 
for later inclusion or encourage someone to become a maintainer.


Curiously one apdb entry has basic installation notes and then uses the 
wiki for a fairly lengthy & comprehensive troubleshooting suggestions - 
and recently someone anon added a portuguese(?) translation summary.


With those who add a new entry - we have had some success with them then 
becoming an apdb maintainer and as admin I put a chill on any misguided 
attempts at competition. The appdb is where that important info belongs 
but perhaps the appdb should be the subject of a seperate discussion.


Joseph Black

Re: Documentation volunteer(s) needed

[Brian Vincent]

On 9/23/05, josephblack <[EMAIL PROTECTED]> wrote:
> www.wine-wiki.org has been compiling tips from the wine mailing lists.
> I had planned to use it to update the documentation, but keeping up
> with the lists has kept me busy.
>
> After some discussion, Jason (the owner) has confirmed he would like to
> raise an offer of wine-wiki.org and its contents to the Wine project.

First off, there's a lot of useful info in that wiki.  It obvious a
lot of time has gone into it.

However, I really don't see the point of having that wiki and I think
it has the potential to do more harm than good.  If there's one thing
Wine and the rest of the community has proven over and over, it's that
we can't maintain documentation.  I'd (almost) argue its best to have
no documentation than completely incorrect docs.

I realize that wiki came into existence before Wine's own, but now
that we have one I think some of that info needs to migrate to
wiki.winehq.org.  Maintaining two distinct wikis is overkill and
confusing for people looking for info.  Furthermore, the wine-wiki.org
has a huge section on applications that's best suited for the AppDB. 
The info there directly competes with the AppDB and we shouldn't
attempt to maintain two places with differing info.

I hope that doesn't sound like a case of Not-Invented-Here syndrome,
but we need to focus on making maintenance easy so that there's a
chance it might actually get done.  I certainly don't want to deter
anyone from working on Wine - any and all contributions are greatly
appreciated.

-Brian

Re: Documentation volunteer(s) needed

[josephblack]

In article <[EMAIL PROTECTED]>, [EMAIL PROTECTED] says...
> Folks,
>
> As most of you probably know (at least those of you who managed to get
> out of bed in time for my keynote ;-) we are supposed to release 0.9
> real soon now.  We do have one remaining issue: the documentation
> needs some major work. Not every bit of it is critical for the
> release, but we need to fix at least the User's Guide to reflect the
> recent configuration changes. Would anybody be interested in helping
> with that?
>

www.wine-wiki.org has been compiling tips from the wine mailing lists.
I had planned to use it to update the documentation, but keeping up
with the lists has kept me busy.

After some discussion, Jason (the owner) has confirmed he would like to
raise an offer of wine-wiki.org and its contents to the Wine project.

joseph black
admin

Re: Documentation volunteer(s) needed

[Oliver Stieber]

--- Stefan Dösinger <[EMAIL PROTECTED]> wrote:

> Hello,
> 
> > I'm just about to put it into wined3d, I can have a look at backporting it
> > to d3d7 but the idea is to get d3d7 using wined3d at some point.
> That would be certainly interesting. Is wined3d ready for this yet? It would 
> make much more sense to change this now instead of looking for bugs in D3D7 
> when we know it will be removed in the not-so-far future.
> 
It's almost ready for DirectX 8 but there quite a bit of work intergrating 
things with ddraw
surfaces before DirectX 7 can be moved over.

> > All you have to do is flag the backbuffer when it's cleared as cleared, and
> > then at the end of a drawing function flag the backbuffer as not cleared.
> > Then when you lock the backbuffer check the flag and if it's flagged as
> > cleared just memset the buffer to whatever the clear value is instead of
> > doing a glReadPixels (most of the time you don't need the memset because
> > the buffer is going to be completely rewritten, on my home pc without the
> > hack I get about 10fps max with 100% CPU load, with the hack I get 30fps
> > with about 30% CPU load)
> I'll look at this. Thanks
> 
http://www.winehq.org/pipermail/wine-patches/2005-September/020829.html

> > Hmm.. I haven't had any problems with that yet, so long as I'm actually
> > using GL_TEXTURE_2D  and providing texture coordinates, in wined3d I
> > disable any texture states that aren't used:
> Sounds interesting. I'll have a look.
> 
> Stefan
> 






___ 
Yahoo! Messenger - NEW crystal clear PC to PC calling worldwide with voicemail 
http://uk.messenger.yahoo.com

Re: Documentation volunteer(s) needed

[Stefan Dösinger]

Hello,

> I'm just about to put it into wined3d, I can have a look at backporting it
> to d3d7 but the idea is to get d3d7 using wined3d at some point.
That would be certainly interesting. Is wined3d ready for this yet? It would 
make much more sense to change this now instead of looking for bugs in D3D7 
when we know it will be removed in the not-so-far future.

> All you have to do is flag the backbuffer when it's cleared as cleared, and
> then at the end of a drawing function flag the backbuffer as not cleared.
> Then when you lock the backbuffer check the flag and if it's flagged as
> cleared just memset the buffer to whatever the clear value is instead of
> doing a glReadPixels (most of the time you don't need the memset because
> the buffer is going to be completely rewritten, on my home pc without the
> hack I get about 10fps max with 100% CPU load, with the hack I get 30fps
> with about 30% CPU load)
I'll look at this. Thanks

> Hmm.. I haven't had any problems with that yet, so long as I'm actually
> using GL_TEXTURE_2D  and providing texture coordinates, in wined3d I
> disable any texture states that aren't used:
Sounds interesting. I'll have a look.

Stefan

Re: Documentation volunteer(s) needed

[Dimi Paun]

On Tue, 2005-09-20 at 23:30 +0200, Holly Bostick wrote:
> But in any case, I'm having another problem somewhat more relevant--
> the docs don't compile as html for me:

It should be fixed now, just get the latest version.

-- 
Dimi Paun <[EMAIL PROTECTED]>
Lattica, Inc.

Re: Documentation volunteer(s) needed

[Oliver Stieber]

--- Stefan Dösinger <[EMAIL PROTECTED]> wrote:

> Hello,
> 
> > You need to turn on backbuffers / backingstore in your xf86config and those
> > two functions were reasonable fast (so long as you don't play mess around
> > with the transfer modes) older driver (can't renember which version)
> Does this still work with newer drivers? 8.16.20 for example? It doesn't work 
> for me.
> (I don't understand this clearly from your sentence.)
> 
It stopped working a few driver versions ago gentoo only goes back as far as 
8.14.13 and I don't
have a copy of any older drivers kicking around., I've sent a bug report to 
ATI, I hoped they'ed
fixed it as part of their performance improvements in 8.16.20 but apparently 
not.

> > I've got a hack to go into wined3d that speeds up locking the backbuffer by
> > not bothering to read it if it's just been cleared, this get's movies using
> > DirectX and backbuffer locking up to a good frame rate with low CPU usage.
> That's exactly the problem I have! I expect it to occur too when Empire Earth 
> finally runs. Can you send me your hack? I'd like to try it with D3D7.

I'm just about to put it into wined3d, I can have a look at backporting it to 
d3d7 but the idea is
to get d3d7 using wined3d at some point.

All you have to do is flag the backbuffer when it's cleared as cleared, and 
then at the end of a
drawing function flag the backbuffer as not cleared.
Then when you lock the backbuffer check the flag and if it's flagged as cleared 
just memset the
buffer to whatever the clear value is instead of doing a glReadPixels (most of 
the time you don't
need the memset because the buffer is going to be completely rewritten, on my 
home pc without the
hack I get about 10fps max with 100% CPU load, with the hack I get 30fps with 
about 30% CPU load)
> 
> Another question: I've hit a problem where fglrx crashes on glBegin(GL_*) 
> when 
> GL_TEXTURE_2D is enabled. Any experiance / hints?
> 
Hmm.. I haven't had any problems with that yet, so long as I'm actually using 
GL_TEXTURE_2D  and
providing texture coordinates, in wined3d I disable any texture states that 
aren't used:

 for (i = 0; i< GL_LIMITS(textures); ++i) {
/* Bind the texture to the stage here */
if (GL_SUPPORT(ARB_MULTITEXTURE)) {
GLACTIVETEXTURE(i);
}
glDisable(GL_TEXTURE_1D);
switch(This->stateBlock->textureDimensions[i]) {
case GL_TEXTURE_2D:
glDisable(GL_TEXTURE_3D);
glDisable(GL_TEXTURE_CUBE_MAP_ARB);
break;
case GL_TEXTURE_3D:
glDisable(GL_TEXTURE_CUBE_MAP_ARB);
glDisable(GL_TEXTURE_2D);
break;
case GLTEXTURECUBEMAP:
glDisable(GL_TEXTURE_2D);
glDisable(GL_TEXTURE_3D);
break;


> Thanks for this hint, it looks like you saved me from doing a time-intensive 
> investigation!
> 
> Stefan
> 
> 
> 





___ 
To help you stay safe and secure online, we've developed the all new Yahoo! 
Security Centre. http://uk.security.yahoo.com

Re: Documentation volunteer(s) needed

[Brian Vincent]

On 9/20/05, Kuba Ober <[EMAIL PROTECTED]> wrote:
> Wouldn't such a book be mostly obsolete within a year of publication? That's
> almost like with those linux kernel development books: in 2 years timeframe
> they are mostly paperweights, unless you're interested only in 'big ideas'
> rather than details.

Well, that's one of the things I wrestle with.  Some of the stuff is
just cool ideas that won't get outdated any time soon.  Some of it
will get outdated... and then the publisher can pay me for the second
addition.

Holly - I should also mention that you'll want to make sure you have
well-formed SGML when you write the docs, i.e. all opening tags must
have a closing tag.  I find xmllint and tidy are very helpful for
that.  tidy has easier output to understand, xmllint seems to be
pretty standard on distros these days.

-Brian

Re: Documentation volunteer(s) needed

[Lionel Ulmer]

On Tue, Sep 20, 2005 at 10:56:41PM +0200, Stefan Dösinger wrote:
> That's exactly the problem I have! I expect it to occur too when Empire Earth 
> finally runs. Can you send me your hack? I'd like to try it with D3D7.

If the game is well behaved, this optimisation should already be present in
the D3D7 code (i.e. if the surface is locked 'write only', do not bother to
read the buffer from the card).

Alas most games are not well behaved and always lock in R/W mode :-)

   Lionel

-- 
 Lionel Ulmer - http://www.bbrox.org/

Re: Documentation volunteer(s) needed

[Holly Bostick]

Oliver Stieber schreef:
> --- Stefan Dösinger <[EMAIL PROTECTED]> wrote:
> 
> 
>> Hello,
>> 
>>> Oh yeah, another question-- are we making provision for 'special 
>>> circumstances'? I've got an ATI card, which makes me sensitive to
>>> such things, since the ATI drivers fail to do many things that 
>>> they should, and often additional provisions need to be made 
>>> specifically to get an app or game to run with the stupid fglrx 
>>> drivers, where no such config workarounds need to be used with 
>>> nVidia cards, or so I've heard. Or does that just fall under 
>>> 'Troubleshooting'? Or does Wine not need such workarounds at all
>>>  (unlike Cedega)?
>> 
>> There are for sure some cases where fglrx-specific problems exist.
>>  I am hunting two problems with this driver. One thing is that 
>> glTexSubImage2D() and glReadPixels() are HORRIBLY slow, another one
>>  is a crash in the fglrx driver somehow related to textures.
>> 
>> Maybe I can solve these 2 in time, so you don't have to write about
>>  them ;-)
>> 
> 
> You need to turn on backbuffers / backingstore in your xf86config and
>  those two functions were reasonable fast (so long as you don't play
>  mess around with the transfer modes) older driver (can't renember 
> which version)
> 
> Section "Device" Identifier  "ATI Graphics 
> Adapter" Driver  "fglrx" ... #Backing
>  store increases performance when locking the backbuffer Option 
> "backingstore" "true" ... EndSection
> 
> I've got a hack to go into wined3d that speeds up locking the 
> backbuffer by not bothering to read it if it's just been cleared, 
> this get's movies using DirectX and backbuffer locking up to a good 
> frame rate with low CPU usage.
> 

Thank you, Oliver and Stefan! I've changed my config (this option did
appear but was not only commented out, but in the wrong place in the
file, as well as having no value of either true or false). And my
impression is that it being commented is the default setting, but I'm
not sure about that.

I haven't restarted X yet, but it's good to know that this setting has
some function (that's why I think it's commented by default; I certainly
never knew what it did, so I most likely never messed with it), so it
can certainly go into my collection of 'miscellaneous technical notes
that might be useful'.

I hope that it won't be necessary to go into the docs, but you never
know what users might do (if the problems that come up on the user list
are any guide), what Wine they might be using, on what
even-less-supported-than-my-9800SE card (I'm thinking the Mobility
users, and the X*00 users) they might have on their systems. So any and
every little bit of info might be useful to somebody.

Assuming of course that if you successfully hunt down the issue and tell
the ATI team, they don't fix it themselves (which would be lovely,
wouldn't it?). Would save us all a lot of work

Holly

Re: Documentation volunteer(s) needed

[Holly Bostick]

Tom Wickline schreef:
> On 9/20/05, Holly Bostick <[EMAIL PROTECTED]> wrote:
> 
>> Oh yeah, another question-- are we making provision for 'special 
>> circumstances'? I've got an ATI card, which makes me sensitive to 
>> such things, since the ATI drivers fail to do many things that they
>>  should, and often additional provisions need to be made 
>> specifically to get an app or game to run with the stupid fglrx 
>> drivers, where no such config workarounds need to be used with 
>> nVidia cards, or so I've heard. Or does that just fall under 
>> 'Troubleshooting'? Or does Wine not need such workarounds at all 
>> (unlike Cedega)?
> 
> 
> IMHO Cedega should not even remotely be in the equation, the 
> documentation is about Wine and only Wine. The folks at TG can write 
> docs for Cedega as CW writes docs for CrossOver. So please don't 
> reference Cedega in the docs.
> 
> Tom
> 
No, I had no intention of doing so, and the reference to Cedega was
peripheral to my question. It is only referenced at all because that is
how I learn to understand things, by triangulation between points.

But in any case, I'm having another problem somewhat more relevant-- the
docs don't compile as html for me:

 ./configure; make
checking whether make sets $(MAKE)... yes
checking for docbook2html... docbook2html
checking for docbook2pdf... docbook2pdf
checking for docbook2ps... docbook2ps
checking for docbook2txt... docbook2txt
checking for nsgmls... nsgmls
configure: creating ./config.status
config.status: creating Make.rules
config.status: creating Makefile
config.status: creating en/Makefile
config.status: creating fr/Makefile

Configure finished.  Do 'make' to compile the documentation.

make[1]: Entering directory `/usr/local/src/docs/en'
docbook2html -u winedev-guide.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/winedev-guide.sgml
Done.
docbook2html -u wineusr-guide.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/wineusr-guide.sgml
Done.
docbook2html -u winelib-guide.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/winelib-guide.sgml
Done.
docbook2html -u wine-faq.sgml
Using catalogs: /etc/sgml/sgml-docbook-3.1.cat
Using stylesheet:
/usr/share/sgml/docbook/utils-0.6.14/docbook-utils.dsl#html
Working on: /usr/local/src/docs/en/wine-faq.sgml
jade:/usr/local/src/docs/en/wine-faq.sgml:1611:13:E: document type does
not allow element "PARA" here; missing one of "FOOTNOTE", "MSGTEXT",
"CAUTION", "IMPORTANT", "NOTE", "TIP", "WARNING", "BLOCKQUOTE",
"INFORMALEXAMPLE" start-tag
jade:/usr/local/src/docs/en/wine-faq.sgml:1616:14:E: end tag for "PARA"
omitted, but OMITTAG NO was specified
jade:/usr/local/src/docs/en/wine-faq.sgml:1602:8: start tag was here
jade:/usr/local/src/docs/en/wine-faq.sgml:1737:21:E: non SGML character
number 132
jade:/usr/local/src/docs/en/wine-faq.sgml:1738:84:E: non SGML character
number 132
make[1]: *** [wine-faq.html] Fout 8
make[1]: Leaving directory `/usr/local/src/docs/en'
make: *** [en] Fout 2

I don't have time to look at the files right now, but from what Brian
said before, it's not strictly necessary to compile them to use/modify
them. Is that correct, or should I be disturbed by this? If I should be
disturbed, can someone point me to a quick fix?

Holly

Re: Documentation volunteer(s) needed

[Stefan Dösinger]

Hello,

> You need to turn on backbuffers / backingstore in your xf86config and those
> two functions were reasonable fast (so long as you don't play mess around
> with the transfer modes) older driver (can't renember which version)
Does this still work with newer drivers? 8.16.20 for example? It doesn't work 
for me.
(I don't understand this clearly from your sentence.)

> I've got a hack to go into wined3d that speeds up locking the backbuffer by
> not bothering to read it if it's just been cleared, this get's movies using
> DirectX and backbuffer locking up to a good frame rate with low CPU usage.
That's exactly the problem I have! I expect it to occur too when Empire Earth 
finally runs. Can you send me your hack? I'd like to try it with D3D7.

Another question: I've hit a problem where fglrx crashes on glBegin(GL_*) when 
GL_TEXTURE_2D is enabled. Any experiance / hints?

Thanks for this hint, it looks like you saved me from doing a time-intensive 
investigation!

Stefan

Re: Documentation volunteer(s) needed

[Oliver Stieber]

--- Stefan Dösinger <[EMAIL PROTECTED]> wrote:

> Hello,
> > Oh yeah, another question-- are we making provision for 'special
> > circumstances'? I've got an ATI card, which makes me sensitive to such
> > things, since the ATI drivers fail to do many things that they should,
> > and often additional provisions need to be made specifically to get an
> > app or game to run with the stupid fglrx drivers, where no such config
> > workarounds need to be used with nVidia cards, or so I've heard. Or does
> > that just fall under 'Troubleshooting'? Or does Wine not need such
> > workarounds at all (unlike Cedega)?
> There are for sure some cases where fglrx-specific problems exist. I am 
> hunting two problems with this driver. One thing is that glTexSubImage2D() 
> and glReadPixels() are HORRIBLY slow, another one is a crash in the fglrx 
> driver somehow related to textures.
> 
> Maybe I can solve these 2 in time, so you don't have to write about them ;-)
> 
You need to turn on backbuffers / backingstore in your xf86config and those two 
functions were
reasonable fast (so long as you don't play mess around with the transfer modes) 
older driver
(can't renember which version)

Section "Device"
Identifier  "ATI Graphics Adapter"
Driver  "fglrx"
...
#Backing store increases performance when locking the backbuffer
Option "backingstore" "true"
...
EndSection

I've got a hack to go into wined3d that speeds up locking the backbuffer by not 
bothering to read
it if it's just been cleared, this get's movies using DirectX and backbuffer 
locking up to a good
frame rate with low CPU usage.

Oliver
> Stefan
> 
> 
> 




___ 
To help you stay safe and secure online, we've developed the all new Yahoo! 
Security Centre. http://uk.security.yahoo.com

Re: Documentation volunteer(s) needed

[Stefan Dösinger]

Hello,
> Oh yeah, another question-- are we making provision for 'special
> circumstances'? I've got an ATI card, which makes me sensitive to such
> things, since the ATI drivers fail to do many things that they should,
> and often additional provisions need to be made specifically to get an
> app or game to run with the stupid fglrx drivers, where no such config
> workarounds need to be used with nVidia cards, or so I've heard. Or does
> that just fall under 'Troubleshooting'? Or does Wine not need such
> workarounds at all (unlike Cedega)?
There are for sure some cases where fglrx-specific problems exist. I am 
hunting two problems with this driver. One thing is that glTexSubImage2D() 
and glReadPixels() are HORRIBLY slow, another one is a crash in the fglrx 
driver somehow related to textures.

Maybe I can solve these 2 in time, so you don't have to write about them ;-)

Stefan

Re: Documentation volunteer(s) needed

[Kuba Ober]

> There's enough material on this topic to practically write a book.
> Someone should think about that.

Wouldn't such a book be mostly obsolete within a year of publication? That's 
almost like with those linux kernel development books: in 2 years timeframe 
they are mostly paperweights, unless you're interested only in 'big ideas' 
rather than details.

I might of course be wrong :)

Kuba

Re: Documentation volunteer(s) needed

[Tom Wickline]

On 9/20/05, Holly Bostick <[EMAIL PROTECTED]> wrote:
>
> Oh yeah, another question-- are we making provision for 'special
> circumstances'? I've got an ATI card, which makes me sensitive to such
> things, since the ATI drivers fail to do many things that they should,
> and often additional provisions need to be made specifically to get an
> app or game to run with the stupid fglrx drivers, where no such config
> workarounds need to be used with nVidia cards, or so I've heard. Or does
> that just fall under 'Troubleshooting'? Or does Wine not need such
> workarounds at all (unlike Cedega)?

IMHO Cedega should not even remotely be in the equation, the
documentation is about Wine and only Wine. The folks at TG can write
docs for Cedega as CW writes docs for CrossOver. So please don't
reference Cedega in the docs.

Tom

> Holly
>

Re: Documentation volunteer(s) needed

[Holly Bostick]

Brian Vincent schreef:
> Hopefully I can make this easier on someone.  Also, I'm cc'ing Scott 
> Ritchie since he mentioned at one point he was interested in this.
> 
> The docs now live in a separate CVS tree, I don't have the details
> for that.  After grabbing them from CVS, you'll want to make sure you
> have the docbook tools available for compiling.  In the docs
> directory you can just do a "make html" or some such in order to
> generate nicely viewable material to help with editing.
> 
> I started in on this about a year ago and there's a pretty good 
> outline to work from.  Some of the actual content is just plain wrong
>  now, but it's probably about 90% accurate.  There have been changes 
> the the DLL Overrides and Drive Settings part of Winecfg.  I'd also 
> consider this stuff to be a little light on the configuration side. 
> For example, to configure just application settings you need to add
> an app on the first tab of winecfg and then make the overrides on the
>  second tab.  I don't think this discusses how that per-app stuff is 
> done (it also affects Graphics.)

One other question in this regard; I'm currently running 20050830. Do I
need to compile from CVS to get a more accurate picture of the current
state of what I'm documenting, or is the current release (naturally I'll
update to the September release as soon as I see it) 'close enough'?
> 
> 
> 
> 
> Going forward, we have a lot of documentation in the User Guide about
>  downloading Wine, compiling Wine, CVS, etc; mostly stuff that's
> already duplicated in some form or another on the web site.  I'd like
> to see as much stuff like that removed from the User Guide as
> possible, we can simply refer people to WineHQ for more info.  (I
> think the reason for the duplication is that the website docs simply
> didn't exist when the User Guide was written, now the website has
> superceded the User Guide.) When it's all said and done we should be
> left with the following sections: - Introduction - Configuration -
> Running - Troubleshooting
> 

OK, that's at least an outline of what you/we aim to achieve which is
(very) good, of course. Nothing more to say until I've looked at the
current material, but I can see the benefits of aiming for simplicity
and clarity.

I hope the release is stable enough to support these goals (I have faith).

Oh yeah, another question-- are we making provision for 'special
circumstances'? I've got an ATI card, which makes me sensitive to such
things, since the ATI drivers fail to do many things that they should,
and often additional provisions need to be made specifically to get an
app or game to run with the stupid fglrx drivers, where no such config
workarounds need to be used with nVidia cards, or so I've heard. Or does
that just fall under 'Troubleshooting'? Or does Wine not need such
workarounds at all (unlike Cedega)? My Wine install seems to be acting a
bit flakey atm, and I'm not sure why, so I haven't gotten as far with my
current project of documenting what works where (Wine vs. Cedega) as I
would like, and it makes it hard to be sure whether something that works
under Cedega but not under Wine is because I can configure Cedega to
work around some ATI problems, whereas I can't with Wine, or whether
it's because my Wine install is acting flakey, or because Wine is kinda
broke atm in some ways.
> 
> 
> 
> There's enough material on this topic to practically write a book. 
> Someone should think about that.

Didn't you get a replacement co-author yet?? Amazing, if true. But
that's another discussion :) .

Thanks for the info; I'll get over to the documentation CVS later
tonight or early tomorrow.

Holly

Re: Documentation volunteer(s) needed

[Tom Wickline]

On 9/20/05, Holly Bostick <[EMAIL PROTECTED]> wrote:
>
> YES!!! Where do I sign up?

Hello Holly,

To get the docs in a terminal run :
cvs -z3 -d:pserver:[EMAIL PROTECTED]:/cvsroot/wine co -P docs
When prompted for a password press the enter key.
A subdirectory named docs will be created. and you can edit to your
hearts content. ;)

Make sure you read over :
http://www.winehq.org/site/sending_patches

I put DOCS: at the beginning of the subject when sending this way Dimi
can easily
pick it out.

Tom

> Holly
>
>
>

Re: Documentation volunteer(s) needed

[Brian Vincent]

On 9/20/05, Holly Bostick <[EMAIL PROTECTED]> wrote:
>
> YES!!! Where do I sign up?

Hopefully I can make this easier on someone.  Also, I'm cc'ing Scott
Ritchie since he mentioned at one point he was interested in this.

The docs now live in a separate CVS tree, I don't have the details for
that.  After grabbing them from CVS, you'll want to make sure you have
the docbook tools available for compiling.  In the docs directory you
can just do a "make html" or some such in order to generate nicely
viewable material to help with editing.

I started in on this about a year ago and there's a pretty good
outline to work from.  Some of the actual content is just plain wrong
now, but it's probably about 90% accurate.  There have been changes
the the DLL Overrides and Drive Settings part of Winecfg.  I'd also
consider this stuff to be a little light on the configuration side. 
For example, to configure just application settings you need to add an
app on the first tab of winecfg and then make the overrides on the
second tab.  I don't think this discusses how that per-app stuff is
done (it also affects Graphics.)

Last year I sent this to wine-devel talking about it:

---

For now, the biggest changes can be found in configuring.sgml  (which
translates into the "Configuring Wine" part of the guide.)  A diff is
available here:

 http://www.theshell.com/~vinn/wine-user-guide.diff

However, this stuff is best looked at as a side-by-side comparison with
the existing docs.  You can find that here:

 http://www.theshell.com/~vinn/wine-user-guide.html

(Not having looked at Mike's recent patches, I'm sure this will soon be out
of date.  Things like drive detection are missing.  There's also parts that
I left undone: such as the printing config, an appendix listing reg keys would
be nice once we know what they all are.  Other parts probably need a
better explanation, such as font configuration.  Anything you notice missing
is probably worth telling me about, though it won't be hard to find lots of
mistakes.)

One of the big goals of all this is to reduce the amount of documentation
and outdated stuff.  Therefore, registry.sgml, printing.sgml, and fonts.sgml
have been somewhat merged into configuring.sgml.  fonts.sgml contained a
lot of outdated info in it that probably caused more confusion than helped.

Going forward, we have a lot of documentation in the User Guide about
downloading Wine, compiling Wine, CVS, etc; mostly stuff that's already
duplicated in some form or another on the web site.  I'd like to see as
much stuff like that removed from the User Guide as possible, we can
simply refer people to WineHQ for more info.  (I think the reason for the
duplication is that the website docs simply didn't exist when the User
Guide was written, now the website has superceded the User Guide.)
When it's all said and done we should be left with the following sections:
 - Introduction
 - Configuration
 - Running
 - Troubleshooting



There's enough material on this topic to practically write a book. 
Someone should think about that.

-Brian

Re: Documentation volunteer(s) needed

[Holly Bostick]

Alexandre Julliard schreef:
> Folks,
> 
> As most of you probably know (at least those of you who managed to get
> out of bed in time for my keynote ;-) we are supposed to release 0.9
> real soon now.  We do have one remaining issue: the documentation
> needs some major work. Not every bit of it is critical for the
> release, but we need to fix at least the User's Guide to reflect the
> recent configuration changes. Would anybody be interested in helping
> with that?
> 

YES!!! Where do I sign up?

Holly

Re: [documentation] winedev-kernel

[Troy Rollo]

On Sun, 13 Mar 2005 19:21, Dmitry Timoshkov wrote:
> "Eric Pouech" <[EMAIL PROTECTED]> wrote:
> > > For asynchronous read operations, hFile can be any handle opened with
> > > the FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket
> > > handle returned by the socket or accept function.
> >
> > which means that ReadFile() only works on socket for async reads, not
> > sync reads. I'll precise this.

It's not quite correct. The following sequence of code will cause all sockets 
created subsequently with socket() to be usable with ReadFile() and 
WriteFile() without overlapped calls. I can confirm that I've done this many 
times (using sockets of this variety is a good way of porting UNIX apps which 
use select on a pipe).

 int optval = SO_SYNCHRONOUS_NONALERT;

 setsockopt( INVALID_SOCKET, SOL_SOCKET, SO_OPENTYPE,
  (char *) &optval, sizeof optval );

According to MSDN you can also use WSASocket in Windows Sockets version 2.0 or 
later to create sockets that do this by not using the WSA_FLAG_OVERLAPPED 
flag.

Re: [documentation] winedev-kernel

[Dimitrie O. Paun]

On Sun, Mar 13, 2005 at 09:17:08AM +0100, Eric Pouech wrote:
> Also, we miss in the KERNEL32 part some information on
> - 16 bit support (and DOS of course)
> - Global vs local vs heap allocation

Yes, these would be very useful. I'll keep it open then.

-- 
Dimi.

Re: [documentation] winedev-kernel

[Eric Pouech]

Dmitry Timoshkov a écrit :
"Eric Pouech" <[EMAIL PROTECTED]> wrote:

For asynchronous read operations, hFile can be any handle opened with the
FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle 
returned
by the socket or accept function.
which means that ReadFile() only works on socket for async reads, not sync 
reads. I'll precise this.

Did you actually test this? We need a knowledge, not a speculation.
I did. See attached test and it fails on XP. Note that ReadFile works on socket 
(overlapped op), while WriteFile (synchronous operation) doesn't.

Your test passes on win2k SP4 for me, but hangs on win98. Uncommented WriteFile
call failes and doesn't change a previous error value, but that might be due to
different reasons: missing OVERLAPPED pointer, incompatible socket open mode, or
something else.
yeahh, you're right.
I found what's going wrong. By default, WS2 opens the socket in overlapped mode, 
hence the error in Read/Write File (while the send/recv and other WS functions 
should handle this gracefully).
BTW, our WS implementation doesn't use the right open mode by default (which is 
overlapped)
A+

--
Eric Pouech

Re: [documentation] winedev-kernel

[Dmitry Timoshkov]

"Eric Pouech" <[EMAIL PROTECTED]> wrote:

> >>>For asynchronous read operations, hFile can be any handle opened with the
> >>>FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle 
> >>>returned
> >>>by the socket or accept function.
> >>>
> >>
> >>which means that ReadFile() only works on socket for async reads, not sync 
> >>reads. I'll precise this.
> > 
> > 
> > Did you actually test this? We need a knowledge, not a speculation.
> > 
> I did. See attached test and it fails on XP. Note that ReadFile works on 
> socket 
> (overlapped op), while WriteFile (synchronous operation) doesn't.

Your test passes on win2k SP4 for me, but hangs on win98. Uncommented WriteFile
call failes and doesn't change a previous error value, but that might be due to
different reasons: missing OVERLAPPED pointer, incompatible socket open mode, or
something else.

-- 
Dmitry.

Re: [documentation] winedev-kernel

[Eric Pouech]

Dmitry Timoshkov a écrit :
"Eric Pouech" <[EMAIL PROTECTED]> wrote:

For asynchronous read operations, hFile can be any handle opened with the
FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle 
returned
by the socket or accept function.
which means that ReadFile() only works on socket for async reads, not sync 
reads. I'll precise this.

Did you actually test this? We need a knowledge, not a speculation.
I did. See attached test and it fails on XP. Note that ReadFile works on socket 
(overlapped op), while WriteFile (synchronous operation) doesn't.
A+

--
Eric Pouech
/*
 * Unit tests for overlapped read/write operations
 *
 * Copyright (c) 2004 Eric Pouech
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA
 */

/* TODO:
 * - we should implement some tests for pipe (or at least, pipe semantics on
 *   top of a file, if this exists in windows)
 * - it could be interesting to provide a loopback type of driver for the serial
 *   lines handling
 * - tests on file don't work well (as there's no blocking mechanism on the writer
 *   thread
 */
 
#include 
#include 
#include 
#include 
#include 

static HANDLE   hPhase0, hPhase1, hPhase2;
static HANDLE   hThread;
static char test_string[] = "abcdefghijklmnopqrstuvwxyz";

static void prolog(DWORD (WINAPI* fn_thread)(void*), void* pmt)
{
hPhase0 = CreateEvent(NULL, FALSE, FALSE, NULL);
hPhase1 = CreateEvent(NULL, FALSE, FALSE, NULL);
hPhase2 = CreateEvent(NULL, FALSE, FALSE, NULL);

hThread = CreateThread(NULL, 0, fn_thread, pmt, 0, NULL);
WaitForSingleObject(hPhase0, INFINITE);
}

static void epilog(void)
{
CloseHandle(hPhase0); hPhase0 = NULL;
CloseHandle(hPhase1); hPhase1 = NULL;
CloseHandle(hPhase2); hPhase2 = NULL;
WaitForSingleObject(hThread, INFINITE);
}

static void do_read(HANDLE hFile, const char* pfx, unsigned with_event)
{
OVERLAPPED  ov;
DWORD   readbytes;
charbuf[27];

memset(&ov, 0, sizeof(ov));
ov.hEvent = (with_event) ? CreateEvent(NULL, FALSE, with_event == 2, NULL) : NULL;
readbytes = 0;

ok(!ReadFile(hFile, buf, sizeof(buf) - 1, &readbytes, &ov), "ReadFile on %s shouldn't have read something (%lu)\n", pfx, readbytes);
ok(GetLastError() == ERROR_IO_PENDING, 
   "ReadFile failed on %s; error #%ld\n", pfx, GetLastError());

ok(!with_event || WaitForSingleObject(ov.hEvent, 0) == WAIT_TIMEOUT, "Event shouldn't be set\n");
ok(!GetOverlappedResult(hFile, &ov, &readbytes, FALSE), "GetOverlappedResult on %s error: %ld\n", pfx, GetLastError());

SetEvent(hPhase1);
WaitForSingleObject(hPhase2, INFINITE);

ok(GetOverlappedResult(hFile, &ov, &readbytes, TRUE), "GetOverlappedResult on %s error: %ld\n", pfx, GetLastError());
buf[readbytes] = '\0';
ok(!strcmp(buf, test_string), "For %s, expected %s(%u), got %s(%u)\n", pfx, test_string, strlen(test_string), buf, strlen(buf));
CloseHandle(hFile);
}

static DWORD WINAPI file_thread(void* pmt)
{
HANDLE hFile = (HANDLE)pmt;
DWORD len;

SetEvent(hPhase0);
WaitForSingleObject(hPhase1, INFINITE);
ok(WriteFile(hFile, test_string, 26, &len, NULL), "Couldn't write\n");
SetEvent(hPhase2);
return 1;
}

static void test_file(BOOL with_event)
{
HANDLE  hFileR, hFileW;
charbuf[MAX_PATH];

GetTempFileNameA(".", "foo", 0, buf);
hFileW = CreateFile(buf, GENERIC_WRITE, FILE_SHARE_READ|FILE_SHARE_WRITE, 
NULL, CREATE_ALWAYS, FILE_ATTRIBUTE_NORMAL|FILE_FLAG_WRITE_THROUGH, NULL);
hFileR = CreateFile(buf, GENERIC_READ, FILE_SHARE_READ|FILE_SHARE_WRITE, 
NULL, OPEN_EXISTING, FILE_ATTRIBUTE_NORMAL|FILE_FLAG_OVERLAPPED, NULL);

ok(hFileW != INVALID_HANDLE_VALUE, "Couldn't open file for writing\n");
ok(hFileR != INVALID_HANDLE_VALUE, "Couldn't open file for reading\n");
if (hFileR == INVALID_HANDLE_VALUE || hFileW == INVALID_HANDLE_VALUE)
return;

/* hFile should be R/W on temp */
prolog(file_thread, hFileW);
do_read(hFileR, "file", with_event);
epilog();
CloseHandle(hFileR);
CloseHandle(hFileW);
}

struct socket_struct
{
struct sockaddr_in   s_addrs;
unsigned s_len;
};

static DWORD WINAPI socke

Re: [documentation] winedev-kernel

[Dmitry Timoshkov]

"Eric Pouech" <[EMAIL PROTECTED]> wrote:

> > For asynchronous read operations, hFile can be any handle opened with the
> > FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle 
> > returned
> > by the socket or accept function.
> > 
> which means that ReadFile() only works on socket for async reads, not sync 
> reads. I'll precise this.

Did you actually test this? We need a knowledge, not a speculation.

-- 
Dmitry.

Re: [documentation] winedev-kernel

[Eric Pouech]

Dimitrie O. Paun a écrit :
Does this complete task Documentation/Devel Guide/6 on the TODO list?
not yet IMO. I'd like to re-balance the content of the archi chapter and the one 
of the kernel modules chapter (ie move the details of process, DLL and memory 
handling from the former to the later).

Also, we miss in the KERNEL32 part some information on
- 16 bit support (and DOS of course)
- Global vs local vs heap allocation
A+
--
Eric Pouech

Re: [documentation] winedev-kernel

[Eric Pouech]

Dmitry Timoshkov a écrit :
"Eric Pouech" <[EMAIL PROTECTED]> wrote:

+  File management
+  
+ With time, Windows API comes closer to the old Unix paradigm "Everything
+ is a file".  Even if it grew better over the years, it's still not 100%
+ there (for example, you cannot use ReadFile() over
+ a socket handle).

Is it really true?
From MSDN:
BOOL ReadFile(
  HANDLE hFile,
  LPVOID lpBuffer,
  DWORD nNumberOfBytesToRead,
  LPDWORD lpNumberOfBytesRead,
  LPOVERLAPPED lpOverlapped
);
Parameters
hFile 
[in] Handle to the file to be read. The file handle must have been created with the
GENERIC_READ access right. For more information, see File Security and Access Rights. 
For asynchronous read operations, hFile can be any handle opened with the
FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle returned
by the socket or accept function.

which means that ReadFile() only works on socket for async reads, not sync 
reads. I'll precise this.
A+

--
Eric Pouech

Re: [documentation] winedev-kernel

[Dmitry Timoshkov]

"Eric Pouech" <[EMAIL PROTECTED]> wrote:

> +  File management
> +  
> + With time, Windows API comes closer to the old Unix paradigm "Everything
> + is a file".  Even if it grew better over the years, it's still not 100%
> + there (for example, you cannot use ReadFile() over
> + a socket handle).

Is it really true?

>From MSDN:

BOOL ReadFile(
  HANDLE hFile,
  LPVOID lpBuffer,
  DWORD nNumberOfBytesToRead,
  LPDWORD lpNumberOfBytesRead,
  LPOVERLAPPED lpOverlapped
);

Parameters
hFile 
[in] Handle to the file to be read. The file handle must have been created with 
the
GENERIC_READ access right. For more information, see File Security and Access 
Rights. 
For asynchronous read operations, hFile can be any handle opened with the
FILE_FLAG_OVERLAPPED flag by the CreateFile function, or a socket handle 
returned
by the socket or accept function.

-- 
Dmitry.

Re: [documentation] winedev-kernel

[Dimitrie O. Paun]

On Sat, Mar 12, 2005 at 09:29:44PM +0100, Eric Pouech wrote:
> some DocBook cosmetic stuff, and new docu (file management being the most 
> important one)

Very nice!
Does this complete task Documentation/Devel Guide/6 on the TODO list?

-- 
Dimi.

Re: documentation for SERVER_START_REQ

[Mike McCormack]

Mike Hearn wrote:
 One thing I don't understand is why
we put the request in two do...while(0) loops.  Won't they just run
once anyway?

It's a portability thing, basically just declaring a new scope, you can
ignore it - do {} while (0) runs the body of the block once.
It's to make sure that code written with SERVER_START_REQ ends with 
SERVER_END_REQ, and that the block ends with a semi-colon.

Mike

Re: documentation for SERVER_START_REQ

[Mike Hearn]

On Mon, 07 Mar 2005 15:21:45 -0600, James Hawkins wrote:
> I've looked deeper into this and found include/wine/server.h and the
> SERVER_START_REQ define.  So this define is a method of communication
> between the client(?) and server?  

Yep, pretty much. It sets up some state for the wine_server_call later.

>   One thing I don't understand is why
> we put the request in two do...while(0) loops.  Won't they just run
> once anyway?

It's a portability thing, basically just declaring a new scope, you can
ignore it - do {} while (0) runs the body of the block once.

thanks -mike

Re: documentation for SERVER_START_REQ

[James Hawkins]

On Mon, 7 Mar 2005 11:51:53 -0600, James Hawkins <[EMAIL PROTECTED]> wrote:
> Hi,
> 
> I'm implementing NtLoadKey, but I can't find any documentation on
> making server requests, ie SERVER_START_REQ, the different tracing
> abilitites such as using fprintf(stderr,...) instead of the known
> TRACE, style of code etc.  The latter two are not as important to me
> because I've picked them up while perusing the code, but it might be
> important to someone who hasn't looked through it before.  I do need
> the semantics for SERVER_START_REQ, so if you could point me in the
> right direction or tell me I would really appreciate it.

I've looked deeper into this and found include/wine/server.h and the
SERVER_START_REQ define.  So this define is a method of communication
between the client(?) and server?  One thing I don't understand is why
we put the request in two do...while(0) loops.  Won't they just run
once anyway?

Concerning Reg/NtLoadKey, load_key (in the server) looks implemented
to me.  NtLoadKey is not is not implemented.  RegLoadKeyW/A is
implemented, but it opens the file containing the hive to load to the
registry and then calls load_registry which loads a part of the
registry from a file.  While this probably does work, I think the
correct thing to do is:

* Implement NtLoadKey, having it call load_key in the server
* Rewrite RegLoadKey to call NtLoadKey

What do you think?

-- 
James Hawkins

Re: Documentation: Clarified need for conformance tests.

[Francois Gouget]

On Wed, 7 Apr 2004, Michael Jacobsen wrote:

> Hi there. This is my first go at submitting a patch. Let's see if it works.

It needs a small s/avalible/available/ and it would be nice to follow
the 2-space indentation used in the rest of the doc. Besides that it
looks good.

Thanks for your contribution.

-- 
Francois Gouget [EMAIL PROTECTED]http://fgouget.free.fr/
  Any sufficiently advanced Operating System is indistinguishable from Linux

Re: Documentation for GDI Region Functions

[Alexandre Julliard]

Robert Shearman <[EMAIL PROTECTED]> writes:

> and renamed the variables to Microsoft conventions.

Please don't do that. The variable names don't matter at all for
compatibility, so we don't have to follow the brain-damaged Microsoft
conventions for them.

-- 
Alexandre Julliard
[EMAIL PROTECTED]

Re: Documentation does not get installed with cvs sources?!

[Christian Britz]

Ivan Leo Murray-Smith schrieb:
AFAIK
./configure
make depend
make
has never built the docs, at least since I use wine.
Ivan.
I have always used the installer script

Re: Documentation does not get installed with cvs sources?!

[Ivan Leo Murray-Smith]

AFAIK
./configure
make depend
make
has never built the docs, at least since I use wine.

Ivan.

Re: [documentation] running.sgml

[Dimitrie O. Paun]

On Wed, 18 Feb 2004, Brian Vincent wrote:

> + files you might want to consider using Winefile.  This Winelib
> + application comes with Wine and can be found in /usr/local/bin.

I'm not sure it's wise to hardcode /usr/local/bin into the documentation,
it may not be installed there...

-- 
Dimi.

Re: documentation/samples/generic.ppd

[Dimitrie O. Paun]

On November 24, 2003 02:49 am, Marcus Meissner wrote:
> This is the generic fallback PPD file which can be used LPR style printing,
> where we do not get access to a PPD easily.

OK, but then it doesn't belong in documentation.
dlls/wineps perhaps?

-- 
Dimi.

Re: documentation/samples/generic.ppd

[Marcus Meissner]

On Mon, Nov 24, 2003 at 02:32:49AM -0500, Dimitrie O. Paun wrote:
> 
> I can't help but feel that this file does not belong in the
> Wine tree, but in the print system packages (cups, etc.).
> 
> cvs rm -f documentation/samples/generic.ppd
> 
> ChangeLog
> Remove generic.ppd, it does not belong in the Wine tree.

This is the generic fallback PPD file which can be used LPR style printing,
where we do not get access to a PPD easily.

Ciao, Marcus


pgp0.pgp
Description: PGP signature

Re: documentation/status

[Dimitrie O. Paun]

On September 27, 2003 01:42 am, Eric Pouech wrote:
> as Dimi is cleaning documentation/status out, documentation/status/dde
> is completly out of date, and can be simply removed.

I've been reviewing that, and the only things that _might_ be
of interest are these TODOs:

  TO DO
   

  Complete initialisation, some of the 2nd call validation conditions have not been 
worked out
  yet and the code for enabling the message loop needs writing.
   

  Complete initialize and unitialize, also add the callback handling to DdeNameService.
   

  Add true Unicode handling to CreateStringHandle, QueryString, CmpStringHandles. Also 
find
  out why Initialize needs ASCII and Unicode variants.
   

  Add DdeGetLAstError and related handling in all other modules. Also find out what to 
do about
  storing errors that result in the instance failing to initialise in some way.



I wanted to double check with the code that they are indeed out
of date, but if you know this is the case, then it can be deleted.


-- 
Dimi.

Re: documentation cleanup

[Dimitrie O. Paun]

On September 18, 2003 08:01 pm, Steven Edwards wrote:
> What do you guys think about a move to a common system
> for after wine 1.0?

I'd say let's get to 0.9 and worry about it then... :)
We are trying to use as many standard tools as possible,
headers, etc. so we are moving in the right direction.

-- 
Dimi.

Re: documentation cleanup

[Steven Edwards]

This is semi-offtopic but it would be nice if we could get WINE, ReactOS 
and Mingw to use the same docbook format and tools. There are parts of the 
WINE docs such as the regression test stuff that would be off use to us and 
other stuff in mingw. What do you guys think about a move to a common system 
for after wine 1.0?

Thanks
Steven

--- Alexandre Julliard <[EMAIL PROTECTED]> wrote:
> I'm happy with 1. It works, and the doc looks good enough. I haven't
> ever heard anybody complain about not being able to change the colors
> of the html, I don't think that's an issue at all. As for the ugliness
> of default.dsl, IMO the whole docbook stuff is one big ugly mess, so
> that's lost in the noise 


__
Do you Yahoo!?
Yahoo! SiteBuilder - Free, easy-to-use web site design software
http://sitebuilder.yahoo.com

Re: documentation cleanup

[Alexandre Julliard]

Francois Gouget <[EMAIL PROTECTED]> writes:

> Maybe you just compared the PostScript files? Our Makefile does not use
> print.dsl for generating the PostScript files which I think is a bug!

No I checked the pdf, all I could see was some spacing differences. I
don't think it's a big problem.

> So we have three options before us:
>  1. keep the current situation
> -> ugly hacks in default.dsl
>
>  2. remove the 'hard-code color hacks' from default.dsl
> -> we lose the color customization
>
>  3. remove the 'hard-code color hacks' from default.dsl and reference a
> winedoc.css file
> -> preserves the current look
> -> the doc look becomes more flexible and maintainable
>
> I'd be happy with either 2 or 3.

I'm happy with 1. It works, and the doc looks good enough. I haven't
ever heard anybody complain about not being able to change the colors
of the html, I don't think that's an issue at all. As for the ugliness
of default.dsl, IMO the whole docbook stuff is one big ugly mess, so
that's lost in the noise 

-- 
Alexandre Julliard
[EMAIL PROTECTED]

Re: documentation cleanup

[Francois Gouget]

On Mon, 15 Sep 2003, Alexandre Julliard wrote:
[...]
> print.dsl doesn't seem to have much effect on my machine so I guess we
> could remove it.

Maybe you just compared the PostScript files? Our Makefile does not use
print.dsl for generating the PostScript files which I think is a bug!

print.dsl has the following effect:
 1. show only two section in the table of content
 2. don't print the section numbers for level 3 items
 3. removes the list of tables
 4. removes the section numbers (so section titles are "Overview/About"
not "1.1. Overview/About")
 5. less spacing after titles and between paragraphs
 6. change title (or paragraph) indentation

When actually used, the effect is the same on PostScript files and on
the PDF ones.

Part of the effect of print.dsl is to make the documentation use fewer
pages (67 pages for wine-user instead of 85). There are only two
settings I would object to: 2 and 4. Removing the section number makes
it harder to find the relevant section in the documentation.


[...]
> I applied the cleanup one I think.

Sorry, I see that now. I had missed the CVS commit.


> I frankly don't see any reason for the CSS one.

Currently we generate HTL code that looks like this:


and


In other words we hard-code the link, table and body colors. This
overrides any settings that the user may have and can be changed only by
regenerating the files from the SGML source.

IMO this is wrong because:
 * it overrides the user settings

 * it's not flexible, users cannot change the presentation

 * we already have all we need in the generated HTML code to let CSS set
the look

 * it's not extensible and maintainable. We already specify some colors
so why not specify that FAQ questions should be in bold and have a
separator just before them. IMHO this would makes the FAQ much more
readable. But I have no idea how to do that from the dsl file, the DSL
documentation is complex and unclear, and nobody in the Wine community
seems to know how to tweak the DSL file. In comparison, it's pretty
easy to understand how CSS files work, and for the above example all
we need is the following line:
  .question { border-top: dashed thin; font-weight: bolder; }

 * the DSL file is not meant to be used to hard-code colors and stuff
like that in the generated HTML


So we have three options before us:
 1. keep the current situation
-> ugly hacks in default.dsl

 2. remove the 'hard-code color hacks' from default.dsl
-> we lose the color customization

 3. remove the 'hard-code color hacks' from default.dsl and reference a
winedoc.css file
-> preserves the current look
-> the doc look becomes more flexible and maintainable

I'd be happy with either 2 or 3.

-- 
Francois Gouget [EMAIL PROTECTED]http://fgouget.free.fr/
 f u kn rd ts, ur wy 2 gky 4 ur wn gd.

Re: documentation cleanup

[Alexandre Julliard]

Francois Gouget <[EMAIL PROTECTED]> writes:

> I guess this means you like the current format better than the default
> db2html/db2ps output. In that case it's probably best to just keep
> default.dsl and print.dsl in the Wine CVS.

print.dsl doesn't seem to have much effect on my machine so I guess we
could remove it. default.dsl is needed at least to have reasonable
file names.

> We can still delete winehq.dsl and make_winehq from the Wine CVS though.
> I notice that you did not apply my patches to use CSS or cleanup
> default.dsl. Any particular reason?

I applied the cleanup one I think. I frankly don't see any reason for
the CSS one.

-- 
Alexandre Julliard
[EMAIL PROTECTED]

Re: documentation cleanup

[Francois Gouget]

On Mon, 15 Sep 2003, Alexandre Julliard wrote:

> "Dimitrie O. Paun" <[EMAIL PROTECTED]> writes:
>
> > Once this patch is applied, we can:
> >   -- move default.dsl and print.dsl into the tools/ module
> >  where they belong (and where make_winehq needs them)
> >   -- remove make_winehq from our documentation dir,
> >  as it's been made obsolete by tools/make_winehq
> >
> > This should result in no change as how we build the documentation.
>
> Well, it will change the documentation I generate when making a
> release. It may not be a big deal, but I'm not sure it's worth the
> trouble. Or you will need to tell me how I should configure my system
> to still use the correct dsl files by default...

I guess this means you like the current format better than the default
db2html/db2ps output. In that case it's probably best to just keep
default.dsl and print.dsl in the Wine CVS.

We can still delete winehq.dsl and make_winehq from the Wine CVS though.
I notice that you did not apply my patches to use CSS or cleanup
default.dsl. Any particular reason?


-- 
Francois Gouget [EMAIL PROTECTED]http://fgouget.free.fr/
 We are Pentium of Borg. You will be approximated. Division is futile.

Re: documentation cleanup

[Dimitrie O. Paun]

On Mon, 15 Sep 2003, Alexandre Julliard wrote:

> Well, it will change the documentation I generate when making a
> release. It may not be a big deal, but I'm not sure it's worth the
> trouble. Or you will need to tell me how I should configure my system
> to still use the correct dsl files by default...

Right, it's a bit more convoluted than I thought. Ohhh, I hate these
SGML tools! I'll look into it, they have so many catalongs and
indirections going on, that there's got to be a way to do it :)

-- 
Dimi.

Re: documentation cleanup

[Alexandre Julliard]

"Dimitrie O. Paun" <[EMAIL PROTECTED]> writes:

> Once this patch is applied, we can:
>   -- move default.dsl and print.dsl into the tools/ module
>  where they belong (and where make_winehq needs them)
>   -- remove make_winehq from our documentation dir,
>  as it's been made obsolete by tools/make_winehq
>
> This should result in no change as how we build the documentation.

Well, it will change the documentation I generate when making a
release. It may not be a big deal, but I'm not sure it's worth the
trouble. Or you will need to tell me how I should configure my system
to still use the correct dsl files by default...

-- 
Alexandre Julliard
[EMAIL PROTECTED]