v3 roadmap

[hsablonniere]

Hi everyone,

We're working on a new version of this generator and your help is welcomed. Yeah :tada::tada: !

You can see the proposed changes in the v3 branch.

Why?

The main goals of this v3 are :

• Update all the dependencies (latest version or alternative)
• Simplify the questions process (too many questions, lots of plugins should be default)
• Solve the current issues

  The roadmap

  PDF generation

The current PDF generation is done with davidmarkclements/bespoke-pdf and davidmarkclements/bespoke-to-pdf. It uses a NW.js app which itself uses an old Webkit engine :disappointed:.

We want authors to be able to use the latest CSS techniques if they want like flexbox and object-fit. In order to do so, we will remove the PDF option in the generator and push authors to use up-to-date projects like astefanutti/decktape.

We need to make sure that this kind of project stays compatible with this generator and the bespoke ecosystem in general.

Bespoke plugins as default

• [x] bespoke-bullets
  This plugin will be replaced with a new approach in the future (bespoke-builds).
• [x] bespoke-scale
  This plugin will be replaced with a new approach in the future (ask @mojavelinux).
• [x] bespoke-hash
• [x] bespoke-classes
• [x] bespoke-extern
  For now, this is required for PDF generation.

  Bespoke plugins as option

• [x] Add bespoke-multimedia as an option.

  Bespoke plugins to replace

• [x] Use bespoke-nav instead of bespoke-keys and bespoke-touch.
• [x] Replace bespoke-theme-cube with basic styles in the generated code.

  Bespoke plugins to remove

• [x] bespoke-pdf
  Explained in a previous section.
• [x] bespoke-backdrop
  Most slide deck don't really need this feature.
• [x] bespoke-progress
  Most of the time this feature is a distraction for the audience.
• [x] bespoke-forms
  Most slide deck don't really need this feature.

  Generator & build dependencies to update

A lot of the gulp/build dependencies need to be updated or removed.

• [x] Remove sindresorhus/opn, this behaviour feels very annoying.
• [x] We also need to update to the latest yeoman generator framework.
• [x] gulp-browserify seems deprecated. We will have to update to the new gulp+browserify way.
• [x] Remove bower and use prismjs from NPM.
• [x] prismjs support should be moved to a plugin.

  Templating options

For now, only Jade is supported :cry:.

• [x] Authors should be able to write plain HTML (see #35)
• [x] Authors should be able to write AsciiDoc with AsciiDoctor.
• [x] We need to update Jade to Pug since the project got renamed.
• [x] Use coderay (and rouge) enabled with AsciiDoc and don't ask for prism in those cases

  Tests

• [x] Test that generated files are OK
• [x] Test that gulp serve works OK
• [x] Test that gulp build works OK

[mojavelinux]

Great plan, @hsablonniere!

[mojavelinux]

I'll explain Hubert's comment about bespoke-scale. We are planning to replace this plugin with the soon to be created bespoke-max. The reason are two-fold:

1. We want a name that fits better for what the plugin does, which is to maximize the slides within the viewport
2. When using the scale transform method, we want to apply it to a container that wraps the whole deck instead of each individual slide so that we don't introduce a new statcking context per slide and break z-index (see https://tiffanybbrown.com/2015/09/css-stacking-contexts-wtf/index.html)
3. We may want to stop using zoom because it's a proprietary CSS property and causes a lot of inconsistency in font rendering between browsers (esp WebKit).

[mojavelinux]

gulp-browserify seems deprecated. We will have to update to the new gulp+browserify way.

For an example of how it's done now, see https://github.com/opendevise/presentation-bespoke-starter/blob/3ea129b1b96e769b3636dac8fbfc811263afa70a/gulpfile.js#L22-L33. There's a link to an article about this migration in a comment within that line range.

[mojavelinux]

Replace bespoke-theme-cube with basic styles in the generated code.

:+1: The generator should encourage best practices. Using a rotating cube is not a very accessible way to give a presentation. The audience focuses more on the cube effect than they do on the content. The default theme should be something that makes the content the focus of the presentation.

[markdalgleish]

@mojavelinux so true—I only ever used the cube styles when Bespoke.js itself was the presentation topic: http://markdalgleish.com/presentations/bespoke.js

[mojavelinux]

If we did have a default from the existing set, I'd say most people like the Nebula theme. But I think we can create one that's even more fundamental that will provide a good hackable starting point. I'd also like to use that theme for the demos across the various plugins (where applicable) so we have some consistency there. (For example: http://opendevise.github.io/bespoke-fullscreen/)

[mojavelinux]

I've reviewed the v3 branch. Overall, it looks really nice. A major step forward.

I sent a PR containing a handful of improvements. See #37.

Here are some additional items I'd like to see addressed when using AsciiDoc as the template language:

• Add a .ruby-version file containing the text default (this sets up RVM correctly when entering the project)
• Run bundle --path=.bundle/rubygems (and possibly gem install bundler if bundle isn't yet available) after npm install
  • If this command fails, issue a warning that the user must run this command to install asciidoctor-bespoke
• Use README.adoc (perhaps always?)

[hsablonniere]

@mojavelinux I'm almost done. I still miss the themes and I'm not sure what to do about that. I also did not updated the tests since I also don't really know what we're aiming for.

[mojavelinux]

Very good. I just don't think we should worry about the themes just yet. What's important is to lay down a good foundation project and keep that maintained. Most users are going to customize the styles anyway, which we encourage, so the focus is on creating a functional, hackable project.

[hsablonniere]

Hey @tiste, @mghignet, @NicolasGeraud, @antoinesd, Gillespie59 !! If you have some time to try this v3 and give a few feedbacks it would be awesome...

[hsablonniere]

@mojavelinux Should we use this.spawnCommand described here : http://yeoman.io/authoring/dependencies.html instead of simple execSync ?

[hsablonniere]

@mojavelinux Right now my "smoke" tests verify that :

• gulp serve has a "navigable" deck on http://localhost:8080
• gulp build generates the correct files in dist

Do we need more? Stuffs like :

• Plugins are plugged correctly
• Styles are generated (in dev mode)
• ...

[hsablonniere]

I had to migrate travis to a node v4. I was unable to properly spawn and kill processes (gulp and npm) with v0.10.x.

Build is now green ;-)

[mojavelinux]

Green bar!

[mojavelinux]

Where does the test application get created when I run npm test? I'm thinking perhaps we should have a section in the README that talks about the tests, how to run them, and what to expect. Also, we should mention that the tests required Node v4+.

[mojavelinux]

I think I know the answer. The sample project is generated into a random folder name inside the current user's temporary folder.

[mojavelinux]

One minor thing. When generating an AsciiDoc presentation, the final message says:

I'm all done. Running npm install for you to install the required dependencies. If this fails, try running the command yourself.

It doesn't mention that it's running the bundle command.

[mojavelinux]

We need to put somewhere that the following command should be run before running yo bespoke if you are generating an AsciiDoc-based presentation:

rvm use default

We can't do this in the generator because not everyone uses RVM. By doing this, it ensures the bundler gem gets installed in the correct place.

[mojavelinux]

The bullets plugin needs to be configured differently when creating an AsciiDoc-based presentation to align with how the Asciidoctor Bespoke converter works.

The configuration should look like this: https://github.com/opendevise/presentation-bespoke-starter/blob/asciidoc/src/scripts/main.js#L20

This also means changing the lists to:

[%build]
* one
* two
* three

More details can be found in the README for Asciidoctor Bespoke.

[mojavelinux]

The classes plugin should come first in the plugin list:

bespoke.from('article', [
  classes(),
  nav(),
  ...
]);

Almost all the plugins rely on the classes plugin, so it needs to be first to ensure the deck is initialized correctly.

[mojavelinux]

I think the extern plugin should always come last.

[mojavelinux]

To ensure we match the right element as the deck, and we don't include any children which are not slides, I think we should use the long-form version of the deck initializer:

bespoke.from({ parent: 'article.deck', slides: 'section' }, [
  ...
]

wdyt?

[strugee]

@mojavelinux specific to your last question, seems reasonable. In general I think it's better to err on the side of caution - the author can remove the "safety net" if it's really that ugly

More generally, I came here to suggest that v3 be put on npm since it seems like work on it has kinda stagnated - at a certain point it's better to just declare a project "ready" and push the remaining changes to the next major release. Slightly more frequent semver-major changes aren't the end of the world, and in the meantime, everyone will benefit from the work that's already been done.

[mojavelinux]

Yes, I agree we are ready to move forward. I discussed it with @hsablonniere and we had agreed, but the end of the year / beginning of the new year threw a wrench in forward progress. Make no mistake, we're using this daily / weekly, but we're cheating by using the v3 branch.

There are three things I'd like to see changed before release:

• [x] clean task should perform sync delete (otherwise, we get a race condition when combined with other tasks)
• [x] missing aside[role=note] { display: none; } in CSS (can't remember if that one got fixed...but is needed for speaker notes)
• [x] move base styles to a separate file so user has a blank file for creating styles (eventually, we want the base styles to come from a package)
• [x] copy custom fonts by default

If you think any of these can be deferred, don't hesitate to suggest. We'd certainly appreciate the help to move this forward.

The clean task is the most grave since this race condition can lead to the build output being deleted immediately after it is created.

[strugee]

@mojavelinux gotcha. I have v3 installed locally, too :)

Those changes make sense; I might take a crack at them if I have some time. That being said, WRT the clean task, I'm not 100% sure but I think it's possible to have Gulp pass you a callback to be called when you're done with whatever. That would let us avoid nasty sync IO.

[strugee]

copy custom fonts by default

What do you mean by this? You mean if the user adds custom fonts they should be picked up automatically?

move base styles to a separate file so user has a blank file for creating styles (eventually, we want the base styles to come from a package)

About to send a PR for this one.

[mojavelinux]

You mean if the user adds custom fonts they should be picked up automatically?

Correct. In the fonts directory adjacent to images. Just about any well-designed presentation is going to use a custom font. You could link to Google Fonts, but then the presentation depends on an internet connection, which never works prior to walking on stage.

[mojavelinux]

I'm not 100% sure but I think it's possible to have Gulp pass you a callback to be called when you're done with whatever. That would let us avoid nasty sync IO.

While that's true, it can't block subsequent tasks. The way the delete task is wired in, it's intended to be a sync operation...otherwise it doesn't make much sense.

Here's how I did it. Pretty straightforward:

  return del.sync('dist');

(same for other other delete operations).

Of course, I really question whether clean should be wired to every task anyway. That seems like a bad practice. Output files should only be cleaned if the user requests it (or we do it intelligently).

[mojavelinux]

To clarify, what it breaks is the following:

gulp clean build

[strugee]

Why does v3 generate a README.adoc instead of README.md? Markdown is far more widely used... it doesn't really make sense to me.

[mojavelinux]

Because we are fans of AsciiDoc.

[strugee]

Shouldn't the generator try to appeal to the widest range of users, though?

I wonder if we could make this a "hidden option" through environment variables or something. Or we could make the first question ask how many questions the user wants to be asked.

[mojavelinux]

I'm firm on this one. I believe AsciiDoc is a better choice for our users and I want to stick with it. It renders just as well on GitHub and thus serves the purpose just fine. If the user of the generator wants to change it afterwards, it's a very straightforward change.

[mojavelinux]

I don't mean to be so tough about it, but this is the direction I decided to take for this generator. I'd rather focus on discussions about improving the generator's capabilities.

[strugee]

OK. I disagree, but it's definitely your call. It's not a big deal for me to just maintain a private fork with this change (rebasing from time to time), anyway.

[mojavelinux]

AsciiDoc is far superior to Markdown and will eventually overtake it if I have anything to do with it. Markdown only enjoys a lead right now because AsciiDoc had no one advocating for it at the time. Users enjoy AsciiDoc far more. This is why I push for it so hard.

[mojavelinux]

Version 3.0.0 is now tagged. We are waiting on permissions to publish, but that should happen shortly after this comment is posted.