Suggested edit for the documentation of asciidoctor-epub3

Walckiers commented 8 years ago

https://github.com/asciidoctor/asciidoctor-epub3 says «Converting an AsciiDoc document to EPUB3 is as simple as passing your document to the asciidoctor-epub3 command.»

So I thought converting our group's Christmas Newsletter (currently an AsciiDoc document for pdf) to EPUB3 should be simple. It turned out to be not quite as simple as that. Here is what I had to do;

Get a more recent version of ruby (I'm running Ubuntu 12.04)

    $ sudo apt-get install python-software-properties
    $ sudo apt-add-repository ppa:brightbox/ruby-ng
    $ sudo apt-get update
    $ sudo apt-get install ruby1.9.3

(With thanks to https://www.brightbox.com/docs/ruby/ubuntu/)

Make a new directory

    $ mkdir asciidoctor-epub3

Get asciidoctor-epub3 from git

    $ git clone https://github.com/asciidoctor/asciidoctor-epub3

Install extra requirements

    $ sudo apt-get install rubygems ruby-dev
    $ sudo gem1.9.3 install gepub
    $ sudo gem1.9.3 install thread_safe

Edit file ./asciidoctor-epub3/lib/asciidoctor-epub3.rb, adding full paths; so that it reads

    require '/var/lib/gems/1.8/gems/asciidoctor-1.5.2/lib/asciidoctor'
    require '/var/lib/gems/1.8/gems/asciidoctor-1.5.2/lib/asciidoctor/extensions'
    require '/var/lib/gems/1.9.1/gems/gepub-0.6.9.2/lib/gepub.rb'
    require_relative 'asciidoctor-epub3/converter'
    require_relative 'asciidoctor-epub3/packager'

Edit the original asciidoc file, making each section of the original into its own standalone asciidoc file («chapterOne.asciidoc», «chapterTwo.asciidoc» ...)
Make a parent asciidoc file «ChristmasNewsletter.adoc» to include those chapters, thus ...

    ...
    include::/path/to/chapterOne.asciidoc[]

    include::/path/to/chapterTwo.asciidoc[]

    include::/path/to/chapterThree.asciidoc[]
    ...

And now this works:-

    bin/asciidoctor-epub3 -D output data/samples/ChristmasNewsletter.adoc

I suggest that a help file with the above information would be a big time-saver for people like me

 Richard H

mojavelinux commented 8 years ago

Thanks for your input.

Converting an AsciiDoc document to EPUB3 is as simple as passing your document to the asciidoctor-epub3 command.

This is more of a goal :)

Make a parent asciidoc file «ChristmasNewsletter.adoc» to include those chapters, thus ...

This is emphasized here:

https://github.com/asciidoctor/asciidoctor-epub3#declaring-the-spine

I agree a sample code snippet would help visualize the requirement. If you'd like to send a pull request for that, I'd be glad to review and merge it.

It should not be necessary to modify source files. Your Ruby setup is not correct, and it's not a more recent version of Ruby (the latest version is Ruby 2.2). However, I do know that setting up Ruby can be tricky, especially on Ubuntu which ships with a completely broken Ruby setup.

What I recommend is RVM. It has never failed me. We are planning a page on asciidoctor.org that explains how to setup Ruby using RVM. See https://github.com/asciidoctor/asciidoctor.org/issues/399. Once that page is ready, we can link to it from this README.

In a nutshell, the setup should be something like what is described here:

https://www.digitalocean.com/community/tutorials/how-to-use-rvm-to-manage-ruby-installations-and-environments-on-a-vps

Except don't install "rails". Instead, use:

rvm use 2.2@runtime --create
gem install asciidoctor-epub3 --pre

Then you can use:

asciidoctor-epub3 sample-book.adoc

If you want to use the development (git) version, then use:

rvm use 2.2@asciidoctor-epub3-dev --create
bundle

Then, you can use:

./bin/asciidoctor-epub3 data/samples/sample-book.adoc

mojavelinux commented 8 years ago

Related to #38.

Walckiers commented 8 years ago

Thank you for your (very) quick reply.

>What I recommend is RVM <rvm.io>.

Yes, I did see RVM during my travails yesterday, but thought it too much of a detour:- Christmas is coming, and the Newsletter Needs To Go Out.

So I've changed camps and done

$ a2x  --format=epub  --epubcheck --icons --no-xmllint   --destination-dir=./  ChristmasNewsletter.adoc

That worked out of the box and it kept all the internal links between chapters ...

It now just remains to tweak the CSS to something more Christmassy; like this-

60878_screenshot

That was easy in LaTeX, so I'm hoping ditto in EPUB 3.

(Here I'm relying on Landry Miñana's excellent "EPUB 3.0 Concevez et réalisez des eBooks enrichis" http://www.pearson.fr/livre/?GCOI=27440100128100 )

Richard H

mojavelinux commented 8 years ago

I see RVM as the path rather than the detour. I know it can seem like a lot of steps, but it keeps paying you back with all the time it saves you in the long run. I wouldn't recommend it otherwise.

I didn't mean for my reply about your Ruby setup to sound so sharp. I'm just really frustrated with Ubuntu for screwing up the Ruby installation. Ruby isn't difficult to understand, but distributions are making it seem complex. That's why I like RVM. It shields you from that problem and lets you use Ruby the way it was intended.

So I've changed camps and done

Actually, if you do use a2x, I recommend first converting to DocBook using Asciidoctor, then converting to whatever output format you want. That lets you take advantage of the all the modern enhancements in Asciidoctor but still use the DocBook toolchain.

asciidoctor -b docbook newsletter.adoc
a2x --format=epub  --epubcheck --icons --no-xmllint  --destination-dir=./ newsletter.xml

The nice part about AsciiDoc is that you have lots of options.

mojavelinux commented 8 years ago

I've added the example of the spine document in the README. The rest of the changes will be addressed by #38.

asciidoctor / asciidoctor-epub3

Suggested edit for the documentation of asciidoctor-epub3 #54