# Copyright (C) 2001-2012, Parrot Foundation.

=pod

=head1 NAME

editor/README.pod - Productivity Comes in Pretty Colors

=head1 DESCRIPTION

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

By default calling C<make vim-install> in the F<editor/> directory will
install several files in F<~/.vim>. You can use the variable C<VIM_DIR>
on the command line by calling C<make> to choose a different target directory
for the vim files.

   make vim-install [VIM_DIR=/vim_files_target_directory]

All these files have the F<.vim>
extension. F<pir.vim> (generated from F<pir_vim.in>), F<pasm.vim>, and
F<pmc.vim> are syntax files; F<indent_pir.vim> is an indent plugin;
and F<filetype_parrot.vim> is a filetype script that tells vim to
associate the extensions .pir, .pasm, and .pmc with the
right syntax. The syntax files are installed to F<~/.vim/syntax/>;
F<filetype_parrot.vim> is installed to F<~/.vim/parrot.vim>;
F<indent_pir.vim> is copied to F<~/.vim/indent/pir.vim>.  If you want
indenting, you should also place C<filetype indent on> somewhere in
your F<~/.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 F<editor/> to build it.

Copy the file F<imcc.xml> to F<~/.kde/share/apps/katepart/syntax>.

=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 F<parrot.el> to a directory where Emacs looks
for external packages and add the following to your F<~/.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 F<pasm.el>.

To install the pasm major mode copy F<pasm.el> to a directory where Emacs
looks for external packages and add the following to your F<~/.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 F<~/.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 F<~/.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. Run

  make tags-vi

for Vim-compatible tags or

  make tags-emacs

for Emacs-style tags.  The tool "exuberant ctags" is required for both. There
is also the

  make tags-xemacs

target which will work with older XEmacs etags (21.5*).

=cut
