Create chart block extension

[ggrossetie]

Rough draft using chart.js Ref #2

Given sample.adoc

= Chart Block Macro Extension

chart::line[data-uri="sample.csv"]

sample.csv

January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40

Then

[mojavelinux]

This is a great start. I say let's merge it. Ready?

[mojavelinux]

How do you feel about c3.js (http://c3js.org/examples.html) over chart.js? I'm not well versed in either, so I'm not sure which is a better choice.

[ggrossetie]

Meh, the code looks simpler, I will give it a try :) Maybe we can add an attribute chart-renderer to use chart.js or c3js ?

[mojavelinux]

chart-library? But yes, indeed. Another option is to have multiple block names like Asciidoctor Diagram does:

[chart]

[c3]

or use a role:

[chart]

[chart.c3]

[ggrossetie]

I just saw http://discuss.asciidoctor.org/d3-js-integration-for-Asciidoctor-Diagram-td2259.html that's nice :smile:

[ggrossetie]

With c3.js:

[bartoszmajsak]

I think c3js (as well as chartist.js) advantage over chart.js is that they are both based on SVG instead of canvas. Great stuff!

[ggrossetie]

@bartoszmajsak Thanks, just for my knowledge, why SVG is better than canvas ?

Not sure which one to pick ? try them all :smile:

chart::line[data-uri="sample.csv"]

chart::bar[data-uri="sample.csv"]

chart::step[data-uri="sample.csv"]

chart::spline[data-uri="sample.csv"]

[bartoszmajsak]

I think this sums it up pretty well http://msdn.microsoft.com/en-us/hh552482.aspx :)

[bartoszmajsak]

Or in brief - I think vector graphic is way better for charting rather than raster. +more memory efficient

[mojavelinux]

Great stuff!

To be consistent with the <name>::<target>[<attributes>] convention, I think we should change the placement of arguments so the data is <target> and the chart type is the first positional attribute. I think chart type should default to "line" if not specified.

chart::sample.csv[line]

chart::sample.csv[bar]

chart::sample.csv[step]

chart::sample.csv[spline]

I think we should also support positional attributes for x and y label as well as size.

chart::<data-uri>[<type>,<x-label>,<y-label>,<width>,<height>]

wdyt?

[mojavelinux]

Eventually, we could also support a block form where the data is specified in a literal block:

[chart,line]
....
January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40
....

[ggrossetie]

@bartoszmajsak Thanks for the detailed explanation :smile:

@mojavelinux

chart::<data-uri>[<type>,<x-label>,<y-label>,<width>,<height>]

I agree.

[chart,line]
....
January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40
....

That's nice, the notation is four dot, not four dash ? And could you give me a hint on how to retrieve this block in the process method ? Thanks

[mojavelinux]

That's nice, the notation is four dot, not four dash ?

I tend to use four dashes (listing) for example code and four dots (literal) for data. It's something that still needs to be defined better in AsciiDoc, but that's sort of my thinking atm. (That's why I like to use four dots for diagrams too.)

And could you give me a hint on how to retrieve this block in the process method ?

I'll point you to the textql extension, which does something very similar (transform data).

https://github.com/asciidoctor/asciidoctor-extensions-lab/blob/master/lib/textql-block.rb

It's reader.source or reader.lines. See http://rubydoc.info/gems/asciidoctor/Asciidoctor/Block

[ggrossetie]

I tend to use four dashes (listing) for example code and four dots (literal) for data.

Got it

I'll point you to the textql extension, which does something very similar (transform data).

The textql extension is using BlockProcessor with method def process parent, reader, attributes. I'm using a BlockMacroProcessor with method def process parent, target, attributes (note the target argument instead of the reader argument). The document on BlockProcessor gives this example:

[shout]
Get a move on.

I'm a little bit confused, can I use a BlockProcessor with a macro <name>::<target>[<attributes>] ?

[mojavelinux]

You need to register two extensions. Probably create an abstract base class that shares the logic, then delegate to it.

[ggrossetie]

I read too quickly, you are using [chart,line] when the data is specified in a literal block. Ok that makes sense and I think this is "AsciiDoc way" of doing it but I don't like having two notations.

The difference between a block and a macro can be confusing for users. IMHO this is more consistent in this (maybe particular) use case:

chart::<data-uri>[<type>,<x-label>,<y-label>,<width>,<height>]

chart[<type>,<x-label>,<y-label>,<width>,<height>]
....
January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40
....

The other notation is not working well (because of the optional <data-uri> attribute) :

[chart,<data-uri>,<type>,<x-label>,<y-label>,<width>,<height>]

[chart,<type>,<x-label>,<y-label>,<width>,<height>]
....
January,February,March,April,May,June,July
28,48,40,19,86,27,90
65,59,80,81,56,55,40
....

[mojavelinux]

chart[,,,,] .... January,February,March,April,May,June,July 28,48,40,19,86,27,90 65,59,80,81,56,55,40 ....

Unfortunately, that syntax is not possible atm. But I think since it's consistent that all delimited blocks use the first positional attribute as the block name, that's just the AsciiDoc way.

[ggrossetie]

Can we merge this with the first notation only, then add the other notation (literal block) ? I would like to include this extension in the Chrome extension :smile:

[mojavelinux]

I'm cool with merging it now and implementing these changes as we go along. Let's make sure we get it updated to the point we agree on a basic structure of the block before putting it in the Chrome extension so we don't disrupt usage, though.

[mojavelinux]

I filed an enhancement request to track the requested updates.

https://github.com/asciidoctor/asciidoctor-backends/issues/105