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 *.patch $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!

== Testing the asciidoctor package and reporting feedback

Before the asciidoctor package can be included in the Fedora distribution, it must be tested by users and receive karma via the http://admin.fedoraproject.org/updates/[Bohdi system]. One way to do this is to use http://admin.fedoraproject.org/pkgdb/acls/name/fedora-easy-karma[fedora-easy-karma].

=== Enable the updates-testing repository temporarily

In a terminal, type:

 sudo yum install rubygem-asciidoctor --enablerepo=updates-testing

This command will download and install the asciidoctor package.

=== Test the asciidoctor package

. On your computer, create a new file and name it `asciidoctor-test.rb` 
. Copy and paste the following code into the file.

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

. Save the file.
. In a terminal, navigate to the directory where you saved `asciidoctor-test.rb` and type the following command to execute the file with Ruby:

 ruby asciidoctor-test.rb
+
You should see this output in your terminal.

 <!DOCTYPE html>
 <html lang="en">
   <head>
     <meta http-equiv="Content-Type" content="text/html; charset=UTF-8">
     <meta name="generator" content="Asciidoctor 0.1.1">
     <title>My First Document</title>
   </head>
   <body class="article">
     <div id="header">
       <h1>My First Document</h1>
     </div>
     <div id="content">
 <div id="preamble">
   <div class="sectionbody">
 <div class="paragraph">
   <p>Render me some <strong>HTML</strong>!</p>
 </div>
   </div>
 </div>
     </div>
     <div id="footer">
       <div id="footer-text">
         Last updated 2013-03-12 10:43:15 MDT
       </div>
     </div>
   </body>
 </html>

. You can render the output as HTML using:

 ruby asciidoctor-test.rb > test.html

. Open your browser to see the result. Or, if you're using Gnome, type:

 gnome-open test.html
+
A new tab should open in your current browser session.

=== Provide feedback with fedora-easy-karma

. If you don't have fedora-easy-karma installed on your computer, type the following command in a terminal.

 sudo yum --enablerepo=updates-testing install fedora-easy-karma

. Once fedora-easy-karma is installed, run it in the terminal.

 fedora-easy-karma --fas-username yourFASaccount *asciidoctor
+
To be on the safe side, include the flag for your FAS account when you start fedora-easy-karma. Once fedora-easy-karma runs, you will not be able to switch accounts.
NOTE: It may take fedora-easy-karma several minutes to fetch the list of packages in updates-testing.
+
When fedora-easy-karma finds `rubygem-asciidoctor`, it will display a summary of the package and prompt you to give -1 (negative), 0 (neutral), or 1 (postive) karma to the package. For more information about providing karma for packages and how to comment on packages, review the http://fedoraproject.org/wiki/QA:Update_feedback_guidelines[Fedora feedback guidelines].

. Enter your karma rating.
. Next, you will be asked to provide additional, detailed feedback. Please comment whether the package worked as expected and you successfully used it, if you think you may have encountered an error, but aren't sure, or if you definitely encountered a bug.
. When prompted, enter your FAS password.
. W00t! The feedback process is complete.
add README 2012-12-19 11:37:43 +00:00			`= rubygem-asciidoctor: Asciidoctor RPM package spec`

update Asciidoctor URL, change extension of file 2013-03-06 22:39:17 +00:00			This repository hosts the RPM package spec file for the https://github.com/asciidoctor/asciidoctor[Asciidoctor] library. The package is named `rubygem-asciidoctor`.
add README 2012-12-19 11:37:43 +00:00
			`== Prerequisites`

update git url 2013-03-06 12:16:58 +00:00			`This RPM spec was developed for Fedora 17 and above, but may be useful for other RPM-based systems.`
add README 2012-12-19 11:37:43 +00:00
			`== Preparing your environment`

update to 0.1.1, add wget install command, update test script 2013-03-01 17:47:57 +00:00			You first need to install the packages necessary to build the RPM. Begin by installing the `@fedora-packager` group (as root or using sudo):
add README 2012-12-19 11:37:43 +00:00
update to 0.1.1, add wget install command, update test script 2013-03-01 17:47:57 +00:00			`yum install @fedora-packager wget`
add README 2012-12-19 11:37:43 +00:00
			`Next, clone this repository and switch to it:`

update git url 2013-03-06 12:16:58 +00:00			`git clone git://github.com/asciidoctor/rubygem-asciidoctor-rpm.git`
			`cd rubygem-asciidoctor-rpm`
add README 2012-12-19 11:37:43 +00:00
update to 0.1.1, add wget install command, update test script 2013-03-01 17:47:57 +00:00			`Finally, install the packages that this build requires (as root or using sudo):`
add README 2012-12-19 11:37:43 +00:00
			`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:

update to 0.1.1, add wget install command, update test script 2013-03-01 17:47:57 +00:00			`wget -O $HOME/rpmbuild/SOURCES/asciidoctor-0.1.1.gem http://rubygems.org/gems/asciidoctor-0.1.1.gem`
add README 2012-12-19 11:37:43 +00:00
			Finally, copy the `.patch` files from this repository to the same directory:

move patches 2013-03-11 19:24:12 +00:00			`cp *.patch $HOME/rpmbuild/SOURCES/`
add README 2012-12-19 11:37:43 +00:00
			`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).

update to 0.1.1, add wget install command, update test script 2013-03-01 17:47:57 +00:00			`yum localinstall $HOME/rpmbuild/RPMS/noarch/rubygem-asciidoctor-0.1.1.rpm`
add README 2012-12-19 11:37:43 +00:00
			`Now, it's time to start using Asciidoctor!`

Update README.adoc Updated the testing and reporting section to include steps for using fedora-easy-karma. 2013-03-12 18:50:04 +00:00			`== Testing the asciidoctor package and reporting feedback`
add README 2012-12-19 11:37:43 +00:00
Update README.adoc Updated the testing and reporting section to include steps for using fedora-easy-karma. 2013-03-12 18:50:04 +00:00			`Before the asciidoctor package can be included in the Fedora distribution, it must be tested by users and receive karma via the http://admin.fedoraproject.org/updates/[Bohdi system]. One way to do this is to use http://admin.fedoraproject.org/pkgdb/acls/name/fedora-easy-karma[fedora-easy-karma].`

			`=== Enable the updates-testing repository temporarily`

			`In a terminal, type:`

			`sudo yum install rubygem-asciidoctor --enablerepo=updates-testing`

			`This command will download and install the asciidoctor package.`

			`=== Test the asciidoctor package`

			. On your computer, create a new file and name it `asciidoctor-test.rb`
			`. Copy and paste the following code into the file.`
add README 2012-12-19 11:37:43 +00:00
fix for github's asciidoc 2012-12-19 11:45:13 +00:00			`require 'asciidoctor'`
			`content = "= My First Document\n\nRender me some HTML!"`
update to 0.1.1, add wget install command, update test script 2013-03-01 17:47:57 +00:00			`puts Asciidoctor.render(content, :header_footer => true, :compact => true)`
add README 2012-12-19 11:37:43 +00:00
Update README.adoc Updated the testing and reporting section to include steps for using fedora-easy-karma. 2013-03-12 18:50:04 +00:00			`. Save the file.`
			. In a terminal, navigate to the directory where you saved `asciidoctor-test.rb` and type the following command to execute the file with Ruby:
add README 2012-12-19 11:37:43 +00:00
			`ruby asciidoctor-test.rb`
Update README.adoc Updated the testing and reporting section to include steps for using fedora-easy-karma. 2013-03-12 18:50:04 +00:00			`+`
			`You should see this output in your terminal.`

			`<!DOCTYPE html>`
			`<html lang="en">`
			`<head>`
			`<meta http-equiv="Content-Type" content="text/html; charset=UTF-8">`
			`<meta name="generator" content="Asciidoctor 0.1.1">`
			`<title>My First Document</title>`
			`</head>`
			`<body class="article">`
			`<div id="header">`
			`<h1>My First Document</h1>`
			`</div>`
			`<div id="content">`
			`<div id="preamble">`
			`<div class="sectionbody">`
			`<div class="paragraph">`
			`<p>Render me some <strong>HTML</strong>!</p>`
			`</div>`
			`</div>`
			`</div>`
			`</div>`
			`<div id="footer">`
			`<div id="footer-text">`
			`Last updated 2013-03-12 10:43:15 MDT`
			`</div>`
			`</div>`
			`</body>`
			`</html>`

			`. You can render the output as HTML using:`
add README 2012-12-19 11:37:43 +00:00
			`ruby asciidoctor-test.rb > test.html`

Update README.adoc Updated the testing and reporting section to include steps for using fedora-easy-karma. 2013-03-12 18:50:04 +00:00			`. Open your browser to see the result. Or, if you're using Gnome, type:`

			`gnome-open test.html`
			`+`
			`A new tab should open in your current browser session.`

			`=== Provide feedback with fedora-easy-karma`

			`. If you don't have fedora-easy-karma installed on your computer, type the following command in a terminal.`

			`sudo yum --enablerepo=updates-testing install fedora-easy-karma`

			`. Once fedora-easy-karma is installed, run it in the terminal.`

			`fedora-easy-karma --fas-username yourFASaccount *asciidoctor`
			`+`
			`To be on the safe side, include the flag for your FAS account when you start fedora-easy-karma. Once fedora-easy-karma runs, you will not be able to switch accounts.`
			`NOTE: It may take fedora-easy-karma several minutes to fetch the list of packages in updates-testing.`
			`+`
			When fedora-easy-karma finds `rubygem-asciidoctor`, it will display a summary of the package and prompt you to give -1 (negative), 0 (neutral), or 1 (postive) karma to the package. For more information about providing karma for packages and how to comment on packages, review the http://fedoraproject.org/wiki/QA:Update_feedback_guidelines[Fedora feedback guidelines].

			`. Enter your karma rating.`
			`. Next, you will be asked to provide additional, detailed feedback. Please comment whether the package worked as expected and you successfully used it, if you think you may have encountered an error, but aren't sure, or if you definitely encountered a bug.`
			`. When prompted, enter your FAS password.`
			`. W00t! The feedback process is complete.`