Create a guard plugin

[mojavelinux]

Create a guard plugin for Asciidoctor. This plugin should be created as a separate repository under the asciidoctor organization.

The plugin can be modeled after plugins with similar purpose, such as guard-haml, guard-slim, guard-sass, guard-less, etc.

See list of available guards: https://github.com/guard/guard/wiki/List-of-available-Guards

We want to be on that list :)

[paulrayner]

I have a working Guard plugin for Asciidoctor at https://github.com/paulrayner/guard-asciidoc. It currently runs Asciidoctor with no parameters/attributes.

Next I would like to add support for passing attributes such as stylesheet, stylesdir, backend, safe mode etc. I see two main options:

1. Other Guard plugins such as Guard Cucumber enable you to pass in CLI args via the Guardfile config, which are then passed directly to the gem being run. This pass-through approach makes handling configuration easy and extensible, but since I am calling Asciidoctor from Ruby directly that approach is less seamless since I expect I will need to parse the CLI args in the plugin.
2. Another option is to support passing in only a few of the most common attributes (such as stylesheet, stylesdir, backend) , which is the approach taken by Guard Markdown.

Suggestions? I'm leaning towards option 2. It's less extensible, but much easier to use.

[mojavelinux]

I gave it a run through and came up with some ideas for how to honor Asciidoctor options. I think it's as simple as forwarding the guard options on to Asciidoctor.

guard :asciidoc, :eruby => 'erubis', :backend => 'docbook', :attributes => {'toc' => ''}

If overrides are needed per document, they can always be set in the document itself. To make that easier, I've assigned the attribute 'guard' so that you can do conditional inclusion, such as:

ifdef::guard[]
:stylesheet: my-test-stylesheet.css
endif::guard[]

With the changes I made in https://github.com/paulrayner/guard-asciidoc/pull/1, using the plugin is as simple as:

Guardfile

guard :asciidoc

[mojavelinux]

Once we get our changes synced, let's move this repo to the asciidoctor org. Agreed?

[mojavelinux]

Btw, I was using guard-coffeescript as a reference point. It seems to be one of the more flexible plugins.

[paulrayner]

👍 👍 This is excellent! I took a quick look at what you came up with and really like it. I didn't look at the coffeescript plugin, so I'm glad you found that one and were able to come up with something so good.

I'll probably need some help moving the repo once we get to that point, so hopefully you can help me with that. Will it keep the history to-date of my changes?

[mojavelinux]

Cool. The one area I left rough around the edges is the run_all method, which just grabs anything that looks like an AsciiDoc document and runs it through Asciidoctor. I'm not sure how that's supposed to know if the file has changed.

Don't worry about moving the repo. That's just a click of a button on my end. It keeps the repository and all related pages intact. All you have to do after that is fork it into your own username so that you still have your original URL, only now it's downstream from the repo.

I find that putting the projects in the organization works best for collaboration.

Btw, I recommend setup up a Rake build to handle building the gem. It's not too difficult for the few basic tasks that you have. You can probably steal it form another guard plugin.

[paulrayner]

I merged your pull request. Please go ahead and move the repo into the AsciiDoctor repo now. I'll then use that as the basis for future changes. Thanks so much for working so well with me on this as I "learn the ropes." 😅

Once you've got the plugin in the AsciiDoctor repo I'll add the Rake file and backfill some rspec tests.

[mojavelinux]

Paul, you're doing awesome. I'm thrilled to have the opportunity to work with you on this project.

If you have any questions, don't hesitate to ask. I'll do the same. We're in the learning process together.

I've transferred the repository and made you an admin of it. Welcome to the org!

https://github.com/asciidoctor/guard-asciidoc

To make your repository a fork, you'll need to refork from the organization repo. You'll first need to delete your own repository (or rename it if you want the peace of mind before deleting it).

I recommend working from a fork even in the case when you control the upstream. That way, you just get in the habit of creating pull requests to be on equal footing and process w/ contributors. Transparency ftw!

[mojavelinux]

Closing issue now that the repository and prerelease is up and running. We'll field issues w/ the plugin in the issue tracker for that repository. On guard!

[paulrayner]

🍻 I'm having a good time. I'll buy you a real beer sometime soon.

As to reforking - done! I'll make the changes you suggested, and flesh out the README a little more. What else needs to be done before I publish it as a Gem to Rubygems? What would you recommend I make the Gem version for when the first official release when I publish it to Rubygems?

It looks like there might be still a few housekeeping things I need to do to get it on the official list of Guard plugins. Once it's ready I'm guessing someone will need to fork the guard-asciidoc repo into the Guard organization. I'm not sure how to make that happen.