Quantcast

Asciidoctor backends

classic Classic list List threaded Threaded
7 messages Options
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Asciidoctor backends

asotobu
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.

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoctor backends

paulrayner
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.
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoctor backends

asotobu
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.

Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoctor backends

LightGuardjp
Administrator
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



--
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoctor backends

aalmiray
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?
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoctor backends

LightGuardjp
Administrator
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



--
Reply | Threaded
Open this post in threaded view
|  
Report Content as Inappropriate

Re: Asciidoctor backends

davide.cavestro
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.
Loading...