Use make_dcp example in documentation.

3 files changed, 22 insertions, 90 deletions

diff --git a/Doxyfile b/Doxyfile
index 8b45466a..7e9dd59b 100644
--- a/Doxyfile
+++ b/Doxyfile
@@ -656,6 +656,7 @@ WARN_LOGFILE           =
 # with spaces.
 
 INPUT                  = src \
+		         examples \
                          doc/mainpage.txt
 
 # This tag can be used to specify the character encoding of the source files
@@ -783,7 +784,7 @@ FILTER_SOURCE_PATTERNS =
 # Note: To get rid of all source code in the generated output, make sure also
 # VERBATIM_HEADERS is set to NO.
 
-SOURCE_BROWSER         = NO
+SOURCE_BROWSER         = YES
 
 # Setting the INLINE_SOURCES tag to YES will include the body
 # of functions and classes directly in the documentation.
diff --git a/doc/mainpage.txt b/doc/mainpage.txt
index b73e9164..497b6a01 100644
--- a/doc/mainpage.txt
+++ b/doc/mainpage.txt
@@ -12,96 +12,12 @@ libdcp is distributed under the GNU GPL.
 Creating DCPs
 --
 
-Typical use for creating DCPs might be:
-@code
-#include <libdcp/dcp.h>
-using namespace std;
-
-libdcp::DCP dcp ("My Film DCP", "My Film", libdcp::DCP::FEATURE, 24, 50000);
-
-vector<string> j2k_files;
-j2k_files.push_back ("1.j2c");
-...
-j2k_files.push_back ("50000.j2c");
-
-// These images are 1998x1080 pixels (DCI Flat)
-dcp.add_picture_asset (j2k_files, 1998, 1080);
-
-vector<string> wav_files;
-wav_files.push_back ("L.wav");
-wav_files.push_back ("R.wav");
-wav_files.push_back ("C.wav");
-wav_files.push_back ("Lfe.wav");
-wav_files.push_back ("Ls.wav");
-wav_files.push_back ("Rs.wav");
-dcp.add_sound_asset (wav_files);
-
-dcp.write_xml ();
-
-@endcode
-
-This will create a DCP at 24 frames per second with 50000 frames, writing
-data to a directory "My Film DCP", naming the DCP "My Film" and marking
-as a Feature.  We then add the picture and sound files (which creates
-MXF files inside the DCP directory) and then write the required XML files.
-
-If you want to report progress for long jobs (add_picture_asset() can
-take a long time, in particular, as it must do a lot of disk I/O for
-large DCPs), connect to the libdcp::DCP::Progress signal and report its parameter
-to the user (it will range between 0 for 0% and 1 for 100%) using something like
-
-@code
-void
-report (float p)
-{
-   cout << "We are " << int (p * 100) << "% done.\n";
-}
-
-dcp.Progress.connect (sigc::ptr_fun (&report));
-@endcode
-
-If you can generate content paths algorithmically, you may prefer to do something
-like this:
-
-@code
-
-string
-j2k_path (int frame)
-{
-	stringstream s;
-	s << "my_j2ks/" << frame << ".j2c"
-	return s.str ();
-}
-
-string
-wav_path (libdcp::Channel channel)
-{
-	switch (channel) {
-	case LEFT:
-		return "left.wav";
-	case RIGHT:
-		return "right.wav";
-	}
-
-	return "";
-}
-
-...
-
-// Our images are 1998x1080 (DCI Flat)
-dcp.add_picture_asset (sigc::ptr_fun (&j2k_path), 1998, 1080);
-// We have two sound channels
-dcp.add_sound_asset (sigc::ptr_fun (&wav_path), 2);
-
-...
-
-@endcode
+An example of DCP creation is given in examples/make_dcp.cc.
 
 Reading existing DCPs
 --
 
-Alternatively libdcp can be used to read existing DCPs and examine their content.  You
-might do
+Alternatively libdcp can be used to read existing DCPs and examine their content.  You might do
 
 @code
 #include <libdcp/dcp.h>
diff --git a/examples/make_dcp.cc b/examples/make_dcp.cc
index 41026cc2..5b764393 100644
--- a/examples/make_dcp.cc
+++ b/examples/make_dcp.cc
@@ -17,13 +17,20 @@
 
 */
 
-/* This example file shows how to make a DCP from some JPEG2000 and WAV files
-   using libdcp.
-*/
+/** @file examples/make_dcp.cc
+ *  @brief Shows how to make a DCP from some JPEG2000 and WAV files.
+ */
 
 #include <vector>
 #include <string>
 #include <sigc++/sigc++.h>
+
+/* If you are using an installed libdcp, these #includes would need to be changed to
+#include <libdcp/dcp.h>
+#include <libdcp/picture_asset.h>
+... etc. ...
+*/
+
 #include "dcp.h"
 #include "picture_asset.h"
 #include "sound_asset.h"
@@ -67,6 +74,14 @@ main ()
 
 	/* Now we will create a `sound asset', which is made up of a WAV file for each channel of audio.  Here we're using
 	   stereo, so we add two WAV files to a vector.
+
+	   We could add more files here to use more channels; the file order is:
+	       Left
+	       Right
+	       Centre
+	       LFE (sub)
+	       Left surround
+	       Right surround
 	*/
 	std::vector<std::string> sound_files;
 	sound_files.push_back ("examples/sine_440_-12dB.wav");