[docs] winedev: Assorted formatting & tagging fixes
Frédéric Delanoy
frederic.delanoy at gmail.com
Mon Aug 26 15:21:55 CDT 2013
A couple typos as well.
---
en/winedev-architecture.sgml | 18 ++--
en/winedev-coding.sgml | 52 +++++------
en/winedev-ddraw.sgml | 92 +++++++++++---------
en/winedev-debugger.sgml | 196 ++++++++++++++++++++++--------------------
en/winedev-debugging.sgml | 21 ++---
en/winedev-documentation.sgml | 106 ++++++++++++-----------
en/winedev-kernel.sgml | 79 +++++++++--------
en/winedev-multimedia.sgml | 53 ++++++------
en/winedev-opengl.sgml | 12 +--
en/winedev-otherdebug.sgml | 22 ++---
en/winedev-testing.sgml | 128 +++++++++++++--------------
en/winedev-windowing.sgml | 8 +-
12 files changed, 408 insertions(+), 379 deletions(-)
diff --git a/en/winedev-architecture.sgml b/en/winedev-architecture.sgml
index eaf76bd..8fc9edf 100644
--- a/en/winedev-architecture.sgml
+++ b/en/winedev-architecture.sgml
@@ -41,7 +41,7 @@
<sect2>
<title>Executables</title>
<para>
- Wine's main task is to run Windows executables under non
+ Wine main task is to run Windows executables under non
Windows operating systems. It supports different types of
executables:
<itemizedlist>
@@ -426,7 +426,7 @@
rare cases where this is not the case, and have been
properly documented (Wine DLLs export some Wine specific
APIs). Usually, those are prefixed with
- <function>__wine</function>.
+ <literal>__wine</literal>.
</para>
<para>
Let's now review in greater details all of those components.
@@ -616,7 +616,7 @@
</para>
<para>
Since Wine is 32-bit code itself, and if the compiler
- supports Windows calling convention, <type>stdcall</type>
+ supports Windows calling convention, <literal>stdcall</literal>
(<command>gcc</command> does), Wine can resolve imports
into Win32 code by substituting the addresses of the Wine
handlers directly without any thunking layer in
@@ -625,8 +625,8 @@
expect anyway.
</para>
<para>
- However, if the user specified <parameter>WINEDEBUG=+relay
- </parameter>, a thunk layer is inserted between the
+ However, if the user specified <userinput><envar>WINEDEBUG</envar>=+relay</userinput>,
+ a thunk layer is inserted between the
application imports and the Wine handlers (actually the
export table of the DLL is modified, and a thunk is
inserted in the table); this layer is known as <quote>relay</quote>
@@ -636,7 +636,7 @@
but it's invaluable for debugging misbehaving calls into
Wine code. A similar mechanism also exists between Windows
DLLs - Wine can optionally insert thunk layers between
- them, by using <parameter>WINEDEBUG=+snoop</parameter>,
+ them, by using <userinput><envar>WINEDEBUG</envar>=+snoop</userinput>,
but since no DLL descriptor information exists for
non-Wine DLLs, this is less reliable and may lead to
crashes.
@@ -660,7 +660,7 @@
<para>
This document mainly deals with the status of current DLL
- support by Wine. <filename>Winecfg</filename> currently supports
+ support by Wine. <command>winecfg</command> currently supports
settings to change the load order of DLLs. The load order
depends on several issues, which results in different settings
for various DLLs.
@@ -767,9 +767,9 @@
the maximum space addressable with a 32-bit pointer). Pages
can be mapped or unmapped: attempts to access an unmapped
page cause an
- <constant>EXCEPTION_ACCESS_VIOLATION</constant> which has
+ <errorname>EXCEPTION_ACCESS_VIOLATION</errorname> which has
the easily recognizable code of
- <constant>0xC0000005</constant>. Any page can be mapped to
+ <errorcode>0xC0000005</errorcode>. Any page can be mapped to
any frame, therefore you can have multiple addresses which
actually <quote>contain</quote> the same memory. Pages can also be mapped
to things like files or swap space, in which case accessing
diff --git a/en/winedev-coding.sgml b/en/winedev-coding.sgml
index 7ff5f27..a805d24 100644
--- a/en/winedev-coding.sgml
+++ b/en/winedev-coding.sgml
@@ -101,7 +101,7 @@
<para>
Commenting out a block of code is usually done by
enclosing it in <command>#if 0 ... #endif</command>
- Statements. For example.
+ statements. For example.
</para>
<screen>
/* note about reason for commenting block */
@@ -164,20 +164,20 @@ code
</listitem>
<listitem>
<para>
- Using regedit add key "Content Type"
- with value "text/plain" to the
+ Using <command>regedit</command> add key <literal>Content Type</literal>
+ with value <literal>text/plain</literal> to the
<filename>.diff</filename> extension under
- HKEY_CLASSES_ROOT (same as for <filename>.txt</filename>
+ <literal>HKEY_CLASSES_ROOT</literal> (same as for <filename>.txt</filename>
extension). This tells OE to use
- Content-Type: text/plain instead of
- application/octet-stream.
+ <literal>Content-Type: text/plain</literal> instead of
+ <literal>application/octet-stream</literal>.
</para>
</listitem>
</orderedlist>
<para>
- Item #1 is important. After you hit the "Send" button, go to
- "Outbox" and using "Properties" verify the message source to
- make sure that the mail has the correct format. You might want
+ Item #1 is important. After you hit the <guibutton>Send</guibutton> button, go to
+ <guilabel>Outbox</guilabel> and using <guibutton>Properties</guibutton> verify the message
+ source to make sure that the mail has the correct format. You might want
to send several test emails to yourself too.
</para>
</sect2>
@@ -186,7 +186,7 @@ code
<para>
<quote>The basic rules are: no attachments, no MIME crap, no
line wrapping, a single patch per mail. Basically if I can't
- do <command>"cat raw_mail | patch -p0"</command> it's in the
+ do <userinput>cat raw_mail | patch -p0</userinput> it's in the
wrong format.</quote>
</para>
</sect2>
@@ -203,7 +203,7 @@ code
Make sure your patch applies to the current Git HEAD
revisions. If a bunch of patches are committed that may
affect whether your patch will apply cleanly then verify that
- your patch does apply! <command>git fetch; git rebase origin</command>
+ your patch does apply! <userinput>git fetch; git rebase origin</userinput>
is your friend!
</para>
<para>
@@ -238,15 +238,15 @@ code
<para>
Operating systems change. Maybe yours doesn't have the
<filename>foo.h</filename> header, but maybe a future
- version will have it. If you want to <symbol>#include
- <foo.h></symbol>, it doesn't matter what operating
+ version will have it. If you want to <userinput>#include
+ <foo.h></userinput>, it doesn't matter what operating
system you are using; it only matters whether
<filename>foo.h</filename> is there.
</para>
<para>
Furthermore, operating systems change names or <quote>fork</quote> into
- several ones. An <symbol>#ifdef <replaceable>MyOS</replaceable></symbol> will break
- over time.
+ several ones. An <userinput>#ifdef <replaceable>MyOS</replaceable></userinput> will break
+ over time.
</para>
<para>
If you use the feature of <command>autoconf</command> -- the
@@ -279,8 +279,8 @@ code
</listitem>
</itemizedlist>
<para>
- You will need Gnu Autoconf, which you can get from your
- friendly Gnu mirror. This program takes Wine
+ You will need GNU <command>autoconf</command>, which you can get from your
+ friendly GNU mirror. This program takes Wine
<filename>configure.ac</filename> file and produces a
<filename>configure</filename> shell script that users use
to configure Wine to their system.
@@ -290,9 +290,9 @@ code
#ifdef <replaceable>MyOS</replaceable></quote> rule. Wine, for example, needs
the internals of the signal stack -- that cannot easily be
described in terms of features. Moreover, you cannot use
- <filename>autoconf</filename> <symbol>HAVE_*</symbol>
+ <command>autoconf</command> <symbol>HAVE_*</symbol>
symbols in Wine headers, as these may be used by Winelib
- users who may not be using a <filename>configure</filename>
+ users who may not be using a <command>configure</command>
script.
</para>
<para>
@@ -339,11 +339,11 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<para>
If your system doesn't have a corresponding header file even
though it has the library functions being used, you might
- have to add an <symbol>#else</symbol> section to the
+ have to add an <literal>#else</literal> section to the
conditional. Avoid this if you can.
</para>
<para>
- You will also need to add <symbol>#undef HAVE_FOO_H</symbol>
+ You will also need to add <userinput>#undef HAVE_FOO_H</userinput>
(etc.) to <filename>include/config.h.in</filename>.
</para>
<para>
@@ -388,15 +388,15 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<para>
You add your implementation in
<filename>misc/port.c</filename> surrounded by
- <symbol>#ifndef HAVE_MEMMOVE</symbol> and
- <symbol>#endif</symbol>.
+ <userinput>#ifndef HAVE_MEMMOVE</userinput> and
+ <literal>#endif</literal>.
</para>
<para>
You might have to add a prototype for your function.
If so, <filename>include/miscemu.h</filename> might be
the place. Don't forget to protect that definition by
- <symbol>#ifndef HAVE_MEMMOVE</symbol> and
- <symbol>#endif</symbol> also!
+ <userinput>#ifndef HAVE_MEMMOVE</userinput> and
+ <literal>#endif</literal> also!
</para>
</listitem>
</varlistentry>
@@ -485,7 +485,7 @@ AC_CHECK_HEADER(foo.h, AC_DEFINE(HAVE_FOO_H))
<para>
To get a list of the files that need translating,
run the following command in the root of your Wine tree:
- <command>find -name "*En.rc"</command>.
+ <userinput>find -name "*En.rc"</userinput>.
</para>
<para>
diff --git a/en/winedev-ddraw.sgml b/en/winedev-ddraw.sgml
index 816ec4e..fb99df2 100644
--- a/en/winedev-ddraw.sgml
+++ b/en/winedev-ddraw.sgml
@@ -18,24 +18,26 @@
<para>
Most of the DirectDraw functionality is implemented in a common base
class. Derived classes are responsible for providing display
- mode functions (Enum, Set, Restore), GetCaps, GetDevice identifier
+ mode functions (<function>EnumDisplayModes</function>, <function>SetDisplayMode</function>,
+ <function>RestoreDisplayMode</function>), <function>GetCaps</function>,
+ <function>GetDeviceIdentifier</function>
and internal functions called to create primary and backbuffer
surfaces.
</para>
<para>
- User provides for DirectDraw capabilities based on drawing to a
- Wine window. It uses the User DirectDrawSurface implementation
- for primary and backbuffer surfaces.
- </para>
+ <classname>User</classname> provides for DirectDraw capabilities based on drawing to a
+ Wine window. It uses the <classname>User</classname> <type>DirectDrawSurface</type>
+ implementation for primary and backbuffer surfaces.
+ </para>
<para>
- XVidMode attempt to use the XFree86 VidMode extension to set the
- display resolution to match the parameters to SetDisplayMode.
+ <classname>XVidMode</classname> attempt to use the XFree86 VidMode extension to set the
+ display resolution to match the parameters to <function>SetDisplayMode</function>.
</para>
<para>
- DGA2 attempt to use the XFree86 DGA 2.x extension to set the
+ <classname>DGA2</classname> attempt to use the XFree86 DGA 2.x extension to set the
display resolution and direct access to the framebuffer, if the
full-screen-exclusive cooperative level is used. If not, it just
- uses the User implementation.
+ uses the <classname>User</classname> implementation.
</para>
</sect1>
<sect1 id="ddsurfaceinheritance">
@@ -51,30 +53,31 @@
User DGA2 DIBTexture
</programlisting>
<para>
- Main provides a very simple base class that does not implement any of
- the image-related functions. Therefore it does not place any
+ <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
constraints on how the surface data is stored.
</para>
<para>
- DIB stores the surface data in a DIB section. It is used by the Main
- DirectDraw driver to create off-screen surfaces.
+ <classname>DIB</classname> stores the surface data in a DIB section. It is used by the
+ <classname>Main</classname> DirectDraw driver to create off-screen surfaces.
</para>
<para>
- User implements primary and backbuffer surfaces for the User DirectDraw
- driver. If it is a primary surface, it will attempt to keep itself
+ <classname>User</classname> implements primary and backbuffer surfaces for the User
+ DirectDraw driver. If it is a primary surface, it will attempt to keep itself
synchronized to the window.
</para>
<para>
- DGA2 surfaces claims an appropriate section of framebuffer space and
- lets DIB build its DIB section on top of it.
+ <classname>DGA2</classname> surfaces claims an appropriate section of framebuffer space
+ and lets <classname>DIB</classname> build its DIB section on top of it.
</para>
<para>
- Fake Z-Buffer surfaces are used by Direct3D to indicate that a primary
- surface has an associated z-buffer. For a first implementation, it
+ <classname>Fake Z-Buffer</classname> surfaces are used by Direct3D to indicate that a
+ primary surface has an associated z-buffer. For a first implementation, it
doesn't need to store any image data since it is just a placeholder.
</para>
<para>
- (Actually 3D programs will rarely use Lock or GetDC on primary
+ (Actually 3D programs will rarely use <function>Lock</function> or
+ <function>GetDC</function> on primary
surfaces, backbuffers or z-buffers so we may want to arrange for
lazy allocation of the DIB sections.)
</para>
@@ -90,9 +93,9 @@
<para>
Not all interface versions have thunks. Some versions could be combined
because their parameters were compatible. For example if a structure
- changes but the structure has a dwSize field, methods using that structure
- are compatible, as long as the implementation remembers to take the dwSize
- into account.
+ changes but the structure has a <structfield>dwSize</structfield> field, methods using that
+ structure are compatible, as long as the implementation remembers to take the
+ <structfield>dwSize</structfield> into account.
</para>
<para>
Interface thunks for Direct3D are more complicated since the paradigm
@@ -104,14 +107,15 @@
<title>Logical Object Layout</title>
<para>
The objects are split into the generic part (essentially the fields for
- Main) and a private part. This is necessary because some objects
- can be created with CoCreateInstance, then Initialized later. Only
+ <classname>Main</classname>) and a private part. This is necessary because some objects
+ can be created with <function>CoCreateInstance</function>, then initialized later. Only
at initialization time do we know which class to use. Each class
- except Main declares a Part structure and adds that to its Impl.
+ except <classname>Main</classname> declares a <structname>Part</structname> structure and
+ adds that to its Impl.
</para>
<para>
- For example, the DIBTexture DirectDrawSurface implementation looks
- like this:
+ For example, the <classname>DIBTexture</classname> <type>DirectDrawSurface</type>
+ implementation looks like this:
</para>
<programlisting>
struct DIBTexture_DirectDrawSurfaceImpl_Part
@@ -126,12 +130,13 @@
} DIBTexture_DirectDrawSurfaceImpl;
</programlisting>
<para>
- So the DIBTexture surface class is derived from the DIB surface
- class and it adds one piece of data, a union.
+ 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.
</para>
<para>
- Main does not have a Part structure. Its fields are stored in
- IDirectDrawImpl/IDirectDrawSurfaceImpl.
+ <classname>Main</classname> does not have a <structname>Part</structname> structure. Its
+ fields are stored in
+ <classname>IDirectDrawImpl</classname>/<classname>IDirectDrawSurfaceImpl</classname>.
</para>
<para>
To access private data, one says
@@ -145,22 +150,23 @@
<sect1 id="creatingobject">
<title>Creating Objects</title>
<para>
- Classes have two functions relevant to object creation, Create and
- Construct. To create a new object, the class' Create function is
- called. It allocates enough memory for IDirectDrawImpl or
- IDirectDrawSurfaceImpl as well as the private data for derived
- classes and then calls Construct.
+ Classes have two functions relevant to object creation, <function>Create</function> and
+ <function>Construct</function>. To create a new object, the <function>Create</function>
+ function of the class is called. It allocates enough memory for
+ <classname>IDirectDrawImpl</classname> or <classname>IDirectDrawSurfaceImpl</classname>
+ as well as the private data for derived classes and then calls
+ <filename>Construct</filename>.
</para>
<para>
- Each class's Construct function calls the base class's Construct,
- then does the necessary initialization.
+ Each class <function>Construct</function> function calls the base class
+ <function>Construct</function>, then does the necessary initialization.
</para>
<para>
For example, creating a primary surface with the user ddraw driver
- calls User_DirectDrawSurface_Create which allocates memory for the
- object and calls User_DirectDrawSurface_Construct to initialize it.
- This calls DIB_DirectDrawSurface_Construct which calls
- Main_DirectDrawSurface_Construct.
+ calls <function>User_DirectDrawSurface_Create</function> which allocates memory for the
+ object and calls <function>User_DirectDrawSurface_Construct</function> to initialize it.
+ This calls <function>DIB_DirectDrawSurface_Construct</function> which calls
+ <function>Main_DirectDrawSurface_Construct</function>.
</para>
</sect1>
</chapter>
diff --git a/en/winedev-debugger.sgml b/en/winedev-debugger.sgml
index ce72570..1b764b0 100644
--- a/en/winedev-debugger.sgml
+++ b/en/winedev-debugger.sgml
@@ -201,7 +201,7 @@ winedbg hl.exe -windowed
<variablelist>
<varlistentry>
- <term>continue</term>
+ <term><literal>continue</literal></term>
<listitem>
<para>
the debugger had the ability to correct what's
@@ -211,7 +211,7 @@ winedbg hl.exe -windowed
</listitem>
</varlistentry>
<varlistentry>
- <term>pass</term>
+ <term><literal>pass</literal></term>
<listitem>
<para>
the debugger couldn't correct the cause of the
@@ -245,8 +245,9 @@ winedbg hl.exe -windowed
<para>
You can stop the debugger while it's running by hitting
- Ctrl-C in its window. This will stop the debugged process,
- and let you manipulate the current context.
+ <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> in its
+ window. This will stop the debugged process, and let you manipulate
+ the current context.
</para>
</sect2>
@@ -507,7 +508,7 @@ process tid prio (all id:s are in hex)
<para>
Determine the cause of the crash. Since this is usually
a primary/secondary reaction to a failed or misbehaving
- Wine function, rerun Wine with the <parameter>WINEDEBUG=+relay</parameter>
+ Wine function, rerun Wine with the <userinput><envar>WINEDEBUG</envar>=+relay</userinput>
environment variable set. This will
generate quite a lot of output, but usually the reason is
located in the last calls. Those lines usually look like
@@ -536,7 +537,7 @@ process tid prio (all id:s are in hex)
Try to make sense of the arguments passed. Usually there is a
<function>WINE_DEFAULT_DEBUG_CHANNEL(<parameter><replaceable>channel</replaceable></parameter>);</function>
at the beginning of the source file. Rerun wine with the
- <parameter>WINEDEBUG=+xyz,+relay</parameter> environment variable set.
+ <userinput><envar>WINEDEBUG</envar>=+xyz,+relay</userinput> environment variable set.
</para>
<para>
Occasionally there are additional debug channels defined at the
@@ -560,7 +561,7 @@ process tid prio (all id:s are in hex)
<para>
If this information isn't clear enough or if you want to
know more about what's happening in the function itself,
- try running wine with <parameter>WINEDEBUG=+all</parameter>,
+ try running wine with <userinput><envar>WINEDEBUG</envar>=+all</userinput>,
which dumps ALL included debug information in wine.
It is often necessary to limit the debug output produced.
That can be done by piping the output through <command>grep</command>,
@@ -575,7 +576,7 @@ process tid prio (all id:s are in hex)
Logging in this guide for more information. You might
also try to run the program in <command>gdb</command>
instead of using the Wine debugger. If you do that, use
- <parameter>handle SIGSEGV nostop noprint</parameter> to
+ <userinput>handle SIGSEGV nostop noprint</userinput> to
disable the handling of seg faults inside
<command>gdb</command> (needed for Win16).
</para>
@@ -585,9 +586,9 @@ process tid prio (all id:s are in hex)
You can also set a breakpoint for that function. Start wine
using <command>winedbg</command> instead of
<command>wine</command>. Once the debugger is running enter
- <command>break</command> <parameter>RegOpenKeyExW</parameter>
- (replace by function you want to debug, CASE IS RELEVANT)
- to set a breakpoint. Then
+ <userinput>break RegOpenKeyExW</userinput>
+ (replace by function you want to debug, <emphasis role="strong">case is
+ relevant</emphasis>) to set a breakpoint. Then
use <command>continue</command> to start normal
program-execution. Wine will stop if it reaches the
breakpoint. If the program isn't yet at the crashing call
@@ -629,13 +630,13 @@ process tid prio (all id:s are in hex)
the message box you can start winedbg and set a
breakpoint at <function>MessageBoxA</function> (called by win16
and win32 programs) and proceed with
- <command>continue</command>. With <parameter>WINEDEBUG=+all</parameter>
+ <command>continue</command>. With <userinput><envar>WINEDEBUG</envar>=+all</userinput>
Wine will now stop directly before setting
up the message box. Proceed as explained above.
</para>
<para>
- You can also run wine using <command>WINEDEBUG=+relay wine
- program.exe 2>&1 | less -i</command> and in
+ You can also run wine using <userinput>WINEDEBUG=+relay wine
+ program.exe 2>&1 | less -i</userinput> and in
<command>less</command> search for <quote>MessageBox</quote>.
</para>
</sect2>
@@ -698,12 +699,12 @@ mov bp, sp
retf XXXX <--------- XXXX is number of bytes of arguments
</programlisting>
<para>
- This is a <function>FAR</function> function with no local
+ This is a <literal>FAR</literal> function with no local
storage. The arguments usually start at
<literal>[bp+6]</literal> with increasing offsets. Note, that
<literal>[bp+6]</literal> belongs to the
<emphasis>rightmost</emphasis> argument, for exported win16
- functions use the PASCAL calling convention. So, if we use
+ functions use the <literal>PASCAL</literal> calling convention. So, if we use
<function>strcmp(a,b)</function> with <parameter>a</parameter>
and <parameter>b</parameter> both 32-bit variables
<parameter>b</parameter> would be at <literal>[bp+6]</literal>
@@ -740,7 +741,7 @@ call KERNEL.LSTRLEN
<title>Sample debugging session</title>
<para>
- Let's debug the infamous Word <filename>SHARE.EXE</filename>
+ Let's debug the infamous Word <command>SHARE.EXE</command>
message box:
</para>
<screen>
@@ -810,8 +811,7 @@ call KERNEL.LSTRLEN
OF_CREATE|OF_SHARE_EXCLUSIVE|OF_READWRITE
</screen>
<para>
- This fails, since my <medialabel>C:</medialabel> drive is in
- this case mounted readonly.
+ This fails, since my C: drive is in this case mounted readonly.
</para>
<screen>
|Ret KERNEL.74: OPENFILE() retval=0xffff ret=060f:09d8 ds=0927
@@ -831,7 +831,7 @@ Wine-dbg>
<para>
The code seems to find a writable harddisk and tries to create
a file there. To work around this bug, you can define
- <medialabel>C:</medialabel> as a network drive, which is ignored
+ C: as a network drive, which is ignored
by the code above.
</para>
</sect2>
@@ -861,7 +861,7 @@ winedbg winfile.exe
<para>
This way, you get into <command>winedbg</command>. Now you
can set a breakpoint on any function the program calls in
- the start function and just type <userinput>c</userinput>
+ the <function>start</function> function and just type <command>c</command>
to bypass the eventual calls of Winfile to this function
until you are finally at the place where this function gets
called by the crashing start function. Now you can proceed
@@ -925,8 +925,6 @@ Call USER.1: MESSAGEBOX(0x0000,0x01ff1246 "Runtime error 219 at 0004:1056.",0x00
Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
^^^^
</programlisting>
- </para>
- <para>
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
@@ -949,7 +947,7 @@ Call KERNEL.96: FREELIBRARY(0x031f) ret=01cf:105c ds=01ff
those functions are called very often.
</para>
<para>
- Then do a <userinput>c</userinput> until you are able to
+ Then do a <command>c</command> until you are able to
set this breakpoint without error message.
</para>
</listitem>
@@ -1179,7 +1177,7 @@ winedbg myprog.exe
</para>
<variablelist>
<varlistentry>
- <term>Debugger</term>
+ <term><literal>Debugger</literal></term>
<listitem>
<para>
This is the command line used to launch the debugger
@@ -1197,7 +1195,7 @@ winedbg myprog.exe
</listitem>
</varlistentry>
<varlistentry>
- <term>Auto</term>
+ <term><literal>Auto</literal></term>
<listitem>
<para>
If this value is zero, a message box will ask the
@@ -1363,42 +1361,38 @@ set $BreakAllThreadsStartup = 1
<sect2 id="cfg-dbg-relay">
<title>Configuring +relay behaviour</title>
<para>
- When setting <parameter>WINEDEBUG</parameter> to +relay and debugging,
+ When setting <envar>WINEDEBUG</envar> to <literal>+relay</literal> and debugging,
you might get a lot of output. You can limit the output by
- configuring the value RelayExclude in the registry, located
- under the key:
+ configuring the value <literal>RelayExclude</literal> in the registry, located
+ under the key <literal>[HKCU\\Software\\Wine\\Debug]</literal>
</para>
- <programlisting>
- [HKCU\\Software\\Wine\\Debug]
- </programlisting>
<para>
- Set the value of RelayExclude to a semicolon-separated list of
- calls to exclude. Example:
+ Set the value of <literal>RelayExclude</literal> to a semicolon-separated list of
+ calls to exclude, e.g.
"RtlEnterCriticalSection;RtlLeaveCriticalSection;kernel32.97;kernel32.98".
</para>
<para>
- RelayInclude is an option similar to RelayExclude, except that
- functions listed here will be the only ones included in the output.
- Also see section 3.4.3.5 for more options.
+ <literal>RelayInclude</literal> is an option similar to <literal>RelayExclude</literal>,
+ except that functions listed here will be the only ones included in the output.
</para>
<para>
- If your application runs too slow with +relay to get meaningful
+ If your application runs too slow with <literal>+relay</literal> to get meaningful
output and you're stuck with multi-GB relay log files, but
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 it's output
+ First, run your application for a minute or so, piping its output
to a file on disk:
</para>
- <programlisting>
+ <screen>
WINEDEBUG=+relay wine <replaceable>appname.exe</replaceable> &>relay.log
- </programlisting>
+ </screen>
<para>
Then run this command to see which calls are performed the most:
</para>
- <programlisting>
+ <screen>
awk -F'(' '{print $1}' < relay.log | awk '{print $2}' | sort | uniq -c | sort
- </programlisting>
+ </screen>
<para>
- Exclude the bottom-most calls with RelayExclude after making
+ Exclude the bottom-most calls with <literal>RelayExclude</literal> after making
sure that they are irrelevant, then run your application again.
</para>
</sect2>
@@ -1423,8 +1417,8 @@ set $BreakAllThreadsStartup = 1
<listitem>
<para>
In cast operation, when specifying a structure or an
- union, you must use the <type>struct</type> or
- <type>union</type> keyword (even if your program uses a typedef).
+ union, you must use the <literal>struct</literal> or <literal>union</literal>
+ keyword (even if your program uses a <literal>typedef</literal>).
</para>
</listitem>
</itemizedlist>
@@ -1737,14 +1731,14 @@ set $BreakAllThreadsStartup = 1
</table>
</para>
<para>
- You can use the symbol <emphasis>EntryPoint</emphasis> to stand for
- the entry point of the Dll.
+ You can use the symbol <literal>EntryPoint</literal> to stand for
+ the entry point of the DLL.
</para>
<para>
When setting a break/watch-point by <replaceable>id</replaceable>, if the
symbol cannot be found (for example, the symbol is contained
- in a not yet loaded module), winedbg will recall the name of
- the symbol and will try to set the breakpoint each time a
+ in a not yet loaded module), <command>winedbg</command> will recall
+ the name of the symbol and will try to set the breakpoint each time a
new module is loaded (until it succeeds).
</para>
</sect2>
@@ -1913,14 +1907,14 @@ set $BreakAllThreadsStartup = 1
<tgroup cols="2" align="left">
<tbody>
<row>
- <entry><command>list 123, 234</command></entry>
+ <entry><userinput>list 123, 234</userinput></entry>
<entry>
lists source lines from line 123 up to line 234 in
current file
</entry>
</row>
<row>
- <entry><command>list foo.c:1, 56</command></entry>
+ <entry><userinput>list foo.c:1, 56</userinput></entry>
<entry>
lists source lines from line 1 up to 56 in file
<filename>foo.c</filename>
@@ -2124,15 +2118,35 @@ set $BreakAllThreadsStartup = 1
between <replaceable>count</replaceable> and <replaceable>letter</replaceable>), where
<replaceable>letter</replaceable> can be
<simplelist type="horiz" columns="2">
- <member>s</member><member>an ASCII string</member>
- <member>u</member><member>an Unicode UTF16 string</member>
- <member>i</member><member>instructions (disassemble)</member>
- <member>x</member><member>32-bit unsigned hexadecimal integer</member>
- <member>d</member><member>32-bit signed decimal integer</member>
- <member>w</member><member>16-bit unsigned hexadecimal integer</member>
- <member>c</member><member>character (only printable 0x20-0x7f are actually printed)</member>
- <member>b</member><member>8-bit unsigned hexadecimal integer</member>
- <member>g</member><member>GUID</member>
+ <member>
+ <literal>s</literal></member><member>an ASCII string
+ </member>
+ <member>
+ <literal>u</literal></member><member>a Unicode UTF16 string
+ </member>
+ <member>
+ <literal>i</literal></member><member>instructions (disassemble)
+ </member>
+ <member>
+ <literal>x</literal></member><member>32-bit unsigned hexadecimal
+ integer
+ </member>
+ <member>
+ <literal>d</literal></member><member>32-bit signed decimal integer
+ </member>
+ <member>
+ <literal>w</literal></member><member>16-bit unsigned hexadecimal
+ integer
+ </member>
+ <member>
+ <literal>c</literal></member><member>character (only printable
+ 0x20-0x7f are actually printed)
+ </member>
+ <member>
+ <literal>b</literal></member><member>8-bit unsigned hexadecimal
+ integer
+ </member>
+ <member><literal>g</literal></member><member>GUID</member>
</simplelist>
</para>
</sect2>
@@ -2256,7 +2270,7 @@ set $BreakAllThreadsStartup = 1
<para>
It is possible to turn on and off debug messages as you
are debugging using the set command (only for debug channels
- specified in WINEDEBUG environment variable).
+ specified in <envar>WINEDEBUG</envar> environment variable).
See <xref linkend="debugging"> for more details on debug
channels.
</para>
@@ -2311,8 +2325,8 @@ set $BreakAllThreadsStartup = 1
WineDbg can act as a remote monitor for GDB. This allows to
use all the power of GDB, but while debugging wine and/or
any Win32 application. To enable this mode, just add
- <parameter>--gdb</parameter> to winedbg command line. You'll
- end up on a GDB prompt. You'll have to use the GDB commands
+ <option>--gdb</option> to <command>winedbg</command> command line.
+ You'll end up on a GDB prompt. You'll have to use the GDB commands
(not WineDbg ones).
</para>
@@ -2330,7 +2344,7 @@ set $BreakAllThreadsStartup = 1
<para>
Moreover, it also provides support for the Dwarf II
debug format (which became the default format (instead
- of stabs) in gcc 3.1).
+ of <literal>stabs</literal>) in gcc 3.1).
</para>
</listitem>
</itemizedlist>
@@ -2339,7 +2353,7 @@ set $BreakAllThreadsStartup = 1
<para>
A few Wine extensions available through the monitor command.
<table>
- <title>WineDbg debug channels' management</title>
+ <title>WineDbg debug channels management</title>
<tgroup cols="2" align="left">
<tbody>
<row>
@@ -2365,7 +2379,7 @@ set $BreakAllThreadsStartup = 1
</sect2>
<sect2>
- <title>Graphical frontends to gdb</title>
+ <title>Graphical frontends to <command>gdb</command></title>
<para>
This section will describe how you can debug Wine using the
@@ -2394,18 +2408,18 @@ set $BreakAllThreadsStartup = 1
</listitem>
<listitem>
<para>
- In ddd, use the 'Open File' or 'Open Program' to
- point to the Wine executable.
+ In <command>ddd</command>, use <guimenuitem>Open File</guimenuitem> or
+ <guimenuitem>Open Program</guimenuitem> to point to the Wine executable.
</para>
</listitem>
<listitem>
<para>
- In the output of 1/, there's a line like
+ In the output of above command, there's a line like
<screen>
- target remote localhost:32878
+ target remote localhost:12345
</screen>
- copy that line and paste into ddd command pane (the
- one with the (gdb) prompt)
+ Copy that line and paste into <command>ddd</command> command pane (the
+ one with the <prompt>(gdb)</prompt> prompt)
</para>
</listitem>
</orderedlist>
@@ -2428,15 +2442,15 @@ set $BreakAllThreadsStartup = 1
</listitem>
<listitem>
<para>
- In the output of 1/, there's a line like
+ In the output of above command, there's a line like
<screen>
- target remote localhost:32878
+ target remote localhost:12345
</screen>
Start kdbg with
<screen>
-kdbg -r localhost:32878 wine
+kdbg -r localhost:12345 wine
</screen>
- localhost:32878 is not a fixed value, but has been
+ <literal>localhost:12345</literal> is not a fixed value, but has been
printed in first step. <quote>wine</quote> should also be the full
path to the Wine executable.
</para>
@@ -2458,9 +2472,9 @@ kdbg -r localhost:32878 wine
<para>
You need to attach the unix debugger to the correct unix
process (representing the correct windows thread) (you can
- <quote>guess</quote> it from a <command>ps fax</command> command for example.
+ <quote>guess</quote> it from a <userinput>ps fax</userinput> command for example.
When running the emulator, usually the first two
- <varname>upids</varname> are for the Windows application
+ <varname>upid</varname>s are for the Windows application
running the desktop, the first thread of the application is
generally the third <varname>upid</varname>; when running a
Winelib program, the first thread of the application is
@@ -2483,7 +2497,7 @@ kdbg -r localhost:32878 wine
<listitem>
<para>
<command>gdb</command> supports the multi-threading
- (you need gdb at least 5.0 for that).
+ (you need at least version 5.0 for that).
</para>
</listitem>
</itemizedlist>
@@ -2504,22 +2518,22 @@ kdbg -r localhost:32878 wine
Change into your Wine source dir and enter:
</para>
<screen>
-$ gdb wine
+<prompt>$ </prompt><userinput>gdb wine</userinput>
</screen>
<para>
- Switch to another console and enter <command>ps ax | grep
- wine</command> to find all wine processes. Inside
+ 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>
-(gdb) attach <replaceable>PID</replaceable>
+<prompt>(gdb) </prompt><userinput>attach <replaceable>PID</replaceable></userinput>
</screen>
<para>
with <replaceable>PID</replaceable> being the process ID of one of
the Wine processes. Use
</para>
<screen>
-(gdb) bt
+<prompt>(gdb) </prompt><userinput>bt</userinput>
</screen>
<para>
to get the backtrace of the current Wine process, i.e. the
@@ -2528,26 +2542,26 @@ $ gdb wine
several times:
</para>
<screen>
-(gdb) n
+<prompt>(gdb) </prompt><userinput>n</userinput>
</screen>
<para>
or maybe even
</para>
<screen>
-(gdb) b <replaceable>SomeFunction</replaceable>
+<prompt>(gdb) </prompt><userinput>b <replaceable>SomeFunction</replaceable></userinput>
</screen>
<para>
and
</para>
<screen>
-(gdb) c
+<prompt>(gdb) </prompt><userinput>c</userinput>
</screen>
<para>
to set a breakpoint at a certain function and continue up to
that function. Finally you can enter
</para>
<screen>
-(gdb) detach
+<prompt>(gdb) </prompt><userinput>detach</userinput>
</screen>
<para>
to detach from the Wine process.
@@ -2590,12 +2604,12 @@ $ gdb wine
</row>
<row>
<entry>
- WineDbg supports debug information from stabs
+ WineDbg supports debug information from <literal>stabs</literal>
(standard Unix format) and C, CodeView, <filename>.DBG</filename>
(Microsoft)
</entry>
<entry>
- GDB supports debug information from stabs (standard
+ GDB supports debug information from <literal>stabs</literal> (standard
Unix format) and Dwarf II.
</entry>
</row>
diff --git a/en/winedev-debugging.sgml b/en/winedev-debugging.sgml
index eabec07..21896bb 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:
- <screen>
+ <programlisting>
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 );
- </screen>
+ </programlisting>
</para>
<sect1 id="dbg-classes">
@@ -95,7 +95,7 @@ MESSAGE( "Could not create graphics driver '%s'\n", buffer );
<para>
Each component is assigned a debugging channel. The
identifier of the channel must be a valid C identifier
- (reserved words like <type>int</type> or <type>static</type>
+ (reserved words like <type>int</type> or <literal>static</literal>
are permitted). To use a new channel, simply use it in
your code. It will be picked up automatically by the build process.
</para>
@@ -104,7 +104,7 @@ MESSAGE( "Could not create graphics driver '%s'\n", buffer );
Typically, a file contains code pertaining to only one component,
and as such, there is only one channel to output to. You can declare
a default channel for the file using the
- <symbol>WINE_DEFAULT_DEBUG_CHANNEL()</symbol> macro:
+ <systemitem class="macro">WINE_DEFAULT_DEBUG_CHANNEL()</systemitem> macro:
<programlisting>
#include "wine/debug.h"
@@ -147,9 +147,10 @@ WINE_DECLARE_DEBUG_CHANNEL(zzz);
<para>
To test whether the debugging channel <literal>xxx</literal> is
- enabled, use the <symbol>TRACE_ON</symbol>, <symbol>WARN_ON</symbol>,
- <symbol>FIXME_ON</symbol>, or <symbol>ERR_ON</symbol> macros. For
- example:
+ enabled, use the <systemitem class="macro">TRACE_ON</systemitem>,
+ <systemitem class="macro">WARN_ON</systemitem>,
+ <systemitem class="macro">FIXME_ON</systemitem>, or
+ <systemitem class="macro">ERR_ON</systemitem> macros. For example:
<programlisting>
if(TRACE_ON(atom)){
...blah...
@@ -276,11 +277,11 @@ HANDLE32 WINAPI YourFunc(LPCSTR s)
slowing down installation considerably.
</para>
<para>
- The <parameter>WINEDEBUG</parameter> environment variable
+ The <envar>WINEDEBUG</envar> environment variable
controls the output of the debug messages.
It has the following syntax:
- <parameter>WINEDEBUG=
- <optional><replaceable>yyy</replaceable></optional><replaceable>#</replaceable><replaceable>xxx</replaceable><optional>,<optional><replaceable>yyy1</replaceable></optional><replaceable>#</replaceable><replaceable>xxx1</replaceable></optional>*</parameter>
+ <userinput><envar>WINEDEBUG</envar>=
+ <optional><replaceable>yyy</replaceable></optional><replaceable>#</replaceable><replaceable>xxx</replaceable><optional>,<optional><replaceable>yyy1</replaceable></optional><replaceable>#</replaceable><replaceable>xxx1</replaceable></optional>*</userinput>
</para>
<itemizedlist>
<listitem>
diff --git a/en/winedev-documentation.sgml b/en/winedev-documentation.sgml
index f88ecee..407a228 100644
--- a/en/winedev-documentation.sgml
+++ b/en/winedev-documentation.sgml
@@ -190,7 +190,7 @@
</para>
<para>
- The following text uses the function <emphasis>PathRelativePathToA()</emphasis> from
+ The following text uses the function <function>PathRelativePathToA()</function> from
<filename>SHLWAPI.DLL</filename> as an example. You can find this function in the Wine
source code tree in the file <filename>dlls/shlwapi/path.c</filename>.
</para>
@@ -201,18 +201,18 @@
(and most common type of) comment:
</para>
- <screen>
+ <programlisting>
/*************************************************************************
* PathRelativePathToW [SHLWAPI.@]
*/
- </screen>
+ </programlisting>
<para>
The functions name and the DLL name are obvious. The ordinal number takes one of
- two forms: Either <command>@</command> as in the above, or a number if the export
+ two forms: Either <literal>@</literal> as in the above, or a number if the export
is exported by ordinal. You can see which to use by looking at the DLL
<filename>.spec</filename> file. If the line on which the function is listed begins
- with a number, use it, otherwise use the <command>@</command> symbol, which indicates
+ with a number, use it, otherwise use the <literal>@</literal> symbol, which indicates
that this function is imported only by name.
</para>
@@ -221,11 +221,11 @@
and the DLL/ordinal is free form. Thus the following is equally valid:
</para>
- <screen>
+ <programlisting>
/*************************************************************************
* PathRelativePathToW (SHLWAPI.@)
*/
- </screen>
+ </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>
- <screen>
+ <programlisting>
/*************************************************************************
* PathRelativePathToW [SHLWAPI.@]
*
* Create a relative path from one path to another.
*/
- </screen>
+ </programlisting>
<para>
To be truly useful however we must document the parameters to the function.
@@ -274,7 +274,7 @@
</screen>
<para>
- The parameters section starts with <command>PARAMS</command> on its own line.
+ The parameters section starts with <literal>PARAMS</literal> on its own line.
Each parameter is listed in the order they appear in the functions prototype,
first with the parameters name, followed by its input/output status, followed
by a free form text description of the comment.
@@ -286,8 +286,8 @@
status must be enclosed in square brackets to be recognized, otherwise, or if it
is absent, anything following the parameter name is treated as the parameter
description. This field is case insensitive and can be any of the following:
- <command>[I]</command>, <command>[In]</command>, <command>[O]</command>,
- <command>[Out]</command>, <command>[I/O]</command>, <command>[In/Out]</command>.
+ <literal>[I]</literal>, <literal>[In]</literal>, <literal>[O]</literal>,
+ <literal>[Out]</literal>, <literal>[I/O]</literal>, <literal>[In/Out]</literal>.
</para>
<para>
@@ -299,22 +299,22 @@
<orderedlist>
<listitem><para>
- <command>NOTES</command>. Anything that needs to be noted about the function
+ <literal>NOTES</literal>. Anything that needs to be noted about the function
such as special cases and the effects of input arguments.
</para></listitem>
<listitem><para>
- <command>BUGS</command>. Any bugs in the function that exist <quote>by design</quote>,
+ <literal>BUGS</literal>. Any bugs in the function that exist <quote>by design</quote>,
i.e. those that will not be fixed or exist for compatibility with Windows.
</para></listitem>
<listitem><para>
- <command>TODO</command>. Any unhandled cases or missing functionality in the Wine
+ <literal>TODO</literal>. Any unhandled cases or missing functionality in the Wine
implementation of the function.
</para></listitem>
<listitem><para>
- <command>FIXME</command>. Things that should be updated or addressed in the implementation
+ <literal>FIXME</literal>. Things that should be updated or addressed in the implementation
of the function at some future date (perhaps dependent on other parts of Wine). Note
that if this information is only relevant to Wine developers then it should probably
be placed in the relevant code section instead.
@@ -323,7 +323,7 @@
</para>
<para>
- Following or before the optional sections comes the <command>RETURNS</command> section
+ Following or before the optional sections comes the <literal>RETURNS</literal> section
which describes the return value of the function. This is free form text but should include
what is returned on success as well as possible error return codes. Note that this
section must be present for documentation to be generated for your comment.
@@ -333,7 +333,7 @@
Our final documentation looks like the following:
</para>
- <screen>
+ <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.
*/
- </screen>
+ </programlisting>
</sect2>
<sect2 id="api-docs-advanced">
@@ -379,7 +379,7 @@
</para>
<para>
- Any valid c identifier that ends with <command>()</command> is taken to
+ Any valid C identifier that ends with <literal>()</literal> is taken to
be an API function and is formatted accordingly. When generating documentation,
this text will become a link to that API call, if the output type supports
hyperlinks or their equivalent.
@@ -387,7 +387,8 @@
<para>
Similarly, any interface name starting with a 'I' and followed by the
- words "reference" or "object" become a link to that objects documentation.
+ words <literal>reference</literal> or <literal>object</literal> becomes a link to the
+ documentation of that object.
</para>
<para>
@@ -395,30 +396,30 @@
recommended that you document only the Unicode version and have the Ascii
version refer to the Unicode one, as follows:
</para>
- <screen>
+ <programlisting>
/*************************************************************************
* PathRelativePathToA [SHLWAPI.@]
*
* See PathRelativePathToW.
*/
- </screen>
+ </programlisting>
<para>
Alternately you may use the following form:
</para>
- <screen>
+ <programlisting>
/*************************************************************************
* PathRelativePathToA [SHLWAPI.@]
*
* Unicode version of PathRelativePathToW.
*/
- </screen>
+ </programlisting>
<para>
- You may also use this construct in any other section, such as <command>NOTES</command>.
+ You may also use this construct in any other section, such as <literal>NOTES</literal>.
</para>
<para>
- Any numbers and text in quotes (<command>""</command>) are highlighted.
+ Any numbers and text in quotes (<literal>""</literal>) are highlighted.
</para>
<para>
@@ -433,7 +434,7 @@
</para>
<para>
- Any comment line starting with (<command>"*|"</command>) is treated as raw text and
+ Any comment line starting with '*' or '|' is treated as raw text and
is not pre-processed before being output. This should be used for code listings,
tables and any text that should remain unformatted.
</para>
@@ -443,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>
- <screen>
+ <programlisting>
* RETURNS
* Success: TRUE. Something happens that is documented here.
* Failure: FALSE. The reasons why this call can fail are listed here.
- </screen>
+ </programlisting>
<para>
Any line starting with a '-' is put into a paragraph by itself.
@@ -469,7 +470,7 @@
before the API Guide can be considered truly useful or comprehensive. For example,
COM objects that are available for developers use should be documented, along with
the interfaces that those objects export. Also, it would be helpful to document
- each dll, to provide some structure to the documentation.
+ each DLL, to provide some structure to the documentation.
</para>
<para>
@@ -481,23 +482,23 @@
<para>
These items are generated using the same formatting rules as described earlier. The
only difference is the first line of the comment, which indicates to the generator
- that the documentation is supplemental and does not describe an export from the dll
+ that the documentation is supplemental and does not describe an export from the DLL
being processed.
</para>
<para>
- Lets assume you have implemented a COM interface that you want to document; we'll
- use the name <command>IExample</command> as an example here. Your comment would
+ Let's assume you have implemented a COM interface that you want to document; we'll
+ use the name <classname>IExample</classname> as an example here. Your comment would
look like the following (assuming you are exporting this object from
<filename>EXAMPLE.DLL</filename>):
- <screen>
+ <programlisting>
/*************************************************************************
* IExample {EXAMPLE}
*
* The IExample object provides lots of interesting functionality.
* ...
*/
- </screen>
+ </programlisting>
</para>
<para>
@@ -557,11 +558,11 @@
<para>
Once you have generated the man pages from the source code, running
<command>make install</command> will install them for you. By default they are
- installed in section 3w of the manual, so they don't conflict with any existing
- man page names. So, to read the man page you should use
- <command>man -S 3w <replaceable>name</replaceable></command>. Alternately you can edit
- <filename>/etc/man.config</filename> and add 3w to the list of search paths
- given in the variable <emphasis>MANSECT</emphasis>.
+ installed in section <literal>3w</literal> of the manual, so they don't conflict with any
+ existing man page names. So, to read the man page you should use
+ <userinput>man -S 3w <replaceable>name</replaceable></userinput>. Alternately you can edit
+ <filename>/etc/man.config</filename> and add <literal>3w</literal> to the list of search
+ paths given in the <envar>MANSECT</envar> variable.
</para>
<para>
@@ -598,7 +599,7 @@
The simple answer to that is that SGML allows you
to create multiple formats of a given document from a single
source. Currently it is used to create HTML, PDF, PS
- (PostScript) and Text versions of the Wine books.
+ (PostScript) and text versions of the Wine books.
</para>
</note>
@@ -715,8 +716,8 @@
</para>
</listitem>
</itemizedlist>
- You can also use ghostscript to view the ps format output and
- Adobe Acrobat 4 to view the pdf file.
+ You can also install <command>ghostscript</command> to view the PostScript format
+ output.
</para>
</sect4>
@@ -853,7 +854,7 @@
set the <sgmltag class="attribute">id</sgmltag> attribute
of the <sgmltag class="starttag">book</sgmltag> element to
<quote>mybook</quote>, you would create a start tag like
- this: <programlisting><book id="mybook"></programlisting>
+ this: <programlisting><book id="mybook"></programlisting>
</para>
<para>
Notice that the contents of the attribute are enclosed in
@@ -864,7 +865,7 @@
</para>
<para>
You can also specify more than one attribute in a single
- tag: <programlisting><book id="mybook" status="draft"></programlisting>
+ tag: <programlisting><book id="mybook" status="draft"></programlisting>
</para>
<para>
Another commonly used type of SGML markup is the
@@ -919,16 +920,17 @@
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 V3.1//EN" []> <book> ...
- </book></programlisting>
+ <programlisting><!doctype book PUBLIC "-//OASIS//DTD DocBook V3.1//EN" []>
+<book>
+...
+</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 V3.1//EN" []>
-<article>
+<article>
...
</article></programlisting>
</para>
@@ -1403,7 +1405,7 @@
<term><sgmltag class="starttag">structname</sgmltag></term>
<listitem>
<para>
- The name of a C-language <type>struct</type>
+ The name of a C-language <literal>struct</literal>
declaration, e.g. <structname>sockaddr</structname>.
</para>
</listitem>
@@ -1412,7 +1414,7 @@
<term><sgmltag class="starttag">structfield</sgmltag></term>
<listitem>
<para>
- A field inside a C <type>struct</type>.
+ A field inside a C <literal>struct</literal>.
</para>
</listitem>
</varlistentry>
diff --git a/en/winedev-kernel.sgml b/en/winedev-kernel.sgml
index 864a225..16067f3 100644
--- a/en/winedev-kernel.sgml
+++ b/en/winedev-kernel.sgml
@@ -29,8 +29,8 @@
exist on the periphery such as MSI, the widget library (in
<filename>USER</filename> and <filename>COMCTL32</filename>) etc. The
purpose of this section is to document and explain how Wine starts up
- from the moment the user runs <command>wine
- <replaceable>myprogram.exe</replaceable></command> to the point at which
+ from the moment the user runs <userinput>wine
+ <replaceable>myprogram.exe</replaceable></userinput> to the point at which
<replaceable>myprogram</replaceable> gets control.
</para>
@@ -38,7 +38,7 @@
<title>First Steps</title>
<para>
- The actual wine binary that the user runs does not do very much, in
+ The actual <command>wine</command> binary that the user runs does not do very much, in
fact it is only responsible for checking the threading model in use
(NPTL vs LinuxThreads) and then invoking a new binary which performs
the next stage in the startup sequence. See the beginning of this
@@ -86,7 +86,7 @@
process by using a static binary it's up to us to restart the
process. The bulk of the code in the preloader is about loading
<command>wine</command> and
- <filename>ld-linux.so.2</filename> off disk, linking them together,
+ <command>ld-linux.so.2</command> off disk, linking them together,
then starting the dynamic linking process.
</para>
@@ -255,7 +255,7 @@ ExitProcess( entry( peb ) );
mmap algorithms. Rather than consistently choosing the same addresses
given the same sequence of requests, the kernel will now choose
randomized addresses. Because the Linux dynamic linker
- (<filename>ld-linux.so.2</filename>) loads DSOs into memory by using
+ (<command>ld-linux.so.2</command>) loads DSOs into memory by using
mmap, this means that DSOs are no longer loaded at predictable
addresses, so making it harder to attack software by using buffer
overflows. It also attempts to relocate certain binaries into a
@@ -472,7 +472,7 @@ ExitProcess( entry( peb ) );
a more specific Wine beast. This later form in fact creates two files
for a given executable (say <filename>foo.exe</filename>). The first
one, named <filename>foo</filename> will be a symbolic link to the
- Wine loader (<filename>wine</filename>). The second one, named
+ Wine loader (<command>wine</command>). The second one, named
<filename>foo.exe.so</filename>, is the equivalent of the
<filename>.dll.so</filename> files we've already described for
DLLs. As in Windows, an executable is, among other things, a module
@@ -482,7 +482,7 @@ ExitProcess( entry( peb ) );
</para>
<para>
When starting a Winelib application from the command line (say with
- <command>foo arg1 arg2</command>), the Unix shell will execute
+ <userinput>foo arg1 arg2</userinput>), the Unix shell will execute
<command>foo</command> as a Unix executable. Since this is in fact the
Wine loader, Wine will fire up. However, it will notice that it hasn't
been started as <command>wine</command> but as <command>foo</command>,
@@ -854,9 +854,9 @@ if (res != ERROR_SUCCESS) return res;
<para>
Windows exceptions typically contain more information than the Unix
standard APIs provide. For instance, a
- <constant>STATUS_ACCESS_VIOLATION</constant> exception
- (<constant>0xC0000005</constant>) structure contains the faulting
- address, whereas a standard Unix <constant>SIGSEGV</constant> just
+ <errorname>STATUS_ACCESS_VIOLATION</errorname> exception
+ (<errorcode>0xC0000005</errorcode>) structure contains the faulting
+ address, whereas a standard Unix <literal>SIGSEGV</literal> just
tells the app that it crashed. Usually this information is passed as
an extra parameter to the signal handler, however its location and
contents vary between kernels (BSD, Solaris, etc). This data is
@@ -1000,8 +1000,8 @@ if (res != ERROR_SUCCESS) return res;
</para>
<note>
<para>
- In NT naming convention, <filename>\Global??</filename> can
- also be called <filename>\??</filename> to shorten the
+ In NT naming convention, <literal>\Global??</literal> can
+ also be called <literal>\??</literal> to shorten the
access.
</para>
</note>
@@ -1090,7 +1090,7 @@ if (res != ERROR_SUCCESS) return res;
per drive is still implemented, even on NT. This
mechanism (through environment variables) is implemented
on <command>CMD.EXE</command>, where those variables are
- set when you change directories with the
+ set when you change directories with
<command>cd</command>. Since environment variables are
inherited at process creation, the current directories
settings are inherited by child processes, hence
@@ -1135,7 +1135,7 @@ if (res != ERROR_SUCCESS) return res;
Microsoft allowed paths to be <constant>32,767</constant>
characters long, under the conditions that the path is
expressed in Unicode (no Ansi version), and that the path is
- prefixed with <filename>\\?\</filename>. This convention is
+ prefixed with <literal>\\?\</literal>. This convention is
applicable to any of the cases described above.
</para>
</listitem>
@@ -1259,11 +1259,10 @@ if (res != ERROR_SUCCESS) return res;
</row>
<row>
<entry>Long paths</entry>
- <entry><filename>\\?\...</filename></entry>
+ <entry><literal>\\?\...</literal></entry>
<entry></entry>
<entry>
- With this prefix, paths can take up to
- <constant>32,767</constant> characters, instead of
+ With this prefix, paths can take up to 32,767 characters, instead of
<constant>MAX_PATH</constant> for all the others). Once
the prefix stripped, to be handled like one of the
previous ones, just providing internal buffers large
@@ -1327,8 +1326,8 @@ if (res != ERROR_SUCCESS) return res;
<listitem>
<para>
a rather readable configuration: no need of sophisticated
- tools to read a drive mapping, a <command>ls -l
- $(WINEPREFIX)/dosdevices</command>
+ tools to read a drive mapping, a <userinput>ls -l
+ $(WINEPREFIX)/dosdevices</userinput>
says it all.
</para>
</listitem>
@@ -1590,15 +1589,15 @@ if (res != ERROR_SUCCESS) return res;
</para>
<para>
Just a note about attributes on directories: while we can easily map
- the meaning of Windows <constant>FILE_ATTRIBUTE_READONLY</constant>
+ the meaning of Windows <literal>FILE_ATTRIBUTE_READONLY</literal>
on a file, we cannot do it for a directory. Windows semantics (when
this flag is set) means do not delete the directory, while the
- <constant>w</constant> attribute in Unix means don't write nor
+ <literal>w</literal> attribute in Unix means don't write nor
delete it. Therefore, Wine uses an asymmetric mapping here: if the
directory (in Unix) isn't writable, then Wine reports the
- <constant>FILE_ATTRIBUTE_READONLY</constant> attribute; on the other
+ <literal>FILE_ATTRIBUTE_READONLY</literal> attribute; on the other
way around, when asked to set a directory with
- <constant>FILE_ATTRIBUTE_READONLY</constant> attribute, Wine simply
+ <literal>FILE_ATTRIBUTE_READONLY</literal> attribute, Wine simply
does nothing.
</para>
</sect3>
@@ -1673,7 +1672,7 @@ if (res != ERROR_SUCCESS) return res;
<title>Overlapped I/O</title>
<para>
Windows introduced the notion of overlapped I/O. Basically, it
- just means that an I/O operation (think read / write to start
+ just means that an I/O operation (think read/write to start
with) will not wait until it's completed, but rather return to the
caller as soon as possible, and let the caller handle the wait
operation and determine when the data is ready (for a read
@@ -1848,7 +1847,7 @@ if (res != ERROR_SUCCESS) return res;
<para>
Now that we know which Unix device to open for a given Windows
device, let's cover the operation on it. Those operations can either
- be read / write, IO control (and even others).
+ be read/write, IO control (and even others).
</para>
<para>
Read and write operations are supported on real disks & CDROM
@@ -1983,9 +1982,9 @@ if (res != ERROR_SUCCESS) return res;
system. Two flavors of this scheme are actually implemented:
they vary on the backend for the
<command>wineconsole</command>. The first one, dubbed
- <constant>user</constant>, creates a real GUI window
+ <literal>user</literal>, creates a real GUI window
(hence the USER name) and renders the console in this window.
- The second one uses the <filename>(n)curses</filename> library
+ The second one uses the <literal>(n)curses</literal> library
to take full control of an existing Unix console; of course,
interaction with other Unix programs will not be as smooth as
the first solution.
@@ -2004,10 +2003,10 @@ if (res != ERROR_SUCCESS) return res;
<entry>Function</entry>
<entry>Bare streams</entry>
<entry>
- <command>Wineconsole</command> & user backend
+ <command>Wineconsole</command> with <literal>user</literal> backend
</entry>
<entry>
- <command>Wineconsole</command> & curses backend
+ <command>Wineconsole</command> with <literal>curses</literal> backend
</entry>
</row>
</thead>
@@ -2098,20 +2097,24 @@ if (res != ERROR_SUCCESS) return res;
</row>
<row>
<entry>
- Signaling (in particular, Ctrl-C handling)
- </entry>
- <entry>
- Nothing is done, which means that Ctrl-C will generate (as
- usual) a <constant>SIGINT</constant> which will terminate
+ Signaling (in particular,
+ <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> handling)
+ </entry>
+ <entry>
+ Nothing is done, which means that
+ <keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> will generate
+ (as usual) a <literal>SIGINT</literal> which will terminate
the program.
</entry>
<entry>
- Partly supported (Ctrl-C behaves as expected, however the
- other Win32 CUI signaling isn't properly implemented).
+ Partly supported
+ (<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> behaves as
+ expected, however the other Win32 CUI signaling isn't properly implemented).
</entry>
<entry>
- Partly supported (Ctrl-C behaves as expected, however the
- other Win32 CUI signaling isn't properly implemented).
+ Partly supported
+ (<keycombo><keycap>Ctrl</keycap><keycap>C</keycap></keycombo> behaves as
+ expected, however the other Win32 CUI signaling isn't properly implemented).
</entry>
</row>
</tbody>
diff --git a/en/winedev-multimedia.sgml b/en/winedev-multimedia.sgml
index ea6cb8c..5282cad 100644
--- a/en/winedev-multimedia.sgml
+++ b/en/winedev-multimedia.sgml
@@ -340,13 +340,13 @@ Kernel space | Client applications
<para>
Wave mapper driver implementation can be found in
- <filename class="directory">dlls/msacm32.drv/</filename> directory. This
+ <filename class="directory">dlls/msacm32.drv</filename> directory. This
driver heavily relies on msacm DLL found in
<filename class="directory">dlls/msacm32</filename>.
This DLL loads ACM
drivers which provide the conversion to PCM format (which is
- normally supported by low level drivers). A Law, uLaw,
- ADPCM, MP3... fit into the category of non PCM formats.
+ normally supported by low level drivers). A-Law, μLaw,
+ ADPCM, MP3... fit into the category of non PCM formats.
</para>
</sect2>
@@ -364,7 +364,7 @@ Kernel space | Client applications
<para>
A built-in MIDI mapper can be found in
- <filename class="directory">dlls/midimap/</filename>. It partly provides
+ <filename class="directory">dlls/midimap</filename>. It partly provides
the same functionality as the Windows one. It allows to
pick up destination channels: you can map a given channel to
a specific playback device channel (see the configuration
@@ -403,7 +403,7 @@ Kernel space | Client applications
<entry>CdAudio</entry>
<entry>mcicda</entry>
<entry>MCI interface to a CD audio player</entry>
- <entry><filename class="directory">dlls/mcicda/</filename></entry>
+ <entry><filename class="directory">dlls/mcicda</filename></entry>
<entry>
Relies on NTDLL CdRom raw interface (through
<function>DeviceIoControl</function>).
@@ -415,21 +415,21 @@ Kernel space | Client applications
<entry>
MCI interface for wave playback and record
</entry>
- <entry><filename class="directory">dlls/mciwave/</filename></entry>
+ <entry><filename class="directory">dlls/mciwave</filename></entry>
<entry>It uses the low level audio API.</entry>
</row>
<row>
<entry>Sequencer</entry>
<entry>mciseq</entry>
<entry>Midi Sequencer (playback)</entry>
- <entry><filename class="directory">dlls/mciseq/</filename></entry>
+ <entry><filename class="directory">dlls/mciseq</filename></entry>
<entry>It uses the low level midi APIs</entry>
</row>
<row>
<entry>AviVideo</entry>
<entry>mciavi32</entry>
<entry>AVI playback and record</entry>
- <entry><filename class="directory">dlls/mciavi32/</filename></entry>
+ <entry><filename class="directory">dlls/mciavi32</filename></entry>
<entry>
It rather heavily relies on msvfw32 DLL to work.
</entry>
@@ -509,7 +509,7 @@ Kernel space | Client applications
</sect1>
<sect1 id="msacm">
- <title>MS ACM Dlls</title>
+ <title>MS ACM DLLs</title>
<sect2>
<title>Contents</title>
@@ -584,18 +584,19 @@ Kernel space | Client applications
<screen>
Software\Microsoft\AudioCompressionManager\DriverCache\<replaceable>driver_name</replaceable>
</screen>
- , are kept for values:
+ are kept for values:
<itemizedlist>
<listitem>
<para>
<literal>aFormatTagCache</literal> which
- contains an array of <literal>DWORD</literal>. There
- are two <literal>DWORD</literal>s per <literal>cFormatTags</literal>
- entry. The first <literal>DWORD</literal> contains a
+ contains an array of <type>DWORD</type>. There
+ are two <type>DWORD</type>s per <literal>cFormatTags</literal>
+ entry. The first <type>DWORD</type> contains a
format tag value, and the second the associated
- maximum size for a <literal>WAVEFORMATEX</literal> structure.
- (Fields <literal>dwFormatTag</literal> and <literal>cbFormatSize</literal> from
- ACMFORMATDETAILS)
+ maximum size for a <structname>WAVEFORMATEX</structname> structure.
+ (Fields <structfield>dwFormatTag</structfield> and
+ <structfield>cbFormatSize</structfield> from
+ <structname>ACMFORMATDETAILS</structname>)
</para>
</listitem>
<listitem>
@@ -630,7 +631,7 @@ Kernel space | Client applications
</sect1>
<sect1 id="msvfw32">
- <title>MS Video Dlls</title>
+ <title>MS Video DLLs</title>
<sect2>
<title>Contents</title>
@@ -739,7 +740,7 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
time. It will setup correctly the MCI drivers configuration
(as well as the wave and MIDI mappers). As the low-level
drivers depend on hardware, their setup will be handled by
- <filename>winecfg</filename>.
+ <command>winecfg</command>.
</para>
<table frame="all">
@@ -751,7 +752,7 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
<entry>Read from NT registry</entry>
<entry>Read from <filename>system.ini</filename></entry>
<entry>Setup by <filename>wine.inf</filename></entry>
- <entry>Setup by <filename>winecfg</filename></entry>
+ <entry>Setup by <command>winecfg</command></entry>
</row>
</thead>
<tbody>
@@ -819,13 +820,13 @@ HKLM\Software\Microsoft\Windows NT\CurrentVersion
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"
+ "cdaudio"="mcicda.drv"
+ "sequencer"="mciseq.drv"
+ "waveaudio"="mciwave.drv"
+ "avivideo"="mciavi.drv"
+ "videodisc"="mcipionr.drv"
+ "vcr"="mcivisca.drv"
+ "MPEGVideo"="mciqtz.drv"
</screen>
</para>
</sect2>
diff --git a/en/winedev-opengl.sgml b/en/winedev-opengl.sgml
index ff173d0..c74cc2c 100644
--- a/en/winedev-opengl.sgml
+++ b/en/winedev-opengl.sgml
@@ -74,10 +74,10 @@
</sect2>
<sect2>
- <title>glXGetProcAddressARB function</title>
+ <title><function>glXGetProcAddressARB</function> function</title>
<para>
- The core of Wine's OpenGL implementation (at least for all
+ The core of Wine OpenGL implementation (at least for all
extensions) is the <function>glXGetProcAddressARB</function>
function. Your OpenGL library needs to have this function
defined for Wine to be able to support OpenGL.
@@ -105,9 +105,9 @@
</listitem>
<listitem>
<para>
- the calling convention between Windows (the 'Pascal'
- convention or 'stdcall') is different from the one used on
- Linux (the 'C' convention or 'cdecl'). This means that
+ the calling convention between Windows (the <literal>Pascal</literal>
+ convention or <literal>stdcall</literal>) is different from the one used on
+ Linux (the C convention or <literal>cdecl</literal>). This means that
each call to an OpenGL function must be <quote>translated</quote> and
cannot be used directly by the Windows program.
</para>
@@ -249,7 +249,7 @@ Please report (lionel.ulmer at free.fr) !
<function>glSelectTextureSGIS</function> as used by
Quake 2 (and apparently also by old versions of Half
Life). If documentation can be found on these functions,
- they can be added to Wine's extension set.
+ they can be added to Wine extension set.
</para>
</listitem>
</orderedlist>
diff --git a/en/winedev-otherdebug.sgml b/en/winedev-otherdebug.sgml
index b1421ed..3bdcb74 100644
--- a/en/winedev-otherdebug.sgml
+++ b/en/winedev-otherdebug.sgml
@@ -21,7 +21,7 @@
<para>
In the <literal>stdcall</literal> calling convention, arguments are
pushed onto the stack right-to-left. For example, the C call
- <function>myfunction(40, 20, 70, 30);</function> is expressed in
+ <userinput>myfunction(40, 20, 70, 30);</userinput> is expressed in
Intel assembly as:
<screen>
push 30
@@ -160,7 +160,7 @@ git bisect bad wine-1.1.44
</para>
<para>
If you have exact date/time instead of a release you will need
- to use sha1 IDs from <filename>git log</filename>.
+ to use sha1 IDs from <command>git log</command>.
</para>
</listitem>
<listitem>
@@ -218,19 +218,19 @@ git bisect reset
Deciding what code should be tested next can be a difficult
decision. And in any given project, there is always code that
isn't tested where bugs could be lurking. This section goes
- over how to identify these sections using a tool called gcov.
+ over how to identify these sections using a tool called <command>gcov</command>.
</para>
<para>
- To use gcov on wine, do the following:
+ To use <command>gcov</command> on wine, do the following:
</para>
<orderedlist>
<listitem>
<para>
In order to activate code coverage in the wine source code,
when running <command>make</command> set
- <literal>EXTRACFLAGS</literal> and <literal>LDFLAGS</literal>
- like so
- <command>make EXTRACFLAGS=--coverage LDFLAGS=--coverage</command>.
+ <varname>EXTRACFLAGS</varname> and <varname>LDFLAGS</varname>
+ like so:
+ <userinput>make EXTRACFLAGS=--coverage LDFLAGS=--coverage</userinput>.
Note that this can be done at any directory level. Since compile
and run time are significantly increased by these flags, you
may want to only use these flags inside a given dll directory.
@@ -243,13 +243,13 @@ git bisect reset
</listitem>
<listitem>
<para>
- Run gcov on the file which you would like to know more
+ Run <command>gcov</command> on the file which you would like to know more
about code coverage.
</para>
</listitem>
</orderedlist>
<para>
- The following is an example situation when using gcov to
+ The following is an example situation when using <command>gcov</command> to
determine the coverage of a file could be helpful. We'll use
the <filename>dlls/advapi32/registry.c</filename> file.
At one time the code in this file was not fully tested (as it
@@ -264,7 +264,7 @@ if (name && name[0]) /* need to create the subkey */
</screen>
Currently there are a few tests written to test this function.
However, these tests don't check that everything is correct.
- Using gcov and directed tests, we can validate the correctness
+ 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>
@@ -289,7 +289,7 @@ less registry.c.gcov
actual text of the line. Note: If a line is optimized out by
the compiler, it will appear as if it was never run.
Line 1275 is never executed, most likely because
- <constant>"name"</constant> is never passed to the function.
+ <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:
<screen>
diff --git a/en/winedev-testing.sgml b/en/winedev-testing.sgml
index bce30e6..c6e00ab 100644
--- a/en/winedev-testing.sgml
+++ b/en/winedev-testing.sgml
@@ -4,7 +4,7 @@
<sect1 id="testing-intro">
<title>Introduction</title>
<para>
- The Windows API follows no standard, it is itself a de facto standard,
+ The Windows API follows no standard, it is itself a <emphasis>de facto</emphasis> standard,
and deviations from that standard, even small ones, often cause
applications to crash or misbehave in some way.
</para>
@@ -96,11 +96,11 @@
<title>What to test for?</title>
<para>
The first thing to test for is the documented behavior of APIs
- and such as CreateFile. For instance one can create a file using a
+ and such as <function>CreateFile</function>. For instance one can create a file using a
long pathname, check that the behavior is correct when the file
already exists, try to open the file using the corresponding short
pathname, convert the filename to Unicode and try to open it using
- CreateFileW, and all other things which are documented and that
+ <function>CreateFileW</function>, and all other things which are documented and that
applications rely on.
</para>
<para>
@@ -152,8 +152,8 @@
run the tests contained in the <filename>thread.c</filename> file of the
kernel library, you would do:
<screen>
-<prompt>$ </prompt>cd dlls/kernel32/tests
-<prompt>$ </prompt>make thread.ok
+<prompt>$ </prompt><userinput>cd dlls/kernel32/tests</userinput>
+<prompt>$ </prompt><userinput>make thread.ok</userinput>
</screen>
</para>
<para>
@@ -167,15 +167,15 @@
You can also run tests manually using a command similar to the
following:
<screen>
-<prompt>$ </prompt>../../../tools/runtest -q -M kernel32.dll -p kernel32_test.exe.so thread.c
-<prompt>$ </prompt>../../../tools/runtest -P wine -p kernel32_test.exe.so thread.c
-thread.c: 86 tests executed, 5 marked as todo, 0 failures.
+<prompt>$ </prompt><userinput>../../../tools/runtest -q -M kernel32.dll -p kernel32_test.exe.so thread.c</userinput>
+<prompt>$ </prompt><userinput>../../../tools/runtest -P wine -p kernel32_test.exe.so thread.c</userinput>
+<computeroutput>thread.c: 86 tests executed, 5 marked as todo, 0 failures.</computeroutput>
</screen>
- The '-P wine' option defines the platform that is currently being
- tested and is used in conjunction with the 'todo' statements (see
- below). Remove the '-q' option if you want the testing framework
+ The <option>-P</option> option defines the platform that is currently being
+ tested and is used in conjunction with the <literal>todo</literal> statements (see
+ below). Remove the <option>-q</option> option if you want the testing framework
to report statistics about the number of successful and failed tests.
- Run <command>runtest -h</command> for more details.
+ Run <userinput>runtest -h</userinput> for more details.
</para>
</sect1>
@@ -195,7 +195,7 @@ thread.c: 86 tests executed, 5 marked as todo, 0 failures.
The following step should probably work on any deb based system.
</para>
<para>
- Run <command>apt-get install mingw32</command>.
+ Run <userinput>apt-get install mingw32</userinput>.
</para>
</sect3>
<sect3>
@@ -206,7 +206,7 @@ thread.c: 86 tests executed, 5 marked as todo, 0 failures.
The following step should probably work on any rpm based system.
</para>
<para>
- Run <command>yum install mingw32-gcc</command>.
+ Run <userinput>yum install mingw32-gcc</userinput>.
</para>
</sect3>
<sect3>
@@ -260,14 +260,13 @@ thread.c: 86 tests executed, 5 marked as todo, 0 failures.
<itemizedlist>
<listitem><para>
If you are using Visual Studio 6, make sure you have the
- "processor pack" from
- <ulink url="http://msdn.microsoft.com/vstudio/downloads/tools/ppack/default.aspx"></ulink>.
- The processor pack fixes <emphasis>"error C2520: conversion from
- unsigned __int64 to double not implemented, use signed __int64"</emphasis>.
- However note that the "processor pack" is incompatible with
+ <ulink url="http://msdn.microsoft.com/vstudio/downloads/tools/ppack/default.aspx">processor pack</ulink>.
+ The processor pack fixes <emphasis>error C2520: conversion from
+ unsigned __int64 to double not implemented, use signed __int64</emphasis>.
+ However note that the processor pack is incompatible with
Visual Studio 6.0 Standard Edition, and with the Visual Studio 6
Service Pack 6. If you are using Visual Studio 7 or greater you
- do not need the processor pack. In either case it is recommended
+ don't need it. In either case it is recommended
to use the most recent compatible Visual Studio
<ulink url="http://msdn.microsoft.com/vstudio/downloads/updates/sp/">service pack</ulink>.
If are using Visual Studio Express and you need specific libraries like
@@ -282,11 +281,11 @@ Kit</ulink>.
get the Wine sources
</para></listitem>
<listitem><para>
- Run msvcmaker to generate Visual C++ project files for the tests.
- 'msvcmaker' is a perl script so you may be able to run it on
+ Run <command>msvcmaker</command> to generate Visual C++ project files for the tests.
+ <command>msvcmaker</command> is a perl script so you may be able to run it on
Windows.
<screen>
-<prompt>$ </prompt>./tools/winapi/msvcmaker --no-wine
+<prompt>$ </prompt><userinput>./tools/winapi/msvcmaker --no-wine</userinput>
</screen>
</para></listitem>
<listitem><para>
@@ -309,33 +308,34 @@ Kit</ulink>.
as well as the latest <ulink url="http://msdn.microsoft.com/library/default.asp?url=/downloads/list/directx.asp">DirectX SDK</ulink>.
Then, <ulink url="http://msdn.microsoft.com/library/default.asp?url=/library/EN-US/sdkintro/sdkintro/installing_the_platform_sdk_with_visual_studio.asp">configure Visual Studio</ulink>
to use these SDK headers and libraries. Alternately you could go
- to the <menuchoice><guimenu>Project</guimenu> <guimenu>Settings...</guimenu></menuchoice>
+ to the <menuchoice><guimenu>Project</guimenu> <guimenuitem>Settings...</guimenuitem></menuchoice>
menu and modify the settings appropriately, but you would then
- have to redo this whenever you rerun msvcmaker.
+ have to redo this whenever you rerun <command>msvcmaker</command>.
</para></listitem>
<listitem><para>
- Open the <menuchoice><guimenu>Build</guimenu> <guimenu>Batch
- build...</guimenu></menuchoice> menu and select the tests and build configurations
+ Open the <menuchoice><guimenu>Build</guimenu> <guimenuitem>Batch
+ build...</guimenuitem></menuchoice> menu and select the tests and build configurations
you want to build. Then click on <guibutton>Build</guibutton>.
</para></listitem>
<listitem><para>
To run a specific test from Visual C++, go to
- <menuchoice><guimenu>Project</guimenu> <guimenu>Settings...</guimenu></menuchoice>. There
+ <menuchoice><guimenu>Project</guimenu>
+ <guimenuitem>Settings...</guimenuitem></menuchoice>. There
select that test's project and build configuration and go to the
<guilabel>Debug</guilabel> tab. There type the name of the specific test
- to run (e.g. 'thread') in the <guilabel>Program arguments</guilabel>
+ to run (e.g. <literal>thread</literal>) in the <guilabel>Program arguments</guilabel>
field. Validate your change by clicking on <guibutton>Ok</guibutton> and
start the test by clicking the red exclamation mark (or hitting
- 'F5' or any other usual method).
+ <keycap>F5</keycap> or any other usual method).
</para></listitem>
<listitem><para>
You can also run the tests from the command line. You will find
them in either <filename class="directory">Output\Win32_Wine_Headers</filename> or
<filename class="directory">Output\Win32_MSVC_Headers</filename> depending on the build
- method. So to run the kernel 'path' tests you would do:
+ method. So to run the kernel <literal>path</literal> tests you would do:
<screen>
-<prompt>C:\></prompt>cd dlls\kernel\tests\Output\Win32_MSVC_Headers
-<prompt>C:\wine\dlls\kernel\tests\Output\Win32_MSVC_Headers></prompt> kernel32_test path
+<prompt>C:\> </prompt><userinput>cd dlls\kernel\tests\Output\Win32_MSVC_Headers</userinput>
+<prompt>C:\wine\dlls\kernel\tests\Output\Win32_MSVC_Headers> </prompt><userinput>kernel32_test path</userinput>
</screen>
</para></listitem>
</itemizedlist>
@@ -347,8 +347,8 @@ Kit</ulink>.
cross-compiler. See the section above called <quote>Setup of the MinGW
cross-compiling environment</quote> for instructions on how to set things up.
When you have a MinGW environment installed all you need to do is rerun
- configure and it should detect the MinGW compiler and tools. Then run
- 'make crosstest' to start building the tests.
+ configure and it should detect the MinGW compiler and tools. Then run
+ <command>make crosstest</command> to start building the tests.
</para>
</sect2>
<sect2>
@@ -373,7 +373,7 @@ Kit</ulink>.
<listitem><para>
Copy some existing test from the Wine source tree, or
create your test program (say, <filename>mytest.c</filename>) using Notepad,
- being sure to begin it with <function>#include <wine/test.h></function>
+ being sure to begin it with <userinput>#include <wine/test.h></userinput>
following the usual Wine test style.
</para></listitem>
<listitem><para>
@@ -411,7 +411,7 @@ Kit</ulink>.
</para>
<para>
A new test file will look something like the following:
-<screen>
+<programlisting>
#include <wine/test.h>
#include <winbase.h>
@@ -423,13 +423,14 @@ START_TEST(paths)
* there
*/
}
-</screen>
+</programlisting>
</para>
<para>
- The test entry point is the START_TEST section. This is where
+ The test entry point is the <literal>START_TEST</literal> section. This is where
execution will start. You can put all your tests in that section but
it may be better to split related checks in functions you will call
- from the START_TEST section. The parameter to START_TEST must match
+ from the <literal>START_TEST</literal> section. The parameter to
+ <literal>START_TEST</literal> must match
the name of the C file. So in the above example the C file would be
called <filename>paths.c</filename>.
</para>
@@ -442,23 +443,23 @@ START_TEST(paths)
</para>
<para>
You can use <function>trace</function> to print informational messages. Note
- that these messages will only be printed if 'runtest -v' is being used.
-<screen>
+ that these messages will only be printed if <userinput>runtest -v</userinput> is being used.
+<programlisting>
trace("testing GlobalAddAtomA\n");
trace("foo=%d\n",foo);
-</screen>
+</programlisting>
</para>
<para>
Then just call functions and use <function>ok</function> to make sure that
they behaved as expected:
-<screen>
+<programlisting>
ATOM atom = GlobalAddAtomA( "foobar" );
ok( GlobalFindAtomA( "foobar" ) == atom, "could not find atom foobar\n" );
ok( GlobalFindAtomA( "FOOBAR" ) == atom, "could not find atom FOOBAR\n" );
-</screen>
+</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
- printf-compatible format string which is displayed in case the test
+ <function>printf</function>-compatible format string which is displayed in case the test
failed, and the following optional parameters depend on the format
string.
</para>
@@ -487,10 +488,10 @@ START_TEST(paths)
<para>
So how do you write a good error message? Let's start with an example
of a bad error message:
-<screen>
+<programlisting>
ok(GetThreadPriorityBoost(curthread,&disabled)!=0,
"GetThreadPriorityBoost Failed\n");
-</screen>
+</programlisting>
This will yield:
<screen>
thread.c:123: Test failed: GetThreadPriorityBoost Failed
@@ -505,13 +506,13 @@ thread.c:123: Test failed: GetThreadPriorityBoost Failed
</para>
<para>
Let's look at how to rewrite it:
-<screen>
+<programlisting>
BOOL rc;
-...
+ ...
rc=GetThreadPriorityBoost(curthread,&disabled);
ok(rc!=0 && disabled==0,"rc=%d error=%ld disabled=%d\n",
rc,GetLastError(),disabled);
-</screen>
+</programlisting>
This will yield:
<screen>
thread.c:123: Test failed: rc=0 error=120 disabled=0
@@ -519,10 +520,11 @@ thread.c:123: Test failed: rc=0 error=120 disabled=0
</para>
<para>
When receiving such a message, one would check the source, see that
- it's a call to GetThreadPriorityBoost, that the test failed not
+ it's a call to <function>GetThreadPriorityBoost</function>, that the test failed not
because the API returned the wrong value, but because it returned an
- error code. Furthermore we see that GetLastError() returned 120 which
- <filename>winerror.h</filename> defines as ERROR_CALL_NOT_IMPLEMENTED. So the source of
+ error code. Furthermore we see that <function>GetLastError()</function> returned
+ <errorcode>120</errorcode> which <filename>winerror.h</filename> defines as
+ <errorname>ERROR_CALL_NOT_IMPLEMENTED</errorname>. So the source of
the problem is obvious: this Windows platform (here Windows 98) does
not support this API and thus the test must be modified to detect
such a condition and skip the test.
@@ -539,8 +541,8 @@ thread.c:123: Test failed: rc=0 error=120 disabled=0
It may also be a good idea to dump items that may be hard to retrieve
from the source, like the expected value in a test if it is the
result of an earlier computation, or comes from a large array of test
- values (e.g. index 112 of _pTestStrA in <filename>vartest.c</filename>). In that respect,
- for some tests you may want to define a macro such as the following:
+ values (e.g. index 112 of <varname>_pTestStrA</varname> in <filename>vartest.c</filename>).
+ In that respect, for some tests you may want to define a macro such as the following:
<screen>
#define eq(received, expected, label, type) \
ok((received) == (expected), "%s: got " type " instead of " type "\n", (label),(received),(expected))
@@ -567,12 +569,12 @@ thread.c:123: Test failed: rc=0 error=120 disabled=0
groups of checks can be declared as expected to fail on some of them.
In the most common case, one would declare a group of tests as
expected to fail in Wine. To do so, use the following construct:
-<screen>
+<programlisting>
todo_wine {
SetLastError( 0xdeadbeef );
ok( GlobalAddAtomA(0) == 0 && GetLastError() == 0xdeadbeef, "failed to add atom 0\n" );
}
-</screen>
+</programlisting>
On Windows the above check would be performed normally, but on Wine it
would be expected to fail, and not cause the failure of the whole
test. However. If that check were to succeed in Wine, it would
@@ -592,16 +594,16 @@ todo_wine {
So, if an API returns a different error code on Windows 9x and
Windows NT, your check should just verify that Wine returns one or
the other:
-<screen>
+<programlisting>
ok ( GetLastError() == WIN9X_ERROR || GetLastError() == NT_ERROR, ...);
-</screen>
+</programlisting>
</para>
<para>
If an API is only present on some Windows platforms, then use
- LoadLibrary and GetProcAddress to check if it is implemented and
- invoke it. Remember, tests must run on all Windows platforms.
+ <function>LoadLibrary</function> and <function>GetProcAddress</function> to check if it is
+ implemented and invoke it. Remember, tests must run on all Windows platforms.
Similarly, conformance tests should not try to correlate the Windows
- version returned by GetVersion with whether given APIs are
+ version returned by <function>GetVersion</function> with whether given APIs are
implemented or not. Again, the goal of Wine is to run Windows
applications (which do not do such checks), and not be a clone of a
specific Windows version.
diff --git a/en/winedev-windowing.sgml b/en/winedev-windowing.sgml
index 7e666ea..6effe48 100644
--- a/en/winedev-windowing.sgml
+++ b/en/winedev-windowing.sgml
@@ -286,9 +286,9 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
found to be relevant:
</para>
<blockquote>
- <attribution>by David Charlap</attribution>
+ <attribution>David Charlap</attribution>
<para>
- " Here's the problem in a nutshell, and there is no
+ Here's the problem in a nutshell, and there is no
good solution. Every possible solution creates a
different problem.
</para>
@@ -431,7 +431,7 @@ child1->popup->child2->child3->wnd1->child4->wnd2->desktop.
The OS/2 solution's problem is that nothing happens
until you try to change window focus, and then wait
for the timeout. Until then, the bad app is not
- detected and nothing is done."
+ detected and nothing is done.
</para>
</blockquote>
</listitem>
@@ -623,7 +623,7 @@ static const char main_key_NO[MAIN_LEN][4] =
</para-->
<para>
After you have written such a table, you need to add it to the
- <function>main_key_tab[]</function> layout index table. This
+ <varname>main_key_tab[]</varname> layout index table. This
will look like this:
</para>
<programlisting>
--
1.8.4
More information about the wine-patches
mailing list