sios-en.html

<h2><a name="Users">Users</a></h2>

<p>
If you just want to install and use the Irish grammar checker, 
you probably don't need to download anything from this site.
The easiest thing to do is to 
install the Perl module
<i>Lingua::GA::Gramadoir</i>
<a href="#Install">as described below</a>; you'll then 
be able to run
the grammar checker from the command-line, or else use
it in conjunction with your favorite
<a href="#Editors">text editor</a>.
</p>

<h2><a name="Devel">Developers</a></h2>

<p>
All developers will need the latest version of
the
<a href="https://sourceforge.net/projects/gramadoir/files/gramadoir/">developers' pack</a>, which contains the scripts 
for converting rule sets into an installable Perl module.
</p>

<p>
All of the language-dependent input files used by the developers' pack
(lexicons, rule sets, etc.) are contained in the following
<i>language packs</i>:
<ul>
<li><a href="https://sourceforge.net/projects/gramadoir/files/gramadoir-ga/">gramadoir-ga</a> (Irish)
</ul>
</p>

<hr>
<h2><a name="Install">Command-Line Installation and Usage</a></h2>

<h3>Linux and Mac OS X</h3>

<p>
For Mac OS X, if you don't like installing packages from
the command line, you can buy a standalone version of the
grammar checker called <i>Ceart</i>, produced in collaboration
with <a href="https://cruinneog.com/">Cruinneog</a>.
</p>

<p>
The Irish grammar checker is distributed as the Perl module
<a href="https://metacpan.org/release/Lingua-GA-Gramadoir"><i>Lingua::GA::Gramadoir</i></a>.
If you are using Linux or some other Unix-like 
operating system (including Mac OS X),
you surely already have Perl installed
and you can
<a href="http://www.troubleshooters.com/codecorn/littperl/perlcpan.htm">install the module using <i>CPAN.pm</i></a>, for example, like this:
</p>

<pre>
$ cpan
cpan&gt; install Lingua::GA::Gramadoir
</pre>

<p>
You probably need to have root permission to do this; 
if you don't, or you don't know what this means, ask a system
administrator for help. 
Also, if this is the first time you're running cpan, you'll be
guided through some configuration steps before you can
do the installation.
</p>

<p>
Alternatively, you can also install everything by hand:
<a href="https://sourceforge.net/projects/gramadoir/files/Lingua-GA-Gramadoir/">download</a> Lingua::GA::Gramadoir,
unpack the archive, and
try the following standard procedure:
</p>
<pre>
$ perl Makefile.PL
$ make
$ make install
</pre>

<p>
You should now have the front-end script 
<i>gram-ga.pl</i> installed.  To check the grammar of an
Irish language text file called <i>gaeilge.txt</i>,
use the following from the shell prompt:
</p>
<pre>
$ gram-ga.pl gaeilge.txt
</pre>

<p>
More detailed usage instructions can be found using:
</p>
<pre>
$ gram-ga.pl --help
</pre>

<h3>Windows</h3>

<p>
Things are somewhat more painful if you're running something
like Windows.
</p>

<ol>
<li>Install the latest version of
<a href="https://www.activestate.com/products/perl/downloads/">ActiveState Perl</a>.
<li>Go the DOS prompt (for the youngsters, you can get there
by going to Start-&gt;Accessories-&gt;Command Prompt)
<li>Enter <tt>perl -v</tt> to verify that perl was installed correctly and is in your path; you should see something like this:
<pre>
C:&gt; perl -v

This is perl, v.5.8.6 built for MSWin32-x86-multi-thread
(with 3 registered patches, see perl -V for more detail)

Copyright 1987-2004, Larry Wall
...
</pre>
<li>Now install <i>An Gramadóir</i> using the ActivePerl package manager
<a href="https://www.activestate.com/products/perl/ppm-perl-modules/">ppm</a>:
<pre>
C:&gt; ppm
ppm&gt; install Lingua::GA::Gramadoir
ppm&gt; quit
</pre>
<li>You should now have the front-end script 
<i>gram-ga.pl</i> installed.  Unfortunately, by default DOS isn't
capable of displaying the ANSI control codes that are
used to highlight the errors in color.  Also, you need to
tell <i lang="ga">An Gramad&oacute;ir</i> to display messages
in the default DOS character encoding (ibm-850).
Therefore, to check an Irish language text file called <i>gaeilge.txt</i>,
use the following:
</p>
<pre>
C:&gt; gram-ga.pl --aschod=cp850 --dath=none gaeilge.txt
</pre>
<p>Addendum (3 April 2012): I'm grateful to Chris Snedigar for pointing out
<a href="https://softkube.com/blog/ansi-command-line-colors-under-windows">this trick</a> for enabling the ANSI color codes!
</p>
</ol>

<hr>
<h2><a name="Editors">Text Editor Support</a></h2>

<h3>Download</h3>
<p>
Interfaces are available for the three most popular editors 
in the open source community: <i>Vim</i>, <i>Emacs</i>, and 
<i>OpenOffice</i>.  These interfaces are distributed with the Perl
module in the <i>share/</i> directory, but if you prefer you
can download them here:
</p>

<ul>
<li><b><a href="gramadoir.el">gramadoir.el</a></b>.  Emacs Lisp Interface (<a href="gram-emacs.png">screenshot</a>).
<li><b><a href="gramadoir.vim">gramadoir.vim</a></b>.  Plug-in for Vim (<a href="gram-vim.png">screenshot</a>).
<li><b><a href="gramadoir.sxw">gramadoir.sxw</a></b>.  OpenOffice macro (<a href="gram-OOo.png">screenshot</a>).
</ul>

<p>
Installation and usage instructions follow.
</p>

<hr>
<h3>Emacs</h3>
<p>
Martin Gregory has kindly contributed an Emacs interface 
to <i lang="ga">An Gramadóir</i> which is very easy to use.
Here are his instructions:
</p>


<p>
“The Emacs interface to <i lang="ga">An Gramadóir</i> allows you to run <i lang="ga">An Gramadóir</i>
from within an Emacs session and navigate to the locations in the
input files where <i lang="ga">An Gramadóir</i> found problems. The interface is
similar to that of the compile or grep commands in Emacs.
</p>


<h3>INSTALLING THE INTERFACE:</h3>

<p>
Put <a href="gramadoir.el"><i>gramadoir.el</i></a> in your emacs site lisp directory, often something like:
<pre>
   /usr/share/emacs/site-lisp/gramadoir
</pre>
If you don't have
one, put it it ~/lisp or some other directory of your choice and put
the following line in your ~/.emacs file<br>
<pre>
   (load-file "/where/you/put/gramadoir.el")
</pre>
If you are an experienced Emacs user, you'll probably want to auto
load the file.
</p>


<h3>USING THE INTERFACE:</h3>

<p>
The interface allows you to specify files in two different ways:
</p>
<ul>
<li>using the command gramadoir-check-files which prompts for a space
separated list of files, without file completion;</li>
<li>from a dired window using the gramadoir-dired command. This behaves
like other dired commands: either all selected files are processed
or, if no file is selected, the file listed on the current
line is processed.</li>
</ul>

<p>
After running one of the above commands, the output of <i lang="ga">An Gramadóir</i> is
written to a new buffer which is displayed in a separate window. Using
the gramadoir-next-message command positions the cursor at the
location of the first error in the first file. Subsequent use of this
command takes you to the locations of subsequent errors. If you
reposition the cursor in the output buffer, the command takes you to
the location of the next error after that position.
</p>


<h3>CUSTOMISATION:</h3>

<p>
For convenience, you can bind the three commands to keys. These need
to be global definitions, for example:
</p>

<pre>
   (global-set-key "\C-cg" 'gramadoir-check-files)
   (global-set-key "\C-cd" 'gramadoir-dired)
   (global-set-key [f3] 'gramadoir-next-message)
</pre>


<p>
If you installed <i lang="ga">An Gramadóir</i> anywhere other than in /usr/bin
you need to tell the interface where to look for it by putting a line
similar to the following:<br>
<pre>
   (setq gramadoir-program-path "/usr/bin/gram-xx.pl")
</pre>
in your ~/.emacs, substituting the appropriate path for <tt>/usr/bin</tt>
and language code for <i>xx</i>.
</p>

<p>
Finally, the interface highlights the error text both in the output
buffer and in the buffer of the original file. If you prefer not to
highlight the text in the original file, add this:<br>
<pre>
   (setq gramadoir-highlight-text nil)
</pre>
to your ~/.emacs.”
</p>
<hr>
<h3>Vim</h3>
<p>
I've written a script which emulates the behavior of Martin's
Emacs interface within Vim.  You can download it from the link at the
top of this page, or you can get it directly from
<a href="https://vim8.org/scripts/script.php?script_id=802">Vim online</a>.
Instructions:
<ol>
<li>put <a href="gramadoir.vim"><i>gramadoir.vim</i></a> in ~/.vim/plugin.  For languages other
than Irish, you'll need to change the <i>gram-ga.pl</i> around line 30 to
the appropriate script name.</li>

<li>put the following lines in your ~/.vimrc file
<pre>
map &lt;F3&gt; &lt;Plug&gt;Gr
map &lt;F4&gt; &lt;Plug&gt;Neamh
map &lt;F5&gt; &lt;Plug&gt;Amach
</pre>
or choose different hot keys if you want.</li>

<li>open the text file to be checked in Vim.</li>

<li>to check its grammar, press <b>F3</b>; a second buffer,
containing the messages from <i lang="ga">An Gramadóir</i>,
will open at the bottom of the screen.  The cursor
will move to the first error (which is also highlighted in red if you
are using a suitable color terminal).</li>

<li>Each successive use of <b>F3</b> moves to the next error
(in both windows, in parallel).</li>

<li>If the current error is a single word (unknown, misspelled, rare,
non-standard, etc.), you can insert it into your <code>.neamhshuim</code> 
(ignore) file by pressing <b>F4</b>.</li>

<li>Pressing <b>F5</b> exits the grammar checker and resumes normal editing.</li>

<li>Notes: you are free to make edits, corrections, etc. to the 
main buffer while running the grammar checker.  The last error
displayed is tracked according to the cursor position in the 
error buffer, so whenever you press <b>F3</b> it will correctly take you 
to the next error.  This also means that you can jump to any
particular error you'd like: go into the error buffer (with Ctrl-w-w),
move the cursor to just before the desired error, press <b>F3</b>.</li>
</ol>

</p>

<hr>
<h3>OpenOffice</h3>
<p>
The file <a href="gramadoir.sxw"><i>gramadoir.sxw</i></a> is an OpenOffice document 
that contains an embedded macro allowing <i lang="ga">An Gramadóir</i>
to be called directly from an OpenOffice session. 
<b>Update: this macro is no longer working with
the latest versions of OpenOffice; please contact me if you'd be 
interest trying to get it back up and running, or doing a port to
LibreOffice.
</p>