- update README and INSTALL, slight doc fixes.

git-svn-id: https://assimp.svn.sourceforge.net/svnroot/assimp/trunk@1050 67173fc5-114c-0410-ac8e-9d2fd5bffc1f

INSTALL

@@ -1,12 +1,12 @@
 	
+========================================================================
+Open Asset Import Library (assimp) INSTALL 
+========================================================================
 
-Open Asset Import Library (Assimp) Install
-------------------------------------------------
 
-
-=======================================================================
-Please refer to the doxygen documentation for full install instructions
-=======================================================================
+------------------------------
+Getting the documentation
+------------------------------
 
 A regularly-updated copy is available at 
 http://assimp.sourceforge.net/lib_html/index.html
@@ -20,38 +20,27 @@ c) navigate to ./doc
 d) and run 'doxygen'
 
 Open the generated HTML (AssimpDoc_Html/index.html) in the browser of your choice.
-Windows only: To generate the CHM doc install the 'Microsoft HTML Workshop'
-and configure the path to it in the DOXYFILE. Run doxygen again.
-
-=======================================================================
-For the inpatient:
-
-Windows: go to ./workspaces/vc8 or ./workspaces/vc9, open the
-VS Solution and build for your preferred build target ...
-release-dll is usually the best choice. Adjust the runtime library to
-your needs, multithreaded-dll is preconfigured by default.
-
-These solutions are currently hand-maintained, they copy all
-the resulting binaries to ./bin/config-name at the moment. 
-
-Unix & Family:
-
-CMake is now our preferred build tool. Run cmake with your
-favourite build script generator from *here* and have fun.
-If you use cmake only to get a makefile, run 
-'make' and 'make install' afterwards. 
-
-NOTE: in order to use the assimp command line tools, you may
-need to run ldconfig as root to make the so loader find
-the assimp shared library --
-
-Note that running make from ./code is deprecated, although there
-is still a suitable makefile in it.
-
+Windows only: To generate the CHM doc, install 'Microsoft HTML Workshop'
+and configure the path to it in the DOXYFILE first. 
 
+------------------------------
+Building Assimp 
+------------------------------
 
+More detailed build instructions can be found in the documentation,
+this section is just for the inpatient among you.
 
+CMake is the preferred build system for Assimp. The minimum required version 
+is 2.6. If you don't have it yet, downloads for CMake can be found on
+http://www.cmake.org/. 
 
+Building Assimp with CMake is 'business as usual' if you've used CMake
+before. All steps can be done either on the command line / shell or
+by using the CMake GUI tool, the choice is up to you. 
 
+First, invoke CMake to generate build files for a particular
+toolchain (for standard GNU makefiles: cmake -G 'Unix Makefiles').
+Afterwards, use the generated build files to perform the actual
+build. 
 
 

README

@@ -1,22 +1,40 @@
-	Open Asset Import Library (Assimp) Readme
-	-----------------------------------------
-
-Here you can find information regarding Open Asset Import Library:
-
+
+========================================================================
+Open Asset Import Library (assimp) README
+========================================================================
+
+
+Table of Contents
+
 	1.		Overview
-	1.1		Supported file formats
-	1.2		File structure
-	2.		Build the Asset Import Library
+	 1.1		Supported file formats
+	 1.2		File structure
+	2.		Build the library
 	3. 		Help
 	4.		License
 
-
-
+
+------------------------------
 1.	Overview
-1.1	Supported file formats
-
-The Asset Import Library provides a lot of model formats:
+------------------------------
+
+Open Asset Import Library is a Open Source library designed to load various 3d file
+formats and convert them into a shared, in-memory format. It supports more than
+30 file formats. Basically, it is like DevIL for 3D models.
+
+Its short name is 'assimp', which is an unintended joke (the abbreviation is derived 
+from 'Asset Importer'). 
+
+
+----------------
+ 1.1	Supported file formats
+----------------
+
+The library provides importers for a lot of file formats, including:
 	- 3DS
+	- BLEND
+	- Collada
+	- IFC-STEP
 	- ASE
 	- DXF
 	- HMP
@@ -32,48 +50,70 @@ The Asset Import Library provides a lot of model formats:
 	- LWO
 	- OBJ
 	- SMD
-	
-	- Collada
-	
 	- LWO
-	
 	- Ogre XML
 	
-	- partly LWS
-	
-	- .. + many more, see http://assimp.sourceforge.net/main_features_formats.html for a full list.
+	
+ .. plus many more, see 
+http://assimp.sourceforge.net/main_features_formats.html for a more exhaustive list.
 
 
+----------------
 1.2 Repository structure
-
-Open Asset Import Library is implemented in C++ and provides a C-interface. The directory structure is:
-
-	/bin			Binaries of the Asset Import Library.
-	/code			Code of the Asset Import Library.
-	/contrib		Third-party-libraries used by the Asset Import Library.
-	/doc			Documentation (doxygen generated and data structure as a xml file)
-	/include		Public headers.
-	/lib			Static library location for Windows.
-	/obj			Object file location for Windows.
-	/port			Ports to other languages. 
+----------------
+
+Open Asset Import Library is implemented in C++ (but provides both a C and a C++ish interface). 
+The directory structure is:
+
+	/bin		Binaries, onyl used on Windows.
+	/code		Source code.
+	/contrib	Third-party-libraries used by the Asset Import Library.
+	/doc		Documentation (doxygen generated and data structure draft)
+	/include	Public headers for you to #include.
+	/lib		Static library location for Windows.
+	/obj		Object file location for Windows.
+	/port		Ports to other languages and scripts therefor. 
 	
-	/test			Unit- and regression tests, model test suite.
-	/tools			Tools (viewer, command line `assimp`).
-	/workspaces		Build enviroments for vc,xcode,...
+	/test		Unit- and regression tests, test suite of models.
+	/tools		Tools (viewer, command line `assimp`).
+	/samples	A small number of samples to illustrate possible use-cases.
+	/workspaces	Build enviroments for vc,xcode,... (deprecated,
+			CMake has superseeded all legacy build options)
 
 
-
-2. Build the Asset Import Library
+------------------------------
+2. Build the library
+------------------------------
 
 Take a look into the INSTALL file.
 
 
-
+------------------------------
 3. Help
-
-For more help go to http://assimp.sourceforge.net/ (or, for germans, http://www.zfx.info). Or take a look into the doc-folder, which contains the doxygen-generated documentation in HTMl format (CHMs for Windows are as well contained in some distributions and located right here in the root folder).
-
-
+------------------------------
+
+For more information go to http://assimp.sourceforge.net/. Or have a look into the ./doc-
+folder, which contains the Doxygen-generated documentation in HTML format (CHMs for
+ Windows are also included in some distributions and should be located right here in
+ the root folder).
+
+If reading the documentation doesn't solve your problems, try our forums at SF.net 
+  Open Discussion: http://sourceforge.net/projects/assimp/forums/forum/817653) 
+  Help: http://sourceforge.net/projects/assimp/forums/forum/817654
+
+or our  mailing list, assimp-discussions 
+  archive: http://sourceforge.net/mailarchive/forum.php?forum_name=assimp-discussions,
+  subscribe: https://lists.sourceforge.net/lists/listinfo/assimp-discussions 
+
+
+------------------------------
 4. License
-
-The license of the Asset Import Library is based on the BSD-License. It is contained in the LICENSE file.
+------------------------------
+
+The license of the Asset Import Library is based on the modified, 3-clause BSD-License,
+which is a very liberal license. An _informal_ summary of the license is: do whatever 
+you want, but include Assimp's license text with your product - and don't sue us
+if it doesn't work.
+
+For the formal details, see the LICENSE file. 
+

doc/dox.h

@@ -130,6 +130,7 @@ assimp-discussions</a>.
 /**
 @page install Installation
 
+
 @section install_prebuilt Using the pre-built libraries with Visual C++ 8/9
 
 If you develop at Visual Studio 2005 or 2008, you can simply use the pre-built linker libraries provided in the distribution.
@@ -148,18 +149,16 @@ run and use the application. If the linker complains about some integral functio
 mixed the runtimes. Recheck the project configuration (project properties -&gt; C++ -&gt; Code generation -&gt; Runtime) if you use 
 static runtimes (Multithreaded / Multithreaded Debug) or dynamic runtimes (Multithreaded DLL / Multithreaded Debug DLL).
 Choose the ASSIMP linker lib accordingly. 
-<br>
+<br><br>
 Please don't forget to also read the @ref assimp_stl section on MSVC and the STL.
 
-@section assimp_stl Microsoft Compilers & STL
+@section assimp_stl Microsoft Compilers and the C++ Standard Library 
 
-In VC8 and VC9 Microsoft has introduced some STL debugging features. A good example are improved iterator checks and
-various useful debug checks. Actually they are really helpful for debugging, but they're extremely slow. They're
-so extremely slow that they can make the STL up to 100 times slower (imagine a <i>std::vector<T>::operator[] </i>
-performing 3 or 4 single checks! scary ...).
+In VC8 and VC9 Microsoft introduced some Standard Library debugging features. A good example are improved iterator checks and
+various useful debug checks. The problem is the performance penalty that incurs with those extra checks.
 
-These security enhancements are - thanks MS! - also active in release builds, rendering ASSIMP several times 
-slower. However, it is possible to disable them by defining
+Most of these security enhancements are active in release builds by default, rendering ASSIMP several times 
+slower. However, it is possible to disable them by setting
 
 @code
 _HAS_ITERATOR_DEBUGGING=0
@@ -174,11 +173,11 @@ If you do not, there are two binary incompatible STL versions mangled together a
 Alternatively you can disable the fast STL settings for ASSIMP by removing the 'FastSTL' property sheet from
 the vc project file.
 
-<i>If you're using ASSIMP in a DLL:</i> It's ok. There's no STL used in the DLL interface, so it doesn't care whether
+<i>If you're using ASSIMP in a DLL/SO:</i> It's ok. There's no STL used in the binary DLL/SO interface, so it doesn't care whether
 your application uses the same STL settings or not.
 <br><br>
 Another option is to build against a different STL implementation, for example STlport. There's a special 
-@ref assimp_stlport section which describes how to achieve this.
+@ref assimp_stlport section that has a description how to achieve this.
 
 
 @section install_own Building the library from scratch
@@ -191,12 +190,12 @@ it for yourself. Read the "Getting Started" section of the Boost documentation f
 can use a comfortable installer from <a href="http://www.boost-consulting.com/products/free">
 http://www.boost-consulting.com/products/free</a>. Choose the appropriate version of boost for your runtime of choice.
 
-<b>If you don't want to use boost</b>, you can build against our <i>"Boost-Workaround"</i>. It consists of very small (dummy)
+<b>If you don't want to use boost</b>, you can build against our <i>"Boost-Workaround"</i>. It consists of very small 
 implementations of the various boost utility classes used. However, you'll loose functionality (e.g. threading) by doing this. 
-So, if it is possible to use boost, you should use boost. See the @link use_noboost NoBoost-Section @endlink 
-later on this page for more details.
+So, if you can use boost, you should use boost. Otherwise, See the @link use_noboost NoBoost-Section @endlink 
+later on this page for the details of the workaround.
 
-Once boost is working, you have to set up a project for the ASSIMP library in your favourite IDE. If you use VC2005 or
+Once boost is working, you have to set up a project for the ASSIMP library in your favorite IDE. If you use VC2005 or
 VC2008, you can simply load the solution or project files in the workspaces/ folder, otherwise you have to create a new 
 package and add all the headers and source files from the include/ and code/ directories. Set the temporary output folder
 to obj/, for example, and redirect the output folder to bin/. Then build the library - it should compile and link fine.
@@ -210,15 +209,16 @@ your solution.
 @section use_noboost Building without boost.
 
 The Boost-Workaround consists of dummy replacements for some boost utility templates. Currently there are replacements for
-<ul>
-<li><i>boost.scoped_ptr</i></li>
-<li><i>boost.scoped_array</i></li>
-<li><i>boost.format</i> </li>
-<li><i>boost.random</i> </li>
-<li><i>boost.common_factor</i> </li>
-<li><i>boost.foreach</i> </li>
-<li><i>boost.tuple</i></li>
-</ul>
+
+ - boost.scoped_ptr
+ - boost.scoped_array
+ - boost.format
+ - boost.random
+ - boost.common_factor
+ - boost.foreach
+ - boost.tuple
+ - boost.make_shared
+
 These implementations are very limited and are not intended for use outside ASSIMP. A compiler
 with full support for partial template specializations is required. To enable the workaround, put the following in
 your compiler's list of predefined macros: 
@@ -233,49 +233,29 @@ See the @ref assimp_st section
 for more details.
 
 
-@section assimp_make Build with MAKE
-
-To build Assimp with MAKE, navigate to the <tt>code</tt> directory and run 
-@code
-make
-@endcode
-respectively 
-@code
-make -fmakefile.mingw
-@endcode
-for mingw-make. For a <i>-noboost</i>-Build, append 
-@code
-NOBOOST=1
-@endcode
-
-@section assimp_st Single-threaded build
-
--- currently there is no difference between single-thread and normal builds --
 
 
-@section assimp_dll DLL build
+@section assimp_dll Windows DLL Build
 
 ASSIMP can be built as DLL. You just need to select a -dll config from the list of project
-configs and you're fine. Don't forget to copy the DLL to the directory of your executable :-)
+configs and you're fine.
 
-<b>NOTE:</b> Theoretically ASSIMP-dll can be used with multithreaded (non-dll) runtime libraries, 
-as long as you don't utilize any non-public stuff from the code dir. However, if you happen
-to encounter *very* strange problems try changing the runtime to multithreaded (Debug) DLL.
+<b>NOTE:</b> Theoretically, assimp-dll can be used with multithreaded (non-dll) runtime libraries, 
+as long as you don't utilize any non-public stuff from the code folder. However, if you happen
+to encounter *very* strange problems, try changing the runtime to <i>Multithreaded (Debug) DLL</i>.
 
 @section assimp_stlport Building against STLport
 
-If your compiler's default implementation of the STL is too slow, lacks some features,
-contains bugs or if you just want to tweak ASSIMP's performance a little try a build
-against STLport. STLport is a free, fast and secure STL replacement that works with
-all major compilers and platforms. To get it visit their website at
-<a href="http://www.stlport.org"/><stlport.org></a> and download the latest STLport release.
-Usually you'll just need to run 'configure' + a makefile (see the README for more details).
+STLport is a free, fast and secure STL replacement that works with
+all major compilers and platforms. To get it, download the latest release from
+<a href="http://www.stlport.org"/><stlport.org></a>.
+Usually you'll just need to run 'configure' + a makefile (see their README for more details).
 Don't miss to add <stlport_root>/stlport to your compiler's default include paths - <b>prior</b>
-to the directory where the compiler vendor's STL lies. Do the same for  <stlport_root>/lib and
+to the directory where your compiler vendor's headers lie. Do the same for  <stlport_root>/lib and
 recompile ASSIMP. To ensure you're really building against STLport see aiGetCompileFlags().
 <br>
-Usually building ASSIMP against STLport yields a better overall performance so it might be
-worth a try if the library is too slow for you.
+In our testing, STLport builds tend to be a bit faster than builds against Microsoft's
+C++ Standard Library.
 
 */