Asciidoctor-pdf: Add support for AsciiDoc cell content

[mojavelinux]

Add support for AsciiDoc cell content. Currently, the raw AsciiDoc source is passed through to the PDF file.

[osterwood]

I tried hacking support for this into converter.rb, and can now generate the PDF code for the styled cells, but I can't seem to find a way to insert raw PDF code into Prawn table cells. Any ideas?

Inserted into def convert_table(node):

    if cell.inner_document != nil
      output = StringIO.new

      inner_doc = ::Asciidoctor::Pdf::Converter.new('pdf', {})
      inner_doc.init_pdf cell.inner_document
      inner_doc.convert(cell.inner_document)
      inner_doc.render_body_public(output)

      code = []
      state = :header

      lines = output.string.split("\n").each do |line|
        # Skip initial lines until actual content start.  
        # Always seems to be the "<< /Length" but not when 2
        state = :body if line.start_with? "<< /Length" and line != "<< /Length 2"

        # We're still in the header (check above not hit), skip this line
        next  if state == :header

        # We've encountered another PDF block, and therefore have all the code we need
        break if line.start_with? "<<" and out.length > 1

        code << line
      end

      puts code.join("\n")
    end

But maybe this is totally the wrong approach. I would really love to have fully supported cells (be able to embed images, code block, lists, etc)

[mojavelinux]

I'll have a look asap. Thanks for giving this a go! I'll work with you to get it merge ready.

[osterwood]

Dan,

I've been super happy with asciidoctor and asciidoctor-pdf -- thanks for creating such great tools.

The code here might be totally the wrong approach. I hope it is useful but I kind of doubt it. Let me know how I can help.

• Chris

[mojavelinux]

I looks like we're pretty limited by what we can put into a cell in Prawn. We're going to have to focus on a subset of content that we can offer and make that as good as we can.

We can put an image in a cell, but only one. We won't be able to do arbitrary block content. We could probably fake lists. Given that images and lists are the two most likely things you put into cells...maybe source code as well.

I'm going to start by focusing on the use case of a single block image. There's actually an API for that :)

[mojavelinux]

It does look like it's possible to define our own type of Cell and respond to the draw_content method, which gives us the chance to write directly to the PDF. However, we'd likely need to patch prawn-table upstream (or monkeypatch it) to make it stick.

See the code for Cell::Image to get the idea: https://github.com/prawnpdf/prawn-table/blob/master/lib/prawn/table/cell/image.rb#L62-L64

[mojavelinux]

I've added initial support for AsciiDoc table cell content. See https://github.com/asciidoctor/asciidoctor-pdf/pull/120

The most important and complete support is for a table cell with a single block image. There's also good support for a table cell with a single paragraph. I've hacked in a few additional options, including basic (but incomplete) support for literal, listing, quote and verse.

cc: @paulrayner

[mojavelinux]

I'll leave this issue open a bit longer, though eventually I foresee creating more fine-grained issues so we can tackle each challenge one at a time.

[paulrayner]

:+1:

[mojavelinux]

I took this a lot further. What's there now should be sufficient to cover most, if not all, basic use cases. The layouts inside AsciiDoc table cells is a bit lacking, but the content is mostly there and styled somewhat sensibly.

In order to do this right, we need to subclass Table::Cell and tie directly into the pdf object. However, the work done in this pull request makes the requirements a bit more clear and hopefully paves the way for that refactoring.

[mojavelinux]

By basic, I mean things like stacking images in a table cell, a table cell with multiple paragraphs, a paragraph and a few list items, etc. It's not fancy, but it's something.

[mojavelinux]

I am looking for real world use cases of AsciiDoc table cell content that aren't met sufficiently by this change (or just in general).

Keep in mind that a cell must be marked as AsciiDoc content when it contains block-level AsciiDoc. The "a" essentially switches the cell from being of type paragraph (i.e., inline text) to an arbitrary number of blocks.

[paulrayner]

I'll do some experiments next week and let you know. This is exciting!

Paul

On Fri, May 15, 2015 at 8:44 PM, Dan Allen [email protected]
wrote:

I am looking for real world use cases of AsciiDoc table cell content that aren't met sufficiently by this change (or just in general).

Keep in mind that a cell must be marked as AsciiDoc content when it contains block-level AsciiDoc. The "a" essentially switches the cell from being of type paragraph (i.e., inline text) to an arbitrary number of blocks.

Reply to this email directly or view it on GitHub:
https://github.com/asciidoctor/asciidoctor-pdf/issues/6#issuecomment-102566232

[mojavelinux]

The Groovy language guide has some pretty good examples of AsciiDoc table cells. Mostly it's a source listing in a cell. That's a case we should try to cover as well as possible (it won't be perfect, but we can make it readable at least).

[msavy]

I was playing with asciidcotor-pdf and have cooked up an example which doesn't quite render properly in PDF which may prove useful:

https://gist.github.com/msavy/7500fe0bdf08a6297888

Renders cleanly through the usual asciidoctor -> HTML pipeline

Not quite right in PDF (i.e. newline missing after initial para)

Using latest HEAD

[msavy@mmbp tmp](master)$ asciidoctor-pdf --version
Asciidoctor PDF 1.5.0.dev using Asciidoctor 1.5.2 [http://asciidoctor.org]
Runtime Environment (ruby 2.0.0p481 (2014-05-08 revision 45883) [universal.x86_64-darwin14]) (lc:UTF-8 fs:UTF-8 in:- ex:UTF-8)

Hope that's helpful!

[mojavelinux]

Thanks @msavy! That's exactly the type of example I was looking for.

I'm happy to say that the pending pull request for this issue will handle this case. I think for the first iteration, I'm going to keep it simple. It will likely support the following blocks:

• block image
• paragraph
• source block
• floating title

The rest of the block types will be emitted raw, almost so it looks like the AsciiDoc source. The next step will be to implement the Cell interface so that we can render the remainder of the block types in the normal way.

[kongou-ae]

:+1:

[gtapper]

Bullet List example

[cols="20%a,30%a,50%a",options="header"]
|===
| User ID              | Usage           | Requirements
| Linux                | Run the Trafodion Installer, which sets up the enviroment and installs the Trafodion software.  | 
* User name or group cannot be `trafodion`.
* Passwordless ssh access to all nodes in the cluster.
* Internet access to download software packages.
* `requiretty` must be disabled in `/etc/sudoers`.
* `sudo`^1^ access to:
** Download and install software packages.
** Mofify `/etc/sudoers.d` (allow the `trafodion` user to modify floating IP: `ip` and `arping`).
** Create the `trafodion` user ID and group.
** Install Trafodion software into the HBase environment.
** Run Java version command on each node in the cluster.
** Run Hadoop version command on each node in the cluster.
** Run HBase version command on each node in the cluster.
** Create directories and files in:
*** `/etc`
*** `/usr/lib`
*** `/var/log`
** Invoke `su` to execute commands as other users; for example, `trafodion`.
** Edit `sysctl.conf` and activate changes using `sysctl -p`:
*** Modify kernel limits.
*** Reserve IP ports.

^1^ `sudo` is *required* in the current release of Trafodion. This restriction may be relaxed in later releases.
Alternative mechanisms for priviliged access (such as running as `root` or `sudo` alternative commands) are not supported.
| Distribution Manager | Modify configuration and stop/start services. | 
* Administrator user name and password.
* URL to Distribution Manager's REST API.
| HDFS Administator | Create directories and change security setting, if needed. | 
* HDFS Administrator user name and password.
* Write access to home directory on the node where the Distribution Manager is running.
| HBase Administator | | 
* HBase Administrator user name and password.
* Read access to `hbase-site.xml`.
|===

[Gitward]

Displaying Asciidoc content in table cells seems to work when creating the PDF using https://github.com/asciidocfx/AsciidocFX . What have they done to solve the problem?

My Test-document:

= Test
:doctype: article
:notitle:
:!toc:

AsciidocFX shows links in PDFs as footnotes http://stackoverflow.com[SO].

.Asciidoc in PDF does not work in Asciidoctor, but works in AsciidocFX.
[cols="2,5a"]
|===
|Line with Asciidoc code
|here comes a list:

* item 1
* item 2
* item 3

http://stackoverflow.com[Get Answers]!

|Line
|with a footnotefootnote:[footnotes do work in AsciidocFX's PDF output (but not in the preview).]

|===

The output of asciidoctor (using gradle):

The output of asciidocFX:

[mojavelinux]

AsciiDocFX is not yet using Asciidoctor PDF. Instead, it uses the DocBook toolchain. It's essentially using fopub under the covers, which executes and manages the DocBook toolchain.

[jmini]

See also this question on StackOverflow: Multiple paragraphs in AsciiDoctor table cell

[mojavelinux]

I was able to figure how to write a custom Cell implementation. However, it appears that we have a few limitations, some of which are coming from Prawn Table.

• works best if column is assigned an explicit (relative) width (otherwise, cell assumes max available width)
• does not permit content that exceeds the height of one page
• extra padding from last block is added to bottom of cell (due to margin at bottom of block)
• ~alignment of content within cell does not yet work~ vertical alignment now works (horizontal alignment must be applied to content blocks)
• does not (yet) inherit font properties from table cell (but should it?)

[buffe]

Hi @mojavelinux is this fix to make table cells parse as asciidoc content has released? I can see the release version has changed to 1.5.0 beta.1

[mojavelinux]

This will be fixed in alpha.14, which is the next release. The release is ready to go out, I just need to do it.

[buffe]

Awesome, looking forward to that.