Add configuration option for specifying custom attributes

[mojavelinux]

Add a configuration option for specifying custom attributes. Presumably, this entails adding an options page for the extension.

The custom attributes are intended as a user-preference for controlling how documents are rendered by the extension globally. Per-document attributes are best placed in the document being rendered, at least for now.

Since Asciidoctor can accept attributes as a String of space-separated key/value attribute pairs, its sufficient to use a simple String option. For example:

• Custom attributes: [ idprefix idseparator=- numbered sectanchors ]

(the square brackets emulate an input field in the configuration dialog)

[mojavelinux]

The YSlow extension has a very simple implementation of an options screen for reference:

https://github.com/marcelduran/yslow/tree/master/src/chrome

[ggrossetie]

Custom attributes: [ idprefix idseparator=- numbered sectanchors ]

Sorry but I didn't quite understand your custom attributes.
idprefix and idseparator are keys and numbered and sectanchors are values ? =- is a delimitor symbol between keys and values ?

Then I just add theses attributes to the option parameter in the render method ?

Opal.Asciidoctor.$render(data, ASCIIDOCTOR_OPTIONS);

[ggrossetie]

@mojavelinux I think I get it: http://asciidoctor.org/docs/user-manual/#attributes

idprefix is a name attribute
idseparator is a name attribute with the value - (separator =)
numbered is a name attribute
sectanchors is a name attribute

The preferred way is to insert attributes on top of the document ?

[mojavelinux]

idprefix and idseparator are keys and numbered and sectanchors are values ? =- is a delimitor symbol between keys and values ?

Each entry is a key/value pair separated by whitespace. The value is optional. The default value is empty string. When a value is specified, a = delimiter is used to separate the key and the value.

Here's the formal version of the sample attributes I gave:

idprefix= idseparator=- numbered= sectanchors=

Here's how that attribute list would look if passed to the asciidoctor cli (for comparison):

-a idprefix -a idseparator=- -a numbered -a sectanchors

The Asciidoctor API understands how to parse space-separated options from a string. That makes it possible to capture and pass on custom attributes from the user using a simple text field. We could make the UI more complex, but we can start there at least.

The preferred way is to insert attributes on top of the document?

It depends. For settings that are specific to a document, yes. For personal preferences that you want applied to all documents you render, passing a configuration string to the API is preferable.

Remember, the extension is often rendering documents not under your control.

I'll give you an example. Let's say I want to add a toc to all documents I view. I would set the following value on the extension's configuration screen:

toc=left toc-placement=auto toc2!

Now I'm guaranteed to have a toc that overrides any document-specific setting. I think this would be a very nice feature.

Make sense?

[mojavelinux]

Excellent! This opens the doors to lots of possibilities in the future.

One minor thing. You can pass the attributes as a String and Asciidoctor
will chop them up into individual key value pairs. No need for the split
call.

[mojavelinux]

...ah, except my point doesn't apply until we're on 0.1.4. So that change
will have to wait.