From 2284351357bac25e203e501c729870785296c8a9 Mon Sep 17 00:00:00 2001 From: Richard Heck Date: Mon, 6 Oct 2008 20:57:11 +0000 Subject: [PATCH] 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 --- lib/doc/Customization.lyx | 1 - lib/doc/Extended.lyx | 543 ++++++++++++++++++++++++++++++++++++++ 2 files changed, 543 insertions(+), 1 deletion(-) diff --git a/lib/doc/Customization.lyx b/lib/doc/Customization.lyx index 6b47f251a7..3c90a75df5 100644 --- a/lib/doc/Customization.lyx +++ b/lib/doc/Customization.lyx @@ -112,7 +112,6 @@ End \output_changes false \author "" \author "" -\author "" \end_header \begin_body diff --git a/lib/doc/Extended.lyx b/lib/doc/Extended.lyx index bdeb450882..3eb7361348 100644 --- a/lib/doc/Extended.lyx +++ b/lib/doc/Extended.lyx @@ -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 -- 2.39.2