[1/3] [docs] winedev: Do not indent verbatim environments
Frédéric Delanoy
frederic.delanoy at gmail.com
Tue Sep 10 01:37:51 CDT 2013
Verbatim block-mode environments, like <screen> or <programlisting> shouldn't be indented:
- this extra space yields an extraneous blank line after each such indented block when converted
- custom indentation/spacing for blocks should use stylesheets like DSSSL or XSL
---
en/winedev-architecture.sgml | 12 +--
en/winedev-coding.sgml | 20 ++---
en/winedev-ddraw.sgml | 64 ++++++-------
en/winedev-debugger.sgml | 204 +++++++++++++++++++-----------------------
en/winedev-debugging.sgml | 136 ++++++++++++++--------------
en/winedev-documentation.sgml | 93 +++++++++++--------
en/winedev-kernel.sgml | 10 +--
en/winedev-multimedia.sgml | 102 +++++++++++----------
en/winedev-ole.sgml | 24 +++--
en/winedev-opengl.sgml | 12 +--
en/winedev-otherdebug.sgml | 130 ++++++++++++++-------------
en/winedev-testing.sgml | 28 +++---
en/winedev-windowing.sgml | 156 ++++++++++++++++----------------
13 files changed, 511 insertions(+), 480 deletions(-)
diff --git a/en/winedev-architecture.sgml b/en/winedev-architecture.sgml
index 38f00a7..0bf152f 100644
--- a/en/winedev-architecture.sgml
+++ b/en/winedev-architecture.sgml
@@ -233,7 +233,7 @@
<para>
The windows architecture (Win 9x way) looks like this:
- <screen>
+<screen>
+---------------------+ \
| Windows EXE | } application
+---------------------+ /
@@ -259,7 +259,7 @@
| Windows low-level | \ drivers (kernel space)
| drivers | /
+---------------------+ /
- </screen>
+</screen>
</para>
</sect2>
<sect2>
@@ -273,7 +273,7 @@
<filename class="libraryfile">kernel32</filename> in NT architecture
implements the Win32 subsystem on top of
<filename class="libraryfile">NTDLL</filename>.
- <screen>
+<screen>
+---------------------+ \
| Windows EXE | } application
+---------------------+ /
@@ -302,7 +302,7 @@
+---------------------------------------+ \
| Windows low-level drivers | } drivers (kernel space)
+---------------------------------------+ /
- </screen>
+</screen>
</para>
<para>
Note also (not depicted in schema above) that the 16-bit
@@ -345,7 +345,7 @@
architecture, even if several subsystems are not implemented
yet (remind also that 16-bit support is implemented in a 32-bit
Windows EXE, not as a subsystem). Here's the overall picture:
- <screen>
+<screen>
+---------------------+ \
| Windows EXE | } application
+---------------------+ /
@@ -385,7 +385,7 @@
+---------------------------------------------------+ \
| Unix device drivers | } Unix drivers (kernel space)
+---------------------------------------------------+ /
- </screen>
+</screen>
</para>
<para>
diff --git a/en/winedev-coding.sgml b/en/winedev-coding.sgml
index edc1d87..f2d0d41 100644
--- a/en/winedev-coding.sgml
+++ b/en/winedev-coding.sgml
@@ -102,14 +102,14 @@
Commenting out a block of code is usually done by
using <code language="c">if (0)</code>. For example:
</para>
- <programlisting language="c">
+<programlisting language="c">
/* note about reason for commenting block */
if (0) {
code
code /* comments */
code
}
- </programlisting>
+</programlisting>
<para>
The reason for using this method is that it does not
require that you edit comments that may be inside the
@@ -312,9 +312,9 @@ code
add a segment like this in the section that checks for
header files (search for <quote>header files</quote>):
</para>
- <programlisting>
+<programlisting>
AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
- </programlisting>
+</programlisting>
<para>
If your operating system supports a header file with the
same contents but a different name, say
@@ -323,19 +323,19 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<para>
Now you can change
</para>
- <programlisting language="c">
+<programlisting language="c">
#include <foo.h>
- </programlisting>
+</programlisting>
<para>
to
</para>
- <programlisting language="c">
+<programlisting language="c">
#ifdef HAVE_FOO_H
#include <foo.h>
#elif defined (HAVE_BAR_H)
#include <bar.h>
#endif
- </programlisting>
+</programlisting>
<para>
If your system doesn't have a corresponding header file even
though it has the library functions being used, you might
@@ -413,7 +413,7 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<filename>loader/signal.c</filename>. Here we have a
multi-branch case on features:
</para>
- <programlisting language="c">
+<programlisting language="c">
#ifdef HAVE_THIS
...
#elif defined (HAVE_THAT)
@@ -421,7 +421,7 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
#elif defined (HAVE_SOMETHING_ELSE)
...
#endif
- </programlisting>
+</programlisting>
<para>
Note that this is very different from testing on
operating systems. If a new version of your operating
diff --git a/en/winedev-ddraw.sgml b/en/winedev-ddraw.sgml
index f2c5243..72dc038 100644
--- a/en/winedev-ddraw.sgml
+++ b/en/winedev-ddraw.sgml
@@ -8,13 +8,13 @@
<sect1 id="ddinheritance">
<title>DirectDraw inheritance tree</title>
- <programlisting>
- Main
- |
- User
- |-----------\
- XVidMode DGA2
- </programlisting>
+<programlisting>
+Main
+ |
+User
+ |-----------\
+XVidMode DGA2
+</programlisting>
<para>
Most of the DirectDraw functionality is implemented in a common base
class. Derived classes are responsible for providing display
@@ -42,16 +42,16 @@
</sect1>
<sect1 id="ddsurfaceinheritance">
<title>DirectDrawSurface inheritance tree</title>
- <programlisting>
- Main
- |--------------\
- | |
- DIB Fake Z-Buffer
- |
- |------\---------\
- | | |
- User DGA2 DIBTexture
- </programlisting>
+<programlisting>
+Main
+ |--------------\
+ | |
+DIB Fake Z-Buffer
+ |
+ |------\---------\
+ | | |
+User DGA2 DIBTexture
+</programlisting>
<para>
<classname>Main</classname> provides a very simple base class that does not implement
any of the image-related functions. Therefore it does not place any
@@ -117,18 +117,18 @@
For example, the <classname>DIBTexture</classname> <type>DirectDrawSurface</type>
implementation looks like this:
</para>
- <programlisting language="c">
- struct DIBTexture_DirectDrawSurfaceImpl_Part
- {
- union DIBTexture_data data; /*declared in the real header*/
- };
+<programlisting language="c">
+struct DIBTexture_DirectDrawSurfaceImpl_Part
+{
+ union DIBTexture_data data; /*declared in the real header*/
+};
- typedef struct
- {
- struct DIB_DirectDrawSurfaceImpl_Part dib;
- struct DIBTexture_DirectDrawSurfaceImpl_Part dibtexture;
- } DIBTexture_DirectDrawSurfaceImpl;
- </programlisting>
+typedef struct
+{
+ struct DIB_DirectDrawSurfaceImpl_Part dib;
+ struct DIBTexture_DirectDrawSurfaceImpl_Part dibtexture;
+} DIBTexture_DirectDrawSurfaceImpl;
+</programlisting>
<para>
So the <classname>DIBTexture</classname> surface class is derived from the
<classname>DIB</classname> surface class and it adds one piece of data, a union.
@@ -141,10 +141,10 @@
<para>
To access private data, one says
</para>
- <programlisting>
- DIBTexture_DirectDrawSurfaceImpl* priv = This->private;
- do_something_with(priv->dibtexture.data);
- </programlisting>
+<programlisting>
+DIBTexture_DirectDrawSurfaceImpl* priv = This->private;
+do_something_with(priv->dibtexture.data);
+</programlisting>
</sect1>
<sect1 id="creatingobject">
diff --git a/en/winedev-debugger.sgml b/en/winedev-debugger.sgml
index cb71de5..8398ab4 100644
--- a/en/winedev-debugger.sgml
+++ b/en/winedev-debugger.sgml
@@ -136,10 +136,10 @@
<command>winedbg</command>. Command line options and tricks
are the same as for wine:
</para>
- <screen>
+<screen>
winedbg telnet.exe
winedbg hl.exe -windowed
- </screen>
+</screen>
</sect2>
<sect2>
@@ -280,7 +280,7 @@ winedbg hl.exe -windowed
<para>
These usually show up like this:
</para>
- <screen>
+<screen>
Unhandled exception: page fault on write access to 0x00000000 in 32-bit code (0x0043369e).
Register dump:
CS:0023 SS:002b DS:002b ES:002b FS:0063 GS:006b
@@ -483,7 +483,7 @@ process tid prio (all id:s are in hex)
0000001d 0
00000023 explorer.exe
00000024 0
- </screen>
+</screen>
<para>
Steps to debug a crash. You may stop at any step, but please
report the bug and provide as much of the information
@@ -514,7 +514,7 @@ process tid prio (all id:s are in hex)
located in the last calls. Those lines usually look like
this:
</para>
- <screen>
+<screen>
000d:Call advapi32.RegOpenKeyExW(00000090,7eb94da0 L"Patterns",00000000,00020019,0033f968) ret=7eb39af8
^^^^ ^^^^^^^^ ^^^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^ ^^^^^^^^^^^^^^^^^^^^^^^^^^ ^^^^^^^^^^^^
| | | | | | |Return address.
@@ -528,7 +528,7 @@ process tid prio (all id:s are in hex)
000d:Ret advapi32.RegOpenKeyExW() retval=00000000 ret=7eb39af8
^^^^^^^^^^^^^^^
|Return value is 32-bit and has the value 0.
- </screen>
+</screen>
</listitem>
<listitem>
<para>
@@ -692,12 +692,12 @@ process tid prio (all id:s are in hex)
is usually written in C). Win16 function entries usually
look like that:
</para>
- <programlisting language="asm">
+<programlisting language="asm">
push bp
mov bp, sp
... function code ..
retf XXXX <--------- XXXX is number of bytes of arguments
- </programlisting>
+</programlisting>
<para>
This is a <literal>FAR</literal> function with no local
storage. The arguments usually start at
@@ -713,12 +713,12 @@ retf XXXX <--------- XXXX is number of bytes of arguments
<para>
Most functions make also use of local storage in the stackframe:
</para>
- <programlisting language="asm">
+<programlisting language="asm">
enter 0086, 00
... function code ...
leave
retf XXXX
- </programlisting>
+</programlisting>
<para>
This does mostly the same as above, but also adds
<literal>0x86</literal> bytes of stackstorage, which is
@@ -726,11 +726,11 @@ retf XXXX
function, arguments are pushed on the stack using something
like this:
</para>
- <programlisting language="asm">
+<programlisting language="asm">
push word ptr [bp-02] <lineannotation><- will be at [bp+8]</lineannotation>
push di <lineannotation><- will be at [bp+6]</lineannotation>
call KERNEL.LSTRLEN
- </programlisting>
+</programlisting>
<para>
Here first the selector and then the offset to the passed
string are pushed.
@@ -744,14 +744,14 @@ call KERNEL.LSTRLEN
Let's debug the infamous Word <command>SHARE.EXE</command>
message box:
</para>
- <screen>
+<screen>
|marcus at jet $ wine winword.exe
| +---------------------------------------------+
| | ! You must leave Windows and load SHARE.EXE|
| | before starting Word. |
| +---------------------------------------------+
- </screen>
- <screen>
+</screen>
+<screen>
|marcus at jet $ WINEDEBUG=+relay,-debug wine winword.exe
|CallTo32(wndproc=0x40065bc0,hwnd=000001ac,msg=00000081,wp=00000000,lp=00000000)
|Win16 task 'winword': Breakpoint 1 at 0x01d7:0x001a
@@ -796,11 +796,10 @@ call KERNEL.LSTRLEN
|Warning: GetTempFileName returns 'C:~doc9281.tmp', which doesn't seem to be writable.
|Please check your configuration file if this generates a failure.
- </screen>
+</screen>
<para>
Whoops, it even detects that something is wrong!
- </para>
- <screen>
+<screen>
|Ret KERNEL.97: GETTEMPFILENAME() retval=0x9281 ret=060f:09b1 ds=0927
^^^^^^ Temporary storage ID
@@ -809,26 +808,27 @@ call KERNEL.LSTRLEN
|filename |OFSTRUCT |open mode:
OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
- </screen>
+</screen>
+ </para>
<para>
This fails, since my <filename class="devicefile">C:</filename> drive is in this case
mounted readonly.
- </para>
- <screen>
+<screen>
|Ret KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
^^^^^^ HFILE_ERROR16, yes, it failed.
|Call USER.1: MESSAGEBOX(0x0000,0x09278376"You must close Windows and load SHARE.EXE before you start Word.",0x00000000,0x1030) ret=060f:084f ds=0927
- </screen>
+</screen>
+ </para>
<para>
And MessageBox'ed.
- </para>
- <screen>
+<screen>
|Stopped on breakpoint 2 at 0x40189100 (MessageBoxA [msgbox.c:190])
|190 { <- the sourceline
In 32 bit mode.
Wine-dbg>
- </screen>
+</screen>
+ </para>
<para>
The code seems to find a writable harddisk and tries to create
a file there. To work around this bug, you can define
@@ -850,14 +850,14 @@ Wine-dbg>
If you have a program crashing at such an early loader phase that you can't
use the Wine debugger normally, but Wine already executes the program's
start code, then you may use a special trick. You should do a
- <programlisting>
+<programlisting>
WINEDEBUG=+relay wine <replaceable>program</replaceable>
- </programlisting>
+</programlisting>
to get a listing of the functions the program calls in its start function.
Now you do a
- <programlisting>
+<programlisting>
winedbg winfile.exe
- </programlisting>
+</programlisting>
</para>
<para>
This way, you get into <command>winedbg</command>. Now you
@@ -875,17 +875,17 @@ winedbg winfile.exe
the problem can usually be identified in the return value of one of the
functions executed before <function>MessageBox()</function>.
That's why you should re-run the program with e.g.
- <programlisting>
+<programlisting>
WINEDEBUG=+relay wine <replaceable>program_name</replaceable> &>relmsg
- </programlisting>
+</programlisting>
Then do a <command>more relmsg</command> and search for the
last occurrence of a call to the string "MESSAGEBOX". This is a line like
- <programlisting>
+<programlisting>
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
- </programlisting>
+</programlisting>
In my example the lines before the call to
<function>MessageBox()</function> look like that:
- <programlisting>
+<programlisting>
Call KERNEL.96: FREELIBRARY(0x0347) ret=01cf:1033 ds=01ff
CallTo16(func=033f:0072,ds=01ff,0x0000)
Ret KERNEL.96: FREELIBRARY() retval=0x0001 ret=01cf:1033 ds=01ff
@@ -905,7 +905,7 @@ Ret KERNEL.96: FREELIBRARY() retval=0x0000 ret=01df:3e29 ds=01ff
Call KERNEL.52: FREEPROCINSTANCE(0x02cf00ba) ret=01f7:1460 ds=01ff
Ret KERNEL.52: FREEPROCINSTANCE() retval=0x0001 ret=01f7:1460 ds=01ff
Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00000000,0x1010) ret=01f7:2160 ds=01ff
- </programlisting>
+</programlisting>
</para>
<para>
I think that the call to <function>MessageBox()</function>
@@ -922,10 +922,10 @@ Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00
quite interesting: offset <literal>1056</literal> is
<emphasis>very</emphasis> close to the return address of
<function>FREELIBRARY()</function>:
- <programlisting>
+<programlisting>
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
^^^^
- </programlisting>
+</programlisting>
Provided that segment <literal>0x0004</literal> is indeed segment
<literal>0x1cf</literal>, we now we can use IDA to disassemble
the part that caused the error. We just have to find the
@@ -960,37 +960,37 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
<para>
After starting your program with
- </para>
- <screen>
+<screen>
winedbg myprog.exe
- </screen>
+</screen>
+ </para>
<para>
the program loads and you get a prompt at the program
starting point. Then you can set breakpoints:
+<screen>
+b RoutineName (by routine name) OR
+b *0x812575 (by address)
+</screen>
</para>
- <screen>
- b RoutineName (by routine name) OR
- b *0x812575 (by address)
- </screen>
<para>
Then you hit <command>c</command> (continue) to run the
program. It stops at the breakpoint. You can type
+<screen>
+step (to step one line) OR
+stepi (to step one machine instruction at a time;
+ here, it helps to know the basic 386
+ instruction set)
+info reg (to see registers)
+info stack (to see hex values in the stack)
+info local (to see local variables)
+list <replaceable>line number</replaceable> (to list source code)
+x <replaceable>variable name</replaceable> (to examine a variable; only works if code
+ is not compiled with optimization)
+x <replaceable>0x4269978</replaceable> (to examine a memory location)
+? (help)
+q (quit)
+</screen>
</para>
- <screen>
- step (to step one line) OR
- stepi (to step one machine instruction at a time;
- here, it helps to know the basic 386
- instruction set)
- info reg (to see registers)
- info stack (to see hex values in the stack)
- info local (to see local variables)
- list <replaceable>line number</replaceable> (to list source code)
- x <replaceable>variable name</replaceable> (to examine a variable; only works if code
- is not compiled with optimization)
- x <replaceable>0x4269978</replaceable> (to examine a memory location)
- ? (help)
- q (quit)
- </screen>
<para>
By hitting <keycap>Enter</keycap>, you repeat the last
command.
@@ -1171,9 +1171,9 @@ winedbg myprog.exe
linkend="dbg-on-exception"></link> for some details). Two
values in key
</para>
- <programlisting>
+<programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
- </programlisting>
+</programlisting>
<para>
determine the behavior:
</para>
@@ -1212,11 +1212,11 @@ winedbg myprog.exe
<para>
A regular Wine registry looks like:
</para>
- <programlisting>
+<programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug] 957636538
"Auto"=dword:00000001
"Debugger"="winedbg %ld %ld"
- </programlisting>
+</programlisting>
<note>
<title>Note 1</title>
@@ -1234,9 +1234,9 @@ winedbg myprog.exe
if a previous Wine installation exists, it's safer to
remove the whole
</para>
- <programlisting>
+<programlisting>
[MACHINE\\Software\\Microsoft\\Windows NT\\CurrentVersion\\AeDebug]
- </programlisting>
+</programlisting>
<para>
key before running again <command>wineinstall</command> to
regenerate this key.
@@ -1252,18 +1252,18 @@ winedbg myprog.exe
of options. Those options are stored in the registry, on a
per user basis. The key is (in <emphasis>my</emphasis> registry)
</para>
- <programlisting>
+<programlisting>
[HKCU\\Software\\Wine\\WineDbg]
- </programlisting>
+</programlisting>
<para>
Those options can be read/written while inside
<command>winedbg</command>, as part of the debugger
expressions. To refer to one of these options, its name must
be prefixed by a <literal>$</literal> sign. For example,
</para>
- <programlisting>
+<programlisting>
set $BreakAllThreadsStartup = 1
- </programlisting>
+</programlisting>
<para>
sets the option <varname>BreakAllThreadsStartup</varname> to
<literal>TRUE</literal>.
@@ -1383,17 +1383,13 @@ set $BreakAllThreadsStartup = 1
you're not sure what to exclude, here's a trick to get you started.
First, run your application for a minute or so, piping its output
to a file on disk:
- </para>
- <screen>
- WINEDEBUG=+relay wine <replaceable>appname.exe</replaceable> &>relay.log
- </screen>
- <para>
+<screen>
+WINEDEBUG=+relay wine <replaceable>appname.exe</replaceable> &>relay.log
+</screen>
Then run this command to see which calls are performed the most:
- </para>
- <screen>
- awk -F'(' '{print $1}' < relay.log | awk '{print $2}' | sort | uniq -c | sort
- </screen>
- <para>
+<screen>
+awk -F'(' '{print $1}' < relay.log | awk '{print $2}' | sort | uniq -c | sort
+</screen>
Exclude the bottom-most calls with <literal>RelayExclude</literal> after making
sure that they are irrelevant, then run your application again.
</para>
@@ -2384,7 +2380,7 @@ set $BreakAllThreadsStartup = 1
<para>
Start the Wine debugger with a command line like:
<screen>
- winedbg --gdb --no-start <replaceable>name_of_exe_to_debug.exe</replaceable> <optional><replaceable>optional parameters</replaceable></optional>
+winedbg --gdb --no-start <replaceable>name_of_exe_to_debug.exe</replaceable> <optional><replaceable>optional parameters</replaceable></optional>
</screen>
</para>
</listitem>
@@ -2403,7 +2399,7 @@ set $BreakAllThreadsStartup = 1
<para>
In the output of above command, there's a line like
<screen>
- target remote localhost:12345
+target remote localhost:12345
</screen>
Copy that line and paste into <command>ddd</command> command pane (the
one with the <prompt>(gdb)</prompt> prompt)
@@ -2423,7 +2419,7 @@ set $BreakAllThreadsStartup = 1
<para>
Start the Wine debugger with a command line like:
<screen>
- winedbg --gdb --no-start <replaceable>name_of_exe_to_debug.exe</replaceable> <optional><replaceable>optional parameters</replaceable></optional>
+winedbg --gdb --no-start <replaceable>name_of_exe_to_debug.exe</replaceable> <optional><replaceable>optional parameters</replaceable></optional>
</screen>
</para>
</listitem>
@@ -2431,7 +2427,7 @@ set $BreakAllThreadsStartup = 1
<para>
In the output of above command, there's a line like
<screen>
- target remote localhost:12345
+target remote localhost:12345
</screen>
Start kdbg with
<screen>
@@ -2503,57 +2499,43 @@ kdbg -r localhost:12345 wine
</para>
<para>
Change into your Wine source dir and enter:
- </para>
- <screen>
+<screen>
<prompt>$ </prompt><userinput>gdb wine</userinput>
- </screen>
- <para>
+</screen>
Switch to another console and enter <userinput>ps ax | grep
wine</userinput> to find all wine processes. Inside
<command>gdb</command>, repeat for all Wine processes:
- </para>
- <screen>
+<screen>
<prompt>(gdb) </prompt><userinput>attach <replaceable>wpid</replaceable></userinput>
- </screen>
- <para>
+</screen>
with <replaceable>wpid</replaceable> being the process ID of one of
the Wine processes. Use
- </para>
- <screen>
+<screen>
<prompt>(gdb) </prompt><userinput>bt</userinput>
- </screen>
- <para>
+</screen>
to get the backtrace of the current Wine process, i.e. the
function call history. That way you can find out what the
current process is doing right now. And then you can use
several times:
- </para>
- <screen>
+<screen>
<prompt>(gdb) </prompt><userinput>n</userinput>
- </screen>
- <para>
+</screen>
or maybe even
- </para>
- <screen>
+<screen>
<prompt>(gdb) </prompt><userinput>b <replaceable>SomeFunction</replaceable></userinput>
- </screen>
- <para>
+</screen>
and
- </para>
- <screen>
+<screen>
<prompt>(gdb) </prompt><userinput>c</userinput>
- </screen>
+</screen>
<para>
to set a breakpoint at a certain function and continue up to
that function. Finally you can enter
- </para>
- <screen>
+<screen>
<prompt>(gdb) </prompt><userinput>detach</userinput>
- </screen>
- <para>
+</screen>
to detach from the Wine process.
</para>
- <!-- *** End of xtra content *** -->
</sect2>
<sect2>
diff --git a/en/winedev-debugging.sgml b/en/winedev-debugging.sgml
index 92120a9..cd4d6e9 100644
--- a/en/winedev-debugging.sgml
+++ b/en/winedev-debugging.sgml
@@ -14,13 +14,13 @@
and how you can control the debugging output. A picture is
worth a thousand words, so here are a few examples of the
debugging API in action:
- <programlisting language="c">
+<programlisting language="c">
ERR("lock_count == 0 ... please report\n");
FIXME("Unsupported RTL style!\n");
WARN(": file seems to be truncated!\n");
TRACE("[%p]: new horz extent = %d\n", hwnd, extent );
MESSAGE( "Could not create graphics driver '%s'\n", buffer );
- </programlisting>
+</programlisting>
</para>
<sect1 id="dbg-classes">
@@ -105,7 +105,7 @@ MESSAGE( "Could not create graphics driver '%s'\n", buffer );
and as such, there is only one channel to output to. You can declare
a default channel for the file using the
<systemitem class="macro">WINE_DEFAULT_DEBUG_CHANNEL()</systemitem> macro:
- <programlisting language="c">
+<programlisting language="c">
#include "wine/debug.h"
WINE_DEFAULT_DEBUG_CHANNEL(xxx);
@@ -116,14 +116,14 @@ WINE_DEFAULT_DEBUG_CHANNEL(xxx);
if (zero != 0)
ERR("This should never be non-null: %d", zero);
...
- </programlisting>
+</programlisting>
</para>
<para>
In rare situations there is a need to output to more than one
debug channel per file. In such cases, you need to declare
all the additional channels at the top of the file, and
use the _-version of the debugging macros:
- <programlisting language="c">
+<programlisting language="c">
#include "wine/debug.h"
WINE_DEFAULT_DEBUG_CHANNEL(xxx);
@@ -137,7 +137,7 @@ WINE_DECLARE_DEBUG_CHANNEL(zzz);
...
WARN_(zzz)("And yet another msg on another channel!");
...
- </programlisting>
+</programlisting>
</para>
</sect1>
@@ -151,11 +151,11 @@ WINE_DECLARE_DEBUG_CHANNEL(zzz);
<systemitem class="macro">WARN_ON</systemitem>,
<systemitem class="macro">FIXME_ON</systemitem>, or
<systemitem class="macro">ERR_ON</systemitem> macros. For example:
- <programlisting>
+<programlisting>
if(TRACE_ON(atom)){
...blah...
}
- </programlisting>
+</programlisting>
You should normally need to test only if <literal>TRACE_ON</literal>,
all the others are very seldom used. With careful coding, you
can avoid the use of these macros, which is generally desired.
@@ -175,34 +175,34 @@ if(TRACE_ON(atom)){
The function is defined in <filename class="headerfile">wine/debug.h</filename>
and has the following prototype:
</para>
- <programlisting>
+<programlisting>
LPSTR debugres(const void *id);
- </programlisting>
+</programlisting>
<para>
It takes a pointer to the resource id and returns a nicely
formatted string of the identifier (which can be a string or
a number, depending on the value of the high word).
Numbers are formatted as such:
</para>
- <programlisting>
+<programlisting>
#xxxx
- </programlisting>
+</programlisting>
<para>
while strings as:
</para>
- <programlisting>
+<programlisting>
'some-string'
- </programlisting>
+</programlisting>
<para>
Simply use it in your code like this:
</para>
- <programlisting>
+<programlisting>
#include "wine/debug.h"
...
- TRACE("resource is %s", debugres(myresource));
- </programlisting>
+TRACE("resource is %s", debugres(myresource));
+</programlisting>
<para>
Many times strings need to be massaged before output:
@@ -211,12 +211,12 @@ LPSTR debugres(const void *id);
strings need to be converted to ASCII for usage with
the debugging API. For all this, you can use the
<function>debugstr_[aw]n?</function> family of functions:
- <programlisting>
+<programlisting>
HANDLE32 WINAPI YourFunc(LPCSTR s)
{
FIXME("(%s): stub\n", debugstr_a(s));
}
- </programlisting>
+</programlisting>
</para>
</sect1>
@@ -242,35 +242,31 @@ HANDLE32 WINAPI YourFunc(LPCSTR s)
Another way to conditionally log debug output (e.g. in case of
very large installers which may create gigabytes of log
output) is to create a pipe:
- </para>
- <screen>
- <prompt>$</prompt> <userinput>mknod /tmp/debug_pipe p</userinput>
- </screen>
-
+<screen>
+<prompt>$</prompt> <userinput>mknod /tmp/debug_pipe p</userinput>
+</screen>
+ </para>
<para>
and then to run wine like that:
- </para>
- <screen>
- <prompt>$</prompt> <userinput>WINEDEBUG=+relay,+snoop wine setup.exe &>/tmp/debug_pipe</userinput>
- </screen>
-
+<screen>
+<prompt>$</prompt> <userinput>WINEDEBUG=+relay,+snoop wine setup.exe &>/tmp/debug_pipe</userinput>
+</screen>
+ </para>
<para>
Since the pipe is initially blocking (and thus wine as a whole),
you have to activate it by doing:
- </para>
- <screen>
- <prompt>$</prompt> <userinput>cat /tmp/debug_pipe</userinput>
- </screen>
- <para>
+<screen>
+<prompt>$</prompt> <userinput>cat /tmp/debug_pipe</userinput>
+</screen>
(press Ctrl-C to stop pasting the pipe content)
- </para>
+ </para>
<para>
Once you are about to approach the problematic part of the program,
you just do:
- </para>
- <screen>
- <prompt>$</prompt> <userinput>cat /tmp/debug_pipe >/tmp/wine.log</userinput>
- </screen>
+<screen>
+<prompt>$</prompt> <userinput>cat /tmp/debug_pipe >/tmp/wine.log</userinput>
+</screen>
+</para>
<para>
to capture specifically the part that interests you from the
pipe without wasting excessive amounts of HDD space and
@@ -297,10 +293,10 @@ HANDLE32 WINAPI YourFunc(LPCSTR s)
enable(<literal>+</literal>)/disable(<literal>-</literal>)
all messages for the given channel (<replaceable>xxx</replaceable>)
on all classes. For example:
- </para>
- <programlisting>
+<screen>
WINEDEBUG=+reg,-file
- </programlisting>
+</screen>
+ </para>
<para>
enables all messages on the <literal>reg</literal>
channel and disables all messages on the
@@ -315,9 +311,9 @@ WINEDEBUG=+reg,-file
messages for the given channel (<literal>xxx</literal>)
only on the given class. For example:
</para>
- <programlisting>
+<screen>
WINEDEBUG=trace+reg,warn-file
- </programlisting>
+</screen>
<para>
enables trace messages on the <literal>reg</literal>
channel and disables warning messages on the
@@ -329,18 +325,18 @@ WINEDEBUG=trace+reg,warn-file
also, the pseudo-channel all is also supported and it
has the intuitive semantics:
</para>
- <screen>
- WINEDEBUG=+all -- enables all debug messages
- WINEDEBUG=-all -- disables all debug messages
- WINEDEBUG=<replaceable>yyy</replaceable>+all -- enables debug messages for class <replaceable>yyy</replaceable> on all channels.
- WINEDEBUG=<replaceable>yyy</replaceable>-all -- disables debug messages for class <replaceable>yyy</replaceable> on all channels.
- </screen>
+<screen>
+WINEDEBUG=+all -- enables all debug messages
+WINEDEBUG=-all -- disables all debug messages
+WINEDEBUG=<replaceable>yyy</replaceable>+all -- enables debug messages for class <replaceable>yyy</replaceable> on all channels.
+WINEDEBUG=<replaceable>yyy</replaceable>-all -- disables debug messages for class <replaceable>yyy</replaceable> on all channels.
+</screen>
<para>
So, for example:
</para>
- <screen>
- WINEDEBUG=warn-all -- disables all warning messages.
- </screen>
+<screen>
+WINEDEBUG=warn-all -- disables all warning messages.
+</screen>
</listitem>
</itemizedlist>
@@ -371,15 +367,17 @@ WINEDEBUG=trace+reg,warn-file
there is still room for improvement by using a common style
of debug messages. Before I continue, let me note that the
output format is the following:
- </para>
- <screen>
+<screen>
<replaceable>yyy</replaceable>:<replaceable>xxx</replaceable>:<replaceable>fff</replaceable> <replaceable>message</replaceable>
+</screen>
where:
- <replaceable>yyy</replaceable> = the class (<literal>fixme</literal>, <literal>err</literal>, <literal>warn</literal>, <literal>trace</literal>)
- <replaceable>xxx</replaceable> = the channel (<literal>atom</literal>, <literal>win</literal>, <literal>font</literal>, <literal>etc</literal>)
- <replaceable>fff</replaceable> = the function name
- </screen>
+<screen>
+<replaceable>yyy</replaceable> = the class (<literal>fixme</literal>, <literal>err</literal>, <literal>warn</literal>, <literal>trace</literal>)
+<replaceable>xxx</replaceable> = the channel (<literal>atom</literal>, <literal>win</literal>, <literal>font</literal>, <literal>etc</literal>)
+<replaceable>fff</replaceable> = the function name
+</screen>
+ </para>
<para>
These fields are output automatically. All you have to
provide is the <replaceable>message</replaceable> part.
@@ -399,26 +397,26 @@ where:
if you want to output the parameters of the function, do
it as the first thing and include them in parentheses,
like this:
- <programlisting language="c">
+<programlisting language="c">
TRACE("(%d, %p, ...)\n", <replaceable>par1</replaceable>, <parameter>par2</parameter>, ...);
- </programlisting>
+</programlisting>
</para>
</listitem>
<listitem>
<para>
if you want to name a parameter, use <literal>=</literal> :
- <programlisting language="c">
+<programlisting language="c">
TRACE("(fd=%d, file=%s): stub\n", <replaceable>fd</replaceable>, <replaceable>name</replaceable>);
- </programlisting>
+</programlisting>
</para>
</listitem>
<listitem>
<para>
for stubs, you should output a <literal>FIXME</literal>
message. I suggest this style:
- <programlisting language="c">
+<programlisting language="c">
FIXME("(%x, %d, ...): stub\n", <replaceable>par1</replaceable>, <replaceable>par2</replaceable>, ...);
- </programlisting>
+</programlisting>
</para>
</listitem>
<listitem>
@@ -432,17 +430,17 @@ FIXME("(%x, %d, ...): stub\n", <replaceable>par1</replaceable>, <replaceable>par
<para>
if the output string needs to be dynamically constructed,
render it in memory before outputting it:
- <programlisting language="c">
+<programlisting language="c">
char buffer[128] = "";
if (flags & FLAG_A) strcat(buffer, "FLAG_A ");
if (flags & FLAG_B) strcat(buffer, "FLAG_B ");
if (flags & FLAG_C) strcat(buffer, "FLAG_C ");
TRACE("flags = %s\n", buffer);
- </programlisting>
+</programlisting>
Most of the time however, it is better to create a helper
function that renders to a temporary buffer:
- <programlisting>
+<programlisting>
static const char *dbgstr_flags(int flags)
{
char buffer[128] = "";
@@ -456,7 +454,7 @@ static const char *dbgstr_flags(int flags)
...
TRACE("flags = %s\n", dbgstr_flags(flags));
- </programlisting>
+</programlisting>
</para>
</listitem>
</itemizedlist>
diff --git a/en/winedev-documentation.sgml b/en/winedev-documentation.sgml
index 2f6aeac..51c6651 100644
--- a/en/winedev-documentation.sgml
+++ b/en/winedev-documentation.sgml
@@ -201,11 +201,11 @@
(and most common type of) comment:
</para>
- <programlisting>
+<programlisting>
/*************************************************************************
* PathRelativePathToW [SHLWAPI.@]
*/
- </programlisting>
+</programlisting>
<para>
The functions name and the DLL name are obvious. The ordinal number takes one of
@@ -221,11 +221,11 @@
and the DLL/ordinal is free form. Thus the following is equally valid:
</para>
- <programlisting>
+<programlisting>
/*************************************************************************
* PathRelativePathToW (SHLWAPI.@)
*/
- </programlisting>
+</programlisting>
<para>
This basic comment will not get processed into documentation, since it
@@ -239,13 +239,13 @@
in general terms. It is free form text:
</para>
- <programlisting>
+<programlisting>
/*************************************************************************
* PathRelativePathToW [SHLWAPI.@]
*
* Create a relative path from one path to another.
*/
- </programlisting>
+</programlisting>
<para>
To be truly useful however we must document the parameters to the function.
@@ -257,7 +257,7 @@
Parameters documented in the comment should be formatted as follows:
</para>
- <screen>
+<screen>
/*************************************************************************
* PathRelativePathToW [SHLWAPI.@]
*
@@ -271,7 +271,7 @@
* dwAttrTo [I] File attributes of destination path
*
*/
- </screen>
+</screen>
<para>
The parameters section starts with <literal>PARAMS</literal> on its own line.
@@ -333,7 +333,7 @@
Our final documentation looks like the following:
</para>
- <programlisting>
+<programlisting>
/*************************************************************************
* PathRelativePathToW [SHLWAPI.@]
*
@@ -364,7 +364,7 @@
* This bug has been fixed here, so for example the relative path from "\\"
* to "\\" is correctly determined as "." in this implementation.
*/
- </programlisting>
+</programlisting>
</sect2>
<sect2 id="api-docs-advanced">
@@ -396,23 +396,23 @@
recommended that you document only the Unicode version and have the Ascii
version refer to the Unicode one, as follows:
</para>
- <programlisting>
+<programlisting>
/*************************************************************************
* PathRelativePathToA [SHLWAPI.@]
*
* See PathRelativePathToW.
*/
- </programlisting>
+</programlisting>
<para>
Alternately you may use the following form:
</para>
- <programlisting>
+<programlisting>
/*************************************************************************
* PathRelativePathToA [SHLWAPI.@]
*
* Unicode version of PathRelativePathToW.
*/
- </programlisting>
+</programlisting>
<para>
You may also use this construct in any other section, such as <literal>NOTES</literal>.
@@ -444,11 +444,11 @@
is assumed to be case listing and is emphasized and put in its own paragraph. This
is most often used for return values, as in the example section below.
</para>
- <programlisting>
+<programlisting>
* RETURNS
* Success: TRUE. Something happens that is documented here.
* Failure: FALSE. The reasons why this call can fail are listed here.
- </programlisting>
+</programlisting>
<para>
Any line starting with a '-' is put into a paragraph by itself.
@@ -491,14 +491,14 @@
use the name <interfacename>IExample</interfacename> as an example here. Your comment would
look like the following (assuming you are exporting this object from
<filename class="libraryfile">EXAMPLE.DLL</filename>):
- <programlisting>
+<programlisting>
/*************************************************************************
* IExample {EXAMPLE}
*
* The IExample object provides lots of interesting functionality.
* ...
*/
- </programlisting>
+</programlisting>
</para>
<para>
@@ -920,19 +920,27 @@
Generally, you will declare which DTD you want to use as
the first line of your SGML document. In the case of
DocBook, you will use something like this:
- <programlisting><!doctype book PUBLIC "-//OASIS//DTD DocBook V4.5//EN" []>
-<book>
+<programlisting>
+<![CDATA[
+<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.5//EN" []>
+<book>
...
-</book></programlisting>
+</book>
+]]>
+</programlisting>
</para>
<para>
Note that you must specify your toplevel element inside
the doctype declaration. If you were writing an article
rather than a book, you might use this declaration instead:
- <programlisting><!doctype article PUBLIC "-//OASIS//DTD DocBook V4.5//EN" []>
-<article>
+<programlisting>
+<![CDATA[
+<!doctype article PUBLIC "-//OASIS//DTD DocBook V4.5//EN" []>
+<article>
...
-</article></programlisting>
+</article>
+]]>
+</programlisting>
</para>
</sect3>
@@ -978,7 +986,7 @@
block so we don't have to bother converting all
brackets to entities
-->
- <programlisting>
+<programlisting>
<![CDATA[
<!doctype book PUBLIC "-//OASIS//DTD DocBook V4.5//EN" []>
<book id="index">
@@ -1288,7 +1296,8 @@
<title>EXAMPLE</title>
<para>This is an example note...</para>
</note>
-]]></programlisting>
+]]>
+</programlisting>
<para>
The results will look something like this:
</para>
@@ -1546,10 +1555,14 @@
the visible text for the link, plus the name of the <sgmltag
class="attribute">id</sgmltag> attribute of the
element that you want to link to. For example:
-<programlisting><link linkend="configuring-wine">the section on configuring wine</link>
+<programlisting>
+<![CDATA[
+<link linkend="configuring-wine">the section on configuring wine</link>
...
-<sect2 id="configuring-wine">
-...</programlisting>
+<sect2 id="configuring-wine">
+...
+]]>
+</programlisting>
</para>
</listitem>
</varlistentry>
@@ -1565,10 +1578,14 @@
to jump to:
</para>
<para>
-<programlisting><xref linkend="configuring-wine">
+<programlisting>
+<![CDATA[
+<xref linkend="configuring-wine">
...
-<sect2 id="configuring-wine">
-...</programlisting>
+<sect2 id="configuring-wine">
+...
+]]>
+</programlisting>
</para>
<para>
By default, most SGML processors will auto generate
@@ -1580,11 +1597,15 @@
hyperlink from another element:
</para>
<para>
-<programlisting><xref linkend="configuring-wine" endterm="config-title">
+<programlisting>
+<![CDATA[
+<xref linkend="configuring-wine" endterm="config-title">
+...
+<sect2 id="configuring-wine">
+ <title id="config-title">Configuring Wine</title>
...
-<sect2 id="configuring-wine">
- <title id="config-title">Configuring Wine</title>
-...</programlisting>
+]]>
+</programlisting>
</para>
<para>
This would create a link to the
diff --git a/en/winedev-kernel.sgml b/en/winedev-kernel.sgml
index 09d0e1c..4b5b840 100644
--- a/en/winedev-kernel.sgml
+++ b/en/winedev-kernel.sgml
@@ -184,9 +184,9 @@
the executable and then on this line:
</para>
- <programlisting language="c">
+<programlisting language="c">
ExitProcess( entry( peb ) );
- </programlisting>
+</programlisting>
<para>
... jumps to the entry point of the program. At this point the users
@@ -613,9 +613,9 @@ ExitProcess( entry( peb ) );
of the code to ensure that any held sections are left. Code like this:
</para>
- <programlisting language="c">
+<programlisting language="c">
if (res != ERROR_SUCCESS) return res;
- </programlisting>
+</programlisting>
<para>
is extremely suspect in a function that also contains a call to
@@ -705,7 +705,7 @@ if (res != ERROR_SUCCESS) return res;
you see code like this:
</para>
- <programlisting language="asm">movl %esp, %fs:0</programlisting>
+<programlisting language="asm">movl %esp, %fs:0</programlisting>
<para>
... then you are seeing the program set up an SEH handler frame. All
diff --git a/en/winedev-multimedia.sgml b/en/winedev-multimedia.sgml
index 4cb277c..fa04b04 100644
--- a/en/winedev-multimedia.sgml
+++ b/en/winedev-multimedia.sgml
@@ -84,7 +84,8 @@
<sect2>
<title>Windows 95 multimedia architecture</title>
- <screen><![CDATA[
+<screen>
+<![CDATA[
|
Kernel space | Client applications
|
@@ -125,7 +126,8 @@ Kernel space | Client applications
| | |<16
| +-------------------------------+
|
- ]]></screen>
+]]>
+</screen>
<para>
The important points to notice are:
@@ -183,7 +185,8 @@ Kernel space | Client applications
<sect2>
<title>Wine multimedia architecture</title>
- <screen><![CDATA[
+<screen>
+<![CDATA[
|
Kernel space | Client applications
|
@@ -219,7 +222,8 @@ Kernel space | Client applications
| | |<32/16
| +-------------------------------+
|
- ]]></screen>
+]]>
+</screen>
<para>
From the previous drawings, the most noticeable differences are:
@@ -593,9 +597,9 @@ Kernel space | Client applications
<para>
<filename class="libraryfile">msacm32</filename> keeps some data cached for all known ACM
drivers. Under the key
- <screen>
- Software\Microsoft\AudioCompressionManager\DriverCache\<replaceable>driver_name</replaceable>
- </screen>
+<screen>
+Software\Microsoft\AudioCompressionManager\DriverCache\<replaceable>driver_name</replaceable>
+</screen>
are kept for values:
<itemizedlist>
<listitem>
@@ -826,20 +830,20 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
<para>
Under the
- <screen>
+<screen>
HKLM\Software\Microsoft\Windows NT\CurrentVersion
- </screen>
+</screen>
key, are stored the names of the DLLs to be loaded for each
MCI driver name:
- <screen>
- "cdaudio"="mcicda.drv"
- "sequencer"="mciseq.drv"
- "waveaudio"="mciwave.drv"
- "avivideo"="mciavi.drv"
- "videodisc"="mcipionr.drv"
- "vcr"="mcivisca.drv"
- "MPEGVideo"="mciqtz.drv"
- </screen>
+<screen>
+"cdaudio"="mcicda.drv"
+"sequencer"="mciseq.drv"
+"waveaudio"="mciwave.drv"
+"avivideo"="mciavi.drv"
+"videodisc"="mcipionr.drv"
+"vcr"="mcivisca.drv"
+"MPEGVideo"="mciqtz.drv"
+</screen>
</para>
</sect2>
@@ -854,30 +858,30 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
<para>
Here's a sample configuration:
- <screen>
- [mci]
- MPEGVideo=mciqtz32.dll
- MPEGVideo2=mciqtz32.dll
- avivideo=mciavi32.dll
- cdaudio=mcicda.dll
- sequencer=mciseq.dll
- vcr=mcivisca.drv
- waveaudio=mciwave.dll
- </screen>
+<screen>
+[mci]
+MPEGVideo=mciqtz32.dll
+MPEGVideo2=mciqtz32.dll
+avivideo=mciavi32.dll
+cdaudio=mcicda.dll
+sequencer=mciseq.dll
+vcr=mcivisca.drv
+waveaudio=mciwave.dll
+</screen>
</para>
<para>
ACM drivers configuration is read (only so far) from the
<filename>system.ini</filename> (and setup at Wine
installation from the <filename>wine.inf</filename> file).
- <screen>
- [drivers32]
- msacm.imaadpcm=imaadp32.acm
- msacm.msadpcm=msadp32.acm
- msacm.msg711=msg711.acm
- msacm.winemp3=winemp3.acm
- msacm.msgsm610=msgsm32.acm
- </screen>
+<screen>
+[drivers32]
+msacm.imaadpcm=imaadp32.acm
+msacm.msadpcm=msadp32.acm
+msacm.msg711=msg711.acm
+msacm.winemp3=winemp3.acm
+msacm.msgsm610=msgsm32.acm
+</screen>
</para>
<para>
@@ -885,12 +889,12 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
far) from the <filename>system.ini</filename> (and setup at
Wine installation from the <filename>wine.inf</filename>
file).
- <screen>
- [drivers32]
- vidc.mrle=msrle32.dll
- vidc.msvc=msvidc32.dll
- vidc.cvid=iccvid.dll
- </screen>
+<screen>
+[drivers32]
+vidc.mrle=msrle32.dll
+vidc.msvc=msvidc32.dll
+vidc.cvid=iccvid.dll
+</screen>
</para>
<para>
@@ -909,9 +913,9 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
<para>
The Midi mapper configuration is the same as on Windows
9x. Under the key:
- <screen>
+<screen>
HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
- </screen>
+</screen>
if the <literal>UseScheme</literal> value is not set, or
is set to a null value, the MIDI mapper will always use
the driver identified by the
@@ -924,9 +928,11 @@ HKEY_CURRENT_USER\Software\Microsoft\Windows\CurrentVersion\Multimedia\MIDIMap
<literal>CurrentScheme</literal> defines the name of the
scheme to map the different channels. All the schemes are
available with keys like
- <screen>
+<screen>
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Schemes\<replaceable>scheme_name</replaceable>
- </screen>
+</screen>
+ </para>
+ <para>
For every scheme, under this key, will be a sub-key (which
name is usually a two digit index, starting at 00). Its
default value is the name of the output driver, and the
@@ -938,9 +944,9 @@ HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivatePrope
<para>
To provide enhanced configuration and mapping
capabilities, each driver can define under the key
- <screen>
+<screen>
HKEY_LOCAL_MACHINE\System\CurrentControlSet\Control\MediaProperties\PrivateProperties\Midi\Ports\<replaceable>driver_name</replaceable>
- </screen>
+</screen>
a link to and <filename class="extension">.IDF</filename> file which allows
to remap channels internally (for example 9 -> 16), to
change instruments identification, event controllers
diff --git a/en/winedev-ole.sgml b/en/winedev-ole.sgml
index 5b58512..09942b3 100644
--- a/en/winedev-ole.sgml
+++ b/en/winedev-ole.sgml
@@ -60,7 +60,8 @@
<para>
Let's take Direct3D as an example:
</para>
- <programlisting language="c">#define ICOM_INTERFACE IDirect3D
+<programlisting language="c">
+#define ICOM_INTERFACE IDirect3D
#define IDirect3D_METHODS \
ICOM_METHOD1(HRESULT,Initialize, REFIID,) \
ICOM_METHOD2(HRESULT,EnumDevices, LPD3DENUMDEVICESCALLBACK,, LPVOID,) \
@@ -86,7 +87,8 @@ ICOM_DEFINE(IDirect3D,IUnknown)
#define IDirect3D_CreateMaterial(p,a,b) ICOM_CALL2(CreateMaterial,p,a,b)
#define IDirect3D_CreateViewport(p,a,b) ICOM_CALL2(CreateViewport,p,a,b)
#define IDirect3D_FindDevice(p,a,b) ICOM_CALL2(FindDevice,p,a,b)
-#endif</programlisting>
+#endif
+</programlisting>
<para>
Comments:
</para>
@@ -169,7 +171,8 @@ ICOM_DEFINE(IDirect3D,IUnknown)
<para>
In C this gives:
</para>
- <programlisting language="c">typedef struct IDirect3DVtbl IDirect3DVtbl;
+<programlisting language="c">
+typedef struct IDirect3DVtbl IDirect3DVtbl;
struct IDirect3D {
IDirect3DVtbl* lpVtbl;
};
@@ -197,7 +200,8 @@ struct IDirect3DVtbl {
#define IDirect3D_CreateMaterial(p,a,b) (p)->lpVtbl->fnCreateMaterial(p,a,b)
#define IDirect3D_CreateViewport(p,a,b) (p)->lpVtbl->fnCreateViewport(p,a,b)
#define IDirect3D_FindDevice(p,a,b) (p)->lpVtbl->fnFindDevice(p,a,b)
-#endif</programlisting>
+#endif
+</programlisting>
<para>
Comments:
</para>
@@ -241,7 +245,8 @@ struct IDirect3DVtbl {
<para>
And in C++ (with <command>g++</command>):
</para>
- <programlisting language="cpp">typedef struct IDirect3D: public IUnknown {
+<programlisting language="cpp">
+typedef struct IDirect3D: public IUnknown {
private: HRESULT (*fnInitialize)(IDirect3D* me, REFIID a);
public: inline HRESULT Initialize(REFIID a) { return ((IDirect3D*)t.lpVtbl)->fnInitialize(this,a); };
private: HRESULT (*fnEnumDevices)(IDirect3D* me, LPD3DENUMDEVICESCALLBACK a, LPVOID b);
@@ -259,7 +264,8 @@ struct IDirect3DVtbl {
private: HRESULT (*fnFindDevice)(IDirect3D* me, LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b);
public: inline HRESULT FindDevice(LPD3DFINDDEVICESEARCH a, LPD3DFINDDEVICERESULT b)
{ return ((IDirect3D*)t.lpVtbl)->fnFindDevice(this,a,b); };
-};</programlisting>
+};
+</programlisting>
<para>
Comments:
</para>
@@ -323,7 +329,8 @@ struct IDirect3DVtbl {
This continues the above example. This example assumes that
the implementation is in C.
</para>
- <programlisting language="c">typedef struct _IDirect3D {
+<programlisting language="c">
+typedef struct _IDirect3D {
void* lpVtbl;
// ...
} _IDirect3D;
@@ -347,7 +354,8 @@ static ICOM_VTABLE(IDirect3D) d3dvt = {
IDirect3D_fnAdd2,
IDirect3D_fnInitialize,
IDirect3D_fnSetWidth
-};</programlisting>
+};
+</programlisting>
<para>
Comments:
</para>
diff --git a/en/winedev-opengl.sgml b/en/winedev-opengl.sgml
index d1a358f..b6dd163 100644
--- a/en/winedev-opengl.sgml
+++ b/en/winedev-opengl.sgml
@@ -218,10 +218,10 @@
<sect2>
<title>Unknown extension error message:</title>
- <screen>
+<screen>
Extension defined in the OpenGL library but NOT in opengl_ext.c...
Please report (lionel.ulmer at free.fr) !
- </screen>
+</screen>
<para>
This means that the extension requested by the application
@@ -280,12 +280,12 @@ Please report (lionel.ulmer at free.fr) !
<para>
create a dummy <filename class="extension">.c</filename> file:
</para>
- <programlisting language="c">
+<programlisting language="c">
int main(void)
{
return 0;
}
- </programlisting>
+</programlisting>
</listitem>
<listitem>
<para>
@@ -294,9 +294,9 @@ int main(void)
installed the Wine libraries in
<filename class="directory">/usr/local/lib</filename>, YMMV):
</para>
- <screen>
+<screen>
gcc dummy.c -L/usr/local/lib -L/usr/local/lib/wine -lwine -lopengl32
- </screen>
+</screen>
</listitem>
<listitem>
<para>
diff --git a/en/winedev-otherdebug.sgml b/en/winedev-otherdebug.sgml
index 3ac92a5..e577bc4 100644
--- a/en/winedev-otherdebug.sgml
+++ b/en/winedev-otherdebug.sgml
@@ -23,29 +23,29 @@
pushed onto the stack right-to-left. For example, the C call
<code language="c">myfunction(40, 20, 70, 30);</code> is expressed in
Intel assembly as:
- <programlisting language="asm">
- push 30
- push 70
- push 20
- push 40
- call myfunction
- </programlisting>
+<programlisting language="asm">
+push 30
+push 70
+push 20
+push 40
+call myfunction
+</programlisting>
The called function is responsible for removing the arguments
off the stack. Thus, before the call to myfunction, the
stack would look like:
- <screen>
- [local variable or temporary]
- [local variable or temporary]
- 30
- 70
- 20
- esp -> 40
- </screen>
+<screen>
+ [local variable or temporary]
+ [local variable or temporary]
+ 30
+ 70
+ 20
+esp -> 40
+</screen>
After the call returns, it should look like:
- <screen>
- [local variable or temporary]
- esp -> [local variable or temporary]
- </screen>
+<screen>
+ [local variable or temporary]
+esp -> [local variable or temporary]
+</screen>
</para>
<para>
@@ -105,16 +105,16 @@
<para>
Much more troublesome is the non-linear flow of a function. For
example, consider the following two functions:
- <programlisting language="asm">
- <replaceable>somefunction1</replaceable>:
- jmp <replaceable>somefunction1_impl</replaceable>
+<programlisting language="asm">
+<replaceable>somefunction1</replaceable>:
+ jmp <replaceable>somefunction1_impl</replaceable>
- <replaceable>somefunction2</replaceable>:
- ret 0004
+<replaceable>somefunction2</replaceable>:
+ ret 0004
- <replaceable>somefunction1_impl</replaceable>:
- ret 0008
- </programlisting>
+<replaceable>somefunction1_impl</replaceable>:
+ ret 0008
+</programlisting>
In this case, we would incorrectly detect both
<function><replaceable>somefunction1</replaceable></function> and
<function><replaceable>somefunction2</replaceable></function> as taking only a single
@@ -151,11 +151,11 @@
If you found that something broke between wine-1.1.42 and
wine-1.1.44 (these are [WWW] release tags). To start regression
testing we run:
- <screen>
+<screen>
git bisect start
git bisect good wine-1.1.42
git bisect bad wine-1.1.44
- </screen>
+</screen>
</para>
<para>
If you have exact date/time instead of a release you will need
@@ -167,35 +167,39 @@ git bisect bad wine-1.1.44
Having told Git when things were working and when they broke,
it will automatically <quote>position</quote> your source tree to the middle.
So all you need to do is build the source:
- <screen>
+<screen>
./configure && make clean && make depend && make
./wine 'c:\test.exe'
- </screen>
+</screen>
+ </para>
+ <para>
If the version of Wine that Git picked still has the bug, run:
- <screen>
+<screen>
git bisect bad
- </screen>
+</screen>
and if it does not, run:
- <screen>
+<screen>
git bisect good
- </screen>
+</screen>
+ </para>
+ <para>
When you run this command, Git will checkout a new version of Wine
for you to rebuild, so repeat this step again. When the regression
has been isolated, git will inform you.
</para>
<para>
To find out what's left to test, try:
- <screen>
+<screen>
git bisect visualize.
- </screen>
+</screen>
</para>
</listitem>
<listitem>
<para>
When you have found the bad patch and want to go back to the current HEAD run:
- <screen>
+<screen>
git bisect reset
- </screen>
+</screen>
</para>
</listitem>
<listitem>
@@ -255,18 +259,20 @@ git bisect reset
may still be). For example at the time of this writing, the
function <function>RegSetValueW</function> had the following
lines in it:
- <screen>
+<screen>
if (name && name[0]) /* need to create the subkey */
{
if ((ret = RegCreateKeyW( hkey, name, &subkey )) != ERROR_SUCCESS) return ret;
}
- </screen>
+</screen>
+ </para>
+ <para>
Currently there are a few tests written to test this function.
However, these tests don't check that everything is correct.
Using <command>gcov</command> and directed tests, we can validate the correctness
of this line of code. First, we see what has been tested already
by running gcov on the file. To do this, do the following:
- <screen>
+<screen>
cd dlls/advapi32
make clean && make EXTRACFLAGS=--coverage LDFLAGS=--coverage
cd tests
@@ -274,15 +280,17 @@ make test
cd ..
gcov registry.c
less registry.c.gcov
- </screen>
+</screen>
+ </para>
+ <para>
The interesting code part looks like this
in <filename>registry.c.gcov</filename>:
- <programlisting language="c">
- 4: 1273: if (name && name[0]) /* need to create the subkey */
- -: 1274: {
- #####: 1275: if ((ret = RegCreateKeyW( hkey, name, &subkey )) != ERROR_SUCCESS) return ret;
- -: 1276: }
- </programlisting>
+<programlisting language="c">
+ 4: 1273: if (name && name[0]) /* need to create the subkey */
+ -: 1274: {
+#####: 1275: if ((ret = RegCreateKeyW( hkey, name, &subkey )) != ERROR_SUCCESS) return ret;
+ -: 1276: }
+</programlisting>
<command>gcov</command> output consists of three components:
the number of times a line was run, the line number, and the
actual text of the line. Note: If a line is optimized out by
@@ -291,12 +299,12 @@ less registry.c.gcov
<varname>name</varname> is never passed to the function.
In order to validate this line, we need to do two things.
First, we must write the test:
- <programlisting language="c">
+<programlisting language="c">
ret = RegSetValueW(hkey_main, name1W, REG_SZ, string1W, sizeof(string1W));
ok(ret == ERROR_SUCCESS, "RegSetValueW failed: %d, GLE=%d\n", ret, GetLastError());
test_hkey_main_Value_A(name1A, string1A, sizeof(string1A));
test_hkey_main_Value_W(name1W, string1W, sizeof(string1W));
- </programlisting>
+</programlisting>
Once we add in this test case, we now want to know if the line
in question is run by this test and works as expected. You
should be in the same directory as in the previous command
@@ -305,9 +313,8 @@ test_hkey_main_Value_W(name1W, string1W, sizeof(string1W));
the count over. (If we leave the files then the number of times
the line is run is just added, e.g. line 545 below would be run
19 times.) We remove the <filename class="extension">*.gcov</filename> files
- because they are out of date and need to be recreated.
- </para>
- <screen>
+ because they are out of date and need to be recreated:
+<screen>
rm *.gcda *.gcov
cd tests
make
@@ -316,17 +323,18 @@ cd ..
cd ..
gcov registry.c
less registry.c.gcov
- </screen>
+</screen>
+ </para>
<para>
The interesting code part looks like this in
<filename>registry.c.gcov</filename>:
</para>
- <programlisting language="c">
- 5: 1273: if (name && name[0]) /* need to create the subkey */
- -: 1274: {
- 1: 1275: if ((ret = RegCreateKeyW( hkey, name, &subkey )) != ERROR_SUCCESS) return ret;
- -: 1276: }
- </programlisting>
+<programlisting language="c">
+ 5: 1273: if (name && name[0]) /* need to create the subkey */
+ -: 1274: {
+ 1: 1275: if ((ret = RegCreateKeyW( hkey, name, &subkey )) != ERROR_SUCCESS) return ret;
+ -: 1276: }
+</programlisting>
<para>
Based on gcov, we now know that line 1275 is executed once.
And since all of our other tests have remain unchanged, we
diff --git a/en/winedev-testing.sgml b/en/winedev-testing.sgml
index 609e144..31fb023 100644
--- a/en/winedev-testing.sgml
+++ b/en/winedev-testing.sgml
@@ -444,17 +444,17 @@ START_TEST(paths)
You can use <function>trace</function> to print informational messages. Note
that these messages will only be printed if <userinput>runtest -v</userinput> is being used.
<programlisting language="c">
- trace("testing GlobalAddAtomA\n");
- trace("foo=%d\n",foo);
+trace("testing GlobalAddAtomA\n");
+trace("foo=%d\n",foo);
</programlisting>
</para>
<para>
Then just call functions and use <function>ok</function> to make sure that
they behaved as expected:
<programlisting language="c">
- ATOM atom = GlobalAddAtomA( "foobar" );
- ok( GlobalFindAtomA( "foobar" ) == atom, "could not find atom foobar\n" );
- ok( GlobalFindAtomA( "FOOBAR" ) == atom, "could not find atom FOOBAR\n" );
+ATOM atom = GlobalAddAtomA( "foobar" );
+ok( GlobalFindAtomA( "foobar" ) == atom, "could not find atom foobar\n" );
+ok( GlobalFindAtomA( "FOOBAR" ) == atom, "could not find atom FOOBAR\n" );
</programlisting>
The first parameter of <function>ok</function> is an expression which must
evaluate to true if the test was successful. The next parameter is a
@@ -488,9 +488,11 @@ START_TEST(paths)
So how do you write a good error message? Let's start with an example
of a bad error message:
<programlisting language="c">
- ok(GetThreadPriorityBoost(curthread,&disabled)!=0,
- "GetThreadPriorityBoost Failed\n");
+ok(GetThreadPriorityBoost(curthread,&disabled)!=0,
+ "GetThreadPriorityBoost Failed\n");
</programlisting>
+ </para>
+ <para>
This will yield:
<screen>
thread.c:123: Test failed: GetThreadPriorityBoost Failed
@@ -506,11 +508,11 @@ thread.c:123: Test failed: GetThreadPriorityBoost Failed
<para>
Let's look at how to rewrite it:
<programlisting language="c">
- BOOL rc;
- ...
- rc=GetThreadPriorityBoost(curthread,&disabled);
- ok(rc!=0 && disabled==0,"rc=%d error=%ld disabled=%d\n",
- rc,GetLastError(),disabled);
+BOOL rc;
+...
+rc=GetThreadPriorityBoost(curthread,&disabled);
+ok(rc!=0 && disabled==0,"rc=%d error=%ld disabled=%d\n",
+ rc,GetLastError(),disabled);
</programlisting>
This will yield:
<screen>
@@ -548,7 +550,7 @@ thread.c:123: Test failed: rc=0 error=120 disabled=0
...
- eq( b, curr_val, "SPI_{GET,SET}BEEP", "%d" );
+eq( b, curr_val, "SPI_{GET,SET}BEEP", "%d" );
</programlisting>
</para>
</sect1>
diff --git a/en/winedev-windowing.sgml b/en/winedev-windowing.sgml
index 46c5843..e69e6a5 100644
--- a/en/winedev-windowing.sgml
+++ b/en/winedev-windowing.sgml
@@ -31,16 +31,18 @@
level of this hierarchy and their ancestor link
(<varname>wnd->parent</varname>) points to the desktop
window.
- </para>
- <screen>
- Desktop window - root window
- | \ `-.
- | \ `-.
- popup -> wnd1 -> wnd2 - top level windows
- | \ `-. `-.
- | \ `-. `-.
- child1 child2 -> child3 child4 - child windows
- </screen>
+<screen>
+<![CDATA[
+Desktop window - root window
+ | \ `-.
+ | \ `-.
+popup -> wnd1 -> wnd2i - top level windows
+ | \ `-. `-.
+ | \ `-. `-.
+child1 child2 -> child3 child4 - child windows
+]]>
+</screen>
+ </para>
<para>
Horizontal arrows denote sibling relationship, vertical
lines - ancestor/child. To summarize, all windows with the
@@ -63,9 +65,9 @@
<quote>above/below</quote> relationship. For instance, in the example
above, z-order is
</para>
- <screen>
+<screen>
child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
- </screen>
+</screen>
<para>
Current active window (<quote>foreground window</quote> in Win32) is
moved to the front of z-order unless its top-level
@@ -94,18 +96,18 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
<para><filename>dlls/user32/winpos.c</filename></para>
<para><filename>dlls/user32/painting.c</filename></para>
- <screen>
- ________________________
- |_________ | A and B are child windows of C
- | A |______ |
- | | | |
- |---------' | |
- | | B | |
- | | | |
- | `------------' |
- | C |
- `------------------------'
- </screen>
+<screen>
+ ________________________
+|_________ | A and B are child windows of C
+| A |______ |
+| | | |
+|---------' | |
+| | B | |
+| | | |
+| `------------' |
+| C |
+`------------------------'
+</screen>
<para>
Visible region determines which part of the window is
not obscured by other windows. If a window has the
@@ -118,15 +120,15 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
</para>
<para>
B has a <constant>WS_CLIPSIBLINGS</constant> style:
- </para>
- <screen>
- . ______
- : | |
- | ,-----' |
- | | B | - visible region of B
- | | |
- : `------------'
- </screen>
+<screen>
+ . ______
+ : | |
+ | ,-----' |
+ | | B | - visible region of B
+ | | |
+ : `------------'
+</screen>
+ </para>
<para>
When the program requests a <firstterm>display
context</firstterm> (DC) for a window it can specify
@@ -137,16 +139,18 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
</para>
<para>
Program asked for a DC with a clipping region:
- </para>
- <screen>
- ______
- ,--|--. | . ,--.
- ,--+--' | | : _: |
- | | B | | => | | | - DC region where the painting will
- | | | | | | | be visible
- `--|-----|---' : `----'
- `-----'
- </screen>
+<screen>
+<![CDATA[
+ ______
+ ,--|--. | . ,--.
+,--+--' | | : _: |
+| | B | | => | | | - DC region where the painting will
+| | | | | | | be visible
+`--|-----|---' : `----'
+ `-----'
+]]>
+</screen>
+ </para>
<para>
When the window manager detects that some part of the window
became visible it adds this area to the update region of this
@@ -165,19 +169,21 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
</para>
<para>
A was moved to the left:
- </para>
- <screen>
- ________________________ ... / C update region
- |______ | : .___ /
- | A |_________ | => | ...|___|..
- | | | | | : | |
- |------' | | | : '---'
- | | B | | | : \
- | | | | : \
- | `------------' | B update region
- | C |
- `------------------------'
- </screen>
+<screen>
+<![CDATA[
+ ________________________ ... / C update region
+|______ | : .___ /
+| A |_________ | => | ...|___|..
+| | | | | : | |
+|------' | | | : '---'
+| | B | | | : \
+| | | | : \
+| `------------' | B update region
+| C |
+`------------------------'
+]]>
+</screen>
+ </para>
<para>
Windows maintains a display context cache consisting of
entries that include the DC itself, the window to which
@@ -469,11 +475,11 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
global handles <type>HACCEL16</type> and
<type>HACCEL32</type> by the Win16/Win32 API.
These are 5 bytes long, with no padding:
- <programlisting language="c">
+<programlisting language="c">
BYTE fVirt;
WORD key;
WORD cmd;
- </programlisting>
+</programlisting>
</para>
</listitem>
<listitem>
@@ -482,13 +488,13 @@ WORD cmd;
user only by direct accessing PE resources. These have a
size of 8 bytes:
</para>
- <programlisting language="c">
+<programlisting language="c">
BYTE fVirt;
BYTE pad0;
WORD key;
WORD cmd;
WORD pad1;
- </programlisting>
+</programlisting>
</listitem>
<listitem>
<para>
@@ -498,12 +504,12 @@ WORD pad1;
in the Win32 API.
These have a size of 6 bytes:
</para>
- <programlisting language="c">
+<programlisting language="c">
BYTE fVirt;
BYTE pad0;
WORD key;
WORD cmd;
- </programlisting>
+</programlisting>
</listitem>
</orderedlist>
@@ -545,8 +551,7 @@ WORD cmd;
each key needs to generate. Find it in the
<function>main_key_scan</function> table, which looks like
this:
- </para>
- <programlisting language="c">
+<programlisting language="c">
static const int main_key_scan[MAIN_LEN] =
{
/* this is my (102-key) keyboard layout, sorry if it doesn't quite match yours */
@@ -556,7 +561,8 @@ static const int main_key_scan[MAIN_LEN] =
0x2C,0x2D,0x2E,0x2F,0x30,0x31,0x32,0x33,0x34,0x35,
0x56 /* the 102nd key (actually to the right of l-shift) */
};
- </programlisting>
+</programlisting>
+ </para>
<para>
Next, assign each scancode the characters imprinted on the
keycaps. This was done (sort of) for the US 101-key keyboard,
@@ -578,8 +584,7 @@ static const int main_key_scan[MAIN_LEN] =
</para>
<!--para>
For example, my Norwegian keyboard looks like this
- </para>
- <screen>
+<screen>
§ ! " # ¤ % & / ( ) = ? ` Back-
| 1 2@ 3£ 4$ 5 6 7{ 8[ 9] 0} + \´ space
@@ -593,7 +598,8 @@ Sh- > Z X C V B N M ; : _ Shift
ift < , . -
Ctrl Alt Spacebar AltGr Ctrl
- </screen>
+</screen>
+ </para>
<para>
Note the 102nd key, which is the <keycap><></keycap> key, to
the left of <keycap>Z</keycap>. The character to the right of
@@ -602,8 +608,7 @@ Ctrl Alt Spacebar AltGr Ctrl
</para>
<para>
This keyboard is defined as follows:
- </para>
- <programlisting>
+<programlisting>
static const char main_key_NO[MAIN_LEN][4] =
{
"|§","1!","2\"@","3#£","4¤$","5%","6&","7/{","8([","9)]","0=}","+?","\\´",
@@ -612,7 +617,8 @@ static const char main_key_NO[MAIN_LEN][4] =
"zZ","xX","cC","vV","bB","nN","mM",",;",".:","-_",
"<>"
};
- </programlisting>
+</programlisting>
+ </para>
<para>
Except that " and \ needs to be quoted with a backslash, and
that the 102nd key is on a separate line, it's pretty
@@ -623,7 +629,7 @@ static const char main_key_NO[MAIN_LEN][4] =
<varname>main_key_tab[]</varname> layout index table. This
will look like this:
</para>
- <programlisting language="c">
+<programlisting language="c">
static struct {
WORD lang, ansi_codepage, oem_codepage;
const char (*key)[MAIN_LEN][4];
@@ -632,14 +638,14 @@ const char (*key)[MAIN_LEN][4];
...
{MAKELANGID(LANG_NORWEGIAN,SUBLANG_DEFAULT), 1252, 865, &main_key_NO},
...
- </programlisting>
+</programlisting>
<para>
After you have added your table, recompile Wine and test that
it works. If it fails to detect your table, try running
</para>
- <screen>
+<screen>
WINEDEBUG=+key,+keyboard wine > key.log 2>&1
- </screen>
+</screen>
<para>
and look in the resulting <filename>key.log</filename> file to
find the error messages it gives for your layout.
--
1.8.4
More information about the wine-patches
mailing list