        LyX::Client: a perl class for communication with LyX


1. What is LyX?

LyX is a program for writing documents: letters, theses, scientific
articles, novels and so on.

It offers the power of the LaTeX system together with the ease of a
graphical interface. Although LaTeX is very powerful (based in turn on
the professional-quality TeX typesetting system), many people don't
like to use it since it requires, to some extent, to "program" a
document instead of only "writing" it. On the other hand, traditional
"word processor" systems show many limitations that make it impossible
to go beyond a certain quality level (to give you an idea, a
scientific paper carefully prepared with LaTeX is considered
camera-ready by publishers, that is the printed paper can be directly
included in a journal or book without any further editing).

LyX is a "document processor". It offers a comfortable user interface
similar to word processors while using LaTeX as typesetting engine. If
you want to know more visit LyX's homepage: http://la1ad.uio.no/lyx/


2. Why communicate with LyX?

LyX has many features (many) but it cannot possibly do everything that
any user might wish (in fact, it is arguably desirable that LyX sticks
to do what it's born for, composing documents, rather than taking an
"add everything" approach).

On the other hand, LyX provides a mechanism, the LyX Server, to talk
to external programs that can carry out whatever task they wish and
display it's output inside the LyX document. This might include
producing a figure on the fly, fetching a web page to be inserted in
the LyX document, or whatever. The external programs can be invoked by
the LyX users by customizable key sequences, allowing them to appear
effectively as LyX builtin functions.

You can read about the LyX server in chapter 4 of the LyX Customzation
document (available from the Help menu within LyX). You need to
understand the LyX Server to have any use of LyX::Client. 

To date, the Server mechanism has not been widely used, both because
it has been in a somewhat experimental state, and also because users
have taken their time to explore what LyX already provides.

LyX::Client provides a simple class interface so that developers of
LyX clients can focus on what the client should do instead of having to
program the communication code first.


3. Documentation

Documentation on how to use LyX::Client is bundled in the Client.pm
file itself as pod documentation. This is installed by default (see
Installation below), but if you want to read it before type:

pod2man Client.pm > LyX::Client.1
man ./LyX::Client.1

at your shell prompt.


4. Installation

Installation amounts to simply copying Client.pm in a directory where
perl can find it. This is done automatically by the installation
process, which also installs the LyX::Client manpage.

In addition, the LyX::Polite module is required for LyX::Client to
work. Since LyX::Polite makes little sense without LyX::Client, it is
distributed together with it, in a seprate .tar.gz file LyX-Polite-VERSION.
Unpack this file and install it first, doing:

perl Makefile.PL
make install

or "make install_site" if you'd rather keep the files separate from
the official perl stuff. Then, come back in the LyX-Client-VERSION
direcotry and repeat the two steps above.

Now the documentation should be available as the manpages LyX::Client
and LyX::Polite. There is also the directory "examples", containing
two programs: lyxlisten and lyxclient. The first only demostrates
LyX::Polite, it should be of limited use if you want to develop a
client. The second, lyxclient, is much more instructive. To test it,
launch LyX and open a new empty document, then launch lyxclient from a
shell prompt and see what happens. This will also test that the
installation went ok. Note that you must have the LyX Server enabled
from your ~/.lyx/lyxrc file (simply uncommment the \serverpipe line),
and also the Ctrl-a key sequence bound to the "server-notify"
function. To achieve this, add:

\bind "C-a" "server-notify"

in the lyxrc file. Be sure that C-a does not conflict with other key
bindigs that you have (it is safe if you use the default LyX
bindings). Anyway, you *must* read the LyX Server documentation in LyX
to use LyX::Client profitably.


5. Problems

This package is very young. Please report to stefano@zool.su.se any
problems that you find. 


6. Copying

    LyX::Client - a perl interface for communication with LyX
    Copyright (C) 1999  Stefano Ghirlanda, stefano@zool.su.se

    This program is free software; you can redistribute it and/or modify
    it under the terms of the GNU General Public License as published by
    the Free Software Foundation; either version 2 of the License, or
    (at your option) any later version.

    This program is distributed in the hope that it will be useful,
    but WITHOUT ANY WARRANTY; without even the implied warranty of
    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
    GNU General Public License for more details.

    You should have received a copy of the GNU General Public License
    along with this program (see COPYING); if not, write to the Free Software
    Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA

Changes
Client.pm
MANIFEST
Makefile.PL
test.pl
