NOTE: Update documentation; CHANGED: Ignore the documentation directory

diff --git a/.gitignore b/.gitignore
index 1943c7575147dd8e33b28776c77a6160b5f92630..ef9d01a1555fcb06ba441cb91fbdf3a17c563e70 100644 (file)
--- a/.gitignore
+++ b/.gitignore
@@ -1,5 +1,6 @@
 .DS_Store
 CHANGELOG-UNRELEASED
+documentation
 
 # Developer Tools
 *.pbxuser

diff --git a/README.md b/README.md
index 1deb88279d86e866cad14270826fde64aee1a0c9..648068d117acdd6cf5ee831c383ce00f506faf62 100644 (file)
--- a/README.md
+++ b/README.md
@@ -205,6 +205,32 @@ Clean out the `build` directory.  Be sure to run this before running another
 command.
 
 
+## Git Submodules ##
+
+Apparently, submodules are a rather controversial feature in git.  For me,
+however, they have proven invaluable.  My most active projects depend on each
+other, and the submodule feature allows me to easily keep everything up to
+date.  That said, however, I quickly realized that submodules don't work very
+well using default commands.
+
+The problem is that I want to always use the latest version of my submodules.
+This is more easily accomplished when the submodule is set to the `master`
+branch of the original repository, rather than a detached commit as happens
+by default.  In order to easily keep all submodules updated, there are two 
+scripts:
+
+1. `link_git_modules` -- this script is generally only run when the master
+repository is first cloned, but can also be run after a new submodule is 
+added.  It causes the submodules to automatically track the master branch.
+If you need to modify this, there are instructions in the script itself 
+explaining how to modify it on a per submodule basis.  Running this script 
+more than one time will not hurt anything.
+
+2. `update_git_modules` -- this script simply causes each submodule to be
+updated to the latest commit in the original repository.  Again, running it
+multiple times doesn't hurt anything.
+
+
 ## Source File Templates ##
 
 In the `templates` directory are two files, `template.c.in` and

diff --git a/templates/README.md.in b/templates/README.md.in
index 95fde4a62d29c903f4dd1c3d5f6cf89eb923bb2e..b2d218b38ecd7523b8c8203848acc4ea49a53232 100644 (file)
--- a/templates/README.md.in
+++ b/templates/README.md.in
@@ -205,6 +205,32 @@ Clean out the `build` directory.  Be sure to run this before running another
 command.
 
 
+## Git Submodules ##
+
+Apparently, submodules are a rather controversial feature in git.  For me,
+however, they have proven invaluable.  My most active projects depend on each
+other, and the submodule feature allows me to easily keep everything up to
+date.  That said, however, I quickly realized that submodules don't work very
+well using default commands.
+
+The problem is that I want to always use the latest version of my submodules.
+This is more easily accomplished when the submodule is set to the `master`
+branch of the original repository, rather than a detached commit as happens
+by default.  In order to easily keep all submodules updated, there are two 
+scripts:
+
+1. `link_git_modules` -- this script is generally only run when the master
+repository is first cloned, but can also be run after a new submodule is 
+added.  It causes the submodules to automatically track the master branch.
+If you need to modify this, there are instructions in the script itself 
+explaining how to modify it on a per submodule basis.  Running this script 
+more than one time will not hurt anything.
+
+2. `update_git_modules` -- this script simply causes each submodule to be
+updated to the latest commit in the original repository.  Again, running it
+multiple times doesn't hurt anything.
+
+
 ## Source File Templates ##
 
 In the `templates` directory are two files, `template.c.in` and