# $Id: README.pod 18593 2007-05-20 09:04:29Z bernhard $

=head1 NAME

editor/README.pod - Productivity Comes in Pretty Colors

=head1 Syntax Highlighting and Other Editor Assistance

Included in this directory are some add-ins for making working on parrot (or in
parrot) easier, for various popular editors. Mostly that means
syntax-highlighting and automatic indenting. Read on to see what's available for
your favorite editor. For a summary on what is available do
  cd editor && make help

=head2 Vim

Calling C<make vim-install> in the F<editor/> directory 
will install several files in F<~/.vim>. All these files have 
the C<.vim> extension. C<pir.vim>
(generated from C<pir.vim.in>), C<pasm.vim>, and C<pmc.vim> are syntax
files; C<indent_pir.vim> is an indent plugin;  and C<filetype_parrot.vim> is a
filetype script that tells vim to associate the extensions .pir, .imc, .imcc,
.pasm, and .pmc with the right syntax. The syntax files are installed to
C<~/.vim/syntax/>; C<filetype_parrot.vim> is installed to
C<~/.vim/ftdetect>; C<indent_pir.vim> is copied to C<~/.vim/indent/pir.vim>.
If you want indenting, you should also place C<filetype indent on> somewhere in
your C<~/.vimrc>.

=head2 Kate

There is a syntax file for the KDE editor Kate, but it is not built by default.
Run:

   make imc.kate

in C<editor/> to build it.

TODO: How do we install Kate syntax files?

=head2 Emacs

=over 4

=item * Editing the Parrot VM source

In this directory is a F<parrot.el> describing the c-mode and cperl-mode
changes modifications required to edit the Parrot source code.  To install
the Parrot mode support copy C<parrot.el> to a directory where Emacs looks
for external packages and add the following to your C<~/.emacs> file:

    (load "parrot")

Alternatively, if you're an active Parrot developer, you may wish to add
this to your .emacs instead, to automatically track future changes:

    (load-file "/<path-to-parrot>/editor/parrot.el")

=item * Editing PASM source files

Included here is an Emacs mode for editing pasm files, in C<pasm.el>.

To install the pasm major mode copy C<pasm.el> to a directory where Emacs
looks for external packages and add the following to your C<~/.emacs> file:

    (load "pasm")

To automatically associate .pasm files with this major mode add:

    (add-to-list 'auto-mode-alist (cons "\\.pasm\\'" 'pasm-mode))

to your C<~/.emacs> or you can alternatively type C<M-x pasm-mode> for every
file that you want to use the major mode in.

Additionally, you might want to add:

    (add-hook 'pasm-mode-hook
              (function (lambda ()
                          (setq indent-tabs-mode nil))))

to C<~/.emacs> as this seems to prevent the odd behavior that is noted when 
using tabs in the pasm mode.

=back

=head2 TAGS file

There is a script here to automatically generate a TAGS file, which works with
Vim and other editors that recognize ctags-format files. The tool "exuberant
ctags" is required. Run
  make tags
in the parrot root directory to build the tags file.

=cut
