Asciidoctor :: Discussion

Asciidoctor backends

_‹ Previous Topic Next Topic _›

Classic

List

Threaded

7 messages Options

asotobu

Asciidoctor backends

I started this discussion to talk about how would be the best way to distribute asciidoctor backends.

We have talked about one gem which contains all possible backends, or multiple gems one for each backend.

From my point of view one gem for backend would be the desirable approach, but maybe the development of backends could be a bit more complicated. But on the other hand user will only download the templates are going to use. For example it seems that does not have much sense that if I want to develop slides with deckjs, I have to download dzslide, impress, reveal, html5, docbook, ...

For now we must download the github repository, copy it to a folder and call asciidoctor with -T option.

Alex.

paulrayner

Re: Asciidoctor backends

Thanks Alex for starting this off. Let me back up a little and ask a more foundational question about backends. Bear with me please...

Right now, if I put the RevealJS backend into Asciidoctor backends, the process someone new to Asciidoctor would need to perform to use it is:

* Know that there is a RevealJS backend (Asciidoctor won't be able to tell them it exists, so they would need to search the docs), and that they need to download another gem.
* Download the Asciidoctor backends gem, or the RevealJS Asciidoc backend gem (depending on how we package them).
* Run Asciidoctor with the -T option, pointing to the backend Gem (which could be hidden in some RVM folder somewhere), plus specify '-b revealjs' (but they have no way of knowing this is the correct value.

My concern is it should be easy for someone using Asciidoctor to discover and use backends. Related to this, shouldn't Asciidoctor be able to report what backends are available and how to use them (i.e. what BACKEND value for the '-b' switch)? Also, where will we put the documentation for the backends? RevealJS has a rich set of functionality, and I'll need to document the backend somewhere.

Why are we distributing core Asciidoctor with only the 2 backends (HTML5 & DocBook 4.5)? Is it because these are the "official" backends? It would be helpful to know the motivation for why the backends were broken out in the first place.

What do other tools in our space do? For example, don't pandoc and asciidoc come prebundled with all the backends?

Sorry to derail the thread a little, but I wanted to get a better understanding of the overall philosophy of how we're doing the backends before weighing in on the one vs many question about backend gems.

That being said, having thought about it, I prefer one backends gem, at least for now. The question about the best place to document their usage remains.

asotobu

Re: Asciidoctor backends

Hi Paul,
well first of all let me tell you that I am only developing backends (mainly because I have no idea of Ruby

), so some of questions you asking should be answered by Dan I guess

. Well let's start with what I can answering you:

- You do not require -b option, only -T pointing to backend directory, in https://github.com/asciidoctor/asciidoctor-backends#deckjs-backend you can see an instellation example.

- I completely agree with you that we need some way to install backends in a fashionable way, something like gem install and then the <backend> / or gem install extra-backends with all backends.

- In case of documentation, for now we are using the README.md where we are documenting all supported backends. So if backends are treat as "external", I think it should be a link from official asciidoctor documentation to get backends repo.

- About what you have noticed about "official" backends, I think that Dan would give you a better answer. By default asciidoc (and asciidoctor) comes with these two backends, and I think that in case of asciidoctor are not implemented as HAML or SLIM template, but as native ruby file (Tilt is not used). So asciidoctor extension is implemented using Tilt gem, so if you want to provide an extension it should be done using this second approach. Keep in mind that in case of asciidoc, it is the way how it works.

Of course feel free to ask me as many questions as you had, and I will try to answer it as better as possible, also keep in mind that Dan and all people of asciidoctor are improving it every week, so we should stay alert about possible changes.

And again for any question do not hesitate to contact me.

Alex.

LightGuardjp

Re: Asciidoctor backends

I was just thinking about this in context of the maven and gradle plugins. With these being a different gem, it

1. becomes difficult to add different backends for your build

2. knowing the exact location of the backends, will Ruby explode the jar?

I think we may need to readdress this idea of having the backends be different gems.

On Thu, Mar 7, 2013 at 7:04 AM, asotobu [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi Paul,
well first of all let me tell you that I am only developing backends (mainly because I have no idea of Ruby ), so some of questions you asking should be answered by Dan I guess . Well let's start with what I can answering you:

- You do not require -b option, only -T pointing to backend directory, in https://github.com/asciidoctor/asciidoctor-backends#deckjs-backend you can see an instellation example.

- I completely agree with you that we need some way to install backends in a fashionable way, something like gem install and then the <backend> / or gem install extra-backends with all backends.

- In case of documentation, for now we are using the README.md where we are documenting all supported backends. So if backends are treat as "external", I think it should be a link from official asciidoctor documentation to get backends repo.

- About what you have noticed about "official" backends, I think that Dan would give you a better answer. By default asciidoc (and asciidoctor) comes with these two backends, and I think that in case of asciidoctor are not implemented as HAML or SLIM template, but as native ruby file (Tilt is not used). So asciidoctor extension is implemented using Tilt gem, so if you want to provide an extension it should be done using this second approach. Keep in mind that in case of asciidoc, it is the way how it works.

Of course feel free to ask me as many questions as you had, and I will try to answer it as better as possible, also keep in mind that Dan and all people of asciidoctor are improving it every week, so we should stay alert about possible changes.

And again for any question do not hesitate to contact me.

Alex.

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

http://discuss.asciidoctor.org/Asciidoctor-backends-tp16p24.html

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

Jason Porter
http://en.gravatar.com/lightguardjp

aalmiray

Re: Asciidoctor backends

Ruby n00b here... wouldn't it be possible to query/install/load gems dynamically? Say for example we configure the gradle plugin in such a way a developer that would like to use additional backends and/or asciidoctor version just has to specify the following

asciidoctor {
asciidoctorVersion = '0.2.0'
backend = 'angularjs'
}

With these instructions the plugin will check if asciidoctor-0.2.0 gem is installed, if not, then will fetch and install required files. Next it will check for the angularjs backend, if not available then fetch & install. Finally loads asciidoctor, configures the chosen backend and goes to town with asciidoc sources.

I'd suspect gems can be queried/fetched/installed using a standard Ruby API, can't they?

LightGuardjp

Re: Asciidoctor backends

The problem isn't getting the gem loaded, it's actually how asciidoctor uses backends. It expects a location to be passed where it can find the backend and templates. We could change this, but as it currently stands today, that is the problem, at least as I see it, could be wrong.

On Fri, Mar 8, 2013 at 2:36 AM, aalmiray [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Ruby n00b here... wouldn't it be possible to query/install/load gems dynamically? Say for example we configure the gradle plugin in such a way a developer that would like to use additional backends and/or asciidoctor version just has to specify the following

asciidoctor {
asciidoctorVersion = '0.2.0'
backend = 'angularjs'
}

With these instructions the plugin will check if asciidoctor-0.2.0 gem is installed, if not, then will fetch and install required files. Next it will check for the angularjs backend, if not available then fetch & install. Finally loads asciidoctor, configures the chosen backend and goes to town with asciidoc sources.

I'd suspect gems can be queried/fetched/installed using a standard Ruby API, can't they?

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

http://discuss.asciidoctor.org/Asciidoctor-backends-tp16p30.html

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

Jason Porter
http://en.gravatar.com/lightguardjp

davide.cavestro

Re: Asciidoctor backends

So could this be something to pay specific attention for asciidoctor-java-integration?
For instance it would be great using plantuml and (hence ditaa) without any hassle even from the java library.
That would be great for jira, confluence and so on.

Cheers
Davide

lightguard.jp wrote

The problem isn't getting the gem loaded, it's actually how asciidoctor
uses backends. It expects a location to be passed where it can find the
backend and templates. We could change this, but as it currently stands
today, that is the problem, at least as I see it, could be wrong.