fix typo that put too many include paths for most people

[lyx.git] / lib / doc / ExternalMaterial.lyx

#LyX 1.1 created this file. For more info see http://www.lyx.org/
\lyxformat 2.16
\textclass article
\language english
\inputencoding latin1
\fontscheme default
\graphics default
\paperfontsize default
\spacing single 
\papersize Default
\paperpackage a4
\use_geometry 0
\use_amsmath 0
\paperorientation portrait
\secnumdepth 3
\tocdepth 3
\paragraph_separation indent
\defskip medskip
\quotes_language english
\quotes_times 2
\papercolumns 1
\papersides 1
\paperpagestyle default

\layout Section

The external material inset
\layout Subsection

Background
\layout Standard

One often requested feature from LyX users is to be able to interface LyX
 with XFig, Dia, or other similar applications that specialize in producing
 a certain kind of diagram, figure, schematic or whatever material might
 be relevant to include in your document.
 Previously, it was only possible to include boring, static, fixed images
 in LyX documents with the figure inset, but there are several limitations
 attached to this approach:
\layout Itemize

If you want to change the figure, you have to invoke an external program
 by hand
\layout Itemize

LyX does not notice that the referenced files change, so the on-screen display
 can fast become obsolete, and this is aggravated by the lack of a means
 of updating the display
\layout Itemize

The figure inset only supports PostScript material
\layout Itemize

The figure inset does not provide any mechanisms for coping with different
 exported formats such as DocBook, HTML or rawAscii
\layout Standard

The external material inset attempts to solve all of these problems
\begin_float footnote 
\layout Standard

Even if the figure inset can't solve all problems, it is still valuable
 because it does provide in-line preview of the figure, and supports advanced
 geometric transformations with a comfortable user interface.
\end_float 
.
 It does this by offering a general method to interface LyX to external
 applications.
 Instead of introducing a long list of different insets taylored for each
 specific application, we chose to sacrify the in-line displaying of the
 included material in order to provide a general construct to cover a wide
 range of applications.
 The result is the external inset.
 An external inset presents itself in the document simply as a button, but
 don't let this fool you.
 When you click on it, a dialog will appear that allows you to chose exactly
 what material to include, and in the following you will learn that this
 is indeed a powerful mechanism that can solve all of the above problems,
 and more.
\layout Subsection

How does it work?
\layout Standard

The external inset is based on the concept of a
\emph on 
 template
\emph default 
.
 A template is a specification of how LyX should interface with a certain
 kind of material.
 As bundled, LyX comes with predefined templates for XFig figures, Dia diagrams,
 various raster format images, gnuplot, and more.
 You can check the actual list by using the 
\family sans 
Insert\SpecialChar \menuseparator
Insert external material 
\family default 
command.
 Furthermore, it is possible to roll your own template to support a specific
 kind of material.
 Later we'll describe in more detail what is involved, and hopefully you
 will submit all the templates you create so we can include them in a later
 LyX version.
\layout Standard

Another basic idea of the external inset is to distinguish between the original
 file that serves as a base for final material and the produced file that
 is included in your exported or printed document.
 For example, consider the case of a figure produced with XFig.
 The XFig application itself works on an original file with the 
\family typewriter 
.fig
\family default 
 extension.
 Within XFig, you create and change your figure, and when you are done,
 you save the 
\family typewriter 
fig
\family default 
-file.
 When you want to include the figure in your document, you invoke 
\family typewriter 
transfig
\family default 
 in order to create a PostScript file that can readily be included in your
 LaTeX file.
 In this case, the 
\family typewriter 
.fig
\family default 
 file is the original file, and the PostScript file is the produced file.
\layout Standard

This distinction is important in order to allow updating of the material
 while you are in the process of writing the document.
 Furthermore, it provides us with the flexibility that is needed to support
 multiple export formats.
 For instance, in the case of an Ascii resulting file, it is not exactly
 an award-winning idea to include the figure as raw PostScript.
 Instead, you'd either prefer to just include a reference to the figure,
 or try to invoke some graphics to Ascii converter to make the final result
 look similar to the real graphics.
 The external material inset allows you to do this, because it is parameterized
 on the different export formats that LyX supports.
\layout Standard

Besides supporting the production of different products according to the
 exported format, the external inset supports tight integration with editing
 and viewing applications.
 In the case of an XFig figure, you are able to invoke xfig on the original
 file with a single click from within the external inset in LyX, and also
 preview the produced PostScript file with ghostview with another click.
 No more fiddling around with the command line and/or file browsers to locate
 and manipulate the original or produced files.
 In this way, you are finally able to take full advantage of the many different
 applications that are relevant to use when you write your documents, and
 ultimately be more productive.
\layout Standard

So, all in all, LyX has information about a number of different programs
 to use behind the scenes in order to realize all of this machinery.
 This information, in fact, is exactly what is contained in the templates.
 To each template, there is associated a list of command lines that are
 used to invoke applications, convert the original file to the produced
 file, and more.
 This mechanism allows the advanced user to extend the capabilities of LyX
 without fiddling with the source code.
 It requires some footwork to define all the different commands and flags,
 but luckily, the LyX team did all the hard work and specified these for
 you.
\layout Standard

But before the trees grow into the skies, we have to admit that we did take
 one tiny short-cut.
 Since the external inset can produce many different kinds of produced files
 to go with each exported format, one could also expect that it would be
 possible to preview each product.
 But, the LyX team decides against this in order to keep the user interface
 simple.
 Instead of providing a button for each exported file format, we decided
 to introduce the concept of the primary file format and just have one button.
 When you press 
\family sans 
View result
\family default 
 in the external inset dialog, you will get a view of the produced file
 in the primary file format.
 And the primary file format is specified by your document class.
 For most document classes, the primary file format is LaTeX, but for the
 DocBook document classes, the primary file format is DocBook.
 So, when you view the produced file, keep in mind that it will only be
 a preview of what the main result will be.
 If you want to see how other exported formats turn out, you have to export
 them and preview them by hand.
\layout Subsection

The external material inset dialog
\layout Standard

You insert an external inset from the 
\family sans 
Insert
\family default 
 menu.
 When you do this, a button is inserted into your document, and the external
 material inset dialog is shown.
 This dialog allows you to describe exactly what material should be included,
 and also how it should be included.
 Furthermore, it provides access to the external applications to either
 view, edit or produce the material that is used in the resulting file.
\layout Standard

At the top of this dialog, there is a drop-down list where you can chose
 which template the inset should use.
 Just below the template drop-down, there's an text area with a short blurp
 about the chosen template that should help you use it.
 Most often, it will provide a short description of the template, and a
 few hints on how to parameterize the use of it.
 Further down, you'll find a filename input field along with a browse-button
 that allows you to chose which file should be included, with the standard
 file browser.
 Thus this field specifies the original file.
 Since the produced file is automatically generated when needed, there is
 no need to give access to it in the user interface.
\layout Standard

At the bottom of the dialog, you'll find a general input box called 
\family sans 
Parameters
\family default 
.
 This box is generally used to parameterize the specific template.
 The specific use should be covered in the help blurp associated with the
 template, but in general it typically allows you to define variations on
 how the produced file should be generated.
\layout Standard

At the right side of the dialog, you'll find three buttons: 
\family sans 
Edit file
\family default 
, 
\family sans 
View result
\family default 
, and 
\family sans 
Update result
\family default 
.
 These in turn allows you to edit your original file with the appropriate
 editing application, view the produced file as included in the primary
 format document, and finally force an update of the resulting material
 in the primary format.
 Normally, the 
\family sans 
Update result
\family default 
 button will be disabled, because most templates are configured to automatically
 update the produced file when needed.
 In those cases, there is no need to force the production of a new produced
 file.
 However, some templates are configured to not be automatically producing
 the residual product, because the cost of producing the produced file might
 be so large that it would be a pain to do it all the time.
 Those insets are known as 
\emph on 
manual
\emph default 
 external insets.
 In those cases, you can use the button to force the production of the produced
 file exactly when you need it, and thus control the amount of work that
 is done.
 In fact, it is 
\emph on 
your
\emph default 
 responsibility to do this to keep the produced files current at all times:
 before printing, before exporting, before viewing, etc.
 At some time in the future, it might be possible that LyX will help you
 with this task.
 It would be nice to use a 
\family sans 
Edit\SpecialChar \menuseparator
Update all external inset
\family default 
 command to update all external insets that use a manual template.
 But be prepared that it might take some time for the updating to implemented.
\layout Standard

At the bottom of the dialog, you find the normal 
\family sans 
OK
\family default 
 and 
\family sans 
Cancel
\family default 
 buttons.
 The only thing worth mentioning about these is that any changes in the
 template, filename or parameters are actually applied whenever you press
 
\family sans 
Edit file
\family default 
, 
\family sans 
View result
\family default 
 or 
\family sans 
Update result
\family default 
 buttons.
 This implies that after using one of those, you will only be able to undo
 changes that occured after the use of those buttons, by pressing 
\family sans 
Cancel
\family default 
.
 Fortunately, you can use the general undo feature in LyX to revert to a
 previous state.
\layout Subsection

Examples
\layout Standard

In this section, we should include some examples of use of the external
 material inset.
 Those examples could include:
\layout Itemize

External raster images
\layout Itemize

External XFig figures
\layout Itemize

Chess diagrams
\layout Itemize

Sound samples
\layout Itemize

The use of makefiles
\layout Itemize

Recursive external LyX templates
\layout Subsection

The external template configuration file
\layout Standard

It is relatively easy to add custom external template definitions to LyX.
 However, be aware this doing this in an careless manner most probably 
\emph on 
will
\emph default 
 introduce an easily exploitable security hole.
 So before you do this, please read the discussion about security which
 will follow later.
\layout Standard

Having said that, we encourage you to submit any interesting templates that
 you create.
 
\layout Standard

The external templates are defined in the 
\family typewriter 
lib/external_templates
\family default 
 file.
 You can place your own version in 
\family typewriter 
.lyx/external_templates
\family default 
.
 At some point in time, hopefully somebody will document the template contents,
 and the syntax used to define your templates.
\layout Subsection

The substitution mechanism
\layout Standard

When the external material inset invokes an external program, it is done
 on the basis of a command defined in the template configuration file.
 These commands can contain various macros that are expanded before execution.
 Execution always take place in the directory of the containing document.
\layout Standard

Also, whenever an external inset is to be displayed, the name will be produced
 by the substitution mechanism.
\layout Standard

The available macros are the following:
\layout Description

$$FName The filename of the file specified in the external inset dialog.
\layout Description

$$Basename The filename without the extension.
\layout Description

$$Tempname A name and full path to a temporary file which will be automatically
 deleted whenever the containing document is closed, or the external inset
 deleted.
\layout Description

$$Contents(
\begin_inset Quotes eld
\end_inset 

filename.ext
\begin_inset Quotes erd
\end_inset 

) This macro will expand to the contents of the file with the name 
\family typewriter 
filename.ext
\family default 
.
\layout Description

$$Sysdir This macro will expand to the absolute path of the system directory.
 This is typically used to point to the various helper scripts that are
 bundled with LyX.
\layout Standard

In addition to these, the facility will expand general environment variables
 with a syntax like 
\family typewriter 
${PATH}
\family default 
.
\layout Subsection

Security discussion
\layout Standard

The external material inset interfaces with a lot of external programs and
 does so automatically, so we have to consider the security implications
 of this.
 In particular, since you have the option of including your own filenames
 and/or parameter strings and those are expanded into a command, it seems
 that it would be possible to create a malicious document which executes
 arbitrary commands when a user views or prints the document.
 This is something we definately want to avoid.
\layout Standard

However, since the external program commands are specified in the template
 configuration file only, there are no security issues if LyX is properly
 configured with safe templates only.
 This is so because the external programs are invoked with the 
\family typewriter 
execvp
\family default 
-system call rather than the 
\family typewriter 
system
\family default 
 system-call, so it's not possible to execute arbitrary commands from the
 filename or parameter section via the shell.
\layout Standard

This also implies that you are restricted in what command strings you can
 use in the external material templates.
 In particular, pipes and redirection are not readily available.
 This has to be so if LyX should remain safe.
 If you want to use some of the shell features, you should write a safe
 script to do this in a controlled manner, and then invoke the script from
 the command string.
 In the 
\family typewriter 
lib/scripts
\family default 
 directory of the LyX installation, you can find a safe wrapper script 
\family typewriter 
general_command_wrapper.py
\family default 
 that supports redirection of input and output.
 That can serve as an example for how to write safe template scripts.
 For a more advanced example that uses 
\family typewriter 
fork
\family default 
 and friends, take a look at the 
\family typewriter 
pic2ascii.py
\family default 
 converter script.
\layout Standard

It is possible to design a template that interacts directly with the shell,
 but since this would allow a malicious user to execute arbitrary commands
 by writing clever filenames and/or parameters, we generally recommend that
 you only use safe scripts that work with the 
\family typewriter 
execvp
\family default 
 system call in a controlled manner.
 Of course, for use in a controlled environment, it can be tempting to just
 fall back to use ordinary shell scripts.
 If you do so, be aware that you 
\emph on 
will
\emph default 
 provide an easily exploitable security hole in your system.
 Of course it stands to reason that such unsafe templates will never be
 included in the standard LyX distribution, although we do encourage people
 to submit new templates in the open source tradition.
 But LyX as shipped from the official distribution channels will never have
 unsafe templates.
\layout Standard

The external material inset provides a lot of power, and you have to be
 careful not to introduce security hazards with this power.
 A subtile error in a single line in an innocent looking script can open
 the door to huge security problems.
 So if you do not fully understand the issues, we recommend that you consult
 a knowledgable security professional or the LyX development team if you
 have any questions about whether a given template is safe or not.
 And do this before you use it in an uncontrolled environment.
\layout Subsection

The future of the external inset
\layout Standard

The current implementation of the external inset is a stable and powerful
 construct that provides raw access to the inner parts of LyX, but as with
 any feature in LyX, it should always be considered work-in-progress.
 When and if somebody has time to continue work on it, here are some general
 directions that could be approached:
\layout Itemize

Support in-line previewing in various formats, rather than the button text
 we are restricted to now.
\layout Itemize

Support in-line editing using OpenParts or any other relevant protocol.
\layout Itemize

Extend the dynamic information to have optional parameter fields for the
 conversion commands in all export formats, and to have optional parameter
 fields for what is produced into all the different exported formats.
 At the moment, we are restricted to only one parameter string that is multiplex
ed across these many applications.
 Also, a change like this would allow us to get rid of the strange primary
 target format restrictions.
\layout Itemize

Extend the framework to provide more intelligent customization options in
 addition to the rather simplistic raw parameter strings.
 With a suitable scripting language, it would be possible to implement user
 friendly versions of many customizable insets that supports a wide range
 of formats, LaTeX packages, editors, etc.
\the_end