Skip to content

Latest commit

 

History

History
130 lines (84 loc) · 4.02 KB

HACKING.adoc

File metadata and controls

130 lines (84 loc) · 4.02 KB

HACKING asciidoctor-reveal.js

Short instructions that aim to help potential contributors.

Table of Contents

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

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.