I use Git a lot. I’m not a terribly sophisticated user, because I don’t do a lot of branching. I mainly use it as a way to keep track of ongoing projects. But sometimes I need to do something a bit more complicated than I am used to and so I head over to the Progit book at https://git-scm.com/book/en/v2 for direction.
I realized at some point that it would be nice to have the pdf version of that book, because I use Okular as a document reader, which allows me to make bookmarks and annotations as needed, which would be more efficient than constantly going back to the website. Fortunately, the friendly folks behind that website give you a link to a pdf version of that book right on the front page, so that you can do exactly that. However, the source code for that book is also available on GitHub, so I decided to take a look. This is what I saw:
I decided that might be a fun thing to try, since I’ve never used Asciidoctor before. I’ve always loved typography, which is why I decided to learn LaTeX, so I thought it might be fun to explore some of the opportunities Asciidoctor might offer. So I opened my terminal, rolled up my sleeves, and got to work.
The first thing to do was to pull down a copy of that repository:
git clone https://github.com/progit/progit2
and then install Asciidoctor. I’m on Ubuntu, so I uses:
sudo apt install asciidoctor
and then, following the instructions on the Progit GitHub page, I tried to make a book:
bundle install
and I failed:
Running ruby -v showed that my Ruby version was, indeed, 3.0.2p107. Time for an upgrade.
Ruby has a couple of command-line tools for managing updates and versions: rvm or the Ruby Version Manager, and rbenv or the other Ruby version manager. I decided to go with rbenv. The first step was to run an update on the package index:
sudo apt update
And then all I had to do was pull down the rbenv installer from its repo on GitHub and pipe it to Bash to run it:
curl -fsSL https://github.com/rbenv/rbenv-installer/raw/HEAD/bin/rbenv-installer | bash
So far, things were looking good:
It took a bit, but I finally got this message, which told me the installation was a success:
I still had to add rbenv to my PATH, as well as make it load automatically by editing my .bashrc file, which would mean that I would also need to reload my .bashrc file. The following three commands accomplished that:
echo 'export PATH="$HOME/.rbenv/bin:$PATH"' >> ~/.bashrc echo 'eval "$(rbenv init -)"' >> ~/.bashrc source ~/.bashrc
I next wanted to see if I had done everything right, so I entered type rbenv into the terminal, and indeed, everything had gone swimmingly:
The only thing I needed to do now was to see which Ruby versions were available to install, so I ran:
rbenv install -l
which told me I had these versions available:
If you remember from the first error message, I needed anything that was 3.1 or greater, as long as it was less than 4.0. I decided to go with 3.3.4, but first I remembered that I needed to install all the dependencies for Ruby first:
sudo apt install curl g++ gcc autoconf automake bison libc6-dev libffi-dev libgdbm-dev libncurses5-dev libsqlite3-dev libtool libyaml-dev make pkg-config sqlite3 zlib1g-dev libgmp-dev libreadline-dev libssl-dev
and then I ran
rbnev install 3.3.4
and it worked:
It’s always nice when software tells you the next thing you need to do, so I ran
rbenv global 3.3.4
Running ruby -v showed this was my new version of Ruby:
I ran bundle install again, and this time it worked. I don’t have a screen cap of the terminal output, because it ran to 145 lines. It also took long enough that I could run and get another cup of coffee.
Then it was time to generate my book:
bundle exec rake book:build_pdf
Which ran without any problem this time:
Finally! After about an hour’s worth of work, I had an exact pdf copy of the book I could have downloaded in about two seconds. But this was far from wasted time. I learned how to upgrade my Ruby install, I learned how to install multiple versions of Ruby and switch between them, and I was introduced to an exciting new piece of software: Asciidoctor. Now I’m wondering what kind of trouble I can get into with Asciidoctor. Stay tuned!
https://techblog.kjodle.net/2024/08/10/managing-your-ruby-version-with-rbenv/
