Add output to PDF to asciidoctor cli and/or API #113

Closed
mojavelinux opened this Issue Jan 25, 2013 · 22 comments

Projects

None yet

9 participants

@mojavelinux
Member

Although we don't have native pdf generation yet in Asciidoctor, it would still be nice to offer this functionality through the asciidoctor cli and/or API.

For now, it will require having the AsciiDoc distribution available to access the XSL stylesheets and such (or we could pull them from the web and cache them locally).

If we need files from the AsciiDoc distribution, we could require the ASCIIDOC_HOME environment variable to point to the install location so that we can run a2x directly or the resources it uses.

Here's the commands I use to generate PDF from the DocBook output that Asciidoctor generates (for an article doctype)

a2x -k -fpdf -darticle --fop output.xml

Under the covers, here are the commands that a2x executes when the doctype is article (the paths here are obviously invocation specific):

xsltproc --stringparam callout.graphics 0 --stringparam navig.graphics 0 \
--stringparam admon.textlabel 1 --stringparam admon.graphics 0  \
--output "$HOME/projects/asciidoc-samples/output.fo" \
"$HOME/opt/asciidoc-8.6.8/docbook-xsl/fo.xsl" \
"$HOME/projects/asciidoc-samples/output.xml"

and

fop -fo "$HOME/projects/asciidoc-samples/output.fo" \
-pdf "$HOME/projects/asciidoc-samples/output.pdf"

We could use Nokogiri to replace the xsltproc call. There isn't yet a replacement for the fop invocation that I know of, but we could wrap it.

@jm
Member
jm commented Jan 25, 2013

Ehhhh I think this is out of scope for Asciidoctor personally unless we figure out a way to make the backends/templates more generic and figure out a way to generate PDF's from that. 👎 I think we'd probably not be adding much value here.

@mojavelinux
Member

Obviously the impact will be different for different audiences. The documentation teams I've talked to that want to adopt Asciidoctor consider this a must have. The feature will certainly take time to evolve as a whole, but I feel very strongly that this is in scope for Asciidoctor.

@mojavelinux
Member

We should use the following option to control this output:

-f FORMAT, --format=FORMAT

I'd also like to stick with fop for now, so the --fop option will be implied.

Also, add this option to keep the artifacts.

-k, --keep-artifacts 
@mojavelinux
Member

The icons dir must be set explicitly for fop to insert the admonition icons:

--icons-dir=images/icons
@mojavelinux mojavelinux referenced this issue in asciidoctor/asciidoctor-gradle-plugin Apr 9, 2013
Closed

Configuration for PDF output #8

@glaforge
glaforge commented Apr 9, 2013

Looking forward to built-in PDF output support :-)

@dobermai

This would be a killer feature! 👍

@mojavelinux
Member

sandoc provides a standalone solution today (written in Scala, uses the Asciidoctor Java integration).

http://discuss.asciidoctor.org/Announcement-Markup-Converter-Sandoc-0-1-td319.html

I still want this to be in Asciidoctor core, but libraries such as sandoc will provide nice alternatives that may open new doors.

@glaforge

I'd really love to have PDF output provided by Asciidoctor directly rather than by another third-party solution that I'd have to integrate in my build, add even more dependencies and so on :-(

@mojavelinux
Member

Totally agreed. I'll be getting to this one soon, at least a first stab at
it. It will probably require a few iterations to find what we like best.

@LightGuard
Member

I'm sure you seen this one @mojavelinux, but if not, let's take a good hard look at prawn. I just skimmed their manual, its only 130 page PDF they create! You can find the manual at http://prawn.majesticseacreature.com/manual.pdf. Sure it may not have templating just yet, man that would be a powerful thing to add (eventually). I also installed it to see what it took, here's the installation:

gem install prawn
Fetching: Ascii85-1.0.2.gem (100%)
Fetching: ruby-rc4-0.1.5.gem (100%)
Fetching: hashery-2.1.0.gem (100%)
Fetching: ttfunk-1.0.3.gem (100%)
Fetching: afm-0.2.0.gem (100%)
Fetching: pdf-reader-1.3.3.gem (100%)

  ********************************************

  v1.0.0 of PDF::Reader introduced a new page-based API. There are extensive
  examples showing how to use it in the README and examples directory.

  For detailed documentation, check the rdocs for the PDF::Reader,
  PDF::Reader::Page and PDF::Reader::ObjectHash classes.

  The old API is marked as deprecated but will continue to work with no
  visible warnings for now.

  ********************************************

Fetching: prawn-0.12.0.gem (100%)

  ********************************************


  A lot has changed since 0.8.4

  Please read the changelog for details:

  https://github.com/sandal/prawn/wiki/CHANGELOG


  ********************************************

Successfully installed Ascii85-1.0.2
Successfully installed ruby-rc4-0.1.5
Successfully installed hashery-2.1.0
Successfully installed ttfunk-1.0.3
Successfully installed afm-0.2.0
Successfully installed pdf-reader-1.3.3
Successfully installed prawn-0.12.0
7 gems installed
Installing ri documentation for Ascii85-1.0.2...
Installing ri documentation for ruby-rc4-0.1.5...
Installing ri documentation for hashery-2.1.0...
Installing ri documentation for ttfunk-1.0.3...
Installing ri documentation for afm-0.2.0...
Installing ri documentation for pdf-reader-1.3.3...
Installing ri documentation for prawn-0.12.0...
Installing RDoc documentation for Ascii85-1.0.2...
Installing RDoc documentation for ruby-rc4-0.1.5...
Installing RDoc documentation for hashery-2.1.0...
Installing RDoc documentation for ttfunk-1.0.3...
Installing RDoc documentation for afm-0.2.0...
Installing RDoc documentation for pdf-reader-1.3.3...
Installing RDoc documentation for prawn-0.12.0...

There's NO NATIVE ANYTHING there! I think we may have found a winner.

@mojavelinux
Member

Prawn looks stellar, but it's going to be a long run solution. Despite the fact that we all despise the DocBook XSL templates (mostly because they are...XSL), there is years of layout work in there. We can throw something together quickly with Prawn, but it's going to take a while to cover all the layouts handled by DocBook XSL + XSL-FO.

That's why, in the meantime, I put effort into creating a bootstrap script, fopdf*, that handles all tasks to set up the toolchain for generating PDFs from AsciiDoc DocBook output using DocBook XSL and Apache FOP. All you have to do is run a Unix shell script or Windows batch file and watch the magic happen.

You can find out more about the project on its GitHub project page:

https://github.com/mojavelinux/asciidoctor-fopdf

The plan is to integrate this tool into Asciidoctor. But first, I think we need to give it a chance to breathe and collect some feedback. That's why I'm proposing to move the completion of this issue to the 1.5.0 release. Consider fopdf to be phase 1 of the implementation.

Btw, the research done for fopdf is great news for the Asciidoctor Java integration. After all, Apache FOP is a Java application. There's a good chance that the shell script won't be needed and that Asciidoctor Java can handle bundling all the assets that fopdf identified and also handle executing the toolchain. The fopdf tool is only necessary, then, when using Asciidoctor from the CLI or Ruby (non-JRuby).

* I'm considering renaming it fopub (intended to be read as it looks)

@mojavelinux mojavelinux was assigned Aug 11, 2013
@mojavelinux
Member

Btw, we still have to figure out what the arguments to the Asciidoctor CLI or API will be to get to PDF. I propose using a backend alias, which behind the scenes handles these two phases:

  1. Convert from AsciiDoc to DocBook (-b docbook)
  2. Run fopdf on the DocBook

Something like:

asciidoctor -b fopdf sample.adoc

I choose "fopdf" rather than "pdf" because I'm reserving the latter for the long-term, native solution (i.e., Prawn).

@lordofthejars
Member

We can try in Asciidoctor Java Integration without any problem, I can intercept fopdf option and do the required changes. Only one small problem, is Asciidoctor-fopdf in Maven repository? For what I have seen is not there, so we will need to resolve this dependency locally. No problem at all of course.
Do you think we could add this feature for Asciidoctor-Java-Integration 1.4.0, or we can create an alternative branch.

WDYT?

@stevehanson

Native PDF support would be awesome!

@praveen12bnitt praveen12bnitt referenced this issue in asciidoctor/asciidoctorj Dec 9, 2013
Closed

PDF support #134

@mojavelinux
Member

I think we are getting closer to this as a reality. The way I envision this working is that we publish Asciidoctor PDF as a gem (asciidoctor-pdf). Then, the renderer in that gem associates itself with the "pdf" backend. When Asciidoctor looks for a renderer for the "pdf" backend, it will find the registered Asciidoctor PDF renderer and delegate to it. That would enable us to use the asciidoctor cli without having the Asciidoctor PDF code base in Asciidoctor core (which would otherwise make it a monolithic project).

In other words, we want to accomplish this through modularity.

@mojavelinux
Member

Note that we could do the same with "fopub" as well...though the integration is a bit more tricky...it can be done.

@paulvickers

Hi, I'm new to asciidoc and asciidoctor (as of yesterday). I'm about to convert a book of mine to a number of e-formats, namely mobi, epub, and pdf. I don't seem to be able to find a single pipeline to go from asciidoctor source files to each of the three output formats cleanly. If I use the stem block for math, asciidoctor-fopub and asciidoctor-epub3 won't handle them. The book doesn't have much math so, at a pinch, I could get by with LaTeXing the equations and inserting them as .pngs.

I was going to use Pandoc and markdown but I really like the existing blocks and stylesheets offered by asciidoctor and the -epub3 extension seems to do a really good job of making ibook-compatible epub files.

I guess what I'm saying is that from my perspective which, longer term will involve using asciidoctor to generate handouts for classes I teach, I would need it to have a seamless pipeline that handles pdf, html, ebook, mobi and math (now called 'stem'?) in one tool. At the moment if I want math I seem to be restricted to vanilla html output as the other tools for generating epub and pdf lag behind the main asciidoctor project.

@jxxcarlson
Member

I've been using and math for some time now. Works beautifully
with no imbedded images.

My configuration: asciidoctor-1.5.0.rc.5 with ruby 2.1.1.

Attached is a file to test your configuration. Below the test file is a screen
shot of what you should see in the browser. (I made the browser window
really small for this).

I've been experimenting with asciidoctor-pdf, but haven't been able
to get a working configuration yet. Of course you can print the html
to pdf.

Jim
@epsilon2718
http://square-the-circle.com


File: test_math.ad

Usage: asciidoctor test_math.ad, then view test_math.html in a browser

:stem: latexmath

The Pythagorean theorem: (a^2 + b^2 = c^2)

The fundamental theorem of calculus:

[
\frac{d}{dx}\int_0^x f(s),ds = f(x)

]

On Aug 6, 2014, at 8:58 AM, Paul Vickers notifications@github.com wrote:

Hi, I'm new to asciidoc and asciidoctor (as of yesterday). I'm about to convert a book of mine to a number of e-formats, namely mobi, epub, and pdf. I don't seem to be able to find a single pipeline to go from asciidoctor source files to each of the three output formats cleanly. If I use the stem block for math, asciidoctor-fopub and asciidoctor-epub3 won't handle them. The book doesn't have much math so, at a pinch, I could get by with LaTeXing the equations and inserting them as .pngs.

I was going to use Pandoc and markdown but I really like the existing blocks and stylesheets offered by asciidoctor and the -epub3 extension seems to do a really good job of making ibook-compatible epub files.

I guess what I'm saying is that from my perspective which, longer term will involve using asciidoctor to generate handouts for classes I teach, I would need it to have a seamless pipeline that handles pdf, html, ebook, mobi and math (now called 'stem'?) in one tool. At the moment if I want math I seem to be restricted to vanilla html output as the other tools for generating epub and pdf lag behind the main asciidoctor project.


Reply to this email directly or view it on GitHub.

@paulvickers

Thanks for that. Yes, I managed to get the latexmath stems working, but not, as you say, with the pdf converter or the asciidoctor-epub3 converters.

@mojavelinux
Member

I guess what I'm saying is that from my perspective which, longer term will involve using asciidoctor to generate handouts for classes I teach, I would need it to have a seamless pipeline that handles pdf, html, ebook, mobi and math (now called 'stem'?) in one tool.

That's precisely the mission we are currently pursuing. We just haven't finished the race yet :)

At the moment if I want math I seem to be restricted to vanilla html output as the other tools for generating epub and pdf lag behind the main asciidoctor project.

Once we get Asciidoctor EPUB3 and PDF to their initial stable releases, they will no longer lag behind because they will be handled as core converters (i.e., backends). We just had a lot of catching up to do.

@mojavelinux
Member

Btw, Asciidoctor PDF can now be installed and used as a gem.

$ gem install asciidoctor-pdf --pre
$ asciidoctor-pdf README.adoc

Keep in mind it's currently alpha. You can track the progress by following the Asciidoctor PDF project.

https://github.com/asciidoctor/asciidoctor-pdf

Asciidoctor PDF also works in AsciidoctorJ.

You can find an example of Asciidoctor PDF in action in a Maven build here:

https://github.com/asciidoctor/asciidoctor-maven-examples/tree/master/asciidoc-to-pdf-example

To use it currently requires a manual installation, but we envision it will be packaged in the asciidoctorj-pdf jar to make it as simple to use as AsciidoctorJ.

@mojavelinux mojavelinux modified the milestone: v1.5.0, v1.6.0 Sep 26, 2014
@mojavelinux
Member

Now that Asciidoctor PDF has been published, I'm going to close this issue and handle issues using the asciidoctor-pdf (or asciidoctor-fopub) issue tracker.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment