mirror of
https://git.lyx.org/repos/lyx.git
synced 2024-09-19 22:40:26 +00:00
Stuff on the LyX server should be in the Extended Features manual, not the
Customization manual. git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@26787 a592a061-630c-0410-9148-cb99ea01b6c8
This commit is contained in:
Richard Heck
parent
c59a64a880
commit
2284351357
@ -112,7 +112,6 @@ End
|
||||
\output_changes false
|
||||
\author ""
|
||||
\author ""
|
||||
\author ""
|
||||
\end_header
|
||||
|
||||
\begin_body
|
||||
|
||||
@ -50,6 +50,21 @@ logicalmkup
|
||||
theorems-ams
|
||||
theorems-ams-extended
|
||||
\end_modules
|
||||
\begin_local_layout
|
||||
Format 7
|
||||
InsetLayout CharStyle:MenuItem
|
||||
LyxType charstyle
|
||||
LabelString menu
|
||||
LatexType command
|
||||
LatexName menuitem
|
||||
Font
|
||||
Family Sans
|
||||
EndFont
|
||||
Preamble
|
||||
\newcommand*{\menuitem}[1]{{\sffamily #1}}
|
||||
EndPreamble
|
||||
End
|
||||
\end_local_layout
|
||||
\language english
|
||||
\inputencoding latin1
|
||||
\font_roman default
|
||||
@ -3300,6 +3315,534 @@ labelitemi[0]{
|
||||
savelabelitemi}
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
The LyX Server
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
Introduction
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The `LyX server' allows other programs to talk to LyX, invoke LyX commands,
|
||||
and retrieve information about the LyX internal state.
|
||||
This is only intended for advanced users, but they should find it useful.
|
||||
It is by writing to the LyX server, for example, that bibliography managers,
|
||||
such as JabRef, are able to
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
push
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
citations to LyX.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Please note that, at present,
|
||||
\emph on
|
||||
the server does not work on Windows
|
||||
\emph default
|
||||
®.
|
||||
\begin_inset Foot
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
There is no reason it cannot do so.
|
||||
But none of the developers on Windows® have yet implemented this functionality
|
||||
there.
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
Starting the LyX Server
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The LyX server works through the use of a pair of named pipes.
|
||||
These are usually located in
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
UserDir
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
and have the names
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
lyxpipe.in
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
and
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
lyxpipe.out
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
External programs write into
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
.lyxpipe.in
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
and read back data from
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
.lyxpipe.out
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
The stem of the pipe names can be defined in the
|
||||
\begin_inset Flex CharStyle:MenuItem
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
|
||||
\bar under
|
||||
T
|
||||
\bar default
|
||||
ools\SpecialChar \menuseparator
|
||||
|
||||
\bar under
|
||||
P
|
||||
\bar default
|
||||
references
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
dialog, for example
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
"/home/myhome/lyxpipe"
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
You
|
||||
\emph on
|
||||
must
|
||||
\emph default
|
||||
configure this manually in order for the server to start.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
LyX will add the '
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
.in
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
' and '
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
.out
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
' to create the pipes.
|
||||
If one of the pipes already exists, LyX will assume that another LyX process
|
||||
is already running and will not start the server.
|
||||
This means that if LyX crashes, or if for some other reason, a
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
stale
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
pipe is left in existence when LyX closes, then LyX will not start the
|
||||
server.
|
||||
(This is bug 641.) You will need to delete the pipes manually and then restart
|
||||
LyX.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
To have several LyX processes with servers at the same time, you have to
|
||||
use different configurations, perhaps by using separate user directories,
|
||||
each with its own
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
preferences
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
file, for each process.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
If you are developing a client program, you might find it useful to enable
|
||||
debugging information from the LyX server.
|
||||
Do this by starting LyX as
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
lyx -dbg lyxserver
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Other than this, there are a few points to consider:
|
||||
\end_layout
|
||||
|
||||
\begin_layout Itemize
|
||||
Both server and clients must run on UNIX or OS/2 machines.
|
||||
Communications between LyX on UNIX and clients on OS/2 or vice versa is
|
||||
not possible right now.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Itemize
|
||||
On OS/2, only one client can connect to LyXServer at a time.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Itemize
|
||||
On OS/2, clients must open the input pipe with
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
O_WRONLY
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
mode.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
You can find a complete example client written in C in the source distribution
|
||||
as
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
development/lyxserver/server_monitor.c
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
Normal communication
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
To issue a LyX call, the client writes a line of ASCII text into the input
|
||||
pipe.
|
||||
This line has the following format:
|
||||
\end_layout
|
||||
|
||||
\begin_layout Quote
|
||||
LYXCMD:
|
||||
\emph on
|
||||
clientname
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
function
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
argument
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
clientname is a name that the client can choose arbitrarily.
|
||||
Its only use is that LyX will echo it if it sends an answer---so a client
|
||||
can dispatch results from different requesters.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
function is the function you want LyX to perform.
|
||||
It is the same as the commands you'd use in the minibuffer.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Description
|
||||
argument is an optional argument which is meaningful only to some functions
|
||||
(for instance, the
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
self-insert
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
LFUN will insert the argument as text at the cursor position).
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
The answer from LyX will arrive in the output pipe and be of the form
|
||||
\end_layout
|
||||
|
||||
\begin_layout Quote
|
||||
INFO:
|
||||
\emph on
|
||||
clientname
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
function
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
data
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
where
|
||||
\emph on
|
||||
clientname
|
||||
\emph default
|
||||
and
|
||||
\emph on
|
||||
function
|
||||
\emph default
|
||||
are just echoed from the command request, while
|
||||
\emph on
|
||||
data
|
||||
\emph default
|
||||
is more or less useful information filled according to how the command
|
||||
execution worked out.
|
||||
Some commands, such as
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
font-state
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
, will return information about the internal state of LyX, while other will
|
||||
return an empty data-response.
|
||||
This means that the command execution went fine.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
In case of errors, the response from LyX will have this form
|
||||
\end_layout
|
||||
|
||||
\begin_layout Quote
|
||||
ERROR:
|
||||
\emph on
|
||||
clientname
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
function
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
error message
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
where the
|
||||
\emph on
|
||||
error message
|
||||
\emph default
|
||||
should contain an explanation of why the command failed.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
Examples:
|
||||
\end_layout
|
||||
|
||||
\begin_layout LyX-Code
|
||||
echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
|
||||
\end_layout
|
||||
|
||||
\begin_layout LyX-Code
|
||||
echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
|
||||
\begin_inset Newline newline
|
||||
\end_inset
|
||||
|
||||
read a <~/.lyxpipe.out
|
||||
\begin_inset Newline newline
|
||||
\end_inset
|
||||
|
||||
echo $a
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
Notification
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
LyX can notify clients of events going on asynchronously.
|
||||
Currently it will only do this if the user binds a key sequence with the
|
||||
function
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
notify
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
The format of the string LyX sends is as follows:
|
||||
\end_layout
|
||||
|
||||
\begin_layout Quote
|
||||
\begin_inset Flex CharStyle:Code
|
||||
status collapsed
|
||||
|
||||
\begin_layout Plain Layout
|
||||
NOTIFY:
|
||||
\end_layout
|
||||
|
||||
\end_inset
|
||||
|
||||
|
||||
\emph on
|
||||
key-sequence
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
where
|
||||
\emph on
|
||||
key-sequence
|
||||
\emph default
|
||||
is the printed representation of the key sequence that was actually typed
|
||||
by the user.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
This mechanism can be used to extend LyX's command set and implement macros.
|
||||
Bind some key sequence to
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
notify
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
Then start a client that listens on the output pipe, dispatches the command
|
||||
according to the sequence, and starts a function that may use LyX calls
|
||||
and LyX requests to issue a command or a series of commands to LyX.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Section
|
||||
The simple LyX Server Protocol
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
LyX implements a simple protocol that can be used for session management.
|
||||
All messages are of the form
|
||||
\end_layout
|
||||
|
||||
\begin_layout Quote
|
||||
LYXSRV:
|
||||
\emph on
|
||||
clientname
|
||||
\emph default
|
||||
:
|
||||
\emph on
|
||||
protocol message
|
||||
\end_layout
|
||||
|
||||
\begin_layout Standard
|
||||
where
|
||||
\emph on
|
||||
protocol message
|
||||
\emph default
|
||||
can be
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
hello
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
or
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
bye
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
.
|
||||
If
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
hello
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
is received from a client, LyX will report back to inform the client that
|
||||
it's listening to it's messages, while
|
||||
\begin_inset Quotes eld
|
||||
\end_inset
|
||||
|
||||
bye
|
||||
\begin_inset Quotes erd
|
||||
\end_inset
|
||||
|
||||
sent from LyX will inform clients that LyX is closing.
|
||||
\end_layout
|
||||
|
||||
\begin_layout Chapter
|
||||
Special Document Classes
|
||||
\end_layout
|
||||
|
||||
Loading…
Reference in New Issue
Block a user