rubygem-asciidoctor/README.adoc

= rubygem-asciidoctor: Asciidoctor RPM package spec

This repository hosts the RPM package spec file for the https://github.com/asciidoctor/asciidoctor[Asciidoctor] library. The package is named `rubygem-asciidoctor`.

== Prerequisites

This RPM spec was developed for Fedora 17 and above, but may be useful for other RPM-based systems.

== Preparing your environment

You first need to install the packages necessary to build the RPM. Begin by installing the `@fedora-packager` group (as root or using sudo):

 yum install @fedora-packager wget

Next, clone this repository and switch to it:

 git clone git://github.com/asciidoctor/rubygem-asciidoctor-rpm.git 
 cd rubygem-asciidoctor-rpm

Finally, install the packages that this build requires (as root or using sudo):

 yum-builddep rubygem-asciidoctor.spec

Next, we need to put the package source and patches in place.

== Preparing the sources

You can build RPMs as a non-privileged user, though you need to prepare the directories first. Let's use the directory rpmbuild in our `$HOME` directory:

 echo "%_topdir %(echo $HOME)/rpmbuild" > $HOME/.rpmmacros

You'll also need to create all the required folders:

 mkdir -p $HOME/rpmbuild/{BUILD,BUILDROOT,RPMS,SOURCES,SPECS,SRPMS}

Next, grab the Asciidoctor gem (the sources) and put it into the `$HOME/rpmbuild/SOURCES` directory:

 wget -O $HOME/rpmbuild/SOURCES/asciidoctor-0.1.1.gem http://rubygems.org/gems/asciidoctor-0.1.1.gem

Finally, copy the `.patch` files from this repository to the same directory:

 cp patches/* $HOME/rpmbuild/SOURCES/

You're now ready to build the RPM.

== Building the RPM

With everything in place, building the RPM is easy!

 rpmbuild -ba rubygem-asciidoctor.spec

If all goes well, both the binary and source RPMs will emerge in the `$HOME/rpmbuild/RPMS/noarch` and `$HOME/rpmbuild/SRPMS` directories, respectively.

== Installing the RPM

There's nothing special about installing this RPM. I recommend using `yum` because it will install any dependencies that the package requires (though you should already have them if you built the RPM).

 yum localinstall $HOME/rpmbuild/RPMS/noarch/rubygem-asciidoctor-0.1.1.rpm

Now, it's time to start using Asciidoctor!

== Basic Asciidoctor usage

Create a file named asciidoctor-test.rb and populate it with the following code:

  require 'asciidoctor'
  content = "= My First Document\n\nRender me some **HTML**!"
  puts Asciidoctor.render(content, :header_footer => true, :compact => true)

Now execute the file with Ruby:

 ruby asciidoctor-test.rb

You should see the HTML output to your terminal. You can update your script to write it to a file, or just redirect the output:

 ruby asciidoctor-test.rb > test.html

Open up your browser to see the result!