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 At some time in the future, it might be possible that LyX will help you
283 It would be nice to use a
285 Edit\SpecialChar \menuseparator
286 Update all external inset
288 command to update all external insets that use a manual template.
289 But be prepared that it might take some time for the updating to implemented.
292 At the bottom of the dialog, you find the normal
301 The only thing worth mentioning about these is that any changes in the
302 template, filename or parameters are actually applied whenever you press
316 This implies that after using one of those, you will only be able to undo
317 changes that occured after the use of those buttons, by pressing
322 Fortunately, you can use the general undo feature in LyX to revert to a
329 In this section, we should include some examples of use of the external
331 Those examples could include:
334 External raster images
337 External XFig figures
349 Recursive external LyX templates
352 The external template configuration file
355 It is relatively easy to add custom external template definitions to LyX.
356 However, be aware this doing this in an careless manner most probably
360 introduce an easily exploitable security hole.
361 So before you do this, please read the discussion about security which
365 Having said that, we encourage you to submit any interesting templates that
370 The external templates are defined in the
372 lib/external_templates
375 You can place your own version in
377 .lyx/external_templates
380 At some point in time, hopefully somebody will document the template contents,
381 and the syntax used to define your templates.
384 The substitution mechanism
387 When the external material inset invokes an external program, it is done
388 on the basis of a command defined in the template configuration file.
389 These commands can contain various macros that are expanded before execution.
390 Execution always take place in the directory of the containing document.
393 Also, whenever an external inset is to be displayed, the name will be produced
394 by the substitution mechanism.
397 The available macros are the following:
400 $$FName The filename of the file specified in the external inset dialog.
403 $$Basename The filename without the extension.
406 $$Tempname A name and full path to a temporary file which will be automatically
407 deleted whenever the containing document is closed, or the external inset
412 \begin_inset Quotes eld
416 \begin_inset Quotes erd
419 ) This macro will expand to the contents of the file with the name
426 $$Sysdir This macro will expand to the absolute path of the system directory.
427 This is typically used to point to the various helper scripts that are
431 In addition to these, the facility will expand general environment variables
442 The external material inset interfaces with a lot of external programs and
443 does so automatically, so we have to consider the security implications
445 In particular, since you have the option of including your own filenames
446 and/or parameter strings and those are expanded into a command, it seems
447 that it would be possible to create a malicious document which executes
448 arbitrary commands when a user views or prints the document.
449 This is something we definately want to avoid.
452 However, since the external program commands are specified in the template
453 configuration file only, there are no security issues if LyX is properly
454 configured with safe templates only.
455 This is so because the external programs are invoked with the
459 -system call rather than the
463 system-call, so it's not possible to execute arbitrary commands from the
464 filename or parameter section via the shell.
467 This also implies that you are restricted in what command strings you can
468 use in the external material templates.
469 In particular, pipes and redirection are not readily available.
470 This has to be so if LyX should remain safe.
471 If you want to use some of the shell features, you should write a safe
472 script to do this in a controlled manner, and then invoke the script from
478 directory of the LyX installation, you can find a safe wrapper script
480 general_command_wrapper.py
482 that supports redirection of input and output.
483 That can serve as an example for how to write safe template scripts.
484 For a more advanced example that uses
488 and friends, take a look at the
495 It is possible to design a template that interacts directly with the shell,
496 but since this would allow a malicious user to execute arbitrary commands
497 by writing clever filenames and/or parameters, we generally recommend that
498 you only use safe scripts that work with the
502 system call in a controlled manner.
503 Of course, for use in a controlled environment, it can be tempting to just
504 fall back to use ordinary shell scripts.
505 If you do so, be aware that you
509 provide an easily exploitable security hole in your system.
510 Of course it stands to reason that such unsafe templates will never be
511 included in the standard LyX distribution, although we do encourage people
512 to submit new templates in the open source tradition.
513 But LyX as shipped from the official distribution channels will never have
517 The external material inset provides a lot of power, and you have to be
518 careful not to introduce security hazards with this power.
519 A subtile error in a single line in an innocent looking script can open
520 the door to huge security problems.
521 So if you do not fully understand the issues, we recommend that you consult
522 a knowledgable security professional or the LyX development team if you
523 have any questions about whether a given template is safe or not.
524 And do this before you use it in an uncontrolled environment.
527 The future of the external inset
530 The current implementation of the external inset is a stable and powerful
531 construct that provides raw access to the inner parts of LyX, but as with
532 any feature in LyX, it should always be considered work-in-progress.
533 When and if somebody has time to continue work on it, here are some general
534 directions that could be approached:
537 Support in-line previewing in various formats, rather than the button text
538 we are restricted to now.
541 Support in-line editing using OpenParts or any other relevant protocol.
544 Extend the dynamic information to have optional parameter fields for the
545 conversion commands in all export formats, and to have optional parameter
546 fields for what is produced into all the different exported formats.
547 At the moment, we are restricted to only one parameter string that is multiplex
548 ed across these many applications.
549 Also, a change like this would allow us to get rid of the strange primary
550 target format restrictions.
553 Extend the framework to provide more intelligent customization options in
554 addition to the rather simplistic raw parameter strings.
555 With a suitable scripting language, it would be possible to implement user
556 friendly versions of many customizable insets that supports a wide range
557 of formats, LaTeX packages, editors, etc.