From 1be9ab2b0c53a17b2689fe366bcf63f27019ce14 Mon Sep 17 00:00:00 2001 From: Jean-Marc Lasgouttes Date: Wed, 24 Apr 2002 22:56:16 +0000 Subject: [PATCH] remove obsolete file git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@4064 a592a061-630c-0410-9148-cb99ea01b6c8 --- lib/ChangeLog | 5 + lib/doc/ExternalMaterial.lyx | 558 ----------------------------------- 2 files changed, 5 insertions(+), 558 deletions(-) delete mode 100644 lib/doc/ExternalMaterial.lyx diff --git a/lib/ChangeLog b/lib/ChangeLog index 9ef5a8d6d6..4f1e7b2fae 100644 --- a/lib/ChangeLog +++ b/lib/ChangeLog @@ -1,3 +1,8 @@ +2002-04-25 Jean-Marc Lasgouttes + + * doc/ExternalMaterial.lyx: remove, since it has been included in + Customization.lyx + 2002-04-24 Jean-Marc Lasgouttes * Makefile.am: do not set M4 explicitely diff --git a/lib/doc/ExternalMaterial.lyx b/lib/doc/ExternalMaterial.lyx deleted file mode 100644 index 406b481dc6..0000000000 --- a/lib/doc/ExternalMaterial.lyx +++ /dev/null @@ -1,558 +0,0 @@ -#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