Asciidoctor :: Discussion

screenshot plugin for asciidoctor

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

6 messages Options

fix

Aug 25, 2014; 8:16pm

screenshot plugin for asciidoctor

This post was updated on Aug 25, 2014; 8:53pm.

Hi guys

I have just released a gradle plugin to automate your screenshots in asciidoctor
http://fix.github.io/asciidoctor-screenshot/

It is simple and powerful i think
It leverages the awesome geb library

I would some help
- to package it as a gradle plugi
- create more examples
- add more frames/options

I have also started some proof of concept to drive BDD towards what can be called DDD Documentation Driven Development. It is some kind of supercharged cucumber with asciidoctor and this screenshot plugin

The idea is to write documentation before and validate and complete on development stage.

I would welcome some cuke mastermind to givr me a hand

Cheers

mojavelinux

Sep 21, 2014; 1:27am

Re: screenshot plugin for asciidoctor

Administrator

FX,

This is really fantastic! It's exactly the type of integration between automation and documentation that we want to encourage to help keep documents up to date and integrated with the application's functionality!

I'd like to make a few suggestions that will help align the extension syntax with the AsciiDoc convention.

First, the title of the image block should be read from the title attribute instead of the body of the block. For example, instead of writing:

[source,asciidoc]

----

[screenshot, name=google, url=http://google.com, dimension=FRAME_IMAC]

The Google landing page

----

We'd want:

[source,asciidoc]

----

.The Google landing page

[screenshot, name=google, url=http://google.com, dimension=FRAME_IMAC]

----

You can access the title from the attributes map that is passed to the extension.

However, it becomes clear that since we have no text in the block, it won't get processed. That's why I think "screenshot" should be a block macro instead of a block. (Thus, we'd need two extensions instead of one).

[source,asciidoc]

----

.The Google landing page

screenshot::[name=google, url=http://google.com, dimension=FRAME_IMAC]

----

Block macros tend to follow the pattern <name>::<target>[<attributes>], so we'd want to move the URL to the <target> location. That gives us:

[source,asciidoc]

----

.The Google landing page

screenshot::http://google.com[name=google,dimension=FRAME_IMAC]

----

That leaves us with the "action" blocks. I think perhaps we should either assume that a screenshot block (not block macro) is an action, or we rename it to something like "browse" to indicate it's driving a browser (perhaps we can drive a browser for other purposes, like tests).

[source,asciidoc]

----

[browse]

....

$("input", name: "q").value("asciidoctor")

waitFor(5){true}

....

----

I think the "browse" should be registered on literal blocks in addition to paragraphs, with the literal block being the preferred syntax (as shown in the previous example). That keeps the text from being interpreted in the absence of the extension (like on GitHub).

You might also want to consider the use of positional attributes for any required attributes to make the syntax simpler. For instance, you could make the dimensions of the window the first positional attribute on the "browse" block:

[source,asciidoc]

----

[browse,iphone5]

....

$("input", name: "q").value("asciidoctor")

waitFor(5){true}

....

----

Notice I used the value "iphone5" instead of FRAME_IPHONE5. I think you could do the conversion automatically.

Again, this is great stuff!

Once you converted the project to a standalone extension, I think it would be a great addition for the Asciidoctor org on GitHub. Since the extension is written for Java, I recommend naming it asciidoctorj-screenshot. In the future, we could have a Ruby version too.

Cheers,

-Dan

On Mon, Aug 25, 2014 at 2:16 PM, fix [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi guys

I have just released a gradle plugin to automate your screenshots in asciidoctor
http://fix.github.io/asciidoctor-screenshot/

It is simple and powerful i think
It leverages the awesome geb library

I would some help
- to package it as a gradle plugi
- create more examples
- add more frames/options

Cheers

If you reply to this email, your message will be added to the discussion below:
http://discuss.asciidoctor.org/screenshot-plugin-for-asciidoctor-tp2072.html

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

... [show rest of quote]

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

fix

Sep 21, 2014; 12:54pm

Re: screenshot plugin for asciidoctor

Hi Dan, thanks for the feedback,

I have to say I agree most of your comments, I felt that the block processing was a bit awkward. I' am doing the necessary changes.

I need however a few hints :
- how to make it as a full asciidoctorj plugin? The only example I have (and i started from) is the pig latin plugin released by andres, which is incomplete in that rescpect. Any hint welcome.
- Also, as you may see in the source code, I use a hack to be able to frame correctly the screenshots (iphone, imac etc...), using the "alt" arg of the tag to apply css. I have not discovered (I do think this is unaccessible) a way to hook in "class".

Cheers,
Fix

mojavelinux

Sep 21, 2014; 11:06pm

Re: screenshot plugin for asciidoctor

Administrator

Excellent!

On Sun, Sep 21, 2014 at 6:54 AM, fix [via Asciidoctor :: Discussion] <[hidden email]> wrote:

- how to make it as a full asciidoctorj plugin? The only example I have (and i started from) is the pig latin plugin released by andres, which is incomplete in that rescpect. Any hint welcome.

Alex has several examples of extensions for AsciidoctorJ in his extension repo {1}. (We should be migrating those into the Asciidoctor organization soon.)

- Also, as you may see in the source code, I use a hack to be able to frame correctly the screenshots (iphone, imac etc...), using the "alt" arg of the tag to apply css. I have not discovered (I do think this is unaccessible) a way to hook in "class".

Aha, that's an easy one. The "role" attribute becomes the "class" attribute in the HTML output. Pass it to the createBlock method {2} when you create the image.

Cheers,

-Dan

:1: https://github.com/lordofthejars/asciidoctorj-extensions

:2: https://github.com/fix/asciidoctor-screenshot/blob/master/buildSrc/src/main/groovy/org/asciidoctor/extension/ScreenshotBlock.groovy#L75

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

wimalopaan

Mar 18, 2015; 10:54am

Re: screenshot plugin for asciidoctor

In reply to this post by fix

Hi all,

is there a chance to use this plugin with asciidoctor? I think its only a plugin for asciidoctorJ ?

mojavelinux

Apr 01, 2015; 5:39pm

Re: screenshot plugin for asciidoctor

Administrator

On Wed, Mar 18, 2015 at 11:54 AM, wimalopaan [via Asciidoctor :: Discussion] <[hidden email]> wrote:

is there a chance to use this plugin with asciidoctor? I think its only a plugin for asciidoctorJ ?

Currently it's only for AsciidoctorJ. This is definitely something to consider when writing plugins. Plugins written in Java can't (easily) be used from Ruby (perhaps there is a way). The other way around is very possible.

I suppose the plugin would need to be rewritten in Ruby if you want to use it from there. But at least the logic is done so it's just a matter of porting the code.

-Dan

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