anne/lyx_mirror
1
0
Fork 0
mirror of https://git.lyx.org/repos/lyx.git synced 2024-11-22 01:59:02 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

remove obsolete file

Browse Source 
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@4064 a592a061-630c-0410-9148-cb99ea01b6c8
This commit is contained in:
Jean-Marc Lasgouttes 2002-04-24 22:56:16 +00:00
parent f79c6a1991
commit 1be9ab2b0c
2 changed files with 5 additions and 558 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

5
lib/ChangeLog
View File

@ -1,3 +1,8 @@
2002-04-25 Jean-Marc Lasgouttes <lasgouttes@freesurf.fr>
* doc/ExternalMaterial.lyx: remove, since it has been included in
Customization.lyx
2002-04-24 Jean-Marc Lasgouttes <lasgouttes@freesurf.fr>
* Makefile.am: do not set M4 explicitely

558
lib/doc/ExternalMaterial.lyx
View File

@ -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