= Ruby Presentation Assistant (R-Pass)

R-Pass is a bundle of small utilities and configuration files to ease
talk slide writing and assist when actually giving the talk. Each program
has its own dependencies, but the most important one is the CodeRay library.
Your version of CodeRay must support the language you want to highlight and the
slide format you want to use.

The rest of this document are explanations about the files included in this
bundle:


= Code sample highlighter

This utility (<tt>code-sample-highlighter</tt>) is a small text filter to
highlight sample code. It supports several slide formats and several source
languages (are you really going to use it for anything besides Ruby?
<tt>;-)</tt> ).  The general idea is like this: you are writing (e.g. LaTeX)
slides, and want to highlight Ruby code. In each place you want highlighted
Ruby code, you write a block with special marks, like this:

 %code ruby
 % class Programmer < Human
 %   def initialize(lang); @lang = lang.to_sym; end
 % end
 %endcode

The <tt>%code</tt>/<tt>%endcode</tt> marks define a "code chunk" that contains
code to be highlighted.  Note that the code you want to highlight is commented
out, so it <b>doesn't</b> appear in the slides (you want the highlighted
version in your slides, not the original one). When you filter the chunk
through <tt>code-sample-highlighter</tt>, you get the following result:

 %code ruby
 % class Programmer < Human
 %   def initialize(lang); @lang = lang.to_sym; end
 % end
 \begin{semiverbatim}
 \synkeyword{class }\synclass{Programmer} \synpunct{<} \synconstant{Human}
  \synkeyword{def
  }\synmethod{initialize}\synpunct{(}\synident{lang}\synpunct{);}
  \synattribute{@lang} \synpunct{=}
  \synident{lang}\synpunct{.}\synident{to\_sym}\synpunct{;} \synkeyword{end}
 \synkeyword{end}
 \end{semiverbatim}
 %endcode

That is, your original code keeps being there, *and* now you have a
syntax-highlighted version of it, in LaTeX format. If you modify the code and
run the filter again, your original code will be kept, but the LaTeX version
will be replaced by an updated version. For other formats it works the same,
only changing the comment format and the given output.

Sample configuration files for easily filtering the are given for VIM (see
below), and it should be trivial to implement those in your text editor of
choice (if you do that, please tell me so I can distribute your configurations
files in the next version).


= VIM configuration files

There are a couple of interesting VIM configuration files under
<tt>/usr/share/r_pass/vim</tt>. The first one is <tt>beamer.vim</tt>, a file
with handy definitions for VIM sessions shown with a beamer. At the time of
this writing, it simply changes the +colorscheme+ to one more beamer-friendly
(you can clearly distinguish the selected text), and changes the font to a huge
one. Please see VIM's help for +runtimepath+ and +runtime+ for ideas on how to
load this file into VIM when needed. Another approach you can take is, just
before your talk, add this line to your <tt>~/.vimrc</tt>:

 source /usr/share/r_pass/vim/beamer.vim

To make VIM use it automatically when starting it. When you finish your talk,
you can comment/remove the line and everything will be as always.

The rest of the files are in the +ftplugin+ directory, and they define the
macro <tt>\RH</tt> to filter all the code blocks through
<tt>code-sample-highlighter</tt>, for slides in LaTeX and HTML formats (again,
at the time of this writing; please look at
<tt>/usr/share/r_pass/vim/ftplugin</tt> for more up-to-date information). There
is also a macro <tt>\RCH</tt>, to refresh the highlight of the _current_ code
block.

To use the +ftplugin+ files, just copy them to the appropriate directories
under your <tt>~/.vim</tt>, or modify your +runtimepath+ VIM variable to
include <tt>/usr/share/r_pass/vim</tt> (i.e., put
<tt>set runtimepath+=/usr/share/r_pass/vim</tt> somewhere in your
<tt>.vimrc</tt>).


= Proyektor

This is a tiny shell script to fire up a +konsole+ session with appropriate
options for a beamer session (big font, black background, fullscreen). It uses
DCOP and Konsole, so it needs a working KDE installation.

The main program needs two files to work: <tt>proyektor.desktop</tt> and
+Proyektor+ (a KDE service definition and a Konsole profile definition,
respectively). These files are installed under
<tt>/usr/share/services/proyektor.desktop</tt> and
<tt>/usr/share/apps/konsole/profiles/Proyektor</tt>, but that may or may not
work for you, depending on your KDE installation. If you want to be sure and
don't want to mess around or figure out anything, just copy the files to
<tt>~/.kde/share/services/</tt> and
<tt>~/.kde/share/apps/konsole/profiles/</tt> and you should be OK.


= Sample highlight files

This bundle also comes with some sample style files for different formats.  At
the time of this writing there are two available: one LaTeX package
(<tt>rubysyntax.sty</tt>) and one CSS file (<tt>rubysyntax.css</tt>).  As you
can guess from the file names, both examples are for the Ruby language syntax,
but you can easily adapt them to the rest of the languages supported by the
CodeRay library.

<b>You need these files, or similar files written by you, to define the visual
aspect of every highlighted syntax element</b>.

In the case of the LaTeX package, you have to load it in your document with
e.g.  <tt>\usepackage{rubysyntax}</tt>. For LaTeX to find it, you have to
either make a copy of the file in your working directory, or convince TeX to
use the files under <tt>/usr/share/r_pass</tt> (see <tt>man texconfig</tt> for
details). If you do not load the package, you will get LaTeX compilation errors
for using non-defined commands.


= License

All these files are (c) 2006 Esteban Manchado Velázquez <zoso*AT*demiurgo.org>.
You can distribute them under the GPL v2.

The exception is <tt>setup.rb</tt>, which is Copyright (c) 2000-2004 Minero
Aoki, and distributed under the terms of the GNU LGPL (Lesser General Public
License) version 2.1.