Default horizontal style for labelled lists

classic Classic list List threaded Threaded
24 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Default horizontal style for labelled lists

gregopet
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!
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

Linda
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




Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

gregopet
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 :) )
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

Linda
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..)?
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

abelsromero
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.
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator

On Fri, Mar 24, 2017 at 12:52 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
I think that in this case you will need to use a custom extension to adapt the properties of the block of the list.


Exactly right! This is the type of use cases that the Treeprocessor extension was designed for. Here's some code you might use to do that:

require 'asciidoctor/extensions'

Asciidoctor::Extensions.register do
  treeprocessor do
    process do |doc|
      (doc.find_by context: :dlist).each do |dlist|
        dlist.style = 'horizontal'
      end
      nil
    end
  end
end

I'm programmatically applying the horizontal style to all dlist blocks (description lists). You have to option of writing this extension in Java, but recall that AsciidoctorJ can also use extension written in Ruby.

Cheers,

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator
In reply to this post by Linda

On Tue, Mar 21, 2017 at 9:30 AM, Linda [via Asciidoctor :: Discussion] <[hidden email]> wrote:
[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.

While that's true, the horizontal description list already does this for you...so it's essentially the same thing (but less semantic).

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator
In reply to this post by gregopet
There are two things to always remember with Asciidoctor:

1. You can modify the parsed document tree to your hearts content using the extension API
2. You can customize the generated HTML by providing your own converter or customize per-node by providing custom templates

Pass it on ;)

> BTW, thanks for the great tool!

You're welcome. Thank you for being part of the community!

-Dan

On Tue, Mar 21, 2017 at 8:00 AM, gregopet [via Asciidoctor :: Discussion] <[hidden email]> wrote:
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!


If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/Default-horizontal-style-for-labelled-lists-tp5400.html
To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML



--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

gregopet
In reply to this post by gregopet
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!
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

gregopet
In reply to this post by mojavelinux
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..?
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

Linda
You're missing an ' after horizontal?
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

Linda
In reply to this post by mojavelinux
It was meant to be a suggestion in case setting the list defaults wouldn't work :-)
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator
In reply to this post by gregopet

On Fri, Mar 24, 2017 at 7:04 AM, gregopet [via Asciidoctor :: Discussion] <[hidden email]> wrote:

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

If you're writing an extension in AsciidoctorJ, you have to be using AsciidoctorJ 1.6.0.alpha.3. The model just wasn't stable enough to use for extensions in AsciidoctorJ 1.5.x. Others my disagree, but that is the position I stand by.

Cheers,

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator
In reply to this post by Linda

On Fri, Mar 24, 2017 at 7:22 AM, Linda [via Asciidoctor :: Discussion] <[hidden email]> wrote:
It was meant to be a suggestion in case setting the list defaults wouldn't work :-)

👍


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

abelsromero
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.
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator
Thanks for the insight, Abel!

On Fri, Mar 24, 2017 at 8:38 AM, abelsromero [via Asciidoctor :: Discussion] <[hidden email]> wrote:
On one side, not even the last version of the DSL is compatible with Asciidoctorj v1.6.0.

We might want to focus on getting 1.6.0 alpha and a new DSL released. We definitely want to keep those moving forward. Perhaps we can plan for that as part of the 1.5.6 release train.

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

abelsromero
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.
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

gregopet
In reply to this post by abelsromero
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
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

mojavelinux
Administrator

On Fri, Mar 24, 2017 at 9:10 AM, gregopet [via Asciidoctor :: Discussion] <[hidden email]> wrote:
Thanks, using context: ":dlist" works! And the setter fails like you said it would

We could certainly consider adding this setter to AsciidoctorJ 1.5.6 if you managed to make it that far. Just open a feature request. 1.5.6 is coming soon.

-Dan


--
Dan Allen | @mojavelinux | https://twitter.com/mojavelinux
Reply | Threaded
Open this post in threaded view
|

Re: Default horizontal style for labelled lists

gregopet
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..
12