Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

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 this issue Sep 15, 2016 · 6 comments
Open

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

hossman opened this issue Sep 15, 2016 · 6 comments

Comments

@hossman
Copy link
Collaborator

hossman commented Sep 15, 2016 •
edited
Loading

While working on /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
Copy link
Collaborator Author

hossman commented Sep 15, 2016

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...

@hossman hossman mentioned this issue Sep 15, 2016
Closed
@ctargett
Copy link
Owner

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 added a commit that referenced this issue Sep 16, 2016
@hossman
Include a TODO comment before any table that we know won't look right…
d50b112 
… in PDF

because it has cells containing block elements or multi paragraphs

#13
@hossman
Copy link
Collaborator Author

hossman commented Sep 16, 2016

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
Copy link
Owner

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

@hossman
Copy link
Collaborator Author

hossman commented Sep 20, 2016

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 pushed a commit that referenced this issue Sep 21, 2016
@hossman @ctargett
Include a TODO comment before any table that we know won't look right…
c6f6d57 
… in PDF

because it has cells containing block elements or multi paragraphs

#13
@ctargett ctargett mentioned this issue Sep 23, 2016
Open
@ctargett
Copy link
Owner

ctargett commented Feb 6, 2017

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Assignees
No one assigned
Labels
None yet
Projects
None yet
Milestone
No milestone
Development

No branches or pull requests
2 participants
@hossman @ctargett