1 #LyX 1.6.0beta4 created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that the User's Guide prints
10 % out as advertised. If you mess with this preamble,
11 % parts of the User's Guide may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
49 InsetLayout CharStyle:MenuItem
58 \newcommand*{\menuitem}[1]{{\sffamily #1}}
66 \font_typewriter default
67 \font_default_family default
77 \pdf_title "LyX Configuration Manual"
78 \pdf_author "LyX Team"
79 \pdf_subject "LyX-documentation Customization"
80 \pdf_keywords "LyX, documentation, customization"
82 \pdf_bookmarksnumbered true
83 \pdf_bookmarksopen true
84 \pdf_bookmarksopenlevel 1
89 \pdf_pagebackref false
90 \pdf_pdfusetitle false
91 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
98 \paperorientation portrait
105 \paragraph_separation indent
107 \quotes_language english
110 \paperpagestyle headings
111 \tracking_changes false
112 \output_changes false
120 Customizing LyX: Features for the Advanced User
128 \begin_layout Plain Layout
130 If you have comments or error corrections, please send them to the LyX Documenta
132 \begin_inset CommandInset href
134 target "lyx-docs@lists.lyx.org"
147 \begin_layout Standard
148 \begin_inset CommandInset toc
149 LatexCommand tableofcontents
156 \begin_layout Chapter
160 \begin_layout Standard
161 This manual covers the customization features present in LyX.
162 In it, we discuss issues like keyboard shortcuts, screen previewing options,
163 printer options, sending commands to LyX via the LyX Server, internationalizati
164 on, installing new LaTeX classes and LyX layouts, etc.
165 We can't possibly hope to touch on everything you can change---our developers
166 add new features faster than we can document them---but we will explain
167 the most common customizations and hopefully point you in the right direction
168 for some of the more obscure ones.
171 \begin_layout Standard
172 \begin_inset Branch OutDated
175 \begin_layout Standard
176 Information from previous versions of this document that now seems to be
177 outdated is contained in the OutDated branch of this document.
178 By default, this information will not appear in the LaTeX output.
186 \begin_layout Chapter
187 LyX configuration files
190 \begin_layout Standard
191 \begin_inset CommandInset label
197 This chapter aims to help you to find your way through the LyX configuration
199 Before continuing to read this chapter, you should find out where your
200 LyX library and user directories are by using
201 \begin_inset Flex CharStyle:MenuItem
204 \begin_layout Plain Layout
209 elp\SpecialChar \menuseparator
222 The library directory is the place where LyX places its system-wide configurati
223 on files; the user directory is where you can place your modified versions.
224 We will call the former
225 \begin_inset Flex CharStyle:Code
228 \begin_layout Plain Layout
235 \begin_inset Flex CharStyle:MenuItem
238 \begin_layout Plain Layout
244 in the remainder of this document.
248 \begin_layout Section
250 \begin_inset Flex CharStyle:Code
253 \begin_layout Plain Layout
262 \begin_layout Standard
263 \begin_inset Flex CharStyle:Code
266 \begin_layout Plain Layout
272 and its sub-directories contain a number of files and that can be used
273 to customise LyX's behaviour.
274 You can change many of these files from within LyX itself through the
275 \begin_inset Flex CharStyle:MenuItem
278 \begin_layout Plain Layout
283 ools\SpecialChar \menuseparator
294 Most customization that you will want to do in LyX is possible through
296 However, many other inner aspects of LyX can be customized by modifying
298 \begin_inset Flex CharStyle:Code
301 \begin_layout Plain Layout
308 These files fall in different categories, described in the following subsection
312 \begin_layout Subsection
313 Automatically generated files
316 \begin_layout Standard
317 The files, which are to be found in
318 \begin_inset Flex CharStyle:MenuItem
321 \begin_layout Plain Layout
327 , are generated when you configure LyX.
328 They contain various default values that are guessed by inspection.
329 In general, it is not a good idea to modify them, since they might be overwritt
333 \begin_layout Labeling
334 \labelwidthstring 00.00.0000
335 \begin_inset Flex CharStyle:Code
338 \begin_layout Plain Layout
344 contains defaults for various commands.
347 \begin_layout Labeling
348 \labelwidthstring 00.00.0000
349 \begin_inset Flex CharStyle:Code
352 \begin_layout Plain Layout
358 contains the list of packages that have been recognized by LyX.
359 It is currently unused by the LyX program itself, but the information extracted
360 , and more, is made available with
361 \begin_inset Flex CharStyle:MenuItem
364 \begin_layout Plain Layout
369 elp\SpecialChar \menuseparator
386 \begin_layout Labeling
387 \labelwidthstring 00.00.0000
388 \begin_inset Flex CharStyle:Code
391 \begin_layout Plain Layout
397 the list of text classes that have been found in your
398 \begin_inset Flex CharStyle:Code
401 \begin_layout Plain Layout
407 directories, along with the associated LaTeX document class and their descripti
411 \begin_layout Labeling
412 \labelwidthstring 00.00.0000
413 \begin_inset Flex CharStyle:Code
416 \begin_layout Plain Layout
422 the list of layout modules found in your
423 \begin_inset Flex CharStyle:Code
426 \begin_layout Plain Layout
435 \begin_layout Labeling
436 \labelwidthstring 00.00.0000
437 \begin_inset Flex CharStyle:Code
440 \begin_layout Plain Layout
446 lists of various sorts of LaTeX-related files found on your system
449 \begin_layout Labeling
450 \labelwidthstring 00.00.0000
451 \begin_inset Flex CharStyle:Code
454 \begin_layout Plain Layout
460 is automatically generated during configuration from the file
461 \begin_inset Flex CharStyle:Code
464 \begin_layout Plain Layout
471 It contains information on your LaTeX configuration.
474 \begin_layout Subsection
478 \begin_layout Standard
479 These directories are duplicated between
480 \begin_inset Flex CharStyle:Code
483 \begin_layout Plain Layout
490 \begin_inset Flex CharStyle:Code
493 \begin_layout Plain Layout
500 If a particular files exists in both places, the one in
501 \begin_inset Flex CharStyle:Code
504 \begin_layout Plain Layout
513 \begin_layout Labeling
514 \labelwidthstring 00.00.0000
515 \begin_inset Flex CharStyle:Code
518 \begin_layout Plain Layout
524 this directory contains files with the extension
525 \begin_inset Flex CharStyle:Code
528 \begin_layout Plain Layout
534 that define the keybindings used in LyX (see section
539 \begin_inset CommandInset ref
541 reference "sec:bindings"
546 If there exists an internationalized version of the bind file named
547 \begin_inset Flex CharStyle:Code
550 \begin_layout Plain Layout
556 , that will be used first.
562 \begin_inset CommandInset ref
564 reference "chap:i18n"
569 \begin_inset CommandInset ref
571 reference "sec:bindings"
578 \begin_layout Labeling
579 \labelwidthstring 00.00.0000
580 \begin_inset Flex CharStyle:Code
583 \begin_layout Plain Layout
589 contains graphics files that can be included in documents.
593 \begin_layout Labeling
594 \labelwidthstring 00.00.0000
595 \begin_inset Flex CharStyle:Code
598 \begin_layout Plain Layout
604 contains LyX documentation files (including the one you are currently reading).
606 \begin_inset Flex CharStyle:Code
609 \begin_layout Plain Layout
615 deserves special attention, as noted above.
616 If there exists an internationalized version of the help-document with
618 \begin_inset Flex CharStyle:Code
621 \begin_layout Plain Layout
627 prepended to the name, that will be used first.
633 \begin_inset CommandInset ref
635 reference "chap:i18n"
642 \begin_layout Labeling
643 \labelwidthstring 00.00.0000
644 \begin_inset Flex CharStyle:Code
647 \begin_layout Plain Layout
653 contains example files that explain how to use some features.
654 In the file browser, press the
655 \begin_inset Flex CharStyle:MenuItem
658 \begin_layout Plain Layout
667 \begin_layout Labeling
668 \labelwidthstring 00.00.0000
669 \begin_inset Flex CharStyle:Code
672 \begin_layout Plain Layout
678 contains image files that are used by the
679 \begin_inset Flex CharStyle:MenuItem
682 \begin_layout Plain Layout
689 In addition, it also contains the individual icons used in the toolbar
690 and the banners that can be shown when LyX is launched.
693 \begin_layout Labeling
694 \labelwidthstring 00.00.0000
695 \begin_inset Flex CharStyle:Code
698 \begin_layout Plain Layout
704 contains keyboard keymapping files.
710 \begin_inset CommandInset ref
712 reference "sec:keymap"
719 \begin_layout Labeling
720 \labelwidthstring 00.00.0000
721 \begin_inset Flex CharStyle:Code
724 \begin_layout Plain Layout
730 contains the text class and module files described in Chapter
735 \begin_inset CommandInset ref
737 reference "chap:textclass"
744 \begin_layout Labeling
745 \labelwidthstring 00.00.0000
746 \begin_inset Flex CharStyle:Code
749 \begin_layout Plain Layout
756 \begin_inset Flex CharStyle:Code
759 \begin_layout Plain Layout
765 Python scripts used to convert between LyX versions.
766 These can be run from the command line if, say, you want to batch-convert
770 \begin_layout Labeling
771 \labelwidthstring 00.00.0000
772 \begin_inset Flex CharStyle:Code
775 \begin_layout Plain Layout
781 contains some files that demonstrate the capabilities of the
782 \begin_inset Flex CharStyle:MenuItem
785 \begin_layout Plain Layout
796 Also contains some scripts used by LyX itself.
799 \begin_layout Labeling
800 \labelwidthstring 00.00.0000
801 \begin_inset Flex CharStyle:Code
804 \begin_layout Plain Layout
810 contains the standard LyX template files described in Chapter
815 \begin_inset CommandInset ref
817 reference "sec:templates"
824 \begin_layout Labeling
825 \labelwidthstring 00.00.0000
826 \begin_inset Flex CharStyle:Code
829 \begin_layout Plain Layout
835 contains files with the extension
836 \begin_inset Flex CharStyle:Code
839 \begin_layout Plain Layout
845 that define the user interface to LyX.
846 That is, the files define which items appear in which menus and the items
847 appearing on the toolbar.
849 \begin_inset CommandInset ref
858 \begin_layout Subsection
859 Files you don't want to modify
862 \begin_layout Standard
863 These files are used internally by LyX and you generally do not need to
864 modify them unless you are a developer.
867 \begin_layout Labeling
868 \labelwidthstring 00.00.0000
869 \begin_inset Flex CharStyle:Code
872 \begin_layout Plain Layout
878 this file contains the list of LyX developers.
879 The contents are displayed with the menu entry
880 \begin_inset Flex CharStyle:MenuItem
883 \begin_layout Plain Layout
888 elp\SpecialChar \menuseparator
901 \begin_layout Labeling
902 \labelwidthstring 00.00.0000
903 \begin_inset Flex CharStyle:Code
906 \begin_layout Plain Layout
912 this is a LaTeX script used during the configuration process.
916 \begin_layout Labeling
917 \labelwidthstring 00.00.0000
918 \begin_inset Flex CharStyle:Code
921 \begin_layout Plain Layout
927 this is the script that is used to re-configure LyX.
928 It creates configuration files in the directory it was run from.
931 \begin_layout Subsection
932 Other files needing a line or two...
935 \begin_layout Labeling
936 \labelwidthstring 00.00.0000
937 \begin_inset Flex CharStyle:Code
940 \begin_layout Plain Layout
946 this contains tables describing how different character encodings can be
950 \begin_layout Labeling
951 \labelwidthstring 00.00.0000
952 \begin_inset Flex CharStyle:Code
955 \begin_layout Plain Layout
961 this file contains the templates available to the new
962 \begin_inset Flex CharStyle:MenuItem
965 \begin_layout Plain Layout
978 \begin_layout Labeling
979 \labelwidthstring 00.00.0000
980 \begin_inset Flex CharStyle:Code
983 \begin_layout Plain Layout
989 this file contains a list of all the languages currently supported by LyX.
992 \begin_layout Section
993 Your local configuration directory
996 \begin_layout Standard
997 Even if you are using LyX as an unprivileged user, you might want to change
998 LyX configuration for your own use.
1000 \begin_inset Flex CharStyle:Code
1003 \begin_layout Plain Layout
1009 directory contains all your personal configuration files.
1010 This is the directory described as
1011 \begin_inset Quotes eld
1015 \begin_inset Quotes erd
1019 \begin_inset Flex CharStyle:MenuItem
1022 \begin_layout Plain Layout
1027 elp\SpecialChar \menuseparator
1029 \begin_inset space ~
1038 This directory is used as a mirror of
1039 \begin_inset Flex CharStyle:Code
1042 \begin_layout Plain Layout
1048 , which means that every file in
1049 \begin_inset Flex CharStyle:Code
1052 \begin_layout Plain Layout
1058 is a replacement for the corresponding file in
1059 \begin_inset Flex CharStyle:Code
1062 \begin_layout Plain Layout
1069 Any configuration file described in the above sections can be placed either
1070 in the system-wide directory, in which case it will affect all users, or
1071 in your local directory for your own use.
1074 \begin_layout Standard
1075 To make things clearer, let's provide a few examples:
1078 \begin_layout Itemize
1079 The preferences set in the
1080 \begin_inset Flex CharStyle:MenuItem
1083 \begin_layout Plain Layout
1088 ools\SpecialChar \menuseparator
1098 dialog are saved to a file
1099 \begin_inset Flex CharStyle:Code
1102 \begin_layout Plain Layout
1109 \begin_inset Flex CharStyle:Code
1112 \begin_layout Plain Layout
1121 \begin_layout Itemize
1122 When you reconfigure using
1123 \begin_inset Flex CharStyle:MenuItem
1126 \begin_layout Plain Layout
1131 ools\SpecialChar \menuseparator
1142 \begin_inset Flex CharStyle:Code
1145 \begin_layout Plain Layout
1151 script, and the resulting files are written in your local configuration
1153 This means that any additional text class file that you might have added
1155 \begin_inset Flex CharStyle:Code
1158 \begin_layout Plain Layout
1164 will be added to the list of classes in the
1165 \begin_inset Flex CharStyle:MenuItem
1168 \begin_layout Plain Layout
1173 ocument\SpecialChar \menuseparator
1186 \begin_layout Itemize
1187 If you get some updated documentation from LyX ftp site and cannot install
1188 it because you do not have sysadmin rights on your system, you can just
1190 \begin_inset Flex CharStyle:Code
1193 \begin_layout Plain Layout
1199 and the items in the
1200 \begin_inset Flex CharStyle:MenuItem
1203 \begin_layout Plain Layout
1213 menu will open them!
1216 \begin_layout Section
1217 Running LyX with multiple configurations
1220 \begin_layout Standard
1221 The configuration freedom of the local configuration directory may not suffice
1222 if you want to have more than one configuration at your disposal.
1223 For example, you may want to be use different key bindings or printer settings
1225 You can achieve this by having several such directories.
1226 You then specify which directory to use at run-time.
1229 \begin_layout Standard
1230 Invoking LyX with the command line switch
1231 \begin_inset Flex CharStyle:Code
1234 \begin_layout Plain Layout
1244 instructs the program to read the configuration from that directory, and
1245 not from the default directory.
1246 (You can determine the default directory by running LyX without the
1247 \begin_inset Flex CharStyle:Code
1250 \begin_layout Plain Layout
1256 switch.) If the specified directory does not exist, LyX offers to create
1257 it for you, just like it does for the default directory on the first time
1258 you run the program.
1259 You can modify the configuration options in this additional user directory
1260 exactly as you would for the default directory.
1261 These directories are completely independent (but read on).
1262 Note that setting the environment variable
1263 \begin_inset Flex CharStyle:Code
1266 \begin_layout Plain Layout
1272 to some value has exactly the same effect.
1275 \begin_layout Standard
1276 Having several configurations also requires more maintenance: if you want
1277 to add a new layout to
1278 \begin_inset Flex CharStyle:Code
1281 \begin_layout Plain Layout
1287 which you want available from all your configurations, you must add it
1288 to each directory separately.
1289 You can avoid this with the following trick: after LyX creates the additional
1290 directory, most of the subdirectories (see above) are empty.
1291 If you want the new configuration to mirror an existing one, replace the
1292 empty subdirectory with a symbolic link to the matching subdirectory in
1293 the existing configuration.
1295 \begin_inset Flex CharStyle:Code
1298 \begin_layout Plain Layout
1304 subirectory, however, since it contains a file written by the configuration
1305 script (also accessible through
1306 \begin_inset Flex CharStyle:MenuItem
1309 \begin_layout Plain Layout
1314 ools\SpecialChar \menuseparator
1324 ) which is configuration-specific.
1327 \begin_layout Chapter
1328 The Preferences dialog
1331 \begin_layout Section
1332 Using the dialog for the first time
1335 \begin_layout Standard
1337 \begin_inset Flex CharStyle:Code
1340 \begin_layout Plain Layout
1346 file will contain only changes that you have made to the default behaviour,
1347 some of which is hard-coded into LyX and some of which is contained in
1349 \begin_inset Flex CharStyle:Code
1352 \begin_layout Plain Layout
1353 LyXDir/lyxrc.defaults
1359 Note that in both files lines beginning with a
1360 \begin_inset Quotes eld
1364 \begin_inset Quotes erd
1367 are just comments and are not interpreted.
1368 However, only system administrators should edit
1369 \begin_inset Flex CharStyle:Code
1372 \begin_layout Plain Layout
1373 LyXDir/lyxrc.defaults
1379 Users should use the
1380 \begin_inset Flex CharStyle:MenuItem
1383 \begin_layout Plain Layout
1388 ools\SpecialChar \menuseparator
1398 dialog to create and modify their own
1399 \begin_inset Flex CharStyle:Code
1402 \begin_layout Plain Layout
1411 \begin_layout Standard
1413 \begin_inset Flex CharStyle:MenuItem
1416 \begin_layout Plain Layout
1421 ools\SpecialChar \menuseparator
1431 dialog will be largely self-explanatory.
1432 Most things in the dialog have associated `tool tips': hover your mouse
1433 pointer over something for more information.
1434 Before we highlight a few of the more important commands below, however,
1436 \begin_inset Flex CharStyle:MenuItem
1439 \begin_layout Plain Layout
1445 ing some of your changes (e.g., screen fonts) will have an instant effect.
1447 changing the bind file) will not.
1448 If nothing appears to have changed, just
1449 \begin_inset Flex CharStyle:MenuItem
1452 \begin_layout Plain Layout
1458 the changes and restart LyX.
1461 \begin_layout Section
1465 \begin_layout Subsection
1469 \begin_layout Standard
1470 The font used to display your documents on the LyX screen is very important,
1471 since you'll be reading all your documents with this font.
1472 Therefore it is important that the font be as readable and good-looking
1474 The LyX team tried to provide the best possible default font for you, but
1475 since systems can be so different, it's quite possible that the default
1476 fonts will be sub-optimal on your system.
1477 Fortunately, you can do something about this.
1478 Before we explain how, you should learn a bit more about fonts so that
1479 you are better prepared for choosing your fonts.
1480 There are trade-offs that are specific to your preferences and the capabilities
1484 \begin_layout Standard
1485 Notice that this section only deals with the fonts on the
1489 inside the LyX window.
1490 The fonts that appear on the
1498 are independent from these fonts, and are determined by the document class.
1503 to learn how to change the font of the printed version of your document.
1506 \begin_layout Standard
1507 Basically, screen fonts come in two different kinds: scalable outline fonts
1508 and non-scalable bitmap fonts.
1509 This distinction seems a bit arbitrary, since non-scalable fonts are actually
1510 scalable in most modern font renderers.
1511 The difference lies in the
1515 of the scaling and the
1520 The most important decision is thus whether you should use non-scalable
1521 bitmap fonts or scalable outline fonts.
1524 \begin_layout Standard
1525 The scalable fonts are built from
1529 of the single glyphs (i.e.
1530 characters) in the font.
1531 This means that each glyph is defined using mathematical curves that are
1532 well suited for scaling to any requested size.
1533 This mathematical definition is interpreted by the font renderer and turned
1534 into a small picture composed of pixels according to which size and glyph
1535 (or symbol) the programmer requests.
1536 This means that scalable fonts will look pretty good in most sizes.Since
1537 scalable fonts are defined in an abstract way, it can be hard to provide
1538 a good rendering at small sizes, where each pixel has to be very carefully
1539 computed to provide a good image.
1540 Technically it is possible to do this from the mathematical definition,
1541 but in order to keep the rendering reasonably fast, tradeoffs have to be
1542 made, and the result is that scalable fonts can be difficult to read at
1546 \begin_layout Standard
1547 Bitmap fonts on the other hand, are defined by bitmap graphics from the
1548 start, so they will look good at all the sizes they are meant for.
1549 However, they don't scale well, because in order to scale a glyph, each
1550 pixel is enlarged into several pixels.
1551 It is the same effect that happens if you try to enlarge a picture in an
1552 image manipulation program.
1553 In order to relieve this effect, bitmap fonts are typically provided in
1554 several fixed sizes typically from around 8 pixels high up to 34 pixels
1555 or so high in steps according to what is believed to be useful.
1556 The advantage of bitmap fonts is that no complicated computations are necessary
1557 to display each glyph, so bitmap fonts are thus faster displayed than scalable
1559 The disadvantage is that sizes that don't exists as fixed versions have
1560 to be scaled by doubling pixels, and thus look bad.
1563 \begin_layout Standard
1564 The net result of all this is that bitmap fonts are generally best for the
1565 small sizes, where they are available, while scalable fonts are generally
1566 best for large sizes.
1567 The logical conclusion would thus be to use bitmap fonts for the small
1568 sizes, and scalable fonts for the large sizes.
1569 Unfortunately, this is not a good idea, since bitmap fonts and scalable
1570 fonts are not designed to be used together, so the overall look of such
1571 a scheme would be bad.
1572 The best you can do is thus to try both schemes and decide for yourself
1576 \begin_layout Standard
1577 In the following, we will describe what to do if the text does not look
1579 We'll start with the most important parameters: DPI and font zoom.
1582 \begin_layout Subsubsection
1583 DPI setting and Font Zoom
1586 \begin_layout Standard
1587 LyX automatically tries to scale the fonts to look as close as the paper
1588 output size as possible, except for the so-called font zoom factor.
1591 \begin_layout Standard
1592 In order for this to work on all systems, it relies on the screen DPI (dots
1593 per inch) setting to be correct.
1594 The DPI setting for your system is autodetected by LyX using information
1595 provided by your system.
1596 You can check what LyX autodetects the DPI setting to, by running LyX as
1598 \begin_inset Flex CharStyle:Code
1601 \begin_layout Plain Layout
1610 \begin_layout Standard
1611 On many systems, this will not be correct, so you should check that it is
1613 On X11 systems, you can run
1614 \begin_inset Quotes eld
1618 \begin_inset Flex CharStyle:Code
1621 \begin_layout Plain Layout
1628 \begin_inset Quotes erd
1631 and write down what the DPI is for the resolution you use (this will be
1632 close to the value LyX detects).
1633 It is the number mentioned as
1634 \begin_inset Quotes eld
1638 \begin_inset Quotes erd
1642 Also write down the number of pixels you have in the width (the first number
1644 \begin_inset Quotes eld
1648 \begin_inset Quotes erd
1654 \begin_layout Standard
1655 Then get the good old ruler out of the closet, and measure the width of
1656 the visible screen-image on your monitor.
1657 Convert this measurement to inches if you used a centimeter ruler by dividing
1659 Now you can determine the correct DPI setting for your screen by dividing
1660 the number of pixels in the width by the width of the screen-image on the
1662 If this number is more than, say, 5 DPI from the detected value, you should
1663 either fix your system setup, or at least tell LyX that the DPI is different
1664 than the detected value.
1667 \begin_layout Standard
1668 If you can't fix system setup (which of course is best since other programs
1669 than LyX will benefit from this as well), you can tell LyX the correct
1671 \begin_inset Flex CharStyle:MenuItem
1674 \begin_layout Plain Layout
1683 \begin_layout Standard
1684 If the text is too small or too big for your taste, you should fiddle with
1685 the font zoom setting.
1686 This setting is used to scale the point size of the text.
1687 If your DPI setting is correct, and the font zoom setting is set to 100,
1688 this means that LyX will try to display the text exactly the same size
1689 as it will appear on the paper-output.
1690 If you set the zoom factor to 200, the text will try to be 2 times as big
1692 Of course, this will only happen if LyX can find a font that has the appropriat
1693 e size, which you can't count on.
1694 Since LyX is a WYSIWYM system anyways, this limitation isn't much of an
1698 \begin_layout Standard
1699 The default font zoom setting is 150, since a monitor is typically wider
1700 than a piece of paper, but you should try to fiddle with it through the
1702 \begin_inset Flex CharStyle:MenuItem
1705 \begin_layout Plain Layout
1707 \begin_inset space ~
1720 \begin_inset Flex CharStyle:MenuItem
1723 \begin_layout Plain Layout
1729 dialog to find a size that you like.
1730 When you've found a setting that seems to work nicely for you (tip: use
1732 \begin_inset Flex CharStyle:MenuItem
1735 \begin_layout Plain Layout
1745 button to keep the dialog open while you experiment), you can make this
1746 setting the default by using the
1747 \begin_inset Flex CharStyle:MenuItem
1750 \begin_layout Plain Layout
1763 \begin_layout Standard
1764 While it is often possible to find a suitable size for the text on the screen,
1765 this doesn't necessarily mean that the fonts are the best ones available
1767 In order to help you get the most out of your system, you can use the font
1768 definition commands to fine-tune the look of the text in greater detail
1772 \begin_layout Subsubsection
1773 Font definition commands
1776 \begin_layout Standard
1777 You can change LyX's screen fonts from within the
1778 \begin_inset Flex CharStyle:MenuItem
1781 \begin_layout Plain Layout
1788 The number of fonts that are available on different systems vary.
1792 \begin_layout Standard
1793 Before you go about scrapping a bitmap font because the larger sizes look
1795 \begin_inset Quotes eld
1799 \begin_inset Quotes erd
1802 , you should toggle the
1803 \begin_inset Flex CharStyle:Code
1806 \begin_layout Plain Layout
1813 This is only useful if you use bitmap fonts, because only these don't scale
1815 If you define this flag, LyX will only use the fixed font sizes that are
1816 available, and this guarantees that all bitmap fonts look good.
1817 However, the downside is that there will be a greater difference between
1818 the size of the fonts on screen and the size of fonts on paper because
1819 LyX will have to be satisfied with the closest available size, and not
1820 try to scale a size to fit.
1821 Also, you can risk that some logically different sizes, such as
1822 \begin_inset Flex CharStyle:MenuItem
1825 \begin_layout Plain Layout
1832 \begin_inset Flex CharStyle:MenuItem
1835 \begin_layout Plain Layout
1841 , will be mapped to the same screen font, making it hard for you to see
1842 the difference on screen.
1846 \begin_layout Standard
1847 One final note regarding the
1848 \begin_inset Flex CharStyle:Code
1851 \begin_layout Plain Layout
1857 flag: you should know that there is nothing wrong with using bitmap and
1858 scalable fonts at the same time for different purposes.
1859 For instance, it's common to use the scalable
1860 \begin_inset Quotes eld
1864 \begin_inset Quotes erd
1867 for the serif text together with a bitmap version of
1868 \begin_inset Quotes eld
1872 \begin_inset Quotes erd
1876 And you can safely select the
1877 \begin_inset Quotes eld
1881 \begin_inset Quotes erd
1884 button without worries: It will only apply to the Helvetica font.
1887 \begin_layout Standard
1888 Sometimes the artifacts introduced by use of the flag can be relieved by
1889 using the fine-detail screen font sizes which defines which point sizes
1890 the different logical font sizes correspond to.
1892 \begin_inset Flex CharStyle:Code
1895 \begin_layout Plain Layout
1901 to see exactly what concrete fonts the logical sizes map to, and try adjusting
1902 the corresponding entries in the
1903 \begin_inset Flex CharStyle:MenuItem
1906 \begin_layout Plain Layout
1912 dialog until you've managed to hit the nail and get the fonts you want.
1913 This can be hard to do, because LyX uses the DPI setting and the font zoom
1914 settings to calculate which exact screen font size to ask the X server
1915 for, thus obfuscating the mapping.
1916 If you can't make it by trial-and-error, you can make the process more
1917 transparent if you set both the DPI setting and font zoom settings to 100---eve
1918 n when this is known to be wrong.
1919 This will of course make your scalable fonts look weird, so use with care.
1922 \begin_layout Standard
1923 \begin_inset Branch OutDated
1926 \begin_layout Subsubsection
1930 \begin_layout Standard
1931 By default, LyX will use fonts meant to write Western European text, including
1932 all kinds of English.
1933 This is defined through the so-called
1942 If you want to use LyX to write for instance Eastern European text, Cyrillic
1943 or any other language not covered by the ISO-8859-1 font encoding, you
1944 can define a different one with the encoding setting.
1945 This requires you to have special fonts installed.
1947 \begin_inset Flex CharStyle:Code
1950 \begin_layout Plain Layout
1956 to see whether this is the case: check the
1957 \begin_inset Quotes eld
1961 \begin_inset Quotes erd
1965 \begin_inset Quotes eld
1969 \begin_inset Quotes erd
1972 fields for ISO-8859-X values different from ISO-8859-1, and search for
1973 one that contains the national characters of your language.
1974 If you find any, enter this encoding in the dialog.
1975 If not, go searching the Web for appropriate fonts.
1976 For the Qt frontend, it's recommended you use an iso646 font set.
1979 \begin_layout Standard
1980 When you've set LyX up to use a different font encoding, you should also
1981 consider changing the font used by dialog windows in LyX.
1983 \begin_inset Flex CharStyle:MenuItem
1986 \begin_layout Plain Layout
1988 \begin_inset space ~
1992 \begin_inset space ~
2000 dialog will not be understandable unless you tell LyX to use a different
2002 By default the menu font is set to
2003 \begin_inset Flex CharStyle:Code
2006 \begin_layout Plain Layout
2007 -*-helvetica-medium-r
2012 , but often Helvetica is not available in the font encoding you need, so
2013 the dialog allows this to be changed.
2016 \begin_layout Standard
2017 As you can see, there are quite a few options that can be used to fine tune
2018 the look of your fonts.
2019 This should not scare you from fiddling with the settings, because after
2020 all, you will hopefully be using LyX for many hours in the future.
2021 And contrary to real WYSIWYG word processors where you are tied to using
2022 fonts that have to look good both on paper and on screen, LyX gives you
2023 the possibility of using fonts that are designed to look good on the screen
2024 while using a different set of fonts to look good on paper.
2032 \begin_layout Subsection
2034 \begin_inset CommandInset label
2043 \begin_layout Standard
2044 The appearance of both the menu and toolbar may both be changed using the
2046 \begin_inset Flex CharStyle:MenuItem
2049 \begin_layout Plain Layout
2056 Simply select a different
2057 \begin_inset Flex CharStyle:Code
2060 \begin_layout Plain Layout
2067 \begin_inset Flex CharStyle:MenuItem
2070 \begin_layout Plain Layout
2071 Look & Feel\SpecialChar \menuseparator
2078 You can customize the interface by copying one of the
2079 \begin_inset Flex CharStyle:Code
2082 \begin_layout Plain Layout
2089 \begin_inset Flex CharStyle:Code
2092 \begin_layout Plain Layout
2099 \begin_inset Flex CharStyle:Code
2102 \begin_layout Plain Layout
2109 You may have to restart LyX for these changes to take effect.
2112 \begin_layout Standard
2114 \begin_inset Flex CharStyle:Code
2117 \begin_layout Plain Layout
2123 files is straightforward: have a look at
2124 \begin_inset Flex CharStyle:Code
2127 \begin_layout Plain Layout
2135 \begin_inset Flex CharStyle:Code
2138 \begin_layout Plain Layout
2145 \begin_inset Flex CharStyle:Code
2148 \begin_layout Plain Layout
2155 \begin_inset Flex CharStyle:Code
2158 \begin_layout Plain Layout
2164 entries must be ended with an explicit
2165 \begin_inset Flex CharStyle:Code
2168 \begin_layout Plain Layout
2176 \begin_inset Flex CharStyle:Code
2179 \begin_layout Plain Layout
2186 \begin_inset Flex CharStyle:Code
2189 \begin_layout Plain Layout
2196 \begin_inset Flex CharStyle:Code
2199 \begin_layout Plain Layout
2206 \begin_inset Flex CharStyle:Code
2209 \begin_layout Plain Layout
2216 \begin_inset Flex CharStyle:Code
2219 \begin_layout Plain Layout
2225 s and in the case of the
2226 \begin_inset Quotes eld
2230 \begin_inset Quotes erd
2234 \begin_inset Flex CharStyle:Code
2237 \begin_layout Plain Layout
2244 One small word of warning.
2246 \begin_inset Flex CharStyle:Code
2249 \begin_layout Plain Layout
2255 s may be inserted in a
2256 \begin_inset Flex CharStyle:Code
2259 \begin_layout Plain Layout
2266 \begin_inset Flex CharStyle:Code
2269 \begin_layout Plain Layout
2275 , but they are defined as
2276 \begin_inset Flex CharStyle:Code
2279 \begin_layout Plain Layout
2286 \begin_inset Flex CharStyle:Code
2289 \begin_layout Plain Layout
2297 \begin_inset Flex CharStyle:Code
2300 \begin_layout Plain Layout
2306 tag is used to insert context-dependent information that is generated by
2308 Unfortunately, the available tags are not documented outside the source
2312 \begin_layout Standard
2313 Note that, as of LyX 1.6, there are extensive context menus, normally accessed
2315 These are defined in the
2316 \begin_inset Flex CharStyle:Code
2319 \begin_layout Plain Layout
2328 \begin_layout Section
2332 \begin_layout Standard
2333 The settings in this section are used to customise the behavior of the LyX
2337 \begin_layout Subsection
2338 \begin_inset CommandInset label
2347 \begin_layout Standard
2348 Bindings are used to associate a LyX function to a key.
2349 Several prepackaged binding files are available: a CUA set of bindings
2350 (familiar as the typical set of PC and CDE set of keyboard shortcuts),
2351 an Emacs set of bindings, for those of us who follow the One True Way and
2352 refuse to lower our standards,
2356 \begin_layout Plain Layout
2357 I'm kidding here, of course!
2362 as well as specialty bindings (broadway and hollywood) and bindings for
2363 languages other than English.
2364 You can select your binding in the
2365 \begin_inset Flex CharStyle:MenuItem
2368 \begin_layout Plain Layout
2369 Editing\SpecialChar \menuseparator
2378 \begin_inset Flex CharStyle:MenuItem
2381 \begin_layout Plain Layout
2386 ools\SpecialChar \menuseparator
2402 \begin_layout Standard
2403 If, however, you'd like to customise the bindings to your own exacting tastes,
2404 then there are two ways to proceed.
2405 The first, and older method, is to copy a file from
2406 \begin_inset Flex CharStyle:Code
2409 \begin_layout Plain Layout
2416 \begin_inset Flex CharStyle:Code
2419 \begin_layout Plain Layout
2425 and modify that in a text editor.
2426 Don't forget to select this file in
2427 \begin_inset Flex CharStyle:MenuItem
2430 \begin_layout Plain Layout
2431 Editing\SpecialChar \menuseparator
2438 The second method is to use the shortcut editor, which you will also find
2440 \begin_inset Flex CharStyle:MenuItem
2443 \begin_layout Plain Layout
2444 Editing\SpecialChar \menuseparator
2451 The changes you make here will be stored at
2452 \begin_inset Flex CharStyle:Code
2455 \begin_layout Plain Layout
2456 UserDir/bind/user.bind
2464 \begin_layout Standard
2465 LyX supports internationalization of the user interface (see Chapter
2466 \begin_inset space ~
2470 \begin_inset CommandInset ref
2472 reference "chap:i18n"
2481 is set, LyX will try to use bindfiles by prepending the standard language
2483 For example, you can put a translated copy of some standard bind file in
2485 \begin_inset Flex CharStyle:Code
2488 \begin_layout Plain Layout
2494 directory, and LyX will use it automatically.
2497 \begin_layout Standard
2499 \begin_inset Flex CharStyle:Code
2502 \begin_layout Plain Layout
2508 files is straightforward:
2511 \begin_layout LyX-Code
2514 bind ``<key combination>'' ``<lyx-function>
2515 \begin_inset Quotes erd
2521 \begin_layout Standard
2522 Both key combination and lyx-function (including any arguments) must be
2523 enclosed in "double quotes".
2524 The LyX functions are partially documented on listed on the
2525 \begin_inset CommandInset href
2528 target "http://wiki.lyx.org/LyX/LyxFunctions"
2533 A major effort is presently underway to improve this documentation.
2536 \begin_layout Section
2537 \begin_inset CommandInset label
2539 name "sec:converters-etc"
2546 \begin_layout Standard
2547 LyX has a powerful mechanism to convert to and from any file format using
2552 \begin_layout Subsection
2553 \begin_inset CommandInset label
2562 \begin_layout Standard
2563 The first step is to define your file formats if they are not already defined.
2565 \begin_inset Flex CharStyle:MenuItem
2568 \begin_layout Plain Layout
2569 Tools\SpecialChar \menuseparator
2570 Preferences\SpecialChar \menuseparator
2571 File Handling\SpecialChar \menuseparator
2579 \begin_inset Flex CharStyle:MenuItem
2582 \begin_layout Plain Layout
2583 New\SpecialChar \ldots{}
2589 button to define your new format.
2591 \begin_inset Flex CharStyle:MenuItem
2594 \begin_layout Plain Layout
2600 field contains the named used to identify the format in the GUI.
2602 \begin_inset Flex CharStyle:MenuItem
2605 \begin_layout Plain Layout
2611 is used to identify the format interally.
2612 You will also need to enter a file extension.
2613 These are all required.
2615 \begin_inset Flex CharStyle:MenuItem
2618 \begin_layout Plain Layout
2624 field is used to provide a keyboard shortcut on the menus.
2625 (For example, pressing
2626 \begin_inset Flex CharStyle:MenuItem
2629 \begin_layout Plain Layout
2636 \begin_inset Flex CharStyle:MenuItem
2639 \begin_layout Plain Layout
2640 View\SpecialChar \menuseparator
2649 \begin_layout Standard
2651 \begin_inset Flex CharStyle:MenuItem
2654 \begin_layout Plain Layout
2661 \begin_inset Flex CharStyle:MenuItem
2664 \begin_layout Plain Layout
2671 For example, you might want to use
2672 \begin_inset Flex CharStyle:MenuItem
2675 \begin_layout Plain Layout
2681 to view PostScript files.
2682 You can enter the command needed to start the program in the corresponding
2684 In defining this command, you can use the four variables listed in the
2686 The viewer is launched when you view an image in LyX or use the
2687 \begin_inset Flex CharStyle:MenuItem
2690 \begin_layout Plain Layout
2697 The editor is for example launched when you press the
2698 \begin_inset Flex CharStyle:MenuItem
2701 \begin_layout Plain Layout
2708 \begin_inset Flex CharStyle:MenuItem
2711 \begin_layout Plain Layout
2718 \begin_inset Flex CharStyle:MenuItem
2721 \begin_layout Plain Layout
2730 \begin_layout Standard
2732 \begin_inset Flex CharStyle:MenuItem
2735 \begin_layout Plain Layout
2741 option tells LyX that a format is suitable for document export.
2742 If this is is set and if a suitable conversion route exists (see
2743 \begin_inset CommandInset ref
2745 reference "sub:Converters"
2749 ), the format will appear in the
2750 \begin_inset Flex CharStyle:MenuItem
2753 \begin_layout Plain Layout
2754 File\SpecialChar \menuseparator
2761 The format will also appear in the
2762 \begin_inset Flex CharStyle:MenuItem
2765 \begin_layout Plain Layout
2771 menu if a viewer is specified for the format.
2772 Pure image formats, such as
2773 \begin_inset Flex CharStyle:Code
2776 \begin_layout Plain Layout
2782 , should not use this option.
2783 Formats that can both represent vector graphics and documents like
2784 \begin_inset Flex CharStyle:Code
2787 \begin_layout Plain Layout
2796 \begin_layout Standard
2798 \begin_inset Flex CharStyle:MenuItem
2801 \begin_layout Plain Layout
2802 Vector graphics format
2807 tells LyX that a format can contain vector graphics.
2808 This information is used to determine the target format of included graphics
2810 \begin_inset Flex CharStyle:MenuItem
2813 \begin_layout Plain Layout
2820 Included graphics may need to be converted to either
2821 \begin_inset Flex CharStyle:MenuItem
2824 \begin_layout Plain Layout
2831 \begin_inset Flex CharStyle:MenuItem
2834 \begin_layout Plain Layout
2841 \begin_inset Flex CharStyle:MenuItem
2844 \begin_layout Plain Layout
2851 \begin_inset Flex CharStyle:MenuItem
2854 \begin_layout Plain Layout
2860 cannot handle other image formats.
2861 If an included graphic is not already in
2862 \begin_inset Flex CharStyle:MenuItem
2865 \begin_layout Plain Layout
2872 \begin_inset Flex CharStyle:MenuItem
2875 \begin_layout Plain Layout
2882 \begin_inset Flex CharStyle:MenuItem
2885 \begin_layout Plain Layout
2891 format, it is converted to
2892 \begin_inset Flex CharStyle:MenuItem
2895 \begin_layout Plain Layout
2901 if the vector format option is set, and otherwise to
2902 \begin_inset Flex CharStyle:MenuItem
2905 \begin_layout Plain Layout
2914 \begin_layout Subsection
2918 \begin_layout Standard
2919 Since all conversions from one format to another take place in LyX's temporary
2920 directory, it is sometimes necessary to modify a file before copying it
2921 to the temporary directory in order that the conversion may be performed.
2925 \begin_layout Plain Layout
2926 For example, the file may refer to other files---images, for example---using
2927 relative filenames, and these may become invalid when the file is copied
2928 to the temporary directory.
2933 This is done by a Copier: It copies a file to (or from) the temporary directory
2934 and may modify it in the process.
2937 \begin_layout Standard
2938 The definitions of the copiers may use four variables:
2941 \begin_layout Labeling
2942 \labelwidthstring 00.00.0000
2943 \begin_inset Flex CharStyle:Code
2946 \begin_layout Plain Layout
2952 The LyX system directory (e.
2953 \begin_inset space \thinspace{}
2957 \begin_inset space ~
2961 \begin_inset Flex CharStyle:MenuItem
2964 \begin_layout Plain Layout
2973 \begin_layout Labeling
2974 \labelwidthstring 00.00.0000
2975 \begin_inset Flex CharStyle:Code
2978 \begin_layout Plain Layout
2987 \begin_layout Labeling
2988 \labelwidthstring 00.00.0000
2989 \begin_inset Flex CharStyle:Code
2992 \begin_layout Plain Layout
3001 \begin_layout Labeling
3002 \labelwidthstring 00.00.0000
3003 \begin_inset Flex CharStyle:Code
3006 \begin_layout Plain Layout
3015 \begin_layout Standard
3016 The latter is to be given in a form suitable for inclusion in a LaTeX's
3023 command and is relevant only when exporting files suitable for such inclusion.
3026 \begin_layout Standard
3027 Copiers can be used to do almost anything with output files.
3028 For example, suppose you want generated pdf files to be copied to a special
3030 \begin_inset Flex CharStyle:Code
3033 \begin_layout Plain Layout
3040 Then you could write a shell script such as this one:
3043 \begin_layout Standard
3044 \begin_inset listings
3048 \begin_layout Plain Layout
3052 \begin_layout Plain Layout
3056 \begin_layout Plain Layout
3057 TOFILE=`basename $2`
3060 \begin_layout Plain Layout
3061 cp $FROMFILE /home/you/pdf/$TOFILE
3066 Save that in your local LyX directory---say,
3067 \begin_inset Flex CharStyle:Code
3070 \begin_layout Plain Layout
3071 /home/you/.lyx/scripts/pdfcopier.sh
3076 ---and make it executable, if you need to do so on your platform.
3078 \begin_inset Flex CharStyle:MenuItem
3081 \begin_layout Plain Layout
3082 Tools\SpecialChar \menuseparator
3089 \begin_inset Flex CharStyle:MenuItem
3092 \begin_layout Plain Layout
3098 format---or one of the other pdf formats---and enter
3099 \begin_inset Flex CharStyle:Code
3102 \begin_layout Plain Layout
3103 pdfcopier.sh $$i $$o
3109 \begin_inset Flex CharStyle:MenuItem
3112 \begin_layout Plain Layout
3122 \begin_layout Standard
3123 Copiers are used by LyX in various of its own conversions.
3124 For example, if appropriate programs are found, LyX will automatically
3125 install copiers for the
3126 \begin_inset Flex CharStyle:MenuItem
3129 \begin_layout Plain Layout
3136 \begin_inset Flex CharStyle:MenuItem
3139 \begin_layout Plain Layout
3141 \begin_inset space ~
3150 When these formats are exported, the copier sees that not just the main
3151 HTML file but various associated files (style files, images, etc.) are also
3153 All these files are written to a subdirectory of the directory in which
3154 the original LyX file was found.
3158 \begin_layout Plain Layout
3159 This copier can be customized.
3161 \begin_inset Quotes eld
3165 \begin_inset Quotes erd
3168 argument takes a comma-separated list of extensions to be copied; if it
3169 is omitted, all files will be copied.
3171 \begin_inset Quotes eld
3175 \begin_inset Quotes erd
3178 argument determines the extension added to the generated directory.
3180 \begin_inset Quotes eld
3184 \begin_inset Flex CharStyle:MenuItem
3187 \begin_layout Plain Layout
3194 \begin_inset Quotes erd
3197 , so HTML generated from
3198 \begin_inset Flex CharStyle:MenuItem
3201 \begin_layout Plain Layout
3202 /path/to/filename.lyx
3208 \begin_inset Flex CharStyle:MenuItem
3211 \begin_layout Plain Layout
3212 /path/to/filename.html.LyXconv
3226 \begin_layout Subsection
3227 \begin_inset CommandInset label
3229 name "sub:Converters"
3236 \begin_layout Standard
3237 You can define your own Converters to, uhh, convert files between different
3240 \begin_inset Flex CharStyle:MenuItem
3243 \begin_layout Plain Layout
3244 Tools\SpecialChar \menuseparator
3245 Preferences\SpecialChar \menuseparator
3246 File Handling\SpecialChar \menuseparator
3255 \begin_layout Standard
3256 To define a new converter, select the
3257 \begin_inset Flex CharStyle:MenuItem
3260 \begin_layout Plain Layout
3262 \begin_inset space ~
3271 \begin_inset space \thinspace{}
3275 \begin_inset Flex CharStyle:MenuItem
3278 \begin_layout Plain Layout
3280 \begin_inset space ~
3288 from the drop-down lists, enter the command needed for the conversion,
3290 \begin_inset Flex CharStyle:MenuItem
3293 \begin_layout Plain Layout
3300 Several variables can be used in the definition of converters:
3303 \begin_layout Labeling
3304 \labelwidthstring 00.00.0000
3305 \begin_inset Flex CharStyle:Code
3308 \begin_layout Plain Layout
3314 The LyX system directory
3317 \begin_layout Labeling
3318 \labelwidthstring 00.00.0000
3319 \begin_inset Flex CharStyle:Code
3322 \begin_layout Plain Layout
3331 \begin_layout Labeling
3332 \labelwidthstring 00.00.0000
3333 \begin_inset Flex CharStyle:Code
3336 \begin_layout Plain Layout
3345 \begin_layout Labeling
3346 \labelwidthstring 00.00.0000
3347 \begin_inset Flex CharStyle:Code
3350 \begin_layout Plain Layout
3356 The base filename of the input file (i.e., without the extension)
3359 \begin_layout Labeling
3360 \labelwidthstring 00.00.0000
3361 \begin_inset Flex CharStyle:Code
3364 \begin_layout Plain Layout
3370 The path to the input file
3373 \begin_layout Standard
3375 \begin_inset Flex CharStyle:MenuItem
3378 \begin_layout Plain Layout
3380 \begin_inset space ~
3388 field you can enter the following flags, separated by commas:
3391 \begin_layout Labeling
3392 \labelwidthstring 00.00.0000
3393 \begin_inset Flex CharStyle:Code
3396 \begin_layout Plain Layout
3402 This converter runs some form of LaTeX.
3403 This will make LyX's LaTeX error logs available.
3406 \begin_layout Labeling
3407 \labelwidthstring 00.00.0000
3408 \begin_inset Flex CharStyle:Code
3411 \begin_layout Plain Layout
3418 \begin_inset Flex CharStyle:MenuItem
3421 \begin_layout Plain Layout
3427 file for the conversion.
3430 \begin_layout Labeling
3431 \labelwidthstring 00.00.0000
3432 \begin_inset Flex CharStyle:Code
3435 \begin_layout Plain Layout
3444 \begin_layout Standard
3445 The following three flags are not really flags at all because they take
3447 \begin_inset Flex CharStyle:MenuItem
3450 \begin_layout Plain Layout
3452 \begin_inset space ~
3456 \begin_inset space ~
3467 \begin_layout Labeling
3468 \labelwidthstring 00.00.0000
3469 \begin_inset Flex CharStyle:Code
3472 \begin_layout Plain Layout
3478 If set, the converter's standard error will be redirected to a file
3479 \begin_inset Flex CharStyle:Code
3482 \begin_layout Plain Layout
3488 , and the script given as argument will be run as:
3489 \begin_inset Flex CharStyle:Code
3492 \begin_layout Plain Layout
3493 script <infile.out >infile.log
3499 The argument may contain
3500 \begin_inset Flex CharStyle:Code
3503 \begin_layout Plain Layout
3512 \begin_layout Labeling
3513 \labelwidthstring 00.00.0000
3514 \begin_inset Flex CharStyle:Code
3517 \begin_layout Plain Layout
3523 The name of the directory in which the converter will dump the generated
3525 LyX will not create this directory, and it does not copy anything into
3526 it, though it will copy this directory to the destination.
3527 The argument may contain
3528 \begin_inset Flex CharStyle:Code
3531 \begin_layout Plain Layout
3537 , which will be replaced by the basename of the input and output files,
3538 respectively, when the directory is copied.
3539 \begin_inset Newline newline
3542 Note that resultdir and usetempdir make no sense together.
3543 The latter will be ignored if the former is given.
3546 \begin_layout Labeling
3547 \labelwidthstring 00.00.0000
3548 \begin_inset Flex CharStyle:Code
3551 \begin_layout Plain Layout
3557 Determines the output filename and may, contain
3558 \begin_inset Flex CharStyle:Code
3561 \begin_layout Plain Layout
3568 Sensible only with resultdir and optional even then; if not given, it defaults
3572 \begin_layout Standard
3573 None of these last three are presently used in any of the converters that
3574 are installed with LyX.
3578 \begin_layout Standard
3579 You do not have to define converters between all the formats between which
3580 you want to convert.
3581 For example, you will note that there is no `LyX to PostScript®' converter,
3582 but LyX will export PostScript®.
3583 It does so by first creating a LaTeX file (no converter needs to be defined
3584 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
3585 and finally converting the resulting DVI file to PostScript®.
3586 LyX finds such `chains' of converters automatically, and it will always
3587 choose the shortest possible chain.
3588 You can, though, still define multiple conversion methods between file
3590 For example, the standard LyX configuration provides three ways to convert
3591 LaTeX to PDF: Directly, using
3592 \begin_inset Flex CharStyle:MenuItem
3595 \begin_layout Plain Layout
3601 ; via (DVI and) PostScript®, using
3602 \begin_inset Flex CharStyle:MenuItem
3605 \begin_layout Plain Layout
3612 \begin_inset Flex CharStyle:MenuItem
3615 \begin_layout Plain Layout
3622 To define such alternate chains, you must define multiple target `file
3623 formats', as described in section
3624 \begin_inset CommandInset ref
3626 reference "sub:Formats"
3631 For example, in the standard configuration, the formats named
3632 \begin_inset Flex CharStyle:MenuItem
3635 \begin_layout Plain Layout
3642 \begin_inset Flex CharStyle:MenuItem
3645 \begin_layout Plain Layout
3652 \begin_inset Flex CharStyle:MenuItem
3655 \begin_layout Plain Layout
3661 are defined, all of which share the extension
3662 \begin_inset Flex CharStyle:MenuItem
3665 \begin_layout Plain Layout
3671 , and which correspond to the conversion methods just mentioned.
3674 \begin_layout Section
3678 \begin_layout Standard
3679 The settings in this section affect the output LyX produces.
3682 \begin_layout Subsection
3683 Plain text export options
3686 \begin_layout Standard
3688 There are a couple of commands that can be used to
3689 \begin_inset Quotes eld
3693 \begin_inset Quotes erd
3696 exported plain text files.
3697 Note that LyX automatically detects and tries to use the best settings
3698 for your system at installation time, but you can modify them in the
3699 \begin_inset Flex CharStyle:MenuItem
3702 \begin_layout Plain Layout
3703 Output\SpecialChar \menuseparator
3709 dialog if you disagree with its interpretation.
3712 \begin_layout Description
3713 \begin_inset Flex CharStyle:Code
3716 \begin_layout Plain Layout
3722 This option defines the command used to produce better plain text tables
3724 \begin_inset Flex CharStyle:Code
3727 \begin_layout Plain Layout
3733 UNIX-commands (refer to their manpages for more information about them).
3734 Setting this as empty tells LyX to use the internal (inferior) formatter.
3737 \begin_layout Description
3738 \begin_inset Flex CharStyle:Code
3741 \begin_layout Plain Layout
3747 With this command you can set the default line length of the plain text
3749 Setting it to 0 means that no line breaks will be inserted except between
3750 paragraphs and the like.
3753 \begin_layout Section
3757 \begin_layout Standard
3758 There are many other configuration options that can be used to customize
3760 Most of them are sufficiently self-explanatory that we have not felt it
3761 necessary to document them here.
3763 \begin_inset CommandInset href
3765 name "mailing lists"
3766 target "http://www.lyx.org/mailing.php"
3770 if you need some more information.
3773 \begin_layout Chapter
3774 Internationalizing LyX
3775 \begin_inset CommandInset label
3784 \begin_layout Standard
3785 LyX supports using a translated interface.
3786 Last time we checked, LyX provided text in thirty languages.
3787 The language of choice is called your
3792 (For further reading on locale settings, see also the documentation for
3793 locale that comes with your operating system.
3794 For Linux, the manual page for
3795 \begin_inset Flex CharStyle:Code
3798 \begin_layout Plain Layout
3804 could be a good place to start).
3807 \begin_layout Standard
3808 Notice that these translations will work, but do contain a few flaws.
3809 In particular, all dialogs have been designed with the English text in
3810 mind, which means that some of the translated text will be too large to
3811 fit within the space allocated.
3812 This is only a display problem and will not cause any harm.
3813 Also, you will find that some of the translations do not define shortcut
3814 keys for everything.
3815 Sometimes, there are simply not enough free letters to do it.
3816 Other times, the translator just hasn't got around to doing it yet.
3817 Our localization team, which you may wish to join,
3821 \begin_layout Plain Layout
3822 If you are a fluent speaker of a language other than English, joining these
3823 teams is a great way to give back to the LyX community!
3828 will of course try to fix these shortcomings in future versions of LyX.
3831 \begin_layout Section
3835 \begin_layout Subsection
3836 Translating the graphical user interface (text messages).
3839 \begin_layout Standard
3841 \begin_inset Flex CharStyle:Code
3844 \begin_layout Plain Layout
3850 library to handle the internationalization of the interface.
3851 To have LyX speak your favorite language in all menus and dialogs, you
3853 \begin_inset Flex CharStyle:Code
3856 \begin_layout Plain Layout
3862 -file for that language.
3863 When this is available, you'll have to generate a
3864 \begin_inset Flex CharStyle:Code
3867 \begin_layout Plain Layout
3873 -file from it and install the
3874 \begin_inset Flex CharStyle:Code
3877 \begin_layout Plain Layout
3884 The process of doing all of this is explained in the documentation for
3886 \begin_inset Flex CharStyle:Code
3889 \begin_layout Plain Layout
3896 It is possible to do this just for yourself, but if you're going to do
3897 it, you might as well share the results of your labors with the rest of
3899 Send a message to the LyX developers' list for more information about how
3903 \begin_layout Standard
3904 In short, this is what you should do (xx denotes the language code):
3907 \begin_layout Itemize
3908 Check out the LyX source code.
3910 \begin_inset CommandInset href
3912 name "information on the web"
3913 target "http://www.lyx.org/devel/cvs.php"
3920 \begin_layout Itemize
3922 \begin_inset Flex CharStyle:Code
3925 \begin_layout Plain Layout
3931 to the folder of the
3932 \begin_inset Flex CharStyle:Code
3935 \begin_layout Plain Layout
3943 \begin_inset Flex CharStyle:Code
3946 \begin_layout Plain Layout
3954 \begin_inset Flex CharStyle:Code
3957 \begin_layout Plain Layout
3963 doesn't exist anywhere, it can be remade with the console command
3964 \begin_inset Flex CharStyle:Code
3967 \begin_layout Plain Layout
3973 in that directory, or you can use an existing po-file for some other language
3977 \begin_layout Itemize
3979 \begin_inset Flex CharStyle:Code
3982 \begin_layout Plain Layout
3992 \begin_layout Plain Layout
3993 This is just a text file, so it can be edited in any text editor.
3994 But there are also specialized programs that support such editing, such
3999 (for all platforms) or
4008 contains a `mode' for editing
4009 \begin_inset Flex CharStyle:Code
4012 \begin_layout Plain Layout
4023 For some menu- and widget-labels, there are also shortcut keys that should
4025 Those keys are marked after a `|', and should be translated according to
4026 the words and phrases of the language.
4027 You should also fill also out the information at the beginning of the new
4029 \begin_inset Flex CharStyle:Code
4032 \begin_layout Plain Layout
4038 -file with your email-address, etc., so people know where to reach you with
4039 suggestions and entertaining flames.
4042 \begin_layout Standard
4043 If you are just doing this on your own, then:
4046 \begin_layout Itemize
4048 \begin_inset Flex CharStyle:Code
4051 \begin_layout Plain Layout
4058 This can be done with
4059 \begin_inset Flex CharStyle:Code
4062 \begin_layout Plain Layout
4063 msgfmt -o xx.mo < xx.po
4071 \begin_layout Itemize
4073 \begin_inset Flex CharStyle:Code
4076 \begin_layout Plain Layout
4082 -file to your locale-tree, at the correct directory for application messages
4087 xx, and under the name
4088 \begin_inset Flex CharStyle:Code
4091 \begin_layout Plain Layout
4099 \begin_inset Flex CharStyle:Code
4102 \begin_layout Plain Layout
4103 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
4113 \begin_layout Standard
4114 As said, however, it would be best if the new
4115 \begin_inset Flex CharStyle:Code
4118 \begin_layout Plain Layout
4124 -file could be added to the LyX distribution, so others can use it.
4125 Adding it involves making additional changes to LyX.
4126 So send an email to the developers' mailing list if you're interested in
4130 \begin_layout Subsubsection
4134 \begin_layout Standard
4135 Sometimes it turns out that one English message needs to be translated into
4136 different messages in the target language.
4137 One example is the message
4138 \begin_inset Flex CharStyle:Code
4141 \begin_layout Plain Layout
4147 which has the German translation
4155 , depending upon exactly what the English
4156 \begin_inset Quotes eld
4160 \begin_inset Quotes erd
4165 \begin_inset Flex CharStyle:Code
4168 \begin_layout Plain Layout
4174 does not handle such ambigous translations.
4175 Therefore you have to add some context information to the message: Instead
4177 \begin_inset Flex CharStyle:Code
4180 \begin_layout Plain Layout
4187 \begin_inset Flex CharStyle:Code
4190 \begin_layout Plain Layout
4191 To[[as in 'From format x to format y']]
4197 \begin_inset Flex CharStyle:Code
4200 \begin_layout Plain Layout
4201 To[[as in 'From page x to page y']].
4206 Now the two occurences of
4207 \begin_inset Flex CharStyle:Code
4210 \begin_layout Plain Layout
4217 \begin_inset Flex CharStyle:Code
4220 \begin_layout Plain Layout
4226 and can be translated correctly to
4237 \begin_layout Standard
4238 Of course the context information needs to be stripped off the original
4239 message when no translation is used.
4240 Therefore you have to put it in double square brackets at the end of the
4241 message (see the example above).
4242 The translation mechanism of LyX ensures that everything in double square
4243 brackets at the end of messages is removed before displaying the message.
4246 \begin_layout Subsection
4247 Translating the documentation.
4250 \begin_layout Standard
4251 The online documentation (in the
4252 \begin_inset Flex CharStyle:MenuItem
4255 \begin_layout Plain Layout
4265 -menu) can (and should!) be translated.
4266 If there are translated versions of the documentation available
4270 \begin_layout Plain Layout
4271 As of March 2008, at least some of the documents have been translated into
4272 fourteen languages, with the Tutorial available in a few more.
4277 and the locale is set accordingly, these will be used automagically by
4279 LyX looks for translated versions as
4280 \begin_inset Flex CharStyle:Code
4283 \begin_layout Plain Layout
4284 LyXDir/doc/xx_DocName.lyx
4290 \begin_inset Flex CharStyle:Code
4293 \begin_layout Plain Layout
4299 is the code for the language currently in use.
4300 If there are no translated documents, the default English versions will
4302 Note that the translated versions must have the same filenames (
4303 \begin_inset Flex CharStyle:Code
4306 \begin_layout Plain Layout
4312 above) as the original.
4313 If you feel up to translating the documentation (an excellent way to proof-read
4314 the original documentation by the way!), there are a few things you should
4318 \begin_layout Itemize
4320 \begin_inset Flex CharStyle:Code
4323 \begin_layout Plain Layout
4329 , the guide to writing LyX documentation.
4330 Pay special attention to the translator's section.
4333 \begin_layout Itemize
4334 Check out the documentation translation web page at
4335 \begin_inset CommandInset href
4337 name "http://www.devel.lyx.org"
4338 target "http://www.devel.lyx.org"
4343 That way, you can find out which (if any) documents have already been translate
4344 d into your language.
4345 You can also find out who (if anyone) is organizing the effort to translate
4346 the documentation into your language.
4347 If no one is organizing the effort, please let us know that you're interested.
4350 \begin_layout Standard
4351 Once you get to actually translating, here's a few hints for you that may
4355 \begin_layout Itemize
4356 Join the documentation team! There is information on how to do that in
4357 \begin_inset Flex CharStyle:Code
4360 \begin_layout Plain Layout
4367 \begin_inset Flex CharStyle:MenuItem
4370 \begin_layout Plain Layout
4375 elp\SpecialChar \menuseparator
4385 ), which by the way is the first document you should translate.
4388 \begin_layout Itemize
4389 Learn the typographic conventions for the language you are translating to.
4390 Typography is an ancient art and over the centuries, a great variety of
4391 conventions have developed throughout different parts of the world.
4392 Also study the professional terminology amongst typographers in your country.
4393 Inventing your own terminology will only confuse the users.
4396 (Warning! Typography is addictive!)
4399 \begin_layout Itemize
4400 Make a copy of the document.
4401 This will be your working copy.
4402 You can use this as your personal translated help-file by placing it in
4404 \begin_inset Flex CharStyle:Code
4407 \begin_layout Plain Layout
4416 \begin_layout Itemize
4417 Sometimes the original document (from the LyX-team) will be updated.
4418 Use the source viewer at
4419 \begin_inset CommandInset href
4421 name "http://www.lyx.org/trac/timeline"
4422 target "http://www.lyx.org/trac/timeline"
4426 to see what has been changed.
4427 That way you can easily see which parts of the translated document need
4431 \begin_layout Standard
4432 If you ever find an error in the original document, fix it and notify the
4433 rest of the documentation team of the changes! (You didn't forget to join
4434 the documentation team, did you?)
4437 \begin_layout Standard
4438 \begin_inset Branch OutDated
4441 \begin_layout Section
4442 International Keyboard Support
4445 \begin_layout Standard
4448 [Editor's Note: The following section is by
4456 It needs to be fixed to conform to the new Documentation Style sheet and
4457 to make use of the new v1.0 features.
4458 The whole thing also needs to be merged with the section following it.-jw
4459 It may also be badly out of date.-rh (2008)]
4462 \begin_layout Subsection
4463 Defining Own Keymaps: Keymap File Format
4466 \begin_layout Standard
4467 Let's look at a keyboard definition file a little closer.
4468 It is a plain text file defining
4471 \begin_layout Itemize
4472 key-to-key or key-to-string translations
4475 \begin_layout Itemize
4479 \begin_layout Itemize
4480 dead keys exceptions
4483 \begin_layout Standard
4484 To define key-to-key or key-to-string translation, use this command:
4487 \begin_layout Quotation
4488 \begin_inset Flex CharStyle:Code
4491 \begin_layout Plain Layout
4500 \begin_inset Flex CharStyle:Code
4503 \begin_layout Plain Layout
4512 \begin_layout Standard
4514 \begin_inset Flex CharStyle:Code
4517 \begin_layout Plain Layout
4523 is the key to be translated and
4524 \begin_inset Flex CharStyle:Code
4527 \begin_layout Plain Layout
4533 is the string to be inserted into the document.
4534 To define dead keys, use:
4537 \begin_layout Quotation
4538 \begin_inset Flex CharStyle:Code
4541 \begin_layout Plain Layout
4550 \begin_inset Flex CharStyle:Code
4553 \begin_layout Plain Layout
4562 \begin_layout Standard
4564 \begin_inset Flex CharStyle:Code
4567 \begin_layout Plain Layout
4573 is a keyboard key and
4574 \begin_inset Flex CharStyle:Code
4577 \begin_layout Plain Layout
4584 The following dead keys are supported (shortcut name is in parentheses):
4587 \begin_layout Quotation
4591 \begin_inset space \hfill{}
4597 \begin_layout Quotation
4599 \begin_inset space \hfill{}
4605 \begin_layout Quotation
4607 \begin_inset space \hfill{}
4613 \begin_layout Quotation
4615 \begin_inset space \hfill{}
4621 \begin_layout Quotation
4623 \begin_inset space \hfill{}
4629 \begin_layout Quotation
4631 \begin_inset space \hfill{}
4638 \begin_layout Plain Layout
4650 \begin_layout Quotation
4652 \begin_inset space \hfill{}
4658 \begin_layout Quotation
4660 \begin_inset space \hfill{}
4667 \begin_layout Plain Layout
4679 \begin_layout Quotation
4681 \begin_inset space \hfill{}
4687 \begin_layout Quotation
4689 \begin_inset space \hfill{}
4695 \begin_layout Quotation
4697 \begin_inset space \hfill{}
4704 \begin_layout Plain Layout
4716 \begin_layout Quotation
4718 \begin_inset space \hfill{}
4725 \begin_layout Plain Layout
4737 \begin_layout Quotation
4739 \begin_inset space \hfill{}
4745 \begin_layout Quotation
4746 hungarian umlaut (hug)
4747 \begin_inset space \hfill{}
4753 \begin_layout Quotation
4755 \begin_inset space \hfill{}
4761 \begin_layout Quotation
4763 \begin_inset space \hfill{}
4770 \begin_layout Plain Layout
4782 \begin_layout Standard
4783 Since in many international keyboards there are exceptions to what some
4784 dead keys should do, you can define them using
4787 \begin_layout Quotation
4788 \begin_inset Flex CharStyle:Code
4791 \begin_layout Plain Layout
4799 deadkey key outstring
4802 \begin_layout Standard
4803 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
4807 \begin_layout Quotation
4808 \begin_inset Flex CharStyle:Code
4811 \begin_layout Plain Layout
4824 \begin_layout Standard
4825 to make it work correctly.
4826 Also, you have to define as exceptions dead keys over i and j, to remove
4827 the dot from them before inserting an accent mark.
4828 I will change this when the time comes, but so far I haven't had time.
4831 \begin_layout Standard
4832 Oh, and about characters: backslash is escaped, so to enter it, you'll need
4835 \begin_inset Flex CharStyle:Code
4838 \begin_layout Plain Layout
4844 have different meaning.
4846 \begin_inset Flex CharStyle:Code
4849 \begin_layout Plain Layout
4855 marks comments, quotes start and end LaTeX-style commands.
4856 To enter quote, you'll need to use
4857 \begin_inset Flex CharStyle:Code
4860 \begin_layout Plain Layout
4869 \begin_inset Flex CharStyle:Code
4872 \begin_layout Plain Layout
4879 \begin_inset Flex CharStyle:Code
4882 \begin_layout Plain Layout
4893 \begin_layout Standard
4894 If you make a keyboard description file that works for your language, please
4895 mail it to me, so I can include it in the next keymap distribution.
4898 \begin_layout Standard
4899 More keywords will be supported in keymap configuration file in future,
4903 \begin_layout Itemize
4904 \begin_inset Flex CharStyle:Code
4907 \begin_layout Plain Layout
4918 \begin_inset space \hfill{}
4922 \begin_inset Flex CharStyle:Code
4925 \begin_layout Plain Layout
4934 \begin_layout Itemize
4935 \begin_inset Flex CharStyle:Code
4938 \begin_layout Plain Layout
4949 \begin_inset space \hfill{}
4953 \begin_inset Flex CharStyle:Code
4956 \begin_layout Plain Layout
4962 an external keymap translation program
4965 \begin_layout Standard
4966 Also, it should look into
4967 \begin_inset Flex CharStyle:Code
4970 \begin_layout Plain Layout
4976 file for defaults, too (for example, a
4977 \begin_inset Flex CharStyle:Code
4980 \begin_layout Plain Layout
4988 option to include default keyboard).
4996 \begin_layout Section
4997 \begin_inset CommandInset label
5003 International Keymap Stuff
5006 \begin_layout Standard
5007 \begin_inset Note Note
5010 \begin_layout Plain Layout
5011 In doing the revisions on this document in March 2008, I did not look over
5012 this stuff, as I do not understand it.
5013 It would be good if someone else could do so.
5021 \begin_layout Standard
5022 The next two sections describe the
5023 \begin_inset Flex CharStyle:Code
5026 \begin_layout Plain Layout
5035 \begin_inset Flex CharStyle:Code
5038 \begin_layout Plain Layout
5046 file syntax in detail.
5047 These sections should help you design your own key map if the ones provided
5048 do not meet your needs.
5051 \begin_layout Subsection
5055 \begin_layout Standard
5059 \begin_inset Flex CharStyle:Code
5062 \begin_layout Plain Layout
5068 file maps keystrokes to characters or strings.
5069 As the name suggests, it sets a keyboard mapping.
5071 \begin_inset Flex CharStyle:Code
5074 \begin_layout Plain Layout
5085 \begin_inset Flex CharStyle:Code
5088 \begin_layout Plain Layout
5103 \begin_inset Flex CharStyle:Code
5106 \begin_layout Plain Layout
5119 \begin_inset Flex CharStyle:Code
5122 \begin_layout Plain Layout
5131 \begin_inset Flex CharStyle:Code
5134 \begin_layout Plain Layout
5142 are described in this section.
5145 \begin_layout Labeling
5146 \labelwidthstring 00.00.0000
5147 \begin_inset Flex CharStyle:Code
5150 \begin_layout Plain Layout
5158 Map a character to a string
5161 \begin_layout LyX-Code
5176 \begin_layout Standard
5209 the double-quote (")
5226 must be escaped with a preceding backslash (
5237 \begin_layout Standard
5239 \begin_inset Flex CharStyle:MenuItem
5242 \begin_layout Plain Layout
5250 statement to cause the symbol
5251 \begin_inset Flex CharStyle:MenuItem
5254 \begin_layout Plain Layout
5262 to be output for the keystroke
5263 \begin_inset Flex CharStyle:MenuItem
5266 \begin_layout Plain Layout
5277 \begin_layout LyX-Code
5283 \begin_layout Labeling
5284 \labelwidthstring 00.00.0000
5285 \begin_inset Flex CharStyle:Code
5288 \begin_layout Plain Layout
5296 Specify an accent character
5299 \begin_layout LyX-Code
5308 \begin_layout Standard
5309 This will make the cha
5347 This is the dead key
5351 \begin_layout Plain Layout
5358 refers to a key that does not produce a character by itself, but when followed
5359 with another key, produces the desired accent character.
5360 For example, a German characte
5362 r with an umlaut like
5372 can be produced in this manner.
5381 \begin_layout Standard
5394 and then another key not in
5411 followed by the other, unallowed key, as output.
5415 \begin_inset Flex CharStyle:MenuItem
5418 \begin_layout Plain Layout
5426 cancels a dead key, so if
5437 \begin_inset Flex CharStyle:MenuItem
5440 \begin_layout Plain Layout
5449 , the cursor will not go one position backwards but will instead cancel
5465 might have had on the next keystroke.
5469 \begin_layout Standard
5470 The following example specifies that the character ' is to be an acute accent,
5471 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
5474 \begin_layout LyX-Code
5477 kmod ' acute aeiouAEIOU
5480 \begin_layout Labeling
5481 \labelwidthstring 00.00.0000
5482 \begin_inset Flex CharStyle:Code
5485 \begin_layout Plain Layout
5491 Specify an exception to the accent character
5494 \begin_layout LyX-Code
5503 \begin_layout Standard
5504 This defines an exce
5545 have been assigned a keystroke with a previous
5548 \begin_inset Flex CharStyle:Code
5551 \begin_layout Plain Layout
5575 must not belong in the
5627 If such a declaration does not exist in
5635 \begin_inset Flex CharStyle:Code
5638 \begin_layout Plain Layout
5678 \begin_inset Flex CharStyle:Code
5681 \begin_layout Plain Layout
5695 \begin_layout Standard
5696 The following command produces causes äi to be produced when you enter acute-i
5700 \begin_layout LyX-Code
5714 \begin_layout Labeling
5715 \labelwidthstring 00.00.0000
5716 \begin_inset Flex CharStyle:Code
5719 \begin_layout Plain Layout
5725 Combine two accent characters
5728 \begin_layout LyX-Code
5734 accent1 accent2 allowed
5737 \begin_layout Standard
5738 This one is getting pretty esoteric.
5739 It allows you to combine the effect
5795 \begin_inset Flex CharStyle:Code
5798 \begin_layout Plain Layout
5826 \begin_layout Standard
5827 Consider this example from the
5828 \begin_inset Flex CharStyle:Code
5831 \begin_layout Plain Layout
5842 \begin_layout LyX-Code
5845 kmod ; acute aeioyvhAEIOYVH
5849 kcomb acute umlaut iyIY
5852 \begin_layout Standard
5853 This allows you to press
5854 \begin_inset Flex CharStyle:MenuItem
5857 \begin_layout Plain Layout
5865 and get the effect of
5866 \begin_inset Flex CharStyle:Code
5869 \begin_layout Plain Layout
5888 in this case cancels the last dead key, so if you press
5889 \begin_inset Flex CharStyle:MenuItem
5892 \begin_layout Plain Layout
5901 \begin_inset Flex CharStyle:Code
5904 \begin_layout Plain Layout
5917 \begin_layout Subsection
5921 \begin_layout Standard
5923 \begin_inset Flex CharStyle:Code
5926 \begin_layout Plain Layout
5934 mapping is performed, a
5935 \begin_inset Flex CharStyle:Code
5938 \begin_layout Plain Layout
5948 file maps the strings that the symbols generate to characters in the current
5950 The LyX distribution currently includes at least the
5951 \begin_inset Flex CharStyle:Code
5954 \begin_layout Plain Layout
5963 \begin_inset Flex CharStyle:Code
5966 \begin_layout Plain Layout
5977 \begin_layout Standard
5979 \begin_inset Flex CharStyle:Code
5982 \begin_layout Plain Layout
5990 file is a sequence of declarations of the form
5993 \begin_layout LyX-Code
6006 \begin_layout Standard
6007 For example, in order to map
6008 \begin_inset Flex CharStyle:MenuItem
6011 \begin_layout Plain Layout
6021 to the corresponding character in the iso-8859-1 set (233), the following
6025 \begin_layout LyX-Code
6033 \begin_layout Standard
6035 \begin_inset Flex CharStyle:Code
6038 \begin_layout Plain Layout
6047 \begin_inset Flex CharStyle:Code
6050 \begin_layout Plain Layout
6068 the same character can apply to more than one string.
6070 \begin_inset Flex CharStyle:Code
6073 \begin_layout Plain Layout
6084 \begin_layout LyX-Code
6096 \begin_inset Newline newline
6112 \begin_layout Standard
6113 If LyX cannot find a mapping for the string produced by the keystroke or
6114 a deadkey sequence, it will check if it looks like an accented char and
6115 try to draw an accent over the character on screen.
6118 \begin_layout Subsection
6122 \begin_layout Standard
6123 There is a second way to add support for international characters through
6124 so-called dead-keys.
6125 A dead-key works in combination with a letter to produce an accented character.
6126 Here, we'll explain how to create a really simple dead-key to illustrate
6130 \begin_layout Standard
6131 Suppose you happen to need the circumflex character,
6132 \begin_inset Quotes eld
6136 \begin_inset Quotes erd
6141 \begin_inset Flex CharStyle:MenuItem
6144 \begin_layout Plain Layout
6151 \begin_inset space ~
6155 \begin_inset Flex CharStyle:MenuItem
6158 \begin_layout Plain Layout
6164 ] to the LyX command
6165 \begin_inset Flex CharStyle:Code
6168 \begin_layout Plain Layout
6175 \begin_inset Flex CharStyle:Code
6178 \begin_layout Plain Layout
6185 Now, whenever you type the
6186 \begin_inset Flex CharStyle:MenuItem
6189 \begin_layout Plain Layout
6195 -key followed by a letter, that letter will have a circumflex accent on
6197 For example, the sequence
6198 \begin_inset Quotes eld
6202 \begin_inset Flex CharStyle:MenuItem
6205 \begin_layout Plain Layout
6212 \begin_inset Quotes erd
6215 produces the letter:
6216 \begin_inset Quotes eld
6220 \begin_inset Quotes erd
6224 If you tried to type
6225 \begin_inset Quotes eld
6229 \begin_inset Flex CharStyle:MenuItem
6232 \begin_layout Plain Layout
6239 \begin_inset Quotes erd
6242 , however, LyX will complain with a beep, since a
6243 \begin_inset Quotes eld
6247 \begin_inset Flex CharStyle:MenuItem
6250 \begin_layout Plain Layout
6257 \begin_inset Quotes erd
6260 never takes a circumflex accent.
6262 \begin_inset Flex CharStyle:MenuItem
6265 \begin_layout Plain Layout
6271 after a dead-key produces the bare-accent.
6272 Please note this last point! If you bind a key to a dead-key, you'll need
6273 to rebind the character on that key to yet another key.
6275 \begin_inset Flex CharStyle:MenuItem
6278 \begin_layout Plain Layout
6284 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
6287 \begin_layout Standard
6288 One common way to bind dead-keys is to use
6289 \begin_inset Flex CharStyle:MenuItem
6292 \begin_layout Plain Layout
6299 \begin_inset Flex CharStyle:MenuItem
6302 \begin_layout Plain Layout
6309 \begin_inset Flex CharStyle:MenuItem
6312 \begin_layout Plain Layout
6318 in combination with an accent, like
6319 \begin_inset Quotes eld
6323 \begin_inset Flex CharStyle:MenuItem
6326 \begin_layout Plain Layout
6333 \begin_inset Quotes erd
6337 \begin_inset Quotes eld
6341 \begin_inset Flex CharStyle:MenuItem
6344 \begin_layout Plain Layout
6351 \begin_inset Quotes erd
6355 \begin_inset Quotes eld
6359 \begin_inset Flex CharStyle:MenuItem
6362 \begin_layout Plain Layout
6369 \begin_inset Quotes erd
6373 Another way involves using
6374 \begin_inset Flex CharStyle:Code
6377 \begin_layout Plain Layout
6384 \begin_inset Flex CharStyle:Code
6387 \begin_layout Plain Layout
6393 to set up the special
6394 \begin_inset Flex CharStyle:Code
6397 \begin_layout Plain Layout
6405 \begin_inset Flex CharStyle:Code
6408 \begin_layout Plain Layout
6414 acts in some ways just like
6415 \begin_inset Flex CharStyle:MenuItem
6418 \begin_layout Plain Layout
6424 and permits you to bind keys to accented characters.
6425 You can also turn keys into dead-keys by binding them to something like
6427 \begin_inset Flex CharStyle:Code
6430 \begin_layout Plain Layout
6436 and then binding this symbolic key to the corresponding LyX command.
6440 \begin_layout Plain Layout
6445 : This is exactly what I do in my
6446 \begin_inset Flex CharStyle:Code
6449 \begin_layout Plain Layout
6456 \begin_inset Flex CharStyle:Code
6459 \begin_layout Plain Layout
6467 \begin_inset Flex CharStyle:MenuItem
6470 \begin_layout Plain Layout
6472 \begin_inset space ~
6481 \begin_inset Flex CharStyle:Code
6484 \begin_layout Plain Layout
6490 and a bunch of these
6491 \begin_inset Quotes eld
6495 \begin_inset Flex CharStyle:Code
6498 \begin_layout Plain Layout
6505 \begin_inset Quotes erd
6508 symbolic keys bound such things as
6509 \begin_inset Flex CharStyle:MenuItem
6512 \begin_layout Plain Layout
6514 \begin_inset space ~
6523 \begin_inset Flex CharStyle:MenuItem
6526 \begin_layout Plain Layout
6528 \begin_inset space ~
6537 This is how I produce my accented characters.
6542 You can make just about anything into the
6543 \begin_inset Flex CharStyle:Code
6546 \begin_layout Plain Layout
6553 \begin_inset Flex CharStyle:MenuItem
6556 \begin_layout Plain Layout
6562 keys, a spare function key, etc.
6563 As for the LyX commands that produce accents, check the entry for
6564 \begin_inset Flex CharStyle:Code
6567 \begin_layout Plain Layout
6578 You'll find the complete list there.
6581 \begin_layout Subsection
6582 Saving your Language Configuration
6585 \begin_layout Standard
6586 \begin_inset CommandInset label
6592 You can edit your preferences so that your desired language environment
6593 is automatically configured when LyX starts up, via the
6594 \begin_inset Flex CharStyle:MenuItem
6597 \begin_layout Plain Layout
6602 dit\SpecialChar \menuseparator
6615 \begin_layout Chapter
6616 Installing New Document Classes, Layouts, and Templates
6617 \begin_inset CommandInset label
6619 name "chap:textclass"
6627 \begin_layout Plain Layout
6628 Installing New Document Classes
6636 \begin_layout Standard
6637 In this chapter, we describe the procedures for creating and installing
6638 new LyX layout and template files, as well as offer a refresher on correctly
6639 installing new LaTeX document classes.
6640 Some definitions: a document class is a LaTeX file (usually ending in
6641 \begin_inset Flex CharStyle:Code
6644 \begin_layout Plain Layout
6651 \begin_inset Flex CharStyle:Code
6654 \begin_layout Plain Layout
6660 ) that describes the format of a document such as an article, report, journal
6661 preprint, etc, and all the commands needed to realize that format.
6662 A layout file is a LyX file that corresponds to a LaTeX document class
6663 and that tells LyX how to
6664 \begin_inset Quotes eld
6668 \begin_inset Quotes erd
6671 things on the screen to make the display look something like the final
6673 More precisely, a layout file describes a
6674 \begin_inset Quotes eld
6678 \begin_inset Quotes erd
6681 which is the internal construct LyX uses to render the screen display.
6683 \begin_inset Quotes eld
6687 \begin_inset Quotes erd
6691 \begin_inset Quotes eld
6695 \begin_inset Quotes erd
6698 can be used somewhat interchangeably, but it is better to refer to the
6699 file as the layout, and the thing living in LyX's memory as the text class.
6700 A template file is simply a LyX document that contains a set of predefined
6701 entries for a given document class---entries that are generally required
6703 Templates are especially useful for things like journal manuscripts that
6704 are to be submitted electronically.
6707 \begin_layout Section
6708 Installing a new LaTeX package
6711 \begin_layout Standard
6712 Some installations may not include a LaTeX package that you would like to
6714 For example, you might need FoilTeX, a common (and very powerful) package
6715 for preparing slides or viewgraphs for overhead projectors.
6716 On some systems, you may have a GUI for installing such packages: MikTeX
6717 on Windows®, for example.
6720 \begin_layout Standard
6721 If you don't have such a GUI, then you can follow these steps.
6724 \begin_layout Enumerate
6725 Get the package from
6726 \begin_inset CommandInset href
6729 target "http://www.ctan.org/"
6736 \begin_layout Enumerate
6737 You can install this package in several different places.
6738 If you want it to be available for all users on your system, then you should
6739 install it in your `local' TeX tree; if you want (or need) it to be available
6740 just for you, then you can install it in your own `user' TeX tree.
6741 Where these should be created, if they do not already exist, depends upon
6742 the details of your system.
6743 To find out, look in the file
6744 \begin_inset Flex CharStyle:Code
6747 \begin_layout Plain Layout
6757 \begin_layout Plain Layout
6758 This usually lives in the directory
6759 \begin_inset Flex CharStyle:Code
6762 \begin_layout Plain Layout
6768 , though you can run
6769 \begin_inset Flex CharStyle:Code
6772 \begin_layout Plain Layout
6783 The location of the `local' TeX tree is defined by
6784 \begin_inset Flex CharStyle:Code
6787 \begin_layout Plain Layout
6793 ; this is usually somewhere like
6794 \begin_inset Flex CharStyle:Code
6797 \begin_layout Plain Layout
6798 /usr/local/share/texmf/
6804 The `user' TeX tree is defined by
6805 \begin_inset Flex CharStyle:Code
6808 \begin_layout Plain Layout
6815 \begin_inset Flex CharStyle:Code
6818 \begin_layout Plain Layout
6825 (If these variables are not predefined, you can define them.) You'll probably
6826 need root permissions to create or modify the `local' tree; but your `user'
6827 tree shouldn't have such limitations.
6830 \begin_layout Enumerate
6832 \begin_inset Flex CharStyle:Code
6835 \begin_layout Plain Layout
6842 \begin_inset Flex CharStyle:Code
6845 \begin_layout Plain Layout
6852 \begin_inset Flex CharStyle:Code
6855 \begin_layout Plain Layout
6863 \begin_inset Newline newline
6867 \begin_inset Flex CharStyle:Code
6870 \begin_layout Plain Layout
6871 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
6877 \begin_inset Newline newline
6880 But, again, most of this will
6881 \begin_inset Quotes eld
6885 \begin_inset Quotes erd
6891 \begin_layout Enumerate
6896 \begin_layout Plain Layout
6897 We'll assume henceforth that you're defining `local' TeX tree.
6898 If you're defining a user tree, just adjust as necessary.
6904 You must follow the directory structure of your existing
6905 \begin_inset Flex CharStyle:Code
6908 \begin_layout Plain Layout
6914 directory, which will be found at
6915 \begin_inset Flex CharStyle:Code
6918 \begin_layout Plain Layout
6925 For example, latex packages should go under
6926 \begin_inset Flex CharStyle:Code
6929 \begin_layout Plain Layout
6930 $TEXMFLOCAL/tex/latex/
6938 \begin_layout Enumerate
6939 Install the package.
6940 For example, you would unpack the FoilTeX tarball and copy it to
6941 \begin_inset Flex CharStyle:Code
6944 \begin_layout Plain Layout
6945 $TEXMFLOCAL/tex/latex/foiltex
6952 \begin_inset Flex CharStyle:Code
6955 \begin_layout Plain Layout
6961 directory contains various files.
6964 \begin_layout Enumerate
6966 \begin_inset Flex CharStyle:Code
6969 \begin_layout Plain Layout
6977 \begin_inset Flex CharStyle:Code
6980 \begin_layout Plain Layout
6989 \begin_layout Standard
6990 Your package is now installed and available to LaTeX.
6991 To make it available to LyX, you need to create a Layout file, if one is
6992 not already available.
6993 (See the next section.) Once you have a layout file, you need only reconfigure
6995 \begin_inset Flex CharStyle:MenuItem
6998 \begin_layout Plain Layout
7003 ools\SpecialChar \menuseparator
7013 ) and then restart LyX.
7014 You should then see your new package---for example
7015 \begin_inset Flex CharStyle:MenuItem
7018 \begin_layout Plain Layout
7025 \begin_inset Flex CharStyle:MenuItem
7028 \begin_layout Plain Layout
7033 ocument\SpecialChar \menuseparator
7044 \begin_inset Flex CharStyle:MenuItem
7047 \begin_layout Plain Layout
7057 \begin_layout Section
7058 \begin_inset CommandInset label
7067 \begin_layout Standard
7068 This section describes how to write and install your own LyX layout files
7069 and walks through the
7070 \begin_inset Flex CharStyle:Code
7073 \begin_layout Plain Layout
7079 text class format as an example.
7081 \begin_inset Flex CharStyle:Code
7084 \begin_layout Plain Layout
7090 files describe what paragraph and character styles are available for a
7091 given document class and how LyX should display them.
7092 We try to provide a thorough description of the process here; however,
7093 there are so many different types of documents supported by LaTeX classes
7094 that we can't hope to cover every different possibility or problem you
7096 (The LyX users' list is frequented by people with lots of experience with
7097 layout design who are willing to share what they've learned.)
7100 \begin_layout Standard
7101 As you prepare to write a new layout, it is extremely helpful to look at
7102 the example layouts distributed with LyX.
7103 If you use a nice LaTeX document class that might be of interest for others,
7104 too, and have a nice corresponding LyX layout, feel free to contribute
7105 the stuff to us, so we may put it into the distribution.
7107 \begin_inset CommandInset href
7109 name "section on the LyX wiki"
7110 target "http://wiki.lyx.org/Layouts/Layouts"
7114 for this kind of material.
7117 \begin_layout Standard
7118 All the tags described in this chapter are case-insensitive; this means
7120 \begin_inset Flex CharStyle:Code
7123 \begin_layout Plain Layout
7130 \begin_inset Flex CharStyle:Code
7133 \begin_layout Plain Layout
7140 \begin_inset Flex CharStyle:Code
7143 \begin_layout Plain Layout
7149 are really the same command.
7150 The possible values are printed in brackets after the feature's name.
7151 The default value if a feature isn't specified inside a text class-description
7153 \begin_inset Flex CharStyle:Code
7156 \begin_layout Plain Layout
7165 If the argument has a datatype like
7166 \begin_inset Quotes eld
7170 \begin_inset Quotes erd
7174 \begin_inset Quotes eld
7178 \begin_inset Quotes erd
7181 , the default is shown like this:
7182 \begin_inset Flex CharStyle:Code
7185 \begin_layout Plain Layout
7196 \begin_layout Subsection
7197 \begin_inset CommandInset label
7199 name "sub:Layout-modules"
7206 \begin_layout Standard
7207 Similar to layout files, and new with LyX 1.6, are layout
7212 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
7213 some modules---such as the Endnotes module---provide support for just such
7215 In a sense, layout modules are similar to included files---files like
7216 \begin_inset Flex CharStyle:Code
7219 \begin_layout Plain Layout
7225 ---in that modules are not specific to a given document layout but may be
7226 used with many different layouts.
7227 The difference is that using a layout module does not require editing the
7229 Rather, modules are selected in the
7230 \begin_inset Flex CharStyle:MenuItem
7233 \begin_layout Plain Layout
7238 ocument\SpecialChar \menuseparator
7251 \begin_layout Standard
7252 Building modules is the easiest way to get started with layout editing,
7253 since it can be as simple as adding a single new paragraph or flex inset.
7254 But modules may, in principle, contain anything a layout file can contain.
7257 \begin_layout Standard
7258 A module must begin with a line like the following:
7261 \begin_layout LyX-Code
7264 DeclareLyXModule[endnotes.sty]{Endnotes}
7267 \begin_layout Standard
7268 The argument in square brackets is optional: It declares any LaTeX packages
7269 on which the module depends.
7270 The mandatory argument, in curly brackets, is the name of the module, as
7272 \begin_inset Flex CharStyle:MenuItem
7275 \begin_layout Plain Layout
7276 Document\SpecialChar \menuseparator
7286 \begin_layout Standard
7287 The module declaration should then be followed by lines like the following:
7290 \begin_layout LyX-Code
7294 \begin_layout LyX-Code
7295 #Adds an endnote command, in addition to footnotes.
7299 \begin_layout LyX-Code
7300 #You will need to add
7302 theendnotes in ERT where you
7305 \begin_layout LyX-Code
7306 #want the endnotes to appear.
7310 \begin_layout LyX-Code
7314 \begin_layout LyX-Code
7315 #Requires: somemodule | othermodule
7318 \begin_layout LyX-Code
7319 #Excludes: badmodule
7322 \begin_layout Standard
7323 The description is used in
7324 \begin_inset Flex CharStyle:MenuItem
7327 \begin_layout Plain Layout
7328 Document\SpecialChar \menuseparator
7334 to provide the user with information about what the module does.
7336 \begin_inset Flex CharStyle:Code
7339 \begin_layout Plain Layout
7345 line is used to identify other modules with which this one must be used;
7347 \begin_inset Flex CharStyle:Code
7350 \begin_layout Plain Layout
7356 line is used to identify modules with which this one may not be used.
7357 Both are optional, and, as shown, multiple modules should be separated
7358 with the pipe symbol: |.
7359 Note that the required modules are treated disjunctively:
7363 of the required modules must be used.
7368 excluded module may be used.
7369 Note that modules are identified here by their
7373 without the .module extension.
7375 \begin_inset Flex CharStyle:Code
7378 \begin_layout Plain Layout
7385 \begin_inset Flex CharStyle:Code
7388 \begin_layout Plain Layout
7397 \begin_layout Standard
7398 After creating a new module, you will need to reconfigure and then restart
7399 LyX for the module to appear in the menu.
7400 However, changes you make to the module will be seen immediately, if you
7402 \begin_inset Flex CharStyle:MenuItem
7405 \begin_layout Plain Layout
7406 Document\SpecialChar \menuseparator
7412 , highlight something, and then hit
7413 \begin_inset Quotes eld
7417 \begin_inset Quotes erd
7423 It is strongly recommended that you save your work before doing so
7428 it is strongly recommended that you not attempt to edit modules while simultaneo
7429 usly working on documents
7432 Though of course the developers strive to keep LyX stable in such situations,
7433 syntax errors and the like in your module file could cause strange behavior.
7436 \begin_layout Subsection
7437 Supporting new document classes
7440 \begin_layout Standard
7441 There are two situations you are likely to encounter when wanting to support
7442 a new LaTeX document class, involving LaTeX2e class (
7443 \begin_inset Flex CharStyle:Code
7446 \begin_layout Plain Layout
7453 \begin_inset Flex CharStyle:Code
7456 \begin_layout Plain Layout
7463 Supporting a style file is usually fairly easy.
7464 Supporting a new document class is a bit harder.
7467 \begin_layout Subsection
7469 \begin_inset Flex CharStyle:MenuItem
7472 \begin_layout Plain Layout
7481 \begin_layout Standard
7482 If your new document class is provided as a style file that is used in conjuncti
7483 on with an existing, supported document class---for the sake of the example,
7484 we'll assume that the style file is called
7485 \begin_inset Flex CharStyle:MenuItem
7488 \begin_layout Plain Layout
7494 and it is meant to be used with
7495 \begin_inset Flex CharStyle:MenuItem
7498 \begin_layout Plain Layout
7504 , which is a standard class---start by copying the existing class's layout
7505 file into your local directory:
7508 \begin_layout LyX-Code
7509 cp report.layout ~/.lyx/layouts/myclass.layout
7512 \begin_layout Standard
7514 \begin_inset Flex CharStyle:Code
7517 \begin_layout Plain Layout
7523 and change the line:
7526 \begin_layout LyX-Code
7529 DeclareLaTeXClass{report}
7532 \begin_layout Standard
7536 \begin_layout LyX-Code
7539 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
7542 \begin_layout Standard
7546 \begin_layout LyX-Code
7548 \begin_inset Newline newline
7554 \begin_inset Newline newline
7560 \begin_layout Standard
7561 near the top of the file.
7564 \begin_layout Standard
7565 Start LyX and select
7566 \begin_inset Flex CharStyle:MenuItem
7569 \begin_layout Plain Layout
7574 ools\SpecialChar \menuseparator
7585 Then restart LyX and try creating a new document.
7587 \begin_inset Flex CharStyle:MenuItem
7590 \begin_layout Plain Layout
7596 " as a document class option in the
7597 \begin_inset Flex CharStyle:MenuItem
7600 \begin_layout Plain Layout
7605 ocument\SpecialChar \menuseparator
7616 It is likely that some of the sectioning commands and such in your new
7617 class will work differently from how they worked in the base class---
7618 \begin_inset Flex CharStyle:Code
7621 \begin_layout Plain Layout
7627 in this example---so you can fiddle around with the settings for the different
7628 sections if you wish.
7631 \begin_layout Subsection
7633 \begin_inset Flex CharStyle:MenuItem
7636 \begin_layout Plain Layout
7645 \begin_layout Standard
7646 There are two possibilities here.
7647 One is that the class file is itself based upon an existing document class.
7648 For example, many thesis classes are based upon
7649 \begin_inset Flex CharStyle:MenuItem
7652 \begin_layout Plain Layout
7659 To see whether yours is, look for a line like
7662 \begin_layout LyX-Code
7668 \begin_layout Standard
7670 If so, then you may proceed largely as in the previous section, though
7671 the DeclareLaTeXClass line will be different.
7672 If your new class is thesis, and it is based upon book, then the line should
7677 \begin_layout Plain Layout
7678 And it will be easiest if you save the file to
7679 \begin_inset Flex CharStyle:Code
7682 \begin_layout Plain Layout
7688 : LyX assumes that the document class has the same name as the layout file.
7697 \begin_layout LyX-Code
7700 DeclareLaTeXClass[thesis,book]{thesis}
7703 \begin_layout Standard
7704 If, on the other hand, the new class is not based upon an existing class,
7705 you will probably have to
7706 \begin_inset Quotes eld
7710 \begin_inset Quotes erd
7714 We strongly suggest copying an existing layout file which uses a similar
7715 LaTeX class and then modifying it, if you can do so.
7716 At least use an existing file as a starting point so you can find out what
7717 items you need to worry about.
7718 Again, the specifics are covered below.
7721 \begin_layout Section
7722 Declaring a new text class
7725 \begin_layout Standard
7726 When it's finally time to get your hands dirty and create or edit your own
7727 layout file, the following sections describe what you're up against.
7728 Our advice is to go slowly, save and test often, listen to soothing music,
7729 and enjoy one or two of your favorite adult beverages; more if you are
7730 getting particularly stuck.
7731 It's really not that hard, except that the multitude of options can become
7732 overwhelming if you try to do to much in one sitting.
7733 Go have another adult beverage, just for good measure.
7736 \begin_layout Standard
7740 \begin_layout Standard
7741 Lines in a layout file which begin with a
7742 \begin_inset Flex CharStyle:Code
7745 \begin_layout Plain Layout
7752 There is one exception to this rule: all layouts should begin with lines
7756 \begin_layout LyX-Code
7759 #% Do not delete the line below; configure depends on this
7762 \begin_layout LyX-Code
7767 DeclareLaTeXClass{article}
7770 \begin_layout Standard
7771 The second line is used when you configure LyX.
7772 The layout file is read by the LaTeX script
7773 \begin_inset Flex CharStyle:Code
7776 \begin_layout Plain Layout
7782 , in a special mode where
7783 \begin_inset Flex CharStyle:Code
7786 \begin_layout Plain Layout
7793 The first line is just a LaTeX comment, and the second one contains the
7794 declaration of the text class.
7795 If these lines appear in a file named
7796 \begin_inset Flex CharStyle:Code
7799 \begin_layout Plain Layout
7805 , then they define a text class of name
7806 \begin_inset Flex CharStyle:Code
7809 \begin_layout Plain Layout
7815 (the name of the layout file) which uses the LaTeX document class
7816 \begin_inset Flex CharStyle:Code
7819 \begin_layout Plain Layout
7825 (the default is to use the same name as the layout).
7827 \begin_inset Quotes eld
7831 \begin_inset Quotes erd
7834 that appears above is used as a description of the text class in the
7835 \begin_inset Flex CharStyle:MenuItem
7838 \begin_layout Plain Layout
7843 ocument\SpecialChar \menuseparator
7856 \begin_layout Standard
7857 Let's assume that you wrote your own text class that uses the
7858 \begin_inset Flex CharStyle:Code
7861 \begin_layout Plain Layout
7867 document class, but where you changed the appearance of the section headings.
7868 If you put it in a file
7869 \begin_inset Flex CharStyle:Code
7872 \begin_layout Plain Layout
7878 , the header of this file should be:
7881 \begin_layout LyX-Code
7884 #% Do not delete the line below; configure depends on this
7887 \begin_layout LyX-Code
7892 DeclareLaTeXClass[article]{article (with my own headings)}
7895 \begin_layout Standard
7896 This declares a text class
7897 \begin_inset Flex CharStyle:Code
7900 \begin_layout Plain Layout
7906 , associated with the LaTeX document class
7907 \begin_inset Flex CharStyle:Code
7910 \begin_layout Plain Layout
7917 \begin_inset Quotes eld
7920 article (with my own headings)
7921 \begin_inset Quotes erd
7925 If your text class depends on several packages, you can declare it as:
7928 \begin_layout LyX-Code
7931 #% Do not delete the line below; configure depends on this
7934 \begin_layout LyX-Code
7939 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7942 \begin_layout Standard
7943 This indicates that your text class uses the foo.sty package.
7944 Finally, it is also possible to declare classes for DocBook code.
7945 Typical declarations will look like
7948 \begin_layout LyX-Code
7951 #% Do not delete the line below; configure depends on this
7954 \begin_layout LyX-Code
7959 DeclareDocBookClass[article]{SGML (DocBook article)}
7962 \begin_layout Standard
7963 Note that these declarations can also be given an optional parameter declaring
7964 the name of the document class (but not a list).
7967 \begin_layout Standard
7968 So, to be as explicit as possible, the form of the layout declaration is:
7971 \begin_layout LyX-Code
7976 DeclareLaTeXClass[class,package.sty]{layout description}
7979 \begin_layout Standard
7980 The class need only be specified if the name of the LaTeX class file and
7981 the name of the layout file are different; if the name of the classfile
7982 is not specified, then LyX will simply assume that it is the same as the
7983 name of the layout file.
7986 \begin_layout Standard
7987 When the text class has been modified to your taste, all you have to do
7988 is to copy it either to
7989 \begin_inset Flex CharStyle:Code
7992 \begin_layout Plain Layout
7999 \begin_inset Flex CharStyle:Code
8002 \begin_layout Plain Layout
8009 \begin_inset Flex CharStyle:MenuItem
8012 \begin_layout Plain Layout
8017 ools\SpecialChar \menuseparator
8027 , exit LyX and restart it.
8028 Then your new text class should be available along with the others.
8031 \begin_layout Standard
8032 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
8033 you made to your layout files.
8034 As a result, editing layout files could be very time consuming.
8035 Beginning with 1.6, however, you can force a reload of the layout currently
8036 in use by using the LyX function
8037 \begin_inset Flex CharStyle:MenuItem
8040 \begin_layout Plain Layout
8047 There is no default binding for this function---though, of course, you
8048 can bind it to a key yourself (see section
8049 \begin_inset CommandInset ref
8051 reference "sec:bindings"
8056 If you want to use this function, then, you should simply enter it in the
8062 : This is very much an `advanced feature'.
8067 recommended that you save your work before using this function.
8072 recommended that you not attempt to edit your layout while simultaneously
8073 working on a document that you care about.
8074 Use a test document.
8075 Syntax errors and the like in your layout file could cause peculiar behavior.
8076 In particular, such errors could cause LyX to regard the current layout
8077 as invalid and to attempt to switch to some other layout.
8078 The LyX team strives to keep LyX stable in such situations, but safe is
8082 \begin_layout Subsection
8086 \begin_layout Standard
8087 The first non-comment line must contain the file format number:
8090 \begin_layout Description
8091 \begin_inset Flex CharStyle:Code
8094 \begin_layout Plain Layout
8101 \begin_inset Flex CharStyle:Code
8104 \begin_layout Plain Layout
8110 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
8111 don't have an explicit file format).
8112 The file format that is documented here is format 7.
8115 \begin_layout Subsection
8116 General text class parameters
8119 \begin_layout Standard
8120 These are the general parameters which describe the form of the entire document:
8123 \begin_layout Description
8124 \begin_inset Flex CharStyle:Code
8127 \begin_layout Plain Layout
8133 Adds information to the document preamble.
8135 \begin_inset Quotes eld
8139 \begin_inset Flex CharStyle:Code
8142 \begin_layout Plain Layout
8149 \begin_inset Quotes erd
8155 \begin_layout Description
8156 \begin_inset Flex CharStyle:Code
8159 \begin_layout Plain Layout
8165 Describes various global options supported by the document class.
8167 \begin_inset space ~
8171 \begin_inset CommandInset ref
8173 reference "sec:classoptions"
8179 \begin_inset Quotes eld
8183 \begin_inset Flex CharStyle:Code
8186 \begin_layout Plain Layout
8193 \begin_inset Quotes erd
8199 \begin_layout Description
8200 \begin_inset Flex CharStyle:Code
8203 \begin_layout Plain Layout
8210 \begin_inset Flex CharStyle:Code
8213 \begin_layout Plain Layout
8222 \begin_inset Flex CharStyle:Code
8225 \begin_layout Plain Layout
8231 ] Whether the class should default to having one or two columns.
8232 Can be changed in the
8233 \begin_inset Flex CharStyle:MenuItem
8236 \begin_layout Plain Layout
8241 ocument\SpecialChar \menuseparator
8254 \begin_layout Description
8255 \begin_inset Flex CharStyle:Code
8258 \begin_layout Plain Layout
8264 This sequence defines a new counter.
8266 \begin_inset space ~
8270 \begin_inset CommandInset ref
8272 reference "sec:counter"
8278 \begin_inset Quotes eld
8282 \begin_inset Flex CharStyle:Code
8285 \begin_layout Plain Layout
8292 \begin_inset Quotes erd
8298 \begin_layout Description
8299 \begin_inset Flex CharStyle:Code
8302 \begin_layout Plain Layout
8308 Sets the default font used to display the document.
8310 \begin_inset space ~
8314 \begin_inset CommandInset ref
8316 reference "sec:fonts"
8320 for how to declare fonts.
8322 \begin_inset Quotes eld
8326 \begin_inset Flex CharStyle:Code
8329 \begin_layout Plain Layout
8336 \begin_inset Quotes erd
8342 \begin_layout Description
8343 \begin_inset Flex CharStyle:Code
8346 \begin_layout Plain Layout
8353 \begin_inset Flex CharStyle:Code
8356 \begin_layout Plain Layout
8362 ] This is the style that will be assigned to new paragraphs, usually
8363 \begin_inset Flex CharStyle:MenuItem
8366 \begin_layout Plain Layout
8373 This will default to the first defined style if not given, but you are
8374 highly encouraged to use this directive.
8377 \begin_layout Description
8378 \begin_inset Flex CharStyle:Code
8381 \begin_layout Plain Layout
8387 Defines a new float.
8389 \begin_inset space ~
8393 \begin_inset CommandInset ref
8395 reference "sec:floats"
8401 \begin_inset Quotes eld
8405 \begin_inset Flex CharStyle:Code
8408 \begin_layout Plain Layout
8415 \begin_inset Quotes erd
8421 \begin_layout Description
8422 \begin_inset Flex CharStyle:Code
8425 \begin_layout Plain Layout
8431 As its name implies, this command allows you to include another layout
8432 definition file within yours to avoid duplicating commands.
8433 Common examples are the standard layout files, for example,
8434 \begin_inset Flex CharStyle:Code
8437 \begin_layout Plain Layout
8443 , which contains most of the basic layouts.
8446 \begin_layout Description
8447 \begin_inset Flex CharStyle:Code
8450 \begin_layout Plain Layout
8456 This section (re-)defines the layout of an inset.
8457 It can be applied to an existing inset of to a new, user-defined inset,
8458 e.g., a new character style.
8460 \begin_inset space ~
8464 \begin_inset CommandInset ref
8466 reference "sec:charstyle"
8470 for more information.
8472 \begin_inset Quotes eld
8476 \begin_inset Flex CharStyle:Code
8479 \begin_layout Plain Layout
8486 \begin_inset Quotes erd
8492 \begin_layout Description
8493 \begin_inset Flex CharStyle:Code
8496 \begin_layout Plain Layout
8505 \begin_layout Description
8506 \begin_inset Flex CharStyle:Code
8509 \begin_layout Plain Layout
8515 This command deletes an existing float.
8516 This is particularly useful when you want to suppress a float that has
8517 be defined in an input file.
8520 \begin_layout Description
8521 \begin_inset Flex CharStyle:Code
8524 \begin_layout Plain Layout
8530 This command deletes an existing style.
8531 This is particularly useful when you want to suppress a style that has
8532 be defined in an input file.
8535 \begin_layout Description
8536 \begin_inset Flex CharStyle:Code
8539 \begin_layout Plain Layout
8548 \begin_layout Description
8549 \begin_inset Flex CharStyle:Code
8552 \begin_layout Plain Layout
8563 \begin_inset Flex CharStyle:Code
8566 \begin_layout Plain Layout
8577 \begin_inset Flex CharStyle:Code
8580 \begin_layout Plain Layout
8587 \begin_inset Flex CharStyle:Code
8590 \begin_layout Plain Layout
8596 ] The class default pagestyle.
8597 Can be changed in the
8598 \begin_inset Flex CharStyle:MenuItem
8601 \begin_layout Plain Layout
8606 ocument\SpecialChar \menuseparator
8619 \begin_layout Description
8620 \begin_inset Flex CharStyle:Code
8623 \begin_layout Plain Layout
8629 Sets the preamble for the LaTeX document.
8630 Note that this will completely override any prior
8631 \begin_inset Flex CharStyle:Code
8634 \begin_layout Plain Layout
8641 \begin_inset Flex CharStyle:Code
8644 \begin_layout Plain Layout
8652 \begin_inset Quotes eld
8656 \begin_inset Flex CharStyle:Code
8659 \begin_layout Plain Layout
8666 \begin_inset Quotes erd
8672 \begin_layout Description
8673 \begin_inset Flex CharStyle:Code
8676 \begin_layout Plain Layout
8683 \begin_inset CommandInset label
8690 \begin_inset Flex CharStyle:Code
8693 \begin_layout Plain Layout
8700 \begin_inset Flex CharStyle:Code
8703 \begin_layout Plain Layout
8712 \begin_inset Flex CharStyle:Code
8715 \begin_layout Plain Layout
8721 ] Whether the class already provides the feature
8722 \begin_inset Flex CharStyle:Code
8725 \begin_layout Plain Layout
8732 A feature is in general the name of a package (
8733 \begin_inset Flex CharStyle:Code
8736 \begin_layout Plain Layout
8743 \begin_inset Flex CharStyle:Code
8746 \begin_layout Plain Layout
8752 , \SpecialChar \ldots{}
8754 \begin_inset Flex CharStyle:Code
8757 \begin_layout Plain Layout
8764 \begin_inset Flex CharStyle:Code
8767 \begin_layout Plain Layout
8773 ,\SpecialChar \ldots{}
8774 ); the complete list of supported features is unfortunately not documented
8775 outside the LyX source code---but see
8776 \begin_inset Flex CharStyle:Code
8779 \begin_layout Plain Layout
8785 if you're interested.
8787 \begin_inset Flex CharStyle:MenuItem
8790 \begin_layout Plain Layout
8795 elp\SpecialChar \menuseparator
8805 also gives an overview of the supported packages.
8808 \begin_layout Description
8809 \begin_inset Flex CharStyle:Code
8812 \begin_layout Plain Layout
8819 \begin_inset Flex CharStyle:Code
8822 \begin_layout Plain Layout
8828 ] Whether the class requires the feature
8829 \begin_inset Flex CharStyle:Code
8832 \begin_layout Plain Layout
8839 Multiple features must be separated by commas.
8840 Note that you can only request supported features.
8843 \begin_layout Description
8844 \begin_inset Flex CharStyle:Code
8847 \begin_layout Plain Layout
8856 \begin_layout Description
8857 \begin_inset Flex CharStyle:Code
8860 \begin_layout Plain Layout
8869 \begin_layout Description
8870 \begin_inset Flex CharStyle:Code
8873 \begin_layout Plain Layout
8882 \begin_inset Flex CharStyle:Code
8885 \begin_layout Plain Layout
8896 \begin_inset Flex CharStyle:Code
8899 \begin_layout Plain Layout
8905 ] Whether the class-default should be printing on one or both sides of the
8907 Can be changed in the
8908 \begin_inset Flex CharStyle:MenuItem
8911 \begin_layout Plain Layout
8916 ocument\SpecialChar \menuseparator
8929 \begin_layout Description
8930 \begin_inset Flex CharStyle:Code
8933 \begin_layout Plain Layout
8939 This sequence defines a new paragraph style.
8940 If the style already exists, it will redefine some of its parameters instead.
8942 \begin_inset space ~
8946 \begin_inset CommandInset ref
8948 reference "sec:style"
8954 \begin_inset Quotes eld
8958 \begin_inset Flex CharStyle:Code
8961 \begin_layout Plain Layout
8968 \begin_inset Quotes erd
8974 \begin_layout Description
8975 \begin_inset Flex CharStyle:Code
8978 \begin_layout Plain Layout
8985 \begin_inset Flex CharStyle:Code
8988 \begin_layout Plain Layout
8994 ] The name of the command or environment to be used with
8995 \begin_inset Flex CharStyle:Code
8998 \begin_layout Plain Layout
9007 \begin_layout Description
9008 \begin_inset Flex CharStyle:Code
9011 \begin_layout Plain Layout
9018 \begin_inset Flex CharStyle:Code
9021 \begin_layout Plain Layout
9030 \begin_inset Flex CharStyle:Code
9033 \begin_layout Plain Layout
9039 ] Indicates what kind of markup is used to define the title of a document.
9041 \begin_inset Flex CharStyle:Code
9044 \begin_layout Plain Layout
9050 means that the macro with name
9051 \begin_inset Flex CharStyle:Code
9054 \begin_layout Plain Layout
9060 will be inserted after the last layout which has
9061 \begin_inset Quotes eld
9065 \begin_inset Flex CharStyle:Code
9068 \begin_layout Plain Layout
9075 \begin_inset Quotes erd
9080 \begin_inset Flex CharStyle:Code
9083 \begin_layout Plain Layout
9089 corresponds to the case where the block of paragraphs which have
9090 \begin_inset Quotes eld
9094 \begin_inset Flex CharStyle:Code
9097 \begin_layout Plain Layout
9104 \begin_inset Quotes erd
9107 should be enclosed into the
9108 \begin_inset Flex CharStyle:Code
9111 \begin_layout Plain Layout
9120 \begin_layout Description
9121 \begin_inset Flex CharStyle:Code
9124 \begin_layout Plain Layout
9133 \begin_layout Subsection
9134 \begin_inset Flex CharStyle:Code
9137 \begin_layout Plain Layout
9146 \begin_layout Standard
9147 \begin_inset CommandInset label
9149 name "sec:classoptions"
9154 \begin_inset Flex CharStyle:Code
9157 \begin_layout Plain Layout
9163 section can contain the following entries:
9166 \begin_layout Description
9167 \begin_inset Flex CharStyle:Code
9170 \begin_layout Plain Layout
9177 \begin_inset Flex CharStyle:Code
9180 \begin_layout Plain Layout
9186 ] The list of available font sizes for the document's main font, separated
9188 \begin_inset Quotes eld
9192 \begin_inset Flex CharStyle:Code
9195 \begin_layout Plain Layout
9202 \begin_inset Quotes erd
9208 \begin_layout Description
9209 \begin_inset Flex CharStyle:Code
9212 \begin_layout Plain Layout
9221 \begin_layout Description
9222 \begin_inset Flex CharStyle:Code
9225 \begin_layout Plain Layout
9232 \begin_inset Flex CharStyle:Code
9235 \begin_layout Plain Layout
9236 string="empty|plain|headings|fancy"
9241 ] The list of available page styles, separated by
9242 \begin_inset Quotes eld
9246 \begin_inset Flex CharStyle:Code
9249 \begin_layout Plain Layout
9256 \begin_inset Quotes erd
9262 \begin_layout Description
9263 \begin_inset Flex CharStyle:Code
9266 \begin_layout Plain Layout
9273 \begin_inset Flex CharStyle:Code
9276 \begin_layout Plain Layout
9282 ] Some document class options, separated by a comma, that will be added
9283 to the optional part of the
9284 \begin_inset Flex CharStyle:Code
9287 \begin_layout Plain Layout
9298 \begin_layout Standard
9300 \begin_inset Flex CharStyle:Code
9303 \begin_layout Plain Layout
9309 section must end with
9310 \begin_inset Quotes eld
9314 \begin_inset Flex CharStyle:Code
9317 \begin_layout Plain Layout
9324 \begin_inset Quotes erd
9330 \begin_layout Subsection
9334 \begin_layout Standard
9335 \begin_inset CommandInset label
9341 A paragraph style description looks like this:
9345 \begin_layout Plain Layout
9346 Note that this will either define a new layout or modify an existing one.
9354 \begin_layout LyX-Code
9361 \begin_layout LyX-Code
9365 \begin_layout LyX-Code
9369 \begin_layout Standard
9370 where the following commands are allowed:
9373 \begin_layout Description
9374 \begin_inset Flex CharStyle:Code
9377 \begin_layout Plain Layout
9384 \begin_inset Flex CharStyle:Code
9387 \begin_layout Plain Layout
9392 , left, right, center
9397 ] Paragraph alignment.
9400 \begin_layout Description
9401 \begin_inset Flex CharStyle:Code
9404 \begin_layout Plain Layout
9411 \begin_inset Flex CharStyle:Code
9414 \begin_layout Plain Layout
9419 , left, right, center
9424 ] A comma separated list of permitted alignments.
9425 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9427 For example a right-aligned or centered enumeration isn't possible.)
9430 \begin_layout Description
9431 \begin_inset Flex CharStyle:Code
9434 \begin_layout Plain Layout
9441 \begin_inset Flex CharStyle:Code
9444 \begin_layout Plain Layout
9454 \begin_layout Plain Layout
9455 Note that a `float' here is a real number, such as: 1.5.
9460 The vertical space with which the last of a chain of paragraphs with this
9461 layout is separated from the following paragraph.
9462 If the next paragraph has another layout, the separations are not simply
9463 added, but the maximum is taken.
9466 \begin_layout Description
9467 \begin_inset Flex CharStyle:Code
9470 \begin_layout Plain Layout
9477 \begin_inset Flex CharStyle:Code
9480 \begin_layout Plain Layout
9486 The category for this style.
9487 This is used to group related styles in the Layout combobox on the toolbar.
9488 Any string can be used, but you may want to use existing categories with
9493 \begin_layout Description
9494 \begin_inset Flex CharStyle:Code
9497 \begin_layout Plain Layout
9506 \begin_layout Description
9507 \begin_inset Flex CharStyle:Code
9510 \begin_layout Plain Layout
9517 \begin_inset Flex CharStyle:Code
9520 \begin_layout Plain Layout
9526 Copies all the features of an existing style into the current one.
9530 \begin_layout Description
9531 \begin_inset Flex CharStyle:Code
9534 \begin_layout Plain Layout
9540 The name of a style whose preamble should be output
9545 This allows to ensure some ordering of the preamble snippets when macros
9546 definitions depend on one another.
9550 \begin_layout Plain Layout
9551 Note that, besides that functionality, there is no way to ensure any ordering
9553 The ordering that you see in a given version of LyX may change without
9554 warning in later versions.
9562 \begin_layout Description
9563 \begin_inset Flex CharStyle:Code
9566 \begin_layout Plain Layout
9573 \begin_inset Flex CharStyle:Code
9576 \begin_layout Plain Layout
9581 , Box, Filled_Box, Static
9586 ] The type of label that stands at the end of the paragraph (or sequence
9588 \begin_inset Flex CharStyle:Code
9591 \begin_layout Plain Layout
9598 \begin_inset Flex CharStyle:Code
9601 \begin_layout Plain Layout
9608 \begin_inset Flex CharStyle:Code
9611 \begin_layout Plain Layout
9618 \begin_inset Flex CharStyle:Code
9621 \begin_layout Plain Layout
9629 \begin_inset Flex CharStyle:Code
9632 \begin_layout Plain Layout
9639 \begin_inset Quotes eld
9643 \begin_inset Quotes erd
9647 \begin_inset Flex CharStyle:Code
9650 \begin_layout Plain Layout
9657 \begin_inset Flex CharStyle:Code
9660 \begin_layout Plain Layout
9661 \begin_inset space ~
9670 \begin_inset space ~
9673 black) square suitable for end of proof markers,
9674 \begin_inset Flex CharStyle:Code
9677 \begin_layout Plain Layout
9683 is an explicit text string.
9686 \begin_layout Description
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9697 \begin_inset Flex CharStyle:Code
9700 \begin_layout Plain Layout
9706 ] The string used for a label with a
9707 \begin_inset Flex CharStyle:Code
9710 \begin_layout Plain Layout
9717 \begin_inset Flex CharStyle:Code
9720 \begin_layout Plain Layout
9730 \begin_layout Description
9731 \begin_inset Flex CharStyle:Code
9734 \begin_layout Plain Layout
9741 \begin_inset Flex CharStyle:Code
9744 \begin_layout Plain Layout
9755 \begin_inset Flex CharStyle:Code
9758 \begin_layout Plain Layout
9767 \begin_layout Description
9768 \begin_inset Flex CharStyle:Code
9771 \begin_layout Plain Layout
9778 \begin_inset Flex CharStyle:Code
9781 \begin_layout Plain Layout
9791 ] With this parameter the
9792 \begin_inset Flex CharStyle:MenuItem
9795 \begin_layout Plain Layout
9802 \begin_inset Quotes eld
9805 Vertical space above
9806 \begin_inset Quotes erd
9810 \begin_inset Flex CharStyle:MenuItem
9813 \begin_layout Plain Layout
9818 dit\SpecialChar \menuseparator
9824 \begin_inset space ~
9832 dialog can be set when initializing a paragraph with this style.
9836 \begin_layout Plain Layout
9839 Note from Jean-Marc:
9841 I'm not sure that this setting has much use, and it should probably be
9842 removed in later versions.
9850 \begin_layout Description
9851 \begin_inset Flex CharStyle:Code
9854 \begin_layout Plain Layout
9860 The font used for both the text body
9866 \begin_inset space ~
9870 \begin_inset CommandInset ref
9872 reference "sec:fonts"
9877 Note that defining this font automatically defines the
9878 \begin_inset Flex CharStyle:Code
9881 \begin_layout Plain Layout
9888 So you should define this one first if you also want to define
9889 \begin_inset Flex CharStyle:Code
9892 \begin_layout Plain Layout
9901 \begin_layout Description
9902 \begin_inset Flex CharStyle:Code
9905 \begin_layout Plain Layout
9912 \begin_inset CommandInset label
9914 name "des:FreeSpacing"
9921 \begin_inset Flex CharStyle:Code
9924 \begin_layout Plain Layout
9935 \begin_inset Flex CharStyle:Code
9938 \begin_layout Plain Layout
9944 ] Usually LyX doesn't allow you to insert more than one space between words,
9945 since a space is considered as the separation between two words, not a
9946 character or symbol of its own.
9947 This is a very fine thing but sometimes annoying, for example, when typing
9948 program code or plain LaTeX code.
9950 \begin_inset Flex CharStyle:Code
9953 \begin_layout Plain Layout
9960 Note that LyX will create protected blanks for the additional blanks when
9961 in another mode than LaTeX-mode.
9964 \begin_layout Description
9965 \begin_inset Flex CharStyle:Code
9968 \begin_layout Plain Layout
9977 \begin_layout Description
9978 \begin_inset Flex CharStyle:Code
9981 \begin_layout Plain Layout
9988 \begin_inset Flex CharStyle:Code
9991 \begin_layout Plain Layout
9997 If 1, marks the layout as being part of a title block (see also the
9998 \begin_inset Flex CharStyle:Code
10001 \begin_layout Plain Layout
10008 \begin_inset Flex CharStyle:Code
10011 \begin_layout Plain Layout
10020 \begin_layout Description
10021 \begin_inset Flex CharStyle:Code
10024 \begin_layout Plain Layout
10031 \begin_inset Flex CharStyle:Code
10034 \begin_layout Plain Layout
10040 ] This provides extra space between paragraphs that have the same layout.
10041 If you put other layouts into an environment, each is separated with the
10043 \begin_inset Flex CharStyle:Code
10046 \begin_layout Plain Layout
10053 But the whole items of the environment are additionally separated with
10055 \begin_inset Flex CharStyle:Code
10058 \begin_layout Plain Layout
10065 Note that this is a
10070 \begin_layout Description
10071 \begin_inset Flex CharStyle:Code
10074 \begin_layout Plain Layout
10083 \begin_layout Description
10084 \begin_inset Flex CharStyle:Code
10087 \begin_layout Plain Layout
10094 \begin_inset CommandInset label
10096 name "des:KeepEmpty"
10103 \begin_inset Flex CharStyle:Code
10106 \begin_layout Plain Layout
10117 \begin_inset Flex CharStyle:Code
10120 \begin_layout Plain Layout
10126 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10127 lead to empty LaTeX output.
10128 There are some cases where this could be desirable however: in a letter
10129 template, the required fields can be provided as empty fields, so that
10130 people do not forget them; in some special classes, a layout can be used
10131 as some kind of break, which does not contain actual text.
10134 \begin_layout Description
10135 \begin_inset Flex CharStyle:Code
10138 \begin_layout Plain Layout
10144 [float=0] The vertical space between the label and the text body.
10145 Only used for labels that are above the text body (
10146 \begin_inset Flex CharStyle:Code
10149 \begin_layout Plain Layout
10156 \begin_inset Flex CharStyle:Code
10159 \begin_layout Plain Layout
10160 Centered_Top_Environment
10168 \begin_layout Description
10169 \begin_inset Flex CharStyle:Code
10172 \begin_layout Plain Layout
10179 \begin_inset Flex CharStyle:Code
10182 \begin_layout Plain Layout
10189 \begin_inset Newline newline
10192 The name of the counter for automatic numbering (see Section
10193 \begin_inset CommandInset ref
10195 reference "sec:counter"
10200 This must be given if
10201 \begin_inset Flex CharStyle:Code
10204 \begin_layout Plain Layout
10211 \begin_inset Flex CharStyle:Code
10214 \begin_layout Plain Layout
10223 \begin_layout Description
10224 \begin_inset Flex CharStyle:Code
10227 \begin_layout Plain Layout
10233 The font used for the label.
10235 \begin_inset space ~
10239 \begin_inset CommandInset ref
10241 reference "sec:fonts"
10248 \begin_layout Description
10249 \begin_inset Flex CharStyle:Code
10252 \begin_layout Plain Layout
10259 \begin_inset Flex CharStyle:Code
10262 \begin_layout Plain Layout
10268 ] The horizontal space between the label and the text body.
10269 Only used for labels that are not above the text body.
10272 \begin_layout Description
10273 \begin_inset Flex CharStyle:Code
10276 \begin_layout Plain Layout
10283 \begin_inset Flex CharStyle:Code
10286 \begin_layout Plain Layout
10292 ] The string used for a label with a
10293 \begin_inset Flex CharStyle:Code
10296 \begin_layout Plain Layout
10304 \begin_inset Flex CharStyle:Code
10307 \begin_layout Plain Layout
10313 is set, this string can be contain the special formatting commands described
10315 \begin_inset CommandInset ref
10317 reference "sec:counter"
10325 \begin_layout Plain Layout
10326 For the sake of backwards compatibility, the string
10327 \begin_inset Flex CharStyle:Code
10330 \begin_layout Plain Layout
10340 will be replaced by the expanded
10341 \begin_inset Flex CharStyle:Code
10344 \begin_layout Plain Layout
10351 \begin_inset Flex CharStyle:Code
10354 \begin_layout Plain Layout
10363 This feature is now obsolete and should be replaced by the mechanisms of
10365 \begin_inset CommandInset ref
10367 reference "sec:counter"
10379 \begin_layout Description
10380 \begin_inset Flex CharStyle:Code
10383 \begin_layout Plain Layout
10384 LabelStringAppendix
10390 \begin_inset Flex CharStyle:Code
10393 \begin_layout Plain Layout
10399 ] This is used inside the appendix instead of
10400 \begin_inset Flex CharStyle:Code
10403 \begin_layout Plain Layout
10411 \begin_inset Flex CharStyle:Code
10414 \begin_layout Plain Layout
10421 \begin_inset Flex CharStyle:Code
10424 \begin_layout Plain Layout
10425 LabelStringAppendix
10433 \begin_layout Description
10434 \begin_inset Flex CharStyle:Code
10437 \begin_layout Plain Layout
10444 \begin_inset Flex CharStyle:Code
10447 \begin_layout Plain Layout
10452 , Manual, Static, Top_Environment,
10453 \begin_inset Newline newline
10456 Centered_Top_Environment, Sensitive, Counter
10462 \begin_inset Newline newline
10466 \begin_inset Flex CharStyle:Code
10469 \begin_layout Plain Layout
10475 means the label is the very first word (up to the first real blank).
10479 \begin_layout Plain Layout
10480 Use protected spaces if you want more than one word as the label.
10486 \begin_inset Flex CharStyle:Code
10489 \begin_layout Plain Layout
10495 means it is defined in the layout (see
10496 \begin_inset Flex CharStyle:Code
10499 \begin_layout Plain Layout
10507 \begin_inset Flex CharStyle:Code
10510 \begin_layout Plain Layout
10517 \begin_inset Flex CharStyle:Code
10520 \begin_layout Plain Layout
10521 Centered_Top_Environment
10526 are special cases of
10527 \begin_inset Flex CharStyle:Code
10530 \begin_layout Plain Layout
10537 The label will be printed above the paragraph, but only at the top of an
10538 environment or the top of a chain of paragraphs with this layout.
10539 Usage is for example the
10540 \begin_inset Flex CharStyle:MenuItem
10543 \begin_layout Plain Layout
10550 \begin_inset Flex CharStyle:MenuItem
10553 \begin_layout Plain Layout
10560 This is also the case for
10561 \begin_inset Flex CharStyle:Code
10564 \begin_layout Plain Layout
10570 labels with latex type
10571 \begin_inset Flex CharStyle:Code
10574 \begin_layout Plain Layout
10580 , in order to make layouts for theorems work correctly.
10582 \begin_inset Flex CharStyle:Code
10585 \begin_layout Plain Layout
10591 is a special case for the caption-labels
10592 \begin_inset Quotes eld
10596 \begin_inset Quotes erd
10600 \begin_inset Quotes eld
10604 \begin_inset Quotes erd
10609 \begin_inset Flex CharStyle:Code
10612 \begin_layout Plain Layout
10618 means the (hardcoded) label string depends on the kind of float.
10620 \begin_inset Flex CharStyle:Code
10623 \begin_layout Plain Layout
10629 label type defines automatically numbered labels.
10631 \begin_inset CommandInset ref
10633 reference "sec:counter"
10640 \begin_layout Description
10641 \begin_inset Flex CharStyle:Code
10644 \begin_layout Plain Layout
10653 \begin_layout Description
10654 \begin_inset Flex CharStyle:Code
10657 \begin_layout Plain Layout
10666 \begin_layout Description
10667 \begin_inset Flex CharStyle:Code
10670 \begin_layout Plain Layout
10677 \begin_inset CommandInset label
10679 name "des:LatexName"
10683 The name of the corresponding LaTeX stuff.
10684 Either the environment or command name.
10687 \begin_layout Description
10688 \begin_inset Flex CharStyle:Code
10691 \begin_layout Plain Layout
10700 \begin_layout Description
10701 \begin_inset Flex CharStyle:Code
10704 \begin_layout Plain Layout
10711 \begin_inset CommandInset label
10713 name "des:LatexParam"
10717 An optional parameter for the corresponding
10718 \begin_inset Flex CharStyle:Code
10721 \begin_layout Plain Layout
10728 This parameter cannot be changed from within LyX.
10731 \begin_layout Description
10732 \begin_inset Flex CharStyle:Code
10735 \begin_layout Plain Layout
10742 \begin_inset CommandInset label
10744 name "des:LatexType"
10749 \begin_inset Flex CharStyle:Code
10752 \begin_layout Plain Layout
10757 , Command, Environment, Item_Environment,
10763 \begin_inset Flex CharStyle:Code
10766 \begin_layout Plain Layout
10772 ] How the layout should be translated into LaTeX.
10774 \begin_inset Flex CharStyle:Code
10777 \begin_layout Plain Layout
10783 means nothing special.
10785 \begin_inset Flex CharStyle:Code
10788 \begin_layout Plain Layout
10795 \begin_inset Flex CharStyle:Code
10798 \begin_layout Plain Layout
10805 {\SpecialChar \ldots{}
10812 \begin_inset Flex CharStyle:Code
10815 \begin_layout Plain Layout
10822 \begin_inset Flex CharStyle:Code
10825 \begin_layout Plain Layout
10832 }\SpecialChar \ldots{}
10846 \begin_inset Flex CharStyle:Code
10849 \begin_layout Plain Layout
10856 \begin_inset Flex CharStyle:Code
10859 \begin_layout Plain Layout
10866 \begin_inset Flex CharStyle:Code
10869 \begin_layout Plain Layout
10877 is generated for each paragraph of this environment.
10879 \begin_inset Flex CharStyle:Code
10882 \begin_layout Plain Layout
10889 \begin_inset Flex CharStyle:Code
10892 \begin_layout Plain Layout
10899 \begin_inset Flex CharStyle:Code
10902 \begin_layout Plain Layout
10908 is passed as an argument to the environment.
10910 \begin_inset Flex CharStyle:Code
10913 \begin_layout Plain Layout
10919 can be defined in the
10920 \begin_inset Flex CharStyle:MenuItem
10923 \begin_layout Plain Layout
10928 ayout\SpecialChar \menuseparator
10940 \begin_inset Flex CharStyle:Code
10943 \begin_layout Plain Layout
10951 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10952 Visit the SGML class files for specific examples.
10955 \begin_layout Standard
10956 Putting the last few things together, the LaTeX output will be either:
10959 \begin_layout LyX-Code
10962 latexname[latexparam]{\SpecialChar \ldots{}
10966 \begin_layout Standard
10970 \begin_layout LyX-Code
10973 begin{latexname}[latexparam] \SpecialChar \ldots{}
10979 \begin_layout Standard
10980 depending upon the LaTex type.
10983 \begin_layout Description
10984 \begin_inset Flex CharStyle:Code
10987 \begin_layout Plain Layout
10994 \begin_inset Flex CharStyle:Code
10997 \begin_layout Plain Layout
11003 ] If you put layouts into environments, the leftmargins are not simply added,
11004 but added with a factor
11005 \begin_inset Formula $\frac{4}{depth+4}$
11009 Note that this parameter is also used when the margin is defined as
11010 \begin_inset Flex CharStyle:Code
11013 \begin_layout Plain Layout
11020 \begin_inset Flex CharStyle:Code
11023 \begin_layout Plain Layout
11030 Then it is added to the manual or dynamic margin.
11032 \begin_inset Newline newline
11035 The argument is passed as a string.
11037 \begin_inset Quotes eld
11041 \begin_inset Flex CharStyle:Code
11044 \begin_layout Plain Layout
11051 \begin_inset Quotes erd
11054 means that the paragraph is indented with the width of
11055 \begin_inset Quotes eld
11059 \begin_inset Flex CharStyle:Code
11062 \begin_layout Plain Layout
11069 \begin_inset Quotes erd
11072 in the normal font.
11073 You can get a negative width by prefixing the string with
11074 \begin_inset Quotes eld
11078 \begin_inset Flex CharStyle:Code
11081 \begin_layout Plain Layout
11088 \begin_inset Quotes erd
11092 This way was chosen so that the look is the same with each used screen
11097 \begin_layout Description
11098 \begin_inset Flex CharStyle:Code
11101 \begin_layout Plain Layout
11108 \begin_inset Flex CharStyle:Code
11111 \begin_layout Plain Layout
11116 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11122 \begin_inset Newline newline
11125 The kind of margin that the layout has on the left side.
11127 \begin_inset Flex CharStyle:Code
11130 \begin_layout Plain Layout
11136 just means a fixed margin.
11138 \begin_inset Flex CharStyle:Code
11141 \begin_layout Plain Layout
11147 means that the left margin depends on the string entered in the
11148 \begin_inset Flex CharStyle:MenuItem
11151 \begin_layout Plain Layout
11156 dit\SpecialChar \menuseparator
11162 \begin_inset space ~
11171 This is used to typeset nice lists without tabulators.
11173 \begin_inset Flex CharStyle:Code
11176 \begin_layout Plain Layout
11182 means that the margin depends on the size of the label.
11183 This is used for automatic enumerated headlines.
11184 It is obvious that the headline
11185 \begin_inset Quotes eld
11188 5.4.3.2.1 Very long headline
11189 \begin_inset Quotes erd
11192 must have a wider left margin (as wide as
11193 \begin_inset Quotes eld
11197 \begin_inset Quotes erd
11200 plus the space) than
11201 \begin_inset Quotes eld
11204 3.2 Very long headline
11205 \begin_inset Quotes erd
11209 \begin_inset Quotes eld
11213 \begin_inset Quotes erd
11216 are not able to do this.
11218 \begin_inset Flex CharStyle:Code
11221 \begin_layout Plain Layout
11227 is similar, but only the very first row of the paragraph is dynamic, while
11228 the others are static; this is used, for example, for descriptions.
11230 \begin_inset Flex CharStyle:Code
11233 \begin_layout Plain Layout
11239 means the margin is chosen in a way that the longest row of this paragraph
11240 fits to the right margin.
11241 This is used to typeset an address on the right edge of the page.
11244 \begin_layout Description
11245 \begin_inset Flex CharStyle:Code
11248 \begin_layout Plain Layout
11255 \begin_inset CommandInset label
11257 name "des:NeedProtect"
11262 \begin_inset Flex CharStyle:Code
11265 \begin_layout Plain Layout
11274 \begin_inset Flex CharStyle:Code
11277 \begin_layout Plain Layout
11283 ] Whether fragile commands in this layout should be
11284 \begin_inset Flex CharStyle:Code
11287 \begin_layout Plain Layout
11298 \begin_layout Description
11299 \begin_inset Flex CharStyle:Code
11302 \begin_layout Plain Layout
11309 \begin_inset Flex CharStyle:Code
11312 \begin_layout Plain Layout
11319 \begin_inset Flex CharStyle:Code
11322 \begin_layout Plain Layout
11330 ] Whether newlines are translated into LaTeX newlines (
11331 \begin_inset Flex CharStyle:Code
11334 \begin_layout Plain Layout
11345 The translation can be switched off to allow more comfortable LaTeX editing
11349 \begin_layout Description
11350 \begin_inset Flex CharStyle:Code
11353 \begin_layout Plain Layout
11360 \begin_inset Flex CharStyle:Code
11363 \begin_layout Plain Layout
11370 \begin_inset Flex CharStyle:Code
11373 \begin_layout Plain Layout
11381 ] Whether the following Paragraph is allowed to indent its very first row.
11383 \begin_inset Flex CharStyle:Code
11386 \begin_layout Plain Layout
11392 means that it is not allowed to do so;
11393 \begin_inset Flex CharStyle:Code
11396 \begin_layout Plain Layout
11402 means it could do so if it wants to.
11405 \begin_layout Description
11406 \begin_inset Flex CharStyle:Code
11409 \begin_layout Plain Layout
11418 \begin_layout Description
11419 \begin_inset Flex CharStyle:Code
11422 \begin_layout Plain Layout
11429 \begin_inset Flex CharStyle:Code
11432 \begin_layout Plain Layout
11438 ] The number of optional arguments that can be used with this layout.
11439 This is useful for things like section headings, and only makes sense with
11443 \begin_layout Description
11444 \begin_inset Flex CharStyle:Code
11447 \begin_layout Plain Layout
11454 \begin_inset Flex CharStyle:Code
11457 \begin_layout Plain Layout
11463 ] The indent of the very first line of a paragraph.
11465 \begin_inset Flex CharStyle:Code
11468 \begin_layout Plain Layout
11474 will be fixed for a certain layout.
11475 The exception is Standard layout, since the indentation of a Standard layout
11476 paragraph can be prohibited with
11477 \begin_inset Flex CharStyle:Code
11480 \begin_layout Plain Layout
11487 Also, Standard layout paragraphs inside environments use the
11488 \begin_inset Flex CharStyle:Code
11491 \begin_layout Plain Layout
11497 of the environment, not their native one.
11498 For example, Standard paragraphs inside an enumeration are not indented.
11501 \begin_layout Description
11502 \begin_inset Flex CharStyle:Code
11505 \begin_layout Plain Layout
11512 \begin_inset Flex CharStyle:Code
11515 \begin_layout Plain Layout
11521 ] The vertical space between two paragraphs of this layout.
11524 \begin_layout Description
11525 \begin_inset Flex CharStyle:Code
11528 \begin_layout Plain Layout
11535 \begin_inset Flex CharStyle:Code
11538 \begin_layout Plain Layout
11544 ] LyX allows the user to choose either
11545 \begin_inset Quotes eld
11549 \begin_inset Quotes erd
11553 \begin_inset Quotes eld
11557 \begin_inset Quotes erd
11560 to typeset a document.
11562 \begin_inset Quotes eld
11566 \begin_inset Quotes erd
11569 is chosen, this value is completely ignored.
11571 \begin_inset Quotes eld
11575 \begin_inset Quotes erd
11578 is chosen, the parindent of a LaTeXtype
11579 \begin_inset Quotes eld
11583 \begin_inset Quotes erd
11586 layout is ignored and all paragraphs are separated by this parskip argument.
11587 The vertical space is calculated with
11588 \begin_inset Flex CharStyle:Code
11591 \begin_layout Plain Layout
11593 \begin_inset space ~
11602 \begin_inset Flex CharStyle:Code
11605 \begin_layout Plain Layout
11611 is the height of a row with the normal font.
11612 This way, the look stays the same with different screen fonts.
11615 \begin_layout Description
11616 \begin_inset Flex CharStyle:Code
11619 \begin_layout Plain Layout
11626 \begin_inset CommandInset label
11628 name "des:PassThru"
11635 \begin_inset Flex CharStyle:Code
11638 \begin_layout Plain Layout
11649 \begin_inset Flex CharStyle:Code
11652 \begin_layout Plain Layout
11658 ] Whether the contents of this paragraph should be output in raw form, meaning
11659 without special translations that LaTeX would require.
11662 \begin_layout Description
11663 \begin_inset Flex CharStyle:Code
11666 \begin_layout Plain Layout
11673 \begin_inset CommandInset label
11675 name "des:Preamble"
11679 Information to be included in the LaTeX preamable when this style is used.
11680 Used to define macros, load packages, etc., required by this particular
11683 \begin_inset Quotes eld
11687 \begin_inset Flex CharStyle:Code
11690 \begin_layout Plain Layout
11697 \begin_inset Quotes erd
11703 \begin_layout Description
11704 \begin_inset Flex CharStyle:Code
11707 \begin_layout Plain Layout
11714 \begin_inset Flex CharStyle:Code
11717 \begin_layout Plain Layout
11724 \begin_inset CommandInset label
11726 name "des:Requires"
11730 Whether the layout requires the feature
11731 \begin_inset Flex CharStyle:Code
11734 \begin_layout Plain Layout
11741 See the description of
11742 \begin_inset Flex CharStyle:Code
11745 \begin_layout Plain Layout
11752 \begin_inset CommandInset ref
11753 LatexCommand pageref
11754 reference "des:FreeSpacing"
11758 ) for information on `features'.
11762 \begin_layout Description
11763 \begin_inset Flex CharStyle:Code
11766 \begin_layout Plain Layout
11773 \begin_inset Flex CharStyle:Code
11776 \begin_layout Plain Layout
11783 \begin_inset Flex CharStyle:Code
11786 \begin_layout Plain Layout
11795 \begin_layout Description
11796 \begin_inset Flex CharStyle:Code
11799 \begin_layout Plain Layout
11806 \begin_inset Flex CharStyle:Code
11809 \begin_layout Plain Layout
11814 , onehalf, double, other
11823 ] This defines what the default spacing should be in the layout.
11825 \begin_inset Flex CharStyle:Code
11828 \begin_layout Plain Layout
11835 \begin_inset Flex CharStyle:Code
11838 \begin_layout Plain Layout
11845 \begin_inset Flex CharStyle:Code
11848 \begin_layout Plain Layout
11854 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11855 If you specify the argument
11856 \begin_inset Flex CharStyle:Code
11859 \begin_layout Plain Layout
11865 , then you should also provide a numerical argument which will be the actual
11867 Note that, contrary to other parameters,
11868 \begin_inset Flex CharStyle:Code
11871 \begin_layout Plain Layout
11877 implies the generation of specific LaTeX code, using the package
11880 \begin_inset Flex CharStyle:Code
11883 \begin_layout Plain Layout
11892 \begin_layout Description
11893 \begin_inset Flex CharStyle:Code
11896 \begin_layout Plain Layout
11902 The font used for the text body .
11904 \begin_inset CommandInset ref
11906 reference "sec:fonts"
11913 \begin_layout Description
11914 \begin_inset Flex CharStyle:Code
11917 \begin_layout Plain Layout
11925 The level of the style in the table of contents.
11926 This is used for automatic numbering of section headings.
11929 \begin_layout Description
11930 \begin_inset Flex CharStyle:Code
11933 \begin_layout Plain Layout
11940 \begin_inset Flex CharStyle:Code
11943 \begin_layout Plain Layout
11949 ] The vertical space with which the very first of a chain of paragraphs
11950 with this layout is separated from the previous paragraph.
11951 If the previous paragraph has another layout, the separations are not simply
11952 added, but the maximum is taken.
11955 \begin_layout Subsection
11959 \begin_layout Standard
11960 \begin_inset CommandInset label
11966 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11967 define the floats (
11968 \begin_inset Flex CharStyle:MenuItem
11971 \begin_layout Plain Layout
11978 \begin_inset Flex CharStyle:MenuItem
11981 \begin_layout Plain Layout
11987 , \SpecialChar \ldots{}
11988 ) in the text class itself.
11989 Standard floats are included in the file
11990 \begin_inset Flex CharStyle:Code
11993 \begin_layout Plain Layout
11999 , so you may have to do no more than add
12002 \begin_layout LyX-Code
12003 Input stdfloats.inc
12006 \begin_layout Standard
12007 to your layout file.
12008 If you want to implement a text class that proposes some other float types
12009 (like the AGU class bundled with LyX), the information below will hopefully
12013 \begin_layout Description
12014 \begin_inset Flex CharStyle:Code
12017 \begin_layout Plain Layout
12024 \begin_inset Flex CharStyle:Code
12027 \begin_layout Plain Layout
12034 \begin_inset Quotes erd
12038 \begin_inset Quotes erd
12041 ] The file name extension of an auxiliary file for the list of figures (or
12043 LaTeX writes the captions to this file.
12046 \begin_layout Description
12047 \begin_inset Flex CharStyle:Code
12050 \begin_layout Plain Layout
12057 \begin_inset Flex CharStyle:Code
12060 \begin_layout Plain Layout
12067 \begin_inset Quotes erd
12071 \begin_inset Quotes erd
12074 ] The string that will be used in the menus and also for the caption.
12077 \begin_layout Description
12078 \begin_inset Flex CharStyle:Code
12081 \begin_layout Plain Layout
12088 \begin_inset Flex CharStyle:Code
12091 \begin_layout Plain Layout
12100 \begin_inset Flex CharStyle:Code
12103 \begin_layout Plain Layout
12110 \begin_inset Flex CharStyle:Code
12113 \begin_layout Plain Layout
12119 if the float is already defined by the LaTeX document class.
12121 \begin_inset Flex CharStyle:Code
12124 \begin_layout Plain Layout
12130 , the float will be defined using the LaTeX package
12131 \begin_inset Flex CharStyle:Code
12134 \begin_layout Plain Layout
12143 \begin_layout Description
12144 \begin_inset Flex CharStyle:Code
12147 \begin_layout Plain Layout
12154 \begin_inset Flex CharStyle:Code
12157 \begin_layout Plain Layout
12164 \begin_inset Quotes erd
12168 \begin_inset Quotes erd
12171 ] The heading used for the list of floats.
12174 \begin_layout Description
12175 \begin_inset Flex CharStyle:Code
12178 \begin_layout Plain Layout
12185 \begin_inset Flex CharStyle:Code
12188 \begin_layout Plain Layout
12195 \begin_inset Quotes erd
12199 \begin_inset Quotes erd
12202 ] This (optional) argument determines whether floats of this class will
12203 be numbered within some sectional unit of the document.
12204 For example, if within is equal to
12205 \begin_inset Flex CharStyle:Code
12208 \begin_layout Plain Layout
12214 , the floats will be numbered within chapters.
12218 \begin_layout Description
12219 \begin_inset Flex CharStyle:Code
12222 \begin_layout Plain Layout
12229 \begin_inset Flex CharStyle:Code
12232 \begin_layout Plain Layout
12239 \begin_inset Quotes erd
12243 \begin_inset Quotes erd
12246 ] The default placement for the given class of floats.
12247 The string should be as in standard LaTeX:
12248 \begin_inset Flex CharStyle:Code
12251 \begin_layout Plain Layout
12258 \begin_inset Flex CharStyle:Code
12261 \begin_layout Plain Layout
12268 \begin_inset Flex CharStyle:Code
12271 \begin_layout Plain Layout
12278 \begin_inset Flex CharStyle:Code
12281 \begin_layout Plain Layout
12287 for top, bottom, page, and here, respectively.
12291 \begin_layout Plain Layout
12292 Note that the order of these letters in the string is irrelevant, like in
12298 On top of that there is a new type,
12299 \begin_inset Flex CharStyle:Code
12302 \begin_layout Plain Layout
12308 , which does not really correspond to a float, since it means: put it
12309 \begin_inset Quotes eld
12313 \begin_inset Quotes erd
12317 Note however that the
12318 \begin_inset Flex CharStyle:Code
12321 \begin_layout Plain Layout
12327 specifier is special and, because of implementation details, cannot be
12328 used in non-builtin float types.
12329 If you do not understand what this means, just use
12330 \begin_inset Quotes eld
12334 \begin_inset Flex CharStyle:Code
12337 \begin_layout Plain Layout
12344 \begin_inset Quotes erd
12350 \begin_layout Description
12351 \begin_inset Flex CharStyle:Code
12354 \begin_layout Plain Layout
12361 \begin_inset Flex CharStyle:Code
12364 \begin_layout Plain Layout
12371 \begin_inset Quotes erd
12375 \begin_inset Quotes erd
12378 ] The style used when defining the float using
12379 \begin_inset Flex CharStyle:Code
12382 \begin_layout Plain Layout
12393 \begin_layout Description
12394 \begin_inset Flex CharStyle:Code
12397 \begin_layout Plain Layout
12404 \begin_inset Flex CharStyle:Code
12407 \begin_layout Plain Layout
12414 \begin_inset Quotes erd
12418 \begin_inset Quotes erd
12422 \begin_inset Quotes eld
12426 \begin_inset Quotes erd
12429 of the new class of floats, like program or algorithm.
12430 After the appropriate
12431 \begin_inset Flex CharStyle:Code
12434 \begin_layout Plain Layout
12443 \begin_inset Flex CharStyle:Code
12446 \begin_layout Plain Layout
12455 \begin_inset Flex CharStyle:Code
12458 \begin_layout Plain Layout
12469 \begin_layout Standard
12470 Note that defining a float with type
12471 \begin_inset Flex CharStyle:Code
12474 \begin_layout Plain Layout
12482 automatically defines the corresponding counter with name
12483 \begin_inset Flex CharStyle:Code
12486 \begin_layout Plain Layout
12497 \begin_layout Subsection
12498 Inset layouts and Flex insets
12501 \begin_layout Standard
12502 \begin_inset CommandInset label
12504 name "sec:charstyle"
12508 LyX has supported character styles since version 1.4.0; since version 1.6.0
12509 these are called Flex insets.
12513 \begin_layout Standard
12514 Furthermore, it is possible to define the general layout of many different
12516 Currently, InsetLayout can be used to customize the layout parameters
12517 for footnotes, marginal notes, note insets, ERT insets, branches, listings,
12518 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
12523 \begin_layout Standard
12524 Flex insets come in three different kinds:
12527 \begin_layout Itemize
12529 \begin_inset Flex CharStyle:Code
12532 \begin_layout Plain Layout
12538 ): These define semantic markup corresponding to such LaTeX commands as
12540 \begin_inset Flex CharStyle:Code
12543 \begin_layout Plain Layout
12552 \begin_inset Flex CharStyle:Code
12555 \begin_layout Plain Layout
12566 \begin_layout Itemize
12568 \begin_inset Flex CharStyle:Code
12571 \begin_layout Plain Layout
12577 ): These can be used to define custom collapsable insets, similar to ERT,
12578 footnote, and the like.
12581 \begin_layout Itemize
12583 \begin_inset Flex CharStyle:Code
12586 \begin_layout Plain Layout
12592 ): For use with DocBook classes.
12595 \begin_layout Standard
12597 \begin_inset Flex CharStyle:Code
12600 \begin_layout Plain Layout
12606 definition starting line is of the form
12609 \begin_layout LyX-Code
12610 InsetLayout <Type> <Name>
12613 \begin_layout Standard
12615 \begin_inset Flex CharStyle:Code
12618 \begin_layout Plain Layout
12625 \begin_inset Flex CharStyle:Code
12628 \begin_layout Plain Layout
12635 \begin_inset Flex CharStyle:Code
12638 \begin_layout Plain Layout
12645 \begin_inset Flex CharStyle:Code
12648 \begin_layout Plain Layout
12655 \begin_inset Flex CharStyle:Code
12658 \begin_layout Plain Layout
12665 \begin_inset Flex CharStyle:Code
12668 \begin_layout Plain Layout
12675 \begin_inset Flex CharStyle:Code
12678 \begin_layout Plain Layout
12685 \begin_inset Flex CharStyle:Code
12688 \begin_layout Plain Layout
12695 \begin_inset Flex CharStyle:Code
12698 \begin_layout Plain Layout
12705 \begin_inset Flex CharStyle:Code
12708 \begin_layout Plain Layout
12715 \begin_inset Flex CharStyle:Code
12718 \begin_layout Plain Layout
12725 \begin_inset Flex CharStyle:Code
12728 \begin_layout Plain Layout
12735 \begin_inset Flex CharStyle:Code
12738 \begin_layout Plain Layout
12745 \begin_inset Flex CharStyle:Code
12748 \begin_layout Plain Layout
12755 \begin_inset Flex CharStyle:Code
12758 \begin_layout Plain Layout
12765 \begin_inset Flex CharStyle:Code
12768 \begin_layout Plain Layout
12775 \begin_inset Flex CharStyle:Code
12778 \begin_layout Plain Layout
12786 \begin_inset Flex CharStyle:Code
12789 \begin_layout Plain Layout
12796 \begin_inset Flex CharStyle:Code
12799 \begin_layout Plain Layout
12806 \begin_inset Flex CharStyle:Code
12809 \begin_layout Plain Layout
12815 should have the form
12816 \begin_inset Flex CharStyle:Code
12819 \begin_layout Plain Layout
12826 \begin_inset Flex CharStyle:Code
12829 \begin_layout Plain Layout
12836 \begin_inset Flex CharStyle:Code
12839 \begin_layout Plain Layout
12846 \begin_inset Flex CharStyle:Code
12849 \begin_layout Plain Layout
12856 \begin_inset Flex CharStyle:Code
12859 \begin_layout Plain Layout
12866 \begin_inset Flex CharStyle:Code
12869 \begin_layout Plain Layout
12875 is any valid identifier.
12879 \begin_layout Standard
12881 \begin_inset Flex CharStyle:Code
12884 \begin_layout Plain Layout
12890 section can contain the following entries:
12893 \begin_layout Description
12894 \begin_inset Flex CharStyle:Code
12897 \begin_layout Plain Layout
12903 The color for the inset's background.
12904 These valid colors are defined in
12905 \begin_inset Flex CharStyle:Code
12908 \begin_layout Plain Layout
12917 \begin_layout Description
12918 \begin_inset Flex CharStyle:Code
12921 \begin_layout Plain Layout
12928 \begin_inset Flex CharStyle:Code
12931 \begin_layout Plain Layout
12938 \begin_inset Flex CharStyle:Code
12941 \begin_layout Plain Layout
12948 \begin_inset Flex CharStyle:Code
12951 \begin_layout Plain Layout
12957 , describing the rendering style used for the inset's frame and buttons.
12958 Footnotes generally use
12959 \begin_inset Flex CharStyle:Code
12962 \begin_layout Plain Layout
12968 ; ERT insets generally use
12969 \begin_inset Flex CharStyle:Code
12972 \begin_layout Plain Layout
12978 ; and character styles use
12979 \begin_inset Flex CharStyle:Code
12982 \begin_layout Plain Layout
12991 \begin_layout Description
12992 \begin_inset Flex CharStyle:Code
12995 \begin_layout Plain Layout
13001 The font used for both the text body
13007 \begin_inset space ~
13011 \begin_inset CommandInset ref
13013 reference "sec:fonts"
13018 Note that defining this font automatically defines the
13019 \begin_inset Flex CharStyle:Code
13022 \begin_layout Plain Layout
13028 to the same value, so define this first and define
13029 \begin_inset Flex CharStyle:Code
13032 \begin_layout Plain Layout
13038 later if you want them to be different.
13041 \begin_layout Description
13042 \begin_inset Flex CharStyle:Code
13045 \begin_layout Plain Layout
13054 \begin_layout Description
13055 \begin_inset Flex CharStyle:Code
13058 \begin_layout Plain Layout
13064 As with paragraph styles (see page
13065 \begin_inset CommandInset ref
13066 LatexCommand pageref
13067 reference "des:FreeSpacing"
13074 \begin_layout Description
13075 \begin_inset Flex CharStyle:Code
13078 \begin_layout Plain Layout
13084 As with paragraph styles (see page
13085 \begin_inset CommandInset ref
13086 LatexCommand pageref
13087 reference "des:KeepEmpty"
13094 \begin_layout Description
13095 \begin_inset Flex CharStyle:Code
13098 \begin_layout Plain Layout
13104 What will be displayed on the button or elsewhere as the inset label.
13105 Some inset types (ERT and Branch) modify this label on the fly.
13108 \begin_layout Description
13109 \begin_inset Flex CharStyle:Code
13112 \begin_layout Plain Layout
13118 The font used for the label.
13120 \begin_inset space ~
13124 \begin_inset CommandInset ref
13126 reference "sec:fonts"
13131 Note that this definition can never appear before
13132 \begin_inset Flex CharStyle:Code
13135 \begin_layout Plain Layout
13141 , lest it be ineffective.
13144 \begin_layout Description
13145 \begin_inset Flex CharStyle:Code
13148 \begin_layout Plain Layout
13154 The name of the corresponding LaTeX stuff.
13155 Either the environment or command name.
13158 \begin_layout Description
13159 \begin_inset Flex CharStyle:Code
13162 \begin_layout Plain Layout
13168 The optional parameter for the corresponding
13169 \begin_inset Flex CharStyle:Code
13172 \begin_layout Plain Layout
13178 stuff, including possible bracket pairs like
13179 \begin_inset Flex CharStyle:Code
13182 \begin_layout Plain Layout
13189 This parameter cannot be changed from within LyX.
13192 \begin_layout Description
13193 \begin_inset Flex CharStyle:Code
13196 \begin_layout Plain Layout
13202 As with paragraph styles (see page
13203 \begin_inset CommandInset ref
13204 LatexCommand pageref
13205 reference "des:LatexType"
13212 \begin_layout Description
13213 \begin_inset Flex CharStyle:Code
13216 \begin_layout Plain Layout
13223 \begin_inset Flex CharStyle:Code
13226 \begin_layout Plain Layout
13233 \begin_inset Flex CharStyle:Code
13236 \begin_layout Plain Layout
13243 \begin_inset Flex CharStyle:Code
13246 \begin_layout Plain Layout
13253 \begin_inset Flex CharStyle:Code
13256 \begin_layout Plain Layout
13262 (indicating a dummy definition ending definitions of charstyles etc.).
13263 This entry is only meaningful for Flex (user definable) insets.
13266 \begin_layout Description
13267 \begin_inset Flex CharStyle:Code
13270 \begin_layout Plain Layout
13276 As with paragraph styles (see page
13277 \begin_inset CommandInset ref
13278 LatexCommand pageref
13279 reference "des:Preamble"
13286 \begin_layout Description
13287 \begin_inset Flex CharStyle:Code
13290 \begin_layout Plain Layout
13297 \begin_inset Flex CharStyle:Code
13300 \begin_layout Plain Layout
13306 ] As with paragraph styles (see page
13307 \begin_inset CommandInset ref
13308 LatexCommand pageref
13309 reference "des:Requires"
13316 \begin_layout Subsection
13320 \begin_layout Standard
13321 \begin_inset CommandInset label
13327 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13329 \begin_inset Flex CharStyle:MenuItem
13332 \begin_layout Plain Layout
13339 \begin_inset Flex CharStyle:MenuItem
13342 \begin_layout Plain Layout
13348 , \SpecialChar \ldots{}
13349 ) in the text class itself.
13350 The standard counters are defined in the file
13351 \begin_inset Flex CharStyle:Code
13354 \begin_layout Plain Layout
13360 , so you may have to do no more than add
13363 \begin_layout LyX-Code
13364 Input stdcounters.inc
13367 \begin_layout Standard
13368 to your layout file to get them to work.
13369 But if you want to define custom counters, then you can do so, using the
13370 following parameters:
13373 \begin_layout Description
13374 \begin_inset Flex CharStyle:Code
13377 \begin_layout Plain Layout
13378 LabelString [string=""]
13383 when this is defined, this string defines how the counter is displayed.
13384 Setting this value sets
13385 \begin_inset Flex CharStyle:Code
13388 \begin_layout Plain Layout
13389 LabelStringAppendix
13395 The following special constructs can be used in the string:
13399 \begin_layout Itemize
13400 \begin_inset Flex CharStyle:Code
13403 \begin_layout Plain Layout
13411 will be replaced by the expansion of the
13412 \begin_inset Flex CharStyle:Code
13415 \begin_layout Plain Layout
13422 \begin_inset Flex CharStyle:Code
13425 \begin_layout Plain Layout
13426 LabelStringAppendix
13432 \begin_inset Flex CharStyle:Code
13435 \begin_layout Plain Layout
13445 \begin_layout Itemize
13446 counter values can be expressed using LaTeX-like macros
13447 \begin_inset Flex CharStyle:Code
13450 \begin_layout Plain Layout
13467 \begin_inset Flex CharStyle:Code
13470 \begin_layout Plain Layout
13482 \begin_layout Plain Layout
13492 Actually, the situation is a bit more complicated: any
13511 other than those descibed below will produce arabic numerals.
13512 It would not be surprising to see this change in the future.
13518 \begin_inset Flex CharStyle:Code
13521 \begin_layout Plain Layout
13527 : 1, 2, 3,\SpecialChar \ldots{}
13529 \begin_inset Flex CharStyle:Code
13532 \begin_layout Plain Layout
13538 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13540 \begin_inset Flex CharStyle:Code
13543 \begin_layout Plain Layout
13549 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13551 \begin_inset Flex CharStyle:Code
13554 \begin_layout Plain Layout
13560 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13562 \begin_inset Flex CharStyle:Code
13565 \begin_layout Plain Layout
13571 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13573 \begin_inset Flex CharStyle:Code
13576 \begin_layout Plain Layout
13582 for hebrew numerals.
13586 \begin_layout Standard
13587 If LabelString is not defined, a default value is constructed as follows:
13588 if the counter has a master counter
13589 \begin_inset Flex CharStyle:Code
13592 \begin_layout Plain Layout
13599 \begin_inset Flex CharStyle:Code
13602 \begin_layout Plain Layout
13609 \begin_inset Flex CharStyle:Code
13612 \begin_layout Plain Layout
13622 is used; otherwise the string
13623 \begin_inset Flex CharStyle:Code
13626 \begin_layout Plain Layout
13637 \begin_layout Description
13638 \begin_inset Flex CharStyle:Code
13641 \begin_layout Plain Layout
13642 LabelStringAppendix [string=""]
13648 \begin_inset Flex CharStyle:Code
13651 \begin_layout Plain Layout
13660 \begin_layout Description
13661 \begin_inset Flex CharStyle:Code
13664 \begin_layout Plain Layout
13671 \begin_inset Flex CharStyle:Code
13674 \begin_layout Plain Layout
13681 \begin_inset Quotes erd
13685 \begin_inset Quotes erd
13688 ] The name of the counter.
13691 \begin_layout Description
13692 \begin_inset Flex CharStyle:Code
13695 \begin_layout Plain Layout
13702 \begin_inset Flex CharStyle:Code
13705 \begin_layout Plain Layout
13712 \begin_inset Quotes erd
13716 \begin_inset Quotes erd
13719 ] If this is set to the name of another counter, the present counter will
13720 be reset everytime the other one is increased.
13722 \begin_inset Flex CharStyle:Code
13725 \begin_layout Plain Layout
13732 \begin_inset Flex CharStyle:Code
13735 \begin_layout Plain Layout
13744 \begin_layout Subsection
13748 \begin_layout Standard
13749 \begin_inset CommandInset label
13755 A font description looks like this:
13758 \begin_layout LyX-Code
13768 \begin_layout LyX-Code
13772 \begin_layout LyX-Code
13776 \begin_layout Standard
13777 The following commands are available:
13780 \begin_layout Description
13781 \begin_inset Flex CharStyle:Code
13784 \begin_layout Plain Layout
13791 \begin_inset Flex CharStyle:Code
13794 \begin_layout Plain Layout
13803 \begin_inset Flex CharStyle:Code
13806 \begin_layout Plain Layout
13813 \begin_inset Flex CharStyle:Code
13816 \begin_layout Plain Layout
13823 \begin_inset Flex CharStyle:Code
13826 \begin_layout Plain Layout
13833 \begin_inset Flex CharStyle:Code
13836 \begin_layout Plain Layout
13843 \begin_inset Flex CharStyle:Code
13846 \begin_layout Plain Layout
13853 \begin_inset Flex CharStyle:Code
13856 \begin_layout Plain Layout
13863 \begin_inset Flex CharStyle:Code
13866 \begin_layout Plain Layout
13873 \begin_inset Flex CharStyle:Code
13876 \begin_layout Plain Layout
13885 \begin_layout Description
13886 \begin_inset Flex CharStyle:Code
13889 \begin_layout Plain Layout
13898 \begin_inset Flex CharStyle:Code
13901 \begin_layout Plain Layout
13912 \begin_inset Flex CharStyle:Code
13915 \begin_layout Plain Layout
13922 \begin_inset Flex CharStyle:Code
13925 \begin_layout Plain Layout
13934 \begin_layout Description
13935 \begin_inset Flex CharStyle:Code
13938 \begin_layout Plain Layout
13945 \begin_inset Flex CharStyle:Code
13948 \begin_layout Plain Layout
13954 ] Valid argument sare:
13955 \begin_inset Flex CharStyle:Code
13958 \begin_layout Plain Layout
13965 \begin_inset Flex CharStyle:Code
13968 \begin_layout Plain Layout
13975 \begin_inset Flex CharStyle:Code
13978 \begin_layout Plain Layout
13985 \begin_inset Flex CharStyle:Code
13988 \begin_layout Plain Layout
13995 \begin_inset Flex CharStyle:Code
13998 \begin_layout Plain Layout
14005 \begin_inset Flex CharStyle:Code
14008 \begin_layout Plain Layout
14015 Each of these turns on or off the corresponding attribute.
14018 \begin_layout Description
14019 \begin_inset Flex CharStyle:Code
14022 \begin_layout Plain Layout
14031 \begin_inset Flex CharStyle:Code
14034 \begin_layout Plain Layout
14045 \begin_inset Flex CharStyle:Code
14048 \begin_layout Plain Layout
14057 \begin_layout Description
14058 \begin_inset Flex CharStyle:Code
14061 \begin_layout Plain Layout
14070 \begin_inset Flex CharStyle:Code
14073 \begin_layout Plain Layout
14084 \begin_inset Flex CharStyle:Code
14087 \begin_layout Plain Layout
14094 \begin_inset Flex CharStyle:Code
14097 \begin_layout Plain Layout
14104 \begin_inset Flex CharStyle:Code
14107 \begin_layout Plain Layout
14116 \begin_layout Description
14117 \begin_inset Flex CharStyle:Code
14120 \begin_layout Plain Layout
14127 \begin_inset Flex CharStyle:Code
14130 \begin_layout Plain Layout
14137 \begin_inset Flex CharStyle:Code
14140 \begin_layout Plain Layout
14147 \begin_inset Flex CharStyle:Code
14150 \begin_layout Plain Layout
14159 \begin_inset Flex CharStyle:Code
14162 \begin_layout Plain Layout
14169 \begin_inset Flex CharStyle:Code
14172 \begin_layout Plain Layout
14179 \begin_inset Flex CharStyle:Code
14182 \begin_layout Plain Layout
14189 \begin_inset Flex CharStyle:Code
14192 \begin_layout Plain Layout
14199 \begin_inset Flex CharStyle:Code
14202 \begin_layout Plain Layout
14211 \begin_layout Subsection
14212 Upgrading old layout files
14215 \begin_layout Standard
14216 The file format of layout files changes from time to time, so old layout
14217 files need to be converted.
14218 This process has been automated since LyX 1.4.0: If LyX reads an old format
14219 layout file it will call the conversion tool
14220 \begin_inset Flex CharStyle:Code
14223 \begin_layout Plain Layout
14224 LyXDir/scripts/layout2layout.py
14229 and convert it to a temporary file in current format.
14230 The original file is left untouched.
14231 If you want to convert the layout file permanently, just call the converter
14235 \begin_layout LyX-Code
14236 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
14239 \begin_layout Standard
14240 (You need to replace
14241 \begin_inset Flex CharStyle:Code
14244 \begin_layout Plain Layout
14250 with the name of your LyX system directory, unless you happen to have defined
14251 such an environment variable.) Then copy
14252 \begin_inset Flex CharStyle:Code
14255 \begin_layout Plain Layout
14262 \begin_inset Flex CharStyle:Code
14265 \begin_layout Plain Layout
14274 \begin_layout Standard
14275 The automatic conversion only handles syntax changes.
14276 It cannot handle the case where the contents of included files was changed,
14277 so these will have to be converted separately.
14280 \begin_layout Section
14282 \begin_inset CommandInset label
14284 name "sec:templates"
14291 \begin_layout Standard
14292 Templates are created just like usual documents.
14293 The only difference is that usual documents contain all possible settings,
14294 including the font scheme and the paper size.
14295 Usually a user doesn't want a template to overwrite his defaults in these
14297 For that reason, the designer of a template should remove the corresponding
14299 \begin_inset Flex CharStyle:Code
14302 \begin_layout Plain Layout
14311 \begin_inset Flex CharStyle:Code
14314 \begin_layout Plain Layout
14322 from the template LyX file.
14323 This can be done with any simple text-editor, for example
14324 \begin_inset Flex CharStyle:Code
14327 \begin_layout Plain Layout
14334 \begin_inset Flex CharStyle:Code
14337 \begin_layout Plain Layout
14347 \begin_layout Standard
14348 Put the edited template files you create in
14349 \begin_inset Flex CharStyle:Code
14352 \begin_layout Plain Layout
14358 , copy the ones you use from the global template directory in
14359 \begin_inset Flex CharStyle:Code
14362 \begin_layout Plain Layout
14368 to the same place, and redefine the template path in the
14369 \begin_inset Flex CharStyle:MenuItem
14372 \begin_layout Plain Layout
14380 \SpecialChar \menuseparator
14385 references\SpecialChar \menuseparator
14394 \begin_layout Standard
14395 Note that there is a template which has a particular meaning:
14396 \begin_inset Flex CharStyle:Code
14399 \begin_layout Plain Layout
14406 This template is loaded everytime you create a new document with
14407 \begin_inset Flex CharStyle:MenuItem
14410 \begin_layout Plain Layout
14420 \SpecialChar \menuseparator
14422 \begin_inset Flex CharStyle:MenuItem
14425 \begin_layout Plain Layout
14435 in order to provide useful defaults.
14436 To create this template from inside LyX, all you have to do is to open
14437 a document with the correct settings, and use the
14438 \begin_inset Flex CharStyle:MenuItem
14441 \begin_layout Plain Layout
14446 e as Document Defaults
14454 \begin_layout Chapter
14455 Including External Material
14458 \begin_layout Standard
14459 The use of material from sources external to LyX is covered in detail in
14465 This part of the manual covers what needs to happen behind the scenes for
14466 new sorts of material to be included.
14469 \begin_layout Section
14473 \begin_layout Standard
14474 The external material feature is based on the concept of a
14479 A template is a specification of how LyX should interface with a certain
14481 As bundled, LyX comes with predefined templates for Xfig figures, various
14482 raster format images, chess diagrams, and LilyPond music notation.
14483 You can check the actual list by using the menu
14484 \begin_inset Flex CharStyle:MenuItem
14487 \begin_layout Plain Layout
14488 Insert\SpecialChar \menuseparator
14489 File\SpecialChar \menuseparator
14496 Furthermore, it is possible to roll your own template to support a specific
14498 Later we'll describe in more detail what is involved, and hopefully you
14499 will submit all the templates you create so we can include them in a later
14503 \begin_layout Standard
14504 Another basic idea of the external material feature is to distinguish between
14505 the original file that serves as a base for final material and the produced
14506 file that is included in your exported or printed document.
14507 For example, consider the case of a figure produced with
14508 \begin_inset Flex CharStyle:Code
14511 \begin_layout Plain Layout
14518 The Xfig application itself works on an original file with the
14519 \begin_inset Flex CharStyle:Code
14522 \begin_layout Plain Layout
14529 Within XFig, you create and change your figure, and when you are done,
14531 \begin_inset Flex CharStyle:Code
14534 \begin_layout Plain Layout
14541 When you want to include the figure in your document, you invoke
14542 \begin_inset Flex CharStyle:Code
14545 \begin_layout Plain Layout
14551 in order to create a PostScript file that can readily be included in your
14554 \begin_inset Flex CharStyle:Code
14557 \begin_layout Plain Layout
14563 file is the original file, and the PostScript file is the produced file.
14566 \begin_layout Standard
14567 This distinction is important in order to allow updating of the material
14568 while you are in the process of writing the document.
14569 Furthermore, it provides us with the flexibility that is needed to support
14570 multiple export formats.
14571 For instance, in the case of a plain text file, it is not exactly an award-winn
14572 ing idea to include the figure as raw PostScript®.
14573 Instead, you'd either prefer to just include a reference to the figure
14574 or try to invoke some graphics to Ascii converter to make the final result
14575 look similar to the real graphics.
14576 The external material management allows you to do this, because it is parameter
14577 ized on the different export formats that LyX supports.
14580 \begin_layout Standard
14581 Besides supporting the production of different products according to the
14582 exported format, it supports tight integration with editing and viewing
14584 In the case of an XFig figure, you are able to invoke Xfig on the original
14585 file with a single click from within the external material dialog in LyX,
14586 and also preview the produced PostScript file with ghostview with another
14588 No more fiddling around with the command line and/or file browsers to locate
14589 and manipulate the original or produced files.
14590 In this way, you are finally able to take full advantage of the many different
14591 applications that are relevant to use when you write your documents, and
14592 ultimately be more productive.
14595 \begin_layout Section
14596 The external template configuration file
14599 \begin_layout Standard
14600 It is relatively easy to add custom external template definitions to LyX.
14601 However, be aware that doing this in an careless manner most probably
14605 introduce an easily exploitable security hole.
14606 So before you do this, please read the discussion about security in section
14608 \begin_inset CommandInset ref
14610 reference "sec:Security-discussion"
14617 \begin_layout Standard
14618 Having said that, we encourage you to submit any interesting templates that
14623 \begin_layout Standard
14624 The external templates are defined in the
14625 \begin_inset Flex CharStyle:Code
14628 \begin_layout Plain Layout
14629 LyXDir/lib/external_templates
14635 You can place your own version in
14636 \begin_inset Flex CharStyle:Code
14639 \begin_layout Plain Layout
14640 UserDir/external_templates
14648 \begin_layout Standard
14649 A typical template looks like this:
14652 \begin_layout LyX-Code
14656 \begin_layout LyX-Code
14657 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14660 \begin_layout LyX-Code
14664 \begin_layout LyX-Code
14668 \begin_layout LyX-Code
14672 \begin_layout LyX-Code
14676 \begin_layout LyX-Code
14680 \begin_layout LyX-Code
14681 AutomaticProduction true
14684 \begin_layout LyX-Code
14688 \begin_layout LyX-Code
14692 \begin_layout LyX-Code
14696 \begin_layout LyX-Code
14697 TransformCommand Rotate RotationLatexCommand
14700 \begin_layout LyX-Code
14701 TransformCommand Resize ResizeLatexCommand
14704 \begin_layout LyX-Code
14705 Product "$$RotateFront$$ResizeFront
14708 \begin_layout LyX-Code
14713 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14716 \begin_layout LyX-Code
14717 $$ResizeBack$$RotateBack"
14720 \begin_layout LyX-Code
14724 \begin_layout LyX-Code
14725 UpdateResult "$$AbsPath$$Basename.pstex_t"
14728 \begin_layout LyX-Code
14729 Requirement "graphicx"
14732 \begin_layout LyX-Code
14733 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14736 \begin_layout LyX-Code
14737 ReferencedFile latex "$$AbsPath$$Basename.eps"
14740 \begin_layout LyX-Code
14741 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14744 \begin_layout LyX-Code
14748 \begin_layout LyX-Code
14752 \begin_layout LyX-Code
14753 TransformCommand Rotate RotationLatexCommand
14756 \begin_layout LyX-Code
14757 TransformCommand Resize ResizeLatexCommand
14760 \begin_layout LyX-Code
14761 Product "$$RotateFront$$ResizeFront
14764 \begin_layout LyX-Code
14769 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14772 \begin_layout LyX-Code
14773 $$ResizeBack$$RotateBack"
14776 \begin_layout LyX-Code
14777 UpdateFormat pdftex
14780 \begin_layout LyX-Code
14781 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14784 \begin_layout LyX-Code
14785 Requirement "graphicx"
14788 \begin_layout LyX-Code
14789 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14792 \begin_layout LyX-Code
14793 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14796 \begin_layout LyX-Code
14800 \begin_layout LyX-Code
14804 \begin_layout LyX-Code
14805 Product "$$Contents(
14807 "$$AbsPath$$Basename.asc
14812 \begin_layout LyX-Code
14813 UpdateFormat asciixfig
14816 \begin_layout LyX-Code
14817 UpdateResult "$$AbsPath$$Basename.asc"
14820 \begin_layout LyX-Code
14824 \begin_layout LyX-Code
14828 \begin_layout LyX-Code
14829 Product "<graphic fileref=
14831 "$$AbsOrRelPathMaster$$Basename.eps
14836 \begin_layout LyX-Code
14840 \begin_layout LyX-Code
14844 \begin_layout LyX-Code
14845 UpdateResult "$$AbsPath$$Basename.eps"
14848 \begin_layout LyX-Code
14849 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14852 \begin_layout LyX-Code
14853 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14856 \begin_layout LyX-Code
14860 \begin_layout LyX-Code
14861 Product "[XFig: $$FName]"
14864 \begin_layout LyX-Code
14868 \begin_layout LyX-Code
14872 \begin_layout Standard
14873 As you can see, the template is enclosed in
14874 \begin_inset Flex CharStyle:Code
14877 \begin_layout Plain Layout
14883 \SpecialChar \ldots{}
14885 \begin_inset Flex CharStyle:Code
14888 \begin_layout Plain Layout
14895 It contains a header specifying some general settings and, for each supported
14896 primary document file format, a section
14897 \begin_inset Flex CharStyle:Code
14900 \begin_layout Plain Layout
14906 \SpecialChar \ldots{}
14908 \begin_inset Flex CharStyle:Code
14911 \begin_layout Plain Layout
14920 \begin_layout Subsection
14921 The template header
14924 \begin_layout Description
14925 \begin_inset Flex CharStyle:Code
14928 \begin_layout Plain Layout
14929 AutomaticProduction
14930 \begin_inset space ~
14938 Whether the file represented by the template must be generated by LyX.
14939 This command must occur exactly once.
14942 \begin_layout Description
14943 \begin_inset Flex CharStyle:Code
14946 \begin_layout Plain Layout
14948 \begin_inset space ~
14956 A glob pattern that is used in the file dialog to filter out the desired
14958 If there is more than one possible file extension (e.g.
14959 \begin_inset space ~
14963 \begin_inset Flex CharStyle:Code
14966 \begin_layout Plain Layout
14973 \begin_inset Flex CharStyle:Code
14976 \begin_layout Plain Layout
14982 ), use something like
14983 \begin_inset Flex CharStyle:Code
14986 \begin_layout Plain Layout
14993 This command must occur exactly once.
14996 \begin_layout Description
14997 \begin_inset Flex CharStyle:Code
15000 \begin_layout Plain Layout
15002 \begin_inset space ~
15010 The text that is displayed on the button.
15011 This command must occur exactly once.
15014 \begin_layout Description
15015 \begin_inset Flex CharStyle:Code
15018 \begin_layout Plain Layout
15020 \begin_inset space ~
15024 \begin_inset space ~
15032 The help text that is used in the External dialog.
15033 Provide enough information to explain to the user just what the template
15034 can provide him with.
15035 This command must occur exactly once.
15038 \begin_layout Description
15039 \begin_inset Flex CharStyle:Code
15042 \begin_layout Plain Layout
15044 \begin_inset space ~
15052 The file format of the original file.
15053 This must be the name of a format that is known to LyX (see section
15054 \begin_inset CommandInset ref
15056 reference "sub:Formats"
15062 \begin_inset Quotes eld
15066 \begin_inset Flex CharStyle:Code
15069 \begin_layout Plain Layout
15076 \begin_inset Quotes erd
15079 if the template can handle original files of more than one format.
15080 LyX will attempt to interrogate the file itself in order to deduce its
15081 format in this case.
15082 This command must occur exactly once.
15085 \begin_layout Description
15086 \begin_inset Flex CharStyle:Code
15089 \begin_layout Plain Layout
15091 \begin_inset space ~
15099 A unique name for the template.
15100 It must not contain substitution macros (see below).
15103 \begin_layout Description
15104 \begin_inset Flex CharStyle:Code
15107 \begin_layout Plain Layout
15109 \begin_inset space ~
15112 Rotate|Resize|Clip|Extra
15117 This command specifies which transformations are supported by this template.
15118 It may occur zero or more times.
15119 This command enables the corresponding tabs in the external dialog.
15121 \begin_inset Flex CharStyle:Code
15124 \begin_layout Plain Layout
15130 command must have either a corresponding
15131 \begin_inset Flex CharStyle:Code
15134 \begin_layout Plain Layout
15141 \begin_inset Flex CharStyle:Code
15144 \begin_layout Plain Layout
15151 \begin_inset Flex CharStyle:Code
15154 \begin_layout Plain Layout
15161 Otherwise the transformation will not be supported by that format.
15164 \begin_layout Subsection
15168 \begin_layout Description
15169 \begin_inset Flex CharStyle:Code
15172 \begin_layout Plain Layout
15174 \begin_inset space ~
15177 LaTeX|PDFLaTeX|PlainText|DocBook
15182 The primary document file format that this format definition is for.
15183 Not every template has a sensible representation in all document file formats.
15184 Please define nevertheless a
15185 \begin_inset Flex CharStyle:Code
15188 \begin_layout Plain Layout
15194 section for all formats.
15195 Use a dummy text when no representation is available.
15196 Then you can at least see a reference to the external material in the exported
15200 \begin_layout Description
15201 \begin_inset Flex CharStyle:Code
15204 \begin_layout Plain Layout
15206 \begin_inset space ~
15210 \begin_inset space ~
15218 This command defines an additional macro
15219 \begin_inset Flex CharStyle:Code
15222 \begin_layout Plain Layout
15228 for substitution in
15229 \begin_inset Flex CharStyle:Code
15232 \begin_layout Plain Layout
15240 \begin_inset Flex CharStyle:Code
15243 \begin_layout Plain Layout
15249 itself may contain substitution macros.
15250 The advantage over using
15251 \begin_inset Flex CharStyle:Code
15254 \begin_layout Plain Layout
15261 \begin_inset Flex CharStyle:Code
15264 \begin_layout Plain Layout
15270 is that the substituted value of
15271 \begin_inset Flex CharStyle:Code
15274 \begin_layout Plain Layout
15280 is sanitized so that it is a valid optional argument in the document format.
15281 This command may occur zero or more times.
15284 \begin_layout Description
15285 \begin_inset Flex CharStyle:Code
15288 \begin_layout Plain Layout
15290 \begin_inset space ~
15298 The text that is inserted in the exported document.
15299 This is actually the most important command and can be quite complex.
15300 This command must occur exactly once.
15303 \begin_layout Description
15304 \begin_inset Flex CharStyle:Code
15307 \begin_layout Plain Layout
15309 \begin_inset space ~
15317 This command specifies a preamble snippet that will be included in the
15319 It has to be defined using
15320 \begin_inset Flex CharStyle:Code
15323 \begin_layout Plain Layout
15329 \SpecialChar \ldots{}
15331 \begin_inset Flex CharStyle:Code
15334 \begin_layout Plain Layout
15341 This command may occur zero or more times.
15344 \begin_layout Description
15345 \begin_inset Flex CharStyle:Code
15348 \begin_layout Plain Layout
15350 \begin_inset space ~
15354 \begin_inset space ~
15362 This command denotes files that are created by the conversion process and
15363 are needed for a particular export format.
15364 If the filename is relative, it is interpreted relative to the master document.
15365 This command may be given zero or more times.
15368 \begin_layout Description
15369 \begin_inset Flex CharStyle:Code
15372 \begin_layout Plain Layout
15374 \begin_inset space ~
15382 The name of a required LaTeX package.
15383 The package is included via
15384 \begin_inset Flex CharStyle:Code
15387 \begin_layout Plain Layout
15395 in the LaTeX preamble.
15396 This command may occur zero or more times.
15399 \begin_layout Description
15400 \begin_inset Flex CharStyle:Code
15403 \begin_layout Plain Layout
15405 \begin_inset space ~
15409 \begin_inset space ~
15412 RotationLatexCommand
15417 This command specifies that the built in LaTeX command should be used for
15419 This command may occur once or not at all.
15422 \begin_layout Description
15423 \begin_inset Flex CharStyle:Code
15426 \begin_layout Plain Layout
15428 \begin_inset space ~
15432 \begin_inset space ~
15440 This command specifies that the built in LaTeX command should be used for
15442 This command may occur once or not at all.
15445 \begin_layout Description
15446 \begin_inset Flex CharStyle:Code
15449 \begin_layout Plain Layout
15451 \begin_inset space ~
15455 \begin_inset space ~
15458 RotationLatexOption
15463 This command specifies that rotation is done via an optional argument.
15464 This command may occur once or not at all.
15467 \begin_layout Description
15468 \begin_inset Flex CharStyle:Code
15471 \begin_layout Plain Layout
15473 \begin_inset space ~
15477 \begin_inset space ~
15485 This command specifies that resizing is done via an optional argument.
15486 This command may occur once or not at all.
15489 \begin_layout Description
15490 \begin_inset Flex CharStyle:Code
15493 \begin_layout Plain Layout
15495 \begin_inset space ~
15499 \begin_inset space ~
15507 This command specifies that clipping is done via an optional argument.
15508 This command may occur once or not at all.
15511 \begin_layout Description
15512 \begin_inset Flex CharStyle:Code
15515 \begin_layout Plain Layout
15517 \begin_inset space ~
15521 \begin_inset space ~
15529 This command specifies that an extra optional argument is used.
15530 This command may occur once or not at all.
15533 \begin_layout Description
15534 \begin_inset Flex CharStyle:Code
15537 \begin_layout Plain Layout
15539 \begin_inset space ~
15547 The file format of the converted file.
15548 This must be the name of a format that is known to LyX (see the
15549 \begin_inset Flex CharStyle:MenuItem
15552 \begin_layout Plain Layout
15557 ools\SpecialChar \menuseparator
15562 references:Conversion
15568 This command must occur exactly once.
15571 \begin_layout Description
15572 \begin_inset Flex CharStyle:Code
15575 \begin_layout Plain Layout
15577 \begin_inset space ~
15585 The file name of the converted file.
15586 The file name must be absolute.
15587 This command must occur exactly once.
15590 \begin_layout Subsection
15591 Preamble definitions
15594 \begin_layout Standard
15595 The external template configuration file may contain additional preamble
15596 definitions enclosed by
15597 \begin_inset Flex CharStyle:Code
15600 \begin_layout Plain Layout
15606 \SpecialChar \ldots{}
15608 \begin_inset Flex CharStyle:Code
15611 \begin_layout Plain Layout
15618 They can be used by the templates in the
15619 \begin_inset Flex CharStyle:Code
15622 \begin_layout Plain Layout
15631 \begin_layout Section
15632 The substitution mechanism
15635 \begin_layout Standard
15636 When the external material facility invokes an external program, it is done
15637 on the basis of a command defined in the template configuration file.
15638 These commands can contain various macros that are expanded before execution.
15639 Execution always take place in the directory of the containing document.
15642 \begin_layout Standard
15643 Also, whenever external material is to be displayed, the name will be produced
15644 by the substitution mechanism, and most other commands in the template
15645 definition support substitution as well.
15648 \begin_layout Standard
15649 The available macros are the following:
15652 \begin_layout Description
15653 \begin_inset Flex CharStyle:Code
15656 \begin_layout Plain Layout
15657 $$AbsOrRelPathMaster
15662 The file path, absolute or relative to the master LyX document.
15665 \begin_layout Description
15666 \begin_inset Flex CharStyle:Code
15669 \begin_layout Plain Layout
15670 $$AbsOrRelPathParent
15675 The file path, absolute or relative to the LyX document.
15678 \begin_layout Description
15679 \begin_inset Flex CharStyle:Code
15682 \begin_layout Plain Layout
15688 The absolute file path.
15691 \begin_layout Description
15692 \begin_inset Flex CharStyle:Code
15695 \begin_layout Plain Layout
15701 The filename without path and without the extension.
15704 \begin_layout Description
15705 \begin_inset Flex CharStyle:Code
15708 \begin_layout Plain Layout
15710 \begin_inset Quotes eld
15714 \begin_inset Quotes erd
15722 This macro will expand to the contents of the file with the name
15723 \begin_inset Flex CharStyle:Code
15726 \begin_layout Plain Layout
15735 \begin_layout Description
15736 \begin_inset Flex CharStyle:Code
15739 \begin_layout Plain Layout
15745 The file extension (including the dot).
15748 \begin_layout Description
15749 \begin_inset Flex CharStyle:Code
15752 \begin_layout Plain Layout
15758 The filename of the file specified in the external material dialog.
15759 This is either an absolute name, or it is relative to the LyX document.
15762 \begin_layout Description
15763 \begin_inset Flex CharStyle:Code
15766 \begin_layout Plain Layout
15773 \begin_inset Flex CharStyle:Code
15776 \begin_layout Plain Layout
15782 (absolute name or relative to the LyX document).
15785 \begin_layout Description
15786 \begin_inset Flex CharStyle:Code
15789 \begin_layout Plain Layout
15795 The file path, relative to the master LyX document.
15798 \begin_layout Description
15799 \begin_inset Flex CharStyle:Code
15802 \begin_layout Plain Layout
15808 The file path, relative to the LyX document.
15811 \begin_layout Description
15812 \begin_inset Flex CharStyle:Code
15815 \begin_layout Plain Layout
15821 This macro will expand to the absolute path of the system directory.
15822 This is typically used to point to the various helper scripts that are
15826 \begin_layout Description
15827 \begin_inset Flex CharStyle:Code
15830 \begin_layout Plain Layout
15836 A name and full path to a temporary file which will be automatically deleted
15837 whenever the containing document is closed, or the external material insertion
15841 \begin_layout Standard
15842 All path macros contain a trailing directory separator, so you can construct
15844 the absolute filename with
15845 \begin_inset Flex CharStyle:Code
15848 \begin_layout Plain Layout
15849 $$AbsPath$$Basename$$Extension
15857 \begin_layout Standard
15858 The macros above are substituted in all commands unless otherwise noted.
15860 \begin_inset Flex CharStyle:Code
15863 \begin_layout Plain Layout
15869 supports additionally the following substitutions if they are enabled by
15871 \begin_inset Flex CharStyle:Code
15874 \begin_layout Plain Layout
15881 \begin_inset Flex CharStyle:Code
15884 \begin_layout Plain Layout
15893 \begin_layout Description
15894 \begin_inset Flex CharStyle:Code
15897 \begin_layout Plain Layout
15903 The front part of the resize command.
15906 \begin_layout Description
15907 \begin_inset Flex CharStyle:Code
15910 \begin_layout Plain Layout
15916 The back part of the resize command.
15919 \begin_layout Description
15920 \begin_inset Flex CharStyle:Code
15923 \begin_layout Plain Layout
15929 The front part of the rotation command.
15932 \begin_layout Description
15933 \begin_inset Flex CharStyle:Code
15936 \begin_layout Plain Layout
15942 The back part of the rotation command.
15945 \begin_layout Standard
15946 The value string of the
15947 \begin_inset Flex CharStyle:Code
15950 \begin_layout Plain Layout
15956 command supports additionally the following substitutions if they are enabled
15958 \begin_inset Flex CharStyle:Code
15961 \begin_layout Plain Layout
15968 \begin_inset Flex CharStyle:Code
15971 \begin_layout Plain Layout
15980 \begin_layout Description
15981 \begin_inset Flex CharStyle:Code
15984 \begin_layout Plain Layout
15993 \begin_layout Description
15994 \begin_inset Flex CharStyle:Code
15997 \begin_layout Plain Layout
16006 \begin_layout Description
16007 \begin_inset Flex CharStyle:Code
16010 \begin_layout Plain Layout
16019 \begin_layout Description
16020 \begin_inset Flex CharStyle:Code
16023 \begin_layout Plain Layout
16029 The rotation option.
16032 \begin_layout Standard
16033 You may ask why there are so many path macros.
16034 There are mainly two reasons:
16037 \begin_layout Enumerate
16038 Relative and absolute file names should remain relative or absolute, respectivel
16040 Users may have reasons to prefer either form.
16041 Relative names are useful for portable documents that should work on different
16042 machines, for example.
16043 Absolute names may be required by some programs.
16046 \begin_layout Enumerate
16047 LaTeX treats relative file names differently than LyX and other programs
16048 in nested included files.
16049 For LyX, a relative file name is always relative to the document that contains
16051 For LaTeX, it is always relative to the master document.
16052 These two definitions are identical if you have only one document, but
16053 differ if you have a master document that includes part documents.
16054 That means that relative filenames must be transformed when presented to
16056 Fortunately LyX does this automatically for you if you choose the right
16060 \begin_layout Standard
16061 So which path macro should be used in new template definitions? The rule
16065 \begin_layout Itemize
16067 \begin_inset Flex CharStyle:Code
16070 \begin_layout Plain Layout
16076 if an absolute path is required.
16079 \begin_layout Itemize
16081 \begin_inset Flex CharStyle:Code
16084 \begin_layout Plain Layout
16085 $$AbsOrRelPathMaster
16090 if the substituted string is some kind of LaTeX input.
16093 \begin_layout Itemize
16095 \begin_inset Flex CharStyle:Code
16098 \begin_layout Plain Layout
16099 $$AbsOrRelPathParent
16104 in order to preserve the user's choice.
16107 \begin_layout Standard
16108 There are special cases where this rule does not work and e.g.
16109 \begin_inset space ~
16112 relative names are needed, but normally it will work just fine.
16113 One example for such a case is the command
16114 \begin_inset Flex CharStyle:Code
16117 \begin_layout Plain Layout
16118 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
16123 in the XFig template above: We can't use the absolute name because the
16125 \begin_inset Flex CharStyle:Code
16128 \begin_layout Plain Layout
16134 files needs the relative name in order to rewrite the file content.
16137 \begin_layout Section
16138 \begin_inset CommandInset label
16140 name "sec:Security-discussion"
16144 Security discussion
16147 \begin_layout Standard
16148 \begin_inset Note Note
16151 \begin_layout Plain Layout
16152 This section is outdated
16157 The external material feature interfaces with a lot of external programs
16158 and does so automatically, so we have to consider the security implications
16160 In particular, since you have the option of including your own filenames
16161 and/or parameter strings and those are expanded into a command, it seems
16162 that it would be possible to create a malicious document which executes
16163 arbitrary commands when a user views or prints the document.
16164 This is something we definately want to avoid.
16167 \begin_layout Standard
16168 However, since the external program commands are specified in the template
16169 configuration file only, there are no security issues if LyX is properly
16170 configured with safe templates only.
16171 This is so because the external programs are invoked with the
16172 \begin_inset Flex CharStyle:Code
16175 \begin_layout Plain Layout
16181 -system call rather than the
16182 \begin_inset Flex CharStyle:Code
16185 \begin_layout Plain Layout
16191 system-call, so it's not possible to execute arbitrary commands from the
16192 filename or parameter section via the shell.
16195 \begin_layout Standard
16196 This also implies that you are restricted in what command strings you can
16197 use in the external material templates.
16198 In particular, pipes and redirection are not readily available.
16199 This has to be so if LyX should remain safe.
16200 If you want to use some of the shell features, you should write a safe
16201 script to do this in a controlled manner, and then invoke the script from
16202 the command string.
16204 \begin_inset Flex CharStyle:Code
16207 \begin_layout Plain Layout
16213 directory of the LyX installation, you can find a safe wrapper script
16214 \begin_inset Flex CharStyle:Code
16217 \begin_layout Plain Layout
16218 general_command_wrapper.py
16223 that supports redirection of input and output.
16224 That can serve as an example for how to write safe template scripts.
16225 For a more advanced example that uses
16226 \begin_inset Flex CharStyle:Code
16229 \begin_layout Plain Layout
16235 and friends, take a look at the
16236 \begin_inset Flex CharStyle:Code
16239 \begin_layout Plain Layout
16248 \begin_layout Standard
16249 It is possible to design a template that interacts directly with the shell,
16250 but since this would allow a malicious user to execute arbitrary commands
16251 by writing clever filenames and/or parameters, we generally recommend that
16252 you only use safe scripts that work with the
16253 \begin_inset Flex CharStyle:Code
16256 \begin_layout Plain Layout
16262 system call in a controlled manner.
16263 Of course, for use in a controlled environment, it can be tempting to just
16264 fall back to use ordinary shell scripts.
16265 If you do so, be aware that you
16269 provide an easily exploitable security hole in your system.
16270 Of course it stands to reason that such unsafe templates will never be
16271 included in the standard LyX distribution, although we do encourage people
16272 to submit new templates in the open source tradition.
16273 But LyX as shipped from the official distribution channels will never have
16277 \begin_layout Standard
16278 Including external material provides a lot of power, and you have to be
16279 careful not to introduce security hazards with this power.
16280 A subtle error in a single line in an innocent looking script can open
16281 the door to huge security problems.
16282 So if you do not fully understand the issues, we recommend that you consult
16283 a knowledgable security professional or the LyX development team if you
16284 have any questions about whether a given template is safe or not.
16285 And do this before you use it in an uncontrolled environment.
16288 \begin_layout Chapter
16292 \begin_layout Section
16296 \begin_layout Standard
16297 The LyX server is a method implemented in LyX that will enable other programs
16298 to talk to LyX, invoke LyX commands, and retrieve information about the
16299 LyX internal state.
16300 This is only intended for advanced users, but they should find it useful.
16301 Please note that, at present,
16303 the server does not work on Windows
16309 \begin_layout Plain Layout
16310 There is no principled reason it cannot do so.
16311 But none of the developers on Windows® have yet implemented this functionality
16320 \begin_layout Section
16321 Starting the LyX Server
16324 \begin_layout Standard
16325 The LyX server works through the use of a pair of named pipes.
16326 These are usually located in
16327 \begin_inset Flex CharStyle:Code
16330 \begin_layout Plain Layout
16337 \begin_inset Quotes eld
16341 \begin_inset Flex CharStyle:Code
16344 \begin_layout Plain Layout
16351 \begin_inset Quotes erd
16355 \begin_inset Quotes eld
16359 \begin_inset Flex CharStyle:Code
16362 \begin_layout Plain Layout
16369 \begin_inset Quotes erd
16373 External programs write into
16374 \begin_inset Flex CharStyle:Code
16377 \begin_layout Plain Layout
16383 and read back data from
16384 \begin_inset Flex CharStyle:Code
16387 \begin_layout Plain Layout
16394 The stem of the pipe names can be defined in the
16395 \begin_inset Flex CharStyle:MenuItem
16398 \begin_layout Plain Layout
16403 ools\SpecialChar \menuseparator
16413 dialog, for example
16414 \begin_inset Flex CharStyle:Code
16417 \begin_layout Plain Layout
16418 "/home/myhome/.lyxpipe"
16426 \begin_layout Standard
16428 \begin_inset Flex CharStyle:Code
16431 \begin_layout Plain Layout
16438 \begin_inset Flex CharStyle:Code
16441 \begin_layout Plain Layout
16447 ' to create the pipes.
16448 The above setting also has the effect of activating the LyX server.
16449 If one of the pipes already exists, LyX will assume that another LyX process
16450 is already running and will not start the server.
16451 To have several LyX processes with servers at the same time, you have to
16452 change the configuration between the start of the programs.
16455 \begin_layout Standard
16456 If you are developing a client program, you might find it useful to enable
16457 debugging information from the LyX server.
16458 Do this by starting LyX as lyx -dbg lyxserver.
16461 \begin_layout Standard
16462 Warning: if LyX crashes, it may not manage to remove the pipes; in this
16463 case you must remove them manually.
16464 If LyX starts and the pipes exist already, it will not start any server.
16467 \begin_layout Standard
16468 Other than this, there are a few points to consider:
16471 \begin_layout Itemize
16472 Both server and clients must run on UNIX or OS/2 machines.
16473 Communications between LyX on UNIX and clients on OS/2 or vice versa is
16474 not possible right now.
16477 \begin_layout Itemize
16478 On OS/2, only one client can connect to LyXServer at a time.
16481 \begin_layout Itemize
16482 On OS/2, clients must open inpipe with
16483 \begin_inset Flex CharStyle:Code
16486 \begin_layout Plain Layout
16495 \begin_layout Standard
16499 \begin_layout Standard
16500 You can find a complete example client written in C in the source distribution
16502 \begin_inset Flex CharStyle:Code
16505 \begin_layout Plain Layout
16506 development/lyxserver/server_monitor.c
16514 \begin_layout Section
16515 Normal communication
16518 \begin_layout Standard
16519 To issue a LyX call, the client writes a line of ASCII text into the input
16521 This line has the following format:
16524 \begin_layout Quote
16538 \begin_layout Description
16543 is a name that the client can choose arbitrarily.
16544 Its only use is that LyX will echo it if it sends an answer---so a client
16545 can dispatch results from different requesters.
16548 \begin_layout Description
16553 is the function you want LyX to perform.
16554 It is the same as the commands you'd use in the minibuffer.
16557 \begin_layout Description
16562 is an optional argument which is meaningful only to some functions (for
16564 \begin_inset Quotes eld
16568 \begin_inset Quotes erd
16571 which will insert the argument as text at the cursor position.)
16574 \begin_layout Standard
16575 The answer from LyX will arrive in the output pipe and be of the form
16578 \begin_layout Quote
16592 \begin_layout Standard
16601 are just echoed from the command request, while
16605 is more or less useful information filled according to how the command
16606 execution worked out.
16607 Some commands will return information about the internal state of LyX,
16609 \begin_inset Quotes eld
16613 \begin_inset Quotes erd
16616 , while other will return an empty data-response.
16617 This means that the command execution went fine.
16620 \begin_layout Standard
16621 In case of errors, the response from LyX will have this form
16624 \begin_layout Quote
16638 \begin_layout Standard
16643 should contain an explanation of why the command failed.
16646 \begin_layout Standard
16650 \begin_layout LyX-Code
16651 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
16654 \begin_layout LyX-Code
16655 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
16656 \begin_inset Newline newline
16659 read a <~/.lyxpipe.out
16660 \begin_inset Newline newline
16666 \begin_layout Section
16670 \begin_layout Standard
16671 LyX can notify clients of events going on asynchronously.
16672 Currently it will only do this if the user binds a key sequence with the
16674 \begin_inset Quotes eld
16678 \begin_inset Quotes erd
16682 The format of the string LyX sends is as follows:
16685 \begin_layout Quote
16686 \begin_inset Flex CharStyle:Code
16689 \begin_layout Plain Layout
16700 \begin_layout Standard
16705 is the printed representation of the key sequence that was actually typed
16709 \begin_layout Standard
16710 This mechanism can be used to extend LyX's command set and implement macros:
16711 bind some key sequence to
16712 \begin_inset Quotes eld
16716 \begin_inset Quotes erd
16719 , start a client that listens on the out pipe, dispatches the command according
16720 to the sequence and starts a function that may use LyX calls and LyX requests
16721 to issue a command or a series of commands to LyX.
16724 \begin_layout Section
16725 The simple LyX Server Protocol
16728 \begin_layout Standard
16729 LyX implements a simple protocol that can be used for session management.
16730 All messages are of the form
16733 \begin_layout Quote
16743 \begin_layout Standard
16749 \begin_inset Quotes eld
16753 \begin_inset Quotes erd
16757 \begin_inset Quotes eld
16761 \begin_inset Quotes erd
16766 \begin_inset Quotes eld
16770 \begin_inset Quotes erd
16773 is received from a client, LyX will report back to inform the client that
16774 it's listening to it's messages, while
16775 \begin_inset Quotes eld
16779 \begin_inset Quotes erd
16782 sent from LyX will inform clients that LyX is closing.