1 #LyX 1.6.0beta3 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 % the pages of the TOC are numbered roman
17 % and a pdf-bookmark for the TOC is added
19 \let\myTOC\tableofcontents
20 \renewcommand\tableofcontents{%
21 \pdfbookmark[1]{Contents}{}
24 \pagenumbering{arabic} }
26 % redefine the \LyX macro for PDF bookmarks
27 \def\LyX{\texorpdfstring{%
28 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
31 % used for multi-column text
40 InsetLayout CharStyle:MenuItem
49 \newcommand*{\menuitem}[1]{{\sffamily #1}}
54 \inputencoding default
57 \font_typewriter default
58 \font_default_family default
64 \paperfontsize default
67 \pdf_title "LyX Configuration Manual"
68 \pdf_author "The LyX Team"
70 \pdf_bookmarksnumbered false
71 \pdf_bookmarksopen false
72 \pdf_bookmarksopenlevel 1
77 \pdf_pagebackref false
85 \paperorientation portrait
92 \paragraph_separation indent
94 \quotes_language english
97 \paperpagestyle headings
98 \tracking_changes false
107 Customizing LyX: Features for the Advanced User
115 \begin_layout Plain Layout
117 If you have comments or error corrections, please send them to the LyX Documenta
118 tion mailing list, <lyx-docs@lists.lyx.org>.
126 \begin_layout Standard
127 \begin_inset CommandInset toc
128 LatexCommand tableofcontents
135 \begin_layout Chapter
139 \begin_layout Standard
140 This manual covers the customization features present in LyX.
141 In it, we discuss issues like keyboard shortcuts, screen previewing options,
142 printer options, sending commands to LyX via the LyX Server, internationalizati
143 on, installing new LaTeX classes and LyX layouts, etc.
144 We can't possibly hope to touch on everything you can change---our developers
145 add new features faster than we can document them---but we will explain
146 the most common customizations and hopefully point you in the right direction
147 for some of the more obscure ones.
150 \begin_layout Standard
151 \begin_inset Branch OutDated
154 \begin_layout Standard
155 Information from previous versions of this document that now seems to be
156 outdated is contained in the OutDated branch of this document.
157 By default, this information will not appear in the LaTeX output.
165 \begin_layout Chapter
166 LyX configuration files
169 \begin_layout Standard
170 \begin_inset CommandInset label
176 This chapter aims to help you to find your way through the LyX configuration
178 Before continuing to read this chapter, you should find out where your
179 LyX library and user directories are by using
180 \begin_inset Flex CharStyle:MenuItem
183 \begin_layout Plain Layout
188 elp\SpecialChar \menuseparator
201 The library directory is the place where LyX places its system-wide configurati
202 on files; the user directory is where you can place your modified versions.
203 We will call the former
204 \begin_inset Flex CharStyle:Code
207 \begin_layout Plain Layout
214 \begin_inset Flex CharStyle:MenuItem
217 \begin_layout Plain Layout
223 in the remainder of this document.
227 \begin_layout Section
229 \begin_inset Flex CharStyle:Code
232 \begin_layout Plain Layout
241 \begin_layout Standard
242 \begin_inset Flex CharStyle:Code
245 \begin_layout Plain Layout
251 and its sub-directories contain a number of files and that can be used
252 to customise LyX's behaviour.
253 You can change many of these files from within LyX itself through the
254 \begin_inset Flex CharStyle:MenuItem
257 \begin_layout Plain Layout
262 ools\SpecialChar \menuseparator
273 Most customization that you will want to do in LyX is possible through
275 However, many other inner aspects of LyX can be customized by modifying
277 \begin_inset Flex CharStyle:Code
280 \begin_layout Plain Layout
287 These files fall in different categories, described in the following subsection
291 \begin_layout Subsection
292 Automatically generated files
295 \begin_layout Standard
296 The files, which are to be found in
297 \begin_inset Flex CharStyle:MenuItem
300 \begin_layout Plain Layout
306 , are generated when you configure LyX.
307 They contain various default values that are guessed by inspection.
308 In general, it is not a good idea to modify them, since they might be overwritt
313 \labelwidthstring 00.00.0000
314 \begin_inset Flex CharStyle:Code
317 \begin_layout Plain Layout
323 contains defaults for various commands.
327 \labelwidthstring 00.00.0000
328 \begin_inset Flex CharStyle:Code
331 \begin_layout Plain Layout
337 contains the list of packages that have been recognized by LyX.
338 It is currently unused by the LyX program itself, but the information extracted
339 , and more, is made available with
340 \begin_inset Flex CharStyle:MenuItem
343 \begin_layout Plain Layout
348 elp\SpecialChar \menuseparator
366 \labelwidthstring 00.00.0000
367 \begin_inset Flex CharStyle:Code
370 \begin_layout Plain Layout
376 the list of text classes that have been found in your
377 \begin_inset Flex CharStyle:Code
380 \begin_layout Plain Layout
386 directories, along with the associated LaTeX document class and their descripti
391 \labelwidthstring 00.00.0000
392 \begin_inset Flex CharStyle:Code
395 \begin_layout Plain Layout
401 the list of layout modules found in your
402 \begin_inset Flex CharStyle:Code
405 \begin_layout Plain Layout
415 \labelwidthstring 00.00.0000
416 \begin_inset Flex CharStyle:Code
419 \begin_layout Plain Layout
425 lists of various sorts of LaTeX-related files found on your system
429 \labelwidthstring 00.00.0000
430 \begin_inset Flex CharStyle:Code
433 \begin_layout Plain Layout
439 is automatically generated during configuration from the file
440 \begin_inset Flex CharStyle:Code
443 \begin_layout Plain Layout
450 It contains information on your LaTeX configuration.
453 \begin_layout Subsection
457 \begin_layout Standard
458 These directories are duplicated between
459 \begin_inset Flex CharStyle:Code
462 \begin_layout Plain Layout
469 \begin_inset Flex CharStyle:Code
472 \begin_layout Plain Layout
479 If a particular files exists in both places, the one in
480 \begin_inset Flex CharStyle:Code
483 \begin_layout Plain Layout
493 \labelwidthstring 00.00.0000
494 \begin_inset Flex CharStyle:Code
497 \begin_layout Plain Layout
503 this directory contains files with the extension
504 \begin_inset Flex CharStyle:Code
507 \begin_layout Plain Layout
513 that define the keybindings used in LyX (see section
518 \begin_inset CommandInset ref
520 reference "sec:bindings"
525 If there exists an internationalized version of the bind file named
526 \begin_inset Flex CharStyle:Code
529 \begin_layout Plain Layout
535 , that will be used first.
541 \begin_inset CommandInset ref
543 reference "chap:i18n"
548 \begin_inset CommandInset ref
550 reference "sec:bindings"
558 \labelwidthstring 00.00.0000
559 \begin_inset Flex CharStyle:Code
562 \begin_layout Plain Layout
568 contains graphics files that can be included in documents.
573 \labelwidthstring 00.00.0000
574 \begin_inset Flex CharStyle:Code
577 \begin_layout Plain Layout
583 contains LyX documentation files (including the one you are currently reading).
585 \begin_inset Flex CharStyle:Code
588 \begin_layout Plain Layout
594 deserves special attention, as noted above.
595 If there exists an internationalized version of the help-document with
597 \begin_inset Flex CharStyle:Code
600 \begin_layout Plain Layout
606 prepended to the name, that will be used first.
612 \begin_inset CommandInset ref
614 reference "chap:i18n"
622 \labelwidthstring 00.00.0000
623 \begin_inset Flex CharStyle:Code
626 \begin_layout Plain Layout
632 contains example files that explain how to use some features.
633 In the file browser, press the
634 \begin_inset Flex CharStyle:MenuItem
637 \begin_layout Plain Layout
647 \labelwidthstring 00.00.0000
648 \begin_inset Flex CharStyle:Code
651 \begin_layout Plain Layout
657 contains image files that are used by the
658 \begin_inset Flex CharStyle:MenuItem
661 \begin_layout Plain Layout
668 In addition, it also contains the individual icons used in the toolbar
669 and the banners that can be shown when LyX is launched.
673 \labelwidthstring 00.00.0000
674 \begin_inset Flex CharStyle:Code
677 \begin_layout Plain Layout
683 contains keyboard keymapping files.
689 \begin_inset CommandInset ref
691 reference "sec:keymap"
699 \labelwidthstring 00.00.0000
700 \begin_inset Flex CharStyle:Code
703 \begin_layout Plain Layout
709 contains the text class and module files described in Chapter
714 \begin_inset CommandInset ref
716 reference "chap:textclass"
724 \labelwidthstring 00.00.0000
725 \begin_inset Flex CharStyle:Code
728 \begin_layout Plain Layout
735 \begin_inset Flex CharStyle:Code
738 \begin_layout Plain Layout
744 Python scripts used to convert between LyX versions.
745 These can be run from the command line if, say, you want to batch-convert
750 \labelwidthstring 00.00.0000
751 \begin_inset Flex CharStyle:Code
754 \begin_layout Plain Layout
760 contains some files that demonstrate the capabilities of the
761 \begin_inset Flex CharStyle:MenuItem
764 \begin_layout Plain Layout
775 Also contains some scripts used by LyX itself.
779 \labelwidthstring 00.00.0000
780 \begin_inset Flex CharStyle:Code
783 \begin_layout Plain Layout
789 contains the standard LyX template files described in Chapter
794 \begin_inset CommandInset ref
796 reference "sec:templates"
804 \labelwidthstring 00.00.0000
805 \begin_inset Flex CharStyle:Code
808 \begin_layout Plain Layout
814 contains files with the extension
815 \begin_inset Flex CharStyle:Code
818 \begin_layout Plain Layout
824 that define the user interface to LyX.
825 That is, the files define which items appear in which menus and the items
826 appearing on the toolbar.
828 \begin_inset CommandInset ref
837 \begin_layout Subsection
838 Files you don't want to modify
841 \begin_layout Standard
842 These files are used internally by LyX and you generally do not need to
843 modify them unless you are a developer.
847 \labelwidthstring 00.00.0000
848 \begin_inset Flex CharStyle:Code
851 \begin_layout Plain Layout
857 this file contains the list of LyX developers.
858 The contents are displayed with the menu entry
859 \begin_inset Flex CharStyle:MenuItem
862 \begin_layout Plain Layout
867 elp\SpecialChar \menuseparator
881 \labelwidthstring 00.00.0000
882 \begin_inset Flex CharStyle:Code
885 \begin_layout Plain Layout
891 this is a LaTeX script used during the configuration process.
896 \labelwidthstring 00.00.0000
897 \begin_inset Flex CharStyle:Code
900 \begin_layout Plain Layout
906 this is the script that is used to re-configure LyX.
907 It creates configuration files in the directory it was run from.
910 \begin_layout Subsection
911 Other files needing a line or two...
915 \labelwidthstring 00.00.0000
916 \begin_inset Flex CharStyle:Code
919 \begin_layout Plain Layout
925 this contains tables describing how different character encodings can be
930 \labelwidthstring 00.00.0000
931 \begin_inset Flex CharStyle:Code
934 \begin_layout Plain Layout
940 this file contains the templates available to the new
941 \begin_inset Flex CharStyle:MenuItem
944 \begin_layout Plain Layout
958 \labelwidthstring 00.00.0000
959 \begin_inset Flex CharStyle:Code
962 \begin_layout Plain Layout
968 this file contains a list of all the languages currently supported by LyX.
971 \begin_layout Section
972 Your local configuration directory
975 \begin_layout Standard
976 Even if you are using LyX as an unprivileged user, you might want to change
977 LyX configuration for your own use.
979 \begin_inset Flex CharStyle:Code
982 \begin_layout Plain Layout
988 directory contains all your personal configuration files.
989 This is the directory described as
990 \begin_inset Quotes eld
994 \begin_inset Quotes erd
998 \begin_inset Flex CharStyle:MenuItem
1001 \begin_layout Plain Layout
1006 elp\SpecialChar \menuseparator
1008 \begin_inset space ~
1017 This directory is used as a mirror of
1018 \begin_inset Flex CharStyle:Code
1021 \begin_layout Plain Layout
1027 , which means that every file in
1028 \begin_inset Flex CharStyle:Code
1031 \begin_layout Plain Layout
1037 is a replacement for the corresponding file in
1038 \begin_inset Flex CharStyle:Code
1041 \begin_layout Plain Layout
1048 Any configuration file described in the above sections can be placed either
1049 in the system-wide directory, in which case it will affect all users, or
1050 in your local directory for your own use.
1053 \begin_layout Standard
1054 To make things clearer, let's provide a few examples:
1057 \begin_layout Itemize
1058 The preferences set in the
1059 \begin_inset Flex CharStyle:MenuItem
1062 \begin_layout Plain Layout
1067 ools\SpecialChar \menuseparator
1077 dialog are saved to a file
1078 \begin_inset Flex CharStyle:Code
1081 \begin_layout Plain Layout
1088 \begin_inset Flex CharStyle:Code
1091 \begin_layout Plain Layout
1100 \begin_layout Itemize
1101 When you reconfigure using
1102 \begin_inset Flex CharStyle:MenuItem
1105 \begin_layout Plain Layout
1110 ools\SpecialChar \menuseparator
1121 \begin_inset Flex CharStyle:Code
1124 \begin_layout Plain Layout
1130 script, and the resulting files are written in your local configuration
1132 This means that any additional text class file that you might have added
1134 \begin_inset Flex CharStyle:Code
1137 \begin_layout Plain Layout
1143 will be added to the list of classes in the
1144 \begin_inset Flex CharStyle:MenuItem
1147 \begin_layout Plain Layout
1152 ocument\SpecialChar \menuseparator
1165 \begin_layout Itemize
1166 If you get some updated documentation from LyX ftp site and cannot install
1167 it because you do not have sysadmin rights on your system, you can just
1169 \begin_inset Flex CharStyle:Code
1172 \begin_layout Plain Layout
1178 and the items in the
1179 \begin_inset Flex CharStyle:MenuItem
1182 \begin_layout Plain Layout
1192 menu will open them!
1195 \begin_layout Section
1196 Running LyX with multiple configurations
1199 \begin_layout Standard
1200 The configuration freedom of the local configuration directory may not suffice
1201 if you want to have more than one configuration at your disposal.
1202 For example, you may want to be use different key bindings or printer settings
1204 You can achieve this by having several such directories.
1205 You then specify which directory to use at run-time.
1208 \begin_layout Standard
1209 Invoking LyX with the command line switch
1210 \begin_inset Flex CharStyle:Code
1213 \begin_layout Plain Layout
1223 instructs the program to read the configuration from that directory, and
1224 not from the default directory.
1225 (You can determine the default directory by running LyX without the
1226 \begin_inset Flex CharStyle:Code
1229 \begin_layout Plain Layout
1235 switch.) If the specified directory does not exist, LyX offers to create
1236 it for you, just like it does for the default directory on the first time
1237 you run the program.
1238 You can modify the configuration options in this additional user directory
1239 exactly as you would for the default directory.
1240 These directories are completely independent (but read on).
1241 Note that setting the environment variable
1242 \begin_inset Flex CharStyle:Code
1245 \begin_layout Plain Layout
1251 to some value has exactly the same effect.
1254 \begin_layout Standard
1255 Having several configurations also requires more maintenance: if you want
1256 to add a new layout to
1257 \begin_inset Flex CharStyle:Code
1260 \begin_layout Plain Layout
1266 which you want available from all your configurations, you must add it
1267 to each directory separately.
1268 You can avoid this with the following trick: after LyX creates the additional
1269 directory, most of the subdirectories (see above) are empty.
1270 If you want the new configuration to mirror an existing one, replace the
1271 empty subdirectory with a symbolic link to the matching subdirectory in
1272 the existing configuration.
1274 \begin_inset Flex CharStyle:Code
1277 \begin_layout Plain Layout
1283 subirectory, however, since it contains a file written by the configuration
1284 script (also accessible through
1285 \begin_inset Flex CharStyle:MenuItem
1288 \begin_layout Plain Layout
1293 ools\SpecialChar \menuseparator
1303 ) which is configuration-specific.
1306 \begin_layout Chapter
1307 The Preferences dialog
1310 \begin_layout Section
1311 Using the dialog for the first time
1314 \begin_layout Standard
1316 \begin_inset Flex CharStyle:Code
1319 \begin_layout Plain Layout
1325 file will contain only changes that you have made to the default behaviour,
1326 some of which is hard-coded into LyX and some of which is contained in
1328 \begin_inset Flex CharStyle:Code
1331 \begin_layout Plain Layout
1332 LyXDir/lyxrc.defaults
1338 Note that in both files lines beginning with a
1339 \begin_inset Quotes eld
1343 \begin_inset Quotes erd
1346 are just comments and are not interpreted.
1347 However, only system administrators should edit
1348 \begin_inset Flex CharStyle:Code
1351 \begin_layout Plain Layout
1352 LyXDir/lyxrc.defaults
1358 Users should use the
1359 \begin_inset Flex CharStyle:MenuItem
1362 \begin_layout Plain Layout
1367 ools\SpecialChar \menuseparator
1377 dialog to create and modify their own
1378 \begin_inset Flex CharStyle:Code
1381 \begin_layout Plain Layout
1390 \begin_layout Standard
1392 \begin_inset Flex CharStyle:MenuItem
1395 \begin_layout Plain Layout
1400 ools\SpecialChar \menuseparator
1410 dialog will be largely self-explanatory.
1411 Most things in the dialog have associated `tool tips': hover your mouse
1412 pointer over something for more information.
1413 Before we highlight a few of the more important commands below, however,
1415 \begin_inset Flex CharStyle:MenuItem
1418 \begin_layout Plain Layout
1424 ing some of your changes (e.g., screen fonts) will have an instant effect.
1426 changing the bind file) will not.
1427 If nothing appears to have changed, just
1428 \begin_inset Flex CharStyle:MenuItem
1431 \begin_layout Plain Layout
1437 the changes and restart LyX.
1440 \begin_layout Section
1444 \begin_layout Subsection
1448 \begin_layout Standard
1449 The font used to display your documents on the LyX screen is very important,
1450 since you'll be reading all your documents with this font.
1451 Therefore it is important that the font be as readable and good-looking
1453 The LyX team tried to provide the best possible default font for you, but
1454 since systems can be so different, it's quite possible that the default
1455 fonts will be sub-optimal on your system.
1456 Fortunately, you can do something about this.
1457 Before we explain how, you should learn a bit more about fonts so that
1458 you are better prepared for choosing your fonts.
1459 There are trade-offs that are specific to your preferences and the capabilities
1463 \begin_layout Standard
1464 Notice that this section only deals with the fonts on the
1468 inside the LyX window.
1469 The fonts that appear on the
1477 are independent from these fonts, and are determined by the document class.
1482 to learn how to change the font of the printed version of your document.
1485 \begin_layout Standard
1486 Basically, screen fonts come in two different kinds: scalable outline fonts
1487 and non-scalable bitmap fonts.
1488 This distinction seems a bit arbitrary, since non-scalable fonts are actually
1489 scalable in most modern font renderers.
1490 The difference lies in the
1494 of the scaling and the
1499 The most important decision is thus whether you should use non-scalable
1500 bitmap fonts or scalable outline fonts.
1503 \begin_layout Standard
1504 The scalable fonts are built from
1508 of the single glyphs (i.e.
1509 characters) in the font.
1510 This means that each glyph is defined using mathematical curves that are
1511 well suited for scaling to any requested size.
1512 This mathematical definition is interpreted by the font renderer and turned
1513 into a small picture composed of pixels according to which size and glyph
1514 (or symbol) the programmer requests.
1515 This means that scalable fonts will look pretty good in most sizes.Since
1516 scalable fonts are defined in an abstract way, it can be hard to provide
1517 a good rendering at small sizes, where each pixel has to be very carefully
1518 computed to provide a good image.
1519 Technically it is possible to do this from the mathematical definition,
1520 but in order to keep the rendering reasonably fast, tradeoffs have to be
1521 made, and the result is that scalable fonts can be difficult to read at
1525 \begin_layout Standard
1526 Bitmap fonts on the other hand, are defined by bitmap graphics from the
1527 start, so they will look good at all the sizes they are meant for.
1528 However, they don't scale well, because in order to scale a glyph, each
1529 pixel is enlarged into several pixels.
1530 It is the same effect that happens if you try to enlarge a picture in an
1531 image manipulation program.
1532 In order to relieve this effect, bitmap fonts are typically provided in
1533 several fixed sizes typically from around 8 pixels high up to 34 pixels
1534 or so high in steps according to what is believed to be useful.
1535 The advantage of bitmap fonts is that no complicated computations are necessary
1536 to display each glyph, so bitmap fonts are thus faster displayed than scalable
1538 The disadvantage is that sizes that don't exists as fixed versions have
1539 to be scaled by doubling pixels, and thus look bad.
1542 \begin_layout Standard
1543 The net result of all this is that bitmap fonts are generally best for the
1544 small sizes, where they are available, while scalable fonts are generally
1545 best for large sizes.
1546 The logical conclusion would thus be to use bitmap fonts for the small
1547 sizes, and scalable fonts for the large sizes.
1548 Unfortunately, this is not a good idea, since bitmap fonts and scalable
1549 fonts are not designed to be used together, so the overall look of such
1550 a scheme would be bad.
1551 The best you can do is thus to try both schemes and decide for yourself
1555 \begin_layout Standard
1556 In the following, we will describe what to do if the text does not look
1558 We'll start with the most important parameters: DPI and font zoom.
1561 \begin_layout Subsubsection
1562 DPI setting and Font Zoom
1565 \begin_layout Standard
1566 LyX automatically tries to scale the fonts to look as close as the paper
1567 output size as possible, except for the so-called font zoom factor.
1570 \begin_layout Standard
1571 In order for this to work on all systems, it relies on the screen DPI (dots
1572 per inch) setting to be correct.
1573 The DPI setting for your system is autodetected by LyX using information
1574 provided by your system.
1575 You can check what LyX autodetects the DPI setting to, by running LyX as
1577 \begin_inset Flex CharStyle:Code
1580 \begin_layout Plain Layout
1589 \begin_layout Standard
1590 On many systems, this will not be correct, so you should check that it is
1592 On X11 systems, you can run
1593 \begin_inset Quotes eld
1597 \begin_inset Flex CharStyle:Code
1600 \begin_layout Plain Layout
1607 \begin_inset Quotes erd
1610 and write down what the DPI is for the resolution you use (this will be
1611 close to the value LyX detects).
1612 It is the number mentioned as
1613 \begin_inset Quotes eld
1617 \begin_inset Quotes erd
1621 Also write down the number of pixels you have in the width (the first number
1623 \begin_inset Quotes eld
1627 \begin_inset Quotes erd
1633 \begin_layout Standard
1634 Then get the good old ruler out of the closet, and measure the width of
1635 the visible screen-image on your monitor.
1636 Convert this measurement to inches if you used a centimeter ruler by dividing
1638 Now you can determine the correct DPI setting for your screen by dividing
1639 the number of pixels in the width by the width of the screen-image on the
1641 If this number is more than, say, 5 DPI from the detected value, you should
1642 either fix your system setup, or at least tell LyX that the DPI is different
1643 than the detected value.
1646 \begin_layout Standard
1647 If you can't fix system setup (which of course is best since other programs
1648 than LyX will benefit from this as well), you can tell LyX the correct
1650 \begin_inset Flex CharStyle:MenuItem
1653 \begin_layout Plain Layout
1662 \begin_layout Standard
1663 If the text is too small or too big for your taste, you should fiddle with
1664 the font zoom setting.
1665 This setting is used to scale the point size of the text.
1666 If your DPI setting is correct, and the font zoom setting is set to 100,
1667 this means that LyX will try to display the text exactly the same size
1668 as it will appear on the paper-output.
1669 If you set the zoom factor to 200, the text will try to be 2 times as big
1671 Of course, this will only happen if LyX can find a font that has the appropriat
1672 e size, which you can't count on.
1673 Since LyX is a WYSIWYM system anyways, this limitation isn't much of an
1677 \begin_layout Standard
1678 The default font zoom setting is 150, since a monitor is typically wider
1679 than a piece of paper, but you should try to fiddle with it through the
1681 \begin_inset Flex CharStyle:MenuItem
1684 \begin_layout Plain Layout
1686 \begin_inset space ~
1699 \begin_inset Flex CharStyle:MenuItem
1702 \begin_layout Plain Layout
1708 dialog to find a size that you like.
1709 When you've found a setting that seems to work nicely for you (tip: use
1711 \begin_inset Flex CharStyle:MenuItem
1714 \begin_layout Plain Layout
1724 button to keep the dialog open while you experiment), you can make this
1725 setting the default by using the
1726 \begin_inset Flex CharStyle:MenuItem
1729 \begin_layout Plain Layout
1742 \begin_layout Standard
1743 While it is often possible to find a suitable size for the text on the screen,
1744 this doesn't necessarily mean that the fonts are the best ones available
1746 In order to help you get the most out of your system, you can use the font
1747 definition commands to fine-tune the look of the text in greater detail
1751 \begin_layout Subsubsection
1752 Font definition commands
1755 \begin_layout Standard
1756 You can change LyX's screen fonts from within the
1757 \begin_inset Flex CharStyle:MenuItem
1760 \begin_layout Plain Layout
1767 The number of fonts that are available on different systems vary.
1771 \begin_layout Standard
1772 Before you go about scrapping a bitmap font because the larger sizes look
1774 \begin_inset Quotes eld
1778 \begin_inset Quotes erd
1781 , you should toggle the
1782 \begin_inset Flex CharStyle:Code
1785 \begin_layout Plain Layout
1792 This is only useful if you use bitmap fonts, because only these don't scale
1794 If you define this flag, LyX will only use the fixed font sizes that are
1795 available, and this guarantees that all bitmap fonts look good.
1796 However, the downside is that there will be a greater difference between
1797 the size of the fonts on screen and the size of fonts on paper because
1798 LyX will have to be satisfied with the closest available size, and not
1799 try to scale a size to fit.
1800 Also, you can risk that some logically different sizes, such as
1801 \begin_inset Flex CharStyle:MenuItem
1804 \begin_layout Plain Layout
1811 \begin_inset Flex CharStyle:MenuItem
1814 \begin_layout Plain Layout
1820 , will be mapped to the same screen font, making it hard for you to see
1821 the difference on screen.
1825 \begin_layout Standard
1826 One final note regarding the
1827 \begin_inset Flex CharStyle:Code
1830 \begin_layout Plain Layout
1836 flag: you should know that there is nothing wrong with using bitmap and
1837 scalable fonts at the same time for different purposes.
1838 For instance, it's common to use the scalable
1839 \begin_inset Quotes eld
1843 \begin_inset Quotes erd
1846 for the serif text together with a bitmap version of
1847 \begin_inset Quotes eld
1851 \begin_inset Quotes erd
1855 And you can safely select the
1856 \begin_inset Quotes eld
1860 \begin_inset Quotes erd
1863 button without worries: It will only apply to the Helvetica font.
1866 \begin_layout Standard
1867 Sometimes the artifacts introduced by use of the flag can be relieved by
1868 using the fine-detail screen font sizes which defines which point sizes
1869 the different logical font sizes correspond to.
1871 \begin_inset Flex CharStyle:Code
1874 \begin_layout Plain Layout
1880 to see exactly what concrete fonts the logical sizes map to, and try adjusting
1881 the corresponding entries in the
1882 \begin_inset Flex CharStyle:MenuItem
1885 \begin_layout Plain Layout
1891 dialog until you've managed to hit the nail and get the fonts you want.
1892 This can be hard to do, because LyX uses the DPI setting and the font zoom
1893 settings to calculate which exact screen font size to ask the X server
1894 for, thus obfuscating the mapping.
1895 If you can't make it by trial-and-error, you can make the process more
1896 transparent if you set both the DPI setting and font zoom settings to 100---eve
1897 n when this is known to be wrong.
1898 This will of course make your scalable fonts look weird, so use with care.
1901 \begin_layout Standard
1902 \begin_inset Branch OutDated
1905 \begin_layout Subsubsection
1909 \begin_layout Standard
1910 By default, LyX will use fonts meant to write Western European text, including
1911 all kinds of English.
1912 This is defined through the so-called
1921 If you want to use LyX to write for instance Eastern European text, Cyrillic
1922 or any other language not covered by the ISO-8859-1 font encoding, you
1923 can define a different one with the encoding setting.
1924 This requires you to have special fonts installed.
1926 \begin_inset Flex CharStyle:Code
1929 \begin_layout Plain Layout
1935 to see whether this is the case: check the
1936 \begin_inset Quotes eld
1940 \begin_inset Quotes erd
1944 \begin_inset Quotes eld
1948 \begin_inset Quotes erd
1951 fields for ISO-8859-X values different from ISO-8859-1, and search for
1952 one that contains the national characters of your language.
1953 If you find any, enter this encoding in the dialog.
1954 If not, go searching the Web for appropriate fonts.
1955 For the Qt frontend, it's recommended you use an iso646 font set.
1958 \begin_layout Standard
1959 When you've set LyX up to use a different font encoding, you should also
1960 consider changing the font used by dialog windows in LyX.
1962 \begin_inset Flex CharStyle:MenuItem
1965 \begin_layout Plain Layout
1967 \begin_inset space ~
1971 \begin_inset space ~
1979 dialog will not be understandable unless you tell LyX to use a different
1981 By default the menu font is set to
1982 \begin_inset Flex CharStyle:Code
1985 \begin_layout Plain Layout
1986 -*-helvetica-medium-r
1991 , but often Helvetica is not available in the font encoding you need, so
1992 the dialog allows this to be changed.
1995 \begin_layout Standard
1996 As you can see, there are quite a few options that can be used to fine tune
1997 the look of your fonts.
1998 This should not scare you from fiddling with the settings, because after
1999 all, you will hopefully be using LyX for many hours in the future.
2000 And contrary to real WYSIWYG word processors where you are tied to using
2001 fonts that have to look good both on paper and on screen, LyX gives you
2002 the possibility of using fonts that are designed to look good on the screen
2003 while using a different set of fonts to look good on paper.
2011 \begin_layout Subsection
2013 \begin_inset CommandInset label
2022 \begin_layout Standard
2023 The appearance of both the menu and toolbar may both be changed using the
2025 \begin_inset Flex CharStyle:MenuItem
2028 \begin_layout Plain Layout
2035 Simply select a different
2036 \begin_inset Flex CharStyle:Code
2039 \begin_layout Plain Layout
2046 \begin_inset Flex CharStyle:MenuItem
2049 \begin_layout Plain Layout
2050 Look & Feel\SpecialChar \menuseparator
2057 You can customize the interface by copying one of the
2058 \begin_inset Flex CharStyle:Code
2061 \begin_layout Plain Layout
2068 \begin_inset Flex CharStyle:Code
2071 \begin_layout Plain Layout
2078 \begin_inset Flex CharStyle:Code
2081 \begin_layout Plain Layout
2088 You may have to restart LyX for these changes to take effect.
2091 \begin_layout Standard
2093 \begin_inset Flex CharStyle:Code
2096 \begin_layout Plain Layout
2102 files is straightforward: have a look at
2103 \begin_inset Flex CharStyle:Code
2106 \begin_layout Plain Layout
2114 \begin_inset Flex CharStyle:Code
2117 \begin_layout Plain Layout
2124 \begin_inset Flex CharStyle:Code
2127 \begin_layout Plain Layout
2134 \begin_inset Flex CharStyle:Code
2137 \begin_layout Plain Layout
2143 entries must be ended with an explicit
2144 \begin_inset Flex CharStyle:Code
2147 \begin_layout Plain Layout
2155 \begin_inset Flex CharStyle:Code
2158 \begin_layout Plain Layout
2165 \begin_inset Flex CharStyle:Code
2168 \begin_layout Plain Layout
2175 \begin_inset Flex CharStyle:Code
2178 \begin_layout Plain Layout
2185 \begin_inset Flex CharStyle:Code
2188 \begin_layout Plain Layout
2195 \begin_inset Flex CharStyle:Code
2198 \begin_layout Plain Layout
2204 s and in the case of the
2205 \begin_inset Quotes eld
2209 \begin_inset Quotes erd
2213 \begin_inset Flex CharStyle:Code
2216 \begin_layout Plain Layout
2223 One small word of warning.
2225 \begin_inset Flex CharStyle:Code
2228 \begin_layout Plain Layout
2234 s may be inserted in a
2235 \begin_inset Flex CharStyle:Code
2238 \begin_layout Plain Layout
2245 \begin_inset Flex CharStyle:Code
2248 \begin_layout Plain Layout
2254 , but they are defined as
2255 \begin_inset Flex CharStyle:Code
2258 \begin_layout Plain Layout
2265 \begin_inset Flex CharStyle:Code
2268 \begin_layout Plain Layout
2276 \begin_inset Flex CharStyle:Code
2279 \begin_layout Plain Layout
2285 tag is used to insert context-dependent information that is generated by
2287 Unfortunately, the available tags are not documented outside the source
2291 \begin_layout Standard
2292 Note that, as of LyX 1.6, there are extensive context menus, normally accessed
2294 These are defined in the
2295 \begin_inset Flex CharStyle:Code
2298 \begin_layout Plain Layout
2307 \begin_layout Section
2311 \begin_layout Standard
2312 The settings in this section are used to customise the behavior of the LyX
2316 \begin_layout Subsection
2317 \begin_inset CommandInset label
2326 \begin_layout Standard
2327 Bindings are used to associate a LyX function to a key.
2328 Several prepackaged binding files are available: a CUA set of bindings
2329 (familiar as the typical set of PC and CDE set of keyboard shortcuts),
2330 an Emacs set of bindings, for those of us who follow the One True Way and
2331 refuse to lower our standards,
2335 \begin_layout Plain Layout
2336 I'm kidding here, of course!
2341 as well as specialty bindings (broadway and hollywood) and bindings for
2342 languages other than English.
2343 You can select your binding in the
2344 \begin_inset Flex CharStyle:MenuItem
2347 \begin_layout Plain Layout
2348 Editing\SpecialChar \menuseparator
2357 \begin_inset Flex CharStyle:MenuItem
2360 \begin_layout Plain Layout
2365 ools\SpecialChar \menuseparator
2381 \begin_layout Standard
2382 If, however, you'd like to customise the bindings to your own exacting tastes,
2383 then there are two ways to proceed.
2384 The first, and older method, is to copy a file from
2385 \begin_inset Flex CharStyle:Code
2388 \begin_layout Plain Layout
2395 \begin_inset Flex CharStyle:Code
2398 \begin_layout Plain Layout
2404 and modify that in a text editor.
2405 Don't forget to select this file in
2406 \begin_inset Flex CharStyle:MenuItem
2409 \begin_layout Plain Layout
2410 Editing\SpecialChar \menuseparator
2417 The second method is to use the shortcut editor, which you will also find
2419 \begin_inset Flex CharStyle:MenuItem
2422 \begin_layout Plain Layout
2423 Editing\SpecialChar \menuseparator
2430 The changes you make here will be stored at
2431 \begin_inset Flex CharStyle:Code
2434 \begin_layout Plain Layout
2435 UserDir/bind/user.bind
2443 \begin_layout Standard
2444 LyX supports internationalization of the user interface (see Chapter
2445 \begin_inset space ~
2449 \begin_inset CommandInset ref
2451 reference "chap:i18n"
2460 is set, LyX will try to use bindfiles by prepending the standard language
2462 For example, you can put a translated copy of some standard bind file in
2464 \begin_inset Flex CharStyle:Code
2467 \begin_layout Plain Layout
2473 directory, and LyX will use it automatically.
2476 \begin_layout Standard
2478 \begin_inset Flex CharStyle:Code
2481 \begin_layout Plain Layout
2487 files is straightforward:
2490 \begin_layout LyX-Code
2493 bind ``<key combination>'' ``<lyx-function>
2494 \begin_inset Quotes erd
2500 \begin_layout Standard
2501 Both key combination and lyx-function (including any arguments) must be
2502 enclosed in "double quotes".
2503 The LyX functions are partially documented on listed on the
2504 \begin_inset CommandInset href
2507 target "http://wiki.lyx.org/LyX/LyxFunctions"
2512 A major effort is presently underway to improve this documentation.
2515 \begin_layout Section
2516 \begin_inset CommandInset label
2518 name "sec:converters-etc"
2525 \begin_layout Standard
2526 LyX has a powerful mechanism to convert to and from any file format using
2531 \begin_layout Subsection
2532 \begin_inset CommandInset label
2541 \begin_layout Standard
2542 The first step is to define your file formats if they are not already defined.
2544 \begin_inset Flex CharStyle:MenuItem
2547 \begin_layout Plain Layout
2548 Tools\SpecialChar \menuseparator
2549 Preferences\SpecialChar \menuseparator
2550 File Handling\SpecialChar \menuseparator
2558 \begin_inset Flex CharStyle:MenuItem
2561 \begin_layout Plain Layout
2562 New\SpecialChar \ldots{}
2568 button to define your new format.
2570 \begin_inset Flex CharStyle:MenuItem
2573 \begin_layout Plain Layout
2579 field contains the named used to identify the format in the GUI.
2581 \begin_inset Flex CharStyle:MenuItem
2584 \begin_layout Plain Layout
2590 is used to identify the format interally.
2591 You will also need to enter a file extension.
2592 These are all required.
2594 \begin_inset Flex CharStyle:MenuItem
2597 \begin_layout Plain Layout
2603 field is used to provide a keyboard shortcut on the menus.
2604 (For example, pressing
2605 \begin_inset Flex CharStyle:MenuItem
2608 \begin_layout Plain Layout
2615 \begin_inset Flex CharStyle:MenuItem
2618 \begin_layout Plain Layout
2619 View\SpecialChar \menuseparator
2628 \begin_layout Standard
2630 \begin_inset Flex CharStyle:MenuItem
2633 \begin_layout Plain Layout
2640 \begin_inset Flex CharStyle:MenuItem
2643 \begin_layout Plain Layout
2650 For example, you might want to use
2651 \begin_inset Flex CharStyle:MenuItem
2654 \begin_layout Plain Layout
2660 to view PostScript files.
2661 You can enter the command needed to start the program in the corresponding
2663 In defining this command, you can use the four variables listed in the
2665 The viewer is launched when you view an image in LyX or use the
2666 \begin_inset Flex CharStyle:MenuItem
2669 \begin_layout Plain Layout
2676 The editor is for example launched when you press the
2677 \begin_inset Flex CharStyle:MenuItem
2680 \begin_layout Plain Layout
2687 \begin_inset Flex CharStyle:MenuItem
2690 \begin_layout Plain Layout
2697 \begin_inset Flex CharStyle:MenuItem
2700 \begin_layout Plain Layout
2709 \begin_layout Standard
2711 \begin_inset Flex CharStyle:MenuItem
2714 \begin_layout Plain Layout
2720 option tells LyX that a format is suitable for document export.
2721 If this is is set and if a suitable conversion route exists (see
2722 \begin_inset CommandInset ref
2724 reference "sub:Converters"
2728 ), the format will appear in the
2729 \begin_inset Flex CharStyle:MenuItem
2732 \begin_layout Plain Layout
2733 File\SpecialChar \menuseparator
2740 The format will also appear in the
2741 \begin_inset Flex CharStyle:MenuItem
2744 \begin_layout Plain Layout
2750 menu if a viewer is specified for the format.
2751 Pure image formats, such as
2752 \begin_inset Flex CharStyle:Code
2755 \begin_layout Plain Layout
2761 , should not use this option.
2762 Formats that can both represent vector graphics and documents like
2763 \begin_inset Flex CharStyle:Code
2766 \begin_layout Plain Layout
2775 \begin_layout Standard
2777 \begin_inset Flex CharStyle:MenuItem
2780 \begin_layout Plain Layout
2781 Vector graphics format
2786 tells LyX that a format can contain vector graphics.
2787 This information is used to determine the target format of included graphics
2789 \begin_inset Flex CharStyle:MenuItem
2792 \begin_layout Plain Layout
2799 Included graphics may need to be converted to either
2800 \begin_inset Flex CharStyle:MenuItem
2803 \begin_layout Plain Layout
2810 \begin_inset Flex CharStyle:MenuItem
2813 \begin_layout Plain Layout
2820 \begin_inset Flex CharStyle:MenuItem
2823 \begin_layout Plain Layout
2830 \begin_inset Flex CharStyle:MenuItem
2833 \begin_layout Plain Layout
2839 cannot handle other image formats.
2840 If an included graphic is not already in
2841 \begin_inset Flex CharStyle:MenuItem
2844 \begin_layout Plain Layout
2851 \begin_inset Flex CharStyle:MenuItem
2854 \begin_layout Plain Layout
2861 \begin_inset Flex CharStyle:MenuItem
2864 \begin_layout Plain Layout
2870 format, it is converted to
2871 \begin_inset Flex CharStyle:MenuItem
2874 \begin_layout Plain Layout
2880 if the vector format option is set, and otherwise to
2881 \begin_inset Flex CharStyle:MenuItem
2884 \begin_layout Plain Layout
2893 \begin_layout Subsection
2897 \begin_layout Standard
2898 Since all conversions from one format to another take place in LyX's temporary
2899 directory, it is sometimes necessary to modify a file before copying it
2900 to the temporary directory in order that the conversion may be performed.
2904 \begin_layout Plain Layout
2905 For example, the file may refer to other files---images, for example---using
2906 relative filenames, and these may become invalid when the file is copied
2907 to the temporary directory.
2912 This is done by a Copier: It copies a file to (or from) the temporary directory
2913 and may modify it in the process.
2916 \begin_layout Standard
2917 The definitions of the copiers may use four variables:
2921 \labelwidthstring 00.00.0000
2922 \begin_inset Flex CharStyle:Code
2925 \begin_layout Plain Layout
2931 The LyX system directory (e.
2932 \begin_inset space \thinspace{}
2936 \begin_inset space ~
2940 \begin_inset Flex CharStyle:MenuItem
2943 \begin_layout Plain Layout
2953 \labelwidthstring 00.00.0000
2954 \begin_inset Flex CharStyle:Code
2957 \begin_layout Plain Layout
2967 \labelwidthstring 00.00.0000
2968 \begin_inset Flex CharStyle:Code
2971 \begin_layout Plain Layout
2981 \labelwidthstring 00.00.0000
2982 \begin_inset Flex CharStyle:Code
2985 \begin_layout Plain Layout
2994 \begin_layout Standard
2995 The latter is to be given in a form suitable for inclusion in a LaTeX's
3002 command and is relevant only when exporting files suitable for such inclusion.
3005 \begin_layout Standard
3006 Copiers can be used to do almost anything with output files.
3007 For example, suppose you want generated pdf files to be copied to a special
3009 \begin_inset Flex CharStyle:Code
3012 \begin_layout Plain Layout
3019 Then you could write a shell script such as this one:
3022 \begin_layout Standard
3023 \begin_inset listings
3027 \begin_layout Plain Layout
3031 \begin_layout Plain Layout
3035 \begin_layout Plain Layout
3036 TOFILE=`basename $2`
3039 \begin_layout Plain Layout
3040 cp $FROMFILE /home/you/pdf/$TOFILE
3045 Save that in your local LyX directory---say,
3046 \begin_inset Flex CharStyle:Code
3049 \begin_layout Plain Layout
3050 /home/you/.lyx/scripts/pdfcopier.sh
3055 ---and make it executable, if you need to do so on your platform.
3057 \begin_inset Flex CharStyle:MenuItem
3060 \begin_layout Plain Layout
3061 Tools\SpecialChar \menuseparator
3068 \begin_inset Flex CharStyle:MenuItem
3071 \begin_layout Plain Layout
3077 format---or one of the other pdf formats---and enter
3078 \begin_inset Flex CharStyle:Code
3081 \begin_layout Plain Layout
3082 pdfcopier.sh $$i $$o
3088 \begin_inset Flex CharStyle:MenuItem
3091 \begin_layout Plain Layout
3101 \begin_layout Standard
3102 Copiers are used by LyX in various of its own conversions.
3103 For example, if appropriate programs are found, LyX will automatically
3104 install copiers for the
3105 \begin_inset Flex CharStyle:MenuItem
3108 \begin_layout Plain Layout
3115 \begin_inset Flex CharStyle:MenuItem
3118 \begin_layout Plain Layout
3120 \begin_inset space ~
3129 When these formats are exported, the copier sees that not just the main
3130 HTML file but various associated files (style files, images, etc.) are also
3132 All these files are written to a subdirectory of the directory in which
3133 the original LyX file was found.
3137 \begin_layout Plain Layout
3138 This copier can be customized.
3140 \begin_inset Quotes eld
3144 \begin_inset Quotes erd
3147 argument takes a comma-separated list of extensions to be copied; if it
3148 is omitted, all files will be copied.
3150 \begin_inset Quotes eld
3154 \begin_inset Quotes erd
3157 argument determines the extension added to the generated directory.
3159 \begin_inset Quotes eld
3163 \begin_inset Flex CharStyle:MenuItem
3166 \begin_layout Plain Layout
3173 \begin_inset Quotes erd
3176 , so HTML generated from
3177 \begin_inset Flex CharStyle:MenuItem
3180 \begin_layout Plain Layout
3181 /path/to/filename.lyx
3187 \begin_inset Flex CharStyle:MenuItem
3190 \begin_layout Plain Layout
3191 /path/to/filename.html.LyXconv
3205 \begin_layout Subsection
3206 \begin_inset CommandInset label
3208 name "sub:Converters"
3215 \begin_layout Standard
3216 You can define your own Converters to, uhh, convert files between different
3219 \begin_inset Flex CharStyle:MenuItem
3222 \begin_layout Plain Layout
3223 Tools\SpecialChar \menuseparator
3224 Preferences\SpecialChar \menuseparator
3225 File Handling\SpecialChar \menuseparator
3234 \begin_layout Standard
3235 To define a new converter, select the
3236 \begin_inset Flex CharStyle:MenuItem
3239 \begin_layout Plain Layout
3241 \begin_inset space ~
3250 \begin_inset space \thinspace{}
3254 \begin_inset Flex CharStyle:MenuItem
3257 \begin_layout Plain Layout
3259 \begin_inset space ~
3267 from the drop-down lists, enter the command needed for the conversion,
3269 \begin_inset Flex CharStyle:MenuItem
3272 \begin_layout Plain Layout
3279 Several variables can be used in the definition of converters:
3283 \labelwidthstring 00.00.0000
3284 \begin_inset Flex CharStyle:Code
3287 \begin_layout Plain Layout
3293 The LyX system directory
3297 \labelwidthstring 00.00.0000
3298 \begin_inset Flex CharStyle:Code
3301 \begin_layout Plain Layout
3311 \labelwidthstring 00.00.0000
3312 \begin_inset Flex CharStyle:Code
3315 \begin_layout Plain Layout
3325 \labelwidthstring 00.00.0000
3326 \begin_inset Flex CharStyle:Code
3329 \begin_layout Plain Layout
3335 The base filename of the input file (i.e., without the extension)
3339 \labelwidthstring 00.00.0000
3340 \begin_inset Flex CharStyle:Code
3343 \begin_layout Plain Layout
3349 The path to the input file
3352 \begin_layout Standard
3354 \begin_inset Flex CharStyle:MenuItem
3357 \begin_layout Plain Layout
3359 \begin_inset space ~
3367 field you can enter the following flags, separated by commas:
3371 \labelwidthstring 00.00.0000
3372 \begin_inset Flex CharStyle:Code
3375 \begin_layout Plain Layout
3381 This converter runs some form of LaTeX.
3382 This will make LyX's LaTeX error logs available.
3386 \labelwidthstring 00.00.0000
3387 \begin_inset Flex CharStyle:Code
3390 \begin_layout Plain Layout
3397 \begin_inset Flex CharStyle:MenuItem
3400 \begin_layout Plain Layout
3406 file for the conversion.
3410 \labelwidthstring 00.00.0000
3411 \begin_inset Flex CharStyle:Code
3414 \begin_layout Plain Layout
3423 \begin_layout Standard
3424 The following three flags are not really flags at all because they take
3426 \begin_inset Flex CharStyle:MenuItem
3429 \begin_layout Plain Layout
3431 \begin_inset space ~
3435 \begin_inset space ~
3447 \labelwidthstring 00.00.0000
3448 \begin_inset Flex CharStyle:Code
3451 \begin_layout Plain Layout
3457 If set, the converter's standard error will be redirected to a file
3458 \begin_inset Flex CharStyle:Code
3461 \begin_layout Plain Layout
3467 , and the script given as argument will be run as:
3468 \begin_inset Flex CharStyle:Code
3471 \begin_layout Plain Layout
3472 script <infile.out >infile.log
3478 The argument may contain
3479 \begin_inset Flex CharStyle:Code
3482 \begin_layout Plain Layout
3492 \labelwidthstring 00.00.0000
3493 \begin_inset Flex CharStyle:Code
3496 \begin_layout Plain Layout
3502 The name of the directory in which the converter will dump the generated
3504 LyX will not create this directory, and it does not copy anything into
3505 it, though it will copy this directory to the destination.
3506 The argument may contain
3507 \begin_inset Flex CharStyle:Code
3510 \begin_layout Plain Layout
3516 , which will be replaced by the basename of the input and output files,
3517 respectively, when the directory is copied.
3518 \begin_inset Newline newline
3521 Note that resultdir and usetempdir make no sense together.
3522 The latter will be ignored if the former is given.
3526 \labelwidthstring 00.00.0000
3527 \begin_inset Flex CharStyle:Code
3530 \begin_layout Plain Layout
3536 Determines the output filename and may, contain
3537 \begin_inset Flex CharStyle:Code
3540 \begin_layout Plain Layout
3547 Sensible only with resultdir and optional even then; if not given, it defaults
3551 \begin_layout Standard
3552 None of these last three are presently used in any of the converters that
3553 are installed with LyX.
3557 \begin_layout Standard
3558 You do not have to define converters between all the formats between which
3559 you want to convert.
3560 For example, you will note that there is no `LyX to PostScript®' converter,
3561 but LyX will export PostScript®.
3562 It does so by first creating a LaTeX file (no converter needs to be defined
3563 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
3564 and finally converting the resulting DVI file to PostScript®.
3565 LyX finds such `chains' of converters automatically, and it will always
3566 choose the shortest possible chain.
3567 You can, though, still define multiple conversion methods between file
3569 For example, the standard LyX configuration provides three ways to convert
3570 LaTeX to PDF: Directly, using
3571 \begin_inset Flex CharStyle:MenuItem
3574 \begin_layout Plain Layout
3580 ; via (DVI and) PostScript®, using
3581 \begin_inset Flex CharStyle:MenuItem
3584 \begin_layout Plain Layout
3591 \begin_inset Flex CharStyle:MenuItem
3594 \begin_layout Plain Layout
3601 To define such alternate chains, you must define multiple target `file
3602 formats', as described in section
3603 \begin_inset CommandInset ref
3605 reference "sub:Formats"
3610 For example, in the standard configuration, the formats named
3611 \begin_inset Flex CharStyle:MenuItem
3614 \begin_layout Plain Layout
3621 \begin_inset Flex CharStyle:MenuItem
3624 \begin_layout Plain Layout
3631 \begin_inset Flex CharStyle:MenuItem
3634 \begin_layout Plain Layout
3640 are defined, all of which share the extension
3641 \begin_inset Flex CharStyle:MenuItem
3644 \begin_layout Plain Layout
3650 , and which correspond to the conversion methods just mentioned.
3653 \begin_layout Section
3657 \begin_layout Standard
3658 The settings in this section affect the output LyX produces.
3661 \begin_layout Subsection
3662 Plain text export options
3665 \begin_layout Standard
3667 There are a couple of commands that can be used to
3668 \begin_inset Quotes eld
3672 \begin_inset Quotes erd
3675 exported plain text files.
3676 Note that LyX automatically detects and tries to use the best settings
3677 for your system at installation time, but you can modify them in the
3678 \begin_inset Flex CharStyle:MenuItem
3681 \begin_layout Plain Layout
3682 Output\SpecialChar \menuseparator
3688 dialog if you disagree with its interpretation.
3691 \begin_layout Description
3692 \begin_inset Flex CharStyle:Code
3695 \begin_layout Plain Layout
3701 This option defines the command used to produce better plain text tables
3703 \begin_inset Flex CharStyle:Code
3706 \begin_layout Plain Layout
3712 UNIX-commands (refer to their manpages for more information about them).
3713 Setting this as empty tells LyX to use the internal (inferior) formatter.
3716 \begin_layout Description
3717 \begin_inset Flex CharStyle:Code
3720 \begin_layout Plain Layout
3726 With this command you can set the default line length of the plain text
3728 Setting it to 0 means that no line breaks will be inserted except between
3729 paragraphs and the like.
3732 \begin_layout Section
3736 \begin_layout Standard
3737 There are many other configuration options that can be used to customize
3739 Most of them are sufficiently self-explanatory that we have not felt it
3740 necessary to document them here.
3742 \begin_inset CommandInset href
3744 name "mailing lists"
3745 target "http://www.lyx.org/mailing.php"
3749 if you need some more information.
3752 \begin_layout Chapter
3753 Internationalizing LyX
3754 \begin_inset CommandInset label
3763 \begin_layout Standard
3764 LyX supports using a translated interface.
3765 Last time we checked, LyX provided text in thirty languages.
3766 The language of choice is called your
3771 (For further reading on locale settings, see also the documentation for
3772 locale that comes with your operating system.
3773 For Linux, the manual page for
3774 \begin_inset Flex CharStyle:Code
3777 \begin_layout Plain Layout
3783 could be a good place to start).
3786 \begin_layout Standard
3787 Notice that these translations will work, but do contain a few flaws.
3788 In particular, all dialogs have been designed with the English text in
3789 mind, which means that some of the translated text will be too large to
3790 fit within the space allocated.
3791 This is only a display problem and will not cause any harm.
3792 Also, you will find that some of the translations do not define shortcut
3793 keys for everything.
3794 Sometimes, there are simply not enough free letters to do it.
3795 Other times, the translator just hasn't got around to doing it yet.
3796 Our localization team, which you may wish to join,
3800 \begin_layout Plain Layout
3801 If you are a fluent speaker of a language other than English, joining these
3802 teams is a great way to give back to the LyX community!
3807 will of course try to fix these shortcomings in future versions of LyX.
3810 \begin_layout Section
3814 \begin_layout Subsection
3815 Translating the graphical user interface (text messages).
3818 \begin_layout Standard
3820 \begin_inset Flex CharStyle:Code
3823 \begin_layout Plain Layout
3829 library to handle the internationalization of the interface.
3830 To have LyX speak your favorite language in all menus and dialogs, you
3832 \begin_inset Flex CharStyle:Code
3835 \begin_layout Plain Layout
3841 -file for that language.
3842 When this is available, you'll have to generate a
3843 \begin_inset Flex CharStyle:Code
3846 \begin_layout Plain Layout
3852 -file from it and install the
3853 \begin_inset Flex CharStyle:Code
3856 \begin_layout Plain Layout
3863 The process of doing all of this is explained in the documentation for
3865 \begin_inset Flex CharStyle:Code
3868 \begin_layout Plain Layout
3875 It is possible to do this just for yourself, but if you're going to do
3876 it, you might as well share the results of your labors with the rest of
3878 Send a message to the LyX developers' list for more information about how
3882 \begin_layout Standard
3883 In short, this is what you should do (xx denotes the language code):
3886 \begin_layout Itemize
3887 Check out the LyX source code.
3889 \begin_inset CommandInset href
3891 name "information on the web"
3892 target "http://www.lyx.org/devel/cvs.php"
3899 \begin_layout Itemize
3901 \begin_inset Flex CharStyle:Code
3904 \begin_layout Plain Layout
3915 \begin_inset Flex CharStyle:Code
3918 \begin_layout Plain Layout
3925 \begin_inset Flex CharStyle:Code
3928 \begin_layout Plain Layout
3934 doesn't exist, it can be remade with
3935 \begin_inset Flex CharStyle:Code
3938 \begin_layout Plain Layout
3944 in that directory, or you can use an existing po-file for some other language
3948 \begin_layout Itemize
3950 \begin_inset Flex CharStyle:Code
3953 \begin_layout Plain Layout
3963 \begin_layout Plain Layout
3964 This is just a text file, so it can be edited in any text editor.
3965 But there are also specialized programs that support such editing, such
3966 as KBabel (for KDE).
3967 Emacs contains a `mode' for editing
3968 \begin_inset Flex CharStyle:Code
3971 \begin_layout Plain Layout
3982 For some menu- and widget-labels, there are also shortcut keys that should
3984 Those keys are marked after a `|', and should be translated according to
3985 the words and phrases of the language.
3986 You should also fill also out the information at the beginning of the new
3988 \begin_inset Flex CharStyle:Code
3991 \begin_layout Plain Layout
3997 -file with your email-address, etc., so people know where to reach you with
3998 suggestions and entertaining flames.
4001 \begin_layout Standard
4002 If you are just doing this on your own, then:
4005 \begin_layout Itemize
4007 \begin_inset Flex CharStyle:Code
4010 \begin_layout Plain Layout
4017 This can be done with
4018 \begin_inset Flex CharStyle:Code
4021 \begin_layout Plain Layout
4022 msgfmt -o xx.mo < xx.po
4030 \begin_layout Itemize
4032 \begin_inset Flex CharStyle:Code
4035 \begin_layout Plain Layout
4041 -file to your locale-tree, at the correct directory for application messages
4046 xx, and under the name
4047 \begin_inset Flex CharStyle:Code
4050 \begin_layout Plain Layout
4058 \begin_inset Flex CharStyle:Code
4061 \begin_layout Plain Layout
4062 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
4072 \begin_layout Standard
4073 As said, however, it would be best if the new
4074 \begin_inset Flex CharStyle:Code
4077 \begin_layout Plain Layout
4083 -file could be added to the LyX distribution, so others can use it.
4084 Adding it involves making additional changes to LyX.
4085 So send an email to the developers' mailing list if you're interested in
4089 \begin_layout Subsubsection
4093 \begin_layout Standard
4094 Sometimes it turns out that one English message needs to be translated into
4095 different messages in the target language.
4096 One example is the message
4097 \begin_inset Flex CharStyle:Code
4100 \begin_layout Plain Layout
4106 which has the German translation
4114 , depending upon exactly what the English
4115 \begin_inset Quotes eld
4119 \begin_inset Quotes erd
4124 \begin_inset Flex CharStyle:Code
4127 \begin_layout Plain Layout
4133 does not handle such ambigous translations.
4134 Therefore you have to add some context information to the message: Instead
4136 \begin_inset Flex CharStyle:Code
4139 \begin_layout Plain Layout
4146 \begin_inset Flex CharStyle:Code
4149 \begin_layout Plain Layout
4150 To[[as in 'From format x to format y']]
4156 \begin_inset Flex CharStyle:Code
4159 \begin_layout Plain Layout
4160 To[[as in 'From page x to page y']].
4165 Now the two occurences of
4166 \begin_inset Flex CharStyle:Code
4169 \begin_layout Plain Layout
4176 \begin_inset Flex CharStyle:Code
4179 \begin_layout Plain Layout
4185 and can be translated correctly to
4196 \begin_layout Standard
4197 Of course the context information needs to be stripped off the original
4198 message when no translation is used.
4199 Therefore you have to put it in double square brackets at the end of the
4200 message (see the example above).
4201 The translation mechanism of LyX ensures that everything in double square
4202 brackets at the end of messages is removed before displaying the message.
4205 \begin_layout Subsection
4206 Translating the documentation.
4209 \begin_layout Standard
4210 The online documentation (in the
4211 \begin_inset Flex CharStyle:MenuItem
4214 \begin_layout Plain Layout
4224 -menu) can (and should!) be translated.
4225 If there are translated versions of the documentation available
4229 \begin_layout Plain Layout
4230 As of March 2008, at least some of the documents have been translated into
4231 fourteen languages, with the Tutorial available in a few more.
4236 and the locale is set accordingly, these will be used automagically by
4238 LyX looks for translated versions as
4239 \begin_inset Flex CharStyle:Code
4242 \begin_layout Plain Layout
4243 LyXDir/doc/xx_DocName.lyx
4249 \begin_inset Flex CharStyle:Code
4252 \begin_layout Plain Layout
4258 is the code for the language currently in use.
4259 If there are no translated documents, the default English versions will
4261 Note that the translated versions must have the same filenames (
4262 \begin_inset Flex CharStyle:Code
4265 \begin_layout Plain Layout
4271 above) as the original.
4272 If you feel up to translating the documentation (an excellent way to proof-read
4273 the original documentation by the way!), there are a few things you should
4277 \begin_layout Itemize
4279 \begin_inset Flex CharStyle:Code
4282 \begin_layout Plain Layout
4288 , the guide to writing LyX documentation.
4289 Pay special attention to the translator's section.
4292 \begin_layout Itemize
4293 Check out the documentation translation web page at
4294 \begin_inset CommandInset href
4296 name "http://www.devel.lyx.org"
4297 target "http://www.devel.lyx.org"
4302 That way, you can find out which (if any) documents have already been translate
4303 d into your language.
4304 You can also find out who (if anyone) is organizing the effort to translate
4305 the documentation into your language.
4306 If no one is organizing the effort, please let us know that you're interested.
4309 \begin_layout Standard
4310 Once you get to actually translating, here's a few hints for you that may
4314 \begin_layout Itemize
4315 Join the documentation team! There is information on how to do that in
4316 \begin_inset Flex CharStyle:Code
4319 \begin_layout Plain Layout
4326 \begin_inset Flex CharStyle:MenuItem
4329 \begin_layout Plain Layout
4334 elp\SpecialChar \menuseparator
4344 ), which by the way is the first document you should translate.
4347 \begin_layout Itemize
4348 Learn the typographic conventions for the language you are translating to.
4349 Typography is an ancient art and over the centuries, a great variety of
4350 conventions have developed throughout different parts of the world.
4351 Also study the professional terminology amongst typographers in your country.
4352 Inventing your own terminology will only confuse the users.
4355 (Warning! Typography is addictive!)
4358 \begin_layout Itemize
4359 Make a copy of the document.
4360 This will be your working copy.
4361 You can use this as your personal translated help-file by placing it in
4363 \begin_inset Flex CharStyle:Code
4366 \begin_layout Plain Layout
4375 \begin_layout Itemize
4376 Sometimes the original document (from the LyX-team) will be updated.
4377 Use the source viewer at
4378 \begin_inset CommandInset href
4380 name "http://www.lyx.org/trac/timeline"
4381 target "http://www.lyx.org/trac/timeline"
4385 to see what has been changed.
4386 That way you can easily see which parts of the translated document need
4390 \begin_layout Standard
4391 If you ever find an error in the original document, fix it and notify the
4392 rest of the documentation team of the changes! (You didn't forget to join
4393 the documentation team, did you?)
4396 \begin_layout Standard
4397 \begin_inset Branch OutDated
4400 \begin_layout Section
4401 International Keyboard Support
4404 \begin_layout Standard
4407 [Editor's Note: The following section is by
4415 It needs to be fixed to conform to the new Documentation Style sheet and
4416 to make use of the new v1.0 features.
4417 The whole thing also needs to be merged with the section following it.-jw
4418 It may also be badly out of date.-rh (2008)]
4421 \begin_layout Subsection
4422 Defining Own Keymaps: Keymap File Format
4425 \begin_layout Standard
4426 Let's look at a keyboard definition file a little closer.
4427 It is a plain text file defining
4430 \begin_layout Itemize
4431 key-to-key or key-to-string translations
4434 \begin_layout Itemize
4438 \begin_layout Itemize
4439 dead keys exceptions
4442 \begin_layout Standard
4443 To define key-to-key or key-to-string translation, use this command:
4446 \begin_layout Quotation
4447 \begin_inset Flex CharStyle:Code
4450 \begin_layout Plain Layout
4459 \begin_inset Flex CharStyle:Code
4462 \begin_layout Plain Layout
4471 \begin_layout Standard
4473 \begin_inset Flex CharStyle:Code
4476 \begin_layout Plain Layout
4482 is the key to be translated and
4483 \begin_inset Flex CharStyle:Code
4486 \begin_layout Plain Layout
4492 is the string to be inserted into the document.
4493 To define dead keys, use:
4496 \begin_layout Quotation
4497 \begin_inset Flex CharStyle:Code
4500 \begin_layout Plain Layout
4509 \begin_inset Flex CharStyle:Code
4512 \begin_layout Plain Layout
4521 \begin_layout Standard
4523 \begin_inset Flex CharStyle:Code
4526 \begin_layout Plain Layout
4532 is a keyboard key and
4533 \begin_inset Flex CharStyle:Code
4536 \begin_layout Plain Layout
4543 The following dead keys are supported (shortcut name is in parentheses):
4546 \begin_layout Quotation
4550 \begin_inset space \hfill{}
4556 \begin_layout Quotation
4558 \begin_inset space \hfill{}
4564 \begin_layout Quotation
4566 \begin_inset space \hfill{}
4572 \begin_layout Quotation
4574 \begin_inset space \hfill{}
4580 \begin_layout Quotation
4582 \begin_inset space \hfill{}
4588 \begin_layout Quotation
4590 \begin_inset space \hfill{}
4597 \begin_layout Plain Layout
4609 \begin_layout Quotation
4611 \begin_inset space \hfill{}
4617 \begin_layout Quotation
4619 \begin_inset space \hfill{}
4626 \begin_layout Plain Layout
4638 \begin_layout Quotation
4640 \begin_inset space \hfill{}
4646 \begin_layout Quotation
4648 \begin_inset space \hfill{}
4654 \begin_layout Quotation
4656 \begin_inset space \hfill{}
4663 \begin_layout Plain Layout
4675 \begin_layout Quotation
4677 \begin_inset space \hfill{}
4684 \begin_layout Plain Layout
4696 \begin_layout Quotation
4698 \begin_inset space \hfill{}
4704 \begin_layout Quotation
4705 hungarian umlaut (hug)
4706 \begin_inset space \hfill{}
4712 \begin_layout Quotation
4714 \begin_inset space \hfill{}
4720 \begin_layout Quotation
4722 \begin_inset space \hfill{}
4729 \begin_layout Plain Layout
4741 \begin_layout Standard
4742 Since in many international keyboards there are exceptions to what some
4743 dead keys should do, you can define them using
4746 \begin_layout Quotation
4747 \begin_inset Flex CharStyle:Code
4750 \begin_layout Plain Layout
4758 deadkey key outstring
4761 \begin_layout Standard
4762 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
4766 \begin_layout Quotation
4767 \begin_inset Flex CharStyle:Code
4770 \begin_layout Plain Layout
4783 \begin_layout Standard
4784 to make it work correctly.
4785 Also, you have to define as exceptions dead keys over i and j, to remove
4786 the dot from them before inserting an accent mark.
4787 I will change this when the time comes, but so far I haven't had time.
4790 \begin_layout Standard
4791 Oh, and about characters: backslash is escaped, so to enter it, you'll need
4794 \begin_inset Flex CharStyle:Code
4797 \begin_layout Plain Layout
4803 have different meaning.
4805 \begin_inset Flex CharStyle:Code
4808 \begin_layout Plain Layout
4814 marks comments, quotes start and end LaTeX-style commands.
4815 To enter quote, you'll need to use
4816 \begin_inset Flex CharStyle:Code
4819 \begin_layout Plain Layout
4828 \begin_inset Flex CharStyle:Code
4831 \begin_layout Plain Layout
4838 \begin_inset Flex CharStyle:Code
4841 \begin_layout Plain Layout
4852 \begin_layout Standard
4853 If you make a keyboard description file that works for your language, please
4854 mail it to me, so I can include it in the next keymap distribution.
4857 \begin_layout Standard
4858 More keywords will be supported in keymap configuration file in future,
4862 \begin_layout Itemize
4863 \begin_inset Flex CharStyle:Code
4866 \begin_layout Plain Layout
4877 \begin_inset space \hfill{}
4881 \begin_inset Flex CharStyle:Code
4884 \begin_layout Plain Layout
4893 \begin_layout Itemize
4894 \begin_inset Flex CharStyle:Code
4897 \begin_layout Plain Layout
4908 \begin_inset space \hfill{}
4912 \begin_inset Flex CharStyle:Code
4915 \begin_layout Plain Layout
4921 an external keymap translation program
4924 \begin_layout Standard
4925 Also, it should look into
4926 \begin_inset Flex CharStyle:Code
4929 \begin_layout Plain Layout
4935 file for defaults, too (for example, a
4936 \begin_inset Flex CharStyle:Code
4939 \begin_layout Plain Layout
4947 option to include default keyboard).
4955 \begin_layout Section
4956 \begin_inset CommandInset label
4962 International Keymap Stuff
4965 \begin_layout Standard
4966 \begin_inset Note Note
4969 \begin_layout Plain Layout
4970 In doing the revisions on this document in March 2008, I did not look over
4971 this stuff, as I do not understand it.
4972 It would be good if someone else could do so.
4980 \begin_layout Standard
4981 The next two sections describe the
4982 \begin_inset Flex CharStyle:Code
4985 \begin_layout Plain Layout
4994 \begin_inset Flex CharStyle:Code
4997 \begin_layout Plain Layout
5005 file syntax in detail.
5006 These sections should help you design your own key map if the ones provided
5007 do not meet your needs.
5010 \begin_layout Subsection
5014 \begin_layout Standard
5018 \begin_inset Flex CharStyle:Code
5021 \begin_layout Plain Layout
5027 file maps keystrokes to characters or strings.
5028 As the name suggests, it sets a keyboard mapping.
5030 \begin_inset Flex CharStyle:Code
5033 \begin_layout Plain Layout
5044 \begin_inset Flex CharStyle:Code
5047 \begin_layout Plain Layout
5062 \begin_inset Flex CharStyle:Code
5065 \begin_layout Plain Layout
5078 \begin_inset Flex CharStyle:Code
5081 \begin_layout Plain Layout
5090 \begin_inset Flex CharStyle:Code
5093 \begin_layout Plain Layout
5101 are described in this section.
5105 \labelwidthstring 00.00.0000
5106 \begin_inset Flex CharStyle:Code
5109 \begin_layout Plain Layout
5117 Map a character to a string
5120 \begin_layout LyX-Code
5135 \begin_layout Standard
5168 the double-quote (")
5185 must be escaped with a preceding backslash (
5196 \begin_layout Standard
5198 \begin_inset Flex CharStyle:MenuItem
5201 \begin_layout Plain Layout
5209 statement to cause the symbol
5210 \begin_inset Flex CharStyle:MenuItem
5213 \begin_layout Plain Layout
5221 to be output for the keystroke
5222 \begin_inset Flex CharStyle:MenuItem
5225 \begin_layout Plain Layout
5236 \begin_layout LyX-Code
5243 \labelwidthstring 00.00.0000
5244 \begin_inset Flex CharStyle:Code
5247 \begin_layout Plain Layout
5255 Specify an accent character
5258 \begin_layout LyX-Code
5267 \begin_layout Standard
5268 This will make the cha
5306 This is the dead key
5310 \begin_layout Plain Layout
5317 refers to a key that does not produce a character by itself, but when followed
5318 with another key, produces the desired accent character.
5319 For example, a German characte
5321 r with an umlaut like
5331 can be produced in this manner.
5340 \begin_layout Standard
5353 and then another key not in
5370 followed by the other, unallowed key, as output.
5374 \begin_inset Flex CharStyle:MenuItem
5377 \begin_layout Plain Layout
5385 cancels a dead key, so if
5396 \begin_inset Flex CharStyle:MenuItem
5399 \begin_layout Plain Layout
5408 , the cursor will not go one position backwards but will instead cancel
5424 might have had on the next keystroke.
5428 \begin_layout Standard
5429 The following example specifies that the character ' is to be an acute accent,
5430 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
5433 \begin_layout LyX-Code
5436 kmod ' acute aeiouAEIOU
5440 \labelwidthstring 00.00.0000
5441 \begin_inset Flex CharStyle:Code
5444 \begin_layout Plain Layout
5450 Specify an exception to the accent character
5453 \begin_layout LyX-Code
5462 \begin_layout Standard
5463 This defines an exce
5504 have been assigned a keystroke with a previous
5507 \begin_inset Flex CharStyle:Code
5510 \begin_layout Plain Layout
5534 must not belong in the
5586 If such a declaration does not exist in
5594 \begin_inset Flex CharStyle:Code
5597 \begin_layout Plain Layout
5637 \begin_inset Flex CharStyle:Code
5640 \begin_layout Plain Layout
5654 \begin_layout Standard
5655 The following command produces causes äi to be produced when you enter acute-i
5659 \begin_layout LyX-Code
5674 \labelwidthstring 00.00.0000
5675 \begin_inset Flex CharStyle:Code
5678 \begin_layout Plain Layout
5684 Combine two accent characters
5687 \begin_layout LyX-Code
5693 accent1 accent2 allowed
5696 \begin_layout Standard
5697 This one is getting pretty esoteric.
5698 It allows you to combine the effect
5754 \begin_inset Flex CharStyle:Code
5757 \begin_layout Plain Layout
5785 \begin_layout Standard
5786 Consider this example from the
5787 \begin_inset Flex CharStyle:Code
5790 \begin_layout Plain Layout
5801 \begin_layout LyX-Code
5804 kmod ; acute aeioyvhAEIOYVH
5808 kcomb acute umlaut iyIY
5811 \begin_layout Standard
5812 This allows you to press
5813 \begin_inset Flex CharStyle:MenuItem
5816 \begin_layout Plain Layout
5824 and get the effect of
5825 \begin_inset Flex CharStyle:Code
5828 \begin_layout Plain Layout
5847 in this case cancels the last dead key, so if you press
5848 \begin_inset Flex CharStyle:MenuItem
5851 \begin_layout Plain Layout
5860 \begin_inset Flex CharStyle:Code
5863 \begin_layout Plain Layout
5876 \begin_layout Subsection
5880 \begin_layout Standard
5882 \begin_inset Flex CharStyle:Code
5885 \begin_layout Plain Layout
5893 mapping is performed, a
5894 \begin_inset Flex CharStyle:Code
5897 \begin_layout Plain Layout
5907 file maps the strings that the symbols generate to characters in the current
5909 The LyX distribution currently includes at least the
5910 \begin_inset Flex CharStyle:Code
5913 \begin_layout Plain Layout
5922 \begin_inset Flex CharStyle:Code
5925 \begin_layout Plain Layout
5936 \begin_layout Standard
5938 \begin_inset Flex CharStyle:Code
5941 \begin_layout Plain Layout
5949 file is a sequence of declarations of the form
5952 \begin_layout LyX-Code
5965 \begin_layout Standard
5966 For example, in order to map
5967 \begin_inset Flex CharStyle:MenuItem
5970 \begin_layout Plain Layout
5980 to the corresponding character in the iso-8859-1 set (233), the following
5984 \begin_layout LyX-Code
5992 \begin_layout Standard
5994 \begin_inset Flex CharStyle:Code
5997 \begin_layout Plain Layout
6006 \begin_inset Flex CharStyle:Code
6009 \begin_layout Plain Layout
6027 the same character can apply to more than one string.
6029 \begin_inset Flex CharStyle:Code
6032 \begin_layout Plain Layout
6043 \begin_layout LyX-Code
6055 \begin_inset Newline newline
6071 \begin_layout Standard
6072 If LyX cannot find a mapping for the string produced by the keystroke or
6073 a deadkey sequence, it will check if it looks like an accented char and
6074 try to draw an accent over the character on screen.
6077 \begin_layout Subsection
6081 \begin_layout Standard
6082 There is a second way to add support for international characters through
6083 so-called dead-keys.
6084 A dead-key works in combination with a letter to produce an accented character.
6085 Here, we'll explain how to create a really simple dead-key to illustrate
6089 \begin_layout Standard
6090 Suppose you happen to need the circumflex character,
6091 \begin_inset Quotes eld
6095 \begin_inset Quotes erd
6100 \begin_inset Flex CharStyle:MenuItem
6103 \begin_layout Plain Layout
6110 \begin_inset space ~
6114 \begin_inset Flex CharStyle:MenuItem
6117 \begin_layout Plain Layout
6123 ] to the LyX command
6124 \begin_inset Flex CharStyle:Code
6127 \begin_layout Plain Layout
6134 \begin_inset Flex CharStyle:Code
6137 \begin_layout Plain Layout
6144 Now, whenever you type the
6145 \begin_inset Flex CharStyle:MenuItem
6148 \begin_layout Plain Layout
6154 -key followed by a letter, that letter will have a circumflex accent on
6156 For example, the sequence
6157 \begin_inset Quotes eld
6161 \begin_inset Flex CharStyle:MenuItem
6164 \begin_layout Plain Layout
6171 \begin_inset Quotes erd
6174 produces the letter:
6175 \begin_inset Quotes eld
6179 \begin_inset Quotes erd
6183 If you tried to type
6184 \begin_inset Quotes eld
6188 \begin_inset Flex CharStyle:MenuItem
6191 \begin_layout Plain Layout
6198 \begin_inset Quotes erd
6201 , however, LyX will complain with a beep, since a
6202 \begin_inset Quotes eld
6206 \begin_inset Flex CharStyle:MenuItem
6209 \begin_layout Plain Layout
6216 \begin_inset Quotes erd
6219 never takes a circumflex accent.
6221 \begin_inset Flex CharStyle:MenuItem
6224 \begin_layout Plain Layout
6230 after a dead-key produces the bare-accent.
6231 Please note this last point! If you bind a key to a dead-key, you'll need
6232 to rebind the character on that key to yet another key.
6234 \begin_inset Flex CharStyle:MenuItem
6237 \begin_layout Plain Layout
6243 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
6246 \begin_layout Standard
6247 One common way to bind dead-keys is to use
6248 \begin_inset Flex CharStyle:MenuItem
6251 \begin_layout Plain Layout
6258 \begin_inset Flex CharStyle:MenuItem
6261 \begin_layout Plain Layout
6268 \begin_inset Flex CharStyle:MenuItem
6271 \begin_layout Plain Layout
6277 in combination with an accent, like
6278 \begin_inset Quotes eld
6282 \begin_inset Flex CharStyle:MenuItem
6285 \begin_layout Plain Layout
6292 \begin_inset Quotes erd
6296 \begin_inset Quotes eld
6300 \begin_inset Flex CharStyle:MenuItem
6303 \begin_layout Plain Layout
6310 \begin_inset Quotes erd
6314 \begin_inset Quotes eld
6318 \begin_inset Flex CharStyle:MenuItem
6321 \begin_layout Plain Layout
6328 \begin_inset Quotes erd
6332 Another way involves using
6333 \begin_inset Flex CharStyle:Code
6336 \begin_layout Plain Layout
6343 \begin_inset Flex CharStyle:Code
6346 \begin_layout Plain Layout
6352 to set up the special
6353 \begin_inset Flex CharStyle:Code
6356 \begin_layout Plain Layout
6364 \begin_inset Flex CharStyle:Code
6367 \begin_layout Plain Layout
6373 acts in some ways just like
6374 \begin_inset Flex CharStyle:MenuItem
6377 \begin_layout Plain Layout
6383 and permits you to bind keys to accented characters.
6384 You can also turn keys into dead-keys by binding them to something like
6386 \begin_inset Flex CharStyle:Code
6389 \begin_layout Plain Layout
6395 and then binding this symbolic key to the corresponding LyX command.
6399 \begin_layout Plain Layout
6404 : This is exactly what I do in my
6405 \begin_inset Flex CharStyle:Code
6408 \begin_layout Plain Layout
6415 \begin_inset Flex CharStyle:Code
6418 \begin_layout Plain Layout
6426 \begin_inset Flex CharStyle:MenuItem
6429 \begin_layout Plain Layout
6431 \begin_inset space ~
6440 \begin_inset Flex CharStyle:Code
6443 \begin_layout Plain Layout
6449 and a bunch of these
6450 \begin_inset Quotes eld
6454 \begin_inset Flex CharStyle:Code
6457 \begin_layout Plain Layout
6464 \begin_inset Quotes erd
6467 symbolic keys bound such things as
6468 \begin_inset Flex CharStyle:MenuItem
6471 \begin_layout Plain Layout
6473 \begin_inset space ~
6482 \begin_inset Flex CharStyle:MenuItem
6485 \begin_layout Plain Layout
6487 \begin_inset space ~
6496 This is how I produce my accented characters.
6501 You can make just about anything into the
6502 \begin_inset Flex CharStyle:Code
6505 \begin_layout Plain Layout
6512 \begin_inset Flex CharStyle:MenuItem
6515 \begin_layout Plain Layout
6521 keys, a spare function key, etc.
6522 As for the LyX commands that produce accents, check the entry for
6523 \begin_inset Flex CharStyle:Code
6526 \begin_layout Plain Layout
6537 You'll find the complete list there.
6540 \begin_layout Subsection
6541 Saving your Language Configuration
6544 \begin_layout Standard
6545 \begin_inset CommandInset label
6551 You can edit your preferences so that your desired language environment
6552 is automatically configured when LyX starts up, via the
6553 \begin_inset Flex CharStyle:MenuItem
6556 \begin_layout Plain Layout
6561 dit\SpecialChar \menuseparator
6574 \begin_layout Chapter
6575 Installing New Document Classes, Layouts, and Templates
6576 \begin_inset CommandInset label
6578 name "chap:textclass"
6586 \begin_layout Plain Layout
6587 Installing New Document Classes
6595 \begin_layout Standard
6596 In this chapter, we describe the procedures for creating and installing
6597 new LyX layout and template files, as well as offer a refresher on correctly
6598 installing new LaTeX document classes.
6599 Some definitions: a document class is a LaTeX file (usually ending in
6600 \begin_inset Flex CharStyle:Code
6603 \begin_layout Plain Layout
6610 \begin_inset Flex CharStyle:Code
6613 \begin_layout Plain Layout
6619 ) that describes the format of a document such as an article, report, journal
6620 preprint, etc, and all the commands needed to realize that format.
6621 A layout file is a LyX file that corresponds to a LaTeX document class
6622 and that tells LyX how to
6623 \begin_inset Quotes eld
6627 \begin_inset Quotes erd
6630 things on the screen to make the display look something like the final
6632 More precisely, a layout file describes a
6633 \begin_inset Quotes eld
6637 \begin_inset Quotes erd
6640 which is the internal construct LyX uses to render the screen display.
6642 \begin_inset Quotes eld
6646 \begin_inset Quotes erd
6650 \begin_inset Quotes eld
6654 \begin_inset Quotes erd
6657 can be used somewhat interchangeably, but it is better to refer to the
6658 file as the layout, and the thing living in LyX's memory as the text class.
6659 A template file is simply a LyX document that contains a set of predefined
6660 entries for a given document class---entries that are generally required
6662 Templates are especially useful for things like journal manuscripts that
6663 are to be submitted electronically.
6666 \begin_layout Section
6667 Installing a new LaTeX package
6670 \begin_layout Standard
6671 Some installations may not include a LaTeX package that you would like to
6673 For example, you might need FoilTeX, a common (and very powerful) package
6674 for preparing slides or viewgraphs for overhead projectors.
6675 On some systems, you may have a GUI for installing such packages: MikTeX
6676 on Windows®, for example.
6679 \begin_layout Standard
6680 If you don't have such a GUI, then you can follow these steps.
6683 \begin_layout Enumerate
6684 Get the package from
6685 \begin_inset CommandInset href
6688 target "http://www.ctan.org/"
6695 \begin_layout Enumerate
6696 You can install this package in several different places.
6697 If you want it to be available for all users on your system, then you should
6698 install it in your `local' TeX tree; if you want (or need) it to be available
6699 just for you, then you can install it in your own `user' TeX tree.
6700 Where these should be created, if they do not already exist, depends upon
6701 the details of your system.
6702 To find out, look in the file
6703 \begin_inset Flex CharStyle:Code
6706 \begin_layout Plain Layout
6716 \begin_layout Plain Layout
6717 This usually lives in the directory
6718 \begin_inset Flex CharStyle:Code
6721 \begin_layout Plain Layout
6727 , though you can run
6728 \begin_inset Flex CharStyle:Code
6731 \begin_layout Plain Layout
6742 The location of the `local' TeX tree is defined by
6743 \begin_inset Flex CharStyle:Code
6746 \begin_layout Plain Layout
6752 ; this is usually somewhere like
6753 \begin_inset Flex CharStyle:Code
6756 \begin_layout Plain Layout
6757 /usr/local/share/texmf/
6763 The `user' TeX tree is defined by
6764 \begin_inset Flex CharStyle:Code
6767 \begin_layout Plain Layout
6774 \begin_inset Flex CharStyle:Code
6777 \begin_layout Plain Layout
6784 (If these variables are not predefined, you can define them.) You'll probably
6785 need root permissions to create or modify the `local' tree; but your `user'
6786 tree shouldn't have such limitations.
6789 \begin_layout Enumerate
6791 \begin_inset Flex CharStyle:Code
6794 \begin_layout Plain Layout
6801 \begin_inset Flex CharStyle:Code
6804 \begin_layout Plain Layout
6811 \begin_inset Flex CharStyle:Code
6814 \begin_layout Plain Layout
6822 \begin_inset Newline newline
6826 \begin_inset Flex CharStyle:Code
6829 \begin_layout Plain Layout
6830 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
6836 \begin_inset Newline newline
6839 But, again, most of this will
6840 \begin_inset Quotes eld
6844 \begin_inset Quotes erd
6850 \begin_layout Enumerate
6855 \begin_layout Plain Layout
6856 We'll assume henceforth that you're defining `local' TeX tree.
6857 If you're defining a user tree, just adjust as necessary.
6863 You must follow the directory structure of your existing
6864 \begin_inset Flex CharStyle:Code
6867 \begin_layout Plain Layout
6873 directory, which will be found at
6874 \begin_inset Flex CharStyle:Code
6877 \begin_layout Plain Layout
6884 For example, latex packages should go under
6885 \begin_inset Flex CharStyle:Code
6888 \begin_layout Plain Layout
6889 $TEXMFLOCAL/tex/latex/
6897 \begin_layout Enumerate
6898 Install the package.
6899 For example, you would unpack the FoilTeX tarball and copy it to
6900 \begin_inset Flex CharStyle:Code
6903 \begin_layout Plain Layout
6904 $TEXMFLOCAL/tex/latex/foiltex
6911 \begin_inset Flex CharStyle:Code
6914 \begin_layout Plain Layout
6920 directory contains various files.
6923 \begin_layout Enumerate
6925 \begin_inset Flex CharStyle:Code
6928 \begin_layout Plain Layout
6936 \begin_inset Flex CharStyle:Code
6939 \begin_layout Plain Layout
6948 \begin_layout Standard
6949 Your package is now installed and available to LaTeX.
6950 To make it available to LyX, you need to create a Layout file, if one is
6951 not already available.
6952 (See the next section.) Once you have a layout file, you need only reconfigure
6954 \begin_inset Flex CharStyle:MenuItem
6957 \begin_layout Plain Layout
6962 ools\SpecialChar \menuseparator
6972 ) and then restart LyX.
6973 You should then see your new package---for example
6974 \begin_inset Flex CharStyle:MenuItem
6977 \begin_layout Plain Layout
6984 \begin_inset Flex CharStyle:MenuItem
6987 \begin_layout Plain Layout
6992 ocument\SpecialChar \menuseparator
7003 \begin_inset Flex CharStyle:MenuItem
7006 \begin_layout Plain Layout
7016 \begin_layout Section
7017 \begin_inset CommandInset label
7026 \begin_layout Standard
7027 This section describes how to write and install your own LyX layout files
7028 and walks through the
7029 \begin_inset Flex CharStyle:Code
7032 \begin_layout Plain Layout
7038 text class format as an example.
7040 \begin_inset Flex CharStyle:Code
7043 \begin_layout Plain Layout
7049 files describe what paragraph and character styles are available for a
7050 given document class and how LyX should display them.
7051 We try to provide a thorough description of the process here; however,
7052 there are so many different types of documents supported by LaTeX classes
7053 that we can't hope to cover every different possibility or problem you
7055 (The LyX users' list is frequented by people with lots of experience with
7056 layout design who are willing to share what they've learned.)
7059 \begin_layout Standard
7060 As you prepare to write a new layout, it is extremely helpful to look at
7061 the example layouts distributed with LyX.
7062 If you use a nice LaTeX document class that might be of interest for others,
7063 too, and have a nice corresponding LyX layout, feel free to contribute
7064 the stuff to us, so we may put it into the distribution.
7066 \begin_inset CommandInset href
7068 name "section on the LyX wiki"
7069 target "http://wiki.lyx.org/Layouts/Layouts"
7073 for this kind of material.
7076 \begin_layout Standard
7077 All the tags described in this chapter are case-insensitive; this means
7079 \begin_inset Flex CharStyle:Code
7082 \begin_layout Plain Layout
7089 \begin_inset Flex CharStyle:Code
7092 \begin_layout Plain Layout
7099 \begin_inset Flex CharStyle:Code
7102 \begin_layout Plain Layout
7108 are really the same command.
7109 The possible values are printed in brackets after the feature's name.
7110 The default value if a feature isn't specified inside a text class-description
7112 \begin_inset Flex CharStyle:Code
7115 \begin_layout Plain Layout
7124 If the argument has a datatype like
7125 \begin_inset Quotes eld
7129 \begin_inset Quotes erd
7133 \begin_inset Quotes eld
7137 \begin_inset Quotes erd
7140 , the default is shown like this:
7141 \begin_inset Flex CharStyle:Code
7144 \begin_layout Plain Layout
7155 \begin_layout Subsection
7156 \begin_inset CommandInset label
7158 name "sub:Layout-modules"
7165 \begin_layout Standard
7166 Similar to layout files, and new with LyX 1.6, are layout
7171 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
7172 some modules---such as the Endnotes module---provide support for just such
7174 In a sense, layout modules are similar to included files---files like
7175 \begin_inset Flex CharStyle:Code
7178 \begin_layout Plain Layout
7184 ---in that modules are not specific to a given document layout but may be
7185 used with many different layouts.
7186 The difference is that using a layout module does not require editing the
7188 Rather, modules are selected in the
7189 \begin_inset Flex CharStyle:MenuItem
7192 \begin_layout Plain Layout
7197 ocument\SpecialChar \menuseparator
7210 \begin_layout Standard
7211 Building modules is the easiest way to get started with layout editing,
7212 since it can be as simple as adding a single new paragraph or flex inset.
7213 But modules may, in principle, contain anything a layout file can contain.
7216 \begin_layout Standard
7217 A module must begin with a line like the following:
7220 \begin_layout LyX-Code
7223 DeclareLyXModule[endnotes.sty]{Endnotes}
7226 \begin_layout Standard
7227 The argument in square brackets is optional: It declares any LaTeX packages
7228 on which the module depends.
7229 The mandatory argument, in curly brackets, is the name of the module, as
7231 \begin_inset Flex CharStyle:MenuItem
7234 \begin_layout Plain Layout
7235 Document\SpecialChar \menuseparator
7245 \begin_layout Standard
7246 The module declaration should then be followed by lines like the following:
7249 \begin_layout LyX-Code
7253 \begin_layout LyX-Code
7254 #Adds an endnote command, in addition to footnotes.
7258 \begin_layout LyX-Code
7259 #You will need to add
7261 theendnotes in ERT where you
7264 \begin_layout LyX-Code
7265 #want the endnotes to appear.
7269 \begin_layout LyX-Code
7273 \begin_layout LyX-Code
7274 #Requires: somemodule | othermodule
7277 \begin_layout LyX-Code
7278 #Excludes: badmodule
7281 \begin_layout Standard
7282 The description is used in
7283 \begin_inset Flex CharStyle:MenuItem
7286 \begin_layout Plain Layout
7287 Document\SpecialChar \menuseparator
7293 to provide the user with information about what the module does.
7295 \begin_inset Flex CharStyle:Code
7298 \begin_layout Plain Layout
7304 line is used to identify other modules with which this one must be used;
7306 \begin_inset Flex CharStyle:Code
7309 \begin_layout Plain Layout
7315 line is used to identify modules with which this one may not be used.
7316 Both are optional, and, as shown, multiple modules should be separated
7317 with the pipe symbol: |.
7318 Note that the required modules are treated disjunctively:
7322 of the required modules must be used.
7327 excluded module may be used.
7328 Note that modules are identified here by their
7332 without the .module extension.
7334 \begin_inset Flex CharStyle:Code
7337 \begin_layout Plain Layout
7344 \begin_inset Flex CharStyle:Code
7347 \begin_layout Plain Layout
7356 \begin_layout Standard
7357 After creating a new module, you will need to reconfigure and then restart
7358 LyX for the module to appear in the menu.
7359 However, changes you make to the module will be seen immediately, if you
7361 \begin_inset Flex CharStyle:MenuItem
7364 \begin_layout Plain Layout
7365 Document\SpecialChar \menuseparator
7371 , highlight something, and then hit
7372 \begin_inset Quotes eld
7376 \begin_inset Quotes erd
7382 It is strongly recommended that you save your work before doing so
7387 it is strongly recommended that you not attempt to edit modules while simultaneo
7388 usly working on documents
7391 Though of course the developers strive to keep LyX stable in such situations,
7392 syntax errors and the like in your module file could cause strange behavior.
7395 \begin_layout Subsection
7396 Supporting new document classes
7399 \begin_layout Standard
7400 There are two situations you are likely to encounter when wanting to support
7401 a new LaTeX document class, involving LaTeX2e class (
7402 \begin_inset Flex CharStyle:Code
7405 \begin_layout Plain Layout
7412 \begin_inset Flex CharStyle:Code
7415 \begin_layout Plain Layout
7422 Supporting a style file is usually fairly easy.
7423 Supporting a new document class is a bit harder.
7426 \begin_layout Subsection
7428 \begin_inset Flex CharStyle:MenuItem
7431 \begin_layout Plain Layout
7440 \begin_layout Standard
7441 If your new document class is provided as a style file that is used in conjuncti
7442 on with an existing, supported document class---for the sake of the example,
7443 we'll assume that the style file is called
7444 \begin_inset Flex CharStyle:MenuItem
7447 \begin_layout Plain Layout
7453 and it is meant to be used with
7454 \begin_inset Flex CharStyle:MenuItem
7457 \begin_layout Plain Layout
7463 , which is a standard class---start by copying the existing class's layout
7464 file into your local directory:
7467 \begin_layout LyX-Code
7468 cp report.layout ~/.lyx/layouts/myclass.layout
7471 \begin_layout Standard
7473 \begin_inset Flex CharStyle:Code
7476 \begin_layout Plain Layout
7482 and change the line:
7485 \begin_layout LyX-Code
7488 DeclareLaTeXClass{report}
7491 \begin_layout Standard
7495 \begin_layout LyX-Code
7498 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
7501 \begin_layout Standard
7505 \begin_layout LyX-Code
7507 \begin_inset Newline newline
7513 \begin_inset Newline newline
7519 \begin_layout Standard
7520 near the top of the file.
7523 \begin_layout Standard
7524 Start LyX and select
7525 \begin_inset Flex CharStyle:MenuItem
7528 \begin_layout Plain Layout
7533 ools\SpecialChar \menuseparator
7544 Then restart LyX and try creating a new document.
7546 \begin_inset Flex CharStyle:MenuItem
7549 \begin_layout Plain Layout
7555 " as a document class option in the
7556 \begin_inset Flex CharStyle:MenuItem
7559 \begin_layout Plain Layout
7564 ocument\SpecialChar \menuseparator
7575 It is likely that some of the sectioning commands and such in your new
7576 class will work differently from how they worked in the base class---
7577 \begin_inset Flex CharStyle:Code
7580 \begin_layout Plain Layout
7586 in this example---so you can fiddle around with the settings for the different
7587 sections if you wish.
7590 \begin_layout Subsection
7592 \begin_inset Flex CharStyle:MenuItem
7595 \begin_layout Plain Layout
7604 \begin_layout Standard
7605 There are two possibilities here.
7606 One is that the class file is itself based upon an existing document class.
7607 For example, many thesis classes are based upon
7608 \begin_inset Flex CharStyle:MenuItem
7611 \begin_layout Plain Layout
7618 To see whether yours is, look for a line like
7621 \begin_layout LyX-Code
7627 \begin_layout Standard
7629 If so, then you may proceed largely as in the previous section, though
7630 the DeclareLaTeXClass line will be different.
7631 If your new class is thesis, and it is based upon book, then the line should
7636 \begin_layout Plain Layout
7637 And it will be easiest if you save the file to
7638 \begin_inset Flex CharStyle:Code
7641 \begin_layout Plain Layout
7647 : LyX assumes that the document class has the same name as the layout file.
7656 \begin_layout LyX-Code
7659 DeclareLaTeXClass[thesis,book]{thesis}
7662 \begin_layout Standard
7663 If, on the other hand, the new class is not based upon an existing class,
7664 you will probably have to
7665 \begin_inset Quotes eld
7669 \begin_inset Quotes erd
7673 We strongly suggest copying an existing layout file which uses a similar
7674 LaTeX class and then modifying it, if you can do so.
7675 At least use an existing file as a starting point so you can find out what
7676 items you need to worry about.
7677 Again, the specifics are covered below.
7680 \begin_layout Section
7681 Declaring a new text class
7684 \begin_layout Standard
7685 When it's finally time to get your hands dirty and create or edit your own
7686 layout file, the following sections describe what you're up against.
7687 Our advice is to go slowly, save and test often, listen to soothing music,
7688 and enjoy one or two of your favorite adult beverages; more if you are
7689 getting particularly stuck.
7690 It's really not that hard, except that the multitude of options can become
7691 overwhelming if you try to do to much in one sitting.
7692 Go have another adult beverage, just for good measure.
7695 \begin_layout Standard
7699 \begin_layout Standard
7700 Lines in a layout file which begin with a
7701 \begin_inset Flex CharStyle:Code
7704 \begin_layout Plain Layout
7711 There is one exception to this rule: all layouts should begin with lines
7715 \begin_layout LyX-Code
7718 #% Do not delete the line below; configure depends on this
7721 \begin_layout LyX-Code
7726 DeclareLaTeXClass{article}
7729 \begin_layout Standard
7730 The second line is used when you configure LyX.
7731 The layout file is read by the LaTeX script
7732 \begin_inset Flex CharStyle:Code
7735 \begin_layout Plain Layout
7741 , in a special mode where
7742 \begin_inset Flex CharStyle:Code
7745 \begin_layout Plain Layout
7752 The first line is just a LaTeX comment, and the second one contains the
7753 declaration of the text class.
7754 If these lines appear in a file named
7755 \begin_inset Flex CharStyle:Code
7758 \begin_layout Plain Layout
7764 , then they define a text class of name
7765 \begin_inset Flex CharStyle:Code
7768 \begin_layout Plain Layout
7774 (the name of the layout file) which uses the LaTeX document class
7775 \begin_inset Flex CharStyle:Code
7778 \begin_layout Plain Layout
7784 (the default is to use the same name as the layout).
7786 \begin_inset Quotes eld
7790 \begin_inset Quotes erd
7793 that appears above is used as a description of the text class in the
7794 \begin_inset Flex CharStyle:MenuItem
7797 \begin_layout Plain Layout
7802 ocument\SpecialChar \menuseparator
7815 \begin_layout Standard
7816 Let's assume that you wrote your own text class that uses the
7817 \begin_inset Flex CharStyle:Code
7820 \begin_layout Plain Layout
7826 document class, but where you changed the appearance of the section headings.
7827 If you put it in a file
7828 \begin_inset Flex CharStyle:Code
7831 \begin_layout Plain Layout
7837 , the header of this file should be:
7840 \begin_layout LyX-Code
7843 #% Do not delete the line below; configure depends on this
7846 \begin_layout LyX-Code
7851 DeclareLaTeXClass[article]{article (with my own headings)}
7854 \begin_layout Standard
7855 This declares a text class
7856 \begin_inset Flex CharStyle:Code
7859 \begin_layout Plain Layout
7865 , associated with the LaTeX document class
7866 \begin_inset Flex CharStyle:Code
7869 \begin_layout Plain Layout
7876 \begin_inset Quotes eld
7879 article (with my own headings)
7880 \begin_inset Quotes erd
7884 If your text class depends on several packages, you can declare it as:
7887 \begin_layout LyX-Code
7890 #% Do not delete the line below; configure depends on this
7893 \begin_layout LyX-Code
7898 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7901 \begin_layout Standard
7902 This indicates that your text class uses the foo.sty package.
7903 Finally, it is also possible to declare classes for DocBook code.
7904 Typical declarations will look like
7907 \begin_layout LyX-Code
7910 #% Do not delete the line below; configure depends on this
7913 \begin_layout LyX-Code
7918 DeclareDocBookClass[article]{SGML (DocBook article)}
7921 \begin_layout Standard
7922 Note that these declarations can also be given an optional parameter declaring
7923 the name of the document class (but not a list).
7926 \begin_layout Standard
7927 So, to be as explicit as possible, the form of the layout declaration is:
7930 \begin_layout LyX-Code
7935 DeclareLaTeXClass[class,package.sty]{layout description}
7938 \begin_layout Standard
7939 The class need only be specified if the name of the LaTeX class file and
7940 the name of the layout file are different; if the name of the classfile
7941 is not specified, then LyX will simply assume that it is the same as the
7942 name of the layout file.
7945 \begin_layout Standard
7946 When the text class has been modified to your taste, all you have to do
7947 is to copy it either to
7948 \begin_inset Flex CharStyle:Code
7951 \begin_layout Plain Layout
7958 \begin_inset Flex CharStyle:Code
7961 \begin_layout Plain Layout
7968 \begin_inset Flex CharStyle:MenuItem
7971 \begin_layout Plain Layout
7976 ools\SpecialChar \menuseparator
7986 , exit LyX and restart it.
7987 Then your new text class should be available along with the others.
7990 \begin_layout Standard
7991 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
7992 you made to your layout files.
7993 As a result, editing layout files could be very time consuming.
7994 Beginning with 1.6, however, you can force a reload of the layout currently
7995 in use by using the LyX function
7996 \begin_inset Flex CharStyle:MenuItem
7999 \begin_layout Plain Layout
8006 There is no default binding for this function---though, of course, you
8007 can bind it to a key yourself (see section
8008 \begin_inset CommandInset ref
8010 reference "sec:bindings"
8015 If you want to use this function, then, you should simply enter it in the
8021 : This is very much an `advanced feature'.
8026 recommended that you save your work before using this function.
8031 recommended that you not attempt to edit your layout while simultaneously
8032 working on a document that you care about.
8033 Use a test document.
8034 Syntax errors and the like in your layout file could cause peculiar behavior.
8035 In particular, such errors could cause LyX to regard the current layout
8036 as invalid and to attempt to switch to some other layout.
8037 The LyX team strives to keep LyX stable in such situations, but safe is
8041 \begin_layout Subsection
8045 \begin_layout Standard
8046 The first non-comment line must contain the file format number:
8049 \begin_layout Description
8050 \begin_inset Flex CharStyle:Code
8053 \begin_layout Plain Layout
8060 \begin_inset Flex CharStyle:Code
8063 \begin_layout Plain Layout
8069 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
8070 don't have an explicit file format).
8071 The file format that is documented here is format 7.
8074 \begin_layout Subsection
8075 General text class parameters
8078 \begin_layout Standard
8079 These are the general parameters which describe the form of the entire document:
8082 \begin_layout Description
8083 \begin_inset Flex CharStyle:Code
8086 \begin_layout Plain Layout
8092 Adds information to the document preamble.
8094 \begin_inset Quotes eld
8098 \begin_inset Flex CharStyle:Code
8101 \begin_layout Plain Layout
8108 \begin_inset Quotes erd
8114 \begin_layout Description
8115 \begin_inset Flex CharStyle:Code
8118 \begin_layout Plain Layout
8124 Describes various global options supported by the document class.
8126 \begin_inset space ~
8130 \begin_inset CommandInset ref
8132 reference "sec:classoptions"
8138 \begin_inset Quotes eld
8142 \begin_inset Flex CharStyle:Code
8145 \begin_layout Plain Layout
8152 \begin_inset Quotes erd
8158 \begin_layout Description
8159 \begin_inset Flex CharStyle:Code
8162 \begin_layout Plain Layout
8169 \begin_inset Flex CharStyle:Code
8172 \begin_layout Plain Layout
8181 \begin_inset Flex CharStyle:Code
8184 \begin_layout Plain Layout
8190 ] Whether the class should default to having one or two columns.
8191 Can be changed in the
8192 \begin_inset Flex CharStyle:MenuItem
8195 \begin_layout Plain Layout
8200 ocument\SpecialChar \menuseparator
8213 \begin_layout Description
8214 \begin_inset Flex CharStyle:Code
8217 \begin_layout Plain Layout
8223 This sequence defines a new counter.
8225 \begin_inset space ~
8229 \begin_inset CommandInset ref
8231 reference "sec:counter"
8237 \begin_inset Quotes eld
8241 \begin_inset Flex CharStyle:Code
8244 \begin_layout Plain Layout
8251 \begin_inset Quotes erd
8257 \begin_layout Description
8258 \begin_inset Flex CharStyle:Code
8261 \begin_layout Plain Layout
8267 Sets the default font used to display the document.
8269 \begin_inset space ~
8273 \begin_inset CommandInset ref
8275 reference "sec:fonts"
8279 for how to declare fonts.
8281 \begin_inset Quotes eld
8285 \begin_inset Flex CharStyle:Code
8288 \begin_layout Plain Layout
8295 \begin_inset Quotes erd
8301 \begin_layout Description
8302 \begin_inset Flex CharStyle:Code
8305 \begin_layout Plain Layout
8312 \begin_inset Flex CharStyle:Code
8315 \begin_layout Plain Layout
8321 ] This is the style that will be assigned to new paragraphs, usually
8322 \begin_inset Flex CharStyle:MenuItem
8325 \begin_layout Plain Layout
8332 This will default to the first defined style if not given, but you are
8333 highly encouraged to use this directive.
8336 \begin_layout Description
8337 \begin_inset Flex CharStyle:Code
8340 \begin_layout Plain Layout
8346 Defines a new float.
8348 \begin_inset space ~
8352 \begin_inset CommandInset ref
8354 reference "sec:floats"
8360 \begin_inset Quotes eld
8364 \begin_inset Flex CharStyle:Code
8367 \begin_layout Plain Layout
8374 \begin_inset Quotes erd
8380 \begin_layout Description
8381 \begin_inset Flex CharStyle:Code
8384 \begin_layout Plain Layout
8390 As its name implies, this command allows you to include another layout
8391 definition file within yours to avoid duplicating commands.
8392 Common examples are the standard layout files, for example,
8393 \begin_inset Flex CharStyle:Code
8396 \begin_layout Plain Layout
8402 , which contains most of the basic layouts.
8405 \begin_layout Description
8406 \begin_inset Flex CharStyle:Code
8409 \begin_layout Plain Layout
8415 This section (re-)defines the layout of an inset.
8416 It can be applied to an existing inset of to a new, user-defined inset,
8417 e.g., a new character style.
8419 \begin_inset space ~
8423 \begin_inset CommandInset ref
8425 reference "sec:charstyle"
8429 for more information.
8431 \begin_inset Quotes eld
8435 \begin_inset Flex CharStyle:Code
8438 \begin_layout Plain Layout
8445 \begin_inset Quotes erd
8451 \begin_layout Description
8452 \begin_inset Flex CharStyle:Code
8455 \begin_layout Plain Layout
8464 \begin_layout Description
8465 \begin_inset Flex CharStyle:Code
8468 \begin_layout Plain Layout
8474 This command deletes an existing float.
8475 This is particularly useful when you want to suppress a float that has
8476 be defined in an input file.
8479 \begin_layout Description
8480 \begin_inset Flex CharStyle:Code
8483 \begin_layout Plain Layout
8489 This command deletes an existing style.
8490 This is particularly useful when you want to suppress a style that has
8491 be defined in an input file.
8494 \begin_layout Description
8495 \begin_inset Flex CharStyle:Code
8498 \begin_layout Plain Layout
8507 \begin_layout Description
8508 \begin_inset Flex CharStyle:Code
8511 \begin_layout Plain Layout
8522 \begin_inset Flex CharStyle:Code
8525 \begin_layout Plain Layout
8536 \begin_inset Flex CharStyle:Code
8539 \begin_layout Plain Layout
8546 \begin_inset Flex CharStyle:Code
8549 \begin_layout Plain Layout
8555 ] The class default pagestyle.
8556 Can be changed in the
8557 \begin_inset Flex CharStyle:MenuItem
8560 \begin_layout Plain Layout
8565 ocument\SpecialChar \menuseparator
8578 \begin_layout Description
8579 \begin_inset Flex CharStyle:Code
8582 \begin_layout Plain Layout
8588 Sets the preamble for the LaTeX document.
8589 Note that this will completely override any prior
8590 \begin_inset Flex CharStyle:Code
8593 \begin_layout Plain Layout
8600 \begin_inset Flex CharStyle:Code
8603 \begin_layout Plain Layout
8611 \begin_inset Quotes eld
8615 \begin_inset Flex CharStyle:Code
8618 \begin_layout Plain Layout
8625 \begin_inset Quotes erd
8631 \begin_layout Description
8632 \begin_inset Flex CharStyle:Code
8635 \begin_layout Plain Layout
8642 \begin_inset CommandInset label
8649 \begin_inset Flex CharStyle:Code
8652 \begin_layout Plain Layout
8659 \begin_inset Flex CharStyle:Code
8662 \begin_layout Plain Layout
8671 \begin_inset Flex CharStyle:Code
8674 \begin_layout Plain Layout
8680 ] Whether the class already provides the feature
8681 \begin_inset Flex CharStyle:Code
8684 \begin_layout Plain Layout
8691 A feature is in general the name of a package (
8692 \begin_inset Flex CharStyle:Code
8695 \begin_layout Plain Layout
8702 \begin_inset Flex CharStyle:Code
8705 \begin_layout Plain Layout
8711 , \SpecialChar \ldots{}
8713 \begin_inset Flex CharStyle:Code
8716 \begin_layout Plain Layout
8723 \begin_inset Flex CharStyle:Code
8726 \begin_layout Plain Layout
8732 ,\SpecialChar \ldots{}
8733 ); the complete list of supported features is unfortunately not documented
8734 outside the LyX source code---but see
8735 \begin_inset Flex CharStyle:Code
8738 \begin_layout Plain Layout
8744 if you're interested.
8746 \begin_inset Flex CharStyle:MenuItem
8749 \begin_layout Plain Layout
8754 elp\SpecialChar \menuseparator
8764 also gives an overview of the supported packages.
8767 \begin_layout Description
8768 \begin_inset Flex CharStyle:Code
8771 \begin_layout Plain Layout
8778 \begin_inset Flex CharStyle:Code
8781 \begin_layout Plain Layout
8787 ] Whether the class requires the feature
8788 \begin_inset Flex CharStyle:Code
8791 \begin_layout Plain Layout
8798 Multiple features must be separated by commas.
8799 Note that you can only request supported features.
8802 \begin_layout Description
8803 \begin_inset Flex CharStyle:Code
8806 \begin_layout Plain Layout
8815 \begin_layout Description
8816 \begin_inset Flex CharStyle:Code
8819 \begin_layout Plain Layout
8828 \begin_layout Description
8829 \begin_inset Flex CharStyle:Code
8832 \begin_layout Plain Layout
8841 \begin_inset Flex CharStyle:Code
8844 \begin_layout Plain Layout
8855 \begin_inset Flex CharStyle:Code
8858 \begin_layout Plain Layout
8864 ] Whether the class-default should be printing on one or both sides of the
8866 Can be changed in the
8867 \begin_inset Flex CharStyle:MenuItem
8870 \begin_layout Plain Layout
8875 ocument\SpecialChar \menuseparator
8888 \begin_layout Description
8889 \begin_inset Flex CharStyle:Code
8892 \begin_layout Plain Layout
8898 This sequence defines a new paragraph style.
8899 If the style already exists, it will redefine some of its parameters instead.
8901 \begin_inset space ~
8905 \begin_inset CommandInset ref
8907 reference "sec:style"
8913 \begin_inset Quotes eld
8917 \begin_inset Flex CharStyle:Code
8920 \begin_layout Plain Layout
8927 \begin_inset Quotes erd
8933 \begin_layout Description
8934 \begin_inset Flex CharStyle:Code
8937 \begin_layout Plain Layout
8944 \begin_inset Flex CharStyle:Code
8947 \begin_layout Plain Layout
8953 ] The name of the command or environment to be used with
8954 \begin_inset Flex CharStyle:Code
8957 \begin_layout Plain Layout
8966 \begin_layout Description
8967 \begin_inset Flex CharStyle:Code
8970 \begin_layout Plain Layout
8977 \begin_inset Flex CharStyle:Code
8980 \begin_layout Plain Layout
8989 \begin_inset Flex CharStyle:Code
8992 \begin_layout Plain Layout
8998 ] Indicates what kind of markup is used to define the title of a document.
9000 \begin_inset Flex CharStyle:Code
9003 \begin_layout Plain Layout
9009 means that the macro with name
9010 \begin_inset Flex CharStyle:Code
9013 \begin_layout Plain Layout
9019 will be inserted after the last layout which has
9020 \begin_inset Quotes eld
9024 \begin_inset Flex CharStyle:Code
9027 \begin_layout Plain Layout
9034 \begin_inset Quotes erd
9039 \begin_inset Flex CharStyle:Code
9042 \begin_layout Plain Layout
9048 corresponds to the case where the block of paragraphs which have
9049 \begin_inset Quotes eld
9053 \begin_inset Flex CharStyle:Code
9056 \begin_layout Plain Layout
9063 \begin_inset Quotes erd
9066 should be enclosed into the
9067 \begin_inset Flex CharStyle:Code
9070 \begin_layout Plain Layout
9079 \begin_layout Description
9080 \begin_inset Flex CharStyle:Code
9083 \begin_layout Plain Layout
9092 \begin_layout Subsection
9093 \begin_inset Flex CharStyle:Code
9096 \begin_layout Plain Layout
9105 \begin_layout Standard
9106 \begin_inset CommandInset label
9108 name "sec:classoptions"
9113 \begin_inset Flex CharStyle:Code
9116 \begin_layout Plain Layout
9122 section can contain the following entries:
9125 \begin_layout Description
9126 \begin_inset Flex CharStyle:Code
9129 \begin_layout Plain Layout
9136 \begin_inset Flex CharStyle:Code
9139 \begin_layout Plain Layout
9145 ] The list of available font sizes for the document's main font, separated
9147 \begin_inset Quotes eld
9151 \begin_inset Flex CharStyle:Code
9154 \begin_layout Plain Layout
9161 \begin_inset Quotes erd
9167 \begin_layout Description
9168 \begin_inset Flex CharStyle:Code
9171 \begin_layout Plain Layout
9180 \begin_layout Description
9181 \begin_inset Flex CharStyle:Code
9184 \begin_layout Plain Layout
9191 \begin_inset Flex CharStyle:Code
9194 \begin_layout Plain Layout
9195 string="empty|plain|headings|fancy"
9200 ] The list of available page styles, separated by
9201 \begin_inset Quotes eld
9205 \begin_inset Flex CharStyle:Code
9208 \begin_layout Plain Layout
9215 \begin_inset Quotes erd
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
9241 ] Some document class options, separated by a comma, that will be added
9242 to the optional part of the
9243 \begin_inset Flex CharStyle:Code
9246 \begin_layout Plain Layout
9257 \begin_layout Standard
9259 \begin_inset Flex CharStyle:Code
9262 \begin_layout Plain Layout
9268 section must end with
9269 \begin_inset Quotes eld
9273 \begin_inset Flex CharStyle:Code
9276 \begin_layout Plain Layout
9283 \begin_inset Quotes erd
9289 \begin_layout Subsection
9293 \begin_layout Standard
9294 \begin_inset CommandInset label
9300 A paragraph style description looks like this:
9304 \begin_layout Plain Layout
9305 Note that this will either define a new layout or modify an existing one.
9313 \begin_layout LyX-Code
9320 \begin_layout LyX-Code
9324 \begin_layout LyX-Code
9328 \begin_layout Standard
9329 where the following commands are allowed:
9332 \begin_layout Description
9333 \begin_inset Flex CharStyle:Code
9336 \begin_layout Plain Layout
9343 \begin_inset Flex CharStyle:Code
9346 \begin_layout Plain Layout
9351 , left, right, center
9356 ] Paragraph alignment.
9359 \begin_layout Description
9360 \begin_inset Flex CharStyle:Code
9363 \begin_layout Plain Layout
9370 \begin_inset Flex CharStyle:Code
9373 \begin_layout Plain Layout
9378 , left, right, center
9383 ] A comma separated list of permitted alignments.
9384 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9386 For example a right-aligned or centered enumeration isn't possible.)
9389 \begin_layout Description
9390 \begin_inset Flex CharStyle:Code
9393 \begin_layout Plain Layout
9400 \begin_inset Flex CharStyle:Code
9403 \begin_layout Plain Layout
9413 \begin_layout Plain Layout
9414 Note that a `float' here is a real number, such as: 1.5.
9419 The vertical space with which the last of a chain of paragraphs with this
9420 layout is separated from the following paragraph.
9421 If the next paragraph has another layout, the separations are not simply
9422 added, but the maximum is taken.
9425 \begin_layout Description
9426 \begin_inset Flex CharStyle:Code
9429 \begin_layout Plain Layout
9436 \begin_inset Flex CharStyle:Code
9439 \begin_layout Plain Layout
9445 The category for this style.
9446 This is used to group related styles in the Layout combobox on the toolbar.
9447 Any string can be used, but you may want to use existing categories with
9452 \begin_layout Description
9453 \begin_inset Flex CharStyle:Code
9456 \begin_layout Plain Layout
9465 \begin_layout Description
9466 \begin_inset Flex CharStyle:Code
9469 \begin_layout Plain Layout
9476 \begin_inset Flex CharStyle:Code
9479 \begin_layout Plain Layout
9485 Copies all the features of an existing style into the current one.
9489 \begin_layout Description
9490 \begin_inset Flex CharStyle:Code
9493 \begin_layout Plain Layout
9499 The name of a style whose preamble should be output
9504 This allows to ensure some ordering of the preamble snippets when macros
9505 definitions depend on one another.
9509 \begin_layout Plain Layout
9510 Note that, besides that functionality, there is no way to ensure any ordering
9512 The ordering that you see in a given version of LyX may change without
9513 warning in later versions.
9521 \begin_layout Description
9522 \begin_inset Flex CharStyle:Code
9525 \begin_layout Plain Layout
9532 \begin_inset Flex CharStyle:Code
9535 \begin_layout Plain Layout
9540 , Box, Filled_Box, Static
9545 ] The type of label that stands at the end of the paragraph (or sequence
9547 \begin_inset Flex CharStyle:Code
9550 \begin_layout Plain Layout
9557 \begin_inset Flex CharStyle:Code
9560 \begin_layout Plain Layout
9567 \begin_inset Flex CharStyle:Code
9570 \begin_layout Plain Layout
9577 \begin_inset Flex CharStyle:Code
9580 \begin_layout Plain Layout
9588 \begin_inset Flex CharStyle:Code
9591 \begin_layout Plain Layout
9598 \begin_inset Quotes eld
9602 \begin_inset Quotes erd
9606 \begin_inset Flex CharStyle:Code
9609 \begin_layout Plain Layout
9616 \begin_inset Flex CharStyle:Code
9619 \begin_layout Plain Layout
9620 \begin_inset space ~
9629 \begin_inset space ~
9632 black) square suitable for end of proof markers,
9633 \begin_inset Flex CharStyle:Code
9636 \begin_layout Plain Layout
9642 is an explicit text string.
9645 \begin_layout Description
9646 \begin_inset Flex CharStyle:Code
9649 \begin_layout Plain Layout
9656 \begin_inset Flex CharStyle:Code
9659 \begin_layout Plain Layout
9665 ] The string used for a label with a
9666 \begin_inset Flex CharStyle:Code
9669 \begin_layout Plain Layout
9676 \begin_inset Flex CharStyle:Code
9679 \begin_layout Plain Layout
9689 \begin_layout Description
9690 \begin_inset Flex CharStyle:Code
9693 \begin_layout Plain Layout
9700 \begin_inset Flex CharStyle:Code
9703 \begin_layout Plain Layout
9714 \begin_inset Flex CharStyle:Code
9717 \begin_layout Plain Layout
9726 \begin_layout Description
9727 \begin_inset Flex CharStyle:Code
9730 \begin_layout Plain Layout
9737 \begin_inset Flex CharStyle:Code
9740 \begin_layout Plain Layout
9750 ] With this parameter the
9751 \begin_inset Flex CharStyle:MenuItem
9754 \begin_layout Plain Layout
9761 \begin_inset Quotes eld
9764 Vertical space above
9765 \begin_inset Quotes erd
9769 \begin_inset Flex CharStyle:MenuItem
9772 \begin_layout Plain Layout
9777 dit\SpecialChar \menuseparator
9783 \begin_inset space ~
9791 dialog can be set when initializing a paragraph with this style.
9795 \begin_layout Plain Layout
9798 Note from Jean-Marc:
9800 I'm not sure that this setting has much use, and it should probably be
9801 removed in later versions.
9809 \begin_layout Description
9810 \begin_inset Flex CharStyle:Code
9813 \begin_layout Plain Layout
9819 The font used for both the text body
9825 \begin_inset space ~
9829 \begin_inset CommandInset ref
9831 reference "sec:fonts"
9836 Note that defining this font automatically defines the
9837 \begin_inset Flex CharStyle:Code
9840 \begin_layout Plain Layout
9847 So you should define this one first if you also want to define
9848 \begin_inset Flex CharStyle:Code
9851 \begin_layout Plain Layout
9860 \begin_layout Description
9861 \begin_inset Flex CharStyle:Code
9864 \begin_layout Plain Layout
9871 \begin_inset CommandInset label
9873 name "des:FreeSpacing"
9880 \begin_inset Flex CharStyle:Code
9883 \begin_layout Plain Layout
9894 \begin_inset Flex CharStyle:Code
9897 \begin_layout Plain Layout
9903 ] Usually LyX doesn't allow you to insert more than one space between words,
9904 since a space is considered as the separation between two words, not a
9905 character or symbol of its own.
9906 This is a very fine thing but sometimes annoying, for example, when typing
9907 program code or plain LaTeX code.
9909 \begin_inset Flex CharStyle:Code
9912 \begin_layout Plain Layout
9919 Note that LyX will create protected blanks for the additional blanks when
9920 in another mode than LaTeX-mode.
9923 \begin_layout Description
9924 \begin_inset Flex CharStyle:Code
9927 \begin_layout Plain Layout
9936 \begin_layout Description
9937 \begin_inset Flex CharStyle:Code
9940 \begin_layout Plain Layout
9947 \begin_inset Flex CharStyle:Code
9950 \begin_layout Plain Layout
9956 If 1, marks the layout as being part of a title block (see also the
9957 \begin_inset Flex CharStyle:Code
9960 \begin_layout Plain Layout
9967 \begin_inset Flex CharStyle:Code
9970 \begin_layout Plain Layout
9979 \begin_layout Description
9980 \begin_inset Flex CharStyle:Code
9983 \begin_layout Plain Layout
9990 \begin_inset Flex CharStyle:Code
9993 \begin_layout Plain Layout
9999 ] This provides extra space between paragraphs that have the same layout.
10000 If you put other layouts into an environment, each is separated with the
10002 \begin_inset Flex CharStyle:Code
10005 \begin_layout Plain Layout
10012 But the whole items of the environment are additionally separated with
10014 \begin_inset Flex CharStyle:Code
10017 \begin_layout Plain Layout
10024 Note that this is a
10029 \begin_layout Description
10030 \begin_inset Flex CharStyle:Code
10033 \begin_layout Plain Layout
10042 \begin_layout Description
10043 \begin_inset Flex CharStyle:Code
10046 \begin_layout Plain Layout
10053 \begin_inset CommandInset label
10055 name "des:KeepEmpty"
10062 \begin_inset Flex CharStyle:Code
10065 \begin_layout Plain Layout
10076 \begin_inset Flex CharStyle:Code
10079 \begin_layout Plain Layout
10085 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10086 lead to empty LaTeX output.
10087 There are some cases where this could be desirable however: in a letter
10088 template, the required fields can be provided as empty fields, so that
10089 people do not forget them; in some special classes, a layout can be used
10090 as some kind of break, which does not contain actual text.
10093 \begin_layout Description
10094 \begin_inset Flex CharStyle:Code
10097 \begin_layout Plain Layout
10103 [float=0] The vertical space between the label and the text body.
10104 Only used for labels that are above the text body (
10105 \begin_inset Flex CharStyle:Code
10108 \begin_layout Plain Layout
10115 \begin_inset Flex CharStyle:Code
10118 \begin_layout Plain Layout
10119 Centered_Top_Environment
10127 \begin_layout Description
10128 \begin_inset Flex CharStyle:Code
10131 \begin_layout Plain Layout
10138 \begin_inset Flex CharStyle:Code
10141 \begin_layout Plain Layout
10148 \begin_inset Newline newline
10151 The name of the counter for automatic numbering (see Section
10152 \begin_inset CommandInset ref
10154 reference "sec:counter"
10159 This must be given if
10160 \begin_inset Flex CharStyle:Code
10163 \begin_layout Plain Layout
10170 \begin_inset Flex CharStyle:Code
10173 \begin_layout Plain Layout
10182 \begin_layout Description
10183 \begin_inset Flex CharStyle:Code
10186 \begin_layout Plain Layout
10192 The font used for the label.
10194 \begin_inset space ~
10198 \begin_inset CommandInset ref
10200 reference "sec:fonts"
10207 \begin_layout Description
10208 \begin_inset Flex CharStyle:Code
10211 \begin_layout Plain Layout
10218 \begin_inset Flex CharStyle:Code
10221 \begin_layout Plain Layout
10227 ] The horizontal space between the label and the text body.
10228 Only used for labels that are not above the text body.
10231 \begin_layout Description
10232 \begin_inset Flex CharStyle:Code
10235 \begin_layout Plain Layout
10242 \begin_inset Flex CharStyle:Code
10245 \begin_layout Plain Layout
10251 ] The string used for a label with a
10252 \begin_inset Flex CharStyle:Code
10255 \begin_layout Plain Layout
10263 \begin_inset Flex CharStyle:Code
10266 \begin_layout Plain Layout
10272 is set, this string can be contain the special formatting commands described
10274 \begin_inset CommandInset ref
10276 reference "sec:counter"
10284 \begin_layout Plain Layout
10285 For the sake of backwards compatibility, the string
10286 \begin_inset Flex CharStyle:Code
10289 \begin_layout Plain Layout
10299 will be replaced by the expanded
10300 \begin_inset Flex CharStyle:Code
10303 \begin_layout Plain Layout
10310 \begin_inset Flex CharStyle:Code
10313 \begin_layout Plain Layout
10322 This feature is now obsolete and should be replaced by the mechanisms of
10324 \begin_inset CommandInset ref
10326 reference "sec:counter"
10338 \begin_layout Description
10339 \begin_inset Flex CharStyle:Code
10342 \begin_layout Plain Layout
10343 LabelStringAppendix
10349 \begin_inset Flex CharStyle:Code
10352 \begin_layout Plain Layout
10358 ] This is used inside the appendix instead of
10359 \begin_inset Flex CharStyle:Code
10362 \begin_layout Plain Layout
10370 \begin_inset Flex CharStyle:Code
10373 \begin_layout Plain Layout
10380 \begin_inset Flex CharStyle:Code
10383 \begin_layout Plain Layout
10384 LabelStringAppendix
10392 \begin_layout Description
10393 \begin_inset Flex CharStyle:Code
10396 \begin_layout Plain Layout
10403 \begin_inset Flex CharStyle:Code
10406 \begin_layout Plain Layout
10411 , Manual, Static, Top_Environment,
10412 \begin_inset Newline newline
10415 Centered_Top_Environment, Sensitive, Counter
10421 \begin_inset Newline newline
10425 \begin_inset Flex CharStyle:Code
10428 \begin_layout Plain Layout
10434 means the label is the very first word (up to the first real blank).
10438 \begin_layout Plain Layout
10439 Use protected spaces if you want more than one word as the label.
10445 \begin_inset Flex CharStyle:Code
10448 \begin_layout Plain Layout
10454 means it is defined in the layout (see
10455 \begin_inset Flex CharStyle:Code
10458 \begin_layout Plain Layout
10466 \begin_inset Flex CharStyle:Code
10469 \begin_layout Plain Layout
10476 \begin_inset Flex CharStyle:Code
10479 \begin_layout Plain Layout
10480 Centered_Top_Environment
10485 are special cases of
10486 \begin_inset Flex CharStyle:Code
10489 \begin_layout Plain Layout
10496 The label will be printed above the paragraph, but only at the top of an
10497 environment or the top of a chain of paragraphs with this layout.
10498 Usage is for example the
10499 \begin_inset Flex CharStyle:MenuItem
10502 \begin_layout Plain Layout
10509 \begin_inset Flex CharStyle:MenuItem
10512 \begin_layout Plain Layout
10519 This is also the case for
10520 \begin_inset Flex CharStyle:Code
10523 \begin_layout Plain Layout
10529 labels with latex type
10530 \begin_inset Flex CharStyle:Code
10533 \begin_layout Plain Layout
10539 , in order to make layouts for theorems work correctly.
10541 \begin_inset Flex CharStyle:Code
10544 \begin_layout Plain Layout
10550 is a special case for the caption-labels
10551 \begin_inset Quotes eld
10555 \begin_inset Quotes erd
10559 \begin_inset Quotes eld
10563 \begin_inset Quotes erd
10568 \begin_inset Flex CharStyle:Code
10571 \begin_layout Plain Layout
10577 means the (hardcoded) label string depends on the kind of float.
10579 \begin_inset Flex CharStyle:Code
10582 \begin_layout Plain Layout
10588 label type defines automatically numbered labels.
10590 \begin_inset CommandInset ref
10592 reference "sec:counter"
10599 \begin_layout Description
10600 \begin_inset Flex CharStyle:Code
10603 \begin_layout Plain Layout
10612 \begin_layout Description
10613 \begin_inset Flex CharStyle:Code
10616 \begin_layout Plain Layout
10625 \begin_layout Description
10626 \begin_inset Flex CharStyle:Code
10629 \begin_layout Plain Layout
10636 \begin_inset CommandInset label
10638 name "des:LatexName"
10642 The name of the corresponding LaTeX stuff.
10643 Either the environment or command name.
10646 \begin_layout Description
10647 \begin_inset Flex CharStyle:Code
10650 \begin_layout Plain Layout
10659 \begin_layout Description
10660 \begin_inset Flex CharStyle:Code
10663 \begin_layout Plain Layout
10670 \begin_inset CommandInset label
10672 name "des:LatexParam"
10676 An optional parameter for the corresponding
10677 \begin_inset Flex CharStyle:Code
10680 \begin_layout Plain Layout
10687 This parameter cannot be changed from within LyX.
10690 \begin_layout Description
10691 \begin_inset Flex CharStyle:Code
10694 \begin_layout Plain Layout
10701 \begin_inset CommandInset label
10703 name "des:LatexType"
10708 \begin_inset Flex CharStyle:Code
10711 \begin_layout Plain Layout
10716 , Command, Environment, Item_Environment,
10722 \begin_inset Flex CharStyle:Code
10725 \begin_layout Plain Layout
10731 ] How the layout should be translated into LaTeX.
10733 \begin_inset Flex CharStyle:Code
10736 \begin_layout Plain Layout
10742 means nothing special.
10744 \begin_inset Flex CharStyle:Code
10747 \begin_layout Plain Layout
10754 \begin_inset Flex CharStyle:Code
10757 \begin_layout Plain Layout
10764 {\SpecialChar \ldots{}
10771 \begin_inset Flex CharStyle:Code
10774 \begin_layout Plain Layout
10781 \begin_inset Flex CharStyle:Code
10784 \begin_layout Plain Layout
10791 }\SpecialChar \ldots{}
10805 \begin_inset Flex CharStyle:Code
10808 \begin_layout Plain Layout
10815 \begin_inset Flex CharStyle:Code
10818 \begin_layout Plain Layout
10825 \begin_inset Flex CharStyle:Code
10828 \begin_layout Plain Layout
10836 is generated for each paragraph of this environment.
10838 \begin_inset Flex CharStyle:Code
10841 \begin_layout Plain Layout
10848 \begin_inset Flex CharStyle:Code
10851 \begin_layout Plain Layout
10858 \begin_inset Flex CharStyle:Code
10861 \begin_layout Plain Layout
10867 is passed as an argument to the environment.
10869 \begin_inset Flex CharStyle:Code
10872 \begin_layout Plain Layout
10878 can be defined in the
10879 \begin_inset Flex CharStyle:MenuItem
10882 \begin_layout Plain Layout
10887 ayout\SpecialChar \menuseparator
10899 \begin_inset Flex CharStyle:Code
10902 \begin_layout Plain Layout
10910 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10911 Visit the SGML class files for specific examples.
10914 \begin_layout Standard
10915 Putting the last few things together, the LaTeX output will be either:
10918 \begin_layout LyX-Code
10921 latexname[latexparam]{\SpecialChar \ldots{}
10925 \begin_layout Standard
10929 \begin_layout LyX-Code
10932 begin{latexname}[latexparam] \SpecialChar \ldots{}
10938 \begin_layout Standard
10939 depending upon the LaTex type.
10942 \begin_layout Description
10943 \begin_inset Flex CharStyle:Code
10946 \begin_layout Plain Layout
10953 \begin_inset Flex CharStyle:Code
10956 \begin_layout Plain Layout
10962 ] If you put layouts into environments, the leftmargins are not simply added,
10963 but added with a factor
10964 \begin_inset Formula $\frac{4}{depth+4}$
10968 Note that this parameter is also used when the margin is defined as
10969 \begin_inset Flex CharStyle:Code
10972 \begin_layout Plain Layout
10979 \begin_inset Flex CharStyle:Code
10982 \begin_layout Plain Layout
10989 Then it is added to the manual or dynamic margin.
10991 \begin_inset Newline newline
10994 The argument is passed as a string.
10996 \begin_inset Quotes eld
11000 \begin_inset Flex CharStyle:Code
11003 \begin_layout Plain Layout
11010 \begin_inset Quotes erd
11013 means that the paragraph is indented with the width of
11014 \begin_inset Quotes eld
11018 \begin_inset Flex CharStyle:Code
11021 \begin_layout Plain Layout
11028 \begin_inset Quotes erd
11031 in the normal font.
11032 You can get a negative width by prefixing the string with
11033 \begin_inset Quotes eld
11037 \begin_inset Flex CharStyle:Code
11040 \begin_layout Plain Layout
11047 \begin_inset Quotes erd
11051 This way was chosen so that the look is the same with each used screen
11056 \begin_layout Description
11057 \begin_inset Flex CharStyle:Code
11060 \begin_layout Plain Layout
11067 \begin_inset Flex CharStyle:Code
11070 \begin_layout Plain Layout
11075 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11081 \begin_inset Newline newline
11084 The kind of margin that the layout has on the left side.
11086 \begin_inset Flex CharStyle:Code
11089 \begin_layout Plain Layout
11095 just means a fixed margin.
11097 \begin_inset Flex CharStyle:Code
11100 \begin_layout Plain Layout
11106 means that the left margin depends on the string entered in the
11107 \begin_inset Flex CharStyle:MenuItem
11110 \begin_layout Plain Layout
11115 dit\SpecialChar \menuseparator
11121 \begin_inset space ~
11130 This is used to typeset nice lists without tabulators.
11132 \begin_inset Flex CharStyle:Code
11135 \begin_layout Plain Layout
11141 means that the margin depends on the size of the label.
11142 This is used for automatic enumerated headlines.
11143 It is obvious that the headline
11144 \begin_inset Quotes eld
11147 5.4.3.2.1 Very long headline
11148 \begin_inset Quotes erd
11151 must have a wider left margin (as wide as
11152 \begin_inset Quotes eld
11156 \begin_inset Quotes erd
11159 plus the space) than
11160 \begin_inset Quotes eld
11163 3.2 Very long headline
11164 \begin_inset Quotes erd
11168 \begin_inset Quotes eld
11172 \begin_inset Quotes erd
11175 are not able to do this.
11177 \begin_inset Flex CharStyle:Code
11180 \begin_layout Plain Layout
11186 is similar, but only the very first row of the paragraph is dynamic, while
11187 the others are static; this is used, for example, for descriptions.
11189 \begin_inset Flex CharStyle:Code
11192 \begin_layout Plain Layout
11198 means the margin is chosen in a way that the longest row of this paragraph
11199 fits to the right margin.
11200 This is used to typeset an address on the right edge of the page.
11203 \begin_layout Description
11204 \begin_inset Flex CharStyle:Code
11207 \begin_layout Plain Layout
11214 \begin_inset CommandInset label
11216 name "des:NeedProtect"
11221 \begin_inset Flex CharStyle:Code
11224 \begin_layout Plain Layout
11233 \begin_inset Flex CharStyle:Code
11236 \begin_layout Plain Layout
11242 ] Whether fragile commands in this layout should be
11243 \begin_inset Flex CharStyle:Code
11246 \begin_layout Plain Layout
11257 \begin_layout Description
11258 \begin_inset Flex CharStyle:Code
11261 \begin_layout Plain Layout
11268 \begin_inset Flex CharStyle:Code
11271 \begin_layout Plain Layout
11278 \begin_inset Flex CharStyle:Code
11281 \begin_layout Plain Layout
11289 ] Whether newlines are translated into LaTeX newlines (
11290 \begin_inset Flex CharStyle:Code
11293 \begin_layout Plain Layout
11304 The translation can be switched off to allow more comfortable LaTeX editing
11308 \begin_layout Description
11309 \begin_inset Flex CharStyle:Code
11312 \begin_layout Plain Layout
11319 \begin_inset Flex CharStyle:Code
11322 \begin_layout Plain Layout
11329 \begin_inset Flex CharStyle:Code
11332 \begin_layout Plain Layout
11340 ] Whether the following Paragraph is allowed to indent its very first row.
11342 \begin_inset Flex CharStyle:Code
11345 \begin_layout Plain Layout
11351 means that it is not allowed to do so;
11352 \begin_inset Flex CharStyle:Code
11355 \begin_layout Plain Layout
11361 means it could do so if it wants to.
11364 \begin_layout Description
11365 \begin_inset Flex CharStyle:Code
11368 \begin_layout Plain Layout
11377 \begin_layout Description
11378 \begin_inset Flex CharStyle:Code
11381 \begin_layout Plain Layout
11388 \begin_inset Flex CharStyle:Code
11391 \begin_layout Plain Layout
11397 ] The number of optional arguments that can be used with this layout.
11398 This is useful for things like section headings, and only makes sense with
11402 \begin_layout Description
11403 \begin_inset Flex CharStyle:Code
11406 \begin_layout Plain Layout
11413 \begin_inset Flex CharStyle:Code
11416 \begin_layout Plain Layout
11422 ] The indent of the very first line of a paragraph.
11424 \begin_inset Flex CharStyle:Code
11427 \begin_layout Plain Layout
11433 will be fixed for a certain layout.
11434 The exception is Standard layout, since the indentation of a Standard layout
11435 paragraph can be prohibited with
11436 \begin_inset Flex CharStyle:Code
11439 \begin_layout Plain Layout
11446 Also, Standard layout paragraphs inside environments use the
11447 \begin_inset Flex CharStyle:Code
11450 \begin_layout Plain Layout
11456 of the environment, not their native one.
11457 For example, Standard paragraphs inside an enumeration are not indented.
11460 \begin_layout Description
11461 \begin_inset Flex CharStyle:Code
11464 \begin_layout Plain Layout
11471 \begin_inset Flex CharStyle:Code
11474 \begin_layout Plain Layout
11480 ] The vertical space between two paragraphs of this layout.
11483 \begin_layout Description
11484 \begin_inset Flex CharStyle:Code
11487 \begin_layout Plain Layout
11494 \begin_inset Flex CharStyle:Code
11497 \begin_layout Plain Layout
11503 ] LyX allows the user to choose either
11504 \begin_inset Quotes eld
11508 \begin_inset Quotes erd
11512 \begin_inset Quotes eld
11516 \begin_inset Quotes erd
11519 to typeset a document.
11521 \begin_inset Quotes eld
11525 \begin_inset Quotes erd
11528 is chosen, this value is completely ignored.
11530 \begin_inset Quotes eld
11534 \begin_inset Quotes erd
11537 is chosen, the parindent of a LaTeXtype
11538 \begin_inset Quotes eld
11542 \begin_inset Quotes erd
11545 layout is ignored and all paragraphs are separated by this parskip argument.
11546 The vertical space is calculated with
11547 \begin_inset Flex CharStyle:Code
11550 \begin_layout Plain Layout
11552 \begin_inset space ~
11561 \begin_inset Flex CharStyle:Code
11564 \begin_layout Plain Layout
11570 is the height of a row with the normal font.
11571 This way, the look stays the same with different screen fonts.
11574 \begin_layout Description
11575 \begin_inset Flex CharStyle:Code
11578 \begin_layout Plain Layout
11585 \begin_inset CommandInset label
11587 name "des:PassThru"
11594 \begin_inset Flex CharStyle:Code
11597 \begin_layout Plain Layout
11608 \begin_inset Flex CharStyle:Code
11611 \begin_layout Plain Layout
11617 ] Whether the contents of this paragraph should be output in raw form, meaning
11618 without special translations that LaTeX would require.
11621 \begin_layout Description
11622 \begin_inset Flex CharStyle:Code
11625 \begin_layout Plain Layout
11632 \begin_inset CommandInset label
11634 name "des:Preamble"
11638 Information to be included in the LaTeX preamable when this style is used.
11639 Used to define macros, load packages, etc., required by this particular
11642 \begin_inset Quotes eld
11646 \begin_inset Flex CharStyle:Code
11649 \begin_layout Plain Layout
11656 \begin_inset Quotes erd
11662 \begin_layout Description
11663 \begin_inset Flex CharStyle:Code
11666 \begin_layout Plain Layout
11673 \begin_inset Flex CharStyle:Code
11676 \begin_layout Plain Layout
11683 \begin_inset CommandInset label
11685 name "des:Requires"
11689 Whether the layout requires the feature
11690 \begin_inset Flex CharStyle:Code
11693 \begin_layout Plain Layout
11700 See the description of
11701 \begin_inset Flex CharStyle:Code
11704 \begin_layout Plain Layout
11711 \begin_inset CommandInset ref
11712 LatexCommand pageref
11713 reference "des:FreeSpacing"
11717 ) for information on `features'.
11721 \begin_layout Description
11722 \begin_inset Flex CharStyle:Code
11725 \begin_layout Plain Layout
11732 \begin_inset Flex CharStyle:Code
11735 \begin_layout Plain Layout
11742 \begin_inset Flex CharStyle:Code
11745 \begin_layout Plain Layout
11754 \begin_layout Description
11755 \begin_inset Flex CharStyle:Code
11758 \begin_layout Plain Layout
11765 \begin_inset Flex CharStyle:Code
11768 \begin_layout Plain Layout
11773 , onehalf, double, other
11782 ] This defines what the default spacing should be in the layout.
11784 \begin_inset Flex CharStyle:Code
11787 \begin_layout Plain Layout
11794 \begin_inset Flex CharStyle:Code
11797 \begin_layout Plain Layout
11804 \begin_inset Flex CharStyle:Code
11807 \begin_layout Plain Layout
11813 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11814 If you specify the argument
11815 \begin_inset Flex CharStyle:Code
11818 \begin_layout Plain Layout
11824 , then you should also provide a numerical argument which will be the actual
11826 Note that, contrary to other parameters,
11827 \begin_inset Flex CharStyle:Code
11830 \begin_layout Plain Layout
11836 implies the generation of specific LaTeX code, using the package
11839 \begin_inset Flex CharStyle:Code
11842 \begin_layout Plain Layout
11851 \begin_layout Description
11852 \begin_inset Flex CharStyle:Code
11855 \begin_layout Plain Layout
11861 The font used for the text body .
11863 \begin_inset CommandInset ref
11865 reference "sec:fonts"
11872 \begin_layout Description
11873 \begin_inset Flex CharStyle:Code
11876 \begin_layout Plain Layout
11884 The level of the style in the table of contents.
11885 This is used for automatic numbering of section headings.
11888 \begin_layout Description
11889 \begin_inset Flex CharStyle:Code
11892 \begin_layout Plain Layout
11899 \begin_inset Flex CharStyle:Code
11902 \begin_layout Plain Layout
11908 ] The vertical space with which the very first of a chain of paragraphs
11909 with this layout is separated from the previous paragraph.
11910 If the previous paragraph has another layout, the separations are not simply
11911 added, but the maximum is taken.
11914 \begin_layout Subsection
11918 \begin_layout Standard
11919 \begin_inset CommandInset label
11925 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11926 define the floats (
11927 \begin_inset Flex CharStyle:MenuItem
11930 \begin_layout Plain Layout
11937 \begin_inset Flex CharStyle:MenuItem
11940 \begin_layout Plain Layout
11946 , \SpecialChar \ldots{}
11947 ) in the text class itself.
11948 Standard floats are included in the file
11949 \begin_inset Flex CharStyle:Code
11952 \begin_layout Plain Layout
11958 , so you may have to do no more than add
11961 \begin_layout LyX-Code
11962 Input stdfloats.inc
11965 \begin_layout Standard
11966 to your layout file.
11967 If you want to implement a text class that proposes some other float types
11968 (like the AGU class bundled with LyX), the information below will hopefully
11972 \begin_layout Description
11973 \begin_inset Flex CharStyle:Code
11976 \begin_layout Plain Layout
11983 \begin_inset Flex CharStyle:Code
11986 \begin_layout Plain Layout
11993 \begin_inset Quotes erd
11997 \begin_inset Quotes erd
12000 ] The file name extension of an auxiliary file for the list of figures (or
12002 LaTeX writes the captions to this file.
12005 \begin_layout Description
12006 \begin_inset Flex CharStyle:Code
12009 \begin_layout Plain Layout
12016 \begin_inset Flex CharStyle:Code
12019 \begin_layout Plain Layout
12026 \begin_inset Quotes erd
12030 \begin_inset Quotes erd
12033 ] The string that will be used in the menus and also for the caption.
12036 \begin_layout Description
12037 \begin_inset Flex CharStyle:Code
12040 \begin_layout Plain Layout
12047 \begin_inset Flex CharStyle:Code
12050 \begin_layout Plain Layout
12059 \begin_inset Flex CharStyle:Code
12062 \begin_layout Plain Layout
12069 \begin_inset Flex CharStyle:Code
12072 \begin_layout Plain Layout
12078 if the float is already defined by the LaTeX document class.
12080 \begin_inset Flex CharStyle:Code
12083 \begin_layout Plain Layout
12089 , the float will be defined using the LaTeX package
12090 \begin_inset Flex CharStyle:Code
12093 \begin_layout Plain Layout
12102 \begin_layout Description
12103 \begin_inset Flex CharStyle:Code
12106 \begin_layout Plain Layout
12113 \begin_inset Flex CharStyle:Code
12116 \begin_layout Plain Layout
12123 \begin_inset Quotes erd
12127 \begin_inset Quotes erd
12130 ] The heading used for the list of floats.
12133 \begin_layout Description
12134 \begin_inset Flex CharStyle:Code
12137 \begin_layout Plain Layout
12144 \begin_inset Flex CharStyle:Code
12147 \begin_layout Plain Layout
12154 \begin_inset Quotes erd
12158 \begin_inset Quotes erd
12161 ] This (optional) argument determines whether floats of this class will
12162 be numbered within some sectional unit of the document.
12163 For example, if within is equal to
12164 \begin_inset Flex CharStyle:Code
12167 \begin_layout Plain Layout
12173 , the floats will be numbered within chapters.
12177 \begin_layout Description
12178 \begin_inset Flex CharStyle:Code
12181 \begin_layout Plain Layout
12188 \begin_inset Flex CharStyle:Code
12191 \begin_layout Plain Layout
12198 \begin_inset Quotes erd
12202 \begin_inset Quotes erd
12205 ] The default placement for the given class of floats.
12206 The string should be as in standard LaTeX:
12207 \begin_inset Flex CharStyle:Code
12210 \begin_layout Plain Layout
12217 \begin_inset Flex CharStyle:Code
12220 \begin_layout Plain Layout
12227 \begin_inset Flex CharStyle:Code
12230 \begin_layout Plain Layout
12237 \begin_inset Flex CharStyle:Code
12240 \begin_layout Plain Layout
12246 for top, bottom, page, and here, respectively.
12250 \begin_layout Plain Layout
12251 Note that the order of these letters in the string is irrelevant, like in
12257 On top of that there is a new type,
12258 \begin_inset Flex CharStyle:Code
12261 \begin_layout Plain Layout
12267 , which does not really correspond to a float, since it means: put it
12268 \begin_inset Quotes eld
12272 \begin_inset Quotes erd
12276 Note however that the
12277 \begin_inset Flex CharStyle:Code
12280 \begin_layout Plain Layout
12286 specifier is special and, because of implementation details, cannot be
12287 used in non-builtin float types.
12288 If you do not understand what this means, just use
12289 \begin_inset Quotes eld
12293 \begin_inset Flex CharStyle:Code
12296 \begin_layout Plain Layout
12303 \begin_inset Quotes erd
12309 \begin_layout Description
12310 \begin_inset Flex CharStyle:Code
12313 \begin_layout Plain Layout
12320 \begin_inset Flex CharStyle:Code
12323 \begin_layout Plain Layout
12330 \begin_inset Quotes erd
12334 \begin_inset Quotes erd
12337 ] The style used when defining the float using
12338 \begin_inset Flex CharStyle:Code
12341 \begin_layout Plain Layout
12352 \begin_layout Description
12353 \begin_inset Flex CharStyle:Code
12356 \begin_layout Plain Layout
12363 \begin_inset Flex CharStyle:Code
12366 \begin_layout Plain Layout
12373 \begin_inset Quotes erd
12377 \begin_inset Quotes erd
12381 \begin_inset Quotes eld
12385 \begin_inset Quotes erd
12388 of the new class of floats, like program or algorithm.
12389 After the appropriate
12390 \begin_inset Flex CharStyle:Code
12393 \begin_layout Plain Layout
12402 \begin_inset Flex CharStyle:Code
12405 \begin_layout Plain Layout
12414 \begin_inset Flex CharStyle:Code
12417 \begin_layout Plain Layout
12428 \begin_layout Standard
12429 Note that defining a float with type
12430 \begin_inset Flex CharStyle:Code
12433 \begin_layout Plain Layout
12441 automatically defines the corresponding counter with name
12442 \begin_inset Flex CharStyle:Code
12445 \begin_layout Plain Layout
12456 \begin_layout Subsection
12457 Inset layouts and Flex insets
12460 \begin_layout Standard
12461 \begin_inset CommandInset label
12463 name "sec:charstyle"
12467 LyX has supported character styles since version 1.4.0; since version 1.6.0
12468 these are called Flex insets.
12472 \begin_layout Standard
12473 Furthermore, it is possible to define the general layout of many different
12475 Currently, InsetLayout can be used to customize the layout parameters
12476 for footnotes, marginal notes, note insets, ERT insets, branches, listings,
12477 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
12482 \begin_layout Standard
12483 Flex insets come in three different kinds:
12486 \begin_layout Itemize
12488 \begin_inset Flex CharStyle:Code
12491 \begin_layout Plain Layout
12497 ): These define semantic markup corresponding to such LaTeX commands as
12499 \begin_inset Flex CharStyle:Code
12502 \begin_layout Plain Layout
12511 \begin_inset Flex CharStyle:Code
12514 \begin_layout Plain Layout
12525 \begin_layout Itemize
12527 \begin_inset Flex CharStyle:Code
12530 \begin_layout Plain Layout
12536 ): These can be used to define custom collapsable insets, similar to ERT,
12537 footnote, and the like.
12540 \begin_layout Itemize
12542 \begin_inset Flex CharStyle:Code
12545 \begin_layout Plain Layout
12551 ): For use with DocBook classes.
12554 \begin_layout Standard
12556 \begin_inset Flex CharStyle:Code
12559 \begin_layout Plain Layout
12565 definition starting line is of the form
12568 \begin_layout LyX-Code
12569 InsetLayout <Type> <Name>
12572 \begin_layout Standard
12574 \begin_inset Flex CharStyle:Code
12577 \begin_layout Plain Layout
12584 \begin_inset Flex CharStyle:Code
12587 \begin_layout Plain Layout
12594 \begin_inset Flex CharStyle:Code
12597 \begin_layout Plain Layout
12604 \begin_inset Flex CharStyle:Code
12607 \begin_layout Plain Layout
12614 \begin_inset Flex CharStyle:Code
12617 \begin_layout Plain Layout
12624 \begin_inset Flex CharStyle:Code
12627 \begin_layout Plain Layout
12634 \begin_inset Flex CharStyle:Code
12637 \begin_layout Plain Layout
12644 \begin_inset Flex CharStyle:Code
12647 \begin_layout Plain Layout
12654 \begin_inset Flex CharStyle:Code
12657 \begin_layout Plain Layout
12664 \begin_inset Flex CharStyle:Code
12667 \begin_layout Plain Layout
12674 \begin_inset Flex CharStyle:Code
12677 \begin_layout Plain Layout
12684 \begin_inset Flex CharStyle:Code
12687 \begin_layout Plain Layout
12694 \begin_inset Flex CharStyle:Code
12697 \begin_layout Plain Layout
12704 \begin_inset Flex CharStyle:Code
12707 \begin_layout Plain Layout
12714 \begin_inset Flex CharStyle:Code
12717 \begin_layout Plain Layout
12724 \begin_inset Flex CharStyle:Code
12727 \begin_layout Plain Layout
12734 \begin_inset Flex CharStyle:Code
12737 \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
12774 should have the form
12775 \begin_inset Flex CharStyle:Code
12778 \begin_layout Plain Layout
12785 \begin_inset Flex CharStyle:Code
12788 \begin_layout Plain Layout
12795 \begin_inset Flex CharStyle:Code
12798 \begin_layout Plain Layout
12805 \begin_inset Flex CharStyle:Code
12808 \begin_layout Plain Layout
12815 \begin_inset Flex CharStyle:Code
12818 \begin_layout Plain Layout
12825 \begin_inset Flex CharStyle:Code
12828 \begin_layout Plain Layout
12834 is any valid identifier.
12838 \begin_layout Standard
12840 \begin_inset Flex CharStyle:Code
12843 \begin_layout Plain Layout
12849 section can contain the following entries:
12852 \begin_layout Description
12853 \begin_inset Flex CharStyle:Code
12856 \begin_layout Plain Layout
12862 The color for the inset's background.
12863 These valid colors are defined in
12864 \begin_inset Flex CharStyle:Code
12867 \begin_layout Plain Layout
12876 \begin_layout Description
12877 \begin_inset Flex CharStyle:Code
12880 \begin_layout Plain Layout
12887 \begin_inset Flex CharStyle:Code
12890 \begin_layout Plain Layout
12897 \begin_inset Flex CharStyle:Code
12900 \begin_layout Plain Layout
12907 \begin_inset Flex CharStyle:Code
12910 \begin_layout Plain Layout
12916 , describing the rendering style used for the inset's frame and buttons.
12917 Footnotes generally use
12918 \begin_inset Flex CharStyle:Code
12921 \begin_layout Plain Layout
12927 ; ERT insets generally use
12928 \begin_inset Flex CharStyle:Code
12931 \begin_layout Plain Layout
12937 ; and character styles use
12938 \begin_inset Flex CharStyle:Code
12941 \begin_layout Plain Layout
12950 \begin_layout Description
12951 \begin_inset Flex CharStyle:Code
12954 \begin_layout Plain Layout
12960 The font used for both the text body
12966 \begin_inset space ~
12970 \begin_inset CommandInset ref
12972 reference "sec:fonts"
12977 Note that defining this font automatically defines the
12978 \begin_inset Flex CharStyle:Code
12981 \begin_layout Plain Layout
12987 to the same value, so define this first and define
12988 \begin_inset Flex CharStyle:Code
12991 \begin_layout Plain Layout
12997 later if you want them to be different.
13000 \begin_layout Description
13001 \begin_inset Flex CharStyle:Code
13004 \begin_layout Plain Layout
13013 \begin_layout Description
13014 \begin_inset Flex CharStyle:Code
13017 \begin_layout Plain Layout
13023 As with paragraph styles (see page
13024 \begin_inset CommandInset ref
13025 LatexCommand pageref
13026 reference "des:FreeSpacing"
13033 \begin_layout Description
13034 \begin_inset Flex CharStyle:Code
13037 \begin_layout Plain Layout
13043 As with paragraph styles (see page
13044 \begin_inset CommandInset ref
13045 LatexCommand pageref
13046 reference "des:KeepEmpty"
13053 \begin_layout Description
13054 \begin_inset Flex CharStyle:Code
13057 \begin_layout Plain Layout
13063 What will be displayed on the button or elsewhere as the inset label.
13064 Some inset types (ERT and Branch) modify this label on the fly.
13067 \begin_layout Description
13068 \begin_inset Flex CharStyle:Code
13071 \begin_layout Plain Layout
13077 The font used for the label.
13079 \begin_inset space ~
13083 \begin_inset CommandInset ref
13085 reference "sec:fonts"
13090 Note that this definition can never appear before
13091 \begin_inset Flex CharStyle:Code
13094 \begin_layout Plain Layout
13100 , lest it be ineffective.
13103 \begin_layout Description
13104 \begin_inset Flex CharStyle:Code
13107 \begin_layout Plain Layout
13113 The name of the corresponding LaTeX stuff.
13114 Either the environment or command name.
13117 \begin_layout Description
13118 \begin_inset Flex CharStyle:Code
13121 \begin_layout Plain Layout
13127 The optional parameter for the corresponding
13128 \begin_inset Flex CharStyle:Code
13131 \begin_layout Plain Layout
13137 stuff, including possible bracket pairs like
13138 \begin_inset Flex CharStyle:Code
13141 \begin_layout Plain Layout
13148 This parameter cannot be changed from within LyX.
13151 \begin_layout Description
13152 \begin_inset Flex CharStyle:Code
13155 \begin_layout Plain Layout
13161 As with paragraph styles (see page
13162 \begin_inset CommandInset ref
13163 LatexCommand pageref
13164 reference "des:LatexType"
13171 \begin_layout Description
13172 \begin_inset Flex CharStyle:Code
13175 \begin_layout Plain Layout
13182 \begin_inset Flex CharStyle:Code
13185 \begin_layout Plain Layout
13192 \begin_inset Flex CharStyle:Code
13195 \begin_layout Plain Layout
13202 \begin_inset Flex CharStyle:Code
13205 \begin_layout Plain Layout
13212 \begin_inset Flex CharStyle:Code
13215 \begin_layout Plain Layout
13221 (indicating a dummy definition ending definitions of charstyles etc.).
13222 This entry is only meaningful for Flex (user definable) insets.
13225 \begin_layout Description
13226 \begin_inset Flex CharStyle:Code
13229 \begin_layout Plain Layout
13235 As with paragraph styles (see page
13236 \begin_inset CommandInset ref
13237 LatexCommand pageref
13238 reference "des:Preamble"
13245 \begin_layout Description
13246 \begin_inset Flex CharStyle:Code
13249 \begin_layout Plain Layout
13256 \begin_inset Flex CharStyle:Code
13259 \begin_layout Plain Layout
13265 ] As with paragraph styles (see page
13266 \begin_inset CommandInset ref
13267 LatexCommand pageref
13268 reference "des:Requires"
13275 \begin_layout Subsection
13279 \begin_layout Standard
13280 \begin_inset CommandInset label
13286 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13288 \begin_inset Flex CharStyle:MenuItem
13291 \begin_layout Plain Layout
13298 \begin_inset Flex CharStyle:MenuItem
13301 \begin_layout Plain Layout
13307 , \SpecialChar \ldots{}
13308 ) in the text class itself.
13309 The standard counters are defined in the file
13310 \begin_inset Flex CharStyle:Code
13313 \begin_layout Plain Layout
13319 , so you may have to do no more than add
13322 \begin_layout LyX-Code
13323 Input stdcounters.inc
13326 \begin_layout Standard
13327 to your layout file to get them to work.
13328 But if you want to define custom counters, then you can do so, using the
13329 following parameters:
13332 \begin_layout Description
13333 \begin_inset Flex CharStyle:Code
13336 \begin_layout Plain Layout
13337 LabelString [string=""]
13342 when this is defined, this string defines how the counter is displayed.
13343 Setting this value sets
13344 \begin_inset Flex CharStyle:Code
13347 \begin_layout Plain Layout
13348 LabelStringAppendix
13354 The following special constructs can be used in the string:
13358 \begin_layout Itemize
13359 \begin_inset Flex CharStyle:Code
13362 \begin_layout Plain Layout
13370 will be replaced by the expansion of the
13371 \begin_inset Flex CharStyle:Code
13374 \begin_layout Plain Layout
13381 \begin_inset Flex CharStyle:Code
13384 \begin_layout Plain Layout
13385 LabelStringAppendix
13391 \begin_inset Flex CharStyle:Code
13394 \begin_layout Plain Layout
13404 \begin_layout Itemize
13405 counter values can be expressed using LaTeX-like macros
13406 \begin_inset Flex CharStyle:Code
13409 \begin_layout Plain Layout
13426 \begin_inset Flex CharStyle:Code
13429 \begin_layout Plain Layout
13441 \begin_layout Plain Layout
13451 Actually, the situation is a bit more complicated: any
13470 other than those descibed below will produce arabic numerals.
13471 It would not be surprising to see this change in the future.
13477 \begin_inset Flex CharStyle:Code
13480 \begin_layout Plain Layout
13486 : 1, 2, 3,\SpecialChar \ldots{}
13488 \begin_inset Flex CharStyle:Code
13491 \begin_layout Plain Layout
13497 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13499 \begin_inset Flex CharStyle:Code
13502 \begin_layout Plain Layout
13508 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13510 \begin_inset Flex CharStyle:Code
13513 \begin_layout Plain Layout
13519 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13521 \begin_inset Flex CharStyle:Code
13524 \begin_layout Plain Layout
13530 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13532 \begin_inset Flex CharStyle:Code
13535 \begin_layout Plain Layout
13541 for hebrew numerals.
13545 \begin_layout Standard
13546 If LabelString is not defined, a default value is constructed as follows:
13547 if the counter has a master counter
13548 \begin_inset Flex CharStyle:Code
13551 \begin_layout Plain Layout
13558 \begin_inset Flex CharStyle:Code
13561 \begin_layout Plain Layout
13568 \begin_inset Flex CharStyle:Code
13571 \begin_layout Plain Layout
13581 is used; otherwise the string
13582 \begin_inset Flex CharStyle:Code
13585 \begin_layout Plain Layout
13596 \begin_layout Description
13597 \begin_inset Flex CharStyle:Code
13600 \begin_layout Plain Layout
13601 LabelStringAppendix [string=""]
13607 \begin_inset Flex CharStyle:Code
13610 \begin_layout Plain Layout
13619 \begin_layout Description
13620 \begin_inset Flex CharStyle:Code
13623 \begin_layout Plain Layout
13630 \begin_inset Flex CharStyle:Code
13633 \begin_layout Plain Layout
13640 \begin_inset Quotes erd
13644 \begin_inset Quotes erd
13647 ] The name of the counter.
13650 \begin_layout Description
13651 \begin_inset Flex CharStyle:Code
13654 \begin_layout Plain Layout
13661 \begin_inset Flex CharStyle:Code
13664 \begin_layout Plain Layout
13671 \begin_inset Quotes erd
13675 \begin_inset Quotes erd
13678 ] If this is set to the name of another counter, the present counter will
13679 be reset everytime the other one is increased.
13681 \begin_inset Flex CharStyle:Code
13684 \begin_layout Plain Layout
13691 \begin_inset Flex CharStyle:Code
13694 \begin_layout Plain Layout
13703 \begin_layout Subsection
13707 \begin_layout Standard
13708 \begin_inset CommandInset label
13714 A font description looks like this:
13717 \begin_layout LyX-Code
13727 \begin_layout LyX-Code
13731 \begin_layout LyX-Code
13735 \begin_layout Standard
13736 The following commands are available:
13739 \begin_layout Description
13740 \begin_inset Flex CharStyle:Code
13743 \begin_layout Plain Layout
13750 \begin_inset Flex CharStyle:Code
13753 \begin_layout Plain Layout
13762 \begin_inset Flex CharStyle:Code
13765 \begin_layout Plain Layout
13772 \begin_inset Flex CharStyle:Code
13775 \begin_layout Plain Layout
13782 \begin_inset Flex CharStyle:Code
13785 \begin_layout Plain Layout
13792 \begin_inset Flex CharStyle:Code
13795 \begin_layout Plain Layout
13802 \begin_inset Flex CharStyle:Code
13805 \begin_layout Plain Layout
13812 \begin_inset Flex CharStyle:Code
13815 \begin_layout Plain Layout
13822 \begin_inset Flex CharStyle:Code
13825 \begin_layout Plain Layout
13832 \begin_inset Flex CharStyle:Code
13835 \begin_layout Plain Layout
13844 \begin_layout Description
13845 \begin_inset Flex CharStyle:Code
13848 \begin_layout Plain Layout
13857 \begin_inset Flex CharStyle:Code
13860 \begin_layout Plain Layout
13871 \begin_inset Flex CharStyle:Code
13874 \begin_layout Plain Layout
13881 \begin_inset Flex CharStyle:Code
13884 \begin_layout Plain Layout
13893 \begin_layout Description
13894 \begin_inset Flex CharStyle:Code
13897 \begin_layout Plain Layout
13904 \begin_inset Flex CharStyle:Code
13907 \begin_layout Plain Layout
13913 ] Valid argument sare:
13914 \begin_inset Flex CharStyle:Code
13917 \begin_layout Plain Layout
13924 \begin_inset Flex CharStyle:Code
13927 \begin_layout Plain Layout
13934 \begin_inset Flex CharStyle:Code
13937 \begin_layout Plain Layout
13944 \begin_inset Flex CharStyle:Code
13947 \begin_layout Plain Layout
13954 \begin_inset Flex CharStyle:Code
13957 \begin_layout Plain Layout
13964 \begin_inset Flex CharStyle:Code
13967 \begin_layout Plain Layout
13974 Each of these turns on or off the corresponding attribute.
13977 \begin_layout Description
13978 \begin_inset Flex CharStyle:Code
13981 \begin_layout Plain Layout
13990 \begin_inset Flex CharStyle:Code
13993 \begin_layout Plain Layout
14004 \begin_inset Flex CharStyle:Code
14007 \begin_layout Plain Layout
14016 \begin_layout Description
14017 \begin_inset Flex CharStyle:Code
14020 \begin_layout Plain Layout
14029 \begin_inset Flex CharStyle:Code
14032 \begin_layout Plain Layout
14043 \begin_inset Flex CharStyle:Code
14046 \begin_layout Plain Layout
14053 \begin_inset Flex CharStyle:Code
14056 \begin_layout Plain Layout
14063 \begin_inset Flex CharStyle:Code
14066 \begin_layout Plain Layout
14075 \begin_layout Description
14076 \begin_inset Flex CharStyle:Code
14079 \begin_layout Plain Layout
14086 \begin_inset Flex CharStyle:Code
14089 \begin_layout Plain Layout
14096 \begin_inset Flex CharStyle:Code
14099 \begin_layout Plain Layout
14106 \begin_inset Flex CharStyle:Code
14109 \begin_layout Plain Layout
14118 \begin_inset Flex CharStyle:Code
14121 \begin_layout Plain Layout
14128 \begin_inset Flex CharStyle:Code
14131 \begin_layout Plain Layout
14138 \begin_inset Flex CharStyle:Code
14141 \begin_layout Plain Layout
14148 \begin_inset Flex CharStyle:Code
14151 \begin_layout Plain Layout
14158 \begin_inset Flex CharStyle:Code
14161 \begin_layout Plain Layout
14170 \begin_layout Subsection
14171 Upgrading old layout files
14174 \begin_layout Standard
14175 The file format of layout files changes from time to time, so old layout
14176 files need to be converted.
14177 This process has been automated since LyX 1.4.0: If LyX reads an old format
14178 layout file it will call the conversion tool
14179 \begin_inset Flex CharStyle:Code
14182 \begin_layout Plain Layout
14183 LyXDir/scripts/layout2layout.py
14188 and convert it to a temporary file in current format.
14189 The original file is left untouched.
14190 If you want to convert the layout file permanently, just call the converter
14194 \begin_layout LyX-Code
14195 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
14198 \begin_layout Standard
14199 (You need to replace
14200 \begin_inset Flex CharStyle:Code
14203 \begin_layout Plain Layout
14209 with the name of your LyX system directory, unless you happen to have defined
14210 such an environment variable.) Then copy
14211 \begin_inset Flex CharStyle:Code
14214 \begin_layout Plain Layout
14221 \begin_inset Flex CharStyle:Code
14224 \begin_layout Plain Layout
14233 \begin_layout Standard
14234 The automatic conversion only handles syntax changes.
14235 It cannot handle the case where the contents of included files was changed,
14236 so these will have to be converted separately.
14239 \begin_layout Section
14241 \begin_inset CommandInset label
14243 name "sec:templates"
14250 \begin_layout Standard
14251 Templates are created just like usual documents.
14252 The only difference is that usual documents contain all possible settings,
14253 including the font scheme and the paper size.
14254 Usually a user doesn't want a template to overwrite his defaults in these
14256 For that reason, the designer of a template should remove the corresponding
14258 \begin_inset Flex CharStyle:Code
14261 \begin_layout Plain Layout
14270 \begin_inset Flex CharStyle:Code
14273 \begin_layout Plain Layout
14281 from the template LyX file.
14282 This can be done with any simple text-editor, for example
14283 \begin_inset Flex CharStyle:Code
14286 \begin_layout Plain Layout
14293 \begin_inset Flex CharStyle:Code
14296 \begin_layout Plain Layout
14306 \begin_layout Standard
14307 Put the edited template files you create in
14308 \begin_inset Flex CharStyle:Code
14311 \begin_layout Plain Layout
14317 , copy the ones you use from the global template directory in
14318 \begin_inset Flex CharStyle:Code
14321 \begin_layout Plain Layout
14327 to the same place, and redefine the template path in the
14328 \begin_inset Flex CharStyle:MenuItem
14331 \begin_layout Plain Layout
14339 \SpecialChar \menuseparator
14344 references\SpecialChar \menuseparator
14353 \begin_layout Standard
14354 Note that there is a template which has a particular meaning:
14355 \begin_inset Flex CharStyle:Code
14358 \begin_layout Plain Layout
14365 This template is loaded everytime you create a new document with
14366 \begin_inset Flex CharStyle:MenuItem
14369 \begin_layout Plain Layout
14379 \SpecialChar \menuseparator
14381 \begin_inset Flex CharStyle:MenuItem
14384 \begin_layout Plain Layout
14394 in order to provide useful defaults.
14395 To create this template from inside LyX, all you have to do is to open
14396 a document with the correct settings, and use the
14397 \begin_inset Flex CharStyle:MenuItem
14400 \begin_layout Plain Layout
14405 e as Document Defaults
14413 \begin_layout Chapter
14414 Including External Material
14417 \begin_layout Standard
14418 The use of material from sources external to LyX is covered in detail in
14424 This part of the manual covers what needs to happen behind the scenes for
14425 new sorts of material to be included.
14428 \begin_layout Section
14432 \begin_layout Standard
14433 The external material feature is based on the concept of a
14438 A template is a specification of how LyX should interface with a certain
14440 As bundled, LyX comes with predefined templates for Xfig figures, various
14441 raster format images, chess diagrams, and LilyPond music notation.
14442 You can check the actual list by using the menu
14443 \begin_inset Flex CharStyle:MenuItem
14446 \begin_layout Plain Layout
14447 Insert\SpecialChar \menuseparator
14448 File\SpecialChar \menuseparator
14455 Furthermore, it is possible to roll your own template to support a specific
14457 Later we'll describe in more detail what is involved, and hopefully you
14458 will submit all the templates you create so we can include them in a later
14462 \begin_layout Standard
14463 Another basic idea of the external material feature is to distinguish between
14464 the original file that serves as a base for final material and the produced
14465 file that is included in your exported or printed document.
14466 For example, consider the case of a figure produced with
14467 \begin_inset Flex CharStyle:Code
14470 \begin_layout Plain Layout
14477 The Xfig application itself works on an original file with the
14478 \begin_inset Flex CharStyle:Code
14481 \begin_layout Plain Layout
14488 Within XFig, you create and change your figure, and when you are done,
14490 \begin_inset Flex CharStyle:Code
14493 \begin_layout Plain Layout
14500 When you want to include the figure in your document, you invoke
14501 \begin_inset Flex CharStyle:Code
14504 \begin_layout Plain Layout
14510 in order to create a PostScript file that can readily be included in your
14513 \begin_inset Flex CharStyle:Code
14516 \begin_layout Plain Layout
14522 file is the original file, and the PostScript file is the produced file.
14525 \begin_layout Standard
14526 This distinction is important in order to allow updating of the material
14527 while you are in the process of writing the document.
14528 Furthermore, it provides us with the flexibility that is needed to support
14529 multiple export formats.
14530 For instance, in the case of a plain text file, it is not exactly an award-winn
14531 ing idea to include the figure as raw PostScript®.
14532 Instead, you'd either prefer to just include a reference to the figure
14533 or try to invoke some graphics to Ascii converter to make the final result
14534 look similar to the real graphics.
14535 The external material management allows you to do this, because it is parameter
14536 ized on the different export formats that LyX supports.
14539 \begin_layout Standard
14540 Besides supporting the production of different products according to the
14541 exported format, it supports tight integration with editing and viewing
14543 In the case of an XFig figure, you are able to invoke Xfig on the original
14544 file with a single click from within the external material dialog in LyX,
14545 and also preview the produced PostScript file with ghostview with another
14547 No more fiddling around with the command line and/or file browsers to locate
14548 and manipulate the original or produced files.
14549 In this way, you are finally able to take full advantage of the many different
14550 applications that are relevant to use when you write your documents, and
14551 ultimately be more productive.
14554 \begin_layout Section
14555 The external template configuration file
14558 \begin_layout Standard
14559 It is relatively easy to add custom external template definitions to LyX.
14560 However, be aware that doing this in an careless manner most probably
14564 introduce an easily exploitable security hole.
14565 So before you do this, please read the discussion about security in section
14567 \begin_inset CommandInset ref
14569 reference "sec:Security-discussion"
14576 \begin_layout Standard
14577 Having said that, we encourage you to submit any interesting templates that
14582 \begin_layout Standard
14583 The external templates are defined in the
14584 \begin_inset Flex CharStyle:Code
14587 \begin_layout Plain Layout
14588 LyXDir/lib/external_templates
14594 You can place your own version in
14595 \begin_inset Flex CharStyle:Code
14598 \begin_layout Plain Layout
14599 UserDir/external_templates
14607 \begin_layout Standard
14608 A typical template looks like this:
14611 \begin_layout LyX-Code
14615 \begin_layout LyX-Code
14616 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14619 \begin_layout LyX-Code
14623 \begin_layout LyX-Code
14627 \begin_layout LyX-Code
14631 \begin_layout LyX-Code
14635 \begin_layout LyX-Code
14639 \begin_layout LyX-Code
14640 AutomaticProduction true
14643 \begin_layout LyX-Code
14647 \begin_layout LyX-Code
14651 \begin_layout LyX-Code
14655 \begin_layout LyX-Code
14656 TransformCommand Rotate RotationLatexCommand
14659 \begin_layout LyX-Code
14660 TransformCommand Resize ResizeLatexCommand
14663 \begin_layout LyX-Code
14664 Product "$$RotateFront$$ResizeFront
14667 \begin_layout LyX-Code
14672 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14675 \begin_layout LyX-Code
14676 $$ResizeBack$$RotateBack"
14679 \begin_layout LyX-Code
14683 \begin_layout LyX-Code
14684 UpdateResult "$$AbsPath$$Basename.pstex_t"
14687 \begin_layout LyX-Code
14688 Requirement "graphicx"
14691 \begin_layout LyX-Code
14692 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14695 \begin_layout LyX-Code
14696 ReferencedFile latex "$$AbsPath$$Basename.eps"
14699 \begin_layout LyX-Code
14700 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14703 \begin_layout LyX-Code
14707 \begin_layout LyX-Code
14711 \begin_layout LyX-Code
14712 TransformCommand Rotate RotationLatexCommand
14715 \begin_layout LyX-Code
14716 TransformCommand Resize ResizeLatexCommand
14719 \begin_layout LyX-Code
14720 Product "$$RotateFront$$ResizeFront
14723 \begin_layout LyX-Code
14728 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14731 \begin_layout LyX-Code
14732 $$ResizeBack$$RotateBack"
14735 \begin_layout LyX-Code
14736 UpdateFormat pdftex
14739 \begin_layout LyX-Code
14740 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14743 \begin_layout LyX-Code
14744 Requirement "graphicx"
14747 \begin_layout LyX-Code
14748 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14751 \begin_layout LyX-Code
14752 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14755 \begin_layout LyX-Code
14759 \begin_layout LyX-Code
14763 \begin_layout LyX-Code
14764 Product "$$Contents(
14766 "$$AbsPath$$Basename.asc
14771 \begin_layout LyX-Code
14772 UpdateFormat asciixfig
14775 \begin_layout LyX-Code
14776 UpdateResult "$$AbsPath$$Basename.asc"
14779 \begin_layout LyX-Code
14783 \begin_layout LyX-Code
14787 \begin_layout LyX-Code
14788 Product "<graphic fileref=
14790 "$$AbsOrRelPathMaster$$Basename.eps
14795 \begin_layout LyX-Code
14799 \begin_layout LyX-Code
14803 \begin_layout LyX-Code
14804 UpdateResult "$$AbsPath$$Basename.eps"
14807 \begin_layout LyX-Code
14808 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14811 \begin_layout LyX-Code
14812 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14815 \begin_layout LyX-Code
14819 \begin_layout LyX-Code
14820 Product "[XFig: $$FName]"
14823 \begin_layout LyX-Code
14827 \begin_layout LyX-Code
14831 \begin_layout Standard
14832 As you can see, the template is enclosed in
14833 \begin_inset Flex CharStyle:Code
14836 \begin_layout Plain Layout
14842 \SpecialChar \ldots{}
14844 \begin_inset Flex CharStyle:Code
14847 \begin_layout Plain Layout
14854 It contains a header specifying some general settings and, for each supported
14855 primary document file format, a section
14856 \begin_inset Flex CharStyle:Code
14859 \begin_layout Plain Layout
14865 \SpecialChar \ldots{}
14867 \begin_inset Flex CharStyle:Code
14870 \begin_layout Plain Layout
14879 \begin_layout Subsection
14880 The template header
14883 \begin_layout Description
14884 \begin_inset Flex CharStyle:Code
14887 \begin_layout Plain Layout
14888 AutomaticProduction
14889 \begin_inset space ~
14897 Whether the file represented by the template must be generated by LyX.
14898 This command must occur exactly once.
14901 \begin_layout Description
14902 \begin_inset Flex CharStyle:Code
14905 \begin_layout Plain Layout
14907 \begin_inset space ~
14915 A glob pattern that is used in the file dialog to filter out the desired
14917 If there is more than one possible file extension (e.g.
14918 \begin_inset space ~
14922 \begin_inset Flex CharStyle:Code
14925 \begin_layout Plain Layout
14932 \begin_inset Flex CharStyle:Code
14935 \begin_layout Plain Layout
14941 ), use something like
14942 \begin_inset Flex CharStyle:Code
14945 \begin_layout Plain Layout
14952 This command must occur exactly once.
14955 \begin_layout Description
14956 \begin_inset Flex CharStyle:Code
14959 \begin_layout Plain Layout
14961 \begin_inset space ~
14969 The text that is displayed on the button.
14970 This command must occur exactly once.
14973 \begin_layout Description
14974 \begin_inset Flex CharStyle:Code
14977 \begin_layout Plain Layout
14979 \begin_inset space ~
14983 \begin_inset space ~
14991 The help text that is used in the External dialog.
14992 Provide enough information to explain to the user just what the template
14993 can provide him with.
14994 This command must occur exactly once.
14997 \begin_layout Description
14998 \begin_inset Flex CharStyle:Code
15001 \begin_layout Plain Layout
15003 \begin_inset space ~
15011 The file format of the original file.
15012 This must be the name of a format that is known to LyX (see section
15013 \begin_inset CommandInset ref
15015 reference "sub:Formats"
15021 \begin_inset Quotes eld
15025 \begin_inset Flex CharStyle:Code
15028 \begin_layout Plain Layout
15035 \begin_inset Quotes erd
15038 if the template can handle original files of more than one format.
15039 LyX will attempt to interrogate the file itself in order to deduce its
15040 format in this case.
15041 This command must occur exactly once.
15044 \begin_layout Description
15045 \begin_inset Flex CharStyle:Code
15048 \begin_layout Plain Layout
15050 \begin_inset space ~
15058 A unique name for the template.
15059 It must not contain substitution macros (see below).
15062 \begin_layout Description
15063 \begin_inset Flex CharStyle:Code
15066 \begin_layout Plain Layout
15068 \begin_inset space ~
15071 Rotate|Resize|Clip|Extra
15076 This command specifies which transformations are supported by this template.
15077 It may occur zero or more times.
15078 This command enables the corresponding tabs in the external dialog.
15080 \begin_inset Flex CharStyle:Code
15083 \begin_layout Plain Layout
15089 command must have either a corresponding
15090 \begin_inset Flex CharStyle:Code
15093 \begin_layout Plain Layout
15100 \begin_inset Flex CharStyle:Code
15103 \begin_layout Plain Layout
15110 \begin_inset Flex CharStyle:Code
15113 \begin_layout Plain Layout
15120 Otherwise the transformation will not be supported by that format.
15123 \begin_layout Subsection
15127 \begin_layout Description
15128 \begin_inset Flex CharStyle:Code
15131 \begin_layout Plain Layout
15133 \begin_inset space ~
15136 LaTeX|PDFLaTeX|PlainText|DocBook
15141 The primary document file format that this format definition is for.
15142 Not every template has a sensible representation in all document file formats.
15143 Please define nevertheless a
15144 \begin_inset Flex CharStyle:Code
15147 \begin_layout Plain Layout
15153 section for all formats.
15154 Use a dummy text when no representation is available.
15155 Then you can at least see a reference to the external material in the exported
15159 \begin_layout Description
15160 \begin_inset Flex CharStyle:Code
15163 \begin_layout Plain Layout
15165 \begin_inset space ~
15169 \begin_inset space ~
15177 This command defines an additional macro
15178 \begin_inset Flex CharStyle:Code
15181 \begin_layout Plain Layout
15187 for substitution in
15188 \begin_inset Flex CharStyle:Code
15191 \begin_layout Plain Layout
15199 \begin_inset Flex CharStyle:Code
15202 \begin_layout Plain Layout
15208 itself may contain substitution macros.
15209 The advantage over using
15210 \begin_inset Flex CharStyle:Code
15213 \begin_layout Plain Layout
15220 \begin_inset Flex CharStyle:Code
15223 \begin_layout Plain Layout
15229 is that the substituted value of
15230 \begin_inset Flex CharStyle:Code
15233 \begin_layout Plain Layout
15239 is sanitized so that it is a valid optional argument in the document format.
15240 This command may occur zero or more times.
15243 \begin_layout Description
15244 \begin_inset Flex CharStyle:Code
15247 \begin_layout Plain Layout
15249 \begin_inset space ~
15257 The text that is inserted in the exported document.
15258 This is actually the most important command and can be quite complex.
15259 This command must occur exactly once.
15262 \begin_layout Description
15263 \begin_inset Flex CharStyle:Code
15266 \begin_layout Plain Layout
15268 \begin_inset space ~
15276 This command specifies a preamble snippet that will be included in the
15278 It has to be defined using
15279 \begin_inset Flex CharStyle:Code
15282 \begin_layout Plain Layout
15288 \SpecialChar \ldots{}
15290 \begin_inset Flex CharStyle:Code
15293 \begin_layout Plain Layout
15300 This command may occur zero or more times.
15303 \begin_layout Description
15304 \begin_inset Flex CharStyle:Code
15307 \begin_layout Plain Layout
15309 \begin_inset space ~
15313 \begin_inset space ~
15321 This command denotes files that are created by the conversion process and
15322 are needed for a particular export format.
15323 If the filename is relative, it is interpreted relative to the master document.
15324 This command may be given zero or more times.
15327 \begin_layout Description
15328 \begin_inset Flex CharStyle:Code
15331 \begin_layout Plain Layout
15333 \begin_inset space ~
15341 The name of a required LaTeX package.
15342 The package is included via
15343 \begin_inset Flex CharStyle:Code
15346 \begin_layout Plain Layout
15354 in the LaTeX preamble.
15355 This command may occur zero or more times.
15358 \begin_layout Description
15359 \begin_inset Flex CharStyle:Code
15362 \begin_layout Plain Layout
15364 \begin_inset space ~
15368 \begin_inset space ~
15371 RotationLatexCommand
15376 This command specifies that the built in LaTeX command should be used for
15378 This command may occur once or not at all.
15381 \begin_layout Description
15382 \begin_inset Flex CharStyle:Code
15385 \begin_layout Plain Layout
15387 \begin_inset space ~
15391 \begin_inset space ~
15399 This command specifies that the built in LaTeX command should be used for
15401 This command may occur once or not at all.
15404 \begin_layout Description
15405 \begin_inset Flex CharStyle:Code
15408 \begin_layout Plain Layout
15410 \begin_inset space ~
15414 \begin_inset space ~
15417 RotationLatexOption
15422 This command specifies that rotation is done via an optional argument.
15423 This command may occur once or not at all.
15426 \begin_layout Description
15427 \begin_inset Flex CharStyle:Code
15430 \begin_layout Plain Layout
15432 \begin_inset space ~
15436 \begin_inset space ~
15444 This command specifies that resizing is done via an optional argument.
15445 This command may occur once or not at all.
15448 \begin_layout Description
15449 \begin_inset Flex CharStyle:Code
15452 \begin_layout Plain Layout
15454 \begin_inset space ~
15458 \begin_inset space ~
15466 This command specifies that clipping is done via an optional argument.
15467 This command may occur once or not at all.
15470 \begin_layout Description
15471 \begin_inset Flex CharStyle:Code
15474 \begin_layout Plain Layout
15476 \begin_inset space ~
15480 \begin_inset space ~
15488 This command specifies that an extra optional argument is used.
15489 This command may occur once or not at all.
15492 \begin_layout Description
15493 \begin_inset Flex CharStyle:Code
15496 \begin_layout Plain Layout
15498 \begin_inset space ~
15506 The file format of the converted file.
15507 This must be the name of a format that is known to LyX (see the
15508 \begin_inset Flex CharStyle:MenuItem
15511 \begin_layout Plain Layout
15516 ools\SpecialChar \menuseparator
15521 references:Conversion
15527 This command must occur exactly once.
15530 \begin_layout Description
15531 \begin_inset Flex CharStyle:Code
15534 \begin_layout Plain Layout
15536 \begin_inset space ~
15544 The file name of the converted file.
15545 The file name must be absolute.
15546 This command must occur exactly once.
15549 \begin_layout Subsection
15550 Preamble definitions
15553 \begin_layout Standard
15554 The external template configuration file may contain additional preamble
15555 definitions enclosed by
15556 \begin_inset Flex CharStyle:Code
15559 \begin_layout Plain Layout
15565 \SpecialChar \ldots{}
15567 \begin_inset Flex CharStyle:Code
15570 \begin_layout Plain Layout
15577 They can be used by the templates in the
15578 \begin_inset Flex CharStyle:Code
15581 \begin_layout Plain Layout
15590 \begin_layout Section
15591 The substitution mechanism
15594 \begin_layout Standard
15595 When the external material facility invokes an external program, it is done
15596 on the basis of a command defined in the template configuration file.
15597 These commands can contain various macros that are expanded before execution.
15598 Execution always take place in the directory of the containing document.
15601 \begin_layout Standard
15602 Also, whenever external material is to be displayed, the name will be produced
15603 by the substitution mechanism, and most other commands in the template
15604 definition support substitution as well.
15607 \begin_layout Standard
15608 The available macros are the following:
15611 \begin_layout Description
15612 \begin_inset Flex CharStyle:Code
15615 \begin_layout Plain Layout
15616 $$AbsOrRelPathMaster
15621 The file path, absolute or relative to the master LyX document.
15624 \begin_layout Description
15625 \begin_inset Flex CharStyle:Code
15628 \begin_layout Plain Layout
15629 $$AbsOrRelPathParent
15634 The file path, absolute or relative to the LyX document.
15637 \begin_layout Description
15638 \begin_inset Flex CharStyle:Code
15641 \begin_layout Plain Layout
15647 The absolute file path.
15650 \begin_layout Description
15651 \begin_inset Flex CharStyle:Code
15654 \begin_layout Plain Layout
15660 The filename without path and without the extension.
15663 \begin_layout Description
15664 \begin_inset Flex CharStyle:Code
15667 \begin_layout Plain Layout
15669 \begin_inset Quotes eld
15673 \begin_inset Quotes erd
15681 This macro will expand to the contents of the file with the name
15682 \begin_inset Flex CharStyle:Code
15685 \begin_layout Plain Layout
15694 \begin_layout Description
15695 \begin_inset Flex CharStyle:Code
15698 \begin_layout Plain Layout
15704 The file extension (including the dot).
15707 \begin_layout Description
15708 \begin_inset Flex CharStyle:Code
15711 \begin_layout Plain Layout
15717 The filename of the file specified in the external material dialog.
15718 This is either an absolute name, or it is relative to the LyX document.
15721 \begin_layout Description
15722 \begin_inset Flex CharStyle:Code
15725 \begin_layout Plain Layout
15732 \begin_inset Flex CharStyle:Code
15735 \begin_layout Plain Layout
15741 (absolute name or relative to the LyX document).
15744 \begin_layout Description
15745 \begin_inset Flex CharStyle:Code
15748 \begin_layout Plain Layout
15754 The file path, relative to the master LyX document.
15757 \begin_layout Description
15758 \begin_inset Flex CharStyle:Code
15761 \begin_layout Plain Layout
15767 The file path, relative to the LyX document.
15770 \begin_layout Description
15771 \begin_inset Flex CharStyle:Code
15774 \begin_layout Plain Layout
15780 This macro will expand to the absolute path of the system directory.
15781 This is typically used to point to the various helper scripts that are
15785 \begin_layout Description
15786 \begin_inset Flex CharStyle:Code
15789 \begin_layout Plain Layout
15795 A name and full path to a temporary file which will be automatically deleted
15796 whenever the containing document is closed, or the external material insertion
15800 \begin_layout Standard
15801 All path macros contain a trailing directory separator, so you can construct
15803 the absolute filename with
15804 \begin_inset Flex CharStyle:Code
15807 \begin_layout Plain Layout
15808 $$AbsPath$$Basename$$Extension
15816 \begin_layout Standard
15817 The macros above are substituted in all commands unless otherwise noted.
15819 \begin_inset Flex CharStyle:Code
15822 \begin_layout Plain Layout
15828 supports additionally the following substitutions if they are enabled by
15830 \begin_inset Flex CharStyle:Code
15833 \begin_layout Plain Layout
15840 \begin_inset Flex CharStyle:Code
15843 \begin_layout Plain Layout
15852 \begin_layout Description
15853 \begin_inset Flex CharStyle:Code
15856 \begin_layout Plain Layout
15862 The front part of the resize command.
15865 \begin_layout Description
15866 \begin_inset Flex CharStyle:Code
15869 \begin_layout Plain Layout
15875 The back part of the resize command.
15878 \begin_layout Description
15879 \begin_inset Flex CharStyle:Code
15882 \begin_layout Plain Layout
15888 The front part of the rotation command.
15891 \begin_layout Description
15892 \begin_inset Flex CharStyle:Code
15895 \begin_layout Plain Layout
15901 The back part of the rotation command.
15904 \begin_layout Standard
15905 The value string of the
15906 \begin_inset Flex CharStyle:Code
15909 \begin_layout Plain Layout
15915 command supports additionally the following substitutions if they are enabled
15917 \begin_inset Flex CharStyle:Code
15920 \begin_layout Plain Layout
15927 \begin_inset Flex CharStyle:Code
15930 \begin_layout Plain Layout
15939 \begin_layout Description
15940 \begin_inset Flex CharStyle:Code
15943 \begin_layout Plain Layout
15952 \begin_layout Description
15953 \begin_inset Flex CharStyle:Code
15956 \begin_layout Plain Layout
15965 \begin_layout Description
15966 \begin_inset Flex CharStyle:Code
15969 \begin_layout Plain Layout
15978 \begin_layout Description
15979 \begin_inset Flex CharStyle:Code
15982 \begin_layout Plain Layout
15988 The rotation option.
15991 \begin_layout Standard
15992 You may ask why there are so many path macros.
15993 There are mainly two reasons:
15996 \begin_layout Enumerate
15997 Relative and absolute file names should remain relative or absolute, respectivel
15999 Users may have reasons to prefer either form.
16000 Relative names are useful for portable documents that should work on different
16001 machines, for example.
16002 Absolute names may be required by some programs.
16005 \begin_layout Enumerate
16006 LaTeX treats relative file names differently than LyX and other programs
16007 in nested included files.
16008 For LyX, a relative file name is always relative to the document that contains
16010 For LaTeX, it is always relative to the master document.
16011 These two definitions are identical if you have only one document, but
16012 differ if you have a master document that includes part documents.
16013 That means that relative filenames must be transformed when presented to
16015 Fortunately LyX does this automatically for you if you choose the right
16019 \begin_layout Standard
16020 So which path macro should be used in new template definitions? The rule
16024 \begin_layout Itemize
16026 \begin_inset Flex CharStyle:Code
16029 \begin_layout Plain Layout
16035 if an absolute path is required.
16038 \begin_layout Itemize
16040 \begin_inset Flex CharStyle:Code
16043 \begin_layout Plain Layout
16044 $$AbsOrRelPathMaster
16049 if the substituted string is some kind of LaTeX input.
16052 \begin_layout Itemize
16054 \begin_inset Flex CharStyle:Code
16057 \begin_layout Plain Layout
16058 $$AbsOrRelPathParent
16063 in order to preserve the user's choice.
16066 \begin_layout Standard
16067 There are special cases where this rule does not work and e.g.
16068 \begin_inset space ~
16071 relative names are needed, but normally it will work just fine.
16072 One example for such a case is the command
16073 \begin_inset Flex CharStyle:Code
16076 \begin_layout Plain Layout
16077 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
16082 in the XFig template above: We can't use the absolute name because the
16084 \begin_inset Flex CharStyle:Code
16087 \begin_layout Plain Layout
16093 files needs the relative name in order to rewrite the file content.
16096 \begin_layout Section
16097 \begin_inset CommandInset label
16099 name "sec:Security-discussion"
16103 Security discussion
16106 \begin_layout Standard
16107 \begin_inset Note Note
16110 \begin_layout Plain Layout
16111 This section is outdated
16116 The external material feature interfaces with a lot of external programs
16117 and does so automatically, so we have to consider the security implications
16119 In particular, since you have the option of including your own filenames
16120 and/or parameter strings and those are expanded into a command, it seems
16121 that it would be possible to create a malicious document which executes
16122 arbitrary commands when a user views or prints the document.
16123 This is something we definately want to avoid.
16126 \begin_layout Standard
16127 However, since the external program commands are specified in the template
16128 configuration file only, there are no security issues if LyX is properly
16129 configured with safe templates only.
16130 This is so because the external programs are invoked with the
16131 \begin_inset Flex CharStyle:Code
16134 \begin_layout Plain Layout
16140 -system call rather than the
16141 \begin_inset Flex CharStyle:Code
16144 \begin_layout Plain Layout
16150 system-call, so it's not possible to execute arbitrary commands from the
16151 filename or parameter section via the shell.
16154 \begin_layout Standard
16155 This also implies that you are restricted in what command strings you can
16156 use in the external material templates.
16157 In particular, pipes and redirection are not readily available.
16158 This has to be so if LyX should remain safe.
16159 If you want to use some of the shell features, you should write a safe
16160 script to do this in a controlled manner, and then invoke the script from
16161 the command string.
16163 \begin_inset Flex CharStyle:Code
16166 \begin_layout Plain Layout
16172 directory of the LyX installation, you can find a safe wrapper script
16173 \begin_inset Flex CharStyle:Code
16176 \begin_layout Plain Layout
16177 general_command_wrapper.py
16182 that supports redirection of input and output.
16183 That can serve as an example for how to write safe template scripts.
16184 For a more advanced example that uses
16185 \begin_inset Flex CharStyle:Code
16188 \begin_layout Plain Layout
16194 and friends, take a look at the
16195 \begin_inset Flex CharStyle:Code
16198 \begin_layout Plain Layout
16207 \begin_layout Standard
16208 It is possible to design a template that interacts directly with the shell,
16209 but since this would allow a malicious user to execute arbitrary commands
16210 by writing clever filenames and/or parameters, we generally recommend that
16211 you only use safe scripts that work with the
16212 \begin_inset Flex CharStyle:Code
16215 \begin_layout Plain Layout
16221 system call in a controlled manner.
16222 Of course, for use in a controlled environment, it can be tempting to just
16223 fall back to use ordinary shell scripts.
16224 If you do so, be aware that you
16228 provide an easily exploitable security hole in your system.
16229 Of course it stands to reason that such unsafe templates will never be
16230 included in the standard LyX distribution, although we do encourage people
16231 to submit new templates in the open source tradition.
16232 But LyX as shipped from the official distribution channels will never have
16236 \begin_layout Standard
16237 Including external material provides a lot of power, and you have to be
16238 careful not to introduce security hazards with this power.
16239 A subtle error in a single line in an innocent looking script can open
16240 the door to huge security problems.
16241 So if you do not fully understand the issues, we recommend that you consult
16242 a knowledgable security professional or the LyX development team if you
16243 have any questions about whether a given template is safe or not.
16244 And do this before you use it in an uncontrolled environment.
16247 \begin_layout Chapter
16251 \begin_layout Section
16255 \begin_layout Standard
16256 The LyX server is a method implemented in LyX that will enable other programs
16257 to talk to LyX, invoke LyX commands, and retrieve information about the
16258 LyX internal state.
16259 This is only intended for advanced users, but they should find it useful.
16260 Please note that, at present,
16262 the server does not work on Windows
16268 \begin_layout Plain Layout
16269 There is no principled reason it cannot do so.
16270 But none of the developers on Windows® have yet implemented this functionality
16279 \begin_layout Section
16280 Starting the LyX Server
16283 \begin_layout Standard
16284 The LyX server works through the use of a pair of named pipes.
16285 These are usually located in
16286 \begin_inset Flex CharStyle:Code
16289 \begin_layout Plain Layout
16296 \begin_inset Quotes eld
16300 \begin_inset Flex CharStyle:Code
16303 \begin_layout Plain Layout
16310 \begin_inset Quotes erd
16314 \begin_inset Quotes eld
16318 \begin_inset Flex CharStyle:Code
16321 \begin_layout Plain Layout
16328 \begin_inset Quotes erd
16332 External programs write into
16333 \begin_inset Flex CharStyle:Code
16336 \begin_layout Plain Layout
16342 and read back data from
16343 \begin_inset Flex CharStyle:Code
16346 \begin_layout Plain Layout
16353 The stem of the pipe names can be defined in the
16354 \begin_inset Flex CharStyle:MenuItem
16357 \begin_layout Plain Layout
16362 ools\SpecialChar \menuseparator
16372 dialog, for example
16373 \begin_inset Flex CharStyle:Code
16376 \begin_layout Plain Layout
16377 "/home/myhome/.lyxpipe"
16385 \begin_layout Standard
16387 \begin_inset Flex CharStyle:Code
16390 \begin_layout Plain Layout
16397 \begin_inset Flex CharStyle:Code
16400 \begin_layout Plain Layout
16406 ' to create the pipes.
16407 The above setting also has the effect of activating the LyX server.
16408 If one of the pipes already exists, LyX will assume that another LyX process
16409 is already running and will not start the server.
16410 To have several LyX processes with servers at the same time, you have to
16411 change the configuration between the start of the programs.
16414 \begin_layout Standard
16415 If you are developing a client program, you might find it useful to enable
16416 debugging information from the LyX server.
16417 Do this by starting LyX as lyx -dbg lyxserver.
16420 \begin_layout Standard
16421 Warning: if LyX crashes, it may not manage to remove the pipes; in this
16422 case you must remove them manually.
16423 If LyX starts and the pipes exist already, it will not start any server.
16426 \begin_layout Standard
16427 Other than this, there are a few points to consider:
16430 \begin_layout Itemize
16431 Both server and clients must run on UNIX or OS/2 machines.
16432 Communications between LyX on UNIX and clients on OS/2 or vice versa is
16433 not possible right now.
16436 \begin_layout Itemize
16437 On OS/2, only one client can connect to LyXServer at a time.
16440 \begin_layout Itemize
16441 On OS/2, clients must open inpipe with
16442 \begin_inset Flex CharStyle:Code
16445 \begin_layout Plain Layout
16454 \begin_layout Standard
16458 \begin_layout Standard
16459 You can find a complete example client written in C in the source distribution
16461 \begin_inset Flex CharStyle:Code
16464 \begin_layout Plain Layout
16465 development/lyxserver/server_monitor.c
16473 \begin_layout Section
16474 Normal communication
16477 \begin_layout Standard
16478 To issue a LyX call, the client writes a line of ASCII text into the input
16480 This line has the following format:
16483 \begin_layout Quote
16497 \begin_layout Description
16502 is a name that the client can choose arbitrarily.
16503 Its only use is that LyX will echo it if it sends an answer---so a client
16504 can dispatch results from different requesters.
16507 \begin_layout Description
16512 is the function you want LyX to perform.
16513 It is the same as the commands you'd use in the minibuffer.
16516 \begin_layout Description
16521 is an optional argument which is meaningful only to some functions (for
16523 \begin_inset Quotes eld
16527 \begin_inset Quotes erd
16530 which will insert the argument as text at the cursor position.)
16533 \begin_layout Standard
16534 The answer from LyX will arrive in the output pipe and be of the form
16537 \begin_layout Quote
16551 \begin_layout Standard
16560 are just echoed from the command request, while
16564 is more or less useful information filled according to how the command
16565 execution worked out.
16566 Some commands will return information about the internal state of LyX,
16568 \begin_inset Quotes eld
16572 \begin_inset Quotes erd
16575 , while other will return an empty data-response.
16576 This means that the command execution went fine.
16579 \begin_layout Standard
16580 In case of errors, the response from LyX will have this form
16583 \begin_layout Quote
16597 \begin_layout Standard
16602 should contain an explanation of why the command failed.
16605 \begin_layout Standard
16609 \begin_layout LyX-Code
16610 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
16613 \begin_layout LyX-Code
16614 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
16615 \begin_inset Newline newline
16618 read a <~/.lyxpipe.out
16619 \begin_inset Newline newline
16625 \begin_layout Section
16629 \begin_layout Standard
16630 LyX can notify clients of events going on asynchronously.
16631 Currently it will only do this if the user binds a key sequence with the
16633 \begin_inset Quotes eld
16637 \begin_inset Quotes erd
16641 The format of the string LyX sends is as follows:
16644 \begin_layout Quote
16645 \begin_inset Flex CharStyle:Code
16648 \begin_layout Plain Layout
16659 \begin_layout Standard
16664 is the printed representation of the key sequence that was actually typed
16668 \begin_layout Standard
16669 This mechanism can be used to extend LyX's command set and implement macros:
16670 bind some key sequence to
16671 \begin_inset Quotes eld
16675 \begin_inset Quotes erd
16678 , start a client that listens on the out pipe, dispatches the command according
16679 to the sequence and starts a function that may use LyX calls and LyX requests
16680 to issue a command or a series of commands to LyX.
16683 \begin_layout Section
16684 The simple LyX Server Protocol
16687 \begin_layout Standard
16688 LyX implements a simple protocol that can be used for session management.
16689 All messages are of the form
16692 \begin_layout Quote
16702 \begin_layout Standard
16708 \begin_inset Quotes eld
16712 \begin_inset Quotes erd
16716 \begin_inset Quotes eld
16720 \begin_inset Quotes erd
16725 \begin_inset Quotes eld
16729 \begin_inset Quotes erd
16732 is received from a client, LyX will report back to inform the client that
16733 it's listening to it's messages, while
16734 \begin_inset Quotes eld
16738 \begin_inset Quotes erd
16741 sent from LyX will inform clients that LyX is closing.