Slide deck creation ideas

[LightGuardjp]

There are many reasons to create a slide deck, however, most of the reasons come
down to the idea of visually sharing information with people.  Creating slide
decks can be a very time consuming process fraught with alignment issues, image
searching, and wrestling with tools. Using AsciiDoc and Asciidoctor can make
this a much easier and more pleasant experience, which should also take less
time than doing things with more traditional tools.

== Background

Traditional tools in this realm include:

* PowerPoint
* Keynote
* Impress

These tools all have the ability to create amazing presentations and organize
information in a useful way for the presenter. However, they also have a
tendency to get in the way and make slide deck creation more difficult. Without
a clear idea, outline, or process one can spend many hours, if not days
creating their perfect deck. Then of course there's the issues that creep
up the day of presentation, for example projector resolution. A deck was
created expecting wide screen support, but the projectors actually only support
1024x768.

There's one other problem: sharing a presentation, either with colleagues or
others online by posting a slide deck on a service, which typically requires
exporting a presentation as a PDF. This of course looses any interactive or
multimedia elements embedded within the presentation and can break the rhythm
or surprise of a slide.

A few years ago another idea came to the stage: HTML5 presentation frameworks!
These solve some of the issues of the previously mentioned tools, yet have some
of their own drawbacks. Alignment and consistency are much easier to wrangle
using an HTML5 presentation framework, sharing a presentation is as easy as
publishing the presentation online to allow others to view it in their own
browser, they're also done using familiar technologies (for developers).
However, things can become difficult if a PDF is needed, and there still isn't
an easy way to reuse a slide deck done this way.

I think we can do better, and some of us have been experimenting in this field!

== Where we are today

The key to doing this better comes back to a core concept of AsciiDoc: write in
plain text and generate something from the text. Because all you have to worry
about is plain text and the semantics of the content (emphasis, admonitions,
quotes, code listings, etc.) there's less to encumber you as you craft your
slide deck!

Asciidoctor today supports the following HTML5 presentation frameworks by using
the <a href="https://github.com/asciidoctor/asciidoctor-backends[asciidoctor-backends]">https://github.com/asciidoctor/asciidoctor-backends[asciidoctor-backends]
project:

* <a href="http://imakewebthings.com/deck.js/[deck.js]">http://imakewebthings.com/deck.js/[deck.js]
* <a href="http://lab.hakim.se/reveal-js/[reveal.js]">http://lab.hakim.se/reveal-js/[reveal.js]
* <a href="http://paulrouget.com/dzslides/[DZSlides]">http://paulrouget.com/dzslides/[DZSlides]

These all work great, but there are a few problems with them:

. No consistency between slide sources
. No core elements or components
. Can be difficult to setup
. Slides must live in their own document

While I've been thinking about crafting decks through AsciiDoc, and also
creating some decks, I've come to believe we need fix some of those problems,
and also be able to create a deck from materials that can then be reused for
other purposes. How great would it be to be able to take your presentation and
create a blog post out of it? Or section things out so slides can be reused and
distributed easier? How about creating PDFs and/or ePub documents from the same
source material? What if all of that could be done from a single file?

== Idea

The crux of this idea rests on an Asciidoctor extension and understanding
of what the author is trying to do with a slide. There's no reason slides
cannot be embedded within the document, they don't need to live separately in
their own file. Taking a presentation from the idea stage to outline to slides
to blog or print can all be done within the same file! The ideas can build upon
one another and the whole deck could be created from a single source file. Best
of all, if a different presentation solution is needed that could be generated
just as easily. Using deck.js today, but want to try DZSlides later? How about
Impress (this isn't done, but it could be possible)? I shouldn't have to rework
my entire source file just because I switched presentation frameworks or tools.

This will require aligning slide backends and templates, and an understanding
of what a slide is supposed to be and display. We have a start on some
component ideas at https://gist.github.com/LightGuard/0ad1c064d3e882f2294a. We
need some more input from others though.

== Example

Below is a working idea about what this may look like.

[source, asciidoc]
----
= Creating slides with Asciidoctor
Jason Porter <[hidden email]>
2014-07-04

Creating slides with Asciidoctor is a breeze! All you need is a text editor,
we'll supply the rest!

== What is Asciidoctor

Asciidoctor is an AsciiDoc tool chain...

[slide role="topic"]
.Asciidoctor, a writer's best friend
--
--

[slide]
--
It's just *text*mate!
--

=== What does it look like?

AsciiDoc syntax is really simple, everything is just text!

[slide, role="source"]
--
[source, asciidoc]
.Basic syntax
---
[#goals]
* Goal 1
* Goal 2

[NOTE]
====
Make sure to talk about how similar AsciiDoc is to markdown.
====
---
--

=== What can I do with it?

Asciidoctor comes with a set of export targets, and a wide range of templates.

[slide, role="list,scatter"]
--
* DocBook 4.5 and 5
* HTML 5
* XHTML
* PDF
* ePub
* mobi
* many more
--
----

We can then build an extension which will crawl the tree, pull out and slide
blocks and render them to the chosen slide framework! All of the support text
can stay where it is, providing information to readers that come to your blog,
colleagues, or even attendees following along with the generated PDF! I'm quite
excited about this and hope you'll join in helping create and maximize this idea!!

--

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

[mojavelinux]

Great state of the union and call to action, Jason!

I agree we should always be moving towards simpler, more portable content. I recognize two themes in your post on this topic:

* switching between presentation frameworks (i.e., changing the converter / backend used)

* reusing content from manuscripts for slides and vice versa

I'd like to emphasize another point, which you also raised in an earlier post about slide creation from AsciiDoc source using Asciidoctor. When creating content for slides, we should be thinking in terms of components (or patterns). By that, I mean that we should not be trying to layout or style the slide content explicitly. Instead, we should look for patterns in the appearance we are trying to achieve and derive names for those patterns. We replace the explicit formatting with roles and other metadata on the section and its content that comprises the slide.

Jason gave a good example in the slide with the bulleted list (which I've slightly revised):

```asciidoc

== AsciiDoc Converters

[.step.scatter]
* DocBook 4.5 / 5
* (X)HTML 5
* PDF
* EPUB3 / KF8
* man pages

* and more!

```

(I do like the idea of using an open block named "slide" for slides without a title, though I do think sections should be the preferred slide delimiter).

Jason has started this list of patterns in his gist, but we should go deeper. When you have the urge to align text to the left, add a background image to a slide or make a big title in the center of the page, you should think about what pattern that is and let the theme handle the presentation. Essentially, we're applying the principles of CSS and semantic HTML to slide creation.

We also want to generally make the AsciiDoc content as simple and clear as possible. The content and metadata should describe what is displayed on the slide, now how. In the end, this saves you a tremendous amount of time, and eliminates distractions, when creating presentations.

One of the first steps we can take towards a simpler, more portable format for slides composed in AsciiDoc is to play with existing presentations. The goal is to distill the content so there's nothing left to take away.

The sculptor, Michelangelo, was once asked how it was that he could create such beautiful works. "It's very simple," he answered. "When I look at a block of marble, I see the sculpture inside it. All I have to do is remove what doesn't belong."

-Dan

On Fri, Jul 4, 2014 at 3:49 PM, LightGuardjp [via Asciidoctor :: Discussion] <[hidden email]> wrote:

There are many reasons to create a slide deck, however, most of the reasons come
down to the idea of visually sharing information with people.  Creating slide
decks can be a very time consuming process fraught with alignment issues, image
searching, and wrestling with tools. Using AsciiDoc and Asciidoctor can make
this a much easier and more pleasant experience, which should also take less
time than doing things with more traditional tools.

== Background

Traditional tools in this realm include:

* PowerPoint
* Keynote
* Impress

These tools all have the ability to create amazing presentations and organize
information in a useful way for the presenter. However, they also have a
tendency to get in the way and make slide deck creation more difficult. Without
a clear idea, outline, or process one can spend many hours, if not days
creating their perfect deck. Then of course there's the issues that creep
up the day of presentation, for example projector resolution. A deck was
created expecting wide screen support, but the projectors actually only support
1024x768.

There's one other problem: sharing a presentation, either with colleagues or
others online by posting a slide deck on a service, which typically requires
exporting a presentation as a PDF. This of course looses any interactive or
multimedia elements embedded within the presentation and can break the rhythm
or surprise of a slide.

A few years ago another idea came to the stage: HTML5 presentation frameworks!
These solve some of the issues of the previously mentioned tools, yet have some
of their own drawbacks. Alignment and consistency are much easier to wrangle
using an HTML5 presentation framework, sharing a presentation is as easy as
publishing the presentation online to allow others to view it in their own
browser, they're also done using familiar technologies (for developers).
However, things can become difficult if a PDF is needed, and there still isn't
an easy way to reuse a slide deck done this way.

I think we can do better, and some of us have been experimenting in this field!

== Where we are today

The key to doing this better comes back to a core concept of AsciiDoc: write in
plain text and generate something from the text. Because all you have to worry
about is plain text and the semantics of the content (emphasis, admonitions,
quotes, code listings, etc.) there's less to encumber you as you craft your
slide deck!

Asciidoctor today supports the following HTML5 presentation frameworks by using
the <a href="https://github.com/asciidoctor/asciidoctor-backends[asciidoctor-backends]">https://github.com/asciidoctor/asciidoctor-backends[asciidoctor-backends]
project:

* <a href="http://imakewebthings.com/deck.js/[deck.js]">http://imakewebthings.com/deck.js/[deck.js]
* <a href="http://lab.hakim.se/reveal-js/[reveal.js]">http://lab.hakim.se/reveal-js/[reveal.js]
* <a href="http://paulrouget.com/dzslides/[DZSlides]">http://paulrouget.com/dzslides/[DZSlides]

These all work great, but there are a few problems with them:

. No consistency between slide sources
. No core elements or components
. Can be difficult to setup
. Slides must live in their own document

While I've been thinking about crafting decks through AsciiDoc, and also
creating some decks, I've come to believe we need fix some of those problems,
and also be able to create a deck from materials that can then be reused for
other purposes. How great would it be to be able to take your presentation and
create a blog post out of it? Or section things out so slides can be reused and
distributed easier? How about creating PDFs and/or ePub documents from the same
source material? What if all of that could be done from a single file?

== Idea

The crux of this idea rests on an Asciidoctor extension and understanding
of what the author is trying to do with a slide. There's no reason slides
cannot be embedded within the document, they don't need to live separately in
their own file. Taking a presentation from the idea stage to outline to slides
to blog or print can all be done within the same file! The ideas can build upon
one another and the whole deck could be created from a single source file. Best
of all, if a different presentation solution is needed that could be generated
just as easily. Using deck.js today, but want to try DZSlides later? How about
Impress (this isn't done, but it could be possible)? I shouldn't have to rework
my entire source file just because I switched presentation frameworks or tools.

This will require aligning slide backends and templates, and an understanding
of what a slide is supposed to be and display. We have a start on some
component ideas at https://gist.github.com/LightGuard/0ad1c064d3e882f2294a. We
need some more input from others though.

== Example

Below is a working idea about what this may look like.

[source, asciidoc]
----
= Creating slides with Asciidoctor
Jason Porter <[hidden email]>
2014-07-04

Creating slides with Asciidoctor is a breeze! All you need is a text editor,
we'll supply the rest!

== What is Asciidoctor

Asciidoctor is an AsciiDoc tool chain...

[slide role="topic"]
.Asciidoctor, a writer's best friend
--
--

[slide]
--
It's just *text*mate!
--

=== What does it look like?

AsciiDoc syntax is really simple, everything is just text!

[slide, role="source"]
--
[source, asciidoc]
.Basic syntax
---
[#goals]
* Goal 1
* Goal 2

[NOTE]
====
Make sure to talk about how similar AsciiDoc is to markdown.
====
---
--

=== What can I do with it?

Asciidoctor comes with a set of export targets, and a wide range of templates.

[slide, role="list,scatter"]
--
* DocBook 4.5 and 5
* HTML 5
* XHTML
* PDF
* ePub
* mobi
* many more
--
----

We can then build an extension which will crawl the tree, pull out and slide
blocks and render them to the chosen slide framework! All of the support text
can stay where it is, providing information to readers that come to your blog,
colleagues, or even attendees following along with the generated PDF! I'm quite
excited about this and hope you'll join in helping create and maximize this idea!!

--

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

---

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

http://discuss.asciidoctor.org/Slide-deck-creation-ideas-tp1901.html

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

... [show rest of quote]

--

Dan Allen | http://google.com/profiles/dan.j.allen

[LightGuardjp]

On Saturday, July 5, 2014, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Great state of the union and call to action, Jason!

I agree we should always be moving towards simpler, more portable content. I recognize two themes in your post on this topic:

* switching between presentation frameworks (i.e., changing the converter / backend used)

* reusing content from manuscripts for slides and vice versa

Glad I made those two points clear :) ease of use is also something I wanted to state, but you have done wonderfully below. 

 

I'd like to emphasize another point, which you also raised in an earlier post about slide creation from AsciiDoc source using Asciidoctor. When creating content for slides, we should be thinking in terms of components (or patterns). By that, I mean that we should not be trying to layout or style the slide content explicitly. Instead, we should look for patterns in the appearance we are trying to achieve and derive names for those patterns. We replace the explicit formatting with roles and other metadata on the section and its content that comprises the slide.

Jason gave a good example in the slide with the bulleted list (which I've slightly revised):

```asciidoc

== AsciiDoc Converters

[.step.scatter]
* DocBook 4.5 / 5
* (X)HTML 5
* PDF
* EPUB3 / KF8
* man pages

* and more!

```

(I do like the idea of using an open block named "slide" for slides without a title, though I do think sections should be the preferred slide delimiter).

... [show rest of quote]

Allowing both would be a great way to create topic slides (a slide with a title) and then the supporting slides (typically without a title. I would think if you need a title on the slide you have moved on to a new subject or subtopic.

 

Jason has started this list of patterns in his gist, but we should go deeper. When you have the urge to align text to the left, add a background image to a slide or make a big title in the center of the page, you should think about what pattern that is and let the theme handle the presentation. Essentially, we're applying the principles of CSS and semantic HTML to slide creation.

Please feel free to add comments to the gist or fork. I have a lot of lower level components, but we need the higher level ideas as well. I think once we have those, or at least a hand full of them we can actually start crafting a tool around this!

 

We also want to generally make the AsciiDoc content as simple and clear as possible. The content and metadata should describe what is displayed on the slide, now how. In the end, this saves you a tremendous amount of time, and eliminates distractions, when creating presentations.

I agree, however, there may be some where this simply isn't doable. Your example of a step/incremental scatter list is one of these I think. Technically they could all be on their own slide, but that creates more noise and makes things difficult when creating the deck.

If you run into something like this when creating components or visions ask yourself what it is you're trying to do at a high level. Give it as descriptive, yet easy a name as possible. If it isn't clear to another person what that component does simply by the name, we'll need to find something better. 

 

One of the first steps we can take towards a simpler, more portable format for slides composed in AsciiDoc is to play with existing presentations. The goal is to distill the content so there's nothing left to take away.

The sculptor, Michelangelo, was once asked how it was that he could create such beautiful works. "It's very simple," he answered. "When I look at a block of marble, I see the sculpture inside it. All I have to do is remove what doesn't belong."

-Dan

[snip]

--

Dan Allen | http://google.com/profiles/dan.j.allen

---

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

http://discuss.asciidoctor.org/Slide-deck-creation-ideas-tp1901p1904.html

To start a new topic under Asciidoctor :: Discussion, email <a href="javascript:_e(%7B%7D,&#39;cvml&#39;,&#39;[e-mail]&#39;);" target="_blank">ml-node+s49171n1h37@...
To unsubscribe from Asciidoctor :: Discussion, click here.
NAML

... [show rest of quote]

--

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

[LightGuardjp]

Anyone that may be interested in where this goes, or to add to the conversation, I have created a Github repo for conversation: https://github.com/LightGuard/asciidoc_slides_conversation

On Sat, Jul 5, 2014 at 3:59 PM, Jason Porter <[hidden email]> wrote:

On Saturday, July 5, 2014, mojavelinux [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Great state of the union and call to action, Jason!

I agree we should always be moving towards simpler, more portable content. I recognize two themes in your post on this topic:

* switching between presentation frameworks (i.e., changing the converter / backend used)

* reusing content from manuscripts for slides and vice versa

Glad I made those two points clear :) ease of use is also something I wanted to state, but you have done wonderfully below. 

 

I'd like to emphasize another point, which you also raised in an earlier post about slide creation from AsciiDoc source using Asciidoctor. When creating content for slides, we should be thinking in terms of components (or patterns). By that, I mean that we should not be trying to layout or style the slide content explicitly. Instead, we should look for patterns in the appearance we are trying to achieve and derive names for those patterns. We replace the explicit formatting with roles and other metadata on the section and its content that comprises the slide.

Jason gave a good example in the slide with the bulleted list (which I've slightly revised):

```asciidoc

== AsciiDoc Converters

[.step.scatter]
* DocBook 4.5 / 5
* (X)HTML 5
* PDF
* EPUB3 / KF8
* man pages

* and more!

```

(I do like the idea of using an open block named "slide" for slides without a title, though I do think sections should be the preferred slide delimiter).

... [show rest of quote]

Allowing both would be a great way to create topic slides (a slide with a title) and then the supporting slides (typically without a title. I would think if you need a title on the slide you have moved on to a new subject or subtopic.

 

Jason has started this list of patterns in his gist, but we should go deeper. When you have the urge to align text to the left, add a background image to a slide or make a big title in the center of the page, you should think about what pattern that is and let the theme handle the presentation. Essentially, we're applying the principles of CSS and semantic HTML to slide creation.

Please feel free to add comments to the gist or fork. I have a lot of lower level components, but we need the higher level ideas as well. I think once we have those, or at least a hand full of them we can actually start crafting a tool around this!

 

We also want to generally make the AsciiDoc content as simple and clear as possible. The content and metadata should describe what is displayed on the slide, now how. In the end, this saves you a tremendous amount of time, and eliminates distractions, when creating presentations.

I agree, however, there may be some where this simply isn't doable. Your example of a step/incremental scatter list is one of these I think. Technically they could all be on their own slide, but that creates more noise and makes things difficult when creating the deck.

If you run into something like this when creating components or visions ask yourself what it is you're trying to do at a high level. Give it as descriptive, yet easy a name as possible. If it isn't clear to another person what that component does simply by the name, we'll need to find something better. 

 

One of the first steps we can take towards a simpler, more portable format for slides composed in AsciiDoc is to play with existing presentations. The goal is to distill the content so there's nothing left to take away.

The sculptor, Michelangelo, was once asked how it was that he could create such beautiful works. "It's very simple," he answered. "When I look at a block of marble, I see the sculpture inside it. All I have to do is remove what doesn't belong."

-Dan

[snip]

--

Dan Allen | http://google.com/profiles/dan.j.allen

---

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

http://discuss.asciidoctor.org/Slide-deck-creation-ideas-tp1901p1904.html

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

... [show rest of quote]

--

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

... [show rest of quote]

--

[Joao]

Hello everyone,

is there any progress to the ideas on this thread? I am currently experimenting with slides creation, out of one single source for both text document (a textbook) and slides.

My intention is to avoid having to maintain two sets of asciidoc source files: one for the textbook chapters and other for the corresponding slides.

So far I am simply adding delimiters as asciidoc comments (//slide //endslide) to the asciidoc source files. For generating the slides, I simply use a script to parse my asciidoc source files, preserve only section titles (which must be flattened out) and text between my slide-delimiters and generate a temporary set of asciidoc sources for the slides.

Are there any better ideas or options to achieve this? I was also checking the ideas provided at https://github.com/LightGuard/asciidoc_slides_conversation/issues and https://github.com/opendevise/neo4j-slide-types/blob/master/docs/slide-types.adoc but it seems that the original idea -- keep only one asciidoc source for both text and slides -- seems to be forgotten.

Actually those were originally stated as:

****
. No consistency between slide sources
. Slides must live in their own document
****

Many thanks in advance for the help and any suggestions.

Kind regards

Joao

[mojavelinux]

Joao,

It seems like what you are looking for is the conditional preprocessor directive.

ifdef::slides[]

slide content

endif::[]

These lines will be excluded when the slides attribute is not set. You can also use the reverse logic for normal content using ifndef.

See https://asciidoctor.org/docs/user-manual/#conditional-preprocessor-directives

Cheers,

-Dan

On Thu, May 17, 2018 at 1:09 AM, Joao [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hello everyone,

is there any progress to the ideas on this thread? I am currently experimenting with slides creation, out of one single source for both text document (a textbook) and slides.

My intention is to avoid having to maintain two sets of asciidoc source files: one for the textbook chapters and other for the corresponding slides.

So far I am simply adding delimiters as asciidoc comments (//slide //endslide) to the asciidoc source files. For generating the slides, I simply use a script to parse my asciidoc source files, preserve only section titles (which must be flattened out) and text between my slide-delimiters and generate a temporary set of asciidoc sources for the slides.

Are there any better ideas or options to achieve this? I was also checking the ideas provided at https://github.com/LightGuard/asciidoc_slides_conversation/issues and https://github.com/opendevise/neo4j-slide-types/blob/master/docs/slide-types.adoc but it seems that the original idea -- keep only one asciidoc source for both text and slides -- seems to be forgotten.

Actually those were originally stated as:

****
. No consistency between slide sources
. Slides must live in their own document
****

Many thanks in advance for the help and any suggestions.

Kind regards

Joao

---

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

http://discuss.asciidoctor.org/Slide-deck-creation-ideas-tp1901p6333.html

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

... [show rest of quote]

--

[Joao]

Hi Dan,

I was not really aware of this feature, many thanks for this idea.

kind regards
Joao

[mojavelinux]

You're welcome! If you have other questions, don't hesitate to ask.

Cheers,

-Dan

On Thu, May 17, 2018 at 2:18 AM, Joao [via Asciidoctor :: Discussion] <[hidden email]> wrote:

Hi Dan,

I was not really aware of this feature, many thanks for this idea.

kind regards
Joao

---

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

http://discuss.asciidoctor.org/Slide-deck-creation-ideas-tp1901p6335.html

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

--