simon-m-mudd/book_template

An asciidoctor book template. Use it to make books and websites. See readme below for instructions on how to convert this into your own repository.

A book template

This is a template for a book or website written with asciidoctor. The resulting template website looks like this: http://simon-m-mudd.github.io/Book_template/. If you want to make your own website or book just clone this repository. You will meed to install ruby, rubygems and bundler to get it working.

Install the ruby package bundler using

$ gem install bundler

1. Turning these files into pdf or html

Note	If you want to set up your own book and website, skip to the next section. These instructions are just for turning the template into pdf and html files.

We will use bundler, which manages asciidoctor and a a bunch of other stuff, to turn these files into pdf and html. The template files do this work for you so all you need to do to egt started is install ruby, rubygems and bundler and then clone this repository 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 an html only version:

$ 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. This is a particular problem on Windows systems, where sometimes windows will stupidly not let you delete the thumbs.db file it automatically generates. To get around this, right click on the images directory and unselect read only, then you should be able to delete the folder. In general, however, as long as you do not look in the images directory you will not have this problem.

1.1. Quick build asciidoctor (i.e., not using bundler)

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

$ gem install asciidoctor
$ asciidoctor Book_template_top.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).

2. If you want to set up your own book, and have an associated website on github.io

1. The point of this template is to allow you to build a nice book that is easily converted to html. One nice place to host this website is github. These are instructions for starting your own book using the template, and setting it up as a github.io website.

2. The first thing you need to do is make a directory for your very own book. Lets call it MyBook. Go into MyBook and clone this template into a directory called master:

   $ mkdir MyBook
   $ cd MyBook
   $ git clone https://github.com/simon-m-mudd/Book_template.git master

3. Next, delete the .git directory inside the master directory.

4. At this point you might want to rename some of the files and folders to suit your new book or website. If you forget to do this you can always change the names of files and directories by using the git mv command.

5. Now use git init to start a new repository and then add and commit the files.

   $ cd master
   $ git init
   $ git add .
   $ git commit -m "Added the files" .

6. Now start a new repository on github without a readme.

7. It will give you the remote name. Add it to the repository:

   $ git remote add origin https://github.com/MYUSERNAME/MYREPONAME.git
   $ git push origin master

   You will need to replace MYUSERNAME and MYREPONAME with the appropraite names.

8. Refresh the github repository page. You should see all the files from the template.

9. Now on the repository page, look above the files: you should see a tab for "Branches". Click on this and make a new branch called gh-pages. + Now go back into your terminal window, go down a level using cd .., and clone the gh-pages branch.

   $ cd ..
   $ git clone https://github.com/MYUSERNAME/MYREPONAME.git gh-pages

10. Go into the gh-pages directory, check out the gh-pages branch, and delete the master branch (it will only delete the master branch form this directory).

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

11. You gh-pages branch is still full of rubbish you don’t need. Remove it all. Then make a dummy index page.

    $ git rm -rf .
    $ echo "My Page" > index.html
    $ git add index.html
    $ git commit -m "Added the index" .
    $ git push origin gh-pages

12. Go back to the master folder and build the book:

    $ cd ..
    $ cd master
    $ bundle exec rake book:build_html

    Warning

    If you are on Windows and using git bash, it will not recognise Ruby commands, so you will need to open a separate powershell window to run the bundle command. This should not be a problem on Linux and MacOS.

13. This will create a directory called images and an html file called My_book.html.

14. Rename My_book.html to index.html and copy it as well as the images directory into the gh-pages directory.

15. Now go back into the gh-pages directory, add the images directory, and then commit and push the changes (the below commands assume you are sitting in the master directory):

    $ cd ..
    $ cd gh-pages
    $ git add images
    $ git commit -m "Updated the website" .
    $ git push origin gh-pages

    Important

    You MUST push to the gh-pages branch!! When you work in the master directory you push and pull to the master branch, and when you work in the gh-pages folder you push and pull from the gh-pages branch! If you mess this up you might have some painful cleaning up to do.

16. Okay, you should now be able to look at your website on: http://MYUSERNAME.github.io/MYREPONAME, where MYUSERNAME is your github username and MYREPONAME is the name of the repo in which you stored your new book.

3. If you are making changes to this template

Note	You can ignore this unless you are helping write the template and have push permission. Currently this applies to nobody so they are more notes for myself to remember how I set up this repository.

I 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/simon-m-mudd/book_template.git master
   $ git clone https://github.com/simon-m-mudd/book_template.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/book_template/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 My_book.html to index.html and copy to the gh-pages folder.

   $ pwd
   my/path/to/repo/book_template/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/book_template/gh-pages/
   $ git push -u origin gh-pages

4. Some notes on installing Ruby for LSDTopoTools.

After a number of painful windows installations, we have decided that life in linux is much easier. If you don’t have linux you can make a little linux machine in your own computer using virtualbox and vagrant.

1. We will assume you are using Ubuntu in a vagrant box. We will use rvm to get everything working.

2. We need to install some software first:

   $ sudo apt-get install software-properties-common
   $ sudo apt-add-repository -y ppa:rael-gc/rvm
   $ sudo apt-get update
   $ sudo apt-get install rvm

   Then you need to logout of vagrant. It says that

   Creating group 'rvm'
   
   Installing RVM to /usr/share/rvm/
   Installation of RVM in /usr/share/rvm/ is almost complete:
   
     * First you need to add all users that will be using rvm to 'rvm' group,
       and logout - login again, anyone using rvm will be operating with `umask u=rwx,g=rwx,o=rx`.
   
     * To start using RVM you need to run `source /etc/profile.d/rvm.sh`
       in all your open shell windows, in rare cases you need to reopen all shell windows.

3. So after running vagrant halt and vagrant up, do the command:

   $ source /etc/profile.d/rvm.sh

4. To see what users are in the group:

   $ getent group rvm

5. To add the vagrant user:

   $ sudo usermod -a -G rvm vagrant
   $ getent group rvm

6. In my installation you cannot just start installing stuff, you need to open a new terminal. So use either ssh (linux or MacOS) or putty.exe (windows) to open a new terminal.

7. In your new terminal run (Warning: this takes a long time!):

   $ rvm install 2.3

8. I wanted to make sure we use this ruby default:

   $ rvm use --default 2.3

9. Then install bundler:

   $ gem install bundler

10. Now I went into a documentation folder and used bundle install. The gemfile is:

    source 'https://rubygems.org'
    
    gem 'rake'
    gem 'asciidoctor'
    
    gem 'json'
    gem 'awesome_print'
    
    gem 'asciidoctor-epub3'
    gem 'asciidoctor-pdf'
    
    gem 'coderay'
    gem 'pygments.rb'
    gem 'thread_safe'
    gem 'epubcheck'

11. Yay, all the gems are installed! You can now compile our docs with:

    $ bundle exec rake book:build_html

4.1. If you want to make pdf files using asciidoctor with equation in them

Forget about doing this in Windows. Follow the instructions above on getting rvm installed on Linux.

1. First, you need to install a bunch of stuff (this works in Ubuntu):

   $ sudo apt-get -qq -y install bison flex libffi-dev libxml2-dev libgdk-pixbuf2.0-dev libcairo2-dev libpango1.0-dev ttf-lyx

2. Now run bundle install with this Gemfile:

   source 'https://rubygems.org'
   
   gem 'rake'
   gem 'asciidoctor'
   
   gem 'json'
   gem 'awesome_print'
   
   gem 'asciidoctor-mathematical'
   gem 'asciidoctor-epub3'
   gem 'asciidoctor-pdf'
   
   gem 'coderay'
   gem 'pygments.rb'
   gem 'thread_safe'
   gem 'epubcheck'

3. Now, this is annoying. To get the pdf to work, you need to designate an :imagesoutdir: but a relative path will not work. So you need an absolute path in your root .asc file. So, for example, the root .asc file should contain the directives:

   :stem: latexmath
   :imagesoutdir: /LSDTopoTools/Git_projects/LSDTopoTools_ChiMudd2014/Documentation/images

4. You need to change this line to suit your path!