LSDtopotools / LSDTT_book

Documentation book for LSDTopoTools

LSDTopoTools for Geomorphology, Hydrology, Ecology and Environmental Sciences

Welcome to documentation for Land Surface Dynamics Topographic Tools Geomorphology, Hydrology, Ecology and Environmental Sciences. In this book you will get instructions on how to set up and use the LSDTopoTools software package. The documentation also contains information about the algorithms used in the software and links to associated publications.

Reading these pages as html

These documents live at the website: http://LSDtopotools.github.io/LSDTT_book/

How To generate the book

You will need to have Ruby installed on your computer, as well as RubyGems. You can learn how to install these in the appendices of this book (which you should be able to read in a text editor or on Github).

You then should install the ruby package bundler using

$ sudo gem install bundler

You also need to clone the files into the directory of your choice from Github. Once you have bundler installed, you can build the book with:

$ bundler install
$ bundle exec rake book:build

This will build html and pdf versions of the book. You can also build just the html with:

$ bundler install
$ bundle exec rake book:build_html

Warning

The build process will make a folder called images in the root directory, which on some systems must be deleted before new builds.

Warning

If you are looking at the html pages, you should be aware that the mathematical rendering might not work on older browsers. If you stubbornly resist updating your browser, you can see the math in the pdf version of the book.

Quick build asciidoctor

You can also quickly generate the document by installing asciidoctor, and then running it on the LSDTT_Book.asc file:

$ sudo gem install asciidoctor
$ asciidoctor LSDTT_Book.asc

Warning

This quick generation will give you the text and cross-linking, but the images will not be linked. For images to be properly linked you need to run bundle exec (see above).

If you are making changes to this book

You can ignore this unless you are helping write the book and have push permission.

I (SMM) do not want any messy merging conflicts! To avoid this please keep the master and gh-pages separate on your computer!

1. When checking out the code, check them out into two directories:

   $ git clone https://github.com/LSDtopotools/LSDTT_book.git master
   $ git clone https://github.com/LSDtopotools/LSDTT_book.git gh-pages

2. In the gh-pages directory, check out the gh-pages branch and get rid of the master branch:

   $ cd gh-pages
   $ git checkout origin/gh-pages -b gh-pages
   $ git branch -d master

3. Now, go back to the master branch, you can make changes there.

4. When you commit changes to the master branch and you want to update the website, commit and push changes, then run bundle:

   $ pwd
   my/path/to/repo/LSDTT_book/master/
   $ git commit -m "My latest commit" .
   $ git push -u origin master
   $ bundle exec rake book:build_html

5. Now copy any new image files to the /images folder in the gh-pages branch (you will need to git add them), and rename LSDTT_book.html to index.html and copy to the gh-pages folder.

   $ pwd
   my/path/to/repo/LSDTT_book/gh-pages/
   $ cd images
   $ git add <filenames of new images>
   $ cd ..
   $ git commit "updating website" .

6. Now push the changes to the gh-pages branch

   $ bundle exec rake book:build_html
   $ pwd
   my/path/to/repo/LSDTT_book/gh-pages/
   $ git push -u origin gh-pages