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
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
projects / features.git / commitdiff