Using PlantUML and blockdiag with asciidoctor

Pepijn,

Glad to help! Little do you know, you (and Alex) are now the role model for extension writers :)

Your updates look great! The ASCII-art support is a nice touch.

> On the testing front I was wondering in particular how I should write the assertions.
> Is there an easy way to dig into the Document object? Something xpath-ish perhaps?

Using xpath to verify the output tends to be pretty hit or miss and the thing I dislike the most about the current Asciidoctor test suite. I think it's far better to just verify the expected output, or at least grab the most relevant fragment of HTML or XML and verify it matches what you expect.

The tricky part about matching HTML and XML is formatting. That's one of the main reasons I've removed all indentation from the output that Asciidoctor generates. Indentation is just messy and has no semantic meaning anyway. Thus, it should be easier to verify directly against the HTML and XML.

What I've done the in Cucumber tests is find a way to compare by structure using the Slim language. The slim template is rendered to HTML and I compare that against what Asciidoctor generates. That way, the assertion is kept at a higher level.

> If you feel the code is up to snuff, I have no objection at all to adding it under the asciidoctor umbrella. Honoured in fact.

Excellent! I've given you transfer permissions. When you are ready, you just go into the admin page on the repository and transfer it to the organization. That moves everything, including the issues and forks. Then, just fork it back into your personal space. I'll assign you the admin role on the repo and you remain the lead.

> There's still more testing to do (on JRuby in particular; Open3 has issues under JRuby IIRC) before I would consider it releasable though.
> Need to write more test cases that actually assert something as well :)

Keep in mind there's always room for improvement, so once you have a few tests running, I encourage you to release a 1.0.0.alpha.1 version. Personally, i think starting with 0.0.1 puts you in the situation we got in with Asciidoctor. You never seem to get to 1.0.0. Let's call a first release what it is, 1.0.0 :)

In the Ruby world, the version qualifiers seem to go something like: preview.<n>, alpha.<n>, beta.<n>, rc.<n>, and finally the unqualified version. You can see an example here: http://rubygems.org/gems/haml/versions. You typically only use preview once a project is mature and you are experimenting with a brand new major version. I recommend starting with alpha.1.

After the 1.0.0 release, you might want to consider keeping the JVM warm by using some sort of spawning approach if available. You can fall back to java -jar for platforms that can't handle it. You could also detect the JRuby environment and see if the plantuml classes are already available. Just some ideas.

Cheers!

-Dan

--

Dan Allen | http://google.com/profiles/dan.j.allen

I think I was a bit imprecise in my single/multiple question. What I had in mind was one or multiple gems. In terms of asciidoctor I think multiple extensions is the way to go. I think we want distinct block types for plantuml, ditaa, blockdiag, etc; not everything under the same name. That way it's very clear from the asciidoc source what you're actually doing.

If you have a look at the plantuml extension you'll see that only a small part is actually plantuml specific code. The rest is infrastructure code that computes code checksums, writes cache files, generates attribute values, writes the images to the correct location, etc. All that is pretty much independent of the diagram generator that is actually used. It feels wasteful to duplicate this boilerplate code multiple times. Keeping everything in a single gem is a simple way to make it possible to reuse the code. Alternatively this could be put in a separate gem that's a dependency of the other ones, but that feels a bit like overengineering to me. I think this boils down to 'do we want many tiny gems or one fat gem'?

Pepijn

On 12-02-14 10:39, asotobu [via Asciidoctor :: Discussion] wrote:

About license, no idea sorry. About creating one or more extensions, in my opinion I would prefer more than one, but of course you have the knowledge of the whole picture. I say one extension for each one because each one renders diagrams in different way, plantUML is an old style and for example ditaa is more modern, so users can get confused on using same extension and receiving different output, but of course if you think it is better in only one, go ahead.

Alex

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1438.html

To unsubscribe from Using PlantUML and blockdiag with asciidoctor, click here.
NAML

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1439.html

To unsubscribe from Using PlantUML and blockdiag with asciidoctor, click here.
NAML

Small update on the ditaa license front. I was looking at the old sourceforge repo which had GPLv2 as license. The newer github repo (https://github.com/stathissideris/ditaa) has it as LGPLv3 which should not be a problem (I think). Not sure if LGPL would allow embedding the jar in the gem though. I'll have a more in depth look at it this evening.

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1441.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Licensing is an area where I feel pretty confident.

Mixing licenses only becomes an issue when you are *modifying* the other project's source code. The license dictates what your obligations are with regard to those changes.

All major open source licenses give you full rights to redistribute the original, unmodified binaries or source code. In our case, that's exactly what we are doing. The fact that we integrate with that unmodified code doesn't impose any sort of restrictions (or taint) our code, especially if its LGPL.

What is important is that we preserve any notices that come from the original project. That's where the attribution bit comes in. The way I've handled this is to create a section in the LICENSE file called "other licensed work" and clearly state the licenses for any projects we are using.

See https://github.com/opendevise/asciidoctor-pdf/blob/master/LICENSE for an example.

-Dan

On Wed, Feb 12, 2014 at 9:50 AM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Small update on the ditaa license front. I was looking at the old sourceforge repo which had GPLv2 as license. The newer github repo (https://github.com/stathissideris/ditaa) has it as LGPLv3 which should not be a problem (I think). Not sure if LGPL would allow embedding the jar in the gem though. I'll have a more in depth look at it this evening.

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1441.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | http://google.com/profiles/dan.j.allen

Could you guys have a look at https://github.com/asciidoctor/asciidoctor-plantuml/pull/12 ?

Proposal is to change the gem name to asciidoctor-diagrams since it then handles plantuml and ditaa. I'm planning on adding support for the blockdiag suite and raw graphviz .dot syntax as well. And then I'm done :)

Figured out how to get the regular and jruby variant of the gem built in the meantime as well, so it's pretty much ready for publishing at this point. If the name change is ok, I would like to do that first though.

Pepijn

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1445.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

Pepijn,

Given that these extensions all follow a very similar pattern, it does make sense to group them. I would suggest the name asciidoctor-diagram (singular) instead of asciidoctor-diagrams (plural), though, as that seems to be the accepted naming pattern (though still subjective).

Since each diagram tool has unique capabilities, I could see the need to have separate gems. However, we could start with a single gem and then branch out once we feel the friction of having them coupled, following the organic growth strategy.

One thing I would change in the pull request though is to preserve the ability to import the extensions with and without auto-registration. Thus, I recommend the following structure under lib:

asciidoctor-diagram.rb
asciidoctor-diagram/

  extension.rb

  ditaa.rb

  ditaa/

    extension.rb

  plantuml.rb

  plantuml/

    extension.rb

The "ditaa/extension.rb" and "plantuml/extension.rb" files have the implementation code. The "ditaa.rb" and "plantuml.rb" have the auto-register code for each extension. The "asciidoctor-diagram.rb" has the auto-register code for both. The "asciidoctor-diagram/extension.rb" just requires all the implementations without auto-registering.

In this way, you can use this import to auto-register all:

 require 'asciidoctor-diagram'

You can use this import to auto-register just plantuml:

 require 'asciidoctor-diagram/plantuml'

And you can use this import just to import the implementation code for plantuml:

 require 'asciidoctor-diagram/plantuml/extension'

Make sense?

-Dan

On Wed, Feb 12, 2014 at 4:03 PM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Could you guys have a look at https://github.com/asciidoctor/asciidoctor-plantuml/pull/12 ?

Proposal is to change the gem name to asciidoctor-diagrams since it then handles plantuml and ditaa. I'm planning on adding support for the blockdiag suite and raw graphviz .dot syntax as well. And then I'm done :)

Figured out how to get the regular and jruby variant of the gem built in the meantime as well, so it's pretty much ready for publishing at this point. If the name change is ok, I would like to do that first though.

Pepijn

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1445.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | http://google.com/profiles/dan.j.allen

Pepijn,

Given that these extensions all follow a very similar pattern, it does make sense to group them. I would suggest the name asciidoctor-diagram (singular) instead of asciidoctor-diagrams (plural), though, as that seems to be the accepted naming pattern (though still subjective).

Since each diagram tool has unique capabilities, I could see the need to have separate gems. However, we could start with a single gem and then branch out once we feel the friction of having them coupled, following the organic growth strategy.

One thing I would change in the pull request though is to preserve the ability to import the extensions with and without auto-registration. Thus, I recommend the following structure under lib:

asciidoctor-diagram.rb
asciidoctor-diagram/

  extension.rb

  ditaa.rb

  ditaa/

    extension.rb

  plantuml.rb

  plantuml/

    extension.rb

The "ditaa/extension.rb" and "plantuml/extension.rb" files have the implementation code. The "ditaa.rb" and "plantuml.rb" have the auto-register code for each extension. The "asciidoctor-diagram.rb" has the auto-register code for both. The "asciidoctor-diagram/extension.rb" just requires all the implementations without auto-registering.

In this way, you can use this import to auto-register all:

 require 'asciidoctor-diagram'

You can use this import to auto-register just plantuml:

 require 'asciidoctor-diagram/plantuml'

And you can use this import just to import the implementation code for plantuml:

 require 'asciidoctor-diagram/plantuml/extension'

Make sense?

-Dan

On Wed, Feb 12, 2014 at 4:03 PM, pepijnve [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Could you guys have a look at https://github.com/asciidoctor/asciidoctor-plantuml/pull/12 ?

Proposal is to change the gem name to asciidoctor-diagrams since it then handles plantuml and ditaa. I'm planning on adding support for the blockdiag suite and raw graphviz .dot syntax as well. And then I'm done :)

Figured out how to get the regular and jruby variant of the gem built in the meantime as well, so it's pretty much ready for publishing at this point. If the name change is ok, I would like to do that first though.

Pepijn

---

If you reply to this email, your message will be added to the discussion below:

http://discuss.asciidoctor.org/Using-PlantUML-and-blockdiag-with-asciidoctor-tp1208p1445.html

To start a new topic under Asciidoctor :: Discussion, email [hidden email]
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

--

Dan Allen | http://google.com/profiles/dan.j.allen