=pod
=for comment
DO NOT EDIT. This Pod was generated by Kwim.
See http://github.com/ingydotnet/kwim-pm#readme
=encoding utf8
=head1 NAME
Vroom - Slide Shows in Vim
=for html
<a href="https://travis-ci.org/ingydotnet/vroom-pm"><img src="https://travis-ci.org/ingydotnet/vroom-pm.png" alt="vroom-pm"></a>
<a href="https://coveralls.io/r/ingydotnet/vroom-pm?branch=master"><img src="https://coveralls.io/repos/ingydotnet/vroom-pm/badge.png" alt="vroom-pm"></a>
=head1 SYNOPSIS
> mkdir MySlides # Make a Directory for Your Slides
> cd MySlides # Go In There
> vroom new # Create Example Slides File
> vim slides.vroom # Edit the File and Add Your Own Slides
> vroom vroom # Show Your Slides
> vroom html # Publish Your Slides as HTML
=head1 DESCRIPTION
Ever given a Slide Show and needed to switch over to Vim?
Now you don't ever have to switch again. You're already there.
Vroom lets you create your slides in a single file using a Wiki-like style,
much like Spork and Sporx do. The difference is that your slides don't compile
to HTML or JavaScript or XUL. They get turned into a set of files that begin
with '0', like '03' or '07c' or '05b.pl'.
The slides are named in alphabetic order. That means you can bring them
all into a Vim session with the command: C<vim 0*>. C<vroom vroom> does
exactly that.
You can do things like advance to the next slide with the spacebar. Vroom
creates a file called C<./.vimrc> with helpful key mappings for navigating a
slideshow. See [KEY MAPPINGS] below.
Vroom takes advantage of Vim's syntax highlighting. It also lets you run
slides that contain code.
Since Vim is an editor, you can change your slides during the show.
=head1 COMMAND USAGE
Vroom has a few command line options:
=over
=item vroom new
Write an example C<slides.vroom> file. This example contains all the config
options and also examples of all the Vroom syntax features.
=item vroom vroom
Compile (create) the slides files from the input file and start vim show.
=item vroom compile
Just compile the slides.
=item vroom html
Publish the slides to HTML, with embedded JavaScript to navigate with the
spacebar and backspace keys. Created in the C<html/> subdirectory.
=item vroom text
Publish the slides to plain text. This action uses all the text slides in
their unsplit form. Created in the C<text/> subdirectory.
=item vroom clean
Clean up all the compiled output files.
=item vroom ghpublish
Creates a shell script in the current directory, that is intended to
publish your slides to the special GitHub branch called gh-pages. See
[GITHUB NOTES] below.
This command does NOT run the script. It merely creates it for you. It is up
to you to review the script and run it (if it makes sense on your system).
=item vroom <action> --skip=#
The skip option takes a number as its input and skips that number of files
during compilation. This is useful when you are polishing your slides and are
finished with the first 50. You can say:
vroom vroom --skip=50
and it will start on slide #51.
=item vroom <action> --input=<file_name>
This option lets you specify an alternate input file name, instead of the
default one, C<slides.vroom>.
=back
=head1 INPUT FORMAT
Here is an example slides.vroom file:
---- config
# These are YAML settings for Vroom
title: My Spiffy Slideshow
# height: 84
# width: 20
auto_size: 1 # Determines height/width automatically
# skip: 12 # Skip 12 slides. Useful when making slides.
---- center
My Presentation
by Ingy
----
== Stuff I care about:
* Foo
+* Bar
+* Baz
---- perl,i10
# Perl code indented 10 spaces
use Vroom;
print "Hello World";
---- center
THE END
A line that starts with C<==> is a header line. It will be centered.
Lines that begin with a C<+> cause vroom to split the slide there, causing an
animation effect.
Lines that begin with a C<%> are slide titles. Titles are completely optional.
They are used with notes files, and also for the index page if you convert to
HTML. You can have only one of these per slide.
A line consisting of nothing but C<====> indicates that what follows are notes
for this slide. Notes are also optional. They are primarily used for notes
files, but are also included if you convert your presentation to HTML. See
[SLIDE NOTES] below.
=head1 CONFIGURATION OPTIONS
each slide can have one or more configuration options. Options are a comma
separated list that follow the C<----> header for a slide. Like this:
---- config
---- center
---- perl,i20
---- include file-name
---- replace
---- skip
=over
=item config
The slide is really a yaml configuration. It will not be displayed in the
presentation, but will tell vroom what to do from that point forward.
Usually, a C<config> slide is the first thing in your input file, but you can
use more than one config slide.
=item center
Center the contents of the slide.
=item C<i##>
'i' followed by a number means to indent the contents by the number of
characters.
=item C<i-##>
'i' followed by a negative number means to strip that number of leading
characters from the contents of the slide. This can be useful if you need to
have characters special to Vroom at the beginning of your lines, for example
if the contents of your slide is unified diff output.
=item perl,ruby,python,php,javascript,haskell,actionscript,html,yaml,xml,json,make,shell,diff
Specifies that the slide is one of those syntaxen, and that the appropriate
file extension will be used, thus causing vim to syntax highlight the slide.
=item include file-path-name
Replace the line with the contents of the specified file. Useful to include
long files that would make your slides file unruly.
=item replace
With the C<replace> option, the '+' animations in the slide cause the content
to replace the previous partial slide, rather than append to it.
=item skip
Ignore the following slide completely.
=back
=head2 Config Slide Options
You can specify the following configuration options in a config slide:
=over
=item C<< title: <text> >>
The title of your presentation.
=item C<< height: <number> >>
The number of lines in the terminal you plan to use when presenting the show.
Used for centering the content.
=item C<< width: <number> >>
The number of columns in the terminal you plan to use when presenting the
show. Used for centering the content.
=item C<< auto_size: <0|1> >>
When set to 1, the height/width options above will be ignored and determined
each time you start the slideshow.
=item C<< indent: <number> >>
All slides will be indented by this number of spaces by default.
=item C<< list_indent: <number> >>
Auto detect slides that have lists in them, and indent them by the specified
number of columns.
=item C<< vim: <name> >>
You can specify the name of the vim executable to use. If you set this to
C<gvim> special gvim support will be provided.
=item GVim options
The following options are available, if your vim option is set to gvim.
fuopt: maxhorz,maxvert
guioptions: egmLtT
guicursor: a:blinkon0-ver25-Cursor
guifont: Bitstream_Vera_Sans_Mono:h18
These are all documented by gvim's help system. Please see that for more
information.
=back
=head1 SLIDE NOTES
You can add notes to each slide, if you like. When you create your
presentation (with C<vroom compile> or C<vroom vroom>), a file called
C<notes.txt> will be created containing all your notes, along with indications
of when to proceed to the next slide. If you give any of your slides titles,
they will also be put into the notes file in order to help you keep track of
where you are in the presentation.
You can print out your notes file, or simply bring it up on a separate device
(such as your smartphone). The notes are not part of the presentation; they
are just for you.
However, if you convert your presentation to HTML, the notes will be included
in a smaller font below each slide. This is useful when sharing your slides
with others who were not present at the presentation.
=head1 KEY MAPPINGS
These are the standard key mappings specified in the local C<.vimrc>.
=over
=item C<< <SPACE> >>
Advance one slide.
=item C<< <BACKSPACE> >>
Go back one slide.
=item C<??>
Bring up the help screen.
=item C<RR> (or R -- deprecated)
If the current slide is declared Perl, Python, Ruby, PHP, Haskell or
JavaScript, then run it accordingly.
=item C<QQ>
Quit Vroom.
=item C<VV>
Since these vim options apply while editing the C<slides.vroom> file (yes,
beware), you can use this shortcut to launch Vroom on the current contents
whilst writing your slides.
=item C<EE>
Edit the file that the cursor is on the filename of.
You can put file path names in your slides, and then easily bring them up
during your presentation.
=item C<OO>
On a Mac, run the OS X C<open> command on the argument that your cursor is on.
For instance, if you want to display an image, you could put the file path of
the image in your slide, then use OO to launch it.
=back
=head1 CUSTOM CONFIGURATION
You can create a file called C<.vroom/vimrc> in your home directory. If vroom
sees this file, it will append it onto every local C<.vimrc> file it creates.
Use this file to specify your own custom vim settings for all your vroom
presentations.
You can also create a file called C<.vroom/gvimrc> for gvim overrides, if you
are using gvim.
=head1 USING MACVIM OR GVIM
If you have a Mac, you really should try using MacVim for Vroom slide shows.
You can run it in fullscreen mode, and it looks kinda professional.
To do this, set the vim option in your config section:
vim: gvim
NOTE: On my Mac, I have gvim symlinked to mvim, which is a smart startup
script that ships with MacVim. Ping me, if you have questions about
this setup.
=head1 GITHUB NOTES
I(ngy) put all my public talks on github. I think it is an excellent way to
publish your slides and give people a url to review them. Here are the things
I do to make this work well:
=over
=item * I create a repository for every presentation I give. The name of the repo is of the form <topic>-<event/time>-talk. You can go to L<http://github.com/ingydotnet/> and look for the repos ending with C<-talk>.
=item * GitHub has a feature called gh-pages that you can use to create a website for each github repo. I use this feature to publish the html output of my talk. I do something like this:
vroom html
mv html /tmp
git branch gh-pages
git checkout gh-pages
rm -r *.html
mv /tmp/html/* .
rmdir /tmp/html
git add .
git commit -m 'Publish my slides'
git push origin gh-pages
git checkout master
=item * Vroom comes with a C<ghpublish> option. If you run:
> vroom ghpublish
it will generate a script called C<ghpublish> that contains commands like the
ones above, to publish your slides to a gh-pages branch.
=item * If my repo is called C<vroom-yapcna2009-talk>, then after I publish the talk to the gh-pages branch, it will be available as L<http://ingydotnet.github.com/vroom-yapcna2009-talk>. I then link this url from L<http://github.com/ingydotnet/vroom-yapcna2009-talk> as the Homepage url.
=back
You can see an example of a talk published to HTML and posted via gh-pages at
L<http://ingydotnet.github.com/vroom-pm/>.
=cut