Open atbest opened 7 years ago
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!
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.
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.
@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.
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.
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 https://github.com/asciidoctor/asciidoctor/issues/566. But it's good to write it first as an extension to explore ideas and get the design right.
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.
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:
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 implementtheme > common
, but forcli > theme
,config-file
andtheme
, the preprocessor need to read the command params.