Default horizontal style for labelled lists

Hey,

Is it possible to set the default style for labelled list to be horizontal? I'm using a plugin to convert Swagger API definitions to Asciidoctor source files and I'm using labelled lists to document various enumerations. The definitions are short and look much better using the horizontal style, pasting [horizontal] all over my Swagger configuration isn't very appealing, though.


BTW, thanks for the great tool!

I don't know if/how it would be possible to change the labelled lists to horizontal by default.

But perhaps using the table structure gives you the desired output?
[cols="s,a", frame="none", grid="none"] would give you a strong first column and in the second column the possibility to use asciidoc syntax. frame="none" removes the borderlines, grid="none" removes the grid lines.

If you want to read more about tables:
http://www.methods.co.nz/asciidoc/chunked/ch23.html
http://asciidoctor.org/docs/user-manual/#tables

Tables are problematic in my case because the rest of the generated documentation uses tables heavily and if I start changing the table defaults I'm likely to break a lot of what the tool gives me. Though provided that a table's defaults can be set, I'd try it - can they be changed? :)

Labelled lists work well because the same source ends up in multiple places. Besides the generated .adoc files, the comment also appears in generated code comments which is very valuable because of IDE hints. The labelled list syntax is very legible in code comments, e.g.:

/**
 * STATIC:: Thingies that never move, implies STATIC_FOO_BAR
 * MOVING:: Mobile thingies
 * MIXED:: Things to be treated like MOBILE but have STATIC_FOO_BAZ
 */
public enum InternetThingy {
    STATIC, MOVING, MIXED;
}

Numbered lists also work great when the keys are numbers (happens a lot in my actual case), but then some of them don't start with 1 (which I can solve relatively unobtrusively) and others have gaps in the numbering (which involves a lot more markup to solve). Having too much Asciidoc markup in there is what I'm trying to avoid (though perhaps I could modify the tool to drop comments encased in [] when it's not generating Asciidoc). Defaults for labelled lists would elegantly solve all my current problems  :)

(obviously, it would be best to have a comment for each enum value separately, but Swagger is very much not there yet :) )

Look what I found :)

http://www.methods.co.nz/asciidoc/faq.html#_how_can_i_set_default_list_and_tables_styles

Does this help you (instead of steering you into the tables..)?

I think that's for the AsciiDoc Python implementation. At least I tested and does not seem to work on Asciidoctor.

I think that in this case you will need to use a custom extension to adapt the properties of the block of the list.

I will try plugging that extension into my build - Java is easier for me, I will have a go at simply extending the pipeline in Gradle.

Thanks everybody!

Well in theory this should be simple in the Gradle extension:

treeprocessor { Document document ->
	document.findBy(context:"dlist").each { it.style = 'horizontal }
}

However, the findBy method doesn't return anything. I tried iterating through all the blocks using document.blocks() but that got me a "org.jruby.exceptions.RaiseException: (NoMethodError) undefined method `level' for nil:NilClass".

Then I figured out that I can do "document.documentRuby.findBy(context:"dlist")" and get some actual blocks back, unfortunately they are of all sorts (sections, paragraphs, tables..). Though some defensive coding I can then target only definition lists, however I get "No such property: style for class: org.jruby.RubyObject" when trying to set the style.

Am I doing something wrong? And if not, where can I start filing issues? Asciidoctor core, AsciidoctorJ, the Gradle plugin..?

You're missing an ' after horizontal?

It was meant to be a suggestion in case setting the list defaults wouldn't work :-)

First of all, to select the elements from Java, you need to prefix it with ':'. The following example allowed me to obtain the 3 labeled lists in a document without problems.

    extensions {
        treeprocessor() {
            document.findBy(context:':dlist').each {
                it.style = 'horizontal'
            }
        }
    }

Then, back to the topic, I am afraid this can't be done from the Groovy DSL right now.
On one side, not even the last version of the DSL is compatible with Asciidoctorj v1.6.0. Some classes have been renamed and the extension loader fails. On another, AsciidoctorJ v1.5.5 does not allow to set the style, it simply lacks the setter method.

So, you will have to use AsciidoctorJ v 1.6.0 which includes a setStyle method and build an extension in Java or Groovy as a separate class. Then add it as a dependency or buildSrc, see https://github.com/asciidoctor/asciidoctor-gradle-plugin#adding-custom-extensions.

Honestly, with all this in mind, I would try to integrate the Ruby extension using AsciidoctorJ 1.5.5 using the `requires` and `getPaths` options of the gradle plugin.

What do you propose?

Ideally we would like to have a DSL compatible with 1.5.x and another with 1.6.x, that means keeping two branches same way we do with Asciidoctorj.
I can't think of any other way.

Thanks, using context: ":dlist" works! And the setter fails like you said it would

So now if I understand correctly I would have to create my extension class in another build so I can compile it against AsciidoctorJ 1.6.0 and then plant it to the Gradle plugin which would still be running Asciidoctor 1.5.*?

I will maybe try it during the weekend, but honestly the extra line breaks in the documentation are not bothering me enough yet to have another build in the project

Sure, I can open an issue, but those newlines are really not a big inconvenience right now so if you guys have more important things to do, I'm quite OK to wait for it a bit. Still a huge fan of Asciidoctor, this is my 3rd or 4th project that I'm documenting with it, just the first time I included Swagger in the mix..

BTW, do you keep a list of entry level tasks anywhere? For any of the Java/Groovy parts as I'm Ruby-phobic? In case of rainy weekends in the future..