Reusable content and language specific documentation

[ggrossetie]

As part of improving the Asciidoctor.js documentation, I came across this useful appendix that describe the Ruby API options.

As you may know, the JavaScript API options are very similar but with a few exceptions:

• some options are specific to the Ruby environment (for instance eruby)
• some descriptions are referring to Ruby ("instead of providing a Ruby block...", "Tilt-compatible converter templates...", etc...)
• the name of the option are prefixed by : (ie. symbol) while in JavaScript the name is just a String
• the column "CLI equivalent" should be removed (as the asciidoctor.js CLI is still experimental)

To keep the documentation as DRY as possible, I think we should reuse the content.

My first attempt was to use custom attributes to share the description of each option:

// API options description
:api-options-attributes-description: Sets additional document attributes, which override equivalently-named attributes defined in the document unless the value ends with `@`.
:api-options-backend-description: Selects the converter to use (as registered with this keyword).

And then use attribute substitution:

|backend
|[subs="attributes,quotes"]
{api-options-backend-description}
|html5
|html5, docbook5, or any backend registered through an active converter

Upon reflection, it's not a good idea because attributes can not include AsciiDoc block content (and more broadly should not be used to hold content).

Instead I think we should use the include directive to include specific regions of content.

// tag::attributes-description[]   
Sets additional document attributes, which override equivalently-named attributes defined in the document unless the value ends with `@`.
// end::attributes-description[]   

// tag::backend-description[]  
Selects the converter to use (as registered with this keyword).
// end::backend-description[]

|attributes
|include::api-options.adoc[tag=attributes-description]
|_not set_
|Any number of built-in or user-defined attributes in one of the following formats:

Does it make sense ? Should we be concerned by the number of include ? Do you think it's a good idea ?

[mojavelinux]

I would say yes, use includes where you see fit. I don't think we should be concerned about too many includes as long as the include by itself can be viewed as a unit of information. I don't like includes (or even attributes) to replace single words or a short phrase as that just becomes excessive and hard to maintain.

The Antora platform on which the docs are now based make this possible, even across projects.