This guide provides all the information you need to become a successful Asciidoctor PDF developer and code contributor! You’ll learn how to retrieve the code from GitHub, execute the tests, build and install the gem, and run the application with your local modifications.
To contribute code, fork the project on GitHub, hack away, and send a pull request with your proposed changes. All pull requests must include a) tests that verify the code change and b) an entry in the CHANGELOG.adoc file to document what changed. If a pull request is missing tests or a CHANGELOG entry, it will not be merged.
Feel free to use the issue tracker or Asciidoctor mailing list to provide feedback or suggestions in other ways.
Follow the instructions below to learn how to clone the source and run it from your local copy.
You can retrieve the source of Asciidoctor PDF in one of two ways:
-
Clone the git repository
-
Download a zip archive of the repository
If you want to clone the git repository, simply copy the GitHub repository URL and pass it to the git clone command:
$ git clone https://github.com/asciidoctor/asciidoctor-pdf
Next, change to the project directory:
$ cd asciidoctor-pdf
If you want to download a zip archive, click the Download Zip button on the right-hand side of the repository page on GitHub. Once the download finishes, extract the archive, open a console and change to that directory.
|
💡
|
Instead of working out of the asciidoctor-pdf directory, you can simply add the absolute path of the bin directory to your PATH environment variable.
|
We’ll leverage the project configuration to install the necessary dependencies.
We recommend using RVM to manage the installation of Ruby you’ll use to build and develop the project.
$ rvm use 2.6
The dependencies needed to use Asciidoctor PDF are defined in the Gemfile at the root of the project. We can use Bundler to install the dependencies for us.
To check you have Bundler available, use the bundle command to query the installed version:
$ bundle --version
If it’s not installed, use the gem command to install it.
$ gem install bundler
Then use the bundle command with the --path option to install the project dependencies into the project:
$ bundle --path=.bundle/gems
|
📎
|
You must call bundle from the project directory so that it can find the Gemfile.
|
Tests are written using RSpec. To run the tests, simply invoke rspec via bundler.
$ bundle exec rspec
To disable tests that access the network, pass the -t ~network option:
$ bundle exec rspec -t ~network
Similarly, to disable the visual integration tests, pass the -t ~visual option:
$ bundle exec rspec -t ~visual
If a visual integration test fails, you can instruct the test suite to keep the files in the spec/output directory by setting the DEBUG environment variable:
$ DEBUG=true bundle exec rspec -t visual
If you want to see the name of each test as it is run, add the -fd option:
$ bundle exec rspec -fd
You can also use the provided Rake task (note the name difference):
$ bundle exec rake spec
Running tests using rspec directly gives you the advantage of being able to specify additional options.
To run a single test, you can filter by the name of the test. For example, to run all tests that pertain to failures, use:
$ bundle exec rspec -e fail
To run all tests that have wip in the name, use:
$ bundle exec rspec -e wip
You can also run all tests in a given file by passing the file’s path to rspec:
$ bundle exec rspec spec/toc_spec.rb
For a full list of options that rspec provides, run rspec -h.
Like with Bundler, you have to run the application from the project directory.
Assuming all the required gems install properly, verify you can run the asciidoctor-pdf script using Ruby:
$ bundle exec asciidoctor-pdf -v
If you see the version of Asciidoctor PDF printed, you’re ready to use Asciidoctor PDF!
You can use the application to convert a document as follows:
$ bundle exec asciidoctor-pdf /path/to/sample.adoc
If you want to install the application globally so you can run it anywhere, use the following rake task:
$ bundle exec rake install
This task will package the gem and install it into your system gems.
If you want to install the gem using a separate command, first use the following rake task to build it:
$ rm -rf pkg bundle exec rake build
This task packages the application as a gem and writes it to the pkg directory.
A message will be printed to the console telling you the exact filename.
You can now use the gem install command to install it.
$ gem install pkg/*.gem
You’ll want to pay attention to which Ruby installation you are installing the gem into.
If successful, the asciidoctor-pdf executable will be available on your PATH.
|
💡
|
If you’re running Asciidoctor PDF in a Gradle build, follow these instructions to use the development version of Asciidoctor PDF. |
To test a pull request (PR), you first need to fetch the branch that contains the change and switch to it. The steps below are covered in detail in the GitHub help.
Let’s assume you want to test PR 955. Here’s how you fetch and switch to it:
$ git fetch origin pull/955/head:pr-955-review git checkout pr-955-review
|
❗
|
Make sure you replace the number with the number of the PR you want to test. |
In case any dependencies have changed, you should run the bundle command again:
$ bundle
Now you can run the application as modified by the PR:
$ bundle exec asciidoctor-pdf /path/to/sample.adoc
To switch back to master, just type:
$ git checkout master
If you’re using Asciidoctor PDF in your application, you can test against the code in the pull request using Bundler.
First, you need to find the origin URL and branch of the PR. You can find this information on the PR page.
Next, update the entry in your project’s Gemfile to point to the branch from which the pull request was originated.
source 'https://rubygems.org'
gem 'asciidoctor-pdf', github: '<username>/asciidoctor-pdf', branch: 'issue-864'Then run Bundler to update the gems in your project:
$ rm -f Gemfile.lock bundle config --local github.https true bundle --path=.bundle/gems --binstubs=.bundle/.bin
Now you can run the development version of Asciidoctor PDF using:
$ bundle exec asciidoctor-pdf input.adoc
or
$ ./.bundle/.bin/asciidoctor-pdf input.adoc
These instructions work for testing any development version of Asciidoctor PDF directly from GitHub.
To generate a code coverage report when running tests using simplecov, set the COVERAGE environment variable as follows when running the tests:
$ COVERAGE=true bundle exec rake spec
You’ll see a total coverage score as well as a link to the HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.
Despite being fast, the downside of using simplecov is that it misses code branches.
You can use deep-cover instead of simplecov to generate a more thorough report.
To do so, first run bundle at least once with the COVERAGE environment variable set:
$ COVERAGE=true bundle
Then, set the COVERAGE environment variable to deep when running the tests:
$ COVERAGE=deep bundle exec rake spec
You’ll see a total coverage score, a detailed coverage report, and a link to HTML report in the output. The HTML report helps you understand which lines and branches were missed, if any.
The formatted text is first converted to a pseudo-HTML language, then converted from there into Prawn text fragments using a treetop parser. treetop is a Ruby-based parsing DSL based on parsing expression grammars. This strategy allows the converter to manipulate the formatted text without needing the know the internal details of how Prawn arranges text fragments. It also allows Asciidoctor to behave in a consistent manner, since some of the inline parsing in Asciidoctor assumes that the converter is generating an SGML-based language like HTML or DocBook.
The parsing expression grammar is defined in the source file lib/asciidoctor/pdf/formatted_text/parser.treetop. If you make a change to this file, you must regenerate the parser, which is defined in the source file lib/asciidoctor/pdf/formatted_text/parser.rb. (Don’t modify the generated parser directly).
Use the following command to regenerate the parser:
bundle exec tt lib/asciidoctor/pdf/formatted_text/parser.treetop
You then need to commit both files.