• Forum
  • Lounge
  • Asciidoctor and Ruby programming languag

Asciidoctor and Ruby programming language?

Has anyone used Ruby? And Asciidoctor?

I'm askin' since to generate manually a PDF and/or EPUB copy of the "Pro Git, 2nd Edition" eBook can be done with Asciidoctor and Ruby.


The Pro Git, 2nd Edition is now free to download in compiled form and is semi-frequently updated. The last revision was a couple of weeks ago. So eazy-peazy to get the latest version from github.

BUT, I'd like to generate the eBook myself, if'n it ain't too complicated. :)
Last edited on
BUT, I'd like to generate the eBook myself, if'n it ain't too complicated. :)

I did it using WSL on my Windows machine. When I started this I had already downloaded the book's sources into d:/progit2 using Github's web GUI. Then in a cmd.exe instance I ran the command wsl to get a Bash prompt. Note that WSL makes the contents of drive d accessible via the directory ("mount point") called /mnt/d, so I just said cd /mnt/d/progit2 to get started.

Following the instructions you linked, I first tried to execute bundle install but bundle was missing. The error suggested I install ruby-bundler, which helped, but I still could have found the right package via https://packages.ubuntu.com/.

I installed it per the error message. Remember to update the system first:
$ sudo apt update
$ sudo apt upgrade
$ sudo apt install ruby-bundler

When I ran bundle install again I was told that a compatible version of ruby was missing. I'd expect that a package called ruby-bundler would have installed ruby as a dependency, but to make sure I said
$ sudo apt install ruby
I could have chosen a less-intrusive way to check whether it was installed. But now it's definitely installed and its version is 2.7.0. This is outdated according to bundle from above, so I had to build a newer version from source.

From https://www.ruby-lang.org/en/downloads/ I downloaded the stable version 3.2.2 to the root of my d: drive and uncompressed it:
$ cd /mnt/d/; tar zxf ruby-3.2.2.tar.gz; cd ruby-3.2.2
The relevant instructions are in doc/contributing/building-ruby.md

I installed all the dependencies, to be safe:
$ sudo apt install gcc autoconf bison gperf libssl-dev libedit-dev libz-dev libffi-dev libyaml-dev
Note that Ruby 2.7 is a required dependency of Ruby 3.2.2, but I just installed that.
Then I generated the configure script
$ ./autogen.sh
Made a build directory and ran the generated code:
$ mkdir -p build; cd build; ../configure --prefix=/usr/local

Then I built it as my normal user (20 minutes). Building in parallel did not work for me.
$ make
I ran tests:
$ make check
And installed the program (5 minutes)
$ sudo make install

This process created conflicts between the manually-installed ruby 3.2.2 and the junk from the package manager. I removed the packaged stuff as follows.
$ sudo apt remove ruby-bundler ruby;
$ sudo apt autoremove

Then I could make the book:
$ cd /mnt/d/progit2
Because I installed into /usr/local the bundle install needed root:
$ sudo bundle install
Then finally:
$ bundle exec rake book:build

Thanks for pointing me to the book!
Last edited on
I don't use WSL so all the *nix commands are essentially useless to me. Though, if I am following what you did, it isn't all that complicated but does require quite a few steps to "bundle" the book into a usable eBook form.

I downloaded the Ruby installers for x86 and x64, though I only need one of the two, along with the devkit. I haven't yet run the installer, nor gotten the Asciidoctor scripts.

Lazy, and very inexperienced, I guess. Using the Win installers should make it easier.

Thanks for pointing me to the book!

You are very welcome! I ran across the eBook a while back when I first installed Git for Windows over a year ago so I could start learning how to use git and github.


I use the console Bash to pull repos the the GUI to push local copies of my repos to github.

There are other GUI clients available, TortoiseGit is one. I had that installe before I got Git For Windows but never used it. I installed ToroiseSVN at the same time and never really use that as well.

I know I don't properly use git as a version control system as I could/should. The consequences of being an old fart self-taught programming hobbyist. There are lots of gaps in my knowledge and experience that I am only gradually and badly filling in. I learn only what piques my interest. Learning git came about because I wanted to host some "work" I'd done at "modernizing" some old pre-C++11 from-a-book Windows GDI games I have been mucking around with for years.

(Shameless self-promotion plug):


My current "project" is mashing together what I consider to be essential modern updates to Petzold's "Programming Windows" Fifth Edition code.
I don't use WSL so all the *nix commands are essentially useless to me.

Honestly, setting up a VM with VirtualBox and installing the Linux distro of your choice (e.g. Ubuntu) takes like 10 minutes or so.

If you don't want to go trough the Ubuntu installation process, there's even "ready-to-use" VirtualBox images for Ubuntu:

And if you totally refuse to use Linux, not even as a VM, then you could still use Cygwin to get most *nix tools working on Win32:

There are other GUI clients available, TortoiseGit

+1 for TortoiseGit when working on Windows.

The "GUI" that comes with Git for Windows itself is pretty much unusable. You still need Git for Windows for the CLI tools.
Last edited on
I used WSL because getting Windows ports of Linux programs to work usually frustrates me. WSL seems reliable enough.

I've used the VM route too but WSL is sufficient right now for me.
Last edited on
Topic archived. No new replies allowed.