[docs] winelib: Assorted formatting & tagging fixes
Frédéric Delanoy
frederic.delanoy at gmail.com
Fri Aug 2 03:39:56 CDT 2013
A couple typos as well.
---
en/winelib-bindlls.sgml | 85 +++++++++++++++++++-----------------
en/winelib-intro.sgml | 107 +++++++++++++++++++++++-----------------------
en/winelib-mfc.sgml | 10 ++---
en/winelib-porting.sgml | 24 +++++------
en/winelib-toolkit.sgml | 111 +++++++++++++++++++++++++-----------------------
5 files changed, 175 insertions(+), 162 deletions(-)
diff --git a/en/winelib-bindlls.sgml b/en/winelib-bindlls.sgml
index 304a3fe..9978bd5 100644
--- a/en/winelib-bindlls.sgml
+++ b/en/winelib-bindlls.sgml
@@ -36,13 +36,13 @@
interface in the same format as a DLL (primarily what functions it
exports). Also you will want to write a small wrapper around the
library. You combine these to form a Wine built-in DLL that links to the
- Linux library. Then you modify the DllOverrides in the wine config
- file to ensure that this new built-in DLL is called rather than any
+ Linux library. Then you modify the <literal>DllOverrides</literal> in the
+ wine configuration to ensure that this new built-in DLL is called rather than any
windows version.
</para>
<para>
In this section we will look at two examples. The first example is
- extremely simple and leads into the subject in "baby steps". The
+ extremely simple and leads into the subject in <quote>baby steps</quote>. The
second example is the ODBC interface proxy in Wine. The files to which
we will refer for the ODBC example are currently in the
<filename class="directory">dlls/odbc32</filename> directory of the
@@ -77,7 +77,7 @@ signed short MyLinuxFunc (unsigned short a, void *b, void *c,
<para>
Start by writing the spec file. This file will describe the interface
as if it were a DLL. See elsewhere for the details of the format of
- a spec file (e.g. man winebuild).
+ a spec file (e.g. <userinput>man winebuild</userinput>).
</para>
<para>
In the simple example we want a Wine built-in DLL that corresponds to
@@ -114,11 +114,12 @@ signed short MyLinuxFunc (unsigned short a, void *b, void *c,
<title id="bindlls-wrapper.title">Writing the wrapper</title>
<para>
Firstly we will look at the simple example. The main complication of
- this case is the slightly different argument lists. The f parameter
- does not have to be passed to the Linux function and the d parameter
- (theoretically) has to be converted between
- <literal>unsigned long *i</literal> and <literal>unsigned short *</literal>.
- Doing this ensures that the "high" bits of the returned value are set
+ this case is the slightly different argument lists. The <parameter
+ class="function">f</parameter> parameter does not have to be passed to
+ the Linux function and the <parameter class="function">d</parameter> parameter
+ (theoretically) has to be converted between <type>unsigned long *</type> and
+ <type>unsigned short *</type>.
+ Doing this ensures that the high bits of the returned value are set
correctly. Also unlike with the ODBC example we will link directly to
the Linux Shared Library.
<programlisting>
@@ -127,25 +128,25 @@ signed short MyLinuxFunc (unsigned short a, void *b, void *c,
*
* Copyright (c) The copyright holder.
*
- * Basic Wine wrapper for the Linux <3rd party library> so that it can be
- * used by <the application>
+ * Basic Wine wrapper for the Linux <replaceable>3rd party library</replaceable> so that it can be
+ * used by <replaceable>the application</replaceable>
*
- * Currently this file makes no attempt to be a full wrapper for the <3rd
- * party library>; it only exports enough for our own use.
+ * Currently this file makes no attempt to be a full wrapper for the <replaceable>3rd
+ * party library</replaceable>; it only exports enough for our own use.
*
* Note that this is a Unix file; please don't go converting it to DOS format
* (e.g. converting line feeds to Carriage return/Line feed).
*
* This file should be built in a Wine environment as a Winelib library,
- * linked to the Linux <3rd party> libraries (currently libxxxx.so and
+ * linked to the Linux <replaceable>3rd party</replaceable> libraries (currently libxxxx.so and
* libyyyy.so)
*/
-#include < <3rd party linux header> >
+#include <<replaceable>3rd party linux header</replaceable>>
#include <windef.h> /* Part of the Wine header files */
/* This declaration is as defined in the spec file. It is deliberately not
- * specified in terms of <3rd party> types since we are messing about here
+ * specified in terms of <replaceable>3rd party</replaceable> types since we are messing about here
* between two operating systems (making it look like a Windows thing when
* actually it is a Linux thing). In this way the compiler will point out any
* inconsistencies.
@@ -158,7 +159,7 @@ signed short WINAPI MyProxyWinFunc (unsigned short a, void *b, void *c,
signed short ret;
d1 = (unsigned short) *d;
- ret = <3rd party linux function> (a, b, c, &d1, e, g, h);
+ ret = <replaceable>3rd party linux function</replaceable> (a, b, c, &d1, e, g, h);
*d = d1;
return ret;
@@ -169,7 +170,7 @@ signed short WINAPI MyProxyWinFunc (unsigned short a, void *b, void *c,
</para>
<para>
For a more extensive case we can use the ODBC example. This is
- implemented as a header file
+ implemented as a header file
(<filename class="headerfile">proxyodbc.h</filename>) and the actual
C source file (<filename>proxyodbc.c</filename>). Although the file
is quite long it is extremely simple in structure.
@@ -191,44 +192,48 @@ signed short WINAPI MyProxyWinFunc (unsigned short a, void *b, void *c,
<title id="binary-dlls-building.title">Building</title>
<para>
So how do we actually build the Wine built-in DLL? The easiest way is
- to get Winemaker to do the hard work for us. For the simple example we
+ to get <command>winemaker</command> to do the hard work for us. For the simple example we
have two source files (the wrapper and the spec file). We also have
the 3rd party header and library files of course.
</para>
<para>
- Put the two source files in a suitable directory and then use
- winemaker to create the build framework, including configure script,
- makefile etc. You will want to use the following options of
- winemaker:
+ Put the two source files in a suitable directory and then use
+ <command>winemaker</command> to create the build framework, including configure script,
+ makefile etc. You will want to use the following options:
<itemizedlist>
<listitem>
<para>
- --nosource-fix (requires winemaker version
+ <option>--nosource-fix</option> (requires <command>winemaker</command> version
0.5.8 or later) to ensure that the two files are not modified
- (if using an older version of winemaker, make the two files
+ (if using an older version, make the two files
read-only and ignore the complaints about being unable to modify
them).
</para>
</listitem>
<listitem>
<para>
- --dll --single-target MyWin --nomfc to specify the target.
+ <userinput>--dll --single-target <replaceable>MyWin</replaceable> --nomfc</userinput> to specify the target.
</para>
</listitem>
<listitem>
<para>
- -DMightNeedSomething -I3rd_party_include -L3rd_party_lib -lxxxx
- -lyyyy where these are the locations of the header files etc.
+ <userinput>-D<replaceable>MightNeedSomething</replaceable>
+ -I<replaceable>3rd_party_include</replaceable>
+ -L<replaceable>3rd_party_lib</replaceable>
+ -l<replaceable>xxxx</replaceable>
+ -l<replaceable>yyyy</replaceable></userinput>
+ where these are the locations of the header files etc.
</para>
</listitem>
</itemizedlist>
</para>
<para>
- After running winemaker I like to edit the Makefile to add the line
- CEXTRA = -Wall just before the DEFINES =.
+ After running <command>winemaker</command> I like to edit the <filename>Makefile</filename>
+ to add the line <userinput>CEXTRA = -Wall</userinput> just before the defines.
</para>
<para>
- Then simply run the configure and make as normal (described elsewhere).
+ Then simply run <command>configure</command> and <command>make</command> as normal
+ (described elsewhere).
</para>
</sect1>
@@ -241,26 +246,27 @@ signed short WINAPI MyProxyWinFunc (unsigned short a, void *b, void *c,
</para>
<para>
Ensure that the actual Linux Shared Object is placed somewhere where
- the Linux system will be able to find it. Typically this means it
- should be in one of the directories mentioned in the /etc/ld.so.conf
- file or somewhere in the path specified by LD_LIBRARY_PATH. If you
+ the Linux system will be able to find it. Typically this means it
+ should be in one of the directories mentioned in the <filename>/etc/ld.so.conf</filename>
+ file or somewhere in the path specified by <envar>LD_LIBRARY_PATH</envar>. If you
can link to it from a Linux program it should be OK.
</para>
<para>
- Put the proxy shared object (MyWin.dll.so) in the same place as the
- rest of the built-in DLLs. Alternatively ensure that WINEDLLPATH
+ Put the proxy shared object (<filename>MyWin.dll.so</filename>) in the same place as the
+ rest of the built-in DLLs. Alternatively ensure that <envar>WINEDLLPATH</envar>
includes the directory containing the proxy shared object.
</para>
<para>
If you have both a Windows DLL and a Linux DLL/proxy pair then you will
have to ensure that the correct one gets called. The easiest way is
probably simply to rename the windows version so that it doesn't get
- detected. Alternatively you could set a DLL override with winecfg,
+ detected. Alternatively you could set a DLL override with <command>winecfg</command>,
so that the built-in version is used.
</para>
<para>
Once you have done this you should be using the Linux Shared Object
- successfully. If you have problems then set the WINEDEBUG=+module
+ successfully. If you have problems then set the
+ <userinput><envar>WINEDEBUG</envar>=+module</userinput>
environment variable before running wine to see what is actually happening.
</para>
</sect1>
@@ -272,7 +278,8 @@ signed short WINAPI MyProxyWinFunc (unsigned short a, void *b, void *c,
Unix equivalent. Of course there is no suitable function in the true
Microsoft Windows API, but wine provides a function for just this
task and exports it from its copy of the kernel32 DLL. The function
- is <function>wine_get_unix_file_name</function> (defined in winbase.h).
+ is <function>wine_get_unix_file_name</function> (defined in
+ <filename>winbase.h</filename>).
</para>
</sect1>
</chapter>
diff --git a/en/winelib-intro.sgml b/en/winelib-intro.sgml
index 0f85543..146be48 100644
--- a/en/winelib-intro.sgml
+++ b/en/winelib-intro.sgml
@@ -55,7 +55,8 @@
</para>
<para>
The main difference is that the compiler becomes much more important.
- It is highly recommended that you use gcc, g++, and the GNU binutils.
+ It is highly recommended that you use <command>gcc</command>,
+ <command>g++</command>, and the GNU binutils.
The more recent your gcc compiler the better.
For any serious amount of code you should not consider anything older
than gcc 2.95.2. The latest gcc snapshots contain some useful bug
@@ -100,7 +101,7 @@
</listitem>
<listitem>
<para>
- you will need to perform the usual Dos to Unix text file conversion
+ you will need to perform the usual DOS to Unix text file conversion
otherwise you'll get in trouble when the compiler considers that
your '\' is not at the end of the line since it is followed by a
pesky carriage return.
@@ -114,10 +115,10 @@
</itemizedlist>
<para>
- The best way to take care of all these issues is to use winemaker.
+ The best way to take care of all these issues is to use <command>winemaker</command>.
</para>
<para>
- Winemaker is a Perl script which is designed to help you bootstrap
+ <command>winemaker</command> is a Perl script which is designed to help you bootstrap
the conversion of your Windows projects to Winelib. In order to do
this it will go analyze your code, fixing the issues listed above
and generate straight Makefiles.
@@ -128,10 +129,10 @@
as just running the two commands below (note the dot indicating
current directory at the end of the first command):
</para>
- <programlisting>
- $ winemaker --lower-uppercase .
- $ make
- </programlisting>
+ <screen>
+ <prompt>$ </prompt><userinput>winemaker --lower-uppercase .</userinput>
+ <prompt>$ </prompt><userinput>make</userinput>
+ </screen>
<para>
But of course things are not always that simple which is why we have
@@ -150,44 +151,46 @@
header and resource files.
</para>
<para>
- Run <command>make clean</command> in the
+ Run <userinput>make clean</userinput> in the
notepad source directory if it contains results of previous builds.
- Create a separate directory with name notepad2, so it won't conflict
+ Create a separate directory with name <literal>notepad2</literal>, so it won't conflict
with the Wine copy of the application. Copy the sources of notepad
- (files *.c, *.h, *.rc) to this directory. Now run the commands,
- mentioned above from the notepad2 directory:
+ (<filename>*.c</filename>, <filename>*.h</filename>,
+ and <filename>*.rc</filename> files) to this directory.
+ Now run the commands mentioned above from the <filename
+ class="directory">notepad2</filename> directory:
</para>
- <programlisting>
- $ winemaker --lower-uppercase .
- $ make
- </programlisting>
+ <screen>
+ <prompt>$ </prompt><userinput>winemaker --lower-uppercase .</userinput>
+ <prompt>$ </prompt><userinput>make</userinput>
+ </screen>
<para>
Notice how it fails linking, because of undefined reference to
- wnsprintfW. This is because we didn't specify the libraries we need
- to link to. Normally you know which libraries you need or you can find
- a list in your old Makefile or project file.
+ <function>wnsprintfW</function>. This is because we didn't specify the
+ libraries we need to link to. Normally you know which libraries you need
+ or you can find a list in your old Makefile or project file.
</para>
<para>
To fix that problem, open <filename>notepad2/Makefile.in</filename>
in a text editor and search for an assignment to a variable with
<literal>IMPORTS</literal> as part of its name. There will
- be a list of import libraries. Now run winemaker again, but with
- these libraries prefixed by <literal>-i</literal>:
+ be a list of import libraries. Now run <command>winemaker</command> again, but with
+ these libraries prefixed by <option>-i</option>:
</para>
- <programlisting>
- $ winemaker --lower-uppercase -icomdlg32 -ishell32 -ishlwapi -iuser32 -igdi32 -iadvapi32 .
- $ make
- </programlisting>
+ <screen>
+ <prompt>$ </prompt><userinput>winemaker --lower-uppercase -icomdlg32 -ishell32 -ishlwapi -iuser32 -igdi32 -iadvapi32 .</userinput>
+ <prompt>$ </prompt><userinput>make</userinput>
+ </screen>
<para>
You are done! Now you can start the application as
- <command>wine notepad2.exe.so</command> or <command>./notepad2.exe</command>.
+ <userinput>wine notepad2.exe.so</userinput> or <userinput>./notepad2.exe</userinput>.
</para>
<para>
If you come across problems preparing and building this application
this probably means that winemaker utility is broken by some changes
- in Wine. Try asking for help on <email>wine-devel at winehq.org</email>
+ in Wine. Try asking for help on <email>wine-devel at winehq.org</email>.
</para>
</sect2>
@@ -199,12 +202,13 @@
</para>
<variablelist>
<varlistentry>
- <term><option>Getting the source</option></term>
+ <term>Getting the source</term>
<listitem>
<para>
First you should try to get the sources together with the
executables/libraries that they build. If you have no
- Visual C++ project files available winemaker having these around
+ Visual C++ project files available <command>winemaker</command>
+ having these around
can help it guess what it is that your project is
trying to build. Otherwise, it is able to understand
Visual C++ projects. Usually the executables and libraries are
@@ -213,20 +217,20 @@
directory where the sources are. So it's best if you can
transfer the source files and either of these directories to
Linux. Note that you don't need to transfer the
- <filename>.obj</filename>, <filename>.pch</filename>,
- <filename>.sbr</filename> and other files that also reside in
+ <filename>.obj</filename>, <filename>.pch</filename>, <filename>.sbr</filename>
+ and other files that also reside in
these directories; especially as they tend to be quite big.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>cd <root_dir></option></term>
+ <term><userinput>cd <replaceable>root_dir</replaceable></userinput></term>
<listitem>
<para>
Then go to the root directory where are your source files.
- Winemaker can deal with a whole directory hierarchy at once so
+ <command>winemaker</command> can deal with a whole directory hierarchy at once so
you don't need to go into a leaf directory, quite the contrary.
- Winemaker will automatically generate makefiles in each
+ <command>winemaker</command> will automatically generate makefiles in each
directory where one is required, and will generate a global
makefile so that you can rebuild all your executables and
libraries with a single <command>make</command> command.
@@ -234,15 +238,15 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><option>Making the source writable</option></term>
+ <term>Making the source writable</term>
<listitem>
<para>
Then make sure you have write access to your sources. It may
sound obvious, but if you copied your source files from a
CD-ROM or if they are in Source Safe on Windows, chances are
that they will be read-only.
- But Winemaker needs write access so that it can fix them. You
- can arrange that by running <command>chmod -R u+w .</command>.
+ But <command>winemaker</command> needs write access so that it can fix them. You
+ can arrange that by running <quote><userinput>chmod -R u+w .</userinput></quote>.
Also you will want to make sure that you have a backup copy of
your sources in case something went horribly wrong, or more
likely, just for reference at a later point. If you use a
@@ -250,19 +254,18 @@
</para>
<para>
If you have already modified your source files and you want
- to make sure that winemaker will not make further changes to
- them then you can use the --nosource-fix option to protect
+ to make sure that <command>winemaker</command> will not make further changes to
+ them then you can use the <option>--nosource-fix</option> option to protect
them.
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>Running winemaker</option></term>
+ <term>Running winemaker</term>
<listitem>
<para>
- Then you'll run winemaker. Here are the options you will most
- likely want to use. For a complete list of options see
- the winemaker man page.
+ Then you'll run <command>winemaker.</command>. Here are the options you will most
+ likely want to use. For a complete list of options see the man page.
</para>
<variablelist>
<varlistentry>
@@ -274,7 +277,7 @@
directories, that have an 'incorrect' case.
<option>--lower-uppercase</option> specifies they should
only be renamed if their name is all uppercase. So files
- that have a mixed case, like 'Hello.c' would not be
+ that have a mixed case, like <filename>Hello.c</filename> would not be
renamed. <option>--lower-all</option> will rename any
file. If neither is specified then no file or directory
will be renamed, almost. As you will see
@@ -318,7 +321,7 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><option>-Dmacro[=defn]</option></term>
+ <term><option>-Dmacro<optional>=<replaceable>defn</replaceable></optional></option></term>
<term><option>-Idir</option></term>
<term><option>-Ldir</option></term>
<term><option>-idll</option></term>
@@ -338,19 +341,19 @@
from any of the source directories. You can also use a
variable in the path yourself if you wish (but don't
forget to escape the '$'). For instance you could specify
- <literal>-I\$(WINELIB_INCLUDE_ROOT)/msvcrt</literal>.
+ <parameter class="option">-I\$(WINELIB_INCLUDE_ROOT)/msvcrt</parameter>.
</para>
</listitem>
</varlistentry>
</variablelist>
<para>
So your command may finally look like:
- <literal>winemaker --lower-uppercase -Imylib/include .</literal>
+ <userinput>winemaker --lower-uppercase -Imylib/include .</userinput>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term id="renaming"><option>File renaming</option></term>
+ <term id="renaming">File renaming</term>
<listitem>
<para>
When you execute winemaker it will first rename files to bring
@@ -368,7 +371,7 @@
</listitem>
</varlistentry>
<varlistentry>
- <term><option>Source modifications and makefile generation</option></term>
+ <term>Source modifications and makefile generation</term>
<listitem>
<para>
winemaker will then proceed to modify the source files so that
@@ -377,13 +380,13 @@
construct that it cannot correct. Finally it will generate the
makefiles. Once all this is done you can review
the changes that winemaker did to your files by using
- <command>diff -uw</command>. For instance:
- <command>diff -uw hello.c.bak hello.c</command>
+ <userinput>diff -uw</userinput>. For instance:
+ <userinput>diff -uw hello.c.bak hello.c</userinput>
</para>
</listitem>
</varlistentry>
<varlistentry>
- <term><option>Running make</option></term>
+ <term>Running make</term>
<listitem>
<para>
This is a pretty simple step: just type <command>make</command>
diff --git a/en/winelib-mfc.sgml b/en/winelib-mfc.sgml
index 5d38105..2f086bf 100644
--- a/en/winelib-mfc.sgml
+++ b/en/winelib-mfc.sgml
@@ -136,8 +136,8 @@
Winelib:
</para>
<para>
- We recommend running winemaker in
- '<option>--interactive</option>' mode to specify the right
+ We recommend running <command>winemaker</command> in
+ <option>--interactive</option> mode to specify the right
options for the MFC and the ATL part (to get the include paths
right, to not consider the MFC MFC-based, and to get it to
build libraries, not executables).
@@ -165,14 +165,14 @@
<function>HtmlView</function>, ...
</para>
<para>
- We recommend using Wine msvcrt headers (<literal>-isystem
- $(WINE_INCLUDE_ROOT)/msvcrt</literal>), though it means you
+ We recommend using Wine msvcrt headers (<parameter class="option">-isystem
+ $(WINE_INCLUDE_ROOT)/msvcrt</parameter>), though it means you
will have to temporarily disable winsock support
(<literal>#ifdef</literal> it out in
<filename>windows.h</filename>).
</para>
<para>
- You should use g++ compiler more recent than g++ 2.95. g++
+ You should use <command>g++</command> compiler more recent than g++ 2.95. g++
2.95 does not support unnamed structs while the more recent
ones do, and this helps a lot. Here are the options worth
mentioning:
diff --git a/en/winelib-porting.sgml b/en/winelib-porting.sgml
index c0c17a3..0e8e5cd 100644
--- a/en/winelib-porting.sgml
+++ b/en/winelib-porting.sgml
@@ -5,12 +5,12 @@
<title id="unicode.title">Unicode</title>
<para>
- The <literal>wchar_t</literal> type has different standard
- sizes in Unix (4 bytes) and Windows (2 bytes). You need a
+ The <type>wchar_t</type> type has different standard
+ sizes in Unix (4 bytes) and Windows (2 bytes). You need a
recent gcc version (2.9.7 or later) that supports the
- <parameter>-fshort-wchar</parameter> option to set the
- size of <literal>wchar_t</literal> to the one expected
- by Windows applications.
+ <option>-fshort-wchar</option> option to set the
+ size of <type>wchar_t</type> to the one expected
+ by Windows applications.
</para>
<para>
@@ -61,7 +61,7 @@
<listitem>
<para>
You rely on the precise semantics of the calls, for
- example, returning <literal>-1</literal> rather than
+ example, returning <returnvalue>-1</returnvalue> rather than
non-zero. More likely, your application will rely on calls
like <function>fopen()</function> taking a Windows path
rather than a Unix one.
@@ -75,7 +75,7 @@
<para>
Add <option>-mno-cygwin</option> to your compiler flags. This
- will cause <command>winebuild</command> to resolve your c
+ will cause <command>winebuild</command> to resolve your C
library calls to <filename>msvcrt.dll</filename>. Many simple
calls which behave the same have been specified as
non-importable from msvcrt; in these cases
@@ -94,7 +94,7 @@
<para>
If you have a set of include files (or when they are available
in Wine), you need to use the <parameter>-isystem
- "include_path"</parameter> flag to gcc to tell it to use your
+ <replaceable>include_path</replaceable></parameter> flag to gcc to tell it to use your
headers in preference to the local system headers.
</para>
<para>
@@ -127,7 +127,7 @@
file. <command>winebuild</command> gives you a warning for
unused imports so you can delete the ones you don't need
later. Failing that, just import all the DLLs you can find in
- the <filename>dlls/</filename> directory of the Wine source
+ the <filename class="directory">dlls/</filename> directory of the Wine source
tree.
</para>
<para>
@@ -135,10 +135,10 @@
<parameter>-luuid</parameter> to the link line.
</para>
<para>
- gcc is more strict than VC++, especially when compiling
- C++. This may require you to add casts to your C++ to prevent
+ <command>gcc</command> is more strict than <command>VC++,</command> especially
+ when compiling C++. This may require you to add casts to your C++ to prevent
overloading ambiguities between similar types (such as two
- overloads that take int and char respectively).
+ overloads that take <type>int</type> and <type>char</type> respectively).
</para>
<para>
If you come across a difference between Windows and Wine
diff --git a/en/winelib-toolkit.sgml b/en/winelib-toolkit.sgml
index 40f8ce5..42b06ac 100644
--- a/en/winelib-toolkit.sgml
+++ b/en/winelib-toolkit.sgml
@@ -25,10 +25,10 @@
The usage is very easy, just replace the path to the source folder
with the path to the project file.
</para>
- <programlisting>
- $ winemaker --lower-uppercase myproject.vcproj
- $ make
- </programlisting>
+ <screen>
+ <prompt>$ </prompt><userinput>winemaker --lower-uppercase myproject.vcproj</userinput>
+ <prompt>$ </prompt><userinput>make</userinput>
+ </screen>
</sect2>
<sect2 id="source-analysis">
@@ -43,7 +43,7 @@
wrong and how to fix it/avoid it.
</para>
<para>
- At the core winemaker does a recursive traversal of
+ At the core <command>winemaker</command> does a recursive traversal of
your source tree looking for targets (things to build) and source
files. Let's start with the targets.
</para>
@@ -52,17 +52,18 @@
a directory, winemaker puts it in the list of things to build and
will later generate a <filename>Makefile</filename> in this
directory. Note that Winemaker also knows about the commonly used
- <filename>Release</filename> and <filename>Debug</filename>
- directories, so it will attribute the executables and libraries
+ <filename class="directory">Release</filename> and <filename
+ class="directory">Debug</filename> directories, so it will
+ attribute the executables and libraries
found in these to their parent directory. When it finds an
executable or a DLL winemaker is happy because these give it more
information than the other cases described below.
</para>
<para>
If it does not find any executable or DLL winemaker will look for
- files with a <filename>.mak</filename> extension. If they are not
- disguised Visual C++ projects (and currently even if they are),
- winemaker will assume that a target by that name should be built
+ files with a <filename>.mak</filename> extension. If they are not
+ disguised Visual C++ projects (and currently even if they are),
+ <command>winemaker</command> will assume that a target by that name should be built
in this directory. But it will not know whether this target is an
executable or a library. So it will assume it is of the default
type, i.e. a graphical application, which you can override by using
@@ -75,24 +76,24 @@
it will not know the name or type of this target. For the type it
will do as in the above case. And for the name it will use the
directory's name. Actually, if the directory starts with
- <filename>src</filename> winemaker will try to make use of the name
+ <literal>src</literal>, <command>winemaker</command> will try to make use of the name
of the parent directory instead.
</para>
<para>
Once the target list for a directory has been established,
- winemaker will check whether it contains a mix of executables and
- libraries. If it is so, then winemaker will make it so that each
+ it will check whether it contains a mix of executables and
+ libraries. If it is so, then it will make it so that each
executable is linked with all the libraries of that directory.
</para>
<para>
If the previous two steps don't produce the expected results (or
- you think they will not) then you should put winemaker in
- interactive mode (see <xref linkend="interactive"
- endterm="interactive.title">). This will allow you to specify the
+ you think they will not) then you should put <command>winemaker</command> in
+ interactive mode (see <xref linkend="interactive"
+ endterm="interactive.title">). This will allow you to specify the
target list (and more) for each directory.
</para>
<para>
- In each directory winemaker also looks for source files: C, C++
+ In each directory <command>winemaker</command> also looks for source files: C, C++
or resource files. If it also found targets to build in this
directory it will then try to assign each source file to one of
these targets based on their names. Source files that do not seem
@@ -107,21 +108,21 @@
source files found in its subdirectories.
</para>
<para>
- Finally winemaker also looks for more exotic files like
- <filename>.h</filename> headers, <filename>.inl</filename> files
+ Finally <command>winemaker</command> also looks for more exotic files like
+ <filename>.h</filename> headers, <filename>.inl</filename> files
containing inline functions and a few others. These are not put in
the regular source file lists since they are not compiled directly.
- But winemaker will still remember them so that they are processed
+ But it will still remember them so that they are processed
when the time comes to fix the source files.
</para>
<para>
- Fixing the source files is done as soon as winemaker has finished
- its recursive directory traversal. The two main tasks in this step
- are fixing the CRLF issues and verifying the case of the include
+ Fixing the source files is done as soon as the recursive directory
+ traversal is completed. The two main tasks in this step are fixing
+ the CRLF issues and verifying the case of the <literal>include</literal>
statements.
</para>
<para>
- Winemaker makes a backup of each source file (in such a way that
+ <command>winemaker</command> makes a backup of each source file (in such a way that
symbolic links are preserved), then reads it fixing the CRLF
issues and the other issues as it goes. Once it has finished
working on a file it checks whether it has done any non
@@ -131,7 +132,7 @@
<para>
Checking the case of the include statements (of any form,
including files referenced by resource files), is done in the
- context of that source file's project. This way winemaker can use
+ context of that source file's project. This way <command>winemaker</command> can use
the proper include path when looking for the file that is included.
If winemaker fails to find a file in any of the directories of the
include path, it will rename it to lowercase on the basis that it
@@ -140,9 +141,8 @@
<option>--nolower-include</option>).
</para>
<para>
- Finally winemaker generates the <filename>Makefile</filename>
- files. From the above description
- you can guess at the items that winemaker may get wrong in
+ Finally <command>winemaker</command> generates the <filename>Makefile</filename>
+ files. From the above description you can guess at the items that it may get wrong in
this phase: macro definitions, include path, DLL path, DLLs to
import, library path, libraries to link with. You can deal with
these issues by using winemaker <option>-D</option>, <option>-P</option>,
@@ -224,7 +224,8 @@ EXES = hello.exe
This is where the targets for this directory are listed. The names
are pretty self-explanatory. <varname>SUBDIRS</varname> is usually
only present in the top-level makefile. For libraries and
- executables, specify the full name, including the '.dll', '.a' or '.exe'
+ executables, specify the full name, including the <filename>.dll</filename>,
+ <filename>.a</filename> or <filename>.exe</filename>
extension. Note that these names must be in all lowercase.
</para>
<programlisting>
@@ -287,8 +288,8 @@ hello_exe_LIBRARIES =
</para>
<para>
The <varname>DLLS</varname> field is where you would enumerate the list of
- DLLs that executable imports. It should contain the full DLL name
- , but not the '-l' option.
+ DLLs that executable imports. It should contain the full DLL name,
+ but not the <option>-l</option> option.
</para>
<programlisting>
hello_exe_OBJS = $(hello_exe_C_SRCS:.c=.o) \
@@ -331,13 +332,13 @@ all: $(SUBDIRS) $(DLLS:%=%.so) $(LIBS) $(EXES)
</sect1>
<sect1 id="wrc">
- <title id="wrc.title">Compiling resource files: WRC</title>
+ <title id="wrc.title">Compiling resource files: <command>wrc</command></title>
<para>
To compile resources you should use the Wine Resource Compiler,
- wrc for short, which produces a binary <filename>.res</filename>
- file. This resource file is then used by winebuild when compiling
- the spec file (see <xref linkend="spec-file"
- endterm="spec-file.title">).
+ <command>wrc</command> for short, which produces a binary
+ <filename>.res</filename> file.
+ This resource file is then used by <command>winebuild</command> when compiling
+ the spec file (see <xref linkend="spec-file" endterm="spec-file.title">).
</para>
<para>
Again the makefiles generated by winemaker take care of this for you.
@@ -359,10 +360,10 @@ WRCFLAGS = -r -L
There are two issues you are likely to encounter with resource files.
</para>
<para>
- The first problem is with the C library headers. WRC does not know
+ The first problem is with the C library headers. <command>wrc</command> does not know
where these headers are located. So if an RC file, of a file it
includes, references such a header you will get a 'file not found'
- error from wrc. Here are a few ways to deal with this:
+ error. Here are a few ways to deal with this:
</para>
<itemizedlist>
<listitem>
@@ -371,7 +372,7 @@ WRCFLAGS = -r -L
enclose the offending include statement in an
<literal>#ifndef RC_INVOKED</literal> statement where
<varname>RC_INVOKED</varname> is a macro name which is
- automatically defined by wrc.
+ automatically defined by <command>wrc</command>.
</para>
</listitem>
<listitem>
@@ -398,12 +399,13 @@ WRCFLAGS = -r -L
</itemizedlist>
<para>
The second problem is that the headers may contain constructs that
- WRC fails to understand. A typical example is a function which return
- a 'const' type. WRC expects a function to be two identifiers followed
- by an opening parenthesis. With the const this is three identifiers
- followed by a parenthesis and thus WRC is confused (note: WRC should
- in fact ignore all this like the windows resource compiler does).
- The current work-around is to enclose offending statement(s) in an
+ <command>wrc</command> fails to understand. A typical example is a function which return a
+ <literal>const</literal> type. <command>wrc</command> expects a function to be two
+ identifiers followed by an opening parenthesis.
+ With the <literal>const</literal> this is three identifiers
+ followed by a parenthesis and thus <command>wrc</command> is confused (note: it should
+ in fact ignore all this like the windows resource compiler does).
+ The current work-around is to enclose offending statement(s) in a
<literal>#ifndef RC_INVOKED</literal>.
</para>
@@ -414,8 +416,8 @@ WRCFLAGS = -r -L
</para>
<para>
If you use common controls/dialogs in your resource files, you
- will need to add <function>#include <commctrl.h></function>
- after the <function>#include <windows.h></function> line,
+ will need to add <literal>#include <commctrl.h></literal>
+ after the <literal>#include <windows.h></literal> line,
so that <command>wrc</command> knows the values of control
specific flags.
</para>
@@ -435,7 +437,7 @@ WRCFLAGS = -r -L
</para>
<para>
The spec file is there to solve the semantic gap described above.
- It provides information about each API exported from a Dll so that
+ It provides information about each API exported from a DLL so that
the appropriate tables can be generated. Further the information is
used to for better relay logging.
</para>
@@ -454,7 +456,7 @@ WRCFLAGS = -r -L
<title id="spec-reference.title">More details</title>
<para>
- Here is a more detailed description of the spec file's format.
+ Here is a more detailed description of the spec file format.
</para>
<programlisting>
@@ -666,9 +668,9 @@ ORDINAL FUNCTYPE OPTIONS EXPORTNAME([ARGTYPE [ARGTYPE [...]]]) HANDLERNAME
<para>
To declare a function using a variable number of arguments in
Win16, specify the function as taking no arguments. The arguments
- are then available with CURRENT_STACK16->args. In Win32, specify
+ are then available with <literal>CURRENT_STACK16->args</literal>. In Win32, specify
the function as <literal>varargs</literal> and declare it with a
- '...' parameter in the C file. See the wsprintf* functions in
+ '...' parameter in the C file. See the <function>wsprintf*</function> functions in
<filename>user.spec</filename> and
<filename>user32.spec</filename> for an example.
</para>
@@ -705,8 +707,9 @@ ORDINAL extern EXPORTNAME SYMBOLNAME
To link an executable you need to link together: your object files,
any Windows libraries that your application depends
on, gdi32 for instance, and any additional library that you use. All
- the libraries you link with should be available as '.so' libraries.
- If one of them is available only in '.dll' form then consult
+ the libraries you link with should be available as
+ <filename>.so</filename> libraries. If one of them is available
+ only in <filename>.dll</filename> form then consult
<xref linkend="bindlls" endterm="bindlls.title">.
</para>
<para>
@@ -729,7 +732,7 @@ ORDINAL extern EXPORTNAME SYMBOLNAME
gdi32. This is because you did not link the said library with gdi32.
One way to fix it is to link this executable, and any other that also
uses your library, with gdi32. But it is better to go back to your
- library's makefile and explicitly link it with gdi32.
+ library makefile and explicitly link it with gdi32.
</para>
<para>
As you will quickly notice, this has unfortunately not been
--
1.8.3.4
More information about the wine-patches
mailing list