Comments (15)
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.
from asciidoctor-backends.
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.
- 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.
- haml refers to the reveal.js resources with the path
reveal.js/
but slim usesrevealjs/
I would like to consolidate the two in my pull request. Personally, I would go forreveal.js/
simply because agit 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.
from asciidoctor-backends.
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.
from asciidoctor-backends.
@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
from asciidoctor-backends.
Btw, welcome and thanks for your help!
from asciidoctor-backends.
Thanks @mojavelinux for the quick answer.
Can you also address my question 2 in my first comment please.
from asciidoctor-backends.
Rename the folder to reveal.js
. It shouldn't have been named revealjs
for the reason you cited.
from asciidoctor-backends.
It is improved in #53 and #54.
from asciidoctor-backends.
Fantastic! Thanks so much for giving the reveal.js backend the love it needed, @obilodeau!
from asciidoctor-backends.
Once #56 is merged I think we will be alright to close this. @sobkowiak anything else you think should be covered?
from asciidoctor-backends.
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!
from asciidoctor-backends.
Excellent. I thing it's enough. Thanks for the description.
from asciidoctor-backends.
Excellent! If you need any additional information, don't hesitate to create a new issue to address it. We want to constantly improve!
from asciidoctor-backends.
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 ;)
from asciidoctor-backends.
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!
from asciidoctor-backends.
Related Issues (20)
- Invoking latex converter from elsewhere HOT 4
- Align chart extension with AsciiDoc conventions HOT 3
- Graduate the LaTeX backend to its own repository HOT 16
- README - populate "General Usage Instructions"
- Support for deckjs being in a different relative location HOT 2
- Include attribute to add third party javascript HOT 3
- No tags for the different releases HOT 2
- Support [%step] for source code HOT 2
- Only treat level-1 headings as sections in deck.js backend HOT 2
- Trim the ERB backend down to a handful of examples HOT 2
- Admonitions (TIP, NOTE...) are rendered in deck.js only as text, and without space HOT 1
- Is it there a backend that outputs to pure text? HOT 5
- Support new SVG embedding options HOT 1
- Should we deprecate this repository ? HOT 12
- if IE tag in Meta does not work since ie10 HOT 2
- DEFAULT_TOCLEVELS seems to be gone in recent Asciidoctor implementations HOT 1
- Problem: reveal.js backend wont generate Title slide HOT 6
- Problem: reveal.js backend wont apply themes from atttribute revealjs_theme HOT 4
- New backend for Remark HOT 4
- Enable Travis in this repo HOT 3
Recommend Projects
-
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
-
Vue.js
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
-
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
-
TensorFlow
An Open Source Machine Learning Framework for Everyone
-
Django
The Web framework for perfectionists with deadlines.
-
Laravel
A PHP framework for web artisans
-
D3
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
-
Recommend Topics
-
javascript
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
-
web
Some thing interesting about web. New door for the world.
-
server
A server is a program made to process requests and deliver data to clients.
-
Machine learning
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
-
Visualization
Some thing interesting about visualization, use data art
-
Game
Some thing interesting about game, make everyone happy.
Recommend Org
-
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
-
Microsoft
Open source projects and samples from Microsoft.
-
Google
Google ❤️ Open Source for everyone.
-
Alibaba
Alibaba Open Source for everyone
-
D3
Data-Driven Documents codes.
-
Tencent
China tencent open source team.
from asciidoctor-backends.