1 #LyX 1.1 created this file. For more info see http://www.lyx.org/
14 \paperorientation portrait
17 \paragraph_separation indent
19 \quotes_language english
23 \paperpagestyle default
27 The external material inset
33 One often requested feature from LyX users is to be able to interface LyX
34 with XFig, Dia, or other similar applications that specialize in producing
35 a certain kind of diagram, figure, schematic or whatever material might
36 be relevant to include in your document.
37 Previously, it was only possible to include boring, static, fixed images
38 in LyX documents with the figure inset, but there are several limitations
39 attached to this approach:
42 If you want to change the figure, you have to invoke an external program
46 LyX does not notice that the referenced files change, so the on-screen display
47 can fast become obsolete, and this is aggravated by the lack of a means
48 of updating the display
51 The figure inset only supports PostScript material
54 The figure inset does not provide any mechanisms for coping with different
55 exported formats such as DocBook, HTML or rawAscii
58 The external material inset attempts to solve all of these problems
62 Even if the figure inset can't solve all problems, it is still valuable
63 because it does provide in-line preview of the figure, and supports advanced
64 geometric transformations with a comfortable user interface.
67 It does this by offering a general method to interface LyX to external
69 Instead of introducing a long list of different insets taylored for each
70 specific application, we chose to sacrify the in-line displaying of the
71 included material in order to provide a general construct to cover a wide
72 range of applications.
73 The result is the external inset.
74 An external inset presents itself in the document simply as a button, but
75 don't let this fool you.
76 When you click on it, a dialog will appear that allows you to chose exactly
77 what material to include, and in the following you will learn that this
78 is indeed a powerful mechanism that can solve all of the above problems,
85 The external inset is based on the concept of a
90 A template is a specification of how LyX should interface with a certain
92 As bundled, LyX comes with predefined templates for XFig figures, Dia diagrams,
93 various raster format images, gnuplot, and more.
94 You can check the actual list by using the
96 Insert\SpecialChar \menuseparator
97 Insert external material
100 Furthermore, it is possible to roll your own template to support a specific
102 Later we'll describe in more detail what is involved, and hopefully you
103 will submit all the templates you create so we can include them in a later
107 Another basic idea of the external inset is to distinguish between the original
108 file that serves as a base for final material and the produced file that
109 is included in your exported or printed document.
110 For example, consider the case of a figure produced with XFig.
111 The XFig application itself works on an original file with the
116 Within XFig, you create and change your figure, and when you are done,
122 When you want to include the figure in your document, you invoke
126 in order to create a PostScript file that can readily be included in your
132 file is the original file, and the PostScript file is the produced file.
135 This distinction is important in order to allow updating of the material
136 while you are in the process of writing the document.
137 Furthermore, it provides us with the flexibility that is needed to support
138 multiple export formats.
139 For instance, in the case of an Ascii resulting file, it is not exactly
140 an award-winning idea to include the figure as raw PostScript.
141 Instead, you'd either prefer to just include a reference to the figure,
142 or try to invoke some graphics to Ascii converter to make the final result
143 look similar to the real graphics.
144 The external material inset allows you to do this, because it is parameterized
145 on the different export formats that LyX supports.
148 Besides supporting the production of different products according to the
149 exported format, the external inset supports tight integration with editing
150 and viewing applications.
151 In the case of an XFig figure, you are able to invoke xfig on the original
152 file with a single click from within the external inset in LyX, and also
153 preview the produced PostScript file with ghostview with another click.
154 No more fiddling around with the command line and/or file browsers to locate
155 and manipulate the original or produced files.
156 In this way, you are finally able to take full advantage of the many different
157 applications that are relevant to use when you write your documents, and
158 ultimately be more productive.
161 So, all in all, LyX has information about a number of different programs
162 to use behind the scenes in order to realize all of this machinery.
163 This information, in fact, is exactly what is contained in the templates.
164 To each template, there is associated a list of command lines that are
165 used to invoke applications, convert the original file to the produced
167 This mechanism allows the advanced user to extend the capabilities of LyX
168 without fiddling with the source code.
169 It requires some footwork to define all the different commands and flags,
170 but luckily, the LyX team did all the hard work and specified these for
174 But before the trees grow into the skies, we have to admit that we did take
176 Since the external inset can produce many different kinds of produced files
177 to go with each exported format, one could also expect that it would be
178 possible to preview each product.
179 But, the LyX team decides against this in order to keep the user interface
181 Instead of providing a button for each exported file format, we decided
182 to introduce the concept of the primary file format and just have one button.
187 in the external inset dialog, you will get a view of the produced file
188 in the primary file format.
189 And the primary file format is specified by your document class.
190 For most document classes, the primary file format is LaTeX, but for the
191 DocBook document classes, the primary file format is DocBook.
192 So, when you view the produced file, keep in mind that it will only be
193 a preview of what the main result will be.
194 If you want to see how other exported formats turn out, you have to export
195 them and preview them by hand.
198 The external material inset dialog
201 You insert an external inset from the
206 When you do this, a button is inserted into your document, and the external
207 material inset dialog is shown.
208 This dialog allows you to describe exactly what material should be included,
209 and also how it should be included.
210 Furthermore, it provides access to the external applications to either
211 view, edit or produce the material that is used in the resulting file.
214 At the top of this dialog, there is a drop-down list where you can chose
215 which template the inset should use.
216 Just below the template drop-down, there's an text area with a short blurp
217 about the chosen template that should help you use it.
218 Most often, it will provide a short description of the template, and a
219 few hints on how to parameterize the use of it.
220 Further down, you'll find a filename input field along with a browse-button
221 that allows you to chose which file should be included, with the standard
223 Thus this field specifies the original file.
224 Since the produced file is automatically generated when needed, there is
225 no need to give access to it in the user interface.
228 At the bottom of the dialog, you'll find a general input box called
233 This box is generally used to parameterize the specific template.
234 The specific use should be covered in the help blurp associated with the
235 template, but in general it typically allows you to define variations on
236 how the produced file should be generated.
239 At the right side of the dialog, you'll find three buttons:
252 These in turn allows you to edit your original file with the appropriate
253 editing application, view the produced file as included in the primary
254 format document, and finally force an update of the resulting material
255 in the primary format.
260 button will be disabled, because most templates are configured to automatically
261 update the produced file when needed.
262 In those cases, there is no need to force the production of a new produced
264 However, some templates are configured to not be automatically producing
265 the residual product, because the cost of producing the produced file might
266 be so large that it would be a pain to do it all the time.
267 Those insets are known as
272 In those cases, you can use the button to force the production of the produced
273 file exactly when you need it, and thus control the amount of work that
279 responsibility to do this to keep the produced files current at all times:
280 before printing, before exporting, before viewing, etc.
281 To help you with this task, you can use the
283 Edit\SpecialChar \menuseparator
284 Update all external inset
286 command that will update all external insets that use a manual template.
287 But be prepared that it might take some time for the updating to finish.
290 At the bottom of the dialog, you find the normal
299 The only thing worth mentioning about these is that any changes in the
300 template, filename or parameters are actually applied whenever you press
314 This implies that after using one of those, you will only be able to undo
315 changes that occured after the use of those buttons, by pressing
320 Fortunately, you can use the general undo feature in LyX to revert to a
327 In this section, we should include some examples of use of the external
329 Those examples could include:
332 External raster images
335 External XFig figures
347 Recursive external LyX templates
350 The external template configuration file
353 It is relatively easy to add custom external template definitions to LyX.
354 However, be aware this doing this in an careless manner most probably
358 introduce an easily exploitable security hole.
359 So before you do this, please read the discussion about security which
363 Having said that, we encourage you to submit any interesting templates that
368 The external templates are defined in the
370 lib/external_templates
373 You can place your own version in
375 .lyx/external_templates
378 At some point in time, hopefully somebody will document the template contents,
379 and the syntax used to define your templates.
382 The substitution mechanism
385 When the external material inset invokes an external program, it is done
386 on the basis of a command defined in the template configuration file.
387 These commands can contain various macros that are expanded before execution.
388 Execution always take place in the directory of the containing document.
391 Also, whenever an external inset is to be displayed, the name will be produced
392 by the substitution mechanism.
395 The available macros are the following:
398 $$FName The filename of the file specified in the external inset dialog.
401 $$Basename The filename without the extension.
404 $$Tempname A name and full path to a temporary file which will be automatically
405 deleted whenever the containing document is closed, or the external inset
410 \begin_inset Quotes eld
414 \begin_inset Quotes erd
417 ) This macro will expand to the contents of the file with the name
424 $$Sysdir This macro will expand to the absolute path of the system directory.
425 This is typically used to point to the various helper scripts that are
429 In addition to these, the facility will expand general environment variables
440 The external material inset interfaces with a lot of external programs and
441 does so automatically, so we have to consider the security implications
443 In particular, since you have the option of including your own filenames
444 and/or parameter strings and those are expanded into a command, it seems
445 that it would be possible to create a malicious document which executes
446 arbitrary commands when a user views or prints the document.
447 This is something we definately want to avoid.
450 However, since the external program commands are specified in the template
451 configuration file only, there are no security issues if LyX is properly
452 configured with safe templates only.
453 This is so because the external programs are invoked with the
457 -system call rather than the
461 system-call, so it's not possible to execute arbitrary commands from the
462 filename or parameter section via the shell.
465 This also implies that you are restricted in what command strings you can
466 use in the external material templates.
467 In particular, pipes and redirection are not readily available.
468 This has to be so if LyX should remain safe.
469 If you want to use some of the shell features, you should write a safe
470 script to do this in a controlled manner, and then invoke the script from
476 directory of the LyX installation, you can find a safe wrapper script
478 general_command_wrapper.py
480 that supports redirection of input and output.
481 That can serve as an example for how to write safe template scripts.
482 For a more advanced example that uses
486 and friends, take a look at the
493 It is possible to design a template that interacts directly with the shell,
494 but since this would allow a malicious user to execute arbitrary commands
495 by writing clever filenames and/or parameters, we generally recommend that
496 you only use safe scripts that work with the
500 system call in a controlled manner.
501 Of course, for use in a controlled environment, it can be tempting to just
502 fall back to use ordinary shell scripts.
503 If you do so, be aware that you
507 provide an easily exploitable security hole in your system.
508 Of course it stands to reason that such unsafe templates will never be
509 included in the standard LyX distribution, although we do encourage people
510 to submit new templates in the open source tradition.
511 But LyX as shipped from the official distribution channels will never have
515 The external material inset provides a lot of power, and you have to be
516 careful not to introduce security hazards with this power.
517 A subtile error in a single line in an innocent looking script can open
518 the door to huge security problems.
519 So if you do not fully understand the issues, we recommend that you consult
520 a knowledgable security professional or the LyX development team if you
521 have any questions about whether a given template is safe or not.
522 And do this before you use it in an uncontrolled environment.
525 The future of the external inset
528 The current implementation of the external inset is a stable and powerful
529 construct that provides raw access to the inner parts of LyX, but as with
530 any feature in LyX, it should always be considered work-in-progress.
531 When and if somebody has time to continue work on it, here are some general
532 directions that could be approached:
535 Support in-line previewing in various formats, rather than the button text
536 we are restricted to now.
539 Support in-line editing using OpenParts or any other relevant protocol.
542 Extend the dynamic information to have optional parameter fields for the
543 conversion commands in all export formats, and to have optional parameter
544 fields for what is produced into all the different exported formats.
545 At the moment, we are restricted to only one parameter string that is multiplex
546 ed across these many applications.
547 Also, a change like this would allow us to get rid of the strange primary
548 target format restrictions.
551 Extend the framework to provide more intelligent customization options in
552 addition to the rather simplistic raw parameter strings.
553 With a suitable scripting language, it would be possible to implement user
554 friendly versions of many customizable insets that supports a wide range
555 of formats, LaTeX packages, editors, etc.