search

ctargett / refguide-asciidoc-poc

Proof of concept of Solr Ref Guide converted to asciidoc format & using Asciidoctor for publishing
2 stars 4 forks source link

Need to audit and re-structure any tables that have block elements in cells or the PDF won't render properly #13

Open hossman opened 7 years ago

hossman commented 7 years ago

While working on ctargett/refguide-asciidoc-poc/issues/8 i discovered this known bug in the PDF backend: asciidoctor/asciidoctor-pdf/issues/6

While the PDF backend has support for basic text formatting, anything that involves multiple "blocks" (ie: [source] code blocks, quoted blocks, admonishments, or even just multiple paragraphs) won't work.

A trivial table example demonstrating the problem is shown below -- all rows render fine in html/jekyll, but with the PDF backend only the last row renders properly

(note the "a" in the cols spec indicating that asciidoc processing should happen on each column, same problem exists if it's specified on a per-cell basis)

[width="100%",cols="30%a,70%a",options="header",]
|===
|Description
|Code

|*FAIL*
|----
this is  Some
  plain [text] formatting
----

|*FAIL*
|[source,html]
<html>
 <body>
  html <strong>markup</strong>
 </body>
</html>

|*FAIL*
|
para one

para two

para three

|*WORKS*
|
`some text` that is _formatted_ in *diff* ways

|===
hossman commented 7 years ago

FWIW: I've been thinking for a while that we should re-think most of our table usages in the ref guide anyway, and restructiong everything but the trivial usage into something else ... this seems force the issue.

Alternatively: we could look into other means of generating the PDF? some folks have noted that using an asciidoctor->docbook->pdf pipeline doesn't have these problems...

ctargett commented 7 years ago

I've long thought that the tables need to go away as the default approach to handling parameters. It's difficult to keep them consistent (in terms of headers and columns) and I don't think they're very easy for users to read. It's high on my list to change those once this conversion is completed, and I'd thought the conversion process was the place where I would start.

I'm -1 on the idea of trying to convert to docbook then pdf. While it's powerful, we'd have to learn how it works, make the conversion, then figure out how to convert it to PDF. For something that I frankly think has low value - everyone uses the online version. Only a small group uses the PDF.

hossman commented 7 years ago

I've updated the conversion process to add a TODO: This table... comment before every table that needs attention. Currently there are 37 of them (but obviously within each table there are many cells that will need to be dealt with)

ctargett commented 7 years ago

The change looks good. Should we close this? Or does it need to stay open for another reason?

hossman commented 7 years ago

I was assuming we'd leave open until we had a concrete game plan for what to do with all these tables? I guess it depends on how you want to track stuff like that. I'm fine either way.

ctargett commented 7 years ago

The latest release of asciidoctor-pdf is supposed to have a fix for this problem: https://github.com/asciidoctor/asciidoctor-pdf/releases/tag/v1.5.0.alpha.14