Changeset 26531

Timestamp:

2007-03-03 11:34:44 (4 years ago)

Author:

res2002

Message:

Texinfo markup fixes + few tweaks on the smart pointers + VC build sections.

Location:

CS/trunk/docs/texinfo

Files:

• build/extlibs.txi (modified) (2 diffs)
• build/platform/win32/msvc/msvc7.txi (modified) (3 diffs)
• build/sysreq.txi (modified) (1 diff)
• usingcs/scf/smartptr.txi (modified) (4 diffs)

CS/trunk/docs/texinfo/build/extlibs.txi

@@ -143 +143 @@
 
 This is needed to enable graphical output on a number of Unix-like operating 
-systems, most prominently @sc{gnu}/Linux.  It is \emph{not} needed for Windows
+systems, most prominently @sc{gnu}/Linux.  It is @emph{not} needed for Windows
 or MacOS/X.
 
@@ -158 +158 @@
 @cindex Libraries, OpenGL
 
-OpenGL is needed to provide accelerated 3D graphics \emph{on all platforms}.
+OpenGL is needed to provide accelerated 3D graphics @emph{on all platforms}.
 
 No special effort is usually needed to install the development components on

CS/trunk/docs/texinfo/build/platform/win32/msvc/msvc7.txi

@@ -224 +224 @@
 Q1. @emph{I'm using the Visual C++ 2005 Express Edition and I get a lot of 
 ``file not found'' errors for @file{windef.h} and others. What is wrong?}
+
 Q2. @emph{I'm using the Visual C++ 2005 Express Edition and I get a lot of 
 ``unresolved symbol'' errors for names like 
@@ -265 +266 @@
 
 @item
-Q. @emph{I've got unresolved symbols.}
-
-A. What kind of symbols?
-
-@itemize @minus
-@item
-@samp{_png_@dots{}}: That means that you don't link the project with
-@file{libpng.lib}.  Just take a look below where it is explained how to do so.
-
-@item
-@samp{_inflate@dots{}} and @samp{_deflate@dots{}}: Well, it seems to your
-project lacks @file{zlib.lib}.  The trick is explained just below, so hang on.
-
-@item
-@samp{_DirectDraw@dots{}}: Same as above, but for @file{ddraw.lib} (DirectX
-component), look below.
-
-@item
 Q. @emph{How can I reduce build times?}
 
@@ -293 +276 @@
 @item
 Q. @emph{How can I reduce build sizes?}
+
 A. Build only the projects you will need.
+
 A. Turning off precompiled headers tends to save a large amount of file space
 while increasing build times somewhat.
 
 @item
-Any others: It seems that there is a missing source file in the project.  
-
-For Crystal Space the MSVC project files are generated once every 24 hours, so 
-normally all missing sources should have been added after that time.  If you
-can't wait that long, or the file is still missing, contact one of the Crystal
-Space developers.
+Q. @emph{It seems that there is a missing source file in the project.}
+
+A. For Crystal Space the MSVC project files are generated once every 24 hours, 
+so normally all missing sources should have been added after that time.  If 
+you can't wait that long, or the file is still missing, contact one of the 
+Crystal Space developers.
 
 For third party projects it's usually the best idea to contact one of it's
 developers, they should be able to tell you which file is missing.
+@end itemize
 
 @subsubheading Executing

CS/trunk/docs/texinfo/build/sysreq.txi

@@ -72 +72 @@
 @item X Window System
 This is needed to enable graphical output on a number of Unix-like operating 
-systems, most prominently @sc{gnu}/Linux. It is \emph{not} needed for Windows
+systems, most prominently @sc{gnu}/Linux. It is @emph{not} needed for Windows
 or MacOS/X.
 
 @item OpenGL
-OpenGL is needed to provide accelerated 3D graphics \emph{on all platforms}.
+OpenGL is needed to provide accelerated 3D graphics @emph{on all platforms}.
 
 Note that no special effort is usually needed to install the development 

CS/trunk/docs/texinfo/usingcs/scf/smartptr.txi

@@ -97 +97 @@
 need to be aware of the interactions with reference counting.
 
-Assigning a smart pointer to a normal pointer \emph{does not} change the 
+Assigning a smart pointer to a normal pointer @emph{does not} change the 
 reference count of the object.  This can be beneficial as the reference 
 counting overhead is avoided.  It can also be dangerous, as the normal pointer 
@@ -105 +105 @@
 the normal pointer.  If that's not guaranteed use a @code{csRef<>} instead.
 
-Assigning a normal pointer to a smart pointer \emph{does} change the reference
+Assigning a normal pointer to a smart pointer @emph{does} change the reference
 count: ownership is taken, ie the reference count is increased.  This can 
 cause a leaked reference in certain circumstances.  One notable instance is 
@@ -114 +114 @@
 leak.
 
-The recommend way to deal with that is to \emph{never} assign an object 
+The recommend way to deal with that is to @emph{never} assign an object 
 allocated with @samp{new} to a smart pointer directly.  Instead use it's
 @code{AttachNew()} method which will take care of the proper reference
@@ -399 +399 @@
 @code{csRef<>} object to take ownership.
 
+@example
+// Passing a csRef<iFoo> as parameter: usually unnecessary
+void Bar (csRef<iFoo>& stuff) @{ @dots{} @}
+
+// iFoo* is usually completely adequate
+void Baz (iFoo* stuff) 
+@{ 
+  @dots{} 
+  /* If 'stuff' runs the risk of being released you can always assign it to
+   * a csRef<> in the function body. */
+  csRef<iFoo> keepRef = stuff;
+  @dots{} 
+@}
+@end example
+
 @subsubheading Warnings About csPtr<>!