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

Closed
opened this Issue Jan 25, 2013 · 22 comments

None yet

### 9 participants

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. Member 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. 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. 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  Member  The icons dir must be set explicitly for fop to insert the admonition icons: --icons-dir=images/icons  referenced this issue in asciidoctor/asciidoctor-gradle-plugin Apr 9, 2013 Closed #### Configuration for PDF output #8 commented Apr 9, 2013  Looking forward to built-in PDF output support :-)  This would be a killer feature! 👍 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.  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 :-( 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. 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. 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) was assigned Aug 11, 2013 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: Convert from AsciiDoc to DocBook (-b docbook) 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). 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?  Native PDF support would be awesome! referenced this issue in asciidoctor/asciidoctorj Dec 9, 2013 Closed #### PDF support #134 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. Member  Note that we could do the same with "fopub" as well...though the integration is a bit more tricky...it can be done.  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. 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.  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. 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. 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.
modified the milestone: v1.5.0, v1.6.0 Sep 26, 2014
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.