= HACKING asciidoctor-reveal.js
:toc: preamble
:toclevels: 2

Short instructions that aim to help potential contributors.

== Inspect the template system


To understand what you have access to in templates you can inject some ruby.
With the slim templating system, this is done by prepending the lines with a dash (`-`) and inserting a ruby statement.
Two complementary approaches can be used to explore the context offered by asciidoctor through the template system:

* logging on the command line via print-like statements
* jump into the context through an interactive debugger

=== Print debugging information

For example to see which attributes are available, you can print them by adding these lines in the `.slim` file of interest:

----
- puts @document.attributes.inspect
- puts @attributes.inspect
- puts @document.methods
----

Other generally useful ruby specific introspection:

----
- puts instance_variables
- puts local_variables
----

One might find `pp` to produce better output (and in some cases not):

----
- require 'pp'
- pp @document.attributes
----

=== Interactively debug a template

Pry is a powerful debugger for ruby that features tab-completion.
It is very useful to discover a complex object hierarchy like what asciidoctor offers.

==== Initial Setup

    gem install pry

==== Usage

In order to be dropped into the debugger at a specific point in a template simply add the following two lines in the relevant `.slim` template file:

----
- require 'pry'
- binding.pry
----

Then run asciidoctor from the command-line to generate your document and you'll be dropped in the debugger:

----
$ make
asciidoctor -T templates/slim -b revealjs test/level-sections.adoc
asciidoctor: WARNING: level-sections.adoc: line 29: section title out of sequence: expected level 2, got level 3

From: /home/olivier/src/asciidoc/asciidoctor-reveal.js/templates/slim/section.html.slim @ line 3 :

    1: - hide_title = (title = self.title) == '!'
    2: - require 'pry'
 => 3: - binding.pry
    4: / parent section of vertical slides set
    5: - if @level == 1 && !(subsections = sections).empty?
    6:   section
    7:     section id=(hide_title ? nil : @id) data-transition=(attr 'data-transition') data-transition-speed=(attr 'data-transition-speed') data-background=(attr 'data-background') data-background-size=(attr 'data-background-size') data-background-repeat=(attr 'data-background-repeat') data-background-transition=(attr 'data-background-transition')
    8:       - unless hide_title

[1] pry(#<Asciidoctor::Section>)>
----

Then using commands like the following allows you to explore interactively asciidoctor's API and object model with syntax highlighting:

    [1] pry(#<Asciidoctor::Section>)> @document

You can also query asciidoctor's documentation:

    [4] pry(#<Asciidoctor::Section>)> ? find_by

=== References

* https://github.com/asciidoctor/asciidoctor.org/issues/80#issuecomment-145698579
* http://pryrepl.org/
* http://discuss.asciidoctor.org/Interactively-debugging-a-template-with-a-REPL-td4498.html

== Tests

In order to help troubleshoot issues and test syntax improvements, some minimalist asciidoc test files are provided.
You can render the tests files and then load them in a browser and check if `asciidoctor-reveal.js` behaves as expected.

=== Initial Setup

    cd test/
    git clone https://github.com/hakimel/reveal.js.git

=== Render tests into .html

From the project's root directory:

    make

=== Open rendered files

You can open the generated `.html` in a Web browser.
For convenience the following command will open the last modified file:

    make open

Additionally, if you want to test with a minimalist web server:

    make serve

The server is running in the foreground and needs `Ctrl-C` to be killed.

== Jade templates

Jade templates are used by AsciidocFX. Since they are separate they might be
out of sync with our asciidoctor's slim templates.

To test the jade templates, install AsciidocFX and copy the jade templates
over to AsciidocFX's `conf/slide/templates/revealjs/` directory. Then use
AsciidocFX to render the slides.


== Attribute inheritence

The attr and attr? methods inherit by default. That means if they don't find the attribute defined on the node, they look on the document.

You only want to enable inheritance if you intend to allow an attribute of the same name to be controlled globally.
That might be good for configuring transitions. For instance:

----
= My Slides
:transition-speed: fast

== First Slide
----

However, there may be attributes that you don't want to inherit.
If that's the case, you generally use the form:

    attr('name', nil, false)

The second parameter value is the default attribute value, which is nil by default.

Relevant documentation: http://www.rubydoc.info/github/asciidoctor/asciidoctor/Asciidoctor%2FAbstractNode%3Aattr


== Merge / Review policy

Any non-trivial change should be integrated in master via a pull-request.
This gives the community a chance to participate and helps write better code because it encourages people to review their own patches.

Pull requests should come from personal forks in order not the clutter the upstream repository.

=== Wait time

Once a pull request is submitted, let it sit for 24-48 hours for small changes.
If you get positive feedback you can merge before the sitting time frame.
If you don't get feedback, just merge after the sitting time frame.

Larger changes should sit longer at around a week.
Positive feedback or no feedback should be handled like for small changes.

Breaking changes should sit until a prominent contributor comments on the changes.
Ping `@mojavelinux` and `@obilodeau` if necessary.

Remember that this is a slower moving project since people are not designing slides everyday.
Well, for most people.

=== Work-in-progress pull-requests

If you prepend "WIP" in front of your pull request we will understand that it is not complete and we will not merge it before you remove the WIP string.

This is useful to let people know that you are working on stuff.
Branches are not that visible otherwise but pull requests are.

You might even be able to get some feedback early which could save you some time.

=== 'needs review' label

You can apply that label to a pull request that is complete and ready for review.

Makes triaging easier.


== Node package

=== Test a local asciidoctor-reveal.js version

In order to test the Node package, you need to create a test project adjacent to the clone of the `asciidoctor-reveal.js` repository:

 $ mkdir test-project
 $ cd test-project
 $ npm init -y

Now, install the dependencies:

 $ npm i --save asciidoctor.js@1.5.5-3
 $ npm i --save ../asciidoctor-reveal.js

NOTE: The relative portion of the last command is where you are installing the local `asciidoctor-reveal.js` version from.

Then proceed as documented in the `README.adoc`.


== Release process

. Update the version in `lib/asciidoctor-revealjs/version.rb` and `package.json`
. Update the changelog
** Generate author list with:
+
    git log <commit>.. --format="%aN" --reverse | perl -e 'my %dedupe; while (<STDIN>) { print unless $dedupe{$_}++}' | sort

. Prepare release commit
** commit msg: Prepare %version% release
** release commit (--allow-empty) msg: Release %version%
. Tag the release commit
** Annotated Tag msg: Version %version%
. Push your changes (including the tag)
. Pushing the gem on rubygems.org:
+
 $ gem build asciidoctor-revealjs.gemspec
 $ gem push asciidoctor-revealjs-X.Y.Z.gem

. Check that the new version is available on https://rubygems.org/gems/asciidoctor-revealjs[rubygems.org]
. Build the node package (make sure you have `devDependencies` installed with: `npm install`):
+
 $ npm run build

. Publish the node package on npm:
+
 $ npm login
 $ npm publish

. Check that the new version is available on https://www.npmjs.com/package/asciidoctor-reveal.js[npmjs.com]
. Update version in `lib/asciidoctor-revealjs/version.rb` and `package.json` (+1 bugfix and append '-dev') and commit
** commit msg: Begin development on next release