Exploring extensions

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Exploring extensions

1marc1
Hi Team,

I have started to do some exploring of extensions. I am using asciidoctor-pdf and have given myself the task to add the keyword "green" to the general properties of a PDF file. The idea is that the extension will force the keyword "green" to be at the start of the list of keywords. I have written the following extension, but I am not getting the desired results.

require 'asciidoctor-pdf' unless defined? ::Asciidoctor::Pdf

module CustomKeyword
  def build_pdf_info doc
    info = {}
    super
    info[:Keywords] = 'green'
    info
  end
end

class Asciidoctor::Pdf::Converter
  prepend CustomKeyword
end

I haven't yet figured out how to place "green" at the beginning of the list of keywords, so I though to start with simply setting the entire keyword list to "green".

The result of the extension above is that the keyword "green" indeed shows up in the general properties of the resulting .PDF file, however, all other details, like author, subject, producer, etc. are missing.

I guess I don't quite understand yet how the extension interacts with the code from converter.rb and what the effect of the "super" command is. For example, I also experimented with leaving the "info = {}" line out of the extension, figuring that this would exist upon return from the "super" command. The result of this is an error saying:
undefined local variable or method `info'
, which leads me to believe that the `info` variable is not available to my extension.

Is there a place where these things are documented, perhaps in a step by step guide? I have spent quite a bit of time looking for this information, including looking through various existing extensions for examples, but I am still stuck.

Thank you in advance for any pointers.

Marc.
Reply | Threaded
Open this post in threaded view
|

Re: Exploring extensions

1marc1
Hi team,

After a lot of puzzling, I learned a lot and I think I can answer my own questions.

@Dan Allen, please correct me if I am wrong.

First of all, for some reason I was under the impression that the extensions were somehow in addition to the functions inside converter.rb. They are not. They replace these functions. However, you can write an extension that makes a logical decision to either run the original code from converter.rb or the code from your extension. Your extension will then look something like:

if condition
  super
else
  custom code
end

The above example essentially says: if a certain condition is true, then run the original code (super), in all other cases, run the custom code. There is no interaction between the original code and the code in the extension. Hence why I was getting the errors.

In order to solve the example task I gave myself (adding the keyword "green" to every PDF file that is created), I have created an extension that contains the same code of the "build_pdf_info" function inside converter.rb. I then changed the "if" statement for the "keywords" to look like this:

if doc.attr? 'keywords'
  info[:Keywords] = ('green ').as_pdf
  info[:Keywords] += (doc.attr 'keywords').as_pdf
end

Doing so will set the first keyword to "green" and will then append all keywords that are defined inside the document via the "keywords" attribute.

I hope this is helpful for someone along the way.

Marc.
Reply | Threaded
Open this post in threaded view
|

Re: Exploring extensions

1marc1
Hi team,

A follow up question on all this: if you are essentially modifying existing functions, then what is the best way to keep up to date with newer versions of asciidoctor-pdf? Would it essentially be to update your custom extension with the new code?

Also, I found the details on the extensions (https://asciidoctor.org/docs/user-manual/#extensions), but I am not sure how much of this relates to asciidoctor-pdf.

Thank you in advance for your insights.

Marc.