#LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
-\lyxformat 263
+\lyxformat 276
\begin_document
\begin_header
\textclass book
\paperpagestyle headings
\tracking_changes false
\output_changes false
-\author "usti"
-\author "Jean-Marc Lasgouttes"
+\author ""
+\author ""
+\author ""
+\author ""
\end_header
\begin_body
\end_layout
\begin_layout Section
-Converters, Formats, Viewers, Editors and Copiers
+\begin_inset LatexCommand label
+name "sec:converters-etc"
+
+\end_inset
+
+Converters, Formats, and Copiers
\end_layout
\begin_layout Standard
LyX has a powerful mechanism to convert to and from any file format using
external programs.
- Define a pair of formats, e.g.
-\family typewriter
-LaTeX
-\family default
- and
-\family typewriter
-PDF
-\family default
-.
- Now define a converter from one format to the other.
- In our example, two possible mechanisms exist.
\end_layout
-\begin_layout Enumerate
-A direct conversion, from LaTeX to PDF using pdflatex
+\begin_layout Subsection
+Formats
\end_layout
-\begin_layout Enumerate
-A more convoluted route using intermediate formats and converters: LaTeX
- to DVI (using latex) to PostScript® (using dvips) to PDF (using ps2pdf).
+\begin_layout Standard
+The first step is to define your file formats, e.g.
+ PDF, if they are not already defined.
+ To do so, open the
+\family sans
+\bar under
+T
+\bar default
+ools\SpecialChar \menuseparator
+
+\bar under
+P
+\bar default
+references:Converters
+\family default
+ dialog.
+ Enter a new format name; a new GUI name (used in, e.g., the View and Export
+ menus); and a file extension.
+ These are required.
+
\end_layout
\begin_layout Standard
-LyX will always choose the shortest possible route, so you must specify
- two different Format names for
+There are also two flags that can be set using the checkboxes in the dialog.
+ The
\family typewriter
-.pdf
+document
\family default
- files to be able to use either.
- Both are included by default in the
+ flag tells LyX that a format is suitable for document export.
+ If this flag is set for a format, and if a suitable conversion route exists,
+ then the format will appear in the
\family sans
-Preferences
+\bar under
+F
+\bar default
+ile\SpecialChar \menuseparator
+
+\bar under
+E
+\bar default
+xport
\family default
- dialog.
- Have a look and then invent your own!
+ menu.
+ The format will also appear in the
+\family sans
+\bar under
+V
+\bar default
+iew
+\family default
+ menu if it has a viewer associated with it.
+ (See below.) Pure image formats (e.g.\InsetSpace ~
+
+\family typewriter
+png
+\family default
+) should not have this flag set; formats that can both represent vector
+ graphics and documents (e.g.\InsetSpace ~
+
+\family typewriter
+pdf
+\family default
+) should have it set.
+\end_layout
+
+\begin_layout Standard
+The
+\family typewriter
+vector
+\family default
+ flag tells LyX whether a format can contain vector graphics.
+ This information is used to determine the target format of included graphics
+ for
+\family typewriter
+pdflatex
+\family default
+ export.
+ Included graphics may need to be converted to either
+\family typewriter
+pdf
+\family default
+,
+\family typewriter
+png
+\family default
+ or
+\family typewriter
+jpg
+\family default
+, since
+\family typewriter
+pdflatex
+\family default
+ cannot handle other image formats.
+ If an included graphic is not already in
+\family typewriter
+pdf
+\family default
+,
+\family typewriter
+png
+\family default
+ or
+\family typewriter
+jpg
+\family default
+ format, it is converted to
+\family typewriter
+pdf
+\family default
+ if the
+\family typewriter
+vector
+\family default
+ flag of the format is set, and otherwise to
+\family typewriter
+png
+\family default
+.
\end_layout
\begin_layout Standard
-Moreover, each Format can have a Viewer associated with it.
+A Format can have a Viewer associated with it.
For example, you might want to use
\family typewriter
ghostview
\family default
- to examine PostScript® files, or
+ to look at PostScript® files, or
\family typewriter
xdvi
\family default
to preview the LaTeX output.
- You can alter the viewer to use (and what options to pass to it) via the
-
+ You can enter the program to use as a viewer (and what options to pass
+ to it) in the Viewer field.
+ You can also modify the viewer associated with a pre-defined format simply
+ by changing what you find in this field, clicking the
\family sans
-\bar under
-T
-\bar default
-ools\SpecialChar \menuseparator
+Modify
+\family default
+ button, and then (if you're sure you want to do this) clicking the
+\family sans
+Apply
+\family default
+ or
+\family sans
+Save
+\family default
+ button.
+\begin_inset Foot
+status collapsed
-\bar under
-P
-\bar default
-references:Conversion
+\begin_layout Standard
+Changes to the formats are kept in the
+\family typewriter
+preferences
\family default
- dialog.
+ file in you local LyX directory (for example,
+\family typewriter
+$HOME/.lyx/
+\family default
+).
+ If you want to restore the defaults, edit this file and delete the lines
+ in the Formats and Converters sections.
+\end_layout
+
+\end_inset
+
For example, to change the
\family typewriter
dvi
\end_layout
\begin_layout Standard
-If the operating system has a default viewer associated to a format it is
- used instead of the one you can define via the
-\family sans
-\bar under
-T
-\bar default
-ools\SpecialChar \menuseparator
-
-\bar under
-P
-\bar default
-references:Conversion
-\family default
- dialog.
- This does currently only work in the Windows® and Mac OS X ports of LyX,
- but it is planned to implement this feature on all other ports that can
- support it, too.
+If the operating system has a default viewer associated to a format, this
+ viewer is used instead of the one defined here in the Windows® and OS X
+ versions of LyX.
+ (It is planned to implement this feature on other platforms.)
\end_layout
\begin_layout Standard
Editors are like viewers: Each Format can have an Editor associated to it,
- and they can be altered via the
+ entered in the Editor field, and the editor associated with a format can
+ be altered via the
\family sans
\bar under
T
\bar under
P
\bar default
-references:Conversion
+references:Converters
\family default
dialog.
- LyX uses them whenever an included file
+ LyX will launch the associated editor whenever an included file
\begin_inset Foot
status collapsed
needs to be edited.
\end_layout
+\begin_layout Subsection
+Copiers
+\end_layout
+
\begin_layout Standard
-Finally, each Format can have a Copier associated to it.
- Since all conversions from one Format to another take place in a temporary
+Each Format can have a Copier associated with it.
+ These are defined in the
+\family sans
+\bar under
+T
+\bar default
+ools\SpecialChar \menuseparator
+
+\bar under
+P
+\bar default
+references:Copiers
+\family default
+ dialog.
+ Since all conversions from one Format to another take place in LyX's temporary
directory, it is sometimes necessary to modify a file before copying it
- to the temporary directory
+ to the temporary directory in order that the conversion may be performed.
\begin_inset Foot
status collapsed
\begin_layout Standard
-For example, the file may reference other files with relative filenames,
- which will become invalid in the temporary directory
+For example, the file may refer to other files---images, for example---using
+ relative filenames, and these may become invalid when the file is copied
+ to the temporary directory.
\end_layout
\end_inset
-.
This is done by the Copier: It copies a file to (or from) the temporary
directory and may modify it in the process.
+
\end_layout
\begin_layout Standard
-Sometimes LyX needs to know a bit more about the properties of a format.
- These bits can be specified with flags.
- Currently there are two of them:
-\end_layout
-
-\begin_layout Standard
-The
-\family typewriter
-document
-\family default
- flag tells LyX that a format is suitable for document export.
- If this flag is set for a format, and if a suitable conversion route exists,
- then the format will appear in the
-\family sans
-\bar under
-F
-\bar default
-ile\SpecialChar \menuseparator
+Copiers may also be used for other purposes.
+ For example, if appropriate converters are found, LyX will automatically
+ install copiers for the html and wordhtml formats.
+ When these formats are exported, the copier sees to it that not just the
+ main HTML file but various associated files (style files, images, and the
+ like) are also copied, and all these files are written to a subdirectory
+ of the directory in which the original LyX file was found.
+ The copier may of course be customized.
+ The optional -e argument takes a comma-separated list of extensions to
+ be copied; if it is omitted, all files will be copied.
+ The -t argument determines the extension added to the generated directory.
+ By default, it is
+\begin_inset Quotes eld
+\end_inset
-\bar under
-E
-\bar default
-xport
-\family default
- menu.
- The format will also appear in the
-\family sans
-\bar under
-V
-\bar default
-iew
-\family default
- menu if it has a viewer associated to it.
- Pure image formats (e.g.\InsetSpace ~
+LyXconv
+\begin_inset Quotes erd
+\end_inset
+, so HTML generated from
\family typewriter
-png
+/path/to/filename.lyx
\family default
-) do not have this flag set, formats that can both represent images and
- documents (e.g.\InsetSpace ~
-
+ will end up in
\family typewriter
-pdf
+/path/to/filename.html.LyXconv
\family default
-) do have it set.
+.
+
\end_layout
\begin_layout Standard
-The
-\family typewriter
-vector
-\family default
- flag tells LyX whether a format can contain vector graphics.
- This information is used to determine the target format of included graphics
- for
-\family typewriter
-pdflatex
-\family default
- export.
- Included graphics may need to be converted to either
-\family typewriter
-pdf
-\family default
-,
-\family typewriter
-png
-\family default
- or
-\family typewriter
-jpg
-\family default
-, since
-\family typewriter
-pdflatex
-\family default
- cannot handle other image formats.
- If an included graphic is not already in
+The definitions of the copiers may use four variables:
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$s The LyX system directory (e.g.,
\family typewriter
-pdf
+/usr/share/lyx
\family default
-,
+).
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$i The input file
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$o The output file
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$l The `LaTeX name'
+\end_layout
+
+\begin_layout Standard
+The latter is to be given in a form suitable for inclusion in a LaTeX
\family typewriter
-png
+
+\backslash
+include
\family default
- or
+ command and is relevant only when exporting files suitable for such inclusion.
+\end_layout
+
+\begin_layout Subsection
+Converters
+\end_layout
+
+\begin_layout Standard
+To define a converter from one format to another---e.g., LaTeX to PDF---select
+ the Converters panel.
+ Choose the `From' and `To' formats, and then enter the program to be used
+ in the conversion in the Converter field.
+
+\end_layout
+
+\begin_layout Standard
+You do not have to define converters between all the Formats between which
+ you want to convert.
+ For example, you will note that there is no `LyX to PostScript®' converter,
+ but LyX will export PostScript®.
+ It does so by first creating a LaTeX file (no converter needs to be defined
+ for this) which it then converts to DVI using the `LaTeX to DVI' converter,
+ and then it converts the resulting DVI file to PostScript®.
+ LyX finds such `chains' of converters automatically, and it will always
+ choose the shortest chain possible.
+ You can, though, still define multiple conversion methods between file
+ formats.
+ For example, the standard LyX configuration provides three ways to convert
+ LaTeX to PDF: Directly, using pdflatex; via (DVI and) PostScript®, using
+ ps2pdf; or via DVI, using dvipdfm.
+ To define such alternate chains, you must define multiple target `file
+ formats'.
+ In the standard configuration, for example, formats named `pdf', `pdf2',
+ and `pdf3' are defined, all of which share the extension `pdf'.
+
+\end_layout
+
+\begin_layout Standard
+Several variables can be used in the definition of converters:
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$s The LyX system directory (e.g.,
\family typewriter
-jpg
+/usr/share/lyx
\family default
- format it is converted to
-\family typewriter
-pdf
+).
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$i The input file
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$o The output file
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$b The base filename of the input file
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+$$p The path to the input file
+\end_layout
+
+\begin_layout Standard
+In the `Extra Flag' field you can enter as many of the following flags as
+ you wish, separated by commas:
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+latex This converter runs some form of LaTeX.
+ (This will make LyX's LaTeX error logs available.)
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+needaux Needs the LaTeX .aux file for the conversion.
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+xml Output is XML.
+\end_layout
+
+\begin_layout Standard
+The following three variables are not really flags at all but take an argument
+ in the
+\family sans
+key\InsetSpace ~
+= value
\family default
- if the
+ format.
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+parselog If set, the converter's standard error will be redirected to a
+ file
\family typewriter
-vector
+infile.out
\family default
- flag of the format is set, and otherwise to
+, and the script given as argument will be run as:
\family typewriter
-png
+script <infile.out >infile.log
\family default
.
+ The argument may contain $$s.
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+resultdir The name of the directory in which the
+\emph on
+converter
+\emph default
+ will dump the generated files.
+ LyX will not create this directory, and it does not copy anything into
+ it, though it will copy this directory to the destination.
+ The argument may contain $$b, which will be replaced by the basename of
+ the input and output files, respectively, when the directory is copied.
+\newline
+Note
+ that resultdir and usetempdir make no sense together.
+ The latter will be ignored if the former is given.
+\end_layout
+
+\begin_layout List
+\labelwidthstring 00.00.0000
+resultfile Determines the output filename and may, again, contain $$b.
+ Sensible only with resultdir, and optional even then; if not given, it
+ defaults to `index'.
+
+\end_layout
+
+\begin_layout Standard
+None of these last three are presently used in any of the converters that
+ are installed with LyX.
+ But see section
+\begin_inset LatexCommand ref
+reference "sub:LyX-and-Literate"
+
+\end_inset
+
+ of the Extended Features guide for some examples of how you might use parselog.
\end_layout
\begin_layout Section
\begin_layout Standard
This indicates that your text class uses the foo.sty package.
- Finally, it is also possible to declare classes for SGML and DocBook code.
+ Finally, it is also possible to declare classes for DocBook code.
Typical declarations will look like
\end_layout
\size small
#
\backslash
-DeclareSGMLClass{SGML (LinuxDoc)}
-\end_layout
-
-\begin_layout Standard
-or
-\end_layout
-
-\begin_layout LyX-Code
-#% Do not delete the line below; configure depends on this
-\end_layout
-
-\begin_layout LyX-Code
-#
-\backslash
DeclareDocBookClass[article]{SGML (DocBook article)}
\end_layout
\family typewriter
\series medium
-ProvidesAmsmath
-\family default
-\series default
- [
-\family typewriter
-\emph on
-0
-\emph default
-, 1
-\family default
-] Whether the class already loads the
-\family typewriter
-amsmath
-\family default
- package.
- This is the case of the
-\family typewriter
-amsart
-\family default
- and
-\family typewriter
-amsbook
-\family default
- document classes.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-\series medium
-ProvidesMakeidx
+Provides
\family default
\series default
- [
+[
\family typewriter
-\emph on
-0
-\emph default
-, 1
-\family default
-] Whether the class already provides the functionality of the
-\family typewriter
-makeidx
-\family default
- package.
- This is the case of the
-\family typewriter
-amsart
-\family default
- and
-\family typewriter
-amsbook
-\family default
- document classes.
-\end_layout
-
-\begin_layout Description
-
-\family typewriter
-\series medium
-ProvidesUrl
+string
\family default
-\series default
- [
+] [
\family typewriter
\emph on
0
\emph default
, 1
\family default
-] Whether the class already provides the functionality of the
+] Whether the class already provides the feature
\family typewriter
-url
-\family default
- package.
- This is the case of the
-\family typewriter
-AASTeX
+ string
\family default
- document class.
+.
+ A feature is in general the name of a package (amsmath, makeidx, \SpecialChar \ldots{}
+) or a
+ macro (url, boldsymbol,\SpecialChar \ldots{}
+); the complete list of supported features is unfortunat
+ely not documented.
\end_layout
\begin_layout Description
\family typewriter
string=""
\family default
-] If non-empty, this is used inside the appendix instead of
+] This is used inside the appendix instead of
\family typewriter
LabelString
\family default
.
-
+ Note that every
+\family typewriter
+LabelString
+\family default
+ statement resets
+\family typewriter
+\series medium
+LabelStringAppendix
+\family default
+\series default
+ too
+\family typewriter
+\series medium
+.
\end_layout
\begin_layout Description
FormatEnd
\end_layout
-\begin_layout LyX-Code
-Format LinuxDoc
-\end_layout
-
\begin_layout LyX-Code
Product "[XFig: $$FName]"
\end_layout
\family typewriter
\series medium
Format\InsetSpace ~
-LaTeX|PDFLaTeX|PlainText|DocBook|LinuxDoc
+LaTeX|PDFLaTeX|PlainText|DocBook
\family default
\series default
The primary document file format that this format definition is for.
Format
\family default
section for all formats.
- Use a dummy text when no representation is available (see the LinuxDoc
- format in the example above).
+ Use a dummy text when no representation is available.
Then you can at least see a reference to the external material in the exported
document.
\end_layout
projects / lyx.git / blobdiff