Add option to asciidoctor cli to specify a config file

[mojavelinux]

Invocations of the asciidoctor command can get lengthy and tedious to type out. We should offer the option of passing a YAML (and/or a TomDoc) config file that specifies the options and attributes for the processor. In the future, this may expand to other uses as well.

I propose the following command options:

-c , --config-file <filename>

Example:

config.yml

:backend: docbook
:template_dir: ../asciidoctor-backends/slim
:attributes:
  toc: ''
  idseparator: -
  idprefix: ''

Used as:

asciidoctor -c config.yml sample.ad

The config file would be processed in the Asciidoctor#load method. Ultimately, it gets translated into the options argument passed to the API.

[mojavelinux]

The other benefit to this improvement is that options can be passed to the processor that are not yet (or will never be) added as command options.

[lordofthejars]

I think it is very important that this option becomes an option of asciidoctor and not only from CLI. This will be an improve for AJI and related projects because we will be able to configure options for Maven plugin with a single line

El dissabte 17 d’agost de 2013, Dan Allen ha escrit:

The other benefit to this improvement is that options can be passed to the processor that are not yet (or will never be) added as command options.

— Reply to this email directly or view it on GitHubhttps://github.com/asciidoctor/asciidoctor/issues/566#issuecomment-22807182 .

Enviat amb Gmail Mobile

[paulrayner]

:+1:

[lordofthejars]

Also in AJI I can implement an strategy to find a configuration file by default in some locations like root classpath or asciidoctor_home env. variable

El dissabte 17 d’agost de 2013, Paul Rayner ha escrit:

[image: :+1:]

— Reply to this email directly or view it on GitHubhttps://github.com/asciidoctor/asciidoctor/issues/566#issuecomment-22812937 .

Enviat amb Gmail Mobile

[mojavelinux]

Good thinking @lordofthejars. That gives me reason to think that we should have a ResourceResolver extension in Asciidoctor that allows all file resolution to be pluggable (with the exception of include files which already has an extension).

[mojavelinux]

The reason I am suggesting that the option spec be -c, --conf-file <filename> and not -f, --config-file is because:

a. It's more logical that the short option and the long option start with the same letter b. This is not a drop-in replacement argument for the asciidoc command, since the config file in Asciidoctor will have a different format (though, there's a chance we can read portions of the AsciiDoc ini format). c. I want to reserve -f for -f, --format in case we need it (an option that comes from the a2x command).

[mojavelinux]

@lordofthejars We should have a separate issue for the config file option on the API, then link that issue to this one (or vice versa).

[mojavelinux]

This can be accomplished today using a preprocessor. The preprocessor would read the config file, convert the values to a map, assign those values to the document object and return the reader (or null) to proceed.

See https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/front-matter-preprocessor/extension.rb for an example of a similar extension. (The main difference is that this preprocessor would never touch the reader since it is getting information from a separate file).

[atbest]

So can we do it now?

[mojavelinux]

Another idea is to make this an implicit include file that contains shared attributes for a project of documents. Once we have this config file, that might be something that an extension handles, or it could be something that a tool does. But what we'd do in core is define a common name and place for this file and describe how it would be interpreted. In other words, esp a spec.

[mojavelinux]

I think we should allow the data to be stored underneath the asciidoc key. If present, the value of that key will be used as the config data. This allows the configuration file to contain other things (for example, an Antora playbook file).

Here's an example:

asciidoc:
  attributes:
    toc: ''

[mojavelinux]

We will tolerate either String or Symbol keys for portability.

[mojavelinux]

I just submitted a PR. Interested to hear some feedback before we move forward with it.

[michael-o]

@mojavelinux Shouldn't the key be asciidoctor?

[mojavelinux]

No, we don't want it to be bound to the processor. This is AsciiDoc configuration we are talking about. That is the model we adopted for Antora and we're going to stick with that.

I suppose maybe we could consider looking for either key...but the preferred key is asciidoc.