Docs: include BuildingOgre.md in the doxygen documentation

BuildingOgre.md

@@ -1,10 +1,7 @@
-GUIDE TO BUILDING OGRE
-========================================================================
+# Guide to building OGRE {#building-ogre}
 
 Ogre uses [CMake](https://cmake.org/) as its build system on all supported platforms.
-This guide will explain to you how to use CMake to build Ogre from source.
-CMake is available from https://cmake.org/download/. You need a CMake
-version >= 3.3.
+This guide will explain to you how to use CMake to build Ogre from source. You need a CMake version >= 3.3.
 
 What is CMake?
 -------------------
@@ -27,7 +24,7 @@ dir stays clean, and you can have multiple build directories all
 working from the same Ogre source.
 
 Getting dependencies
--------------------------
+--------------------
 
 By default ogre will build the essential dependencies automatically when you run cmake the first time. If you would rather use system wide libraries set `OGRE_BUILD_DEPENDENCIES=OFF`.
 
@@ -72,18 +69,17 @@ then build it according to its documentation.
 (+) can be used for threading instead of `std::thread`
 
 Running CMake
-------------------
+-------------
 
 Now start the program cmake-gui by either typing the name in a console
 or selecting it from the start menu. In the field *Where is the source
 code* enter the path to the Ogre source directory (the directory which
 contains this file). In the field *Where to build the binaries* enter
 the path to the build directory you created.
 Hit *Configure*. A dialogue will appear asking you to select a generator.
-Choose the appropriate one for your platform and compiler.
 
 Check the [CMake documentation](https://cmake.org/cmake/help/latest/manual/cmake-generators.7.html) for details on which one is appropriate for your platform and compiler.  
-**Note** on OSX, you must to use the Xcode generator to get a proper SampleBrowser .app bundle.
+@note on OSX, you must to use the Xcode generator to get a proper SampleBrowser .app bundle.
 
 Click *Finish*. CMake will now gather some information about your
 build environment and try to locate the dependencies. It will then show
@@ -93,53 +89,51 @@ particular component from being built. Once you are satisfied, hit
 *Configure* again and then click on *Generate*. CMake will then create
 the build system for you.
 
-Building Ogre
-------------------
+Building
+--------
 
 Go to your chosen build directory. CMake has generated a build system for
 you which you will now use to build Ogre. If you are using Visual Studio,
 you should find the file OGRE.sln. Open it and compile the target
 *BUILD_ALL*. Similarly you will find an Xcode project to build Ogre
-on MacOS. If you rather want to trigger the build form a console, then
- cd to your build directory and call the appropriate make
-program as
+on MacOS. 
+
+If you rather want to trigger the build form a console, then cd to your build directory and call the appropriate make program as
 
     cmake --build . --config release
 
 to start the build process.
+
 If you have doxygen installed and CMake picked it up, then there will
 be an additional build target called *OgreDoc* which you can optionally build.
-This will freshly generate the API documentation for Ogre's classes from
-the header files. In Visual Studio, just select and build the target
-*OgreDoc*, on Linux type:
+This will freshly generate the API documentation for Ogre's classes from the header files. In Visual Studio, just select and build the target *OgreDoc*, on Linux type:
 
      make OgreDoc
 
 
-Installing Ogre
---------------------
+Installing
+----------
 
 Once the build is complete, you can optionally have the build system
 copy the built libraries and headers to a clean location. We recommend
 you do this step as it will make it easier to use Ogre in your projects.
 In Visual Studio, just select and build the target *INSTALL*. For Makefile based generators, type:
 
-```sh
-make install  # (or sudo make install, if root privileges are required)
-```
+
+    make install  # (or sudo make install, if root privileges are required)
+
 
 On Linux Ogre will be installed to `/usr/local` by default. On Windows this will create the folder `sdk` inside your build directory and copy all the
 required libraries there. You can change the install location by changing the variable `CMAKE_INSTALL_PREFIX` in CMake.
 
 
-Building Ogre on Mac OS X for iOS OS
---------------------------------------------
+Building on Mac OS X for iOS OS
+-------------------------------
 
 To build Ogre for iOS, you need to specify the ios cross toolchain to cmake as
 
-```
-cmake -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain/ios.toolchain.xcode.cmake -G Xcode .
-```
+    cmake -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain/ios.toolchain.xcode.cmake -G Xcode .
+
 
 Unfortunately, you will now have to do a few manual steps to
 make the generated build system work properly.
@@ -159,7 +153,7 @@ the Info.plist file to match the App ID of the chosen code signing identity.
 This can be done from the Target Properties panel.  It must match the bundle
 identifier of a valid developer certificate if you are building for devices.
 
-Building Ogre as Windows Store or Windows Phone application
+Building as Windows Store or Windows Phone application
 -------------------------------------------------------------------
 
 You need Windows 8.0 or later, Windows 10 is recommended.
@@ -210,32 +204,26 @@ All versions of Visual Studio 2012 have a window refresh issue when running
 in VMware and the window is maximized, the solution is just to change the
 size of the Visual Studio window to be less the the screen width and height.
 
-Building Ogre on Ubuntu for Android
+Building on Ubuntu for Android
 --------------------------------------------
 
 To build Ogre for Android, you need to specify the ios cross toolchain to cmake as
 
-```
-cmake -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain/android.toolchain.cmake -DANDROID_NDK=path/to/android-ndk .
-```
+    cmake -DCMAKE_TOOLCHAIN_FILE=CMake/toolchain/android.toolchain.cmake -DANDROID_NDK=path/to/android-ndk .
 
 this will build the core Ogre libraries. Also if your `PATH` contains the `android` executable it will generate the SampleBrowser APK.
 
 To manually generate the APK and install it on your device, run
 
-```
-ant debug install
-```
+    ant debug install
 
-Building Ogre for HTML5 (Emscripten)
+Building for HTML5 (Emscripten)
 -----------------------------------------
 Install the Emscripten SDK and make sure that the environment variables are correctly set.
 
 Run cmake in cross compile mode using emscripten as following:
 
-```
-cmake -DCMAKE_TOOLCHAIN_FILE=$EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake .
-```
+    cmake -DCMAKE_TOOLCHAIN_FILE=$EMSCRIPTEN/cmake/Modules/Platform/Emscripten.cmake .
 
 in cmake GUI change `CMAKE_AR` to `emcc`. Then run `make`.
 

Docs/CMakeLists.txt

@@ -46,6 +46,7 @@ if(DOXYGEN_FOUND)
         ${OGRE_SOURCE_DIR}/Docs/src/high-level-programs.md
         ${OGRE_SOURCE_DIR}/Docs/src/particle-scripts.md
         ${OGRE_SOURCE_DIR}/Docs/src/hardware-buffers.md
+        ${OGRE_SOURCE_DIR}/BuildingOgre.md
         ${TUTORIALS}
         ${BASIC_TUTORIALS})
     string(REPLACE ";" " \\\n" CMAKE_DOXYGEN_INPUT_LIST "${CMAKE_DOXYGEN_INPUT_LIST}")

Docs/src/tutorials/setup.md

@@ -1,5 +1,5 @@
 # Setting up an OGRE project {#setup}
-@note see BuildingOgre.md for instructions how to build OGRE itself
+@note see @ref building-ogre for instructions how to build OGRE itself
 # CMake Configuration {#cmake}
 Ogre uses CMake as its build system. It is recommended that you use it in your project as well.  
 Then all you need is to add the following three lines to your project

Docs/src/tutorials/tutorials.md

@@ -1,6 +1,7 @@
 # Tutorials {#tutorials}
 
 - Getting Started
+    - @subpage building-ogre
     - @subpage setup
     - @subpage tut_FirstScene
     - @subpage tut_LightsCamerasShadows