1 #LyX 1.6.0svn created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that the User's Guide prints
10 % out as advertised. If you mess with this preamble,
11 % parts of the User's Guide may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
49 InsetLayout CharStyle:MenuItem
58 \newcommand*{\menuitem}[1]{{\sffamily #1}}
66 \font_typewriter default
67 \font_default_family default
77 \pdf_title "LyX Configuration Manual"
78 \pdf_author "LyX Team"
79 \pdf_subject "LyX-documentation Customization"
80 \pdf_keywords "LyX, documentation, customization"
82 \pdf_bookmarksnumbered true
83 \pdf_bookmarksopen true
84 \pdf_bookmarksopenlevel 1
89 \pdf_pagebackref false
90 \pdf_pdfusetitle false
91 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
98 \paperorientation portrait
105 \paragraph_separation indent
107 \quotes_language english
110 \paperpagestyle headings
111 \tracking_changes false
112 \output_changes false
120 Customizing LyX: Features for the Advanced User
128 \begin_layout Plain Layout
130 If you have comments or error corrections, please send them to the LyX Documenta
131 tion mailing list, <lyx-docs@lists.lyx.org>.
139 \begin_layout Standard
140 \begin_inset CommandInset toc
141 LatexCommand tableofcontents
148 \begin_layout Chapter
152 \begin_layout Standard
153 This manual covers the customization features present in LyX.
154 In it, we discuss issues like keyboard shortcuts, screen previewing options,
155 printer options, sending commands to LyX via the LyX Server, internationalizati
156 on, installing new LaTeX classes and LyX layouts, etc.
157 We can't possibly hope to touch on everything you can change---our developers
158 add new features faster than we can document them---but we will explain
159 the most common customizations and hopefully point you in the right direction
160 for some of the more obscure ones.
163 \begin_layout Standard
164 \begin_inset Branch OutDated
167 \begin_layout Standard
168 Information from previous versions of this document that now seems to be
169 outdated is contained in the OutDated branch of this document.
170 By default, this information will not appear in the LaTeX output.
178 \begin_layout Chapter
179 LyX configuration files
182 \begin_layout Standard
183 \begin_inset CommandInset label
189 This chapter aims to help you to find your way through the LyX configuration
191 Before continuing to read this chapter, you should find out where your
192 LyX library and user directories are by using
193 \begin_inset Flex CharStyle:MenuItem
196 \begin_layout Plain Layout
201 elp\SpecialChar \menuseparator
214 The library directory is the place where LyX places its system-wide configurati
215 on files; the user directory is where you can place your modified versions.
216 We will call the former
217 \begin_inset Flex CharStyle:Code
220 \begin_layout Plain Layout
227 \begin_inset Flex CharStyle:MenuItem
230 \begin_layout Plain Layout
236 in the remainder of this document.
240 \begin_layout Section
242 \begin_inset Flex CharStyle:Code
245 \begin_layout Plain Layout
254 \begin_layout Standard
255 \begin_inset Flex CharStyle:Code
258 \begin_layout Plain Layout
264 and its sub-directories contain a number of files and that can be used
265 to customise LyX's behaviour.
266 You can change many of these files from within LyX itself through the
267 \begin_inset Flex CharStyle:MenuItem
270 \begin_layout Plain Layout
275 ools\SpecialChar \menuseparator
286 Most customization that you will want to do in LyX is possible through
288 However, many other inner aspects of LyX can be customized by modifying
290 \begin_inset Flex CharStyle:Code
293 \begin_layout Plain Layout
300 These files fall in different categories, described in the following subsection
304 \begin_layout Subsection
305 Automatically generated files
308 \begin_layout Standard
309 The files, which are to be found in
310 \begin_inset Flex CharStyle:MenuItem
313 \begin_layout Plain Layout
319 , are generated when you configure LyX.
320 They contain various default values that are guessed by inspection.
321 In general, it is not a good idea to modify them, since they might be overwritt
325 \begin_layout Labeling
326 \labelwidthstring 00.00.0000
327 \begin_inset Flex CharStyle:Code
330 \begin_layout Plain Layout
336 contains defaults for various commands.
339 \begin_layout Labeling
340 \labelwidthstring 00.00.0000
341 \begin_inset Flex CharStyle:Code
344 \begin_layout Plain Layout
350 contains the list of packages that have been recognized by LyX.
351 It is currently unused by the LyX program itself, but the information extracted
352 , and more, is made available with
353 \begin_inset Flex CharStyle:MenuItem
356 \begin_layout Plain Layout
361 elp\SpecialChar \menuseparator
378 \begin_layout Labeling
379 \labelwidthstring 00.00.0000
380 \begin_inset Flex CharStyle:Code
383 \begin_layout Plain Layout
389 the list of text classes that have been found in your
390 \begin_inset Flex CharStyle:Code
393 \begin_layout Plain Layout
399 directories, along with the associated LaTeX document class and their descripti
403 \begin_layout Labeling
404 \labelwidthstring 00.00.0000
405 \begin_inset Flex CharStyle:Code
408 \begin_layout Plain Layout
414 the list of layout modules found in your
415 \begin_inset Flex CharStyle:Code
418 \begin_layout Plain Layout
427 \begin_layout Labeling
428 \labelwidthstring 00.00.0000
429 \begin_inset Flex CharStyle:Code
432 \begin_layout Plain Layout
438 lists of various sorts of LaTeX-related files found on your system
441 \begin_layout Labeling
442 \labelwidthstring 00.00.0000
443 \begin_inset Flex CharStyle:Code
446 \begin_layout Plain Layout
452 is automatically generated during configuration from the file
453 \begin_inset Flex CharStyle:Code
456 \begin_layout Plain Layout
463 It contains information on your LaTeX configuration.
466 \begin_layout Subsection
470 \begin_layout Standard
471 These directories are duplicated between
472 \begin_inset Flex CharStyle:Code
475 \begin_layout Plain Layout
482 \begin_inset Flex CharStyle:Code
485 \begin_layout Plain Layout
492 If a particular files exists in both places, the one in
493 \begin_inset Flex CharStyle:Code
496 \begin_layout Plain Layout
505 \begin_layout Labeling
506 \labelwidthstring 00.00.0000
507 \begin_inset Flex CharStyle:Code
510 \begin_layout Plain Layout
516 this directory contains files with the extension
517 \begin_inset Flex CharStyle:Code
520 \begin_layout Plain Layout
526 that define the keybindings used in LyX (see section
531 \begin_inset CommandInset ref
533 reference "sec:bindings"
538 If there exists an internationalized version of the bind file named
539 \begin_inset Flex CharStyle:Code
542 \begin_layout Plain Layout
548 , that will be used first.
554 \begin_inset CommandInset ref
556 reference "chap:i18n"
561 \begin_inset CommandInset ref
563 reference "sec:bindings"
570 \begin_layout Labeling
571 \labelwidthstring 00.00.0000
572 \begin_inset Flex CharStyle:Code
575 \begin_layout Plain Layout
581 contains graphics files that can be included in documents.
585 \begin_layout Labeling
586 \labelwidthstring 00.00.0000
587 \begin_inset Flex CharStyle:Code
590 \begin_layout Plain Layout
596 contains LyX documentation files (including the one you are currently reading).
598 \begin_inset Flex CharStyle:Code
601 \begin_layout Plain Layout
607 deserves special attention, as noted above.
608 If there exists an internationalized version of the help-document with
610 \begin_inset Flex CharStyle:Code
613 \begin_layout Plain Layout
619 prepended to the name, that will be used first.
625 \begin_inset CommandInset ref
627 reference "chap:i18n"
634 \begin_layout Labeling
635 \labelwidthstring 00.00.0000
636 \begin_inset Flex CharStyle:Code
639 \begin_layout Plain Layout
645 contains example files that explain how to use some features.
646 In the file browser, press the
647 \begin_inset Flex CharStyle:MenuItem
650 \begin_layout Plain Layout
659 \begin_layout Labeling
660 \labelwidthstring 00.00.0000
661 \begin_inset Flex CharStyle:Code
664 \begin_layout Plain Layout
670 contains image files that are used by the
671 \begin_inset Flex CharStyle:MenuItem
674 \begin_layout Plain Layout
681 In addition, it also contains the individual icons used in the toolbar
682 and the banners that can be shown when LyX is launched.
685 \begin_layout Labeling
686 \labelwidthstring 00.00.0000
687 \begin_inset Flex CharStyle:Code
690 \begin_layout Plain Layout
696 contains keyboard keymapping files.
702 \begin_inset CommandInset ref
704 reference "sec:keymap"
711 \begin_layout Labeling
712 \labelwidthstring 00.00.0000
713 \begin_inset Flex CharStyle:Code
716 \begin_layout Plain Layout
722 contains the text class and module files described in Chapter
727 \begin_inset CommandInset ref
729 reference "chap:textclass"
736 \begin_layout Labeling
737 \labelwidthstring 00.00.0000
738 \begin_inset Flex CharStyle:Code
741 \begin_layout Plain Layout
748 \begin_inset Flex CharStyle:Code
751 \begin_layout Plain Layout
757 Python scripts used to convert between LyX versions.
758 These can be run from the command line if, say, you want to batch-convert
762 \begin_layout Labeling
763 \labelwidthstring 00.00.0000
764 \begin_inset Flex CharStyle:Code
767 \begin_layout Plain Layout
773 contains some files that demonstrate the capabilities of the
774 \begin_inset Flex CharStyle:MenuItem
777 \begin_layout Plain Layout
788 Also contains some scripts used by LyX itself.
791 \begin_layout Labeling
792 \labelwidthstring 00.00.0000
793 \begin_inset Flex CharStyle:Code
796 \begin_layout Plain Layout
802 contains the standard LyX template files described in Chapter
807 \begin_inset CommandInset ref
809 reference "sec:templates"
816 \begin_layout Labeling
817 \labelwidthstring 00.00.0000
818 \begin_inset Flex CharStyle:Code
821 \begin_layout Plain Layout
827 contains files with the extension
828 \begin_inset Flex CharStyle:Code
831 \begin_layout Plain Layout
837 that define the user interface to LyX.
838 That is, the files define which items appear in which menus and the items
839 appearing on the toolbar.
841 \begin_inset CommandInset ref
850 \begin_layout Subsection
851 Files you don't want to modify
854 \begin_layout Standard
855 These files are used internally by LyX and you generally do not need to
856 modify them unless you are a developer.
859 \begin_layout Labeling
860 \labelwidthstring 00.00.0000
861 \begin_inset Flex CharStyle:Code
864 \begin_layout Plain Layout
870 this file contains the list of LyX developers.
871 The contents are displayed with the menu entry
872 \begin_inset Flex CharStyle:MenuItem
875 \begin_layout Plain Layout
880 elp\SpecialChar \menuseparator
893 \begin_layout Labeling
894 \labelwidthstring 00.00.0000
895 \begin_inset Flex CharStyle:Code
898 \begin_layout Plain Layout
904 this is a LaTeX script used during the configuration process.
908 \begin_layout Labeling
909 \labelwidthstring 00.00.0000
910 \begin_inset Flex CharStyle:Code
913 \begin_layout Plain Layout
919 this is the script that is used to re-configure LyX.
920 It creates configuration files in the directory it was run from.
923 \begin_layout Subsection
924 Other files needing a line or two...
927 \begin_layout Labeling
928 \labelwidthstring 00.00.0000
929 \begin_inset Flex CharStyle:Code
932 \begin_layout Plain Layout
938 this contains tables describing how different character encodings can be
942 \begin_layout Labeling
943 \labelwidthstring 00.00.0000
944 \begin_inset Flex CharStyle:Code
947 \begin_layout Plain Layout
953 this file contains the templates available to the new
954 \begin_inset Flex CharStyle:MenuItem
957 \begin_layout Plain Layout
970 \begin_layout Labeling
971 \labelwidthstring 00.00.0000
972 \begin_inset Flex CharStyle:Code
975 \begin_layout Plain Layout
981 this file contains a list of all the languages currently supported by LyX.
984 \begin_layout Section
985 Your local configuration directory
988 \begin_layout Standard
989 Even if you are using LyX as an unprivileged user, you might want to change
990 LyX configuration for your own use.
992 \begin_inset Flex CharStyle:Code
995 \begin_layout Plain Layout
1001 directory contains all your personal configuration files.
1002 This is the directory described as
1003 \begin_inset Quotes eld
1007 \begin_inset Quotes erd
1011 \begin_inset Flex CharStyle:MenuItem
1014 \begin_layout Plain Layout
1019 elp\SpecialChar \menuseparator
1021 \begin_inset space ~
1030 This directory is used as a mirror of
1031 \begin_inset Flex CharStyle:Code
1034 \begin_layout Plain Layout
1040 , which means that every file in
1041 \begin_inset Flex CharStyle:Code
1044 \begin_layout Plain Layout
1050 is a replacement for the corresponding file in
1051 \begin_inset Flex CharStyle:Code
1054 \begin_layout Plain Layout
1061 Any configuration file described in the above sections can be placed either
1062 in the system-wide directory, in which case it will affect all users, or
1063 in your local directory for your own use.
1066 \begin_layout Standard
1067 To make things clearer, let's provide a few examples:
1070 \begin_layout Itemize
1071 The preferences set in the
1072 \begin_inset Flex CharStyle:MenuItem
1075 \begin_layout Plain Layout
1080 ools\SpecialChar \menuseparator
1090 dialog are saved to a file
1091 \begin_inset Flex CharStyle:Code
1094 \begin_layout Plain Layout
1101 \begin_inset Flex CharStyle:Code
1104 \begin_layout Plain Layout
1113 \begin_layout Itemize
1114 When you reconfigure using
1115 \begin_inset Flex CharStyle:MenuItem
1118 \begin_layout Plain Layout
1123 ools\SpecialChar \menuseparator
1134 \begin_inset Flex CharStyle:Code
1137 \begin_layout Plain Layout
1143 script, and the resulting files are written in your local configuration
1145 This means that any additional text class file that you might have added
1147 \begin_inset Flex CharStyle:Code
1150 \begin_layout Plain Layout
1156 will be added to the list of classes in the
1157 \begin_inset Flex CharStyle:MenuItem
1160 \begin_layout Plain Layout
1165 ocument\SpecialChar \menuseparator
1178 \begin_layout Itemize
1179 If you get some updated documentation from LyX ftp site and cannot install
1180 it because you do not have sysadmin rights on your system, you can just
1182 \begin_inset Flex CharStyle:Code
1185 \begin_layout Plain Layout
1191 and the items in the
1192 \begin_inset Flex CharStyle:MenuItem
1195 \begin_layout Plain Layout
1205 menu will open them!
1208 \begin_layout Section
1209 Running LyX with multiple configurations
1212 \begin_layout Standard
1213 The configuration freedom of the local configuration directory may not suffice
1214 if you want to have more than one configuration at your disposal.
1215 For example, you may want to be use different key bindings or printer settings
1217 You can achieve this by having several such directories.
1218 You then specify which directory to use at run-time.
1221 \begin_layout Standard
1222 Invoking LyX with the command line switch
1223 \begin_inset Flex CharStyle:Code
1226 \begin_layout Plain Layout
1236 instructs the program to read the configuration from that directory, and
1237 not from the default directory.
1238 (You can determine the default directory by running LyX without the
1239 \begin_inset Flex CharStyle:Code
1242 \begin_layout Plain Layout
1248 switch.) If the specified directory does not exist, LyX offers to create
1249 it for you, just like it does for the default directory on the first time
1250 you run the program.
1251 You can modify the configuration options in this additional user directory
1252 exactly as you would for the default directory.
1253 These directories are completely independent (but read on).
1254 Note that setting the environment variable
1255 \begin_inset Flex CharStyle:Code
1258 \begin_layout Plain Layout
1264 to some value has exactly the same effect.
1267 \begin_layout Standard
1268 Having several configurations also requires more maintenance: if you want
1269 to add a new layout to
1270 \begin_inset Flex CharStyle:Code
1273 \begin_layout Plain Layout
1279 which you want available from all your configurations, you must add it
1280 to each directory separately.
1281 You can avoid this with the following trick: after LyX creates the additional
1282 directory, most of the subdirectories (see above) are empty.
1283 If you want the new configuration to mirror an existing one, replace the
1284 empty subdirectory with a symbolic link to the matching subdirectory in
1285 the existing configuration.
1287 \begin_inset Flex CharStyle:Code
1290 \begin_layout Plain Layout
1296 subirectory, however, since it contains a file written by the configuration
1297 script (also accessible through
1298 \begin_inset Flex CharStyle:MenuItem
1301 \begin_layout Plain Layout
1306 ools\SpecialChar \menuseparator
1316 ) which is configuration-specific.
1319 \begin_layout Chapter
1320 The Preferences dialog
1323 \begin_layout Section
1324 Using the dialog for the first time
1327 \begin_layout Standard
1329 \begin_inset Flex CharStyle:Code
1332 \begin_layout Plain Layout
1338 file will contain only changes that you have made to the default behaviour,
1339 some of which is hard-coded into LyX and some of which is contained in
1341 \begin_inset Flex CharStyle:Code
1344 \begin_layout Plain Layout
1345 LyXDir/lyxrc.defaults
1351 Note that in both files lines beginning with a
1352 \begin_inset Quotes eld
1356 \begin_inset Quotes erd
1359 are just comments and are not interpreted.
1360 However, only system administrators should edit
1361 \begin_inset Flex CharStyle:Code
1364 \begin_layout Plain Layout
1365 LyXDir/lyxrc.defaults
1371 Users should use the
1372 \begin_inset Flex CharStyle:MenuItem
1375 \begin_layout Plain Layout
1380 ools\SpecialChar \menuseparator
1390 dialog to create and modify their own
1391 \begin_inset Flex CharStyle:Code
1394 \begin_layout Plain Layout
1403 \begin_layout Standard
1405 \begin_inset Flex CharStyle:MenuItem
1408 \begin_layout Plain Layout
1413 ools\SpecialChar \menuseparator
1423 dialog will be largely self-explanatory.
1424 Most things in the dialog have associated `tool tips': hover your mouse
1425 pointer over something for more information.
1426 Before we highlight a few of the more important commands below, however,
1428 \begin_inset Flex CharStyle:MenuItem
1431 \begin_layout Plain Layout
1437 ing some of your changes (e.g., screen fonts) will have an instant effect.
1439 changing the bind file) will not.
1440 If nothing appears to have changed, just
1441 \begin_inset Flex CharStyle:MenuItem
1444 \begin_layout Plain Layout
1450 the changes and restart LyX.
1453 \begin_layout Section
1457 \begin_layout Subsection
1461 \begin_layout Standard
1462 The font used to display your documents on the LyX screen is very important,
1463 since you'll be reading all your documents with this font.
1464 Therefore it is important that the font be as readable and good-looking
1466 The LyX team tried to provide the best possible default font for you, but
1467 since systems can be so different, it's quite possible that the default
1468 fonts will be sub-optimal on your system.
1469 Fortunately, you can do something about this.
1470 Before we explain how, you should learn a bit more about fonts so that
1471 you are better prepared for choosing your fonts.
1472 There are trade-offs that are specific to your preferences and the capabilities
1476 \begin_layout Standard
1477 Notice that this section only deals with the fonts on the
1481 inside the LyX window.
1482 The fonts that appear on the
1490 are independent from these fonts, and are determined by the document class.
1495 to learn how to change the font of the printed version of your document.
1498 \begin_layout Standard
1499 Basically, screen fonts come in two different kinds: scalable outline fonts
1500 and non-scalable bitmap fonts.
1501 This distinction seems a bit arbitrary, since non-scalable fonts are actually
1502 scalable in most modern font renderers.
1503 The difference lies in the
1507 of the scaling and the
1512 The most important decision is thus whether you should use non-scalable
1513 bitmap fonts or scalable outline fonts.
1516 \begin_layout Standard
1517 The scalable fonts are built from
1521 of the single glyphs (i.e.
1522 characters) in the font.
1523 This means that each glyph is defined using mathematical curves that are
1524 well suited for scaling to any requested size.
1525 This mathematical definition is interpreted by the font renderer and turned
1526 into a small picture composed of pixels according to which size and glyph
1527 (or symbol) the programmer requests.
1528 This means that scalable fonts will look pretty good in most sizes.Since
1529 scalable fonts are defined in an abstract way, it can be hard to provide
1530 a good rendering at small sizes, where each pixel has to be very carefully
1531 computed to provide a good image.
1532 Technically it is possible to do this from the mathematical definition,
1533 but in order to keep the rendering reasonably fast, tradeoffs have to be
1534 made, and the result is that scalable fonts can be difficult to read at
1538 \begin_layout Standard
1539 Bitmap fonts on the other hand, are defined by bitmap graphics from the
1540 start, so they will look good at all the sizes they are meant for.
1541 However, they don't scale well, because in order to scale a glyph, each
1542 pixel is enlarged into several pixels.
1543 It is the same effect that happens if you try to enlarge a picture in an
1544 image manipulation program.
1545 In order to relieve this effect, bitmap fonts are typically provided in
1546 several fixed sizes typically from around 8 pixels high up to 34 pixels
1547 or so high in steps according to what is believed to be useful.
1548 The advantage of bitmap fonts is that no complicated computations are necessary
1549 to display each glyph, so bitmap fonts are thus faster displayed than scalable
1551 The disadvantage is that sizes that don't exists as fixed versions have
1552 to be scaled by doubling pixels, and thus look bad.
1555 \begin_layout Standard
1556 The net result of all this is that bitmap fonts are generally best for the
1557 small sizes, where they are available, while scalable fonts are generally
1558 best for large sizes.
1559 The logical conclusion would thus be to use bitmap fonts for the small
1560 sizes, and scalable fonts for the large sizes.
1561 Unfortunately, this is not a good idea, since bitmap fonts and scalable
1562 fonts are not designed to be used together, so the overall look of such
1563 a scheme would be bad.
1564 The best you can do is thus to try both schemes and decide for yourself
1568 \begin_layout Standard
1569 In the following, we will describe what to do if the text does not look
1571 We'll start with the most important parameters: DPI and font zoom.
1574 \begin_layout Subsubsection
1575 DPI setting and Font Zoom
1578 \begin_layout Standard
1579 LyX automatically tries to scale the fonts to look as close as the paper
1580 output size as possible, except for the so-called font zoom factor.
1583 \begin_layout Standard
1584 In order for this to work on all systems, it relies on the screen DPI (dots
1585 per inch) setting to be correct.
1586 The DPI setting for your system is autodetected by LyX using information
1587 provided by your system.
1588 You can check what LyX autodetects the DPI setting to, by running LyX as
1590 \begin_inset Flex CharStyle:Code
1593 \begin_layout Plain Layout
1602 \begin_layout Standard
1603 On many systems, this will not be correct, so you should check that it is
1605 On X11 systems, you can run
1606 \begin_inset Quotes eld
1610 \begin_inset Flex CharStyle:Code
1613 \begin_layout Plain Layout
1620 \begin_inset Quotes erd
1623 and write down what the DPI is for the resolution you use (this will be
1624 close to the value LyX detects).
1625 It is the number mentioned as
1626 \begin_inset Quotes eld
1630 \begin_inset Quotes erd
1634 Also write down the number of pixels you have in the width (the first number
1636 \begin_inset Quotes eld
1640 \begin_inset Quotes erd
1646 \begin_layout Standard
1647 Then get the good old ruler out of the closet, and measure the width of
1648 the visible screen-image on your monitor.
1649 Convert this measurement to inches if you used a centimeter ruler by dividing
1651 Now you can determine the correct DPI setting for your screen by dividing
1652 the number of pixels in the width by the width of the screen-image on the
1654 If this number is more than, say, 5 DPI from the detected value, you should
1655 either fix your system setup, or at least tell LyX that the DPI is different
1656 than the detected value.
1659 \begin_layout Standard
1660 If you can't fix system setup (which of course is best since other programs
1661 than LyX will benefit from this as well), you can tell LyX the correct
1663 \begin_inset Flex CharStyle:MenuItem
1666 \begin_layout Plain Layout
1675 \begin_layout Standard
1676 If the text is too small or too big for your taste, you should fiddle with
1677 the font zoom setting.
1678 This setting is used to scale the point size of the text.
1679 If your DPI setting is correct, and the font zoom setting is set to 100,
1680 this means that LyX will try to display the text exactly the same size
1681 as it will appear on the paper-output.
1682 If you set the zoom factor to 200, the text will try to be 2 times as big
1684 Of course, this will only happen if LyX can find a font that has the appropriat
1685 e size, which you can't count on.
1686 Since LyX is a WYSIWYM system anyways, this limitation isn't much of an
1690 \begin_layout Standard
1691 The default font zoom setting is 150, since a monitor is typically wider
1692 than a piece of paper, but you should try to fiddle with it through the
1694 \begin_inset Flex CharStyle:MenuItem
1697 \begin_layout Plain Layout
1699 \begin_inset space ~
1712 \begin_inset Flex CharStyle:MenuItem
1715 \begin_layout Plain Layout
1721 dialog to find a size that you like.
1722 When you've found a setting that seems to work nicely for you (tip: use
1724 \begin_inset Flex CharStyle:MenuItem
1727 \begin_layout Plain Layout
1737 button to keep the dialog open while you experiment), you can make this
1738 setting the default by using the
1739 \begin_inset Flex CharStyle:MenuItem
1742 \begin_layout Plain Layout
1755 \begin_layout Standard
1756 While it is often possible to find a suitable size for the text on the screen,
1757 this doesn't necessarily mean that the fonts are the best ones available
1759 In order to help you get the most out of your system, you can use the font
1760 definition commands to fine-tune the look of the text in greater detail
1764 \begin_layout Subsubsection
1765 Font definition commands
1768 \begin_layout Standard
1769 You can change LyX's screen fonts from within the
1770 \begin_inset Flex CharStyle:MenuItem
1773 \begin_layout Plain Layout
1780 The number of fonts that are available on different systems vary.
1784 \begin_layout Standard
1785 Before you go about scrapping a bitmap font because the larger sizes look
1787 \begin_inset Quotes eld
1791 \begin_inset Quotes erd
1794 , you should toggle the
1795 \begin_inset Flex CharStyle:Code
1798 \begin_layout Plain Layout
1805 This is only useful if you use bitmap fonts, because only these don't scale
1807 If you define this flag, LyX will only use the fixed font sizes that are
1808 available, and this guarantees that all bitmap fonts look good.
1809 However, the downside is that there will be a greater difference between
1810 the size of the fonts on screen and the size of fonts on paper because
1811 LyX will have to be satisfied with the closest available size, and not
1812 try to scale a size to fit.
1813 Also, you can risk that some logically different sizes, such as
1814 \begin_inset Flex CharStyle:MenuItem
1817 \begin_layout Plain Layout
1824 \begin_inset Flex CharStyle:MenuItem
1827 \begin_layout Plain Layout
1833 , will be mapped to the same screen font, making it hard for you to see
1834 the difference on screen.
1838 \begin_layout Standard
1839 One final note regarding the
1840 \begin_inset Flex CharStyle:Code
1843 \begin_layout Plain Layout
1849 flag: you should know that there is nothing wrong with using bitmap and
1850 scalable fonts at the same time for different purposes.
1851 For instance, it's common to use the scalable
1852 \begin_inset Quotes eld
1856 \begin_inset Quotes erd
1859 for the serif text together with a bitmap version of
1860 \begin_inset Quotes eld
1864 \begin_inset Quotes erd
1868 And you can safely select the
1869 \begin_inset Quotes eld
1873 \begin_inset Quotes erd
1876 button without worries: It will only apply to the Helvetica font.
1879 \begin_layout Standard
1880 Sometimes the artifacts introduced by use of the flag can be relieved by
1881 using the fine-detail screen font sizes which defines which point sizes
1882 the different logical font sizes correspond to.
1884 \begin_inset Flex CharStyle:Code
1887 \begin_layout Plain Layout
1893 to see exactly what concrete fonts the logical sizes map to, and try adjusting
1894 the corresponding entries in the
1895 \begin_inset Flex CharStyle:MenuItem
1898 \begin_layout Plain Layout
1904 dialog until you've managed to hit the nail and get the fonts you want.
1905 This can be hard to do, because LyX uses the DPI setting and the font zoom
1906 settings to calculate which exact screen font size to ask the X server
1907 for, thus obfuscating the mapping.
1908 If you can't make it by trial-and-error, you can make the process more
1909 transparent if you set both the DPI setting and font zoom settings to 100---eve
1910 n when this is known to be wrong.
1911 This will of course make your scalable fonts look weird, so use with care.
1914 \begin_layout Standard
1915 \begin_inset Branch OutDated
1918 \begin_layout Subsubsection
1922 \begin_layout Standard
1923 By default, LyX will use fonts meant to write Western European text, including
1924 all kinds of English.
1925 This is defined through the so-called
1934 If you want to use LyX to write for instance Eastern European text, Cyrillic
1935 or any other language not covered by the ISO-8859-1 font encoding, you
1936 can define a different one with the encoding setting.
1937 This requires you to have special fonts installed.
1939 \begin_inset Flex CharStyle:Code
1942 \begin_layout Plain Layout
1948 to see whether this is the case: check the
1949 \begin_inset Quotes eld
1953 \begin_inset Quotes erd
1957 \begin_inset Quotes eld
1961 \begin_inset Quotes erd
1964 fields for ISO-8859-X values different from ISO-8859-1, and search for
1965 one that contains the national characters of your language.
1966 If you find any, enter this encoding in the dialog.
1967 If not, go searching the Web for appropriate fonts.
1968 For the Qt frontend, it's recommended you use an iso646 font set.
1971 \begin_layout Standard
1972 When you've set LyX up to use a different font encoding, you should also
1973 consider changing the font used by dialog windows in LyX.
1975 \begin_inset Flex CharStyle:MenuItem
1978 \begin_layout Plain Layout
1980 \begin_inset space ~
1984 \begin_inset space ~
1992 dialog will not be understandable unless you tell LyX to use a different
1994 By default the menu font is set to
1995 \begin_inset Flex CharStyle:Code
1998 \begin_layout Plain Layout
1999 -*-helvetica-medium-r
2004 , but often Helvetica is not available in the font encoding you need, so
2005 the dialog allows this to be changed.
2008 \begin_layout Standard
2009 As you can see, there are quite a few options that can be used to fine tune
2010 the look of your fonts.
2011 This should not scare you from fiddling with the settings, because after
2012 all, you will hopefully be using LyX for many hours in the future.
2013 And contrary to real WYSIWYG word processors where you are tied to using
2014 fonts that have to look good both on paper and on screen, LyX gives you
2015 the possibility of using fonts that are designed to look good on the screen
2016 while using a different set of fonts to look good on paper.
2024 \begin_layout Subsection
2026 \begin_inset CommandInset label
2035 \begin_layout Standard
2036 The appearance of both the menu and toolbar may both be changed using the
2038 \begin_inset Flex CharStyle:MenuItem
2041 \begin_layout Plain Layout
2048 Simply select a different
2049 \begin_inset Flex CharStyle:Code
2052 \begin_layout Plain Layout
2059 \begin_inset Flex CharStyle:MenuItem
2062 \begin_layout Plain Layout
2063 Look & Feel\SpecialChar \menuseparator
2070 You can customize the interface by copying one of the
2071 \begin_inset Flex CharStyle:Code
2074 \begin_layout Plain Layout
2081 \begin_inset Flex CharStyle:Code
2084 \begin_layout Plain Layout
2091 \begin_inset Flex CharStyle:Code
2094 \begin_layout Plain Layout
2101 You may have to restart LyX for these changes to take effect.
2104 \begin_layout Standard
2106 \begin_inset Flex CharStyle:Code
2109 \begin_layout Plain Layout
2115 files is straightforward: have a look at
2116 \begin_inset Flex CharStyle:Code
2119 \begin_layout Plain Layout
2127 \begin_inset Flex CharStyle:Code
2130 \begin_layout Plain Layout
2137 \begin_inset Flex CharStyle:Code
2140 \begin_layout Plain Layout
2147 \begin_inset Flex CharStyle:Code
2150 \begin_layout Plain Layout
2156 entries must be ended with an explicit
2157 \begin_inset Flex CharStyle:Code
2160 \begin_layout Plain Layout
2168 \begin_inset Flex CharStyle:Code
2171 \begin_layout Plain Layout
2178 \begin_inset Flex CharStyle:Code
2181 \begin_layout Plain Layout
2188 \begin_inset Flex CharStyle:Code
2191 \begin_layout Plain Layout
2198 \begin_inset Flex CharStyle:Code
2201 \begin_layout Plain Layout
2208 \begin_inset Flex CharStyle:Code
2211 \begin_layout Plain Layout
2217 s and in the case of the
2218 \begin_inset Quotes eld
2222 \begin_inset Quotes erd
2226 \begin_inset Flex CharStyle:Code
2229 \begin_layout Plain Layout
2236 One small word of warning.
2238 \begin_inset Flex CharStyle:Code
2241 \begin_layout Plain Layout
2247 s may be inserted in a
2248 \begin_inset Flex CharStyle:Code
2251 \begin_layout Plain Layout
2258 \begin_inset Flex CharStyle:Code
2261 \begin_layout Plain Layout
2267 , but they are defined as
2268 \begin_inset Flex CharStyle:Code
2271 \begin_layout Plain Layout
2278 \begin_inset Flex CharStyle:Code
2281 \begin_layout Plain Layout
2289 \begin_inset Flex CharStyle:Code
2292 \begin_layout Plain Layout
2298 tag is used to insert context-dependent information that is generated by
2300 Unfortunately, the available tags are not documented outside the source
2304 \begin_layout Standard
2305 Note that, as of LyX 1.6, there are extensive context menus, normally accessed
2307 These are defined in the
2308 \begin_inset Flex CharStyle:Code
2311 \begin_layout Plain Layout
2320 \begin_layout Section
2324 \begin_layout Standard
2325 The settings in this section are used to customise the behavior of the LyX
2329 \begin_layout Subsection
2330 \begin_inset CommandInset label
2339 \begin_layout Standard
2340 Bindings are used to associate a LyX function to a key.
2341 Several prepackaged binding files are available: a CUA set of bindings
2342 (familiar as the typical set of PC and CDE set of keyboard shortcuts),
2343 an Emacs set of bindings, for those of us who follow the One True Way and
2344 refuse to lower our standards,
2348 \begin_layout Plain Layout
2349 I'm kidding here, of course!
2354 as well as specialty bindings (broadway and hollywood) and bindings for
2355 languages other than English.
2356 You can select your binding in the
2357 \begin_inset Flex CharStyle:MenuItem
2360 \begin_layout Plain Layout
2361 Editing\SpecialChar \menuseparator
2370 \begin_inset Flex CharStyle:MenuItem
2373 \begin_layout Plain Layout
2378 ools\SpecialChar \menuseparator
2394 \begin_layout Standard
2395 If, however, you'd like to customise the bindings to your own exacting tastes,
2396 then there are two ways to proceed.
2397 The first, and older method, is to copy a file from
2398 \begin_inset Flex CharStyle:Code
2401 \begin_layout Plain Layout
2408 \begin_inset Flex CharStyle:Code
2411 \begin_layout Plain Layout
2417 and modify that in a text editor.
2418 Don't forget to select this file in
2419 \begin_inset Flex CharStyle:MenuItem
2422 \begin_layout Plain Layout
2423 Editing\SpecialChar \menuseparator
2430 The second method is to use the shortcut editor, which you will also find
2432 \begin_inset Flex CharStyle:MenuItem
2435 \begin_layout Plain Layout
2436 Editing\SpecialChar \menuseparator
2443 The changes you make here will be stored at
2444 \begin_inset Flex CharStyle:Code
2447 \begin_layout Plain Layout
2448 UserDir/bind/user.bind
2456 \begin_layout Standard
2457 LyX supports internationalization of the user interface (see Chapter
2458 \begin_inset space ~
2462 \begin_inset CommandInset ref
2464 reference "chap:i18n"
2473 is set, LyX will try to use bindfiles by prepending the standard language
2475 For example, you can put a translated copy of some standard bind file in
2477 \begin_inset Flex CharStyle:Code
2480 \begin_layout Plain Layout
2486 directory, and LyX will use it automatically.
2489 \begin_layout Standard
2491 \begin_inset Flex CharStyle:Code
2494 \begin_layout Plain Layout
2500 files is straightforward:
2503 \begin_layout LyX-Code
2506 bind ``<key combination>'' ``<lyx-function>
2507 \begin_inset Quotes erd
2513 \begin_layout Standard
2514 Both key combination and lyx-function (including any arguments) must be
2515 enclosed in "double quotes".
2516 The LyX functions are partially documented on listed on the
2517 \begin_inset CommandInset href
2520 target "http://wiki.lyx.org/LyX/LyxFunctions"
2525 A major effort is presently underway to improve this documentation.
2528 \begin_layout Section
2529 \begin_inset CommandInset label
2531 name "sec:converters-etc"
2538 \begin_layout Standard
2539 LyX has a powerful mechanism to convert to and from any file format using
2544 \begin_layout Subsection
2545 \begin_inset CommandInset label
2554 \begin_layout Standard
2555 The first step is to define your file formats if they are not already defined.
2557 \begin_inset Flex CharStyle:MenuItem
2560 \begin_layout Plain Layout
2561 Tools\SpecialChar \menuseparator
2562 Preferences\SpecialChar \menuseparator
2563 File Handling\SpecialChar \menuseparator
2571 \begin_inset Flex CharStyle:MenuItem
2574 \begin_layout Plain Layout
2575 New\SpecialChar \ldots{}
2581 button to define your new format.
2583 \begin_inset Flex CharStyle:MenuItem
2586 \begin_layout Plain Layout
2592 field contains the named used to identify the format in the GUI.
2594 \begin_inset Flex CharStyle:MenuItem
2597 \begin_layout Plain Layout
2603 is used to identify the format interally.
2604 You will also need to enter a file extension.
2605 These are all required.
2607 \begin_inset Flex CharStyle:MenuItem
2610 \begin_layout Plain Layout
2616 field is used to provide a keyboard shortcut on the menus.
2617 (For example, pressing
2618 \begin_inset Flex CharStyle:MenuItem
2621 \begin_layout Plain Layout
2628 \begin_inset Flex CharStyle:MenuItem
2631 \begin_layout Plain Layout
2632 View\SpecialChar \menuseparator
2641 \begin_layout Standard
2643 \begin_inset Flex CharStyle:MenuItem
2646 \begin_layout Plain Layout
2653 \begin_inset Flex CharStyle:MenuItem
2656 \begin_layout Plain Layout
2663 For example, you might want to use
2664 \begin_inset Flex CharStyle:MenuItem
2667 \begin_layout Plain Layout
2673 to view PostScript files.
2674 You can enter the command needed to start the program in the corresponding
2676 In defining this command, you can use the four variables listed in the
2678 The viewer is launched when you view an image in LyX or use the
2679 \begin_inset Flex CharStyle:MenuItem
2682 \begin_layout Plain Layout
2689 The editor is for example launched when you press the
2690 \begin_inset Flex CharStyle:MenuItem
2693 \begin_layout Plain Layout
2700 \begin_inset Flex CharStyle:MenuItem
2703 \begin_layout Plain Layout
2710 \begin_inset Flex CharStyle:MenuItem
2713 \begin_layout Plain Layout
2722 \begin_layout Standard
2724 \begin_inset Flex CharStyle:MenuItem
2727 \begin_layout Plain Layout
2733 option tells LyX that a format is suitable for document export.
2734 If this is is set and if a suitable conversion route exists (see
2735 \begin_inset CommandInset ref
2737 reference "sub:Converters"
2741 ), the format will appear in the
2742 \begin_inset Flex CharStyle:MenuItem
2745 \begin_layout Plain Layout
2746 File\SpecialChar \menuseparator
2753 The format will also appear in the
2754 \begin_inset Flex CharStyle:MenuItem
2757 \begin_layout Plain Layout
2763 menu if a viewer is specified for the format.
2764 Pure image formats, such as
2765 \begin_inset Flex CharStyle:Code
2768 \begin_layout Plain Layout
2774 , should not use this option.
2775 Formats that can both represent vector graphics and documents like
2776 \begin_inset Flex CharStyle:Code
2779 \begin_layout Plain Layout
2788 \begin_layout Standard
2790 \begin_inset Flex CharStyle:MenuItem
2793 \begin_layout Plain Layout
2794 Vector graphics format
2799 tells LyX that a format can contain vector graphics.
2800 This information is used to determine the target format of included graphics
2802 \begin_inset Flex CharStyle:MenuItem
2805 \begin_layout Plain Layout
2812 Included graphics may need to be converted to either
2813 \begin_inset Flex CharStyle:MenuItem
2816 \begin_layout Plain Layout
2823 \begin_inset Flex CharStyle:MenuItem
2826 \begin_layout Plain Layout
2833 \begin_inset Flex CharStyle:MenuItem
2836 \begin_layout Plain Layout
2843 \begin_inset Flex CharStyle:MenuItem
2846 \begin_layout Plain Layout
2852 cannot handle other image formats.
2853 If an included graphic is not already in
2854 \begin_inset Flex CharStyle:MenuItem
2857 \begin_layout Plain Layout
2864 \begin_inset Flex CharStyle:MenuItem
2867 \begin_layout Plain Layout
2874 \begin_inset Flex CharStyle:MenuItem
2877 \begin_layout Plain Layout
2883 format, it is converted to
2884 \begin_inset Flex CharStyle:MenuItem
2887 \begin_layout Plain Layout
2893 if the vector format option is set, and otherwise to
2894 \begin_inset Flex CharStyle:MenuItem
2897 \begin_layout Plain Layout
2906 \begin_layout Subsection
2910 \begin_layout Standard
2911 Since all conversions from one format to another take place in LyX's temporary
2912 directory, it is sometimes necessary to modify a file before copying it
2913 to the temporary directory in order that the conversion may be performed.
2917 \begin_layout Plain Layout
2918 For example, the file may refer to other files---images, for example---using
2919 relative filenames, and these may become invalid when the file is copied
2920 to the temporary directory.
2925 This is done by a Copier: It copies a file to (or from) the temporary directory
2926 and may modify it in the process.
2929 \begin_layout Standard
2930 The definitions of the copiers may use four variables:
2933 \begin_layout Labeling
2934 \labelwidthstring 00.00.0000
2935 \begin_inset Flex CharStyle:Code
2938 \begin_layout Plain Layout
2944 The LyX system directory (e.
2945 \begin_inset space \thinspace{}
2949 \begin_inset space ~
2953 \begin_inset Flex CharStyle:MenuItem
2956 \begin_layout Plain Layout
2965 \begin_layout Labeling
2966 \labelwidthstring 00.00.0000
2967 \begin_inset Flex CharStyle:Code
2970 \begin_layout Plain Layout
2979 \begin_layout Labeling
2980 \labelwidthstring 00.00.0000
2981 \begin_inset Flex CharStyle:Code
2984 \begin_layout Plain Layout
2993 \begin_layout Labeling
2994 \labelwidthstring 00.00.0000
2995 \begin_inset Flex CharStyle:Code
2998 \begin_layout Plain Layout
3007 \begin_layout Standard
3008 The latter is to be given in a form suitable for inclusion in a LaTeX's
3015 command and is relevant only when exporting files suitable for such inclusion.
3018 \begin_layout Standard
3019 Copiers can be used to do almost anything with output files.
3020 For example, suppose you want generated pdf files to be copied to a special
3022 \begin_inset Flex CharStyle:Code
3025 \begin_layout Plain Layout
3032 Then you could write a shell script such as this one:
3035 \begin_layout Standard
3036 \begin_inset listings
3040 \begin_layout Plain Layout
3044 \begin_layout Plain Layout
3048 \begin_layout Plain Layout
3049 TOFILE=`basename $2`
3052 \begin_layout Plain Layout
3053 cp $FROMFILE /home/you/pdf/$TOFILE
3058 Save that in your local LyX directory---say,
3059 \begin_inset Flex CharStyle:Code
3062 \begin_layout Plain Layout
3063 /home/you/.lyx/scripts/pdfcopier.sh
3068 ---and make it executable, if you need to do so on your platform.
3070 \begin_inset Flex CharStyle:MenuItem
3073 \begin_layout Plain Layout
3074 Tools\SpecialChar \menuseparator
3081 \begin_inset Flex CharStyle:MenuItem
3084 \begin_layout Plain Layout
3090 format---or one of the other pdf formats---and enter
3091 \begin_inset Flex CharStyle:Code
3094 \begin_layout Plain Layout
3095 pdfcopier.sh $$i $$o
3101 \begin_inset Flex CharStyle:MenuItem
3104 \begin_layout Plain Layout
3114 \begin_layout Standard
3115 Copiers are used by LyX in various of its own conversions.
3116 For example, if appropriate programs are found, LyX will automatically
3117 install copiers for the
3118 \begin_inset Flex CharStyle:MenuItem
3121 \begin_layout Plain Layout
3128 \begin_inset Flex CharStyle:MenuItem
3131 \begin_layout Plain Layout
3133 \begin_inset space ~
3142 When these formats are exported, the copier sees that not just the main
3143 HTML file but various associated files (style files, images, etc.) are also
3145 All these files are written to a subdirectory of the directory in which
3146 the original LyX file was found.
3150 \begin_layout Plain Layout
3151 This copier can be customized.
3153 \begin_inset Quotes eld
3157 \begin_inset Quotes erd
3160 argument takes a comma-separated list of extensions to be copied; if it
3161 is omitted, all files will be copied.
3163 \begin_inset Quotes eld
3167 \begin_inset Quotes erd
3170 argument determines the extension added to the generated directory.
3172 \begin_inset Quotes eld
3176 \begin_inset Flex CharStyle:MenuItem
3179 \begin_layout Plain Layout
3186 \begin_inset Quotes erd
3189 , so HTML generated from
3190 \begin_inset Flex CharStyle:MenuItem
3193 \begin_layout Plain Layout
3194 /path/to/filename.lyx
3200 \begin_inset Flex CharStyle:MenuItem
3203 \begin_layout Plain Layout
3204 /path/to/filename.html.LyXconv
3218 \begin_layout Subsection
3219 \begin_inset CommandInset label
3221 name "sub:Converters"
3228 \begin_layout Standard
3229 You can define your own Converters to, uhh, convert files between different
3232 \begin_inset Flex CharStyle:MenuItem
3235 \begin_layout Plain Layout
3236 Tools\SpecialChar \menuseparator
3237 Preferences\SpecialChar \menuseparator
3238 File Handling\SpecialChar \menuseparator
3247 \begin_layout Standard
3248 To define a new converter, select the
3249 \begin_inset Flex CharStyle:MenuItem
3252 \begin_layout Plain Layout
3254 \begin_inset space ~
3263 \begin_inset space \thinspace{}
3267 \begin_inset Flex CharStyle:MenuItem
3270 \begin_layout Plain Layout
3272 \begin_inset space ~
3280 from the drop-down lists, enter the command needed for the conversion,
3282 \begin_inset Flex CharStyle:MenuItem
3285 \begin_layout Plain Layout
3292 Several variables can be used in the definition of converters:
3295 \begin_layout Labeling
3296 \labelwidthstring 00.00.0000
3297 \begin_inset Flex CharStyle:Code
3300 \begin_layout Plain Layout
3306 The LyX system directory
3309 \begin_layout Labeling
3310 \labelwidthstring 00.00.0000
3311 \begin_inset Flex CharStyle:Code
3314 \begin_layout Plain Layout
3323 \begin_layout Labeling
3324 \labelwidthstring 00.00.0000
3325 \begin_inset Flex CharStyle:Code
3328 \begin_layout Plain Layout
3337 \begin_layout Labeling
3338 \labelwidthstring 00.00.0000
3339 \begin_inset Flex CharStyle:Code
3342 \begin_layout Plain Layout
3348 The base filename of the input file (i.e., without the extension)
3351 \begin_layout Labeling
3352 \labelwidthstring 00.00.0000
3353 \begin_inset Flex CharStyle:Code
3356 \begin_layout Plain Layout
3362 The path to the input file
3365 \begin_layout Standard
3367 \begin_inset Flex CharStyle:MenuItem
3370 \begin_layout Plain Layout
3372 \begin_inset space ~
3380 field you can enter the following flags, separated by commas:
3383 \begin_layout Labeling
3384 \labelwidthstring 00.00.0000
3385 \begin_inset Flex CharStyle:Code
3388 \begin_layout Plain Layout
3394 This converter runs some form of LaTeX.
3395 This will make LyX's LaTeX error logs available.
3398 \begin_layout Labeling
3399 \labelwidthstring 00.00.0000
3400 \begin_inset Flex CharStyle:Code
3403 \begin_layout Plain Layout
3410 \begin_inset Flex CharStyle:MenuItem
3413 \begin_layout Plain Layout
3419 file for the conversion.
3422 \begin_layout Labeling
3423 \labelwidthstring 00.00.0000
3424 \begin_inset Flex CharStyle:Code
3427 \begin_layout Plain Layout
3436 \begin_layout Standard
3437 The following three flags are not really flags at all because they take
3439 \begin_inset Flex CharStyle:MenuItem
3442 \begin_layout Plain Layout
3444 \begin_inset space ~
3448 \begin_inset space ~
3459 \begin_layout Labeling
3460 \labelwidthstring 00.00.0000
3461 \begin_inset Flex CharStyle:Code
3464 \begin_layout Plain Layout
3470 If set, the converter's standard error will be redirected to a file
3471 \begin_inset Flex CharStyle:Code
3474 \begin_layout Plain Layout
3480 , and the script given as argument will be run as:
3481 \begin_inset Flex CharStyle:Code
3484 \begin_layout Plain Layout
3485 script <infile.out >infile.log
3491 The argument may contain
3492 \begin_inset Flex CharStyle:Code
3495 \begin_layout Plain Layout
3504 \begin_layout Labeling
3505 \labelwidthstring 00.00.0000
3506 \begin_inset Flex CharStyle:Code
3509 \begin_layout Plain Layout
3515 The name of the directory in which the converter will dump the generated
3517 LyX will not create this directory, and it does not copy anything into
3518 it, though it will copy this directory to the destination.
3519 The argument may contain
3520 \begin_inset Flex CharStyle:Code
3523 \begin_layout Plain Layout
3529 , which will be replaced by the basename of the input and output files,
3530 respectively, when the directory is copied.
3531 \begin_inset Newline newline
3534 Note that resultdir and usetempdir make no sense together.
3535 The latter will be ignored if the former is given.
3538 \begin_layout Labeling
3539 \labelwidthstring 00.00.0000
3540 \begin_inset Flex CharStyle:Code
3543 \begin_layout Plain Layout
3549 Determines the output filename and may, contain
3550 \begin_inset Flex CharStyle:Code
3553 \begin_layout Plain Layout
3560 Sensible only with resultdir and optional even then; if not given, it defaults
3564 \begin_layout Standard
3565 None of these last three are presently used in any of the converters that
3566 are installed with LyX.
3570 \begin_layout Standard
3571 You do not have to define converters between all the formats between which
3572 you want to convert.
3573 For example, you will note that there is no `LyX to PostScript®' converter,
3574 but LyX will export PostScript®.
3575 It does so by first creating a LaTeX file (no converter needs to be defined
3576 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
3577 and finally converting the resulting DVI file to PostScript®.
3578 LyX finds such `chains' of converters automatically, and it will always
3579 choose the shortest possible chain.
3580 You can, though, still define multiple conversion methods between file
3582 For example, the standard LyX configuration provides three ways to convert
3583 LaTeX to PDF: Directly, using
3584 \begin_inset Flex CharStyle:MenuItem
3587 \begin_layout Plain Layout
3593 ; via (DVI and) PostScript®, using
3594 \begin_inset Flex CharStyle:MenuItem
3597 \begin_layout Plain Layout
3604 \begin_inset Flex CharStyle:MenuItem
3607 \begin_layout Plain Layout
3614 To define such alternate chains, you must define multiple target `file
3615 formats', as described in section
3616 \begin_inset CommandInset ref
3618 reference "sub:Formats"
3623 For example, in the standard configuration, the formats named
3624 \begin_inset Flex CharStyle:MenuItem
3627 \begin_layout Plain Layout
3634 \begin_inset Flex CharStyle:MenuItem
3637 \begin_layout Plain Layout
3644 \begin_inset Flex CharStyle:MenuItem
3647 \begin_layout Plain Layout
3653 are defined, all of which share the extension
3654 \begin_inset Flex CharStyle:MenuItem
3657 \begin_layout Plain Layout
3663 , and which correspond to the conversion methods just mentioned.
3666 \begin_layout Section
3670 \begin_layout Standard
3671 The settings in this section affect the output LyX produces.
3674 \begin_layout Subsection
3675 Plain text export options
3678 \begin_layout Standard
3680 There are a couple of commands that can be used to
3681 \begin_inset Quotes eld
3685 \begin_inset Quotes erd
3688 exported plain text files.
3689 Note that LyX automatically detects and tries to use the best settings
3690 for your system at installation time, but you can modify them in the
3691 \begin_inset Flex CharStyle:MenuItem
3694 \begin_layout Plain Layout
3695 Output\SpecialChar \menuseparator
3701 dialog if you disagree with its interpretation.
3704 \begin_layout Description
3705 \begin_inset Flex CharStyle:Code
3708 \begin_layout Plain Layout
3714 This option defines the command used to produce better plain text tables
3716 \begin_inset Flex CharStyle:Code
3719 \begin_layout Plain Layout
3725 UNIX-commands (refer to their manpages for more information about them).
3726 Setting this as empty tells LyX to use the internal (inferior) formatter.
3729 \begin_layout Description
3730 \begin_inset Flex CharStyle:Code
3733 \begin_layout Plain Layout
3739 With this command you can set the default line length of the plain text
3741 Setting it to 0 means that no line breaks will be inserted except between
3742 paragraphs and the like.
3745 \begin_layout Section
3749 \begin_layout Standard
3750 There are many other configuration options that can be used to customize
3752 Most of them are sufficiently self-explanatory that we have not felt it
3753 necessary to document them here.
3755 \begin_inset CommandInset href
3757 name "mailing lists"
3758 target "http://www.lyx.org/mailing.php"
3762 if you need some more information.
3765 \begin_layout Chapter
3766 Internationalizing LyX
3767 \begin_inset CommandInset label
3776 \begin_layout Standard
3777 LyX supports using a translated interface.
3778 Last time we checked, LyX provided text in thirty languages.
3779 The language of choice is called your
3784 (For further reading on locale settings, see also the documentation for
3785 locale that comes with your operating system.
3786 For Linux, the manual page for
3787 \begin_inset Flex CharStyle:Code
3790 \begin_layout Plain Layout
3796 could be a good place to start).
3799 \begin_layout Standard
3800 Notice that these translations will work, but do contain a few flaws.
3801 In particular, all dialogs have been designed with the English text in
3802 mind, which means that some of the translated text will be too large to
3803 fit within the space allocated.
3804 This is only a display problem and will not cause any harm.
3805 Also, you will find that some of the translations do not define shortcut
3806 keys for everything.
3807 Sometimes, there are simply not enough free letters to do it.
3808 Other times, the translator just hasn't got around to doing it yet.
3809 Our localization team, which you may wish to join,
3813 \begin_layout Plain Layout
3814 If you are a fluent speaker of a language other than English, joining these
3815 teams is a great way to give back to the LyX community!
3820 will of course try to fix these shortcomings in future versions of LyX.
3823 \begin_layout Section
3827 \begin_layout Subsection
3828 Translating the graphical user interface (text messages).
3831 \begin_layout Standard
3833 \begin_inset Flex CharStyle:Code
3836 \begin_layout Plain Layout
3842 library to handle the internationalization of the interface.
3843 To have LyX speak your favorite language in all menus and dialogs, you
3845 \begin_inset Flex CharStyle:Code
3848 \begin_layout Plain Layout
3854 -file for that language.
3855 When this is available, you'll have to generate a
3856 \begin_inset Flex CharStyle:Code
3859 \begin_layout Plain Layout
3865 -file from it and install the
3866 \begin_inset Flex CharStyle:Code
3869 \begin_layout Plain Layout
3876 The process of doing all of this is explained in the documentation for
3878 \begin_inset Flex CharStyle:Code
3881 \begin_layout Plain Layout
3888 It is possible to do this just for yourself, but if you're going to do
3889 it, you might as well share the results of your labors with the rest of
3891 Send a message to the LyX developers' list for more information about how
3895 \begin_layout Standard
3896 In short, this is what you should do (xx denotes the language code):
3899 \begin_layout Itemize
3900 Check out the LyX source code.
3902 \begin_inset CommandInset href
3904 name "information on the web"
3905 target "http://www.lyx.org/devel/cvs.php"
3912 \begin_layout Itemize
3914 \begin_inset Flex CharStyle:Code
3917 \begin_layout Plain Layout
3928 \begin_inset Flex CharStyle:Code
3931 \begin_layout Plain Layout
3938 \begin_inset Flex CharStyle:Code
3941 \begin_layout Plain Layout
3947 doesn't exist, it can be remade with
3948 \begin_inset Flex CharStyle:Code
3951 \begin_layout Plain Layout
3957 in that directory, or you can use an existing po-file for some other language
3961 \begin_layout Itemize
3963 \begin_inset Flex CharStyle:Code
3966 \begin_layout Plain Layout
3976 \begin_layout Plain Layout
3977 This is just a text file, so it can be edited in any text editor.
3978 But there are also specialized programs that support such editing, such
3979 as KBabel (for KDE).
3980 Emacs contains a `mode' for editing
3981 \begin_inset Flex CharStyle:Code
3984 \begin_layout Plain Layout
3995 For some menu- and widget-labels, there are also shortcut keys that should
3997 Those keys are marked after a `|', and should be translated according to
3998 the words and phrases of the language.
3999 You should also fill also out the information at the beginning of the new
4001 \begin_inset Flex CharStyle:Code
4004 \begin_layout Plain Layout
4010 -file with your email-address, etc., so people know where to reach you with
4011 suggestions and entertaining flames.
4014 \begin_layout Standard
4015 If you are just doing this on your own, then:
4018 \begin_layout Itemize
4020 \begin_inset Flex CharStyle:Code
4023 \begin_layout Plain Layout
4030 This can be done with
4031 \begin_inset Flex CharStyle:Code
4034 \begin_layout Plain Layout
4035 msgfmt -o xx.mo < xx.po
4043 \begin_layout Itemize
4045 \begin_inset Flex CharStyle:Code
4048 \begin_layout Plain Layout
4054 -file to your locale-tree, at the correct directory for application messages
4059 xx, and under the name
4060 \begin_inset Flex CharStyle:Code
4063 \begin_layout Plain Layout
4071 \begin_inset Flex CharStyle:Code
4074 \begin_layout Plain Layout
4075 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
4085 \begin_layout Standard
4086 As said, however, it would be best if the new
4087 \begin_inset Flex CharStyle:Code
4090 \begin_layout Plain Layout
4096 -file could be added to the LyX distribution, so others can use it.
4097 Adding it involves making additional changes to LyX.
4098 So send an email to the developers' mailing list if you're interested in
4102 \begin_layout Subsubsection
4106 \begin_layout Standard
4107 Sometimes it turns out that one English message needs to be translated into
4108 different messages in the target language.
4109 One example is the message
4110 \begin_inset Flex CharStyle:Code
4113 \begin_layout Plain Layout
4119 which has the German translation
4127 , depending upon exactly what the English
4128 \begin_inset Quotes eld
4132 \begin_inset Quotes erd
4137 \begin_inset Flex CharStyle:Code
4140 \begin_layout Plain Layout
4146 does not handle such ambigous translations.
4147 Therefore you have to add some context information to the message: Instead
4149 \begin_inset Flex CharStyle:Code
4152 \begin_layout Plain Layout
4159 \begin_inset Flex CharStyle:Code
4162 \begin_layout Plain Layout
4163 To[[as in 'From format x to format y']]
4169 \begin_inset Flex CharStyle:Code
4172 \begin_layout Plain Layout
4173 To[[as in 'From page x to page y']].
4178 Now the two occurences of
4179 \begin_inset Flex CharStyle:Code
4182 \begin_layout Plain Layout
4189 \begin_inset Flex CharStyle:Code
4192 \begin_layout Plain Layout
4198 and can be translated correctly to
4209 \begin_layout Standard
4210 Of course the context information needs to be stripped off the original
4211 message when no translation is used.
4212 Therefore you have to put it in double square brackets at the end of the
4213 message (see the example above).
4214 The translation mechanism of LyX ensures that everything in double square
4215 brackets at the end of messages is removed before displaying the message.
4218 \begin_layout Subsection
4219 Translating the documentation.
4222 \begin_layout Standard
4223 The online documentation (in the
4224 \begin_inset Flex CharStyle:MenuItem
4227 \begin_layout Plain Layout
4237 -menu) can (and should!) be translated.
4238 If there are translated versions of the documentation available
4242 \begin_layout Plain Layout
4243 As of March 2008, at least some of the documents have been translated into
4244 fourteen languages, with the Tutorial available in a few more.
4249 and the locale is set accordingly, these will be used automagically by
4251 LyX looks for translated versions as
4252 \begin_inset Flex CharStyle:Code
4255 \begin_layout Plain Layout
4256 LyXDir/doc/xx_DocName.lyx
4262 \begin_inset Flex CharStyle:Code
4265 \begin_layout Plain Layout
4271 is the code for the language currently in use.
4272 If there are no translated documents, the default English versions will
4274 Note that the translated versions must have the same filenames (
4275 \begin_inset Flex CharStyle:Code
4278 \begin_layout Plain Layout
4284 above) as the original.
4285 If you feel up to translating the documentation (an excellent way to proof-read
4286 the original documentation by the way!), there are a few things you should
4290 \begin_layout Itemize
4292 \begin_inset Flex CharStyle:Code
4295 \begin_layout Plain Layout
4301 , the guide to writing LyX documentation.
4302 Pay special attention to the translator's section.
4305 \begin_layout Itemize
4306 Check out the documentation translation web page at
4307 \begin_inset CommandInset href
4309 name "http://www.devel.lyx.org"
4310 target "http://www.devel.lyx.org"
4315 That way, you can find out which (if any) documents have already been translate
4316 d into your language.
4317 You can also find out who (if anyone) is organizing the effort to translate
4318 the documentation into your language.
4319 If no one is organizing the effort, please let us know that you're interested.
4322 \begin_layout Standard
4323 Once you get to actually translating, here's a few hints for you that may
4327 \begin_layout Itemize
4328 Join the documentation team! There is information on how to do that in
4329 \begin_inset Flex CharStyle:Code
4332 \begin_layout Plain Layout
4339 \begin_inset Flex CharStyle:MenuItem
4342 \begin_layout Plain Layout
4347 elp\SpecialChar \menuseparator
4357 ), which by the way is the first document you should translate.
4360 \begin_layout Itemize
4361 Learn the typographic conventions for the language you are translating to.
4362 Typography is an ancient art and over the centuries, a great variety of
4363 conventions have developed throughout different parts of the world.
4364 Also study the professional terminology amongst typographers in your country.
4365 Inventing your own terminology will only confuse the users.
4368 (Warning! Typography is addictive!)
4371 \begin_layout Itemize
4372 Make a copy of the document.
4373 This will be your working copy.
4374 You can use this as your personal translated help-file by placing it in
4376 \begin_inset Flex CharStyle:Code
4379 \begin_layout Plain Layout
4388 \begin_layout Itemize
4389 Sometimes the original document (from the LyX-team) will be updated.
4390 Use the source viewer at
4391 \begin_inset CommandInset href
4393 name "http://www.lyx.org/trac/timeline"
4394 target "http://www.lyx.org/trac/timeline"
4398 to see what has been changed.
4399 That way you can easily see which parts of the translated document need
4403 \begin_layout Standard
4404 If you ever find an error in the original document, fix it and notify the
4405 rest of the documentation team of the changes! (You didn't forget to join
4406 the documentation team, did you?)
4409 \begin_layout Standard
4410 \begin_inset Branch OutDated
4413 \begin_layout Section
4414 International Keyboard Support
4417 \begin_layout Standard
4420 [Editor's Note: The following section is by
4428 It needs to be fixed to conform to the new Documentation Style sheet and
4429 to make use of the new v1.0 features.
4430 The whole thing also needs to be merged with the section following it.-jw
4431 It may also be badly out of date.-rh (2008)]
4434 \begin_layout Subsection
4435 Defining Own Keymaps: Keymap File Format
4438 \begin_layout Standard
4439 Let's look at a keyboard definition file a little closer.
4440 It is a plain text file defining
4443 \begin_layout Itemize
4444 key-to-key or key-to-string translations
4447 \begin_layout Itemize
4451 \begin_layout Itemize
4452 dead keys exceptions
4455 \begin_layout Standard
4456 To define key-to-key or key-to-string translation, use this command:
4459 \begin_layout Quotation
4460 \begin_inset Flex CharStyle:Code
4463 \begin_layout Plain Layout
4472 \begin_inset Flex CharStyle:Code
4475 \begin_layout Plain Layout
4484 \begin_layout Standard
4486 \begin_inset Flex CharStyle:Code
4489 \begin_layout Plain Layout
4495 is the key to be translated and
4496 \begin_inset Flex CharStyle:Code
4499 \begin_layout Plain Layout
4505 is the string to be inserted into the document.
4506 To define dead keys, use:
4509 \begin_layout Quotation
4510 \begin_inset Flex CharStyle:Code
4513 \begin_layout Plain Layout
4522 \begin_inset Flex CharStyle:Code
4525 \begin_layout Plain Layout
4534 \begin_layout Standard
4536 \begin_inset Flex CharStyle:Code
4539 \begin_layout Plain Layout
4545 is a keyboard key and
4546 \begin_inset Flex CharStyle:Code
4549 \begin_layout Plain Layout
4556 The following dead keys are supported (shortcut name is in parentheses):
4559 \begin_layout Quotation
4563 \begin_inset space \hfill{}
4569 \begin_layout Quotation
4571 \begin_inset space \hfill{}
4577 \begin_layout Quotation
4579 \begin_inset space \hfill{}
4585 \begin_layout Quotation
4587 \begin_inset space \hfill{}
4593 \begin_layout Quotation
4595 \begin_inset space \hfill{}
4601 \begin_layout Quotation
4603 \begin_inset space \hfill{}
4610 \begin_layout Plain Layout
4622 \begin_layout Quotation
4624 \begin_inset space \hfill{}
4630 \begin_layout Quotation
4632 \begin_inset space \hfill{}
4639 \begin_layout Plain Layout
4651 \begin_layout Quotation
4653 \begin_inset space \hfill{}
4659 \begin_layout Quotation
4661 \begin_inset space \hfill{}
4667 \begin_layout Quotation
4669 \begin_inset space \hfill{}
4676 \begin_layout Plain Layout
4688 \begin_layout Quotation
4690 \begin_inset space \hfill{}
4697 \begin_layout Plain Layout
4709 \begin_layout Quotation
4711 \begin_inset space \hfill{}
4717 \begin_layout Quotation
4718 hungarian umlaut (hug)
4719 \begin_inset space \hfill{}
4725 \begin_layout Quotation
4727 \begin_inset space \hfill{}
4733 \begin_layout Quotation
4735 \begin_inset space \hfill{}
4742 \begin_layout Plain Layout
4754 \begin_layout Standard
4755 Since in many international keyboards there are exceptions to what some
4756 dead keys should do, you can define them using
4759 \begin_layout Quotation
4760 \begin_inset Flex CharStyle:Code
4763 \begin_layout Plain Layout
4771 deadkey key outstring
4774 \begin_layout Standard
4775 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
4779 \begin_layout Quotation
4780 \begin_inset Flex CharStyle:Code
4783 \begin_layout Plain Layout
4796 \begin_layout Standard
4797 to make it work correctly.
4798 Also, you have to define as exceptions dead keys over i and j, to remove
4799 the dot from them before inserting an accent mark.
4800 I will change this when the time comes, but so far I haven't had time.
4803 \begin_layout Standard
4804 Oh, and about characters: backslash is escaped, so to enter it, you'll need
4807 \begin_inset Flex CharStyle:Code
4810 \begin_layout Plain Layout
4816 have different meaning.
4818 \begin_inset Flex CharStyle:Code
4821 \begin_layout Plain Layout
4827 marks comments, quotes start and end LaTeX-style commands.
4828 To enter quote, you'll need to use
4829 \begin_inset Flex CharStyle:Code
4832 \begin_layout Plain Layout
4841 \begin_inset Flex CharStyle:Code
4844 \begin_layout Plain Layout
4851 \begin_inset Flex CharStyle:Code
4854 \begin_layout Plain Layout
4865 \begin_layout Standard
4866 If you make a keyboard description file that works for your language, please
4867 mail it to me, so I can include it in the next keymap distribution.
4870 \begin_layout Standard
4871 More keywords will be supported in keymap configuration file in future,
4875 \begin_layout Itemize
4876 \begin_inset Flex CharStyle:Code
4879 \begin_layout Plain Layout
4890 \begin_inset space \hfill{}
4894 \begin_inset Flex CharStyle:Code
4897 \begin_layout Plain Layout
4906 \begin_layout Itemize
4907 \begin_inset Flex CharStyle:Code
4910 \begin_layout Plain Layout
4921 \begin_inset space \hfill{}
4925 \begin_inset Flex CharStyle:Code
4928 \begin_layout Plain Layout
4934 an external keymap translation program
4937 \begin_layout Standard
4938 Also, it should look into
4939 \begin_inset Flex CharStyle:Code
4942 \begin_layout Plain Layout
4948 file for defaults, too (for example, a
4949 \begin_inset Flex CharStyle:Code
4952 \begin_layout Plain Layout
4960 option to include default keyboard).
4968 \begin_layout Section
4969 \begin_inset CommandInset label
4975 International Keymap Stuff
4978 \begin_layout Standard
4979 \begin_inset Note Note
4982 \begin_layout Plain Layout
4983 In doing the revisions on this document in March 2008, I did not look over
4984 this stuff, as I do not understand it.
4985 It would be good if someone else could do so.
4993 \begin_layout Standard
4994 The next two sections describe the
4995 \begin_inset Flex CharStyle:Code
4998 \begin_layout Plain Layout
5007 \begin_inset Flex CharStyle:Code
5010 \begin_layout Plain Layout
5018 file syntax in detail.
5019 These sections should help you design your own key map if the ones provided
5020 do not meet your needs.
5023 \begin_layout Subsection
5027 \begin_layout Standard
5031 \begin_inset Flex CharStyle:Code
5034 \begin_layout Plain Layout
5040 file maps keystrokes to characters or strings.
5041 As the name suggests, it sets a keyboard mapping.
5043 \begin_inset Flex CharStyle:Code
5046 \begin_layout Plain Layout
5057 \begin_inset Flex CharStyle:Code
5060 \begin_layout Plain Layout
5075 \begin_inset Flex CharStyle:Code
5078 \begin_layout Plain Layout
5091 \begin_inset Flex CharStyle:Code
5094 \begin_layout Plain Layout
5103 \begin_inset Flex CharStyle:Code
5106 \begin_layout Plain Layout
5114 are described in this section.
5117 \begin_layout Labeling
5118 \labelwidthstring 00.00.0000
5119 \begin_inset Flex CharStyle:Code
5122 \begin_layout Plain Layout
5130 Map a character to a string
5133 \begin_layout LyX-Code
5148 \begin_layout Standard
5181 the double-quote (")
5198 must be escaped with a preceding backslash (
5209 \begin_layout Standard
5211 \begin_inset Flex CharStyle:MenuItem
5214 \begin_layout Plain Layout
5222 statement to cause the symbol
5223 \begin_inset Flex CharStyle:MenuItem
5226 \begin_layout Plain Layout
5234 to be output for the keystroke
5235 \begin_inset Flex CharStyle:MenuItem
5238 \begin_layout Plain Layout
5249 \begin_layout LyX-Code
5255 \begin_layout Labeling
5256 \labelwidthstring 00.00.0000
5257 \begin_inset Flex CharStyle:Code
5260 \begin_layout Plain Layout
5268 Specify an accent character
5271 \begin_layout LyX-Code
5280 \begin_layout Standard
5281 This will make the cha
5319 This is the dead key
5323 \begin_layout Plain Layout
5330 refers to a key that does not produce a character by itself, but when followed
5331 with another key, produces the desired accent character.
5332 For example, a German characte
5334 r with an umlaut like
5344 can be produced in this manner.
5353 \begin_layout Standard
5366 and then another key not in
5383 followed by the other, unallowed key, as output.
5387 \begin_inset Flex CharStyle:MenuItem
5390 \begin_layout Plain Layout
5398 cancels a dead key, so if
5409 \begin_inset Flex CharStyle:MenuItem
5412 \begin_layout Plain Layout
5421 , the cursor will not go one position backwards but will instead cancel
5437 might have had on the next keystroke.
5441 \begin_layout Standard
5442 The following example specifies that the character ' is to be an acute accent,
5443 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
5446 \begin_layout LyX-Code
5449 kmod ' acute aeiouAEIOU
5452 \begin_layout Labeling
5453 \labelwidthstring 00.00.0000
5454 \begin_inset Flex CharStyle:Code
5457 \begin_layout Plain Layout
5463 Specify an exception to the accent character
5466 \begin_layout LyX-Code
5475 \begin_layout Standard
5476 This defines an exce
5517 have been assigned a keystroke with a previous
5520 \begin_inset Flex CharStyle:Code
5523 \begin_layout Plain Layout
5547 must not belong in the
5599 If such a declaration does not exist in
5607 \begin_inset Flex CharStyle:Code
5610 \begin_layout Plain Layout
5650 \begin_inset Flex CharStyle:Code
5653 \begin_layout Plain Layout
5667 \begin_layout Standard
5668 The following command produces causes äi to be produced when you enter acute-i
5672 \begin_layout LyX-Code
5686 \begin_layout Labeling
5687 \labelwidthstring 00.00.0000
5688 \begin_inset Flex CharStyle:Code
5691 \begin_layout Plain Layout
5697 Combine two accent characters
5700 \begin_layout LyX-Code
5706 accent1 accent2 allowed
5709 \begin_layout Standard
5710 This one is getting pretty esoteric.
5711 It allows you to combine the effect
5767 \begin_inset Flex CharStyle:Code
5770 \begin_layout Plain Layout
5798 \begin_layout Standard
5799 Consider this example from the
5800 \begin_inset Flex CharStyle:Code
5803 \begin_layout Plain Layout
5814 \begin_layout LyX-Code
5817 kmod ; acute aeioyvhAEIOYVH
5821 kcomb acute umlaut iyIY
5824 \begin_layout Standard
5825 This allows you to press
5826 \begin_inset Flex CharStyle:MenuItem
5829 \begin_layout Plain Layout
5837 and get the effect of
5838 \begin_inset Flex CharStyle:Code
5841 \begin_layout Plain Layout
5860 in this case cancels the last dead key, so if you press
5861 \begin_inset Flex CharStyle:MenuItem
5864 \begin_layout Plain Layout
5873 \begin_inset Flex CharStyle:Code
5876 \begin_layout Plain Layout
5889 \begin_layout Subsection
5893 \begin_layout Standard
5895 \begin_inset Flex CharStyle:Code
5898 \begin_layout Plain Layout
5906 mapping is performed, a
5907 \begin_inset Flex CharStyle:Code
5910 \begin_layout Plain Layout
5920 file maps the strings that the symbols generate to characters in the current
5922 The LyX distribution currently includes at least the
5923 \begin_inset Flex CharStyle:Code
5926 \begin_layout Plain Layout
5935 \begin_inset Flex CharStyle:Code
5938 \begin_layout Plain Layout
5949 \begin_layout Standard
5951 \begin_inset Flex CharStyle:Code
5954 \begin_layout Plain Layout
5962 file is a sequence of declarations of the form
5965 \begin_layout LyX-Code
5978 \begin_layout Standard
5979 For example, in order to map
5980 \begin_inset Flex CharStyle:MenuItem
5983 \begin_layout Plain Layout
5993 to the corresponding character in the iso-8859-1 set (233), the following
5997 \begin_layout LyX-Code
6005 \begin_layout Standard
6007 \begin_inset Flex CharStyle:Code
6010 \begin_layout Plain Layout
6019 \begin_inset Flex CharStyle:Code
6022 \begin_layout Plain Layout
6040 the same character can apply to more than one string.
6042 \begin_inset Flex CharStyle:Code
6045 \begin_layout Plain Layout
6056 \begin_layout LyX-Code
6068 \begin_inset Newline newline
6084 \begin_layout Standard
6085 If LyX cannot find a mapping for the string produced by the keystroke or
6086 a deadkey sequence, it will check if it looks like an accented char and
6087 try to draw an accent over the character on screen.
6090 \begin_layout Subsection
6094 \begin_layout Standard
6095 There is a second way to add support for international characters through
6096 so-called dead-keys.
6097 A dead-key works in combination with a letter to produce an accented character.
6098 Here, we'll explain how to create a really simple dead-key to illustrate
6102 \begin_layout Standard
6103 Suppose you happen to need the circumflex character,
6104 \begin_inset Quotes eld
6108 \begin_inset Quotes erd
6113 \begin_inset Flex CharStyle:MenuItem
6116 \begin_layout Plain Layout
6123 \begin_inset space ~
6127 \begin_inset Flex CharStyle:MenuItem
6130 \begin_layout Plain Layout
6136 ] to the LyX command
6137 \begin_inset Flex CharStyle:Code
6140 \begin_layout Plain Layout
6147 \begin_inset Flex CharStyle:Code
6150 \begin_layout Plain Layout
6157 Now, whenever you type the
6158 \begin_inset Flex CharStyle:MenuItem
6161 \begin_layout Plain Layout
6167 -key followed by a letter, that letter will have a circumflex accent on
6169 For example, the sequence
6170 \begin_inset Quotes eld
6174 \begin_inset Flex CharStyle:MenuItem
6177 \begin_layout Plain Layout
6184 \begin_inset Quotes erd
6187 produces the letter:
6188 \begin_inset Quotes eld
6192 \begin_inset Quotes erd
6196 If you tried to type
6197 \begin_inset Quotes eld
6201 \begin_inset Flex CharStyle:MenuItem
6204 \begin_layout Plain Layout
6211 \begin_inset Quotes erd
6214 , however, LyX will complain with a beep, since a
6215 \begin_inset Quotes eld
6219 \begin_inset Flex CharStyle:MenuItem
6222 \begin_layout Plain Layout
6229 \begin_inset Quotes erd
6232 never takes a circumflex accent.
6234 \begin_inset Flex CharStyle:MenuItem
6237 \begin_layout Plain Layout
6243 after a dead-key produces the bare-accent.
6244 Please note this last point! If you bind a key to a dead-key, you'll need
6245 to rebind the character on that key to yet another key.
6247 \begin_inset Flex CharStyle:MenuItem
6250 \begin_layout Plain Layout
6256 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
6259 \begin_layout Standard
6260 One common way to bind dead-keys is to use
6261 \begin_inset Flex CharStyle:MenuItem
6264 \begin_layout Plain Layout
6271 \begin_inset Flex CharStyle:MenuItem
6274 \begin_layout Plain Layout
6281 \begin_inset Flex CharStyle:MenuItem
6284 \begin_layout Plain Layout
6290 in combination with an accent, like
6291 \begin_inset Quotes eld
6295 \begin_inset Flex CharStyle:MenuItem
6298 \begin_layout Plain Layout
6305 \begin_inset Quotes erd
6309 \begin_inset Quotes eld
6313 \begin_inset Flex CharStyle:MenuItem
6316 \begin_layout Plain Layout
6323 \begin_inset Quotes erd
6327 \begin_inset Quotes eld
6331 \begin_inset Flex CharStyle:MenuItem
6334 \begin_layout Plain Layout
6341 \begin_inset Quotes erd
6345 Another way involves using
6346 \begin_inset Flex CharStyle:Code
6349 \begin_layout Plain Layout
6356 \begin_inset Flex CharStyle:Code
6359 \begin_layout Plain Layout
6365 to set up the special
6366 \begin_inset Flex CharStyle:Code
6369 \begin_layout Plain Layout
6377 \begin_inset Flex CharStyle:Code
6380 \begin_layout Plain Layout
6386 acts in some ways just like
6387 \begin_inset Flex CharStyle:MenuItem
6390 \begin_layout Plain Layout
6396 and permits you to bind keys to accented characters.
6397 You can also turn keys into dead-keys by binding them to something like
6399 \begin_inset Flex CharStyle:Code
6402 \begin_layout Plain Layout
6408 and then binding this symbolic key to the corresponding LyX command.
6412 \begin_layout Plain Layout
6417 : This is exactly what I do in my
6418 \begin_inset Flex CharStyle:Code
6421 \begin_layout Plain Layout
6428 \begin_inset Flex CharStyle:Code
6431 \begin_layout Plain Layout
6439 \begin_inset Flex CharStyle:MenuItem
6442 \begin_layout Plain Layout
6444 \begin_inset space ~
6453 \begin_inset Flex CharStyle:Code
6456 \begin_layout Plain Layout
6462 and a bunch of these
6463 \begin_inset Quotes eld
6467 \begin_inset Flex CharStyle:Code
6470 \begin_layout Plain Layout
6477 \begin_inset Quotes erd
6480 symbolic keys bound such things as
6481 \begin_inset Flex CharStyle:MenuItem
6484 \begin_layout Plain Layout
6486 \begin_inset space ~
6495 \begin_inset Flex CharStyle:MenuItem
6498 \begin_layout Plain Layout
6500 \begin_inset space ~
6509 This is how I produce my accented characters.
6514 You can make just about anything into the
6515 \begin_inset Flex CharStyle:Code
6518 \begin_layout Plain Layout
6525 \begin_inset Flex CharStyle:MenuItem
6528 \begin_layout Plain Layout
6534 keys, a spare function key, etc.
6535 As for the LyX commands that produce accents, check the entry for
6536 \begin_inset Flex CharStyle:Code
6539 \begin_layout Plain Layout
6550 You'll find the complete list there.
6553 \begin_layout Subsection
6554 Saving your Language Configuration
6557 \begin_layout Standard
6558 \begin_inset CommandInset label
6564 You can edit your preferences so that your desired language environment
6565 is automatically configured when LyX starts up, via the
6566 \begin_inset Flex CharStyle:MenuItem
6569 \begin_layout Plain Layout
6574 dit\SpecialChar \menuseparator
6587 \begin_layout Chapter
6588 Installing New Document Classes, Layouts, and Templates
6589 \begin_inset CommandInset label
6591 name "chap:textclass"
6599 \begin_layout Plain Layout
6600 Installing New Document Classes
6608 \begin_layout Standard
6609 In this chapter, we describe the procedures for creating and installing
6610 new LyX layout and template files, as well as offer a refresher on correctly
6611 installing new LaTeX document classes.
6612 Some definitions: a document class is a LaTeX file (usually ending in
6613 \begin_inset Flex CharStyle:Code
6616 \begin_layout Plain Layout
6623 \begin_inset Flex CharStyle:Code
6626 \begin_layout Plain Layout
6632 ) that describes the format of a document such as an article, report, journal
6633 preprint, etc, and all the commands needed to realize that format.
6634 A layout file is a LyX file that corresponds to a LaTeX document class
6635 and that tells LyX how to
6636 \begin_inset Quotes eld
6640 \begin_inset Quotes erd
6643 things on the screen to make the display look something like the final
6645 More precisely, a layout file describes a
6646 \begin_inset Quotes eld
6650 \begin_inset Quotes erd
6653 which is the internal construct LyX uses to render the screen display.
6655 \begin_inset Quotes eld
6659 \begin_inset Quotes erd
6663 \begin_inset Quotes eld
6667 \begin_inset Quotes erd
6670 can be used somewhat interchangeably, but it is better to refer to the
6671 file as the layout, and the thing living in LyX's memory as the text class.
6672 A template file is simply a LyX document that contains a set of predefined
6673 entries for a given document class---entries that are generally required
6675 Templates are especially useful for things like journal manuscripts that
6676 are to be submitted electronically.
6679 \begin_layout Section
6680 Installing a new LaTeX package
6683 \begin_layout Standard
6684 Some installations may not include a LaTeX package that you would like to
6686 For example, you might need FoilTeX, a common (and very powerful) package
6687 for preparing slides or viewgraphs for overhead projectors.
6688 On some systems, you may have a GUI for installing such packages: MikTeX
6689 on Windows®, for example.
6692 \begin_layout Standard
6693 If you don't have such a GUI, then you can follow these steps.
6696 \begin_layout Enumerate
6697 Get the package from
6698 \begin_inset CommandInset href
6701 target "http://www.ctan.org/"
6708 \begin_layout Enumerate
6709 You can install this package in several different places.
6710 If you want it to be available for all users on your system, then you should
6711 install it in your `local' TeX tree; if you want (or need) it to be available
6712 just for you, then you can install it in your own `user' TeX tree.
6713 Where these should be created, if they do not already exist, depends upon
6714 the details of your system.
6715 To find out, look in the file
6716 \begin_inset Flex CharStyle:Code
6719 \begin_layout Plain Layout
6729 \begin_layout Plain Layout
6730 This usually lives in the directory
6731 \begin_inset Flex CharStyle:Code
6734 \begin_layout Plain Layout
6740 , though you can run
6741 \begin_inset Flex CharStyle:Code
6744 \begin_layout Plain Layout
6755 The location of the `local' TeX tree is defined by
6756 \begin_inset Flex CharStyle:Code
6759 \begin_layout Plain Layout
6765 ; this is usually somewhere like
6766 \begin_inset Flex CharStyle:Code
6769 \begin_layout Plain Layout
6770 /usr/local/share/texmf/
6776 The `user' TeX tree is defined by
6777 \begin_inset Flex CharStyle:Code
6780 \begin_layout Plain Layout
6787 \begin_inset Flex CharStyle:Code
6790 \begin_layout Plain Layout
6797 (If these variables are not predefined, you can define them.) You'll probably
6798 need root permissions to create or modify the `local' tree; but your `user'
6799 tree shouldn't have such limitations.
6802 \begin_layout Enumerate
6804 \begin_inset Flex CharStyle:Code
6807 \begin_layout Plain Layout
6814 \begin_inset Flex CharStyle:Code
6817 \begin_layout Plain Layout
6824 \begin_inset Flex CharStyle:Code
6827 \begin_layout Plain Layout
6835 \begin_inset Newline newline
6839 \begin_inset Flex CharStyle:Code
6842 \begin_layout Plain Layout
6843 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
6849 \begin_inset Newline newline
6852 But, again, most of this will
6853 \begin_inset Quotes eld
6857 \begin_inset Quotes erd
6863 \begin_layout Enumerate
6868 \begin_layout Plain Layout
6869 We'll assume henceforth that you're defining `local' TeX tree.
6870 If you're defining a user tree, just adjust as necessary.
6876 You must follow the directory structure of your existing
6877 \begin_inset Flex CharStyle:Code
6880 \begin_layout Plain Layout
6886 directory, which will be found at
6887 \begin_inset Flex CharStyle:Code
6890 \begin_layout Plain Layout
6897 For example, latex packages should go under
6898 \begin_inset Flex CharStyle:Code
6901 \begin_layout Plain Layout
6902 $TEXMFLOCAL/tex/latex/
6910 \begin_layout Enumerate
6911 Install the package.
6912 For example, you would unpack the FoilTeX tarball and copy it to
6913 \begin_inset Flex CharStyle:Code
6916 \begin_layout Plain Layout
6917 $TEXMFLOCAL/tex/latex/foiltex
6924 \begin_inset Flex CharStyle:Code
6927 \begin_layout Plain Layout
6933 directory contains various files.
6936 \begin_layout Enumerate
6938 \begin_inset Flex CharStyle:Code
6941 \begin_layout Plain Layout
6949 \begin_inset Flex CharStyle:Code
6952 \begin_layout Plain Layout
6961 \begin_layout Standard
6962 Your package is now installed and available to LaTeX.
6963 To make it available to LyX, you need to create a Layout file, if one is
6964 not already available.
6965 (See the next section.) Once you have a layout file, you need only reconfigure
6967 \begin_inset Flex CharStyle:MenuItem
6970 \begin_layout Plain Layout
6975 ools\SpecialChar \menuseparator
6985 ) and then restart LyX.
6986 You should then see your new package---for example
6987 \begin_inset Flex CharStyle:MenuItem
6990 \begin_layout Plain Layout
6997 \begin_inset Flex CharStyle:MenuItem
7000 \begin_layout Plain Layout
7005 ocument\SpecialChar \menuseparator
7016 \begin_inset Flex CharStyle:MenuItem
7019 \begin_layout Plain Layout
7029 \begin_layout Section
7030 \begin_inset CommandInset label
7039 \begin_layout Standard
7040 This section describes how to write and install your own LyX layout files
7041 and walks through the
7042 \begin_inset Flex CharStyle:Code
7045 \begin_layout Plain Layout
7051 text class format as an example.
7053 \begin_inset Flex CharStyle:Code
7056 \begin_layout Plain Layout
7062 files describe what paragraph and character styles are available for a
7063 given document class and how LyX should display them.
7064 We try to provide a thorough description of the process here; however,
7065 there are so many different types of documents supported by LaTeX classes
7066 that we can't hope to cover every different possibility or problem you
7068 (The LyX users' list is frequented by people with lots of experience with
7069 layout design who are willing to share what they've learned.)
7072 \begin_layout Standard
7073 As you prepare to write a new layout, it is extremely helpful to look at
7074 the example layouts distributed with LyX.
7075 If you use a nice LaTeX document class that might be of interest for others,
7076 too, and have a nice corresponding LyX layout, feel free to contribute
7077 the stuff to us, so we may put it into the distribution.
7079 \begin_inset CommandInset href
7081 name "section on the LyX wiki"
7082 target "http://wiki.lyx.org/Layouts/Layouts"
7086 for this kind of material.
7089 \begin_layout Standard
7090 All the tags described in this chapter are case-insensitive; this means
7092 \begin_inset Flex CharStyle:Code
7095 \begin_layout Plain Layout
7102 \begin_inset Flex CharStyle:Code
7105 \begin_layout Plain Layout
7112 \begin_inset Flex CharStyle:Code
7115 \begin_layout Plain Layout
7121 are really the same command.
7122 The possible values are printed in brackets after the feature's name.
7123 The default value if a feature isn't specified inside a text class-description
7125 \begin_inset Flex CharStyle:Code
7128 \begin_layout Plain Layout
7137 If the argument has a datatype like
7138 \begin_inset Quotes eld
7142 \begin_inset Quotes erd
7146 \begin_inset Quotes eld
7150 \begin_inset Quotes erd
7153 , the default is shown like this:
7154 \begin_inset Flex CharStyle:Code
7157 \begin_layout Plain Layout
7168 \begin_layout Subsection
7169 \begin_inset CommandInset label
7171 name "sub:Layout-modules"
7178 \begin_layout Standard
7179 Similar to layout files, and new with LyX 1.6, are layout
7184 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
7185 some modules---such as the Endnotes module---provide support for just such
7187 In a sense, layout modules are similar to included files---files like
7188 \begin_inset Flex CharStyle:Code
7191 \begin_layout Plain Layout
7197 ---in that modules are not specific to a given document layout but may be
7198 used with many different layouts.
7199 The difference is that using a layout module does not require editing the
7201 Rather, modules are selected in the
7202 \begin_inset Flex CharStyle:MenuItem
7205 \begin_layout Plain Layout
7210 ocument\SpecialChar \menuseparator
7223 \begin_layout Standard
7224 Building modules is the easiest way to get started with layout editing,
7225 since it can be as simple as adding a single new paragraph or flex inset.
7226 But modules may, in principle, contain anything a layout file can contain.
7229 \begin_layout Standard
7230 A module must begin with a line like the following:
7233 \begin_layout LyX-Code
7236 DeclareLyXModule[endnotes.sty]{Endnotes}
7239 \begin_layout Standard
7240 The argument in square brackets is optional: It declares any LaTeX packages
7241 on which the module depends.
7242 The mandatory argument, in curly brackets, is the name of the module, as
7244 \begin_inset Flex CharStyle:MenuItem
7247 \begin_layout Plain Layout
7248 Document\SpecialChar \menuseparator
7258 \begin_layout Standard
7259 The module declaration should then be followed by lines like the following:
7262 \begin_layout LyX-Code
7266 \begin_layout LyX-Code
7267 #Adds an endnote command, in addition to footnotes.
7271 \begin_layout LyX-Code
7272 #You will need to add
7274 theendnotes in ERT where you
7277 \begin_layout LyX-Code
7278 #want the endnotes to appear.
7282 \begin_layout LyX-Code
7286 \begin_layout LyX-Code
7287 #Requires: somemodule | othermodule
7290 \begin_layout LyX-Code
7291 #Excludes: badmodule
7294 \begin_layout Standard
7295 The description is used in
7296 \begin_inset Flex CharStyle:MenuItem
7299 \begin_layout Plain Layout
7300 Document\SpecialChar \menuseparator
7306 to provide the user with information about what the module does.
7308 \begin_inset Flex CharStyle:Code
7311 \begin_layout Plain Layout
7317 line is used to identify other modules with which this one must be used;
7319 \begin_inset Flex CharStyle:Code
7322 \begin_layout Plain Layout
7328 line is used to identify modules with which this one may not be used.
7329 Both are optional, and, as shown, multiple modules should be separated
7330 with the pipe symbol: |.
7331 Note that the required modules are treated disjunctively:
7335 of the required modules must be used.
7340 excluded module may be used.
7341 Note that modules are identified here by their
7345 without the .module extension.
7347 \begin_inset Flex CharStyle:Code
7350 \begin_layout Plain Layout
7357 \begin_inset Flex CharStyle:Code
7360 \begin_layout Plain Layout
7369 \begin_layout Standard
7370 After creating a new module, you will need to reconfigure and then restart
7371 LyX for the module to appear in the menu.
7372 However, changes you make to the module will be seen immediately, if you
7374 \begin_inset Flex CharStyle:MenuItem
7377 \begin_layout Plain Layout
7378 Document\SpecialChar \menuseparator
7384 , highlight something, and then hit
7385 \begin_inset Quotes eld
7389 \begin_inset Quotes erd
7395 It is strongly recommended that you save your work before doing so
7400 it is strongly recommended that you not attempt to edit modules while simultaneo
7401 usly working on documents
7404 Though of course the developers strive to keep LyX stable in such situations,
7405 syntax errors and the like in your module file could cause strange behavior.
7408 \begin_layout Subsection
7409 Supporting new document classes
7412 \begin_layout Standard
7413 There are two situations you are likely to encounter when wanting to support
7414 a new LaTeX document class, involving LaTeX2e class (
7415 \begin_inset Flex CharStyle:Code
7418 \begin_layout Plain Layout
7425 \begin_inset Flex CharStyle:Code
7428 \begin_layout Plain Layout
7435 Supporting a style file is usually fairly easy.
7436 Supporting a new document class is a bit harder.
7439 \begin_layout Subsection
7441 \begin_inset Flex CharStyle:MenuItem
7444 \begin_layout Plain Layout
7453 \begin_layout Standard
7454 If your new document class is provided as a style file that is used in conjuncti
7455 on with an existing, supported document class---for the sake of the example,
7456 we'll assume that the style file is called
7457 \begin_inset Flex CharStyle:MenuItem
7460 \begin_layout Plain Layout
7466 and it is meant to be used with
7467 \begin_inset Flex CharStyle:MenuItem
7470 \begin_layout Plain Layout
7476 , which is a standard class---start by copying the existing class's layout
7477 file into your local directory:
7480 \begin_layout LyX-Code
7481 cp report.layout ~/.lyx/layouts/myclass.layout
7484 \begin_layout Standard
7486 \begin_inset Flex CharStyle:Code
7489 \begin_layout Plain Layout
7495 and change the line:
7498 \begin_layout LyX-Code
7501 DeclareLaTeXClass{report}
7504 \begin_layout Standard
7508 \begin_layout LyX-Code
7511 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
7514 \begin_layout Standard
7518 \begin_layout LyX-Code
7520 \begin_inset Newline newline
7526 \begin_inset Newline newline
7532 \begin_layout Standard
7533 near the top of the file.
7536 \begin_layout Standard
7537 Start LyX and select
7538 \begin_inset Flex CharStyle:MenuItem
7541 \begin_layout Plain Layout
7546 ools\SpecialChar \menuseparator
7557 Then restart LyX and try creating a new document.
7559 \begin_inset Flex CharStyle:MenuItem
7562 \begin_layout Plain Layout
7568 " as a document class option in the
7569 \begin_inset Flex CharStyle:MenuItem
7572 \begin_layout Plain Layout
7577 ocument\SpecialChar \menuseparator
7588 It is likely that some of the sectioning commands and such in your new
7589 class will work differently from how they worked in the base class---
7590 \begin_inset Flex CharStyle:Code
7593 \begin_layout Plain Layout
7599 in this example---so you can fiddle around with the settings for the different
7600 sections if you wish.
7603 \begin_layout Subsection
7605 \begin_inset Flex CharStyle:MenuItem
7608 \begin_layout Plain Layout
7617 \begin_layout Standard
7618 There are two possibilities here.
7619 One is that the class file is itself based upon an existing document class.
7620 For example, many thesis classes are based upon
7621 \begin_inset Flex CharStyle:MenuItem
7624 \begin_layout Plain Layout
7631 To see whether yours is, look for a line like
7634 \begin_layout LyX-Code
7640 \begin_layout Standard
7642 If so, then you may proceed largely as in the previous section, though
7643 the DeclareLaTeXClass line will be different.
7644 If your new class is thesis, and it is based upon book, then the line should
7649 \begin_layout Plain Layout
7650 And it will be easiest if you save the file to
7651 \begin_inset Flex CharStyle:Code
7654 \begin_layout Plain Layout
7660 : LyX assumes that the document class has the same name as the layout file.
7669 \begin_layout LyX-Code
7672 DeclareLaTeXClass[thesis,book]{thesis}
7675 \begin_layout Standard
7676 If, on the other hand, the new class is not based upon an existing class,
7677 you will probably have to
7678 \begin_inset Quotes eld
7682 \begin_inset Quotes erd
7686 We strongly suggest copying an existing layout file which uses a similar
7687 LaTeX class and then modifying it, if you can do so.
7688 At least use an existing file as a starting point so you can find out what
7689 items you need to worry about.
7690 Again, the specifics are covered below.
7693 \begin_layout Section
7694 Declaring a new text class
7697 \begin_layout Standard
7698 When it's finally time to get your hands dirty and create or edit your own
7699 layout file, the following sections describe what you're up against.
7700 Our advice is to go slowly, save and test often, listen to soothing music,
7701 and enjoy one or two of your favorite adult beverages; more if you are
7702 getting particularly stuck.
7703 It's really not that hard, except that the multitude of options can become
7704 overwhelming if you try to do to much in one sitting.
7705 Go have another adult beverage, just for good measure.
7708 \begin_layout Standard
7712 \begin_layout Standard
7713 Lines in a layout file which begin with a
7714 \begin_inset Flex CharStyle:Code
7717 \begin_layout Plain Layout
7724 There is one exception to this rule: all layouts should begin with lines
7728 \begin_layout LyX-Code
7731 #% Do not delete the line below; configure depends on this
7734 \begin_layout LyX-Code
7739 DeclareLaTeXClass{article}
7742 \begin_layout Standard
7743 The second line is used when you configure LyX.
7744 The layout file is read by the LaTeX script
7745 \begin_inset Flex CharStyle:Code
7748 \begin_layout Plain Layout
7754 , in a special mode where
7755 \begin_inset Flex CharStyle:Code
7758 \begin_layout Plain Layout
7765 The first line is just a LaTeX comment, and the second one contains the
7766 declaration of the text class.
7767 If these lines appear in a file named
7768 \begin_inset Flex CharStyle:Code
7771 \begin_layout Plain Layout
7777 , then they define a text class of name
7778 \begin_inset Flex CharStyle:Code
7781 \begin_layout Plain Layout
7787 (the name of the layout file) which uses the LaTeX document class
7788 \begin_inset Flex CharStyle:Code
7791 \begin_layout Plain Layout
7797 (the default is to use the same name as the layout).
7799 \begin_inset Quotes eld
7803 \begin_inset Quotes erd
7806 that appears above is used as a description of the text class in the
7807 \begin_inset Flex CharStyle:MenuItem
7810 \begin_layout Plain Layout
7815 ocument\SpecialChar \menuseparator
7828 \begin_layout Standard
7829 Let's assume that you wrote your own text class that uses the
7830 \begin_inset Flex CharStyle:Code
7833 \begin_layout Plain Layout
7839 document class, but where you changed the appearance of the section headings.
7840 If you put it in a file
7841 \begin_inset Flex CharStyle:Code
7844 \begin_layout Plain Layout
7850 , the header of this file should be:
7853 \begin_layout LyX-Code
7856 #% Do not delete the line below; configure depends on this
7859 \begin_layout LyX-Code
7864 DeclareLaTeXClass[article]{article (with my own headings)}
7867 \begin_layout Standard
7868 This declares a text class
7869 \begin_inset Flex CharStyle:Code
7872 \begin_layout Plain Layout
7878 , associated with the LaTeX document class
7879 \begin_inset Flex CharStyle:Code
7882 \begin_layout Plain Layout
7889 \begin_inset Quotes eld
7892 article (with my own headings)
7893 \begin_inset Quotes erd
7897 If your text class depends on several packages, you can declare it as:
7900 \begin_layout LyX-Code
7903 #% Do not delete the line below; configure depends on this
7906 \begin_layout LyX-Code
7911 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7914 \begin_layout Standard
7915 This indicates that your text class uses the foo.sty package.
7916 Finally, it is also possible to declare classes for DocBook code.
7917 Typical declarations will look like
7920 \begin_layout LyX-Code
7923 #% Do not delete the line below; configure depends on this
7926 \begin_layout LyX-Code
7931 DeclareDocBookClass[article]{SGML (DocBook article)}
7934 \begin_layout Standard
7935 Note that these declarations can also be given an optional parameter declaring
7936 the name of the document class (but not a list).
7939 \begin_layout Standard
7940 So, to be as explicit as possible, the form of the layout declaration is:
7943 \begin_layout LyX-Code
7948 DeclareLaTeXClass[class,package.sty]{layout description}
7951 \begin_layout Standard
7952 The class need only be specified if the name of the LaTeX class file and
7953 the name of the layout file are different; if the name of the classfile
7954 is not specified, then LyX will simply assume that it is the same as the
7955 name of the layout file.
7958 \begin_layout Standard
7959 When the text class has been modified to your taste, all you have to do
7960 is to copy it either to
7961 \begin_inset Flex CharStyle:Code
7964 \begin_layout Plain Layout
7971 \begin_inset Flex CharStyle:Code
7974 \begin_layout Plain Layout
7981 \begin_inset Flex CharStyle:MenuItem
7984 \begin_layout Plain Layout
7989 ools\SpecialChar \menuseparator
7999 , exit LyX and restart it.
8000 Then your new text class should be available along with the others.
8003 \begin_layout Standard
8004 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
8005 you made to your layout files.
8006 As a result, editing layout files could be very time consuming.
8007 Beginning with 1.6, however, you can force a reload of the layout currently
8008 in use by using the LyX function
8009 \begin_inset Flex CharStyle:MenuItem
8012 \begin_layout Plain Layout
8019 There is no default binding for this function---though, of course, you
8020 can bind it to a key yourself (see section
8021 \begin_inset CommandInset ref
8023 reference "sec:bindings"
8028 If you want to use this function, then, you should simply enter it in the
8034 : This is very much an `advanced feature'.
8039 recommended that you save your work before using this function.
8044 recommended that you not attempt to edit your layout while simultaneously
8045 working on a document that you care about.
8046 Use a test document.
8047 Syntax errors and the like in your layout file could cause peculiar behavior.
8048 In particular, such errors could cause LyX to regard the current layout
8049 as invalid and to attempt to switch to some other layout.
8050 The LyX team strives to keep LyX stable in such situations, but safe is
8054 \begin_layout Subsection
8058 \begin_layout Standard
8059 The first non-comment line must contain the file format number:
8062 \begin_layout Description
8063 \begin_inset Flex CharStyle:Code
8066 \begin_layout Plain Layout
8073 \begin_inset Flex CharStyle:Code
8076 \begin_layout Plain Layout
8082 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
8083 don't have an explicit file format).
8084 The file format that is documented here is format 7.
8087 \begin_layout Subsection
8088 General text class parameters
8091 \begin_layout Standard
8092 These are the general parameters which describe the form of the entire document:
8095 \begin_layout Description
8096 \begin_inset Flex CharStyle:Code
8099 \begin_layout Plain Layout
8105 Adds information to the document preamble.
8107 \begin_inset Quotes eld
8111 \begin_inset Flex CharStyle:Code
8114 \begin_layout Plain Layout
8121 \begin_inset Quotes erd
8127 \begin_layout Description
8128 \begin_inset Flex CharStyle:Code
8131 \begin_layout Plain Layout
8137 Describes various global options supported by the document class.
8139 \begin_inset space ~
8143 \begin_inset CommandInset ref
8145 reference "sec:classoptions"
8151 \begin_inset Quotes eld
8155 \begin_inset Flex CharStyle:Code
8158 \begin_layout Plain Layout
8165 \begin_inset Quotes erd
8171 \begin_layout Description
8172 \begin_inset Flex CharStyle:Code
8175 \begin_layout Plain Layout
8182 \begin_inset Flex CharStyle:Code
8185 \begin_layout Plain Layout
8194 \begin_inset Flex CharStyle:Code
8197 \begin_layout Plain Layout
8203 ] Whether the class should default to having one or two columns.
8204 Can be changed in the
8205 \begin_inset Flex CharStyle:MenuItem
8208 \begin_layout Plain Layout
8213 ocument\SpecialChar \menuseparator
8226 \begin_layout Description
8227 \begin_inset Flex CharStyle:Code
8230 \begin_layout Plain Layout
8236 This sequence defines a new counter.
8238 \begin_inset space ~
8242 \begin_inset CommandInset ref
8244 reference "sec:counter"
8250 \begin_inset Quotes eld
8254 \begin_inset Flex CharStyle:Code
8257 \begin_layout Plain Layout
8264 \begin_inset Quotes erd
8270 \begin_layout Description
8271 \begin_inset Flex CharStyle:Code
8274 \begin_layout Plain Layout
8280 Sets the default font used to display the document.
8282 \begin_inset space ~
8286 \begin_inset CommandInset ref
8288 reference "sec:fonts"
8292 for how to declare fonts.
8294 \begin_inset Quotes eld
8298 \begin_inset Flex CharStyle:Code
8301 \begin_layout Plain Layout
8308 \begin_inset Quotes erd
8314 \begin_layout Description
8315 \begin_inset Flex CharStyle:Code
8318 \begin_layout Plain Layout
8325 \begin_inset Flex CharStyle:Code
8328 \begin_layout Plain Layout
8334 ] This is the style that will be assigned to new paragraphs, usually
8335 \begin_inset Flex CharStyle:MenuItem
8338 \begin_layout Plain Layout
8345 This will default to the first defined style if not given, but you are
8346 highly encouraged to use this directive.
8349 \begin_layout Description
8350 \begin_inset Flex CharStyle:Code
8353 \begin_layout Plain Layout
8359 Defines a new float.
8361 \begin_inset space ~
8365 \begin_inset CommandInset ref
8367 reference "sec:floats"
8373 \begin_inset Quotes eld
8377 \begin_inset Flex CharStyle:Code
8380 \begin_layout Plain Layout
8387 \begin_inset Quotes erd
8393 \begin_layout Description
8394 \begin_inset Flex CharStyle:Code
8397 \begin_layout Plain Layout
8403 As its name implies, this command allows you to include another layout
8404 definition file within yours to avoid duplicating commands.
8405 Common examples are the standard layout files, for example,
8406 \begin_inset Flex CharStyle:Code
8409 \begin_layout Plain Layout
8415 , which contains most of the basic layouts.
8418 \begin_layout Description
8419 \begin_inset Flex CharStyle:Code
8422 \begin_layout Plain Layout
8428 This section (re-)defines the layout of an inset.
8429 It can be applied to an existing inset of to a new, user-defined inset,
8430 e.g., a new character style.
8432 \begin_inset space ~
8436 \begin_inset CommandInset ref
8438 reference "sec:charstyle"
8442 for more information.
8444 \begin_inset Quotes eld
8448 \begin_inset Flex CharStyle:Code
8451 \begin_layout Plain Layout
8458 \begin_inset Quotes erd
8464 \begin_layout Description
8465 \begin_inset Flex CharStyle:Code
8468 \begin_layout Plain Layout
8477 \begin_layout Description
8478 \begin_inset Flex CharStyle:Code
8481 \begin_layout Plain Layout
8487 This command deletes an existing float.
8488 This is particularly useful when you want to suppress a float that has
8489 be defined in an input file.
8492 \begin_layout Description
8493 \begin_inset Flex CharStyle:Code
8496 \begin_layout Plain Layout
8502 This command deletes an existing style.
8503 This is particularly useful when you want to suppress a style that has
8504 be defined in an input file.
8507 \begin_layout Description
8508 \begin_inset Flex CharStyle:Code
8511 \begin_layout Plain Layout
8520 \begin_layout Description
8521 \begin_inset Flex CharStyle:Code
8524 \begin_layout Plain Layout
8535 \begin_inset Flex CharStyle:Code
8538 \begin_layout Plain Layout
8549 \begin_inset Flex CharStyle:Code
8552 \begin_layout Plain Layout
8559 \begin_inset Flex CharStyle:Code
8562 \begin_layout Plain Layout
8568 ] The class default pagestyle.
8569 Can be changed in the
8570 \begin_inset Flex CharStyle:MenuItem
8573 \begin_layout Plain Layout
8578 ocument\SpecialChar \menuseparator
8591 \begin_layout Description
8592 \begin_inset Flex CharStyle:Code
8595 \begin_layout Plain Layout
8601 Sets the preamble for the LaTeX document.
8602 Note that this will completely override any prior
8603 \begin_inset Flex CharStyle:Code
8606 \begin_layout Plain Layout
8613 \begin_inset Flex CharStyle:Code
8616 \begin_layout Plain Layout
8624 \begin_inset Quotes eld
8628 \begin_inset Flex CharStyle:Code
8631 \begin_layout Plain Layout
8638 \begin_inset Quotes erd
8644 \begin_layout Description
8645 \begin_inset Flex CharStyle:Code
8648 \begin_layout Plain Layout
8655 \begin_inset CommandInset label
8662 \begin_inset Flex CharStyle:Code
8665 \begin_layout Plain Layout
8672 \begin_inset Flex CharStyle:Code
8675 \begin_layout Plain Layout
8684 \begin_inset Flex CharStyle:Code
8687 \begin_layout Plain Layout
8693 ] Whether the class already provides the feature
8694 \begin_inset Flex CharStyle:Code
8697 \begin_layout Plain Layout
8704 A feature is in general the name of a package (
8705 \begin_inset Flex CharStyle:Code
8708 \begin_layout Plain Layout
8715 \begin_inset Flex CharStyle:Code
8718 \begin_layout Plain Layout
8724 , \SpecialChar \ldots{}
8726 \begin_inset Flex CharStyle:Code
8729 \begin_layout Plain Layout
8736 \begin_inset Flex CharStyle:Code
8739 \begin_layout Plain Layout
8745 ,\SpecialChar \ldots{}
8746 ); the complete list of supported features is unfortunately not documented
8747 outside the LyX source code---but see
8748 \begin_inset Flex CharStyle:Code
8751 \begin_layout Plain Layout
8757 if you're interested.
8759 \begin_inset Flex CharStyle:MenuItem
8762 \begin_layout Plain Layout
8767 elp\SpecialChar \menuseparator
8777 also gives an overview of the supported packages.
8780 \begin_layout Description
8781 \begin_inset Flex CharStyle:Code
8784 \begin_layout Plain Layout
8791 \begin_inset Flex CharStyle:Code
8794 \begin_layout Plain Layout
8800 ] Whether the class requires the feature
8801 \begin_inset Flex CharStyle:Code
8804 \begin_layout Plain Layout
8811 Multiple features must be separated by commas.
8812 Note that you can only request supported features.
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_layout Description
8842 \begin_inset Flex CharStyle:Code
8845 \begin_layout Plain Layout
8854 \begin_inset Flex CharStyle:Code
8857 \begin_layout Plain Layout
8868 \begin_inset Flex CharStyle:Code
8871 \begin_layout Plain Layout
8877 ] Whether the class-default should be printing on one or both sides of the
8879 Can be changed in the
8880 \begin_inset Flex CharStyle:MenuItem
8883 \begin_layout Plain Layout
8888 ocument\SpecialChar \menuseparator
8901 \begin_layout Description
8902 \begin_inset Flex CharStyle:Code
8905 \begin_layout Plain Layout
8911 This sequence defines a new paragraph style.
8912 If the style already exists, it will redefine some of its parameters instead.
8914 \begin_inset space ~
8918 \begin_inset CommandInset ref
8920 reference "sec:style"
8926 \begin_inset Quotes eld
8930 \begin_inset Flex CharStyle:Code
8933 \begin_layout Plain Layout
8940 \begin_inset Quotes erd
8946 \begin_layout Description
8947 \begin_inset Flex CharStyle:Code
8950 \begin_layout Plain Layout
8957 \begin_inset Flex CharStyle:Code
8960 \begin_layout Plain Layout
8966 ] The name of the command or environment to be used with
8967 \begin_inset Flex CharStyle:Code
8970 \begin_layout Plain Layout
8979 \begin_layout Description
8980 \begin_inset Flex CharStyle:Code
8983 \begin_layout Plain Layout
8990 \begin_inset Flex CharStyle:Code
8993 \begin_layout Plain Layout
9002 \begin_inset Flex CharStyle:Code
9005 \begin_layout Plain Layout
9011 ] Indicates what kind of markup is used to define the title of a document.
9013 \begin_inset Flex CharStyle:Code
9016 \begin_layout Plain Layout
9022 means that the macro with name
9023 \begin_inset Flex CharStyle:Code
9026 \begin_layout Plain Layout
9032 will be inserted after the last layout which has
9033 \begin_inset Quotes eld
9037 \begin_inset Flex CharStyle:Code
9040 \begin_layout Plain Layout
9047 \begin_inset Quotes erd
9052 \begin_inset Flex CharStyle:Code
9055 \begin_layout Plain Layout
9061 corresponds to the case where the block of paragraphs which have
9062 \begin_inset Quotes eld
9066 \begin_inset Flex CharStyle:Code
9069 \begin_layout Plain Layout
9076 \begin_inset Quotes erd
9079 should be enclosed into the
9080 \begin_inset Flex CharStyle:Code
9083 \begin_layout Plain Layout
9092 \begin_layout Description
9093 \begin_inset Flex CharStyle:Code
9096 \begin_layout Plain Layout
9105 \begin_layout Subsection
9106 \begin_inset Flex CharStyle:Code
9109 \begin_layout Plain Layout
9118 \begin_layout Standard
9119 \begin_inset CommandInset label
9121 name "sec:classoptions"
9126 \begin_inset Flex CharStyle:Code
9129 \begin_layout Plain Layout
9135 section can contain the following entries:
9138 \begin_layout Description
9139 \begin_inset Flex CharStyle:Code
9142 \begin_layout Plain Layout
9149 \begin_inset Flex CharStyle:Code
9152 \begin_layout Plain Layout
9158 ] The list of available font sizes for the document's main font, separated
9160 \begin_inset Quotes eld
9164 \begin_inset Flex CharStyle:Code
9167 \begin_layout Plain Layout
9174 \begin_inset Quotes erd
9180 \begin_layout Description
9181 \begin_inset Flex CharStyle:Code
9184 \begin_layout Plain Layout
9193 \begin_layout Description
9194 \begin_inset Flex CharStyle:Code
9197 \begin_layout Plain Layout
9204 \begin_inset Flex CharStyle:Code
9207 \begin_layout Plain Layout
9208 string="empty|plain|headings|fancy"
9213 ] The list of available page styles, separated by
9214 \begin_inset Quotes eld
9218 \begin_inset Flex CharStyle:Code
9221 \begin_layout Plain Layout
9228 \begin_inset Quotes erd
9234 \begin_layout Description
9235 \begin_inset Flex CharStyle:Code
9238 \begin_layout Plain Layout
9245 \begin_inset Flex CharStyle:Code
9248 \begin_layout Plain Layout
9254 ] Some document class options, separated by a comma, that will be added
9255 to the optional part of the
9256 \begin_inset Flex CharStyle:Code
9259 \begin_layout Plain Layout
9270 \begin_layout Standard
9272 \begin_inset Flex CharStyle:Code
9275 \begin_layout Plain Layout
9281 section must end with
9282 \begin_inset Quotes eld
9286 \begin_inset Flex CharStyle:Code
9289 \begin_layout Plain Layout
9296 \begin_inset Quotes erd
9302 \begin_layout Subsection
9306 \begin_layout Standard
9307 \begin_inset CommandInset label
9313 A paragraph style description looks like this:
9317 \begin_layout Plain Layout
9318 Note that this will either define a new layout or modify an existing one.
9326 \begin_layout LyX-Code
9333 \begin_layout LyX-Code
9337 \begin_layout LyX-Code
9341 \begin_layout Standard
9342 where the following commands are allowed:
9345 \begin_layout Description
9346 \begin_inset Flex CharStyle:Code
9349 \begin_layout Plain Layout
9356 \begin_inset Flex CharStyle:Code
9359 \begin_layout Plain Layout
9364 , left, right, center
9369 ] Paragraph alignment.
9372 \begin_layout Description
9373 \begin_inset Flex CharStyle:Code
9376 \begin_layout Plain Layout
9383 \begin_inset Flex CharStyle:Code
9386 \begin_layout Plain Layout
9391 , left, right, center
9396 ] A comma separated list of permitted alignments.
9397 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9399 For example a right-aligned or centered enumeration isn't possible.)
9402 \begin_layout Description
9403 \begin_inset Flex CharStyle:Code
9406 \begin_layout Plain Layout
9413 \begin_inset Flex CharStyle:Code
9416 \begin_layout Plain Layout
9426 \begin_layout Plain Layout
9427 Note that a `float' here is a real number, such as: 1.5.
9432 The vertical space with which the last of a chain of paragraphs with this
9433 layout is separated from the following paragraph.
9434 If the next paragraph has another layout, the separations are not simply
9435 added, but the maximum is taken.
9438 \begin_layout Description
9439 \begin_inset Flex CharStyle:Code
9442 \begin_layout Plain Layout
9449 \begin_inset Flex CharStyle:Code
9452 \begin_layout Plain Layout
9458 The category for this style.
9459 This is used to group related styles in the Layout combobox on the toolbar.
9460 Any string can be used, but you may want to use existing categories with
9465 \begin_layout Description
9466 \begin_inset Flex CharStyle:Code
9469 \begin_layout Plain Layout
9478 \begin_layout Description
9479 \begin_inset Flex CharStyle:Code
9482 \begin_layout Plain Layout
9489 \begin_inset Flex CharStyle:Code
9492 \begin_layout Plain Layout
9498 Copies all the features of an existing style into the current one.
9502 \begin_layout Description
9503 \begin_inset Flex CharStyle:Code
9506 \begin_layout Plain Layout
9512 The name of a style whose preamble should be output
9517 This allows to ensure some ordering of the preamble snippets when macros
9518 definitions depend on one another.
9522 \begin_layout Plain Layout
9523 Note that, besides that functionality, there is no way to ensure any ordering
9525 The ordering that you see in a given version of LyX may change without
9526 warning in later versions.
9534 \begin_layout Description
9535 \begin_inset Flex CharStyle:Code
9538 \begin_layout Plain Layout
9545 \begin_inset Flex CharStyle:Code
9548 \begin_layout Plain Layout
9553 , Box, Filled_Box, Static
9558 ] The type of label that stands at the end of the paragraph (or sequence
9560 \begin_inset Flex CharStyle:Code
9563 \begin_layout Plain Layout
9570 \begin_inset Flex CharStyle:Code
9573 \begin_layout Plain Layout
9580 \begin_inset Flex CharStyle:Code
9583 \begin_layout Plain Layout
9590 \begin_inset Flex CharStyle:Code
9593 \begin_layout Plain Layout
9601 \begin_inset Flex CharStyle:Code
9604 \begin_layout Plain Layout
9611 \begin_inset Quotes eld
9615 \begin_inset Quotes erd
9619 \begin_inset Flex CharStyle:Code
9622 \begin_layout Plain Layout
9629 \begin_inset Flex CharStyle:Code
9632 \begin_layout Plain Layout
9633 \begin_inset space ~
9642 \begin_inset space ~
9645 black) square suitable for end of proof markers,
9646 \begin_inset Flex CharStyle:Code
9649 \begin_layout Plain Layout
9655 is an explicit text string.
9658 \begin_layout Description
9659 \begin_inset Flex CharStyle:Code
9662 \begin_layout Plain Layout
9669 \begin_inset Flex CharStyle:Code
9672 \begin_layout Plain Layout
9678 ] The string used for a label with a
9679 \begin_inset Flex CharStyle:Code
9682 \begin_layout Plain Layout
9689 \begin_inset Flex CharStyle:Code
9692 \begin_layout Plain Layout
9702 \begin_layout Description
9703 \begin_inset Flex CharStyle:Code
9706 \begin_layout Plain Layout
9713 \begin_inset Flex CharStyle:Code
9716 \begin_layout Plain Layout
9727 \begin_inset Flex CharStyle:Code
9730 \begin_layout Plain Layout
9739 \begin_layout Description
9740 \begin_inset Flex CharStyle:Code
9743 \begin_layout Plain Layout
9750 \begin_inset Flex CharStyle:Code
9753 \begin_layout Plain Layout
9763 ] With this parameter the
9764 \begin_inset Flex CharStyle:MenuItem
9767 \begin_layout Plain Layout
9774 \begin_inset Quotes eld
9777 Vertical space above
9778 \begin_inset Quotes erd
9782 \begin_inset Flex CharStyle:MenuItem
9785 \begin_layout Plain Layout
9790 dit\SpecialChar \menuseparator
9796 \begin_inset space ~
9804 dialog can be set when initializing a paragraph with this style.
9808 \begin_layout Plain Layout
9811 Note from Jean-Marc:
9813 I'm not sure that this setting has much use, and it should probably be
9814 removed in later versions.
9822 \begin_layout Description
9823 \begin_inset Flex CharStyle:Code
9826 \begin_layout Plain Layout
9832 The font used for both the text body
9838 \begin_inset space ~
9842 \begin_inset CommandInset ref
9844 reference "sec:fonts"
9849 Note that defining this font automatically defines the
9850 \begin_inset Flex CharStyle:Code
9853 \begin_layout Plain Layout
9860 So you should define this one first if you also want to define
9861 \begin_inset Flex CharStyle:Code
9864 \begin_layout Plain Layout
9873 \begin_layout Description
9874 \begin_inset Flex CharStyle:Code
9877 \begin_layout Plain Layout
9884 \begin_inset CommandInset label
9886 name "des:FreeSpacing"
9893 \begin_inset Flex CharStyle:Code
9896 \begin_layout Plain Layout
9907 \begin_inset Flex CharStyle:Code
9910 \begin_layout Plain Layout
9916 ] Usually LyX doesn't allow you to insert more than one space between words,
9917 since a space is considered as the separation between two words, not a
9918 character or symbol of its own.
9919 This is a very fine thing but sometimes annoying, for example, when typing
9920 program code or plain LaTeX code.
9922 \begin_inset Flex CharStyle:Code
9925 \begin_layout Plain Layout
9932 Note that LyX will create protected blanks for the additional blanks when
9933 in another mode than LaTeX-mode.
9936 \begin_layout Description
9937 \begin_inset Flex CharStyle:Code
9940 \begin_layout Plain Layout
9949 \begin_layout Description
9950 \begin_inset Flex CharStyle:Code
9953 \begin_layout Plain Layout
9960 \begin_inset Flex CharStyle:Code
9963 \begin_layout Plain Layout
9969 If 1, marks the layout as being part of a title block (see also the
9970 \begin_inset Flex CharStyle:Code
9973 \begin_layout Plain Layout
9980 \begin_inset Flex CharStyle:Code
9983 \begin_layout Plain Layout
9992 \begin_layout Description
9993 \begin_inset Flex CharStyle:Code
9996 \begin_layout Plain Layout
10003 \begin_inset Flex CharStyle:Code
10006 \begin_layout Plain Layout
10012 ] This provides extra space between paragraphs that have the same layout.
10013 If you put other layouts into an environment, each is separated with the
10015 \begin_inset Flex CharStyle:Code
10018 \begin_layout Plain Layout
10025 But the whole items of the environment are additionally separated with
10027 \begin_inset Flex CharStyle:Code
10030 \begin_layout Plain Layout
10037 Note that this is a
10042 \begin_layout Description
10043 \begin_inset Flex CharStyle:Code
10046 \begin_layout Plain Layout
10055 \begin_layout Description
10056 \begin_inset Flex CharStyle:Code
10059 \begin_layout Plain Layout
10066 \begin_inset CommandInset label
10068 name "des:KeepEmpty"
10075 \begin_inset Flex CharStyle:Code
10078 \begin_layout Plain Layout
10089 \begin_inset Flex CharStyle:Code
10092 \begin_layout Plain Layout
10098 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10099 lead to empty LaTeX output.
10100 There are some cases where this could be desirable however: in a letter
10101 template, the required fields can be provided as empty fields, so that
10102 people do not forget them; in some special classes, a layout can be used
10103 as some kind of break, which does not contain actual text.
10106 \begin_layout Description
10107 \begin_inset Flex CharStyle:Code
10110 \begin_layout Plain Layout
10116 [float=0] The vertical space between the label and the text body.
10117 Only used for labels that are above the text body (
10118 \begin_inset Flex CharStyle:Code
10121 \begin_layout Plain Layout
10128 \begin_inset Flex CharStyle:Code
10131 \begin_layout Plain Layout
10132 Centered_Top_Environment
10140 \begin_layout Description
10141 \begin_inset Flex CharStyle:Code
10144 \begin_layout Plain Layout
10151 \begin_inset Flex CharStyle:Code
10154 \begin_layout Plain Layout
10161 \begin_inset Newline newline
10164 The name of the counter for automatic numbering (see Section
10165 \begin_inset CommandInset ref
10167 reference "sec:counter"
10172 This must be given if
10173 \begin_inset Flex CharStyle:Code
10176 \begin_layout Plain Layout
10183 \begin_inset Flex CharStyle:Code
10186 \begin_layout Plain Layout
10195 \begin_layout Description
10196 \begin_inset Flex CharStyle:Code
10199 \begin_layout Plain Layout
10205 The font used for the label.
10207 \begin_inset space ~
10211 \begin_inset CommandInset ref
10213 reference "sec:fonts"
10220 \begin_layout Description
10221 \begin_inset Flex CharStyle:Code
10224 \begin_layout Plain Layout
10231 \begin_inset Flex CharStyle:Code
10234 \begin_layout Plain Layout
10240 ] The horizontal space between the label and the text body.
10241 Only used for labels that are not above the text body.
10244 \begin_layout Description
10245 \begin_inset Flex CharStyle:Code
10248 \begin_layout Plain Layout
10255 \begin_inset Flex CharStyle:Code
10258 \begin_layout Plain Layout
10264 ] The string used for a label with a
10265 \begin_inset Flex CharStyle:Code
10268 \begin_layout Plain Layout
10276 \begin_inset Flex CharStyle:Code
10279 \begin_layout Plain Layout
10285 is set, this string can be contain the special formatting commands described
10287 \begin_inset CommandInset ref
10289 reference "sec:counter"
10297 \begin_layout Plain Layout
10298 For the sake of backwards compatibility, the string
10299 \begin_inset Flex CharStyle:Code
10302 \begin_layout Plain Layout
10312 will be replaced by the expanded
10313 \begin_inset Flex CharStyle:Code
10316 \begin_layout Plain Layout
10323 \begin_inset Flex CharStyle:Code
10326 \begin_layout Plain Layout
10335 This feature is now obsolete and should be replaced by the mechanisms of
10337 \begin_inset CommandInset ref
10339 reference "sec:counter"
10351 \begin_layout Description
10352 \begin_inset Flex CharStyle:Code
10355 \begin_layout Plain Layout
10356 LabelStringAppendix
10362 \begin_inset Flex CharStyle:Code
10365 \begin_layout Plain Layout
10371 ] This is used inside the appendix instead of
10372 \begin_inset Flex CharStyle:Code
10375 \begin_layout Plain Layout
10383 \begin_inset Flex CharStyle:Code
10386 \begin_layout Plain Layout
10393 \begin_inset Flex CharStyle:Code
10396 \begin_layout Plain Layout
10397 LabelStringAppendix
10405 \begin_layout Description
10406 \begin_inset Flex CharStyle:Code
10409 \begin_layout Plain Layout
10416 \begin_inset Flex CharStyle:Code
10419 \begin_layout Plain Layout
10424 , Manual, Static, Top_Environment,
10425 \begin_inset Newline newline
10428 Centered_Top_Environment, Sensitive, Counter
10434 \begin_inset Newline newline
10438 \begin_inset Flex CharStyle:Code
10441 \begin_layout Plain Layout
10447 means the label is the very first word (up to the first real blank).
10451 \begin_layout Plain Layout
10452 Use protected spaces if you want more than one word as the label.
10458 \begin_inset Flex CharStyle:Code
10461 \begin_layout Plain Layout
10467 means it is defined in the layout (see
10468 \begin_inset Flex CharStyle:Code
10471 \begin_layout Plain Layout
10479 \begin_inset Flex CharStyle:Code
10482 \begin_layout Plain Layout
10489 \begin_inset Flex CharStyle:Code
10492 \begin_layout Plain Layout
10493 Centered_Top_Environment
10498 are special cases of
10499 \begin_inset Flex CharStyle:Code
10502 \begin_layout Plain Layout
10509 The label will be printed above the paragraph, but only at the top of an
10510 environment or the top of a chain of paragraphs with this layout.
10511 Usage is for example the
10512 \begin_inset Flex CharStyle:MenuItem
10515 \begin_layout Plain Layout
10522 \begin_inset Flex CharStyle:MenuItem
10525 \begin_layout Plain Layout
10532 This is also the case for
10533 \begin_inset Flex CharStyle:Code
10536 \begin_layout Plain Layout
10542 labels with latex type
10543 \begin_inset Flex CharStyle:Code
10546 \begin_layout Plain Layout
10552 , in order to make layouts for theorems work correctly.
10554 \begin_inset Flex CharStyle:Code
10557 \begin_layout Plain Layout
10563 is a special case for the caption-labels
10564 \begin_inset Quotes eld
10568 \begin_inset Quotes erd
10572 \begin_inset Quotes eld
10576 \begin_inset Quotes erd
10581 \begin_inset Flex CharStyle:Code
10584 \begin_layout Plain Layout
10590 means the (hardcoded) label string depends on the kind of float.
10592 \begin_inset Flex CharStyle:Code
10595 \begin_layout Plain Layout
10601 label type defines automatically numbered labels.
10603 \begin_inset CommandInset ref
10605 reference "sec:counter"
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
10638 \begin_layout Description
10639 \begin_inset Flex CharStyle:Code
10642 \begin_layout Plain Layout
10649 \begin_inset CommandInset label
10651 name "des:LatexName"
10655 The name of the corresponding LaTeX stuff.
10656 Either the environment or command name.
10659 \begin_layout Description
10660 \begin_inset Flex CharStyle:Code
10663 \begin_layout Plain Layout
10672 \begin_layout Description
10673 \begin_inset Flex CharStyle:Code
10676 \begin_layout Plain Layout
10683 \begin_inset CommandInset label
10685 name "des:LatexParam"
10689 An optional parameter for the corresponding
10690 \begin_inset Flex CharStyle:Code
10693 \begin_layout Plain Layout
10700 This parameter cannot be changed from within LyX.
10703 \begin_layout Description
10704 \begin_inset Flex CharStyle:Code
10707 \begin_layout Plain Layout
10714 \begin_inset CommandInset label
10716 name "des:LatexType"
10721 \begin_inset Flex CharStyle:Code
10724 \begin_layout Plain Layout
10729 , Command, Environment, Item_Environment,
10735 \begin_inset Flex CharStyle:Code
10738 \begin_layout Plain Layout
10744 ] How the layout should be translated into LaTeX.
10746 \begin_inset Flex CharStyle:Code
10749 \begin_layout Plain Layout
10755 means nothing special.
10757 \begin_inset Flex CharStyle:Code
10760 \begin_layout Plain Layout
10767 \begin_inset Flex CharStyle:Code
10770 \begin_layout Plain Layout
10777 {\SpecialChar \ldots{}
10784 \begin_inset Flex CharStyle:Code
10787 \begin_layout Plain Layout
10794 \begin_inset Flex CharStyle:Code
10797 \begin_layout Plain Layout
10804 }\SpecialChar \ldots{}
10818 \begin_inset Flex CharStyle:Code
10821 \begin_layout Plain Layout
10828 \begin_inset Flex CharStyle:Code
10831 \begin_layout Plain Layout
10838 \begin_inset Flex CharStyle:Code
10841 \begin_layout Plain Layout
10849 is generated for each paragraph of this environment.
10851 \begin_inset Flex CharStyle:Code
10854 \begin_layout Plain Layout
10861 \begin_inset Flex CharStyle:Code
10864 \begin_layout Plain Layout
10871 \begin_inset Flex CharStyle:Code
10874 \begin_layout Plain Layout
10880 is passed as an argument to the environment.
10882 \begin_inset Flex CharStyle:Code
10885 \begin_layout Plain Layout
10891 can be defined in the
10892 \begin_inset Flex CharStyle:MenuItem
10895 \begin_layout Plain Layout
10900 ayout\SpecialChar \menuseparator
10912 \begin_inset Flex CharStyle:Code
10915 \begin_layout Plain Layout
10923 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10924 Visit the SGML class files for specific examples.
10927 \begin_layout Standard
10928 Putting the last few things together, the LaTeX output will be either:
10931 \begin_layout LyX-Code
10934 latexname[latexparam]{\SpecialChar \ldots{}
10938 \begin_layout Standard
10942 \begin_layout LyX-Code
10945 begin{latexname}[latexparam] \SpecialChar \ldots{}
10951 \begin_layout Standard
10952 depending upon the LaTex type.
10955 \begin_layout Description
10956 \begin_inset Flex CharStyle:Code
10959 \begin_layout Plain Layout
10966 \begin_inset Flex CharStyle:Code
10969 \begin_layout Plain Layout
10975 ] If you put layouts into environments, the leftmargins are not simply added,
10976 but added with a factor
10977 \begin_inset Formula $\frac{4}{depth+4}$
10981 Note that this parameter is also used when the margin is defined as
10982 \begin_inset Flex CharStyle:Code
10985 \begin_layout Plain Layout
10992 \begin_inset Flex CharStyle:Code
10995 \begin_layout Plain Layout
11002 Then it is added to the manual or dynamic margin.
11004 \begin_inset Newline newline
11007 The argument is passed as a string.
11009 \begin_inset Quotes eld
11013 \begin_inset Flex CharStyle:Code
11016 \begin_layout Plain Layout
11023 \begin_inset Quotes erd
11026 means that the paragraph is indented with the width of
11027 \begin_inset Quotes eld
11031 \begin_inset Flex CharStyle:Code
11034 \begin_layout Plain Layout
11041 \begin_inset Quotes erd
11044 in the normal font.
11045 You can get a negative width by prefixing the string with
11046 \begin_inset Quotes eld
11050 \begin_inset Flex CharStyle:Code
11053 \begin_layout Plain Layout
11060 \begin_inset Quotes erd
11064 This way was chosen so that the look is the same with each used screen
11069 \begin_layout Description
11070 \begin_inset Flex CharStyle:Code
11073 \begin_layout Plain Layout
11080 \begin_inset Flex CharStyle:Code
11083 \begin_layout Plain Layout
11088 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11094 \begin_inset Newline newline
11097 The kind of margin that the layout has on the left side.
11099 \begin_inset Flex CharStyle:Code
11102 \begin_layout Plain Layout
11108 just means a fixed margin.
11110 \begin_inset Flex CharStyle:Code
11113 \begin_layout Plain Layout
11119 means that the left margin depends on the string entered in the
11120 \begin_inset Flex CharStyle:MenuItem
11123 \begin_layout Plain Layout
11128 dit\SpecialChar \menuseparator
11134 \begin_inset space ~
11143 This is used to typeset nice lists without tabulators.
11145 \begin_inset Flex CharStyle:Code
11148 \begin_layout Plain Layout
11154 means that the margin depends on the size of the label.
11155 This is used for automatic enumerated headlines.
11156 It is obvious that the headline
11157 \begin_inset Quotes eld
11160 5.4.3.2.1 Very long headline
11161 \begin_inset Quotes erd
11164 must have a wider left margin (as wide as
11165 \begin_inset Quotes eld
11169 \begin_inset Quotes erd
11172 plus the space) than
11173 \begin_inset Quotes eld
11176 3.2 Very long headline
11177 \begin_inset Quotes erd
11181 \begin_inset Quotes eld
11185 \begin_inset Quotes erd
11188 are not able to do this.
11190 \begin_inset Flex CharStyle:Code
11193 \begin_layout Plain Layout
11199 is similar, but only the very first row of the paragraph is dynamic, while
11200 the others are static; this is used, for example, for descriptions.
11202 \begin_inset Flex CharStyle:Code
11205 \begin_layout Plain Layout
11211 means the margin is chosen in a way that the longest row of this paragraph
11212 fits to the right margin.
11213 This is used to typeset an address on the right edge of the page.
11216 \begin_layout Description
11217 \begin_inset Flex CharStyle:Code
11220 \begin_layout Plain Layout
11227 \begin_inset CommandInset label
11229 name "des:NeedProtect"
11234 \begin_inset Flex CharStyle:Code
11237 \begin_layout Plain Layout
11246 \begin_inset Flex CharStyle:Code
11249 \begin_layout Plain Layout
11255 ] Whether fragile commands in this layout should be
11256 \begin_inset Flex CharStyle:Code
11259 \begin_layout Plain Layout
11270 \begin_layout Description
11271 \begin_inset Flex CharStyle:Code
11274 \begin_layout Plain Layout
11281 \begin_inset Flex CharStyle:Code
11284 \begin_layout Plain Layout
11291 \begin_inset Flex CharStyle:Code
11294 \begin_layout Plain Layout
11302 ] Whether newlines are translated into LaTeX newlines (
11303 \begin_inset Flex CharStyle:Code
11306 \begin_layout Plain Layout
11317 The translation can be switched off to allow more comfortable LaTeX editing
11321 \begin_layout Description
11322 \begin_inset Flex CharStyle:Code
11325 \begin_layout Plain Layout
11332 \begin_inset Flex CharStyle:Code
11335 \begin_layout Plain Layout
11342 \begin_inset Flex CharStyle:Code
11345 \begin_layout Plain Layout
11353 ] Whether the following Paragraph is allowed to indent its very first row.
11355 \begin_inset Flex CharStyle:Code
11358 \begin_layout Plain Layout
11364 means that it is not allowed to do so;
11365 \begin_inset Flex CharStyle:Code
11368 \begin_layout Plain Layout
11374 means it could do so if it wants to.
11377 \begin_layout Description
11378 \begin_inset Flex CharStyle:Code
11381 \begin_layout Plain Layout
11390 \begin_layout Description
11391 \begin_inset Flex CharStyle:Code
11394 \begin_layout Plain Layout
11401 \begin_inset Flex CharStyle:Code
11404 \begin_layout Plain Layout
11410 ] The number of optional arguments that can be used with this layout.
11411 This is useful for things like section headings, and only makes sense with
11415 \begin_layout Description
11416 \begin_inset Flex CharStyle:Code
11419 \begin_layout Plain Layout
11426 \begin_inset Flex CharStyle:Code
11429 \begin_layout Plain Layout
11435 ] The indent of the very first line of a paragraph.
11437 \begin_inset Flex CharStyle:Code
11440 \begin_layout Plain Layout
11446 will be fixed for a certain layout.
11447 The exception is Standard layout, since the indentation of a Standard layout
11448 paragraph can be prohibited with
11449 \begin_inset Flex CharStyle:Code
11452 \begin_layout Plain Layout
11459 Also, Standard layout paragraphs inside environments use the
11460 \begin_inset Flex CharStyle:Code
11463 \begin_layout Plain Layout
11469 of the environment, not their native one.
11470 For example, Standard paragraphs inside an enumeration are not indented.
11473 \begin_layout Description
11474 \begin_inset Flex CharStyle:Code
11477 \begin_layout Plain Layout
11484 \begin_inset Flex CharStyle:Code
11487 \begin_layout Plain Layout
11493 ] The vertical space between two paragraphs of this layout.
11496 \begin_layout Description
11497 \begin_inset Flex CharStyle:Code
11500 \begin_layout Plain Layout
11507 \begin_inset Flex CharStyle:Code
11510 \begin_layout Plain Layout
11516 ] LyX allows the user to choose either
11517 \begin_inset Quotes eld
11521 \begin_inset Quotes erd
11525 \begin_inset Quotes eld
11529 \begin_inset Quotes erd
11532 to typeset a document.
11534 \begin_inset Quotes eld
11538 \begin_inset Quotes erd
11541 is chosen, this value is completely ignored.
11543 \begin_inset Quotes eld
11547 \begin_inset Quotes erd
11550 is chosen, the parindent of a LaTeXtype
11551 \begin_inset Quotes eld
11555 \begin_inset Quotes erd
11558 layout is ignored and all paragraphs are separated by this parskip argument.
11559 The vertical space is calculated with
11560 \begin_inset Flex CharStyle:Code
11563 \begin_layout Plain Layout
11565 \begin_inset space ~
11574 \begin_inset Flex CharStyle:Code
11577 \begin_layout Plain Layout
11583 is the height of a row with the normal font.
11584 This way, the look stays the same with different screen fonts.
11587 \begin_layout Description
11588 \begin_inset Flex CharStyle:Code
11591 \begin_layout Plain Layout
11598 \begin_inset CommandInset label
11600 name "des:PassThru"
11607 \begin_inset Flex CharStyle:Code
11610 \begin_layout Plain Layout
11621 \begin_inset Flex CharStyle:Code
11624 \begin_layout Plain Layout
11630 ] Whether the contents of this paragraph should be output in raw form, meaning
11631 without special translations that LaTeX would require.
11634 \begin_layout Description
11635 \begin_inset Flex CharStyle:Code
11638 \begin_layout Plain Layout
11645 \begin_inset CommandInset label
11647 name "des:Preamble"
11651 Information to be included in the LaTeX preamable when this style is used.
11652 Used to define macros, load packages, etc., required by this particular
11655 \begin_inset Quotes eld
11659 \begin_inset Flex CharStyle:Code
11662 \begin_layout Plain Layout
11669 \begin_inset Quotes erd
11675 \begin_layout Description
11676 \begin_inset Flex CharStyle:Code
11679 \begin_layout Plain Layout
11686 \begin_inset Flex CharStyle:Code
11689 \begin_layout Plain Layout
11696 \begin_inset CommandInset label
11698 name "des:Requires"
11702 Whether the layout requires the feature
11703 \begin_inset Flex CharStyle:Code
11706 \begin_layout Plain Layout
11713 See the description of
11714 \begin_inset Flex CharStyle:Code
11717 \begin_layout Plain Layout
11724 \begin_inset CommandInset ref
11725 LatexCommand pageref
11726 reference "des:FreeSpacing"
11730 ) for information on `features'.
11734 \begin_layout Description
11735 \begin_inset Flex CharStyle:Code
11738 \begin_layout Plain Layout
11745 \begin_inset Flex CharStyle:Code
11748 \begin_layout Plain Layout
11755 \begin_inset Flex CharStyle:Code
11758 \begin_layout Plain Layout
11767 \begin_layout Description
11768 \begin_inset Flex CharStyle:Code
11771 \begin_layout Plain Layout
11778 \begin_inset Flex CharStyle:Code
11781 \begin_layout Plain Layout
11786 , onehalf, double, other
11795 ] This defines what the default spacing should be in the layout.
11797 \begin_inset Flex CharStyle:Code
11800 \begin_layout Plain Layout
11807 \begin_inset Flex CharStyle:Code
11810 \begin_layout Plain Layout
11817 \begin_inset Flex CharStyle:Code
11820 \begin_layout Plain Layout
11826 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11827 If you specify the argument
11828 \begin_inset Flex CharStyle:Code
11831 \begin_layout Plain Layout
11837 , then you should also provide a numerical argument which will be the actual
11839 Note that, contrary to other parameters,
11840 \begin_inset Flex CharStyle:Code
11843 \begin_layout Plain Layout
11849 implies the generation of specific LaTeX code, using the package
11852 \begin_inset Flex CharStyle:Code
11855 \begin_layout Plain Layout
11864 \begin_layout Description
11865 \begin_inset Flex CharStyle:Code
11868 \begin_layout Plain Layout
11874 The font used for the text body .
11876 \begin_inset CommandInset ref
11878 reference "sec:fonts"
11885 \begin_layout Description
11886 \begin_inset Flex CharStyle:Code
11889 \begin_layout Plain Layout
11897 The level of the style in the table of contents.
11898 This is used for automatic numbering of section headings.
11901 \begin_layout Description
11902 \begin_inset Flex CharStyle:Code
11905 \begin_layout Plain Layout
11912 \begin_inset Flex CharStyle:Code
11915 \begin_layout Plain Layout
11921 ] The vertical space with which the very first of a chain of paragraphs
11922 with this layout is separated from the previous paragraph.
11923 If the previous paragraph has another layout, the separations are not simply
11924 added, but the maximum is taken.
11927 \begin_layout Subsection
11931 \begin_layout Standard
11932 \begin_inset CommandInset label
11938 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11939 define the floats (
11940 \begin_inset Flex CharStyle:MenuItem
11943 \begin_layout Plain Layout
11950 \begin_inset Flex CharStyle:MenuItem
11953 \begin_layout Plain Layout
11959 , \SpecialChar \ldots{}
11960 ) in the text class itself.
11961 Standard floats are included in the file
11962 \begin_inset Flex CharStyle:Code
11965 \begin_layout Plain Layout
11971 , so you may have to do no more than add
11974 \begin_layout LyX-Code
11975 Input stdfloats.inc
11978 \begin_layout Standard
11979 to your layout file.
11980 If you want to implement a text class that proposes some other float types
11981 (like the AGU class bundled with LyX), the information below will hopefully
11985 \begin_layout Description
11986 \begin_inset Flex CharStyle:Code
11989 \begin_layout Plain Layout
11996 \begin_inset Flex CharStyle:Code
11999 \begin_layout Plain Layout
12006 \begin_inset Quotes erd
12010 \begin_inset Quotes erd
12013 ] The file name extension of an auxiliary file for the list of figures (or
12015 LaTeX writes the captions to this file.
12018 \begin_layout Description
12019 \begin_inset Flex CharStyle:Code
12022 \begin_layout Plain Layout
12029 \begin_inset Flex CharStyle:Code
12032 \begin_layout Plain Layout
12039 \begin_inset Quotes erd
12043 \begin_inset Quotes erd
12046 ] The string that will be used in the menus and also for the caption.
12049 \begin_layout Description
12050 \begin_inset Flex CharStyle:Code
12053 \begin_layout Plain Layout
12060 \begin_inset Flex CharStyle:Code
12063 \begin_layout Plain Layout
12072 \begin_inset Flex CharStyle:Code
12075 \begin_layout Plain Layout
12082 \begin_inset Flex CharStyle:Code
12085 \begin_layout Plain Layout
12091 if the float is already defined by the LaTeX document class.
12093 \begin_inset Flex CharStyle:Code
12096 \begin_layout Plain Layout
12102 , the float will be defined using the LaTeX package
12103 \begin_inset Flex CharStyle:Code
12106 \begin_layout Plain Layout
12115 \begin_layout Description
12116 \begin_inset Flex CharStyle:Code
12119 \begin_layout Plain Layout
12126 \begin_inset Flex CharStyle:Code
12129 \begin_layout Plain Layout
12136 \begin_inset Quotes erd
12140 \begin_inset Quotes erd
12143 ] The heading used for the list of floats.
12146 \begin_layout Description
12147 \begin_inset Flex CharStyle:Code
12150 \begin_layout Plain Layout
12157 \begin_inset Flex CharStyle:Code
12160 \begin_layout Plain Layout
12167 \begin_inset Quotes erd
12171 \begin_inset Quotes erd
12174 ] This (optional) argument determines whether floats of this class will
12175 be numbered within some sectional unit of the document.
12176 For example, if within is equal to
12177 \begin_inset Flex CharStyle:Code
12180 \begin_layout Plain Layout
12186 , the floats will be numbered within chapters.
12190 \begin_layout Description
12191 \begin_inset Flex CharStyle:Code
12194 \begin_layout Plain Layout
12201 \begin_inset Flex CharStyle:Code
12204 \begin_layout Plain Layout
12211 \begin_inset Quotes erd
12215 \begin_inset Quotes erd
12218 ] The default placement for the given class of floats.
12219 The string should be as in standard LaTeX:
12220 \begin_inset Flex CharStyle:Code
12223 \begin_layout Plain Layout
12230 \begin_inset Flex CharStyle:Code
12233 \begin_layout Plain Layout
12240 \begin_inset Flex CharStyle:Code
12243 \begin_layout Plain Layout
12250 \begin_inset Flex CharStyle:Code
12253 \begin_layout Plain Layout
12259 for top, bottom, page, and here, respectively.
12263 \begin_layout Plain Layout
12264 Note that the order of these letters in the string is irrelevant, like in
12270 On top of that there is a new type,
12271 \begin_inset Flex CharStyle:Code
12274 \begin_layout Plain Layout
12280 , which does not really correspond to a float, since it means: put it
12281 \begin_inset Quotes eld
12285 \begin_inset Quotes erd
12289 Note however that the
12290 \begin_inset Flex CharStyle:Code
12293 \begin_layout Plain Layout
12299 specifier is special and, because of implementation details, cannot be
12300 used in non-builtin float types.
12301 If you do not understand what this means, just use
12302 \begin_inset Quotes eld
12306 \begin_inset Flex CharStyle:Code
12309 \begin_layout Plain Layout
12316 \begin_inset Quotes erd
12322 \begin_layout Description
12323 \begin_inset Flex CharStyle:Code
12326 \begin_layout Plain Layout
12333 \begin_inset Flex CharStyle:Code
12336 \begin_layout Plain Layout
12343 \begin_inset Quotes erd
12347 \begin_inset Quotes erd
12350 ] The style used when defining the float using
12351 \begin_inset Flex CharStyle:Code
12354 \begin_layout Plain Layout
12365 \begin_layout Description
12366 \begin_inset Flex CharStyle:Code
12369 \begin_layout Plain Layout
12376 \begin_inset Flex CharStyle:Code
12379 \begin_layout Plain Layout
12386 \begin_inset Quotes erd
12390 \begin_inset Quotes erd
12394 \begin_inset Quotes eld
12398 \begin_inset Quotes erd
12401 of the new class of floats, like program or algorithm.
12402 After the appropriate
12403 \begin_inset Flex CharStyle:Code
12406 \begin_layout Plain Layout
12415 \begin_inset Flex CharStyle:Code
12418 \begin_layout Plain Layout
12427 \begin_inset Flex CharStyle:Code
12430 \begin_layout Plain Layout
12441 \begin_layout Standard
12442 Note that defining a float with type
12443 \begin_inset Flex CharStyle:Code
12446 \begin_layout Plain Layout
12454 automatically defines the corresponding counter with name
12455 \begin_inset Flex CharStyle:Code
12458 \begin_layout Plain Layout
12469 \begin_layout Subsection
12470 Inset layouts and Flex insets
12473 \begin_layout Standard
12474 \begin_inset CommandInset label
12476 name "sec:charstyle"
12480 LyX has supported character styles since version 1.4.0; since version 1.6.0
12481 these are called Flex insets.
12485 \begin_layout Standard
12486 Furthermore, it is possible to define the general layout of many different
12488 Currently, InsetLayout can be used to customize the layout parameters
12489 for footnotes, marginal notes, note insets, ERT insets, branches, listings,
12490 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
12495 \begin_layout Standard
12496 Flex insets come in three different kinds:
12499 \begin_layout Itemize
12501 \begin_inset Flex CharStyle:Code
12504 \begin_layout Plain Layout
12510 ): These define semantic markup corresponding to such LaTeX commands as
12512 \begin_inset Flex CharStyle:Code
12515 \begin_layout Plain Layout
12524 \begin_inset Flex CharStyle:Code
12527 \begin_layout Plain Layout
12538 \begin_layout Itemize
12540 \begin_inset Flex CharStyle:Code
12543 \begin_layout Plain Layout
12549 ): These can be used to define custom collapsable insets, similar to ERT,
12550 footnote, and the like.
12553 \begin_layout Itemize
12555 \begin_inset Flex CharStyle:Code
12558 \begin_layout Plain Layout
12564 ): For use with DocBook classes.
12567 \begin_layout Standard
12569 \begin_inset Flex CharStyle:Code
12572 \begin_layout Plain Layout
12578 definition starting line is of the form
12581 \begin_layout LyX-Code
12582 InsetLayout <Type> <Name>
12585 \begin_layout Standard
12587 \begin_inset Flex CharStyle:Code
12590 \begin_layout Plain Layout
12597 \begin_inset Flex CharStyle:Code
12600 \begin_layout Plain Layout
12607 \begin_inset Flex CharStyle:Code
12610 \begin_layout Plain Layout
12617 \begin_inset Flex CharStyle:Code
12620 \begin_layout Plain Layout
12627 \begin_inset Flex CharStyle:Code
12630 \begin_layout Plain Layout
12637 \begin_inset Flex CharStyle:Code
12640 \begin_layout Plain Layout
12647 \begin_inset Flex CharStyle:Code
12650 \begin_layout Plain Layout
12657 \begin_inset Flex CharStyle:Code
12660 \begin_layout Plain Layout
12667 \begin_inset Flex CharStyle:Code
12670 \begin_layout Plain Layout
12677 \begin_inset Flex CharStyle:Code
12680 \begin_layout Plain Layout
12687 \begin_inset Flex CharStyle:Code
12690 \begin_layout Plain Layout
12697 \begin_inset Flex CharStyle:Code
12700 \begin_layout Plain Layout
12707 \begin_inset Flex CharStyle:Code
12710 \begin_layout Plain Layout
12717 \begin_inset Flex CharStyle:Code
12720 \begin_layout Plain Layout
12727 \begin_inset Flex CharStyle:Code
12730 \begin_layout Plain Layout
12737 \begin_inset Flex CharStyle:Code
12740 \begin_layout Plain Layout
12747 \begin_inset Flex CharStyle:Code
12750 \begin_layout Plain Layout
12758 \begin_inset Flex CharStyle:Code
12761 \begin_layout Plain Layout
12768 \begin_inset Flex CharStyle:Code
12771 \begin_layout Plain Layout
12778 \begin_inset Flex CharStyle:Code
12781 \begin_layout Plain Layout
12787 should have the form
12788 \begin_inset Flex CharStyle:Code
12791 \begin_layout Plain Layout
12798 \begin_inset Flex CharStyle:Code
12801 \begin_layout Plain Layout
12808 \begin_inset Flex CharStyle:Code
12811 \begin_layout Plain Layout
12818 \begin_inset Flex CharStyle:Code
12821 \begin_layout Plain Layout
12828 \begin_inset Flex CharStyle:Code
12831 \begin_layout Plain Layout
12838 \begin_inset Flex CharStyle:Code
12841 \begin_layout Plain Layout
12847 is any valid identifier.
12851 \begin_layout Standard
12853 \begin_inset Flex CharStyle:Code
12856 \begin_layout Plain Layout
12862 section can contain the following entries:
12865 \begin_layout Description
12866 \begin_inset Flex CharStyle:Code
12869 \begin_layout Plain Layout
12875 The color for the inset's background.
12876 These valid colors are defined in
12877 \begin_inset Flex CharStyle:Code
12880 \begin_layout Plain Layout
12889 \begin_layout Description
12890 \begin_inset Flex CharStyle:Code
12893 \begin_layout Plain Layout
12900 \begin_inset Flex CharStyle:Code
12903 \begin_layout Plain Layout
12910 \begin_inset Flex CharStyle:Code
12913 \begin_layout Plain Layout
12920 \begin_inset Flex CharStyle:Code
12923 \begin_layout Plain Layout
12929 , describing the rendering style used for the inset's frame and buttons.
12930 Footnotes generally use
12931 \begin_inset Flex CharStyle:Code
12934 \begin_layout Plain Layout
12940 ; ERT insets generally use
12941 \begin_inset Flex CharStyle:Code
12944 \begin_layout Plain Layout
12950 ; and character styles use
12951 \begin_inset Flex CharStyle:Code
12954 \begin_layout Plain Layout
12963 \begin_layout Description
12964 \begin_inset Flex CharStyle:Code
12967 \begin_layout Plain Layout
12973 The font used for both the text body
12979 \begin_inset space ~
12983 \begin_inset CommandInset ref
12985 reference "sec:fonts"
12990 Note that defining this font automatically defines the
12991 \begin_inset Flex CharStyle:Code
12994 \begin_layout Plain Layout
13000 to the same value, so define this first and define
13001 \begin_inset Flex CharStyle:Code
13004 \begin_layout Plain Layout
13010 later if you want them to be different.
13013 \begin_layout Description
13014 \begin_inset Flex CharStyle:Code
13017 \begin_layout Plain Layout
13026 \begin_layout Description
13027 \begin_inset Flex CharStyle:Code
13030 \begin_layout Plain Layout
13036 As with paragraph styles (see page
13037 \begin_inset CommandInset ref
13038 LatexCommand pageref
13039 reference "des:FreeSpacing"
13046 \begin_layout Description
13047 \begin_inset Flex CharStyle:Code
13050 \begin_layout Plain Layout
13056 As with paragraph styles (see page
13057 \begin_inset CommandInset ref
13058 LatexCommand pageref
13059 reference "des:KeepEmpty"
13066 \begin_layout Description
13067 \begin_inset Flex CharStyle:Code
13070 \begin_layout Plain Layout
13076 What will be displayed on the button or elsewhere as the inset label.
13077 Some inset types (ERT and Branch) modify this label on the fly.
13080 \begin_layout Description
13081 \begin_inset Flex CharStyle:Code
13084 \begin_layout Plain Layout
13090 The font used for the label.
13092 \begin_inset space ~
13096 \begin_inset CommandInset ref
13098 reference "sec:fonts"
13103 Note that this definition can never appear before
13104 \begin_inset Flex CharStyle:Code
13107 \begin_layout Plain Layout
13113 , lest it be ineffective.
13116 \begin_layout Description
13117 \begin_inset Flex CharStyle:Code
13120 \begin_layout Plain Layout
13126 The name of the corresponding LaTeX stuff.
13127 Either the environment or command name.
13130 \begin_layout Description
13131 \begin_inset Flex CharStyle:Code
13134 \begin_layout Plain Layout
13140 The optional parameter for the corresponding
13141 \begin_inset Flex CharStyle:Code
13144 \begin_layout Plain Layout
13150 stuff, including possible bracket pairs like
13151 \begin_inset Flex CharStyle:Code
13154 \begin_layout Plain Layout
13161 This parameter cannot be changed from within LyX.
13164 \begin_layout Description
13165 \begin_inset Flex CharStyle:Code
13168 \begin_layout Plain Layout
13174 As with paragraph styles (see page
13175 \begin_inset CommandInset ref
13176 LatexCommand pageref
13177 reference "des:LatexType"
13184 \begin_layout Description
13185 \begin_inset Flex CharStyle:Code
13188 \begin_layout Plain Layout
13195 \begin_inset Flex CharStyle:Code
13198 \begin_layout Plain Layout
13205 \begin_inset Flex CharStyle:Code
13208 \begin_layout Plain Layout
13215 \begin_inset Flex CharStyle:Code
13218 \begin_layout Plain Layout
13225 \begin_inset Flex CharStyle:Code
13228 \begin_layout Plain Layout
13234 (indicating a dummy definition ending definitions of charstyles etc.).
13235 This entry is only meaningful for Flex (user definable) insets.
13238 \begin_layout Description
13239 \begin_inset Flex CharStyle:Code
13242 \begin_layout Plain Layout
13248 As with paragraph styles (see page
13249 \begin_inset CommandInset ref
13250 LatexCommand pageref
13251 reference "des:Preamble"
13258 \begin_layout Description
13259 \begin_inset Flex CharStyle:Code
13262 \begin_layout Plain Layout
13269 \begin_inset Flex CharStyle:Code
13272 \begin_layout Plain Layout
13278 ] As with paragraph styles (see page
13279 \begin_inset CommandInset ref
13280 LatexCommand pageref
13281 reference "des:Requires"
13288 \begin_layout Subsection
13292 \begin_layout Standard
13293 \begin_inset CommandInset label
13299 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13301 \begin_inset Flex CharStyle:MenuItem
13304 \begin_layout Plain Layout
13311 \begin_inset Flex CharStyle:MenuItem
13314 \begin_layout Plain Layout
13320 , \SpecialChar \ldots{}
13321 ) in the text class itself.
13322 The standard counters are defined in the file
13323 \begin_inset Flex CharStyle:Code
13326 \begin_layout Plain Layout
13332 , so you may have to do no more than add
13335 \begin_layout LyX-Code
13336 Input stdcounters.inc
13339 \begin_layout Standard
13340 to your layout file to get them to work.
13341 But if you want to define custom counters, then you can do so, using the
13342 following parameters:
13345 \begin_layout Description
13346 \begin_inset Flex CharStyle:Code
13349 \begin_layout Plain Layout
13350 LabelString [string=""]
13355 when this is defined, this string defines how the counter is displayed.
13356 Setting this value sets
13357 \begin_inset Flex CharStyle:Code
13360 \begin_layout Plain Layout
13361 LabelStringAppendix
13367 The following special constructs can be used in the string:
13371 \begin_layout Itemize
13372 \begin_inset Flex CharStyle:Code
13375 \begin_layout Plain Layout
13383 will be replaced by the expansion of the
13384 \begin_inset Flex CharStyle:Code
13387 \begin_layout Plain Layout
13394 \begin_inset Flex CharStyle:Code
13397 \begin_layout Plain Layout
13398 LabelStringAppendix
13404 \begin_inset Flex CharStyle:Code
13407 \begin_layout Plain Layout
13417 \begin_layout Itemize
13418 counter values can be expressed using LaTeX-like macros
13419 \begin_inset Flex CharStyle:Code
13422 \begin_layout Plain Layout
13439 \begin_inset Flex CharStyle:Code
13442 \begin_layout Plain Layout
13454 \begin_layout Plain Layout
13464 Actually, the situation is a bit more complicated: any
13483 other than those descibed below will produce arabic numerals.
13484 It would not be surprising to see this change in the future.
13490 \begin_inset Flex CharStyle:Code
13493 \begin_layout Plain Layout
13499 : 1, 2, 3,\SpecialChar \ldots{}
13501 \begin_inset Flex CharStyle:Code
13504 \begin_layout Plain Layout
13510 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13512 \begin_inset Flex CharStyle:Code
13515 \begin_layout Plain Layout
13521 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13523 \begin_inset Flex CharStyle:Code
13526 \begin_layout Plain Layout
13532 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13534 \begin_inset Flex CharStyle:Code
13537 \begin_layout Plain Layout
13543 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13545 \begin_inset Flex CharStyle:Code
13548 \begin_layout Plain Layout
13554 for hebrew numerals.
13558 \begin_layout Standard
13559 If LabelString is not defined, a default value is constructed as follows:
13560 if the counter has a master counter
13561 \begin_inset Flex CharStyle:Code
13564 \begin_layout Plain Layout
13571 \begin_inset Flex CharStyle:Code
13574 \begin_layout Plain Layout
13581 \begin_inset Flex CharStyle:Code
13584 \begin_layout Plain Layout
13594 is used; otherwise the string
13595 \begin_inset Flex CharStyle:Code
13598 \begin_layout Plain Layout
13609 \begin_layout Description
13610 \begin_inset Flex CharStyle:Code
13613 \begin_layout Plain Layout
13614 LabelStringAppendix [string=""]
13620 \begin_inset Flex CharStyle:Code
13623 \begin_layout Plain Layout
13632 \begin_layout Description
13633 \begin_inset Flex CharStyle:Code
13636 \begin_layout Plain Layout
13643 \begin_inset Flex CharStyle:Code
13646 \begin_layout Plain Layout
13653 \begin_inset Quotes erd
13657 \begin_inset Quotes erd
13660 ] The name of the counter.
13663 \begin_layout Description
13664 \begin_inset Flex CharStyle:Code
13667 \begin_layout Plain Layout
13674 \begin_inset Flex CharStyle:Code
13677 \begin_layout Plain Layout
13684 \begin_inset Quotes erd
13688 \begin_inset Quotes erd
13691 ] If this is set to the name of another counter, the present counter will
13692 be reset everytime the other one is increased.
13694 \begin_inset Flex CharStyle:Code
13697 \begin_layout Plain Layout
13704 \begin_inset Flex CharStyle:Code
13707 \begin_layout Plain Layout
13716 \begin_layout Subsection
13720 \begin_layout Standard
13721 \begin_inset CommandInset label
13727 A font description looks like this:
13730 \begin_layout LyX-Code
13740 \begin_layout LyX-Code
13744 \begin_layout LyX-Code
13748 \begin_layout Standard
13749 The following commands are available:
13752 \begin_layout Description
13753 \begin_inset Flex CharStyle:Code
13756 \begin_layout Plain Layout
13763 \begin_inset Flex CharStyle:Code
13766 \begin_layout Plain Layout
13775 \begin_inset Flex CharStyle:Code
13778 \begin_layout Plain Layout
13785 \begin_inset Flex CharStyle:Code
13788 \begin_layout Plain Layout
13795 \begin_inset Flex CharStyle:Code
13798 \begin_layout Plain Layout
13805 \begin_inset Flex CharStyle:Code
13808 \begin_layout Plain Layout
13815 \begin_inset Flex CharStyle:Code
13818 \begin_layout Plain Layout
13825 \begin_inset Flex CharStyle:Code
13828 \begin_layout Plain Layout
13835 \begin_inset Flex CharStyle:Code
13838 \begin_layout Plain Layout
13845 \begin_inset Flex CharStyle:Code
13848 \begin_layout Plain Layout
13857 \begin_layout Description
13858 \begin_inset Flex CharStyle:Code
13861 \begin_layout Plain Layout
13870 \begin_inset Flex CharStyle:Code
13873 \begin_layout Plain Layout
13884 \begin_inset Flex CharStyle:Code
13887 \begin_layout Plain Layout
13894 \begin_inset Flex CharStyle:Code
13897 \begin_layout Plain Layout
13906 \begin_layout Description
13907 \begin_inset Flex CharStyle:Code
13910 \begin_layout Plain Layout
13917 \begin_inset Flex CharStyle:Code
13920 \begin_layout Plain Layout
13926 ] Valid argument sare:
13927 \begin_inset Flex CharStyle:Code
13930 \begin_layout Plain Layout
13937 \begin_inset Flex CharStyle:Code
13940 \begin_layout Plain Layout
13947 \begin_inset Flex CharStyle:Code
13950 \begin_layout Plain Layout
13957 \begin_inset Flex CharStyle:Code
13960 \begin_layout Plain Layout
13967 \begin_inset Flex CharStyle:Code
13970 \begin_layout Plain Layout
13977 \begin_inset Flex CharStyle:Code
13980 \begin_layout Plain Layout
13987 Each of these turns on or off the corresponding attribute.
13990 \begin_layout Description
13991 \begin_inset Flex CharStyle:Code
13994 \begin_layout Plain Layout
14003 \begin_inset Flex CharStyle:Code
14006 \begin_layout Plain Layout
14017 \begin_inset Flex CharStyle:Code
14020 \begin_layout Plain Layout
14029 \begin_layout Description
14030 \begin_inset Flex CharStyle:Code
14033 \begin_layout Plain Layout
14042 \begin_inset Flex CharStyle:Code
14045 \begin_layout Plain Layout
14056 \begin_inset Flex CharStyle:Code
14059 \begin_layout Plain Layout
14066 \begin_inset Flex CharStyle:Code
14069 \begin_layout Plain Layout
14076 \begin_inset Flex CharStyle:Code
14079 \begin_layout Plain Layout
14088 \begin_layout Description
14089 \begin_inset Flex CharStyle:Code
14092 \begin_layout Plain Layout
14099 \begin_inset Flex CharStyle:Code
14102 \begin_layout Plain Layout
14109 \begin_inset Flex CharStyle:Code
14112 \begin_layout Plain Layout
14119 \begin_inset Flex CharStyle:Code
14122 \begin_layout Plain Layout
14131 \begin_inset Flex CharStyle:Code
14134 \begin_layout Plain Layout
14141 \begin_inset Flex CharStyle:Code
14144 \begin_layout Plain Layout
14151 \begin_inset Flex CharStyle:Code
14154 \begin_layout Plain Layout
14161 \begin_inset Flex CharStyle:Code
14164 \begin_layout Plain Layout
14171 \begin_inset Flex CharStyle:Code
14174 \begin_layout Plain Layout
14183 \begin_layout Subsection
14184 Upgrading old layout files
14187 \begin_layout Standard
14188 The file format of layout files changes from time to time, so old layout
14189 files need to be converted.
14190 This process has been automated since LyX 1.4.0: If LyX reads an old format
14191 layout file it will call the conversion tool
14192 \begin_inset Flex CharStyle:Code
14195 \begin_layout Plain Layout
14196 LyXDir/scripts/layout2layout.py
14201 and convert it to a temporary file in current format.
14202 The original file is left untouched.
14203 If you want to convert the layout file permanently, just call the converter
14207 \begin_layout LyX-Code
14208 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
14211 \begin_layout Standard
14212 (You need to replace
14213 \begin_inset Flex CharStyle:Code
14216 \begin_layout Plain Layout
14222 with the name of your LyX system directory, unless you happen to have defined
14223 such an environment variable.) Then copy
14224 \begin_inset Flex CharStyle:Code
14227 \begin_layout Plain Layout
14234 \begin_inset Flex CharStyle:Code
14237 \begin_layout Plain Layout
14246 \begin_layout Standard
14247 The automatic conversion only handles syntax changes.
14248 It cannot handle the case where the contents of included files was changed,
14249 so these will have to be converted separately.
14252 \begin_layout Section
14254 \begin_inset CommandInset label
14256 name "sec:templates"
14263 \begin_layout Standard
14264 Templates are created just like usual documents.
14265 The only difference is that usual documents contain all possible settings,
14266 including the font scheme and the paper size.
14267 Usually a user doesn't want a template to overwrite his defaults in these
14269 For that reason, the designer of a template should remove the corresponding
14271 \begin_inset Flex CharStyle:Code
14274 \begin_layout Plain Layout
14283 \begin_inset Flex CharStyle:Code
14286 \begin_layout Plain Layout
14294 from the template LyX file.
14295 This can be done with any simple text-editor, for example
14296 \begin_inset Flex CharStyle:Code
14299 \begin_layout Plain Layout
14306 \begin_inset Flex CharStyle:Code
14309 \begin_layout Plain Layout
14319 \begin_layout Standard
14320 Put the edited template files you create in
14321 \begin_inset Flex CharStyle:Code
14324 \begin_layout Plain Layout
14330 , copy the ones you use from the global template directory in
14331 \begin_inset Flex CharStyle:Code
14334 \begin_layout Plain Layout
14340 to the same place, and redefine the template path in the
14341 \begin_inset Flex CharStyle:MenuItem
14344 \begin_layout Plain Layout
14352 \SpecialChar \menuseparator
14357 references\SpecialChar \menuseparator
14366 \begin_layout Standard
14367 Note that there is a template which has a particular meaning:
14368 \begin_inset Flex CharStyle:Code
14371 \begin_layout Plain Layout
14378 This template is loaded everytime you create a new document with
14379 \begin_inset Flex CharStyle:MenuItem
14382 \begin_layout Plain Layout
14392 \SpecialChar \menuseparator
14394 \begin_inset Flex CharStyle:MenuItem
14397 \begin_layout Plain Layout
14407 in order to provide useful defaults.
14408 To create this template from inside LyX, all you have to do is to open
14409 a document with the correct settings, and use the
14410 \begin_inset Flex CharStyle:MenuItem
14413 \begin_layout Plain Layout
14418 e as Document Defaults
14426 \begin_layout Chapter
14427 Including External Material
14430 \begin_layout Standard
14431 The use of material from sources external to LyX is covered in detail in
14437 This part of the manual covers what needs to happen behind the scenes for
14438 new sorts of material to be included.
14441 \begin_layout Section
14445 \begin_layout Standard
14446 The external material feature is based on the concept of a
14451 A template is a specification of how LyX should interface with a certain
14453 As bundled, LyX comes with predefined templates for Xfig figures, various
14454 raster format images, chess diagrams, and LilyPond music notation.
14455 You can check the actual list by using the menu
14456 \begin_inset Flex CharStyle:MenuItem
14459 \begin_layout Plain Layout
14460 Insert\SpecialChar \menuseparator
14461 File\SpecialChar \menuseparator
14468 Furthermore, it is possible to roll your own template to support a specific
14470 Later we'll describe in more detail what is involved, and hopefully you
14471 will submit all the templates you create so we can include them in a later
14475 \begin_layout Standard
14476 Another basic idea of the external material feature is to distinguish between
14477 the original file that serves as a base for final material and the produced
14478 file that is included in your exported or printed document.
14479 For example, consider the case of a figure produced with
14480 \begin_inset Flex CharStyle:Code
14483 \begin_layout Plain Layout
14490 The Xfig application itself works on an original file with the
14491 \begin_inset Flex CharStyle:Code
14494 \begin_layout Plain Layout
14501 Within XFig, you create and change your figure, and when you are done,
14503 \begin_inset Flex CharStyle:Code
14506 \begin_layout Plain Layout
14513 When you want to include the figure in your document, you invoke
14514 \begin_inset Flex CharStyle:Code
14517 \begin_layout Plain Layout
14523 in order to create a PostScript file that can readily be included in your
14526 \begin_inset Flex CharStyle:Code
14529 \begin_layout Plain Layout
14535 file is the original file, and the PostScript file is the produced file.
14538 \begin_layout Standard
14539 This distinction is important in order to allow updating of the material
14540 while you are in the process of writing the document.
14541 Furthermore, it provides us with the flexibility that is needed to support
14542 multiple export formats.
14543 For instance, in the case of a plain text file, it is not exactly an award-winn
14544 ing idea to include the figure as raw PostScript®.
14545 Instead, you'd either prefer to just include a reference to the figure
14546 or try to invoke some graphics to Ascii converter to make the final result
14547 look similar to the real graphics.
14548 The external material management allows you to do this, because it is parameter
14549 ized on the different export formats that LyX supports.
14552 \begin_layout Standard
14553 Besides supporting the production of different products according to the
14554 exported format, it supports tight integration with editing and viewing
14556 In the case of an XFig figure, you are able to invoke Xfig on the original
14557 file with a single click from within the external material dialog in LyX,
14558 and also preview the produced PostScript file with ghostview with another
14560 No more fiddling around with the command line and/or file browsers to locate
14561 and manipulate the original or produced files.
14562 In this way, you are finally able to take full advantage of the many different
14563 applications that are relevant to use when you write your documents, and
14564 ultimately be more productive.
14567 \begin_layout Section
14568 The external template configuration file
14571 \begin_layout Standard
14572 It is relatively easy to add custom external template definitions to LyX.
14573 However, be aware that doing this in an careless manner most probably
14577 introduce an easily exploitable security hole.
14578 So before you do this, please read the discussion about security in section
14580 \begin_inset CommandInset ref
14582 reference "sec:Security-discussion"
14589 \begin_layout Standard
14590 Having said that, we encourage you to submit any interesting templates that
14595 \begin_layout Standard
14596 The external templates are defined in the
14597 \begin_inset Flex CharStyle:Code
14600 \begin_layout Plain Layout
14601 LyXDir/lib/external_templates
14607 You can place your own version in
14608 \begin_inset Flex CharStyle:Code
14611 \begin_layout Plain Layout
14612 UserDir/external_templates
14620 \begin_layout Standard
14621 A typical template looks like this:
14624 \begin_layout LyX-Code
14628 \begin_layout LyX-Code
14629 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14632 \begin_layout LyX-Code
14636 \begin_layout LyX-Code
14640 \begin_layout LyX-Code
14644 \begin_layout LyX-Code
14648 \begin_layout LyX-Code
14652 \begin_layout LyX-Code
14653 AutomaticProduction true
14656 \begin_layout LyX-Code
14660 \begin_layout LyX-Code
14664 \begin_layout LyX-Code
14668 \begin_layout LyX-Code
14669 TransformCommand Rotate RotationLatexCommand
14672 \begin_layout LyX-Code
14673 TransformCommand Resize ResizeLatexCommand
14676 \begin_layout LyX-Code
14677 Product "$$RotateFront$$ResizeFront
14680 \begin_layout LyX-Code
14685 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14688 \begin_layout LyX-Code
14689 $$ResizeBack$$RotateBack"
14692 \begin_layout LyX-Code
14696 \begin_layout LyX-Code
14697 UpdateResult "$$AbsPath$$Basename.pstex_t"
14700 \begin_layout LyX-Code
14701 Requirement "graphicx"
14704 \begin_layout LyX-Code
14705 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14708 \begin_layout LyX-Code
14709 ReferencedFile latex "$$AbsPath$$Basename.eps"
14712 \begin_layout LyX-Code
14713 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14716 \begin_layout LyX-Code
14720 \begin_layout LyX-Code
14724 \begin_layout LyX-Code
14725 TransformCommand Rotate RotationLatexCommand
14728 \begin_layout LyX-Code
14729 TransformCommand Resize ResizeLatexCommand
14732 \begin_layout LyX-Code
14733 Product "$$RotateFront$$ResizeFront
14736 \begin_layout LyX-Code
14741 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14744 \begin_layout LyX-Code
14745 $$ResizeBack$$RotateBack"
14748 \begin_layout LyX-Code
14749 UpdateFormat pdftex
14752 \begin_layout LyX-Code
14753 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14756 \begin_layout LyX-Code
14757 Requirement "graphicx"
14760 \begin_layout LyX-Code
14761 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14764 \begin_layout LyX-Code
14765 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14768 \begin_layout LyX-Code
14772 \begin_layout LyX-Code
14776 \begin_layout LyX-Code
14777 Product "$$Contents(
14779 "$$AbsPath$$Basename.asc
14784 \begin_layout LyX-Code
14785 UpdateFormat asciixfig
14788 \begin_layout LyX-Code
14789 UpdateResult "$$AbsPath$$Basename.asc"
14792 \begin_layout LyX-Code
14796 \begin_layout LyX-Code
14800 \begin_layout LyX-Code
14801 Product "<graphic fileref=
14803 "$$AbsOrRelPathMaster$$Basename.eps
14808 \begin_layout LyX-Code
14812 \begin_layout LyX-Code
14816 \begin_layout LyX-Code
14817 UpdateResult "$$AbsPath$$Basename.eps"
14820 \begin_layout LyX-Code
14821 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14824 \begin_layout LyX-Code
14825 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14828 \begin_layout LyX-Code
14832 \begin_layout LyX-Code
14833 Product "[XFig: $$FName]"
14836 \begin_layout LyX-Code
14840 \begin_layout LyX-Code
14844 \begin_layout Standard
14845 As you can see, the template is enclosed in
14846 \begin_inset Flex CharStyle:Code
14849 \begin_layout Plain Layout
14855 \SpecialChar \ldots{}
14857 \begin_inset Flex CharStyle:Code
14860 \begin_layout Plain Layout
14867 It contains a header specifying some general settings and, for each supported
14868 primary document file format, a section
14869 \begin_inset Flex CharStyle:Code
14872 \begin_layout Plain Layout
14878 \SpecialChar \ldots{}
14880 \begin_inset Flex CharStyle:Code
14883 \begin_layout Plain Layout
14892 \begin_layout Subsection
14893 The template header
14896 \begin_layout Description
14897 \begin_inset Flex CharStyle:Code
14900 \begin_layout Plain Layout
14901 AutomaticProduction
14902 \begin_inset space ~
14910 Whether the file represented by the template must be generated by LyX.
14911 This command must occur exactly once.
14914 \begin_layout Description
14915 \begin_inset Flex CharStyle:Code
14918 \begin_layout Plain Layout
14920 \begin_inset space ~
14928 A glob pattern that is used in the file dialog to filter out the desired
14930 If there is more than one possible file extension (e.g.
14931 \begin_inset space ~
14935 \begin_inset Flex CharStyle:Code
14938 \begin_layout Plain Layout
14945 \begin_inset Flex CharStyle:Code
14948 \begin_layout Plain Layout
14954 ), use something like
14955 \begin_inset Flex CharStyle:Code
14958 \begin_layout Plain Layout
14965 This command must occur exactly once.
14968 \begin_layout Description
14969 \begin_inset Flex CharStyle:Code
14972 \begin_layout Plain Layout
14974 \begin_inset space ~
14982 The text that is displayed on the button.
14983 This command must occur exactly once.
14986 \begin_layout Description
14987 \begin_inset Flex CharStyle:Code
14990 \begin_layout Plain Layout
14992 \begin_inset space ~
14996 \begin_inset space ~
15004 The help text that is used in the External dialog.
15005 Provide enough information to explain to the user just what the template
15006 can provide him with.
15007 This command must occur exactly once.
15010 \begin_layout Description
15011 \begin_inset Flex CharStyle:Code
15014 \begin_layout Plain Layout
15016 \begin_inset space ~
15024 The file format of the original file.
15025 This must be the name of a format that is known to LyX (see section
15026 \begin_inset CommandInset ref
15028 reference "sub:Formats"
15034 \begin_inset Quotes eld
15038 \begin_inset Flex CharStyle:Code
15041 \begin_layout Plain Layout
15048 \begin_inset Quotes erd
15051 if the template can handle original files of more than one format.
15052 LyX will attempt to interrogate the file itself in order to deduce its
15053 format in this case.
15054 This command must occur exactly once.
15057 \begin_layout Description
15058 \begin_inset Flex CharStyle:Code
15061 \begin_layout Plain Layout
15063 \begin_inset space ~
15071 A unique name for the template.
15072 It must not contain substitution macros (see below).
15075 \begin_layout Description
15076 \begin_inset Flex CharStyle:Code
15079 \begin_layout Plain Layout
15081 \begin_inset space ~
15084 Rotate|Resize|Clip|Extra
15089 This command specifies which transformations are supported by this template.
15090 It may occur zero or more times.
15091 This command enables the corresponding tabs in the external dialog.
15093 \begin_inset Flex CharStyle:Code
15096 \begin_layout Plain Layout
15102 command must have either a corresponding
15103 \begin_inset Flex CharStyle:Code
15106 \begin_layout Plain Layout
15113 \begin_inset Flex CharStyle:Code
15116 \begin_layout Plain Layout
15123 \begin_inset Flex CharStyle:Code
15126 \begin_layout Plain Layout
15133 Otherwise the transformation will not be supported by that format.
15136 \begin_layout Subsection
15140 \begin_layout Description
15141 \begin_inset Flex CharStyle:Code
15144 \begin_layout Plain Layout
15146 \begin_inset space ~
15149 LaTeX|PDFLaTeX|PlainText|DocBook
15154 The primary document file format that this format definition is for.
15155 Not every template has a sensible representation in all document file formats.
15156 Please define nevertheless a
15157 \begin_inset Flex CharStyle:Code
15160 \begin_layout Plain Layout
15166 section for all formats.
15167 Use a dummy text when no representation is available.
15168 Then you can at least see a reference to the external material in the exported
15172 \begin_layout Description
15173 \begin_inset Flex CharStyle:Code
15176 \begin_layout Plain Layout
15178 \begin_inset space ~
15182 \begin_inset space ~
15190 This command defines an additional macro
15191 \begin_inset Flex CharStyle:Code
15194 \begin_layout Plain Layout
15200 for substitution in
15201 \begin_inset Flex CharStyle:Code
15204 \begin_layout Plain Layout
15212 \begin_inset Flex CharStyle:Code
15215 \begin_layout Plain Layout
15221 itself may contain substitution macros.
15222 The advantage over using
15223 \begin_inset Flex CharStyle:Code
15226 \begin_layout Plain Layout
15233 \begin_inset Flex CharStyle:Code
15236 \begin_layout Plain Layout
15242 is that the substituted value of
15243 \begin_inset Flex CharStyle:Code
15246 \begin_layout Plain Layout
15252 is sanitized so that it is a valid optional argument in the document format.
15253 This command may occur zero or more times.
15256 \begin_layout Description
15257 \begin_inset Flex CharStyle:Code
15260 \begin_layout Plain Layout
15262 \begin_inset space ~
15270 The text that is inserted in the exported document.
15271 This is actually the most important command and can be quite complex.
15272 This command must occur exactly once.
15275 \begin_layout Description
15276 \begin_inset Flex CharStyle:Code
15279 \begin_layout Plain Layout
15281 \begin_inset space ~
15289 This command specifies a preamble snippet that will be included in the
15291 It has to be defined using
15292 \begin_inset Flex CharStyle:Code
15295 \begin_layout Plain Layout
15301 \SpecialChar \ldots{}
15303 \begin_inset Flex CharStyle:Code
15306 \begin_layout Plain Layout
15313 This command may occur zero or more times.
15316 \begin_layout Description
15317 \begin_inset Flex CharStyle:Code
15320 \begin_layout Plain Layout
15322 \begin_inset space ~
15326 \begin_inset space ~
15334 This command denotes files that are created by the conversion process and
15335 are needed for a particular export format.
15336 If the filename is relative, it is interpreted relative to the master document.
15337 This command may be given zero or more times.
15340 \begin_layout Description
15341 \begin_inset Flex CharStyle:Code
15344 \begin_layout Plain Layout
15346 \begin_inset space ~
15354 The name of a required LaTeX package.
15355 The package is included via
15356 \begin_inset Flex CharStyle:Code
15359 \begin_layout Plain Layout
15367 in the LaTeX preamble.
15368 This command may occur zero or more times.
15371 \begin_layout Description
15372 \begin_inset Flex CharStyle:Code
15375 \begin_layout Plain Layout
15377 \begin_inset space ~
15381 \begin_inset space ~
15384 RotationLatexCommand
15389 This command specifies that the built in LaTeX command should be used for
15391 This command may occur once or not at all.
15394 \begin_layout Description
15395 \begin_inset Flex CharStyle:Code
15398 \begin_layout Plain Layout
15400 \begin_inset space ~
15404 \begin_inset space ~
15412 This command specifies that the built in LaTeX command should be used for
15414 This command may occur once or not at all.
15417 \begin_layout Description
15418 \begin_inset Flex CharStyle:Code
15421 \begin_layout Plain Layout
15423 \begin_inset space ~
15427 \begin_inset space ~
15430 RotationLatexOption
15435 This command specifies that rotation is done via an optional argument.
15436 This command may occur once or not at all.
15439 \begin_layout Description
15440 \begin_inset Flex CharStyle:Code
15443 \begin_layout Plain Layout
15445 \begin_inset space ~
15449 \begin_inset space ~
15457 This command specifies that resizing is done via an optional argument.
15458 This command may occur once or not at all.
15461 \begin_layout Description
15462 \begin_inset Flex CharStyle:Code
15465 \begin_layout Plain Layout
15467 \begin_inset space ~
15471 \begin_inset space ~
15479 This command specifies that clipping is done via an optional argument.
15480 This command may occur once or not at all.
15483 \begin_layout Description
15484 \begin_inset Flex CharStyle:Code
15487 \begin_layout Plain Layout
15489 \begin_inset space ~
15493 \begin_inset space ~
15501 This command specifies that an extra optional argument is used.
15502 This command may occur once or not at all.
15505 \begin_layout Description
15506 \begin_inset Flex CharStyle:Code
15509 \begin_layout Plain Layout
15511 \begin_inset space ~
15519 The file format of the converted file.
15520 This must be the name of a format that is known to LyX (see the
15521 \begin_inset Flex CharStyle:MenuItem
15524 \begin_layout Plain Layout
15529 ools\SpecialChar \menuseparator
15534 references:Conversion
15540 This command must occur exactly once.
15543 \begin_layout Description
15544 \begin_inset Flex CharStyle:Code
15547 \begin_layout Plain Layout
15549 \begin_inset space ~
15557 The file name of the converted file.
15558 The file name must be absolute.
15559 This command must occur exactly once.
15562 \begin_layout Subsection
15563 Preamble definitions
15566 \begin_layout Standard
15567 The external template configuration file may contain additional preamble
15568 definitions enclosed by
15569 \begin_inset Flex CharStyle:Code
15572 \begin_layout Plain Layout
15578 \SpecialChar \ldots{}
15580 \begin_inset Flex CharStyle:Code
15583 \begin_layout Plain Layout
15590 They can be used by the templates in the
15591 \begin_inset Flex CharStyle:Code
15594 \begin_layout Plain Layout
15603 \begin_layout Section
15604 The substitution mechanism
15607 \begin_layout Standard
15608 When the external material facility invokes an external program, it is done
15609 on the basis of a command defined in the template configuration file.
15610 These commands can contain various macros that are expanded before execution.
15611 Execution always take place in the directory of the containing document.
15614 \begin_layout Standard
15615 Also, whenever external material is to be displayed, the name will be produced
15616 by the substitution mechanism, and most other commands in the template
15617 definition support substitution as well.
15620 \begin_layout Standard
15621 The available macros are the following:
15624 \begin_layout Description
15625 \begin_inset Flex CharStyle:Code
15628 \begin_layout Plain Layout
15629 $$AbsOrRelPathMaster
15634 The file path, absolute or relative to the master LyX document.
15637 \begin_layout Description
15638 \begin_inset Flex CharStyle:Code
15641 \begin_layout Plain Layout
15642 $$AbsOrRelPathParent
15647 The file path, absolute or relative to the LyX document.
15650 \begin_layout Description
15651 \begin_inset Flex CharStyle:Code
15654 \begin_layout Plain Layout
15660 The absolute file path.
15663 \begin_layout Description
15664 \begin_inset Flex CharStyle:Code
15667 \begin_layout Plain Layout
15673 The filename without path and without the extension.
15676 \begin_layout Description
15677 \begin_inset Flex CharStyle:Code
15680 \begin_layout Plain Layout
15682 \begin_inset Quotes eld
15686 \begin_inset Quotes erd
15694 This macro will expand to the contents of the file with the name
15695 \begin_inset Flex CharStyle:Code
15698 \begin_layout Plain Layout
15707 \begin_layout Description
15708 \begin_inset Flex CharStyle:Code
15711 \begin_layout Plain Layout
15717 The file extension (including the dot).
15720 \begin_layout Description
15721 \begin_inset Flex CharStyle:Code
15724 \begin_layout Plain Layout
15730 The filename of the file specified in the external material dialog.
15731 This is either an absolute name, or it is relative to the LyX document.
15734 \begin_layout Description
15735 \begin_inset Flex CharStyle:Code
15738 \begin_layout Plain Layout
15745 \begin_inset Flex CharStyle:Code
15748 \begin_layout Plain Layout
15754 (absolute name or relative to the LyX document).
15757 \begin_layout Description
15758 \begin_inset Flex CharStyle:Code
15761 \begin_layout Plain Layout
15767 The file path, relative to the master LyX document.
15770 \begin_layout Description
15771 \begin_inset Flex CharStyle:Code
15774 \begin_layout Plain Layout
15780 The file path, relative to the LyX document.
15783 \begin_layout Description
15784 \begin_inset Flex CharStyle:Code
15787 \begin_layout Plain Layout
15793 This macro will expand to the absolute path of the system directory.
15794 This is typically used to point to the various helper scripts that are
15798 \begin_layout Description
15799 \begin_inset Flex CharStyle:Code
15802 \begin_layout Plain Layout
15808 A name and full path to a temporary file which will be automatically deleted
15809 whenever the containing document is closed, or the external material insertion
15813 \begin_layout Standard
15814 All path macros contain a trailing directory separator, so you can construct
15816 the absolute filename with
15817 \begin_inset Flex CharStyle:Code
15820 \begin_layout Plain Layout
15821 $$AbsPath$$Basename$$Extension
15829 \begin_layout Standard
15830 The macros above are substituted in all commands unless otherwise noted.
15832 \begin_inset Flex CharStyle:Code
15835 \begin_layout Plain Layout
15841 supports additionally the following substitutions if they are enabled by
15843 \begin_inset Flex CharStyle:Code
15846 \begin_layout Plain Layout
15853 \begin_inset Flex CharStyle:Code
15856 \begin_layout Plain Layout
15865 \begin_layout Description
15866 \begin_inset Flex CharStyle:Code
15869 \begin_layout Plain Layout
15875 The front part of the resize command.
15878 \begin_layout Description
15879 \begin_inset Flex CharStyle:Code
15882 \begin_layout Plain Layout
15888 The back part of the resize command.
15891 \begin_layout Description
15892 \begin_inset Flex CharStyle:Code
15895 \begin_layout Plain Layout
15901 The front part of the rotation command.
15904 \begin_layout Description
15905 \begin_inset Flex CharStyle:Code
15908 \begin_layout Plain Layout
15914 The back part of the rotation command.
15917 \begin_layout Standard
15918 The value string of the
15919 \begin_inset Flex CharStyle:Code
15922 \begin_layout Plain Layout
15928 command supports additionally the following substitutions if they are enabled
15930 \begin_inset Flex CharStyle:Code
15933 \begin_layout Plain Layout
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
15991 \begin_layout Description
15992 \begin_inset Flex CharStyle:Code
15995 \begin_layout Plain Layout
16001 The rotation option.
16004 \begin_layout Standard
16005 You may ask why there are so many path macros.
16006 There are mainly two reasons:
16009 \begin_layout Enumerate
16010 Relative and absolute file names should remain relative or absolute, respectivel
16012 Users may have reasons to prefer either form.
16013 Relative names are useful for portable documents that should work on different
16014 machines, for example.
16015 Absolute names may be required by some programs.
16018 \begin_layout Enumerate
16019 LaTeX treats relative file names differently than LyX and other programs
16020 in nested included files.
16021 For LyX, a relative file name is always relative to the document that contains
16023 For LaTeX, it is always relative to the master document.
16024 These two definitions are identical if you have only one document, but
16025 differ if you have a master document that includes part documents.
16026 That means that relative filenames must be transformed when presented to
16028 Fortunately LyX does this automatically for you if you choose the right
16032 \begin_layout Standard
16033 So which path macro should be used in new template definitions? The rule
16037 \begin_layout Itemize
16039 \begin_inset Flex CharStyle:Code
16042 \begin_layout Plain Layout
16048 if an absolute path is required.
16051 \begin_layout Itemize
16053 \begin_inset Flex CharStyle:Code
16056 \begin_layout Plain Layout
16057 $$AbsOrRelPathMaster
16062 if the substituted string is some kind of LaTeX input.
16065 \begin_layout Itemize
16067 \begin_inset Flex CharStyle:Code
16070 \begin_layout Plain Layout
16071 $$AbsOrRelPathParent
16076 in order to preserve the user's choice.
16079 \begin_layout Standard
16080 There are special cases where this rule does not work and e.g.
16081 \begin_inset space ~
16084 relative names are needed, but normally it will work just fine.
16085 One example for such a case is the command
16086 \begin_inset Flex CharStyle:Code
16089 \begin_layout Plain Layout
16090 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
16095 in the XFig template above: We can't use the absolute name because the
16097 \begin_inset Flex CharStyle:Code
16100 \begin_layout Plain Layout
16106 files needs the relative name in order to rewrite the file content.
16109 \begin_layout Section
16110 \begin_inset CommandInset label
16112 name "sec:Security-discussion"
16116 Security discussion
16119 \begin_layout Standard
16120 \begin_inset Note Note
16123 \begin_layout Plain Layout
16124 This section is outdated
16129 The external material feature interfaces with a lot of external programs
16130 and does so automatically, so we have to consider the security implications
16132 In particular, since you have the option of including your own filenames
16133 and/or parameter strings and those are expanded into a command, it seems
16134 that it would be possible to create a malicious document which executes
16135 arbitrary commands when a user views or prints the document.
16136 This is something we definately want to avoid.
16139 \begin_layout Standard
16140 However, since the external program commands are specified in the template
16141 configuration file only, there are no security issues if LyX is properly
16142 configured with safe templates only.
16143 This is so because the external programs are invoked with the
16144 \begin_inset Flex CharStyle:Code
16147 \begin_layout Plain Layout
16153 -system call rather than the
16154 \begin_inset Flex CharStyle:Code
16157 \begin_layout Plain Layout
16163 system-call, so it's not possible to execute arbitrary commands from the
16164 filename or parameter section via the shell.
16167 \begin_layout Standard
16168 This also implies that you are restricted in what command strings you can
16169 use in the external material templates.
16170 In particular, pipes and redirection are not readily available.
16171 This has to be so if LyX should remain safe.
16172 If you want to use some of the shell features, you should write a safe
16173 script to do this in a controlled manner, and then invoke the script from
16174 the command string.
16176 \begin_inset Flex CharStyle:Code
16179 \begin_layout Plain Layout
16185 directory of the LyX installation, you can find a safe wrapper script
16186 \begin_inset Flex CharStyle:Code
16189 \begin_layout Plain Layout
16190 general_command_wrapper.py
16195 that supports redirection of input and output.
16196 That can serve as an example for how to write safe template scripts.
16197 For a more advanced example that uses
16198 \begin_inset Flex CharStyle:Code
16201 \begin_layout Plain Layout
16207 and friends, take a look at the
16208 \begin_inset Flex CharStyle:Code
16211 \begin_layout Plain Layout
16220 \begin_layout Standard
16221 It is possible to design a template that interacts directly with the shell,
16222 but since this would allow a malicious user to execute arbitrary commands
16223 by writing clever filenames and/or parameters, we generally recommend that
16224 you only use safe scripts that work with the
16225 \begin_inset Flex CharStyle:Code
16228 \begin_layout Plain Layout
16234 system call in a controlled manner.
16235 Of course, for use in a controlled environment, it can be tempting to just
16236 fall back to use ordinary shell scripts.
16237 If you do so, be aware that you
16241 provide an easily exploitable security hole in your system.
16242 Of course it stands to reason that such unsafe templates will never be
16243 included in the standard LyX distribution, although we do encourage people
16244 to submit new templates in the open source tradition.
16245 But LyX as shipped from the official distribution channels will never have
16249 \begin_layout Standard
16250 Including external material provides a lot of power, and you have to be
16251 careful not to introduce security hazards with this power.
16252 A subtle error in a single line in an innocent looking script can open
16253 the door to huge security problems.
16254 So if you do not fully understand the issues, we recommend that you consult
16255 a knowledgable security professional or the LyX development team if you
16256 have any questions about whether a given template is safe or not.
16257 And do this before you use it in an uncontrolled environment.
16260 \begin_layout Chapter
16264 \begin_layout Section
16268 \begin_layout Standard
16269 The LyX server is a method implemented in LyX that will enable other programs
16270 to talk to LyX, invoke LyX commands, and retrieve information about the
16271 LyX internal state.
16272 This is only intended for advanced users, but they should find it useful.
16273 Please note that, at present,
16275 the server does not work on Windows
16281 \begin_layout Plain Layout
16282 There is no principled reason it cannot do so.
16283 But none of the developers on Windows® have yet implemented this functionality
16292 \begin_layout Section
16293 Starting the LyX Server
16296 \begin_layout Standard
16297 The LyX server works through the use of a pair of named pipes.
16298 These are usually located in
16299 \begin_inset Flex CharStyle:Code
16302 \begin_layout Plain Layout
16309 \begin_inset Quotes eld
16313 \begin_inset Flex CharStyle:Code
16316 \begin_layout Plain Layout
16323 \begin_inset Quotes erd
16327 \begin_inset Quotes eld
16331 \begin_inset Flex CharStyle:Code
16334 \begin_layout Plain Layout
16341 \begin_inset Quotes erd
16345 External programs write into
16346 \begin_inset Flex CharStyle:Code
16349 \begin_layout Plain Layout
16355 and read back data from
16356 \begin_inset Flex CharStyle:Code
16359 \begin_layout Plain Layout
16366 The stem of the pipe names can be defined in the
16367 \begin_inset Flex CharStyle:MenuItem
16370 \begin_layout Plain Layout
16375 ools\SpecialChar \menuseparator
16385 dialog, for example
16386 \begin_inset Flex CharStyle:Code
16389 \begin_layout Plain Layout
16390 "/home/myhome/.lyxpipe"
16398 \begin_layout Standard
16400 \begin_inset Flex CharStyle:Code
16403 \begin_layout Plain Layout
16410 \begin_inset Flex CharStyle:Code
16413 \begin_layout Plain Layout
16419 ' to create the pipes.
16420 The above setting also has the effect of activating the LyX server.
16421 If one of the pipes already exists, LyX will assume that another LyX process
16422 is already running and will not start the server.
16423 To have several LyX processes with servers at the same time, you have to
16424 change the configuration between the start of the programs.
16427 \begin_layout Standard
16428 If you are developing a client program, you might find it useful to enable
16429 debugging information from the LyX server.
16430 Do this by starting LyX as lyx -dbg lyxserver.
16433 \begin_layout Standard
16434 Warning: if LyX crashes, it may not manage to remove the pipes; in this
16435 case you must remove them manually.
16436 If LyX starts and the pipes exist already, it will not start any server.
16439 \begin_layout Standard
16440 Other than this, there are a few points to consider:
16443 \begin_layout Itemize
16444 Both server and clients must run on UNIX or OS/2 machines.
16445 Communications between LyX on UNIX and clients on OS/2 or vice versa is
16446 not possible right now.
16449 \begin_layout Itemize
16450 On OS/2, only one client can connect to LyXServer at a time.
16453 \begin_layout Itemize
16454 On OS/2, clients must open inpipe with
16455 \begin_inset Flex CharStyle:Code
16458 \begin_layout Plain Layout
16467 \begin_layout Standard
16471 \begin_layout Standard
16472 You can find a complete example client written in C in the source distribution
16474 \begin_inset Flex CharStyle:Code
16477 \begin_layout Plain Layout
16478 development/lyxserver/server_monitor.c
16486 \begin_layout Section
16487 Normal communication
16490 \begin_layout Standard
16491 To issue a LyX call, the client writes a line of ASCII text into the input
16493 This line has the following format:
16496 \begin_layout Quote
16510 \begin_layout Description
16515 is a name that the client can choose arbitrarily.
16516 Its only use is that LyX will echo it if it sends an answer---so a client
16517 can dispatch results from different requesters.
16520 \begin_layout Description
16525 is the function you want LyX to perform.
16526 It is the same as the commands you'd use in the minibuffer.
16529 \begin_layout Description
16534 is an optional argument which is meaningful only to some functions (for
16536 \begin_inset Quotes eld
16540 \begin_inset Quotes erd
16543 which will insert the argument as text at the cursor position.)
16546 \begin_layout Standard
16547 The answer from LyX will arrive in the output pipe and be of the form
16550 \begin_layout Quote
16564 \begin_layout Standard
16573 are just echoed from the command request, while
16577 is more or less useful information filled according to how the command
16578 execution worked out.
16579 Some commands will return information about the internal state of LyX,
16581 \begin_inset Quotes eld
16585 \begin_inset Quotes erd
16588 , while other will return an empty data-response.
16589 This means that the command execution went fine.
16592 \begin_layout Standard
16593 In case of errors, the response from LyX will have this form
16596 \begin_layout Quote
16610 \begin_layout Standard
16615 should contain an explanation of why the command failed.
16618 \begin_layout Standard
16622 \begin_layout LyX-Code
16623 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
16626 \begin_layout LyX-Code
16627 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
16628 \begin_inset Newline newline
16631 read a <~/.lyxpipe.out
16632 \begin_inset Newline newline
16638 \begin_layout Section
16642 \begin_layout Standard
16643 LyX can notify clients of events going on asynchronously.
16644 Currently it will only do this if the user binds a key sequence with the
16646 \begin_inset Quotes eld
16650 \begin_inset Quotes erd
16654 The format of the string LyX sends is as follows:
16657 \begin_layout Quote
16658 \begin_inset Flex CharStyle:Code
16661 \begin_layout Plain Layout
16672 \begin_layout Standard
16677 is the printed representation of the key sequence that was actually typed
16681 \begin_layout Standard
16682 This mechanism can be used to extend LyX's command set and implement macros:
16683 bind some key sequence to
16684 \begin_inset Quotes eld
16688 \begin_inset Quotes erd
16691 , start a client that listens on the out pipe, dispatches the command according
16692 to the sequence and starts a function that may use LyX calls and LyX requests
16693 to issue a command or a series of commands to LyX.
16696 \begin_layout Section
16697 The simple LyX Server Protocol
16700 \begin_layout Standard
16701 LyX implements a simple protocol that can be used for session management.
16702 All messages are of the form
16705 \begin_layout Quote
16715 \begin_layout Standard
16721 \begin_inset Quotes eld
16725 \begin_inset Quotes erd
16729 \begin_inset Quotes eld
16733 \begin_inset Quotes erd
16738 \begin_inset Quotes eld
16742 \begin_inset Quotes erd
16745 is received from a client, LyX will report back to inform the client that
16746 it's listening to it's messages, while
16747 \begin_inset Quotes eld
16751 \begin_inset Quotes erd
16754 sent from LyX will inform clients that LyX is closing.