asciidoctor-revealjs 3.0.0.pre.rc1 → 4.1.0.rc2

data/HACKING.adoc

@@ -1,343 +0,0 @@
-= HACKING asciidoctor-reveal.js
-:toc: preamble
-:toclevels: 2
-
-Short instructions that aim to help potential contributors.
-
-== Getting Started
-
-* Setup the Asciidoctor-revealjs plugin in <<ruby-localversion,development mode>>
-* Modify the http://slim-lang.com/[slim templates] in `templates/`
-* Templates need to be compiled before being used, do so with:
-
-    bundle exec rake build
-
-* Then using the following command will render slides with your template changes baked in:
-
-    bundle exec asciidoctor-revealjs <source.adoc>
-
-The next section will provide further help on how to use `print` statements or a debugger to assist development.
-
-
-== 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
-
-[NOTE]
---
-Starting with v1.1.0 the slim templates are compiled to Ruby in order to
-use the same templates from Asciidoctor.js (Javascript / Node.js ecosystem).
-Don't forget to recompile the templates if you make changes to them.
-This can be done by running:
-
-    bundle exec rake build
---
-
-=== 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
-
-    bundle --path=.bundle/gems --binstubs=.bundle/.bin
-
-==== 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-revealjs` from the command-line to generate your document and you'll be dropped in the debugger:
-
-----
-$ bundle exec asciidoctor-revealjs examples/video.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
-
-If you install the `pry-byebug` gem you get additional debugging capabilities.
-See the gem's documentation for details.
-
-Since 1.1.0, templates are compiled. It is easier to inject the debug
-triggering statements and use the templates directly instead of debugging
-compiled templates. You can call the slim templates directly with:
-
-// TODO it's still not clear whether `-r slim-htag` is required right now (#153)
-
-    bundle exec asciidoctor --trace -T templates/ examples/customcss.adoc
-
-=== 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
-
-== Manual 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-revealjs` behaves as expected.
-
-=== Initial Setup
-
-Make sure to have a working version of `asciidoctor-reveals` this is usually
-done with `bundler`:
-
-    bundle config --local github.https true
-    bundle --path=.bundle/gems --binstubs=.bundle/.bin
-    bundle exec rake build
-
-Go to `test/doctest` folder and install `reveal.js`:
-
-    cd test/doctest/
-    git clone https://github.com/hakimel/reveal.js.git
-
-=== Render tests into .html
-
-From the project's root directory:
-
-    bundle exec rake doctest::generate FORCE=yes
-
-=== Open rendered files
-
-NOTE: Right now, https://github.com/asciidoctor/asciidoctor-doctest/issues/12[doctest issue #12] means that the generated examples will not be pretty.
-
-You can open the generated `.html` in `test/doctest/` in a Web browser.
-
-
-== Asciidoctor API's gotchas
-
-=== 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 first need to build the converter into Javascript and create a tarball of the project.
-
-  $ bundle exec rake build:js
-  $ npm pack
-
-That last command will produce a file named `asciidoctor-reveal.js-<version>.tgz` in the working directory.
-
-Then, create a test project adjacent to the clone of the [.path]_asciidoctor-reveal.js_ repository:
-
- $ mkdir test-project
- $ cd test-project
-
-Now, install the dependencies from the tarball:
-
- $ npm i --save ../asciidoctor-reveal.js/asciidoctor-reveal.js-<version>.tgz
-
-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`.
-
-=== Upgrade Asciidoctor.js version
-
-WARNING: It is important to track `Asciidoctor.js` and `opal` versions together.
-The `opal` used to compile our node package must match `asciidoctor.js`'s `opal` requirement.
-The former is specified in our `package.json` and the latter in the `asciidoctor-revealjs.gemspec`.
-When you update one remember to update the other.
-Versions known to work together can be found by looking at the Asciidoctor.js release notes, just replace <tag> with the `asciidoctor.js` release you are interested in: https://github.com/asciidoctor/asciidoctor.js/releases/tag/<tag>.
-
-== RubyGem package
-
-[[ruby-localversion]]
-=== Test a local asciidoctor-revealjs version
-
-Compile the converter:
-
-  $ bundle exec rake build
-
-In a clean directory besides the `asciidoctor-reveal.js` repository, create the following `Gemspec` file:
-
-  source 'https://rubygems.org'
-  gem 'asciidoctor-revealjs', :path => '../asciidoctor-reveal.js'
-
-Then run:
-
-  $ bundle --path=.bundle/gems --binstubs=.bundle/.bin
-
-
-== Release process
-
-. Update the version in `lib/asciidoctor-revealjs/version.rb` and `package.json`
-. Update the changelog
-** Generate author list with:
-+
-    git log <prev-version-tag>.. --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)
-. Make a release on github (from changelog and copy from previous releases)
-// TODO: reg needs fixin'
-** Useful vim regex for AsciiDoc to Markdown: `:%s/{uri-issue}\d\+\(\(\[#\d\+\)]\)/\1(https:\/\/github.com\/asciidoctor\/asciidoctor-reveal.js\/issues\/\2)/gc`
-. Pushing the gem on rubygems.org:
-+
- $ bundle exec rake build
- $ 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]
-. Generate the javascript version of the Ruby converter
-+
- $ bundle exec rake build:js
-
-. Test the node package (make sure you have `devDependencies` installed with: `npm install`):
-+
- $ npm run test
-
-. Publish the node package on npm:
-+
- $ npm login # only required if not already authenticated
- $ 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
-. Submit a PR upstream to sync the documentation on asciidoctor.org
-** Modify this page: https://github.com/asciidoctor/asciidoctor.org/edit/master/docs/asciidoctor-revealjs.adoc
-
-== Ruby and asciidoctor-doctest tests
-
-=== Running tests
-
-We recommend tests to be run with a fresh install of all dependencies in a local folder that won't affect your ruby install (a `.bundle/` in this directory):
-
-    bundle --path=.bundle/gems --binstubs=.bundle/.bin
-
-Then you can execute the tests with:
-
-    bundle exec rake doctest
-
-However, if you have all dependencies properly installed this command should run the tests successfully:
-
-    rake doctest
-
-=== Generating HTML test target
-
-Tests were bootstrapped by https://github.com/asciidoctor/asciidoctor-doctest/#generate-examples[generating them from asciidoctor-doctest's test corpus] and current asciidoctor-revealjs' slim template engine.
-This is done using the following command:
-
-    bundle exec rake doctest:generate FORCE=y
-
-=== Custom tests
-
-Files in the `examples/` directory are used as tests.
-Resulting slides are kept in `test/doctest/`.

data/examples/revealjs-features.adoc

@@ -1,23 +0,0 @@
-// .revealjs-features
-// This example tests some of Reveal.js 3.7.0 features
-// :include: //body/script | //div[@class="slides"]
-// :header_footer:
-= Reveal.JS
-:revealjs_history: true
-:revealjs_fragmentInURL: true
-
-== Slide One
-
-Some content
-
-=== And
-
-With Reveal.JS 3.6
-
-=== Fragments
-
-Can now be displayed in URLs
-
-== Second slide
-
-Done

data/templates/asciidoctor_revealjs.css.slim

@@ -1,59 +0,0 @@
-/! This CSS is generated by the Asciidoctor-Reveal.js converter to further integrate AsciiDoc's existing semantic with Reveal.js
-css:
-  .reveal div.right {
-    float: right;
-  }
-
-  .reveal .listingblock.stretch > .content {
-    height: 100%;
-  }
-
-  .reveal .listingblock.stretch > .content > pre {
-    height: 100%;
-  }
-
-  .reveal .listingblock.stretch > .content > pre > code {
-    height: 100%;
-    max-height: 100%;
-  }
-
-  /* tables */
-  table{border-collapse:collapse;border-spacing:0}
-  table{margin-bottom:1.25em;border:solid 1px #dedede}
-  table thead tr th,table thead tr td,table tfoot tr th,table tfoot tr td{padding:.5em .625em .625em;font-size:inherit;text-align:left}
-  table tr th,table tr td{padding:.5625em .625em;font-size:inherit}
-  table thead tr th,table tfoot tr th,table tbody tr td,table tr td,table tfoot tr td{display:table-cell;line-height:1.6}
-  td.tableblock>.content{margin-bottom:1.25em}
-  td.tableblock>.content>:last-child{margin-bottom:-1.25em}
-  table.tableblock,th.tableblock,td.tableblock{border:0 solid #dedede}
-  table.grid-all>thead>tr>.tableblock,table.grid-all>tbody>tr>.tableblock{border-width:0 1px 1px 0}
-  table.grid-all>tfoot>tr>.tableblock{border-width:1px 1px 0 0}
-  table.grid-cols>*>tr>.tableblock{border-width:0 1px 0 0}
-  table.grid-rows>thead>tr>.tableblock,table.grid-rows>tbody>tr>.tableblock{border-width:0 0 1px}
-  table.grid-rows>tfoot>tr>.tableblock{border-width:1px 0 0}
-  table.grid-all>*>tr>.tableblock:last-child,table.grid-cols>*>tr>.tableblock:last-child{border-right-width:0}
-  table.grid-all>tbody>tr:last-child>.tableblock,table.grid-all>thead:last-child>tr>.tableblock,table.grid-rows>tbody>tr:last-child>.tableblock,table.grid-rows>thead:last-child>tr>.tableblock{border-bottom-width:0}
-  table.frame-all{border-width:1px}
-  table.frame-sides{border-width:0 1px}
-  table.frame-topbot,table.frame-ends{border-width:1px 0}
-  .reveal table th.halign-left,.reveal table td.halign-left{text-align:left}
-  .reveal table th.halign-right,.reveal table td.halign-right{text-align:right}
-  .reveal table th.halign-center,.reveal table td.halign-center{text-align:center}
-  .reveal table th.valign-top,.reveal table td.valign-top{vertical-align:top}
-  .reveal table th.valign-bottom,.reveal table td.valign-bottom{vertical-align:bottom}
-  .reveal table th.valign-middle,.reveal table td.valign-middle{vertical-align:middle}
-  table thead th,table tfoot th{font-weight:bold}
-  tbody tr th{display:table-cell;line-height:1.6}
-  tbody tr th,tbody tr th p,tfoot tr th,tfoot tr th p{font-weight:bold}
-  thead{display:table-header-group}
-
-  .reveal table.grid-none th,.reveal table.grid-none td{border-bottom:0!important}
-
-  /* callouts */
-  .conum[data-value] {display:inline-block;color:#fff!important;background-color:rgba(50,150,50,.8);-webkit-border-radius:100px;border-radius:100px;text-align:center;font-size:.75em;width:1.67em;height:1.67em;line-height:1.67em;font-family:"Open Sans","DejaVu Sans",sans-serif;font-style:normal;font-weight:bold}
-  .conum[data-value] *{color:#fff!important}
-  .conum[data-value]+b{display:none}
-  .conum[data-value]:after{content:attr(data-value)}
-  pre .conum[data-value]{position:relative;top:-.125em}
-  b.conum *{color:inherit!important}
-  .conum:not([data-value]):empty{display:none}