Raise exception when backend cannot be resolved

[mojavelinux]

To be helpful to components that use AsciidoctorJ, such as the Asciidoctor Gradle plugin, raise an explicit exception (e.g., UnresolvedBackendException) when a backend cannot be resolved. This may involve catching the error coming out of Asciidoctor Ruby and throwing it as a typed exception.

Related to asciidoctor/asciidoctor-gradle-plugin#141.

[lordofthejars]

Cool! My question is should it be checked or unchecked? I really prefer unchecked because it leaves a clean API. I mean we can start by creating UnresolvedBackendException then TemplateDirNotFoundException (#231), then .... and finishing with a multi catch problem.

WDYT?

[mojavelinux]

Definitely unchecked. We could probably get away with the same exception in
both cases...or perhaps make the template exception a subclass, since it's
also a backend problem.

[mojavelinux]

Alex, this is good, except I think the exception should be more specific than just AsciidoctorCoreException. It's not that helpful for clients to know that Asciidoctor failed in general. Instead, we are looking to know when it failed for a particular reason. In this case, it's really important to know that it failed because it couldn't resolve a backend (UnresolvedBackendException). Now, this may require a change in core, in which case we can make the change in AsciidoctorJ once the requirement is met in Asciidoctor core.

I do think it's okay to have a generic exception, but it should catch things for which we don't specifically have a type. In that case, I'm in favor of calling it AsciidoctorException instead of AsciidoctorCoreException. I think it's understood that "Asciidoctor" means core.

[lordofthejars]

Yes I know I don't know why now resolves also closes the issues, it wasn't my idea to close this issue. The problem is that Asciidoctor Ruby returns a RuntimeException as is without any type. Then I can only do two things, create a generic exception as Asciidoctor core does, in this case I have looked the code and I have seen that you are calling failmethod without an exception which means untyped RuntimeException is thrown, or I could scan the message and according to the message do one thing or another. The problem with this approach is that if you change the error message then the exception resolver doesn't work.

For this reason my idea was to push this simple code and comment to you, but Github is closing the issue automatically 😠

[lordofthejars]

Concretely https://github.com/asciidoctor/asciidoctor/blob/283f8b23b9b5332363cc3cb4082a5885f2337eab/lib/asciidoctor/document.rb#L1016 according of what I have read here http://stackoverflow.com/questions/18811675/what-does-the-fail-keyword-do-in-ruby

[mojavelinux]

For this reason my idea was to push this simple code and comment to you, but Github is closing the issue automatically

When you merge a pull request, GitHub will close the issue if certain keywords are in the commit message subject. One of those phrases is "resolves #xyz" ;)

Turn the focus to the change, again, it's very clear that now is the time we need to start establishing a more formal integration for failure scenarios. Asciidoctor core was designed originally around command line usage and now we are graduating :) I'll do some digging and see what suggestion I can come up with.