Merge pull request #149 from tpmccallum/master

Update documentation

AUTHORS.md

@@ -7,6 +7,7 @@ Thanks to everyone who has contributed to this project (in alphabetical order):
 * adam-nielsen
 * Malvineous
 * sukoi26
+* tpmccallum
 * xpol
 
 Project logo designed by Thomas Fussell.

docs/introduction/Examples.md

@@ -129,3 +129,62 @@ time ./process
 real	0m0.044s
 ```
 ### Simple - writing values to a new xlsx spread sheet.
+```
+#include <iostream>
+#include <xlnt/xlnt.hpp>
+#include <vector>
+#include <string>
+
+int main()
+{
+    //Creating a 2 dimensional vector which we will write values to
+    std::vector< std::vector<std::string> > wholeWorksheet;
+    //Looping through each row (100 rows as per the second argument in the for loop)
+    for (int outer = 0; outer < 100; outer++)
+    {
+        //Creating a fresh vector for a fresh row
+	std::vector<std::string> singleRow;
+	//Looping through each of the columns (100 as per the second argument in the for loop) in this particular row
+	for(int inner = 0; inner < 100; inner++)
+	{
+	    //Adding a single value in each cell of the row 
+	    std::string val = std::to_string(inner + 1);
+	    singleRow.push_back(val);			
+	}
+	//Adding the single row to the 2 dimensional vector
+	wholeWorksheet.push_back(singleRow);
+	std::clog << "Writing to row " << outer << " in the vector " << std::endl;
+    }
+    //Writing to the spread sheet
+    //Creating the output workbook 
+    std::clog << "Creating workbook" << std::endl;
+    xlnt::workbook wbOut;
+    //Setting the destination output file name
+    std::string dest_filename = "output.xlsx";
+    //Creating the output worksheet
+    xlnt::worksheet wsOut = wbOut.active_sheet();
+    //Giving the output worksheet a title/name
+    wsOut.title("data");
+    //We will now be looping through the 2 dimensional vector which we created above
+    //In this case we have two iterators one for the outer loop (row) and one for the inner loop (column)
+    std::clog << "Looping through vector and writing to spread sheet" << std::endl;
+    for (int fOut = 0; fOut < wholeWorksheet.size(); fOut++)
+    {
+        std::clog << "Row" << fOut << std::endl;
+        for (int fIn = 0; fIn < wholeWorksheet.at(fOut).size(); fIn++)
+        {
+            //Take notice of the difference between accessing the vector and accessing the work sheet
+	    //As you may already know Excel spread sheets start at row 1 and column 1 (not row 0 and column 0 like you would expect from a C++ vector) 
+	    //In short the xlnt cell reference starts at column 1 row 1 (hence the + 1s below) and the vector reference starts at row 0 and column 0
+	    wsOut.cell(xlnt::cell_reference(fIn + 1, fOut + 1)).value(wholeWorksheet.at(fOut).at(fIn));
+	    //Further clarification to avoid confusion
+	    //Cell reference arguments are (column number, row number); e.g. cell_reference(fIn + 1, fOut + 1)
+	    //Vector arguments are (row number, column number); e.g. wholeWorksheet.at(fOut).at(fIn)
+	}
+    }
+    std::clog << "Finished writing spread sheet" << std::endl;
+    wbOut.save(dest_filename); 
+    return 0;
+}
+```
+This process is also quite quick; a time command showed that xlnt was able to create and write 10, 000 values to the output spread sheet in 0.582 seconds.

docs/introduction/Installation.md

@@ -8,42 +8,23 @@
 
 ## vcpkg
 
-## Compiling from Source - Ubuntu 16.04 LTS (Xenial Xerus) 
-Please run the following commands and read the comments as you go.
-You will notice that we update and upgrade quite frequently, this is to ensure that all dependancies are met at all times. You will also notice that we are installing some libraries from source, there are two reasons for this; firstly in the event that the library is not available through apt-get or secondly, because we want the very latest version (not the version available in apt-get).
+## Compiling xlnt 1.x.x from Source on Ubuntu 16.04 LTS (Xenial Xerus) 
+Time required: Approximately 5 minutes (depending on your internet speed)
 ```
 sudo apt-get update
 sudo apt-get upgrade
 sudo apt-get install cmake
 sudo apt-get install zlibc
+```
+The following steps update the compiler and set the appropriate environment variables - see note [1] below for the reason why we need to update the standard available compiler
+```
 sudo add-apt-repository ppa:ubuntu-toolchain-r/test
 sudo apt update
 sudo apt-get upgrade
 sudo apt-get install gcc-6 g++-6
-sudo apt update
-sudo apt-get upgrade
-```
-The following steps will set up some environment variables for this session
-```
 export CC=/usr/bin/gcc-6  
 export CXX=/usr/bin/g++-6
 ```
-The following steps will install the latest GCC compiler from source (you will notice that we installed GCC 6 using apt-get, this was a building block to the next step of getting GCC 6.3.0 - the latest compiler available at present).
-Download gcc 6.3.0 from https://gcc.gnu.org/mirrors.html I used the Japanese mirror as this is the closest location to me http://ftp.tsukuba.wide.ad.jp/software/gcc/releases/gcc-6.3.0/gcc-6.3.0.tar.gz
-
-```
-cd ~
-tar -zxvf Downloads/gcc-6.3.0.tar.gz
-cd gcc-6.3.0
-./contrib/download_prerequisites
-mkdir build
-cd build
-../configure --disable-multilib --enable-languages=c,c++
-make -j 2
-sudo make install
-```
-If the above make command fails please use "make clean pristine" and then remove and remake the build directory. This will clean up and prepare the environment for another attempt. A common reason for failure on virtual machines is lack of RAM (if you don't have enough RAM you may get an error like this "recipe for target 's-attrtab' failed"). Otherwise, if all goes well in about 30 to 60 minutes the compiler will be ready and we will move on to the next steps.
-
 The following steps will intall xlnt
 Download the zip file from the xlnt repository
 https://github.com/tfussell/xlnt/archive/master.zip
@@ -61,6 +42,10 @@ sudo ldconfig
 ```
 xlnt will now be ready to use on your Ubuntu instance. 
 
+[1] 
+Xlnt requires a minimum of gcc 6.2.0
+The most recent gcc version available using the standard APT repositories is gcc 5.4.0 (obtained through build-essential 12.1ubuntu2). If these older versions of gcc are used an error "workbook.cpp error 1502:31 'extended_property' is not a class, namespace or enumeration" will occur during the xlnt make command.
+
 ## Compiling from Source
 
 Build configurations for Visual Studio, GNU Make, Ninja, and Xcode can be created using [cmake](https://cmake.org/) v3.2+. A full list of cmake generators can be found [here](https://cmake.org/cmake/help/v3.0/manual/cmake-generators.7.html). A basic build would look like (starting in the root xlnt directory):