Asciidoctor :: Discussion

asciidoctor-pdf vs asciidoctor-web-pdf

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

5 messages Options

jlo2k

asciidoctor-pdf vs asciidoctor-web-pdf

Hello,
how are these projects correlated?

Is the plan to coexist or to slowly phase out one?
Is there some communication between the projects about this?

Also i am confused that within asciidoctor-web-pdf it was mentioned that asciidoctor-pdf is depricated.
But i have the feeling it meant a previous js based version, not the asciidoctor-pdf for asciidoctor based on ruby or the java bindings version.

Thanks in advance.

David Jencks

Re: asciidoctor-pdf vs asciidoctor-web-pdf

Some time ago what is now asciidoctor-web-pdf was named something like asciidoctor-pdf.js, causing plenty of confusion. I think the ‘deprecated” comment refers to this name change.

Asciidoctor-web-pdf usually works, and when it does it provides much more flexible styling (through css) than asciidoctor-pdf (through rather limited themes). However, there are several problems, generally related to non-text content that is larger than a page, such as long tables, or long source blocks, or images wider than the page. These are bugs in the paged.js library that is used in the headless browser to prepare the document for rendering to pdf. Paged.js is complicated, pretty much undocumented, and while not dead, not very actively maintained. It does implement a standard, so there is also a chance that at some point browsers will support the standard directly and it will become unnecessary.

I think everyone agrees that the asciidoctor-web-pdf approach is “the future” of pdf rendering, but it’s difficult to predict when it might become as reliable as asciidoctor-pdf.

FWIW I’ve adapted the asciidoctor-web-pdf approach to be an (experimental) Antora pipeline extension so you can render parts of your Antora site as pdf manuals.

David Jencks

On Mar 4, 2021, at 3:02 AM, jlo2k [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hello,
how are these projects correlated?

Is the plan to coexist or to slowly phase out one?
Is there some communication between the projects about this?

Also i am confused that within asciidoctor-web-pdf it was mentioned that asciidoctor-pdf is depricated.
But i have the feeling it meant a previous js based version, not the asciidoctor-pdf for asciidoctor based on ruby or the java bindings version.

Thanks in advance.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/asciidoctor-pdf-vs-asciidoctor-web-pdf-tp8555.html

To start a new topic under Asciidoctor :: Discussion, [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

mojavelinux

Re: asciidoctor-pdf vs asciidoctor-web-pdf

Administrator

In reply to this post by jlo2k

As you've pointed out, there are two active projects in Asciidoctor that provide a PDF converter, though with very different approaches. And yes, we communicate. I currently lead Asciidoctor PDF and Guillaume leads Asciidoctor Web PDF. We communicate every day.

The reason there are two converters is because we've reached (or very nearly reached) the limit of what we can do with Asciidoctor PDF. The hope is that Asciidoctor Web PDF can sail over these limitations and thus eventually replace it. Though, given how much functionality is in Asciidoctor PDF, that's still a very tall order. (PDF is very, very difficult to make). So the effort to get there is ongoing.

My plan is to announce this strategy, and address the relationship between the two projects, after I release Asciidoctor PDF 2.0.0. However, that release has been held up due to technical challenges finalizing several remaining enhancements that are slated for it.

If Asciidoctor PDF works for you, and its limitations aren't prohibitive, then you can keep on using it. However, if it's not working for you, I encourage you to evaluate Asciidoctor Web PDF as an alternative. Feedback is only going to make it better.

To build on what David wrote:
> I think everyone agrees that the asciidoctor-web-pdf approach is “the future” of pdf rendering, but it’s difficult to predict when it might become as reliable as asciidoctor-pdf.

We do hope that Asciidoctor Web PDF can give us a better way to make highly customized PDFs, but it's still too early to predict if that will prove possible. It's certainly showing promise!

Best Regards,

-Dan

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux

jlo2k

Re: asciidoctor-pdf vs asciidoctor-web-pdf

hi, as mentioned my personal main use case is to make the styling between html and pdf simpler. i slowly get the grasp what it means that creating pdf is not an easy task.
I will talk to docToolchain maintainer. He made me aware of asciidoctor-web-pdf and i will surely look into it.
Giving that it works on node.js i will surely look into asciidoctor.js in conjunction with it.

Thanks for all your efforts.

mojavelinux

Re: asciidoctor-pdf vs asciidoctor-web-pdf

Administrator

We're always glad to help. Continue to ask questions and we'll help you along your journey. We'll keep working to make publishing as straightforward as we can!

Best Regards,

-Dan

On Thu, Mar 4, 2021 at 11:18 PM jlo2k [via Asciidoctor :: Discussion] <[hidden email]> wrote:

hi, as mentioned my personal main use case is to make the styling between html and pdf simpler. i slowly get the grasp what it means that creating pdf is not an easy task.
I will talk to docToolchain maintainer. He made me aware of asciidoctor-web-pdf and i will surely look into it.
Giving that it works on node.js i will surely look into asciidoctor.js in conjunction with it.

Thanks for all your efforts.

If you reply to this email, your message will be added to the discussion below:
https://discuss.asciidoctor.org/asciidoctor-pdf-vs-asciidoctor-web-pdf-tp8555p8562.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Dan Allen (he, him, his) | @mojavelinux | https://twitter.com/mojavelinux