How to access command line params from Preprocessor

[atbest]

I am planning to write a preprocessor to parse attributes from a yaml file as described in 566. In order to maximize the use of the config file, I am planing to implement a theme feature from the config file, which contains common attributes (overidable) and theme specific attributes.
Example:

linkcss: true
copycss: true
stylesdir: styles
themes:
   bright:
      stylesheet: asciidoctor
      source-highlighter: highlight.js
      highlightjs-theme: atom
   dark:
      stylesheet: asciidoctor-dark
      source-highlighter: highlight.js
      highlightjs-theme: monokai

Then the cli command is asciidoctor --config-file=conf.yml --theme=dark -a stylesdir=new_style input.adoc.

The order of the attributes is cli > theme > common. It's easier to implement theme > common, but for cli > theme, config-file and theme, the preprocessor need to read the command params.

[mojavelinux]

You can access the commandline parameters via the global variable ARGV. That is an array of flags which is otherwise unparsed.

However, since we use a commandline parser, additional flags such as --config-file are not permitted. In order to get the parser to recognize these, you would need to extend the options class (but it's not really designed for that).

A better way to specify options is to pass them through document attributes. Document attributes are schemaless, so you can introduce any number of them as long as they don't collide with built-in attributes.

For example, something like:

asciidoctor -a config-file=conf.yml -a theme=dark ...

You can access the document attributes via the attributes Hash on the Document object.

Happy hacking!

[mojavelinux]

For an example of a preprocessor that manipulates values on the Document object, see https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/enable-sourcemap-preprocessor.rb.

[atbest]

Thanks, this is very helpful. I've complete the coding successfully for this part. Is it possible to register or save the file to some location so that asciidoctor can load it automatically without using -r argument?
Thanks.

[mojavelinux]

@atbest Not at the moment. The -r flag is required to load an extension. If you have an idea about how to autoload extensions, feel free to propose. For example, we could consider an environment variable such as RUBYOPT or ASCIIDOCTOR_OPTS. Something like http://rubyworks.github.io/rc/ also looks interesting.

[atbest]

I think it should go either Asciidoctor::Cli::Options.parse! (for cmd use only) or Asciidoctor.load (more general). Then asciidoctor should be able to read the extension information from a config file like ~/.asciidoctor.conf or scan all .rb files in a directory like ~/.asciidoctor/extensions. Personally, I like the first idea, which will be more flexible, and I already implemented this idea in https://github.com/atbest/asciidoctor-ext/blob/master/attributeloader.rb, which can load common attributes and theme specific attributes from a config file as I said above. In addition, it can also find and load other extensions specific in the config file, so I don't need to use -r flag for all other extensions.

Because I don't want to set dir and theme for highlight.js and prettify with different attributes (this was mentioned somewhere, but I cannot find it now), I added two new attributes (optional), highlighterdir and highlighter-theme to replace them. For example, if highlighterdir is set, its value is passed to highlightjsdir or prettifydir according to the value of source-highlighter. If you like this idea, you can achieve this much easier than me since highlight.js and prettify is only used in html5 backend.

Original lines 208-219 in html5.rb:

      case highlighter
      when 'highlightjs', 'highlight.js'
        highlightjs_path = node.attr 'highlightjsdir', %(#{cdn_base}/highlight.js/8.9.1)
        result << %(<link rel="stylesheet" href="#{highlightjs_path}/styles/#{node.attr 'highlightjs-theme', 'github'}.min.css"#{slash}>)
        result << %(<script src="#{highlightjs_path}/highlight.min.js"></script>
<script>hljs.initHighlighting()</script>)
      when 'prettify'
        prettify_path = node.attr 'prettifydir', %(#{cdn_base}/prettify/r298)
        result << %(<link rel="stylesheet" href="#{prettify_path}/#{node.attr 'prettify-theme', 'prettify'}.min.css"#{slash}>)
        result << %(<script src="#{prettify_path}/prettify.min.js"></script>
<script>prettyPrint()</script>)
      end

Backward-compatible addition of highlighterdir and highlighter-theme.

      case highlighter
      when 'highlightjs', 'highlight.js'
        highlighter_path = node.attr('highlightjsdir', nil) || node.attr('highlighterdir', %(#{cdn_base}/highlight.js/8.9.1))
        highlighter_theme = node.attr('highlightjs-theme', nil) || node.attr('highlighter-theme', 'github')
        result << %(<link rel="stylesheet" href="#{highlighter_path}/styles/#{highlighter_theme}.min.css"#{slash}>)
        result << %(<script src="#{highlighter_path}/highlight.min.js"></script>
<script>hljs.initHighlighting()</script>)
      when 'prettify'
        highlighter_path = node.attr('prettifydir', nil) || node.attr('highlighterdir', %(#{cdn_base}/prettify/r298))
        highlighter_theme = node.attr('prettify-theme', nil) || node.attr('highlighter-theme', 'prettify')
        result << %(<link rel="stylesheet" href="#{highlighter_path}/#{highlighter_theme}.min.css"#{slash}>)
        result << %(<script src="#{highlighter_path}/prettify.min.js"></script>
<script>prettyPrint()</script>)
      end

This is moderate implement than the preprocessor, and will not change anything for old documents.

The last optional attribute, common-dir is only for my own purpose to pass the dir of stylesheet and js files when temporary preview html file is saved in %USERPROFILE%\AppData\Local\Temp. This should not go into asciidoctor.

[mojavelinux]

Technically, you only need one -r flag because that Ruby file can require other extensions. In fact, it can do anything it wants to do. It's Ruby.

That's why I think the ASCIIDOCTOR_OPTS env variable is the right way to go to set up an environment that passes additional flags to the cli options parser. For example:

ASCIIDOCTOR_OPTS='-r asciidoctor-config-loader'

The config loader can then register your preprocessor to push additional attributes into Asciidoctor.

I do think that the cli parser needs to be extensible though. The problem is that the cli options declarations are buried inside the parse! method. I've made a note to file an issue to make that reachable. We also need this for other converters such as Asciidoctor PDF.

Keep in mind, I still plan on implementing asciidoctor/asciidoctor#566. But it's good to write it first as an extension to explore ideas and get the design right.

[atbest]

I do think that the cli parser needs to be extensible though. The problem is that the cli options declarations are buried inside the parse! method.

Yes, that's why I said that it can go to Asciidoctor::Cli::Options.parse! (for cmd use only). Then if you want the ruby API and others to have similar behavior, you'll find some mechanism for them.