Write a short README for reveal.js backend about asciidoctor-backends

[mojavelinux]

I agree. Even better would be to have a tutorial page similar to what we have for deck.js.

http://asciidoctor.org/docs/install-and-use-deckjs-backend/

If someone is interested in writing one, you can start with the source of the deck.js tutorial.

https://raw.githubusercontent.com/asciidoctor/asciidoctor.org/master/docs/install-and-use-deckjs-backend.adoc

[obilodeau]

I've written a very short README (mostly only install and render instructions) for the reveal.js backend but I have two questions before I offer my pull request.

1. Should I use the haml or the slim backend in the example. slim is more recent and has more files but I don't know feature-wise if it should be the default. But it looks like it should be the one.
2. haml refers to the reveal.js resources with the path reveal.js/ but slim uses revealjs/ I would like to consolidate the two in my pull request. Personally, I would go for reveal.js/ simply because a git clone will give you that directory name. Since there was no documentation I think this is an acceptable breaking change for the few users of this backend.

[obilodeau]

By the way is there any documentation on creating back-ends? I will likely improve the reveal.js back-end while I work on my stuff but I want to make sure I follow the best-practices. I'll definitely look at the haml/deckjs back-end which look like the more feature rich.

[mojavelinux]

@obilodeau We should move forward with slim and eventually remove the haml backend. I prefer slim over haml because it's (a) more concise, (b) faster and (c) more current (though that fluctuates).

I haven't had a chance to write documentation for creating backends (#7), but it has been on my list. The best documentation we have so far is the following thread: #12 (comment). Beware it might be a bit out of date. To see how the templates are called, refer to the following class: https://github.com/asciidoctor/asciidoctor/blob/master/lib/asciidoctor/converter/template.rb

[mojavelinux]

Btw, welcome and thanks for your help!

[obilodeau]

Thanks @mojavelinux for the quick answer.

Can you also address my question 2 in my first comment please.

[mojavelinux]

Rename the folder to reveal.js. It shouldn't have been named revealjs for the reason you cited.

[obilodeau]

It is improved in #53 and #54.

[mojavelinux]

Fantastic! Thanks so much for giving the reveal.js backend the love it needed, @obilodeau!

[obilodeau]

Once #56 is merged I think we will be alright to close this. @sobkowiak anything else you think should be covered?

[mojavelinux]

This looks great.

I do have one request, though. (Keep in mind this request isn't documented, so you didn't miss anything). In the Asciidoctor project, we like to write the AsciiDoc content using the sentence-per-line convention instead of wrapping text at a fixed column.

For instance, take the following snippet from the README:

Slide Four has bullets that are revealed one after the other. This is what
`reveal.js` calls http://lab.hakim.se/reveal-js/#/fragments[fragments].
Applying the step option or role on a list (`[%step]` or `[.step]`) will do
the trick. Here is https://github.com/hakimel/reveal.js#fragments[upstream
documentation] on the topic. Note that only `fade-in` is supported for lists
at the moment.

We prefer to write this as:

Applying the step option or role on a list (`[%step]` or `[.step]`) will do the trick.
Here is https://github.com/hakimel/reveal.js#fragments[upstream documentation] on the topic.
Note that only `fade-in` is supported for lists at the moment.

This allows us to treat lines of documentation like we treat lines of code.

If you're able to make this change, let me know. If you don't have time, I can pick it up. I just don't want to step over you. Cheers!

[sobkowiak]

Excellent. I thing it's enough. Thanks for the description.

[mojavelinux]

Excellent! If you need any additional information, don't hesitate to create a new issue to address it. We want to constantly improve!

[obilodeau]

I've been going back and forth with the one-sentence per line approach since I've been doing asciidoc (4 years now). Since I've found about git diff --word-diff I prefer using fixed width now. It looks more pretty in plaintext (which means most of the time for me) and it's easier to maintain (the vim bindings are burned in my brain now).

This allows us to treat lines of documentation like we treat lines of code.

I wrap my code at 80 chars (following Python's PEP8). It is a pain in the ass but when you are 3-way merging you are able to have all that code fit on a 22" monitor.

Religious fighting aside I'm going to comply with your request and do one sentence per line as you requested. I guess it means that I'm not that into religion ;)

[mojavelinux]

Since I've found about git diff --word-diff I prefer using fixed width now.

That's definitely a handy command. I'm glad I finally discovered it too, because diffs sucked before I knew about it :)

The main focus of sentence per line isn't so much the look of the diff, but avoiding busy work of formatting. While some developers have this setup automatically, others do not or the line length setting is different. What ends up happening is people spend a lot of time fiddling with something that's completely meaningless in the end anyway. By doing sentence per line, the focus of the change is localized to the sentence that needs changing.

As a bonus, you can reorder sentences just by pushing them up or down a line. I find a lot of editing involved reordering sentences, so this saves a ton of time. In fact, I almost think this is why I like the approach the most.

Religious fighting aside I'm going to comply with your request and do one sentence per line as you requested. I guess it means that I'm not that into religion ;)

Hahaha. Thanks!