diff --git a/README.adoc b/README.adoc index 85ee6ec..f13a109 100644 --- a/README.adoc +++ b/README.adoc @@ -2,6 +2,8 @@ Antonin Stefanutti // Meta :description: DeckTape is a high-quality PDF exporter for HTML5 presentation frameworks. +:decktape-version: 1.0.0 +:decktape-tag: v{decktape-version} // Settings :idprefix: :idseparator: - @@ -26,30 +28,34 @@ ifndef::env-github[] :icon-edit: icon:pencil[fw] endif::[] // URIs -:uri-bespokejs: http://markdalgleish.com/projects/bespoke.js -:uri-csss: http://leaverou.github.io/csss -:uri-deckjs: http://imakewebthings.com/deck.js -:uri-decktape-clone: https://github.com/astefanutti/decktape.git +:uri-decktape-release: https://github.com/astefanutti/decktape/releases/latest + +:uri-phantomjs: http://phantomjs.org +:uri-phantomjs-download: https://github.com/astefanutti/decktape/releases/download/{decktape-tag} +:uri-phantomjs-build: {uri-phantomjs}/build.html +:uri-phantomjs-fork: https://github.com/astefanutti/phantomjs/commits/decktape +:uri-phantomjs-page-event-keys: https://github.com/ariya/phantomjs/blob/cab2635e66d74b7e665c44400b8b20a8f225153a/src/modules/webpage.js#L329 + :uri-docker: https://www.docker.com :uri-docker-hub: https://hub.docker.com :uri-docker-image: https://hub.docker.com/r/astefanutti/decktape :uri-docker-ref: http://docs.docker.com/engine/reference + +:uri-qt-webkit: https://wiki.qt.io/Qt_WebKit +:uri-qt-webkit-build: https://wiki.qt.io/Building_Qt_5_from_Git + +:uri-bespokejs: http://markdalgleish.com/projects/bespoke.js +:uri-csss: http://leaverou.github.io/csss +:uri-deckjs: http://imakewebthings.com/deck.js :uri-dzslides: http://paulrouget.com/dzslides :uri-flowtimejs: http://flowtime-js.marcolago.com :uri-impressjs: http://impress.github.io/impress.js :uri-pageres: https://github.com/sindresorhus/pageres -:uri-phantomjs: http://phantomjs.org -:uri-phantomjs-download: http://astefanutti.github.io/decktape/downloads -:uri-phantomjs-build: {uri-phantomjs}/build.html -:uri-phantomjs-fork: https://github.com/astefanutti/phantomjs/commits/decktape -:uri-phantomjs-page-event-keys: https://github.com/ariya/phantomjs/blob/cab2635e66d74b7e665c44400b8b20a8f225153a/src/modules/webpage.js#L329 :uri-remark: http://remarkjs.com :uri-revealjs: http://lab.hakim.se/reveal-js :uri-rise: https://github.com/damianavila/RISE :uri-shower: http://shwr.me :uri-slidy: http://www.w3.org/Talks/Tools/Slidy/ -:uri-qt-webkit: https://wiki.qt.io/Qt_WebKit -:uri-qt-webkit-build: https://wiki.qt.io/Building_Qt_5_from_Git {description} @@ -78,41 +84,36 @@ You can browse some slide deck <> below that have been export == Install -From the command-line, follow the instructions below: +You can install DeckTape by downloading the source and executable manually from the {uri-decktape-release}[latest release], or by executing the instructions below from the command-line: -. Shallow clone DeckTape Git repository: +. Download DeckTape source: + [subs=attributes+] - $ git clone --depth 1 {uri-decktape-clone} + $ curl -L https://github.com/astefanutti/decktape/archive/{decktape-tag}.tar.gz | tar -xz --exclude phantomjs . Change into the `decktape` directory: - - $ cd decktape ++ +[subs=attributes+] + $ cd decktape-{decktape-version} . Download PhantomJS executable: + -- -NOTE: DeckTape currently depends on a <> of PhantomJS. -What follows is a list of precompiled binaries for various platforms. +NOTE: DeckTape currently depends on a <> of PhantomJS. +What follows is a list of pre-compiled binaries for various platforms. [source,shell,subs=attributes+] - # Windows (MSVC 2013), 64-bit, for Windows Vista or later, bundles VC++ Runtime 2013 - $ curl -L {uri-phantomjs-download}/phantomjs-msvc2013-win64.exe -o bin\phantomjs.exe - # Mac OS X (Cocoa), 64-bit, for OS X 10.6 or later - $ curl -L {uri-phantomjs-download}/phantomjs-osx-cocoa-x86-64 -o bin/phantomjs - # Linux (CentOS 6), 64-bit - $ curl -L {uri-phantomjs-download}/phantomjs-linux-centos6-x86-64 -o bin/phantomjs - # Linux (CentOS 7), 64-bit - $ curl -L {uri-phantomjs-download}/phantomjs-linux-centos7-x86-64 -o bin/phantomjs - # Linux (Debian 8), 64-bit - $ curl -L {uri-phantomjs-download}/phantomjs-linux-debian8-x86-64 -o bin/phantomjs - # Linux (Ubuntu 16.04), 64-bit - $ curl -L {uri-phantomjs-download}/phantomjs-linux-ubuntu16-x86-64 -o bin/phantomjs +# Windows (MSVC 2013), for Windows Vista or later, bundles VC++ Runtime 2013 +$ curl -L {uri-phantomjs-download}/phantomjs-msvc2013-x86.exe -o phantomjs.exe +# Mac OS X (Cocoa), 64-bit, for OS X 10.6 or later +$ curl -L {uri-phantomjs-download}/phantomjs-osx-cocoa-x86-64 -o phantomjs +# Linux (static build), 64-bit, requires fontconfig (CentOS) or libfontconfig (Debian, Ubuntu) +$ curl -L {uri-phantomjs-download}/phantomjs-linux-x86-64 -o phantomjs -- . Set the execute permission (non-Windows OS binaries only): - $ chmod +x bin/phantomjs + $ chmod +x phantomjs If the executable isn't available for your target platform, follow the instructions in the <> section. Alternatively, DeckTape provides a {uri-docker-image}[Docker image] so that you can directly execute it with {uri-docker}[Docker]. @@ -124,7 +125,7 @@ Inside the DeckTape install directory, run: [source] ---- -$ ./bin/phantomjs decktape.js -h +$ ./phantomjs decktape.js -h Usage: phantomjs decktape.js [options] [command] @@ -152,7 +153,7 @@ specified and uses it to export and write the PDF into the specified -h + $ ./phantomjs decktape.js -h == Commands @@ -172,7 +173,7 @@ Emulates the end-user interaction by pressing the key with the specified `--keyc The `--keycode` value must be one of the {uri-phantomjs-page-event-keys}[PhantomJS page event keys] and defaults to `Right`, e.g.: - $ ./bin/phantomjs decktape.js generic --keycode=Space + $ ./phantomjs decktape.js generic --keycode=Space == Options @@ -182,21 +183,23 @@ Captures each slide as an image at the `--screenshots-size` resolution, exports The `--screenshots-size` option can be set multiple times. For example: - $ ./bin/phantomjs decktape.js --screenshots --screenshots-size=400x300 --screenshots-size=800x600 + $ ./phantomjs decktape.js --screenshots --screenshots-size=400x300 --screenshots-size=800x600 === `--slides` Exports only the slides specified as a series of slides indexes and ranges, e.g.: [source,shell] - # Capture a single slide - $ ./bin/phantomjs decktape.js --slides 1 - # Capture a series of slides - $ ./bin/phantomjs decktape.js --slides 1,3,5 - # Capture a range of slides - $ ./bin/phantomjs decktape.js --slides 1-10 - # Capture a combination of slides and ranges - $ ./bin/phantomjs decktape.js --slides 1,2,5-10 +---- +# Capture a single slide +$ ./phantomjs decktape.js --slides 1 +# Capture a series of slides +$ ./phantomjs decktape.js --slides 1,3,5 +# Capture a range of slides +$ ./phantomjs decktape.js --slides 1-10 +# Capture a combination of slides and ranges +$ ./phantomjs decktape.js --slides 1,2,5-10 +---- The rendering stops and the file written out after the largest numbered slide is exported. @@ -263,17 +266,19 @@ For example: * To convert an online HTML presentation and have it exported into the working directory under the `slides.pdf` filename: [source,shell,subs=attributes+] - $ docker run --rm -v `pwd`:/slides astefanutti/decktape {uri-revealjs} slides.pdf +$ docker run --rm -v `pwd`:/slides astefanutti/decktape {uri-revealjs} slides.pdf * Or, to convert an HTML presentation that's stored on the local file system in the `home` directory: [source,shell] - $ docker run --rm -v `pwd`:/slides -v ~:/home/user astefanutti/decktape /home/user/slides.html slides.pdf +$ docker run --rm -v `pwd`:/slides -v ~:/home/user astefanutti/decktape /home/user/slides.html slides.pdf * Or, to convert an HTML presentation that's deployed on the local host: [source,shell] - $ docker run --rm --net=host -v `pwd`:/slides astefanutti/decktape http://localhost:8000 slides.pdf +$ docker run --rm --net=host -v `pwd`:/slides astefanutti/decktape http://localhost:8000 slides.pdf -It is recommended to use the following options from the {uri-docker-ref}/run[`docker run`] command: +You may want to specify a tag corresponding to a released version of DeckTape for the Docker image, e.g. `astefanutti/decktape:{decktape-version}`. + +Besides, it is recommended to use the following options from the {uri-docker-ref}/run[`docker run`] command: {uri-docker-ref}/run/#clean-up-rm[`--rm`]:: DeckTape is meant to be run as a short-term foreground process so that it's not necessary to have the container's file system persisted after DeckTape exits, {uri-docker-ref}/commandline/run/#mount-volume-v-read-only[`-v`]:: to mount a data volume so that DeckTape can directly write to the local file system. @@ -281,19 +286,21 @@ It is recommended to use the following options from the {uri-docker-ref}/run[`do Alternatively, you can use the {uri-docker-ref}/commandline/cp[`docker cp`] command, e.g.: [source,shell,subs=attributes+] - # Run docker run without the --rm option - $ docker run astefanutti/decktape {uri-revealjs} slides.pdf - # Copy the exported PDF from the latest used container to the local file system - $ docker cp `docker ps -lq`:decktape/slides.pdf . - # Finally remove the latest used container - $ docker rm `docker ps -lq` +---- +# Run docker run without the --rm option +$ docker run astefanutti/decktape {uri-revealjs} slides.pdf +# Copy the exported PDF from the latest used container to the local file system +$ docker cp `docker ps -lq`:decktape/slides.pdf . +# Finally remove the latest used container +$ docker rm `docker ps -lq` +---- Finally, if you want to execute DeckTape using a local clone of the DeckTape repository in order to take your changes into account, you can run: [source,shell] - $ docker run --rm -v `pwd`:`pwd` -w `pwd` astefanutti/decktape slides.html slides.pdf +$ docker run --rm -v `pwd`:`pwd` -w `pwd` astefanutti/decktape slides.html slides.pdf -== PhantomJS fork +== PhantomJS === Overview