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

Update documentation regarding converters, etc.

Browse Source 
git-svn-id: svn://svn.lyx.org/lyx/lyx-devel/trunk@18491 a592a061-630c-0410-9148-cb99ea01b6c8
This commit is contained in:
Richard Heck 2007-05-24 16:42:40 +00:00
parent 93baf8eb9b
commit 9879a1a185
2 changed files with 522 additions and 358 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

469
lib/doc/Customization.lyx
View File

@ -1,5 +1,5 @@
#LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
\lyxformat 263
\lyxformat 271
\begin_document
\begin_header
\textclass book
@ -39,6 +39,7 @@
\paperpagestyle headings
\tracking_changes false
\output_changes false
\author "Richard Heck"
\author "Jean-Marc Lasgouttes"
\author "usti"
\end_header
@ -1698,63 +1699,23 @@ s.
\end_layout
\begin_layout Section
Converters, Formats, Viewers, Editors and Copiers
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
\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 Subsection
Formats
\end_layout
\begin_layout Standard
LyX will always choose the shortest possible route, so you must specify
two different Format names for
\family typewriter
.pdf
\family default
files to be able to use either.
Both are included by default in the
\family sans
Preferences
\family default
dialog.
Have a look and then invent your own!
\end_layout
\begin_layout Standard
Moreover, each 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
\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
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
@ -1764,111 +1725,17 @@ ools\SpecialChar \menuseparator
\bar under
P
\bar default
references:Conversion
references:Converters
\family default
dialog.
For example, to change the
\family typewriter
dvi
\family default
viewer, select the
\family typewriter
DVI
\family default
format in the dialog, change the viewer to be
\family typewriter
kdvi
\family default
(or whatever), and hit
\family sans
\bar under
M
\bar default
odify
\family default
.
\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.
\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
\family sans
\bar under
T
\bar default
ools\SpecialChar \menuseparator
\bar under
P
\bar default
references:Conversion
\family default
dialog.
LyX uses them whenever an included file
\begin_inset Foot
status collapsed
\begin_layout Standard
This can be an included
\family typewriter
.tex
\family default
file, a verbatim included text file, external material or an included graphics
file.
\end_layout
\end_inset
needs to be edited.
\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
directory, it is sometimes necessary to modify a file before copying it
to the temporary directory
\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
\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:
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
There are also two flags that can be set using the checkboxes in the dialog.
The
\family typewriter
document
@ -1895,19 +1762,19 @@ V
\bar default
iew
\family default
menu if it has a viewer associated to it.
Pure image formats (e.g.\InsetSpace ~
menu if it has a viewer associated with it.
(See below.) Pure image formats (e.g.\InsetSpace ~
\family typewriter
png
\family default
) do not have this flag set, formats that can both represent images and
documents (e.g.\InsetSpace ~
) should not have this flag set; formats that can both represent vector
graphics and documents (e.g.\InsetSpace ~
\family typewriter
pdf
\family default
) do have it set.
) should have it set.
\end_layout
\begin_layout Standard
@ -1951,7 +1818,7 @@ png
\family typewriter
jpg
\family default
format it is converted to
format, it is converted to
\family typewriter
pdf
\family default
@ -1966,6 +1833,302 @@ png
.
\end_layout
\begin_layout Standard
A Format can have a Viewer associated with it.
For example, you might want to use
\family typewriter
ghostview
\family default
to look at PostScript® files, or
\family typewriter
xdvi
\family default
to preview the LaTeX output.
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
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
\begin_layout Standard
Changes to the formats are kept in the
\family typewriter
preferences
\family default
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
\family default
viewer, select the
\family typewriter
DVI
\family default
format in the dialog, change the viewer to be
\family typewriter
kdvi
\family default
(or whatever), and hit
\family sans
\bar under
M
\bar default
odify
\family default
.
\end_layout
\begin_layout Standard
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,
entered in the Editor field, and the editor associated with a format can
be altered via the
\family sans
\bar under
T
\bar default
ools\SpecialChar \menuseparator
\bar under
P
\bar default
references:Converters
\family default
dialog.
LyX will launch the associated editor whenever an included file
\begin_inset Foot
status collapsed
\begin_layout Standard
This can be an included
\family typewriter
.tex
\family default
file, a verbatim included text file, external material or an included graphics
file.
\end_layout
\end_inset
needs to be edited.
\end_layout
\begin_layout Subsection
Copiers
\end_layout
\begin_layout Standard
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 a temporary
directory, it is sometimes necessary to modify a file before copying it
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 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 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
/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
$$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
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
infile.out
\family default
, and the script given as argument will be run as:
\family typewriter
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
BibTeX and makeindex
\end_layout

101
lib/doc/Extended.lyx
View File

@ -1,5 +1,5 @@
#LyX 1.5.0svn created this file. For more info see http://www.lyx.org/
\lyxformat 256
\lyxformat 271
\begin_document
\begin_header
\textclass book
@ -36,7 +36,8 @@
\papersides 2
\paperpagestyle headings
\tracking_changes false
\output_changes true
\output_changes false
\author "Richard Heck"
\author "usti"
\end_header
@ -163,12 +164,8 @@ In this document, many sections are independent articles contributed by
\begin_layout Standard
Since all the topics in this manual depend heavily on LyX's interaction
with LaTeX, this first chapter covers
\emph on
\emph default
the inner workings of LyX and how to direct LyX to generate exactly the
LaTeX code you want.
with LaTeX, this first chapter covers the inner workings of LyX and how
to direct LyX to generate exactly the LaTeX code you want.
It is obviously for more seasoned LyX users.
\end_layout
@ -932,11 +929,7 @@ Customization Manual
declare the usage of packages.
LaTeX packages provide special commands, which are only available within
a document when the package has been declared in the preamble.
For example, the
\family typewriter
\family default
package
For example, the package
\family typewriter
indentfirst
\family default
@ -1455,7 +1448,6 @@ open
\begin_layout Standard
Some folks also like to look at the log file directly, accessible from
\family sans
\bar under
D
\bar default
@ -2548,12 +2540,14 @@ status collapsed
\noun off
\color none
In the
\family sans
\family default
\series default
\shape default
\size default
\emph default
\bar default
\family sans
\size default
\noun default
Outputs\SpecialChar \menuseparator
LaT\SpecialChar \textcompwordmark{}
@ -2567,12 +2561,14 @@ eX
\noun off
section of the preferences dialog, however, you can customize the index
command, if you prefer an alternative program like
\family typewriter
\family default
\series default
\shape default
\size default
\emph default
\bar default
\family typewriter
\size default
\noun default
xindy
\family roman
@ -2674,9 +2670,7 @@ Glossaries
\begin_layout Standard
by
\noun on
Özgür U\i \~{g}
ra\i \c{s}
Baran
Özgür Ug̃raş Baran
\end_layout
\begin_layout Standard
@ -3150,8 +3144,6 @@ output
\family default
checkbox typesets a mark to unambiguously define the presence of a space.
\emph on
\end_layout
\begin_layout Subsection
@ -3854,10 +3846,6 @@ How to use it
\begin_layout Standard
Select which bullet depth you want to change then select the bullet shape
and size.
\family sans
\family default
Any changes will not be visible in LyX, but are visible when viewing the
document using xdvi or ghostview.
\end_layout
@ -4436,15 +4424,7 @@ target "http://www.edpsciences.fr/aa/"
\end_inset
)
\emph on
\emph default
using
\emph on
\emph default
Version 5.01 of the document class
) using Version 5.01 of the document class
\family typewriter
aa.cls
\family default
@ -4934,11 +4914,7 @@ Settings.
\end_layout
\begin_layout Standard
There is
\family sans
\family default
only one special thing: the figures with caption besides the figure.
There is only one special thing: the figures with caption besides the figure.
To create such a figure, you have to do the following:
\end_layout
@ -4958,7 +4934,6 @@ Figure
\family default
, then right click in the figure and select
\family sans
\bar under
S
\bar default
@ -5035,6 +5010,8 @@ Position the cursor behind the caption text, switch to LaTeX mode and insert
\family sans
M-c\InsetSpace ~
t
\family default
\family typewriter
}
\family default
@ -5169,6 +5146,9 @@ F
\bar default
ile\SpecialChar \menuseparator
New from
\family default
\family sans
\bar under
T
\bar default
@ -6323,6 +6303,9 @@ F
\bar default
ile\SpecialChar \menuseparator
New from
\family default
\family sans
\bar under
T
\bar default
@ -6899,6 +6882,9 @@ The easiest way to write a paper is to start with the Kluwer template file.
\family sans
File\SpecialChar \menuseparator
New from
\family default
\family sans
\bar under
T
\bar default
@ -7300,6 +7286,7 @@ There is a big difference between the bold sans serif old cm fonts and new
\family typewriter
cmsd.sty by
\family default
\shape smallcaps
Walter Schmidt
\shape default
@ -7614,8 +7601,8 @@ Captionabove
\family sans
Captionbelow
\family default
are special captions which respect the different space settings needed for
captions placed above or below an element (if you follow strict typographic
are special captions which respect the different space settings needed
for captions placed above or below an element (if you follow strict typographic
rules, you might want to place table captions always above the table).
You can also use the class option
\family typewriter
@ -15328,10 +15315,6 @@ S
ettings
\family default
dialog.
\family sans
\family default
Then you will find that there are fewer paragraph environments than for
most other classes.
You can see them on the pull down box on the left of the tool bar.
@ -15382,7 +15365,6 @@ You can print and save these documents in the normal way.
the basic sgml tags.
Use
\family sans
\bar under
F
\bar default
@ -15464,6 +15446,8 @@ Here is a list of all the tags you will find listed on the layout bar in
\family sans
Standard:
\family default
\family roman
works as described in [cross reference]
\end_layout
@ -15515,8 +15499,13 @@ User's Guide
\family sans
Itemize:
\family default
\family roman
Again much the same as in the other classes: see the
\family default
\family roman
\emph on
User's Guide
\emph default
@ -15551,6 +15540,8 @@ As usual.
\family sans
Code: similar to the LyX-Code
\family default
\family roman
environment
\end_layout
@ -15743,6 +15734,8 @@ insert some description between the second and third blocks.
\family sans
URL:
\family default
\family roman
both the HTML tag and the description will appear in the document
\end_layout
@ -15752,6 +15745,8 @@ URL:
\family sans
HTML\InsetSpace ~
URL:
\family default
\family roman
only the description appears in the printed version
\end_layout
@ -15886,6 +15881,8 @@ E
xport\SpecialChar \menuseparator
as\InsetSpace ~
LinuxDoc
\family default
\family roman
option.
\end_layout
@ -17419,6 +17416,11 @@ Starting from there you can reach many other interesting links and even
\end_layout
\begin_layout Subsection
\begin_inset LatexCommand label
name "sub:LyX-and-Literate"
\end_inset
LyX and Literate Programming
\end_layout
@ -18204,7 +18206,6 @@ When debugging code with ddd/gdb, it is possible to invoke a text editor
It happens that you can define the editor command line invocation in ddd
by accessing the
\family sans
\bar under
E
\bar default