1 #LyX 2.0.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 this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document 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
44 \use_default_options false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
67 \font_typewriter default
68 \font_default_family default
76 \default_output_format default
77 \bibtex_command default
78 \index_command default
82 \pdf_title "LyX Configuration Manual"
83 \pdf_author "LyX Team"
84 \pdf_subject "LyX-documentation Customization"
85 \pdf_keywords "LyX, documentation, customization"
87 \pdf_bookmarksnumbered true
88 \pdf_bookmarksopen true
89 \pdf_bookmarksopenlevel 1
94 \pdf_pdfusetitle false
95 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
103 \paperorientation portrait
110 \paragraph_separation indent
112 \quotes_language english
115 \paperpagestyle headings
116 \tracking_changes true
117 \output_changes false
118 \author "Jean-Marc Lasgouttes"
125 Customizing LyX: Features for the Advanced User
133 \begin_layout Plain Layout
135 If you have comments or error corrections, please send them to the LyX Documenta
137 \begin_inset CommandInset href
139 target "lyx-docs@lists.lyx.org"
146 \begin_inset Quotes eld
150 \begin_inset Quotes erd
153 in the subject header, and please cc the current maintainer of this file,
164 \begin_inset Newline newline
168 \begin_inset Newline newline
174 \begin_layout Standard
175 \begin_inset CommandInset toc
176 LatexCommand tableofcontents
183 \begin_layout Standard
184 \begin_inset Note Note
187 \begin_layout Plain Layout
188 Please use change tracking when modifying this document.
189 This makes it easier for our translators to recognize things that have
190 been changed, and it helps the maintainer keep up-to-date with what's been
199 \begin_layout Chapter
203 \begin_layout Standard
204 This manual covers the customization features present in LyX.
205 In it, we discuss issues like keyboard shortcuts, screen previewing options,
206 printer options, sending commands to LyX via the LyX Server, internationalizati
209 classes and LyX layouts, etc.
210 We can't possibly hope to touch on everything you can change—our developers
211 add new features faster than we can document them—but we will explain the
212 most common customizations and hopefully point you in the right direction
213 for some of the more obscure ones.
216 \begin_layout Standard
217 \begin_inset Branch OutDated
220 \begin_layout Standard
221 Information from previous versions of this document that now seems to be
222 outdated is contained in the
224 branch of this document.
225 By default, this information will not appear in the
235 \begin_layout Chapter
236 LyX configuration files
239 \begin_layout Standard
240 This chapter aims to help you to find your way through the LyX configuration
242 Before continuing to read this chapter, you should find out where your
243 LyX library and user directories are by using
244 \begin_inset Flex CharStyle:MenuItem
247 \begin_layout Plain Layout
248 Help\SpecialChar \menuseparator
259 The library directory is the place where LyX places its system-wide configurati
260 on files; the user directory is where you can place your modified versions.
261 We will call the former
262 \begin_inset Flex CharStyle:Code
265 \begin_layout Plain Layout
273 \begin_inset Flex CharStyle:MenuItem
276 \begin_layout Plain Layout
283 in the remainder of this document.
287 \begin_layout Section
289 \begin_inset Flex CharStyle:Code
292 \begin_layout Plain Layout
302 \begin_layout Standard
303 \begin_inset Flex CharStyle:Code
306 \begin_layout Plain Layout
313 and its sub-directories contain a number of files and that can be used
314 to customize LyX's behavior.
315 You can change many of these files from within LyX itself through the
316 \begin_inset Flex CharStyle:MenuItem
319 \begin_layout Plain Layout
320 Tools\SpecialChar \menuseparator
327 Most customization that you will want to do in LyX is possible through
329 However, many other inner aspects of LyX can be customized by modifying
331 \begin_inset Flex CharStyle:Code
334 \begin_layout Plain Layout
342 These files fall in different categories, described in the following subsection
346 \begin_layout Subsection
347 Automatically generated files
350 \begin_layout Standard
351 The files, which are to be found in
352 \begin_inset Flex CharStyle:MenuItem
355 \begin_layout Plain Layout
362 , are generated when you configure LyX.
363 They contain various default values that are guessed by inspection.
364 In general, it is not a good idea to modify them, since they might be overwritt
368 \begin_layout Labeling
369 \labelwidthstring 00.00.0000
370 \begin_inset Flex CharStyle:Code
373 \begin_layout Plain Layout
379 contains defaults for various commands.
382 \begin_layout Labeling
383 \labelwidthstring 00.00.0000
384 \begin_inset Flex CharStyle:Code
387 \begin_layout Plain Layout
394 contains the list of packages that have been recognized by LyX.
395 It is currently unused by the LyX program itself, but the information extracted
396 , and more, is made available with
397 \begin_inset Flex CharStyle:MenuItem
400 \begin_layout Plain Layout
401 Help\SpecialChar \menuseparator
416 \begin_layout Labeling
417 \labelwidthstring 00.00.0000
418 \begin_inset Flex CharStyle:Code
421 \begin_layout Plain Layout
430 the list of text classes that have been found in your
431 \begin_inset Flex CharStyle:Code
434 \begin_layout Plain Layout
440 directories, along with the associated
442 document class and their description.
445 \begin_layout Labeling
446 \labelwidthstring 00.00.0000
447 \begin_inset Flex CharStyle:Code
450 \begin_layout Plain Layout
459 the list of layout modules found in your
460 \begin_inset Flex CharStyle:Code
463 \begin_layout Plain Layout
472 \begin_layout Labeling
473 \labelwidthstring 00.00.0000
474 \begin_inset Flex CharStyle:Code
477 \begin_layout Plain Layout
484 lists of various sorts of
486 -related files found on your system
489 \begin_layout Labeling
490 \labelwidthstring 00.00.0000
491 \begin_inset Flex CharStyle:Code
494 \begin_layout Plain Layout
502 is automatically generated during configuration from the file
503 \begin_inset Flex CharStyle:Code
506 \begin_layout Plain Layout
515 It contains information on your
520 \begin_layout Subsection
524 \begin_layout Standard
525 These directories are duplicated between
526 \begin_inset Flex CharStyle:Code
529 \begin_layout Plain Layout
537 \begin_inset Flex CharStyle:Code
540 \begin_layout Plain Layout
548 If a particular files exists in both places, the one in
549 \begin_inset Flex CharStyle:Code
552 \begin_layout Plain Layout
562 \begin_layout Labeling
563 \labelwidthstring 00.00.0000
564 \begin_inset Flex CharStyle:Code
567 \begin_layout Plain Layout
573 this directory contains files with the extension
574 \begin_inset Flex CharStyle:Code
577 \begin_layout Plain Layout
586 If there exists an internationalized version of the bind file named
587 \begin_inset Flex CharStyle:Code
590 \begin_layout Plain Layout
596 , that will be used first.
599 \begin_layout Labeling
600 \labelwidthstring 00.00.0000
601 \begin_inset Flex CharStyle:Code
604 \begin_layout Plain Layout
612 contains graphics files that can be included in documents.
616 \begin_layout Labeling
617 \labelwidthstring 00.00.0000
618 \begin_inset Flex CharStyle:Code
621 \begin_layout Plain Layout
627 contains LyX documentation files (including the one you are currently reading).
629 \begin_inset Flex CharStyle:Code
632 \begin_layout Plain Layout
640 deserves special attention, as noted above.
641 The internationalized help docs are in
644 \begin_inset Flex CharStyle:Code
647 \begin_layout Plain Layout
654 \begin_inset Quotes eld
658 \begin_inset Quotes erd
661 is the ISO language code.
667 \begin_inset CommandInset ref
669 reference "cha:Internationalizing-LyX"
676 \begin_layout Labeling
677 \labelwidthstring 00.00.0000
678 \begin_inset Flex CharStyle:Code
681 \begin_layout Plain Layout
687 contains example files that explain how to use some features.
688 In the file browser, press the
689 \begin_inset Flex CharStyle:MenuItem
692 \begin_layout Plain Layout
701 \begin_layout Labeling
702 \labelwidthstring 00.00.0000
703 \begin_inset Flex CharStyle:Code
706 \begin_layout Plain Layout
712 contains image files that are used by the
713 \begin_inset Flex CharStyle:MenuItem
716 \begin_layout Plain Layout
723 In addition, it also contains the individual icons used in the toolbar
724 and the banners that can be shown when LyX is launched.
727 \begin_layout Labeling
728 \labelwidthstring 00.00.0000
729 \begin_inset Flex CharStyle:Code
732 \begin_layout Plain Layout
748 \begin_inset CommandInset ref
750 reference "sec:International-Keymap-Stuff"
757 \begin_layout Labeling
758 \labelwidthstring 00.00.0000
759 \begin_inset Flex CharStyle:Code
762 \begin_layout Plain Layout
768 contains the text class and module files described in Chapter
773 \begin_inset CommandInset ref
775 reference "cha:Installing-New-Document"
782 \begin_layout Labeling
783 \labelwidthstring 00.00.0000
784 \begin_inset Flex CharStyle:Code
787 \begin_layout Plain Layout
795 \begin_inset Flex CharStyle:Code
798 \begin_layout Plain Layout
805 Python scripts used to convert between LyX versions.
806 These can be run from the command line if, say, you want to batch-convert
810 \begin_layout Labeling
811 \labelwidthstring 00.00.0000
812 \begin_inset Flex CharStyle:Code
815 \begin_layout Plain Layout
821 contains some files that demonstrate the capabilities of the
822 \begin_inset Flex CharStyle:MenuItem
825 \begin_layout Plain Layout
836 Also contains some scripts used by LyX itself.
839 \begin_layout Labeling
840 \labelwidthstring 00.00.0000
841 \begin_inset Flex CharStyle:Code
844 \begin_layout Plain Layout
850 contains the standard LyX template files described in Chapter
855 \begin_inset CommandInset ref
857 reference "sec:Creating-Templates"
864 \begin_layout Labeling
865 \labelwidthstring 00.00.0000
866 \begin_inset Flex CharStyle:Code
869 \begin_layout Plain Layout
877 contains files with the extension
878 \begin_inset Flex CharStyle:Code
881 \begin_layout Plain Layout
888 that define the user interface to LyX.
889 That is, the files define which items appear in which menus and the items
890 appearing on the toolbar.
893 \begin_layout Subsection
894 Files you don't want to modify
897 \begin_layout Standard
898 These files are used internally by LyX and you generally do not need to
899 modify them unless you are a developer.
902 \begin_layout Labeling
903 \labelwidthstring 00.00.0000
904 \begin_inset Flex CharStyle:Code
907 \begin_layout Plain Layout
913 this file contains the list of LyX developers.
914 The contents are displayed with the menu entry
915 \begin_inset Flex CharStyle:MenuItem
918 \begin_layout Plain Layout
919 Help\SpecialChar \menuseparator
932 \begin_layout Labeling
933 \labelwidthstring 00.00.0000
934 \begin_inset Flex CharStyle:Code
937 \begin_layout Plain Layout
948 script used during the configuration process.
952 \begin_layout Labeling
953 \labelwidthstring 00.00.0000
954 \begin_inset Flex CharStyle:Code
957 \begin_layout Plain Layout
964 this is the script that is used to re-configure LyX.
965 It creates configuration files in the directory it was run from.
968 \begin_layout Subsection
969 Other files needing a line or two...
972 \begin_layout Labeling
973 \labelwidthstring 00.00.0000
974 \begin_inset Flex CharStyle:Code
977 \begin_layout Plain Layout
984 this contains tables describing how different character
986 can be mapped to Unicode
989 \begin_layout Labeling
990 \labelwidthstring 00.00.0000
991 \begin_inset Flex CharStyle:Code
994 \begin_layout Plain Layout
1000 this file contains the templates available to the new
1001 \begin_inset Flex CharStyle:MenuItem
1004 \begin_layout Plain Layout
1006 \begin_inset space ~
1017 \begin_layout Labeling
1018 \labelwidthstring 00.00.0000
1019 \begin_inset Flex CharStyle:Code
1022 \begin_layout Plain Layout
1028 this file contains a list of all the languages currently supported by LyX.
1031 \begin_layout Section
1032 Your local configuration directory
1035 \begin_layout Standard
1036 Even if you are using LyX as an unprivileged user, you might want to change
1037 LyX configuration for your own use.
1039 \begin_inset Flex CharStyle:Code
1042 \begin_layout Plain Layout
1049 directory contains all your personal configuration files.
1050 This is the directory described as
1051 \begin_inset Quotes eld
1055 \begin_inset Quotes erd
1059 \begin_inset Flex CharStyle:MenuItem
1062 \begin_layout Plain Layout
1063 Help\SpecialChar \menuseparator
1065 \begin_inset space ~
1074 This directory is used as a mirror of
1075 \begin_inset Flex CharStyle:Code
1078 \begin_layout Plain Layout
1085 , which means that every file in
1086 \begin_inset Flex CharStyle:Code
1089 \begin_layout Plain Layout
1096 is a replacement for the corresponding file in
1097 \begin_inset Flex CharStyle:Code
1100 \begin_layout Plain Layout
1108 Any configuration file described in the above sections can be placed either
1109 in the system-wide directory, in which case it will affect all users, or
1110 in your local directory for your own use.
1113 \begin_layout Standard
1114 To make things clearer, let's provide a few examples:
1117 \begin_layout Itemize
1118 The preferences set in the
1119 \begin_inset Flex CharStyle:MenuItem
1122 \begin_layout Plain Layout
1123 Tools\SpecialChar \menuseparator
1129 dialog are saved to a file
1130 \begin_inset Flex CharStyle:Code
1133 \begin_layout Plain Layout
1140 \begin_inset Flex CharStyle:Code
1143 \begin_layout Plain Layout
1153 \begin_layout Itemize
1154 When you reconfigure using
1155 \begin_inset Flex CharStyle:MenuItem
1158 \begin_layout Plain Layout
1159 Tools\SpecialChar \menuseparator
1166 \begin_inset Flex CharStyle:Code
1169 \begin_layout Plain Layout
1176 script, and the resulting files are written in your local configuration
1178 This means that any additional text class file that you might have added
1180 \begin_inset Flex CharStyle:Code
1183 \begin_layout Plain Layout
1191 will be added to the list of classes in the
1192 \begin_inset Flex CharStyle:MenuItem
1195 \begin_layout Plain Layout
1196 Document\SpecialChar \menuseparator
1205 \begin_layout Itemize
1206 If you get some updated documentation from LyX ftp site and cannot install
1207 it because you do not have sysadmin rights on your system, you can just
1209 \begin_inset Flex CharStyle:Code
1212 \begin_layout Plain Layout
1220 and the items in the
1221 \begin_inset Flex CharStyle:MenuItem
1224 \begin_layout Plain Layout
1230 menu will open them!
1233 \begin_layout Section
1234 Running LyX with multiple configurations
1237 \begin_layout Standard
1238 The configuration freedom of the local configuration directory may not suffice
1239 if you want to have more than one configuration at your disposal.
1240 For example, you may want to be use different key bindings or printer settings
1242 You can achieve this by having several such directories.
1243 You then specify which directory to use at run-time.
1246 \begin_layout Standard
1247 Invoking LyX with the command line switch
1248 \begin_inset Flex CharStyle:Code
1251 \begin_layout Plain Layout
1262 instructs the program to read the configuration from that directory, and
1263 not from the default directory.
1264 (You can determine the default directory by running LyX without the
1265 \begin_inset Flex CharStyle:Code
1268 \begin_layout Plain Layout
1275 switch.) If the specified directory does not exist, LyX offers to create
1276 it for you, just like it does for the default directory on the first time
1277 you run the program.
1278 You can modify the configuration options in this additional user directory
1279 exactly as you would for the default directory.
1280 These directories are completely independent (but read on).
1281 Note that setting the environment variable
1282 \begin_inset Flex CharStyle:Code
1285 \begin_layout Plain Layout
1294 to some value has exactly the same effect.
1297 \begin_layout Standard
1298 Having several configurations also requires more maintenance: if you want
1299 to add a new layout to
1300 \begin_inset Flex CharStyle:Code
1303 \begin_layout Plain Layout
1311 which you want available from all your configurations, you must add it
1312 to each directory separately.
1313 You can avoid this with the following trick: after LyX creates the additional
1314 directory, most of the
1316 (see above) are empty.
1317 If you want the new configuration to mirror an existing one, replace the
1320 with a symbolic link to the matching
1322 in the existing configuration.
1324 \begin_inset Flex CharStyle:Code
1327 \begin_layout Plain Layout
1335 , however, since it contains a file written by the configuration script
1336 (also accessible through
1337 \begin_inset Flex CharStyle:MenuItem
1340 \begin_layout Plain Layout
1341 Tools\SpecialChar \menuseparator
1347 ) which is configuration-specific.
1350 \begin_layout Chapter
1351 The Preferences dialog
1354 \begin_layout Standard
1355 All options of the preferences dialog are described in the Appendix
1357 The Preferences Dialog
1364 For some options you might find here more details.
1367 \begin_layout Section
1369 \begin_inset CommandInset label
1378 \begin_layout Standard
1379 The first step is to define your file formats if they are not already defined.
1381 \begin_inset Flex CharStyle:MenuItem
1384 \begin_layout Plain Layout
1385 Tools\SpecialChar \menuseparator
1393 \begin_inset Flex CharStyle:MenuItem
1396 \begin_layout Plain Layout
1397 File Handling\SpecialChar \menuseparator
1404 \begin_inset Flex CharStyle:MenuItem
1407 \begin_layout Plain Layout
1408 New\SpecialChar \ldots{}
1414 button to define your new format.
1416 \begin_inset Flex CharStyle:MenuItem
1419 \begin_layout Plain Layout
1425 field contains the name used to identify the format in the GUI.
1427 \begin_inset Flex CharStyle:MenuItem
1430 \begin_layout Plain Layout
1436 is used to identify the format internally.
1437 You will also need to enter a file extension.
1438 These are all required.
1440 \begin_inset Flex CharStyle:MenuItem
1443 \begin_layout Plain Layout
1449 field is used to provide a keyboard shortcut on the menus.
1450 (For example, pressing
1451 \begin_inset Flex CharStyle:MenuItem
1454 \begin_layout Plain Layout
1461 \begin_inset Flex CharStyle:MenuItem
1464 \begin_layout Plain Layout
1465 View\SpecialChar \menuseparator
1474 \begin_layout Standard
1476 \begin_inset Flex CharStyle:MenuItem
1479 \begin_layout Plain Layout
1486 \begin_inset Flex CharStyle:MenuItem
1489 \begin_layout Plain Layout
1496 For example, you might want to use
1497 \begin_inset Flex CharStyle:MenuItem
1500 \begin_layout Plain Layout
1507 to view PostScript files.
1508 You can enter the command needed to start the program in the corresponding
1510 In defining this command, you can use the four variables listed in the
1512 The viewer is launched when you view an image in LyX or use the
1513 \begin_inset Flex CharStyle:MenuItem
1516 \begin_layout Plain Layout
1523 The editor is for example launched when you right-click on an image and
1525 \begin_inset Flex CharStyle:MenuItem
1528 \begin_layout Plain Layout
1534 in the appearing context menu.
1537 \begin_layout Standard
1539 \begin_inset Flex CharStyle:MenuItem
1542 \begin_layout Plain Layout
1548 option tells LyX that a format is suitable for document export.
1549 If this is set and if a suitable conversion route exists (see sec.
1550 \begin_inset space \thinspace{}
1554 \begin_inset CommandInset ref
1556 reference "sec:Converters"
1560 ), the format will appear in the
1561 \begin_inset Flex CharStyle:MenuItem
1564 \begin_layout Plain Layout
1565 File\SpecialChar \menuseparator
1572 The format will also appear in the
1573 \begin_inset Flex CharStyle:MenuItem
1576 \begin_layout Plain Layout
1582 menu if a viewer is specified for the format.
1583 Pure image formats, such as
1584 \begin_inset Flex CharStyle:Code
1587 \begin_layout Plain Layout
1594 , should not use this option.
1595 Formats that can both represent vector graphics and documents like
1596 \begin_inset Flex CharStyle:Code
1599 \begin_layout Plain Layout
1609 \begin_layout Standard
1611 \begin_inset Flex CharStyle:MenuItem
1614 \begin_layout Plain Layout
1615 Vector graphics format
1620 tells LyX that a format can contain vector graphics.
1621 This information is used to determine the target format of included graphics
1623 \begin_inset Flex CharStyle:MenuItem
1626 \begin_layout Plain Layout
1634 Included graphics may need to be converted to either
1635 \begin_inset Flex CharStyle:MenuItem
1638 \begin_layout Plain Layout
1646 \begin_inset Flex CharStyle:MenuItem
1649 \begin_layout Plain Layout
1657 \begin_inset Flex CharStyle:MenuItem
1660 \begin_layout Plain Layout
1668 \begin_inset Flex CharStyle:MenuItem
1671 \begin_layout Plain Layout
1678 cannot handle other image formats.
1679 If an included graphic is not already in
1680 \begin_inset Flex CharStyle:MenuItem
1683 \begin_layout Plain Layout
1691 \begin_inset Flex CharStyle:MenuItem
1694 \begin_layout Plain Layout
1702 \begin_inset Flex CharStyle:MenuItem
1705 \begin_layout Plain Layout
1712 format, it is converted to
1713 \begin_inset Flex CharStyle:MenuItem
1716 \begin_layout Plain Layout
1723 if the vector format option is set, and otherwise to
1724 \begin_inset Flex CharStyle:MenuItem
1727 \begin_layout Plain Layout
1737 \begin_layout Section
1741 \begin_layout Standard
1742 Since all conversions from one format to another take place in LyX's temporary
1743 directory, it is sometimes necessary to modify a file before copying it
1744 to the temporary directory in order that the conversion may be performed.
1748 \begin_layout Plain Layout
1749 For example, the file may refer to other files—images, for example—using
1750 relative file names, and these may become invalid when the file is copied
1751 to the temporary directory.
1756 This is done by a Copier: It copies a file to (or from) the temporary directory
1757 and may modify it in the process.
1760 \begin_layout Standard
1761 The definitions of the copiers may use four variables:
1764 \begin_layout Labeling
1765 \labelwidthstring 00.00.0000
1766 \begin_inset Flex CharStyle:Code
1769 \begin_layout Plain Layout
1775 The LyX system directory (e.
1776 \begin_inset space \thinspace{}
1780 \begin_inset space \space{}
1784 \begin_inset Flex CharStyle:MenuItem
1787 \begin_layout Plain Layout
1796 \begin_layout Labeling
1797 \labelwidthstring 00.00.0000
1798 \begin_inset Flex CharStyle:Code
1801 \begin_layout Plain Layout
1810 \begin_layout Labeling
1811 \labelwidthstring 00.00.0000
1812 \begin_inset Flex CharStyle:Code
1815 \begin_layout Plain Layout
1824 \begin_layout Labeling
1825 \labelwidthstring 00.00.0000
1826 \begin_inset Flex CharStyle:Code
1829 \begin_layout Plain Layout
1841 \begin_layout Standard
1842 The latter should be the
1844 as it would be used in a
1853 It is relevant only when exporting files suitable for such inclusion.
1856 \begin_layout Standard
1857 Copiers can be used to do almost anything with output files.
1858 For example, suppose you want generated
1860 files to be copied to a special directory,
1861 \begin_inset Flex CharStyle:Code
1864 \begin_layout Plain Layout
1873 Then you could write a shell script such as this one:
1876 \begin_layout Standard
1877 \begin_inset listings
1881 \begin_layout Plain Layout
1886 \begin_layout Plain Layout
1891 \begin_layout Plain Layout
1893 TOFILE=`basename $2`
1896 \begin_layout Plain Layout
1898 cp $FROMFILE /home/you/pdf/$TOFILE
1903 Save it in your local LyX directory—say,
1904 \begin_inset Flex CharStyle:Code
1907 \begin_layout Plain Layout
1908 /home/you/.lyx/scripts/
1915 —and make it executable, if you need to do so on your platform.
1917 \begin_inset Flex CharStyle:MenuItem
1920 \begin_layout Plain Layout
1921 Tools\SpecialChar \menuseparator
1927 dialog, select under
1928 \begin_inset Flex CharStyle:MenuItem
1931 \begin_layout Plain Layout
1932 File Handling\SpecialChar \menuseparator
1939 \begin_inset Flex CharStyle:MenuItem
1942 \begin_layout Plain Layout
1952 format—or one of the other
1955 \begin_inset Flex CharStyle:Code
1958 \begin_layout Plain Layout
1967 \begin_inset Flex CharStyle:MenuItem
1970 \begin_layout Plain Layout
1980 \begin_layout Standard
1981 Copiers are used by LyX in various of its own conversions.
1982 For example, if appropriate programs are found, LyX will automatically
1983 install copiers for the
1984 \begin_inset Flex CharStyle:MenuItem
1987 \begin_layout Plain Layout
1994 \begin_inset Flex CharStyle:MenuItem
1997 \begin_layout Plain Layout
1999 \begin_inset space ~
2008 When these formats are exported, the copier sees that not just the main
2009 HTML file but various associated files (style files, images, etc.) are also
2011 All these files are written to a
2013 of the directory in which the original LyX file was found.
2017 \begin_layout Plain Layout
2018 This copier can be customized.
2020 \begin_inset Quotes eld
2024 \begin_inset Quotes erd
2027 argument takes a comma-separated list of extensions to be copied; if it
2028 is omitted, all files will be copied.
2030 \begin_inset Quotes eld
2034 \begin_inset Quotes erd
2037 argument determines the extension added to the generated directory.
2039 \begin_inset Quotes eld
2043 \begin_inset Flex CharStyle:MenuItem
2046 \begin_layout Plain Layout
2054 \begin_inset Quotes erd
2057 , so HTML generated from
2058 \begin_inset Flex CharStyle:MenuItem
2061 \begin_layout Plain Layout
2070 \begin_inset Flex CharStyle:MenuItem
2073 \begin_layout Plain Layout
2093 \begin_layout Section
2095 \begin_inset CommandInset label
2097 name "sec:Converters"
2104 \begin_layout Standard
2105 You can define your own Converters to convert files between different formats.
2107 \begin_inset Flex CharStyle:MenuItem
2110 \begin_layout Plain Layout
2111 Tools\SpecialChar \menuseparator
2112 Preferences\SpecialChar \menuseparator
2113 File Handling\SpecialChar \menuseparator
2122 \begin_layout Standard
2123 To define a new converter, select the
2124 \begin_inset Flex CharStyle:MenuItem
2127 \begin_layout Plain Layout
2129 \begin_inset space ~
2138 \begin_inset Flex CharStyle:MenuItem
2141 \begin_layout Plain Layout
2143 \begin_inset space ~
2151 from the drop-down lists, enter the command needed for the conversion,
2153 \begin_inset Flex CharStyle:MenuItem
2156 \begin_layout Plain Layout
2163 Several variables can be used in the definition of converters:
2166 \begin_layout Labeling
2167 \labelwidthstring 00.00.0000
2168 \begin_inset Flex CharStyle:Code
2171 \begin_layout Plain Layout
2177 The LyX system directory
2180 \begin_layout Labeling
2181 \labelwidthstring 00.00.0000
2182 \begin_inset Flex CharStyle:Code
2185 \begin_layout Plain Layout
2194 \begin_layout Labeling
2195 \labelwidthstring 00.00.0000
2196 \begin_inset Flex CharStyle:Code
2199 \begin_layout Plain Layout
2208 \begin_layout Labeling
2209 \labelwidthstring 00.00.0000
2210 \begin_inset Flex CharStyle:Code
2213 \begin_layout Plain Layout
2221 of the input file (i.
2222 \begin_inset space \thinspace{}
2225 g., without the extension)
2228 \begin_layout Labeling
2229 \labelwidthstring 00.00.0000
2230 \begin_inset Flex CharStyle:Code
2233 \begin_layout Plain Layout
2239 The path to the input file
2242 \begin_layout Labeling
2243 \labelwidthstring 00.00.0000
2244 \begin_inset Flex CharStyle:Code
2247 \begin_layout Plain Layout
2253 The path to the original input file (this is different from $$p when a
2254 chain of converters is called).
2257 \begin_layout Standard
2259 \begin_inset Flex CharStyle:MenuItem
2262 \begin_layout Plain Layout
2264 \begin_inset space ~
2272 field you can enter the following flags, separated by commas:
2275 \begin_layout Labeling
2276 \labelwidthstring 00.00.0000
2277 \begin_inset Flex CharStyle:Code
2280 \begin_layout Plain Layout
2286 This converter runs some form of
2289 This will make LyX's
2291 error logs available.
2294 \begin_layout Labeling
2295 \labelwidthstring 00.00.0000
2296 \begin_inset Flex CharStyle:Code
2299 \begin_layout Plain Layout
2309 \begin_inset Flex CharStyle:MenuItem
2312 \begin_layout Plain Layout
2318 file for the conversion.
2321 \begin_layout Labeling
2322 \labelwidthstring 00.00.0000
2323 \begin_inset Flex CharStyle:Code
2326 \begin_layout Plain Layout
2336 \begin_layout Standard
2337 The following three flags are not really flags at all because they take
2339 \begin_inset Flex CharStyle:MenuItem
2342 \begin_layout Plain Layout
2344 \begin_inset space ~
2348 \begin_inset space ~
2359 \begin_layout Labeling
2360 \labelwidthstring 00.00.0000
2361 \begin_inset Flex CharStyle:Code
2364 \begin_layout Plain Layout
2371 If set, the converter's standard error will be redirected to a file
2372 \begin_inset Flex CharStyle:Code
2375 \begin_layout Plain Layout
2383 , and the script given as argument will be run as:
2384 \begin_inset Flex CharStyle:Code
2387 \begin_layout Plain Layout
2398 The argument may contain
2399 \begin_inset Flex CharStyle:Code
2402 \begin_layout Plain Layout
2411 \begin_layout Labeling
2412 \labelwidthstring 00.00.0000
2413 \begin_inset Flex CharStyle:Code
2416 \begin_layout Plain Layout
2423 The name of the directory in which the converter will dump the generated
2425 LyX will not create this directory, and it does not copy anything into
2426 it, though it will copy this directory to the destination.
2427 The argument may contain
2428 \begin_inset Flex CharStyle:Code
2431 \begin_layout Plain Layout
2437 , which will be replaced by the base name of the input and output files,
2438 respectively, when the directory is copied.
2439 \begin_inset Newline newline
2446 make no sense together.
2447 The latter will be ignored if the former is given.
2450 \begin_layout Labeling
2451 \labelwidthstring 00.00.0000
2452 \begin_inset Flex CharStyle:Code
2455 \begin_layout Plain Layout
2462 Determines the output file name and may, contain
2463 \begin_inset Flex CharStyle:Code
2466 \begin_layout Plain Layout
2475 and optional even then; if not given, it defaults to `
2480 \begin_layout Standard
2481 None of these last three are presently used in any of the converters that
2482 are installed with LyX.
2486 \begin_layout Standard
2487 You do not have to define converters for all formats between which you want
2489 For example, you will note that there is no `LyX to
2491 converter, but LyX will export PostScript.
2492 It does so by first creating a
2494 file (no converter needs to be defined for this) which is then converted
2499 converter, and finally converting the resulting DVI file to PostScript.
2502 of converters automatically, and it will always choose the shortest possible
2504 You can, though, still define multiple conversion methods between file
2506 For example, the standard LyX configuration provides three ways to convert
2512 \begin_inset Flex CharStyle:MenuItem
2515 \begin_layout Plain Layout
2522 ; via (DVI and) PostScript, using
2523 \begin_inset Flex CharStyle:MenuItem
2526 \begin_layout Plain Layout
2534 \begin_inset Flex CharStyle:MenuItem
2537 \begin_layout Plain Layout
2545 To define such alternate chains, you must define multiple target `file
2548 , as described in section
2549 \begin_inset CommandInset ref
2551 reference "sec:Formats"
2556 For example, in the standard configuration, the formats named
2557 \begin_inset Flex CharStyle:MenuItem
2560 \begin_layout Plain Layout
2568 \begin_inset Flex CharStyle:MenuItem
2571 \begin_layout Plain Layout
2579 \begin_inset Flex CharStyle:MenuItem
2582 \begin_layout Plain Layout
2589 are defined, all of which share the extension
2590 \begin_inset Flex CharStyle:MenuItem
2593 \begin_layout Plain Layout
2600 , and which correspond to the conversion methods just mentioned.
2603 \begin_layout Chapter
2604 Internationalizing LyX
2605 \begin_inset CommandInset label
2607 name "cha:Internationalizing-LyX"
2614 \begin_layout Standard
2615 LyX supports using a translated interface.
2616 Last time we checked, LyX provided text in thirty languages.
2617 The language of choice is called your
2622 (For further reading on locale settings, see also the documentation for
2623 locale that comes with your operating system.
2624 For Linux, the manual page for
2625 \begin_inset Flex CharStyle:Code
2628 \begin_layout Plain Layout
2634 could be a good place to start).
2637 \begin_layout Standard
2638 Notice that these translations will work, but do contain a few flaws.
2639 In particular, all dialogs have been designed with the English text in
2640 mind, which means that some of the translated text will be too large to
2641 fit within the space allocated.
2642 This is only a display problem and will not cause any harm.
2643 Also, you will find that some of the translations do not define shortcut
2644 keys for everything.
2645 Sometimes, there are simply not enough free letters to do it.
2646 Other times, the translator just hasn't got around to doing it yet.
2647 Our localization team, which you may wish to join,
2651 \begin_layout Plain Layout
2652 If you are a fluent speaker of a language other than English, joining these
2653 teams is a great way to give back to the LyX community!
2658 will of course try to fix these shortcomings in future versions of LyX.
2661 \begin_layout Section
2665 \begin_layout Subsection
2666 Translating the graphical user interface (text messages).
2669 \begin_layout Standard
2671 \begin_inset Flex CharStyle:Code
2674 \begin_layout Plain Layout
2681 library to handle the internationalization of the interface.
2682 To have LyX speak your favorite language in all menus and dialogs, you
2684 \begin_inset Flex CharStyle:Code
2687 \begin_layout Plain Layout
2694 -file for that language.
2695 When this is available, you'll have to generate a
2696 \begin_inset Flex CharStyle:Code
2699 \begin_layout Plain Layout
2705 -file from it and install the
2706 \begin_inset Flex CharStyle:Code
2709 \begin_layout Plain Layout
2716 The process of doing all of this is explained in the documentation for
2718 \begin_inset Flex CharStyle:Code
2721 \begin_layout Plain Layout
2729 It is possible to do this just for yourself, but if you're going to do
2730 it, you might as well share the results of your labors with the rest of
2732 Send a message to the LyX
2734 list for more information about how to proceed.
2737 \begin_layout Standard
2738 In short, this is what you should do (xx denotes the language code):
2741 \begin_layout Itemize
2742 Check out the LyX source code.
2744 \begin_inset CommandInset href
2746 name "information on the web"
2747 target "http://www.lyx.org/devel/cvs.php"
2754 \begin_layout Itemize
2756 \begin_inset Flex CharStyle:Code
2759 \begin_layout Plain Layout
2765 to the folder of the
2766 \begin_inset Flex CharStyle:Code
2769 \begin_layout Plain Layout
2778 \begin_inset Flex CharStyle:Code
2781 \begin_layout Plain Layout
2790 \begin_inset Flex CharStyle:Code
2793 \begin_layout Plain Layout
2799 doesn't exist anywhere, it can be remade with the console command
2800 \begin_inset Flex CharStyle:Code
2803 \begin_layout Plain Layout
2809 in that directory, or you can use an existing
2811 -file for some other language as a template).
2814 \begin_layout Itemize
2816 \begin_inset Flex CharStyle:Code
2819 \begin_layout Plain Layout
2830 \begin_layout Plain Layout
2831 This is just a text file, so it can be edited in any text editor.
2832 But there are also specialized programs that support such editing, such
2837 (for all platforms) or
2851 \begin_inset Flex CharStyle:Code
2854 \begin_layout Plain Layout
2866 For some menu- and widget-labels, there are also shortcut keys that should
2868 Those keys are marked after a `|', and should be translated according to
2869 the words and phrases of the language.
2870 You should also fill also out the information at the beginning of the new
2872 \begin_inset Flex CharStyle:Code
2875 \begin_layout Plain Layout
2882 -file with your email-address, etc., so people know where to reach you with
2883 suggestions and entertaining flames.
2886 \begin_layout Standard
2887 If you are just doing this on your own, then:
2890 \begin_layout Itemize
2892 \begin_inset Flex CharStyle:Code
2895 \begin_layout Plain Layout
2902 This can be done with
2903 \begin_inset Flex CharStyle:Code
2906 \begin_layout Plain Layout
2918 \begin_layout Itemize
2920 \begin_inset Flex CharStyle:Code
2923 \begin_layout Plain Layout
2929 -file to your locale-tree, at the correct directory for application messages
2934 xx, and under the name
2935 \begin_inset Flex CharStyle:Code
2938 \begin_layout Plain Layout
2945 \begin_inset space \thinspace{}
2949 \begin_inset space \space{}
2953 \begin_inset Flex CharStyle:Code
2956 \begin_layout Plain Layout
2957 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2967 \begin_layout Standard
2968 As said, however, it would be best if the new
2969 \begin_inset Flex CharStyle:Code
2972 \begin_layout Plain Layout
2979 -file could be added to the LyX distribution, so others can use it.
2980 Adding it involves making additional changes to LyX.
2981 So send an email to the
2983 mailing list if you're interested in doing that.
2986 \begin_layout Subsubsection
2990 \begin_layout Standard
2991 Sometimes it turns out that one English message needs to be translated into
2992 different messages in the target language.
2993 One example is the message
2994 \begin_inset Flex CharStyle:Code
2997 \begin_layout Plain Layout
3003 which has the German translation
3011 , depending upon exactly what the English
3012 \begin_inset Quotes eld
3016 \begin_inset Quotes erd
3021 \begin_inset Flex CharStyle:Code
3024 \begin_layout Plain Layout
3031 does not handle such ambiguous translations.
3032 Therefore you have to add some context information to the message: Instead
3034 \begin_inset Flex CharStyle:Code
3037 \begin_layout Plain Layout
3044 \begin_inset Flex CharStyle:Code
3047 \begin_layout Plain Layout
3058 \begin_inset Flex CharStyle:Code
3061 \begin_layout Plain Layout
3071 Now the two occurrences of
3072 \begin_inset Flex CharStyle:Code
3075 \begin_layout Plain Layout
3082 \begin_inset Flex CharStyle:Code
3085 \begin_layout Plain Layout
3092 and can be translated correctly to
3103 \begin_layout Standard
3104 Of course the context information needs to be stripped off the original
3105 message when no translation is used.
3106 Therefore you have to put it in double square brackets at the end of the
3107 message (see the example above).
3108 The translation mechanism of LyX ensures that everything in double square
3109 brackets at the end of messages is removed before displaying the message.
3112 \begin_layout Subsection
3113 Translating the documentation.
3116 \begin_layout Standard
3117 The online documentation (in the
3118 \begin_inset Flex CharStyle:MenuItem
3121 \begin_layout Plain Layout
3127 -menu) can (and should!) be translated.
3128 If there are translated versions of the documentation available
3132 \begin_layout Plain Layout
3133 As of March 2008, at least some of the documents have been translated into
3134 fourteen languages, with the Tutorial available in a few more.
3139 and the locale is set accordingly, these will be used automagically by
3141 LyX looks for translated versions as
3142 \begin_inset Flex CharStyle:Code
3145 \begin_layout Plain Layout
3146 LyXDir/doc/xx/DocName.lyx
3152 \begin_inset Flex CharStyle:Code
3155 \begin_layout Plain Layout
3161 is the code for the language currently in use.
3162 If there are no translated documents, the default English versions will
3164 Note that the translated versions must have the same filenames (
3165 \begin_inset Flex CharStyle:Code
3168 \begin_layout Plain Layout
3174 above) as the original.
3175 If you feel up to translating the documentation (an excellent way to proof-read
3176 the original documentation by the way!), there are a few things you should
3180 \begin_layout Itemize
3182 \begin_inset Flex CharStyle:Code
3185 \begin_layout Plain Layout
3191 , the guide to writing LyX documentation.
3192 Pay special attention to the translator's section.
3195 \begin_layout Itemize
3196 Check out the documentation translation web page at
3197 \begin_inset CommandInset href
3199 name "http://www.lyx.org/Translation"
3200 target "http://www.lyx.org/Translation"
3205 That way, you can find out which (if any) documents have already been translate
3206 d into your language.
3207 You can also find out who (if anyone) is organizing the effort to translate
3208 the documentation into your language.
3209 If no one is organizing the effort, please let us know that you're interested.
3212 \begin_layout Standard
3213 Once you get to actually translating, here's a few hints for you that may
3217 \begin_layout Itemize
3218 Join the documentation team! There is information on how to do that in
3219 \begin_inset Flex CharStyle:Code
3222 \begin_layout Plain Layout
3229 \begin_inset Flex CharStyle:MenuItem
3232 \begin_layout Plain Layout
3233 Help\SpecialChar \menuseparator
3243 ), which by the way is the first document you should translate.
3246 \begin_layout Itemize
3247 Learn the typographic conventions for the language you are translating to.
3248 Typography is an ancient art and over the centuries, a great variety of
3249 conventions have developed throughout different parts of the world.
3250 Also study the professional terminology amongst typographers in your country.
3251 Inventing your own terminology will only confuse the users.
3254 (Warning! Typography is addictive!)
3257 \begin_layout Itemize
3258 Make a copy of the document.
3259 This will be your working copy.
3260 You can use this as your personal translated help-file by placing it in
3262 \begin_inset Flex CharStyle:Code
3265 \begin_layout Plain Layout
3274 \begin_layout Itemize
3275 Sometimes the original document (from the LyX-team) will be updated.
3276 Use the source viewer at
3277 \begin_inset CommandInset href
3279 name "http://www.lyx.org/trac/timeline"
3280 target "http://www.lyx.org/trac/timeline"
3284 to see what has been changed.
3285 That way you can easily see which parts of the translated document need
3289 \begin_layout Standard
3290 If you ever find an error in the original document, fix it and notify the
3291 rest of the documentation team of the changes! (You didn't forget to join
3292 the documentation team, did you?)
3295 \begin_layout Standard
3296 \begin_inset Branch OutDated
3299 \begin_layout Section
3300 International Keyboard Support
3303 \begin_layout Standard
3306 [Editor's Note: The following section is by
3314 It needs to be fixed to conform to the new Documentation Style sheet and
3315 to make use of the new v1.0 features.
3316 The whole thing also needs to be merged with the section following it.-jw
3317 It may also be badly out of date.-rh (2008)]
3320 \begin_layout Subsection
3321 Defining Own Keymaps: Keymap File Format
3324 \begin_layout Standard
3325 Let's look at a keyboard definition file a little closer.
3326 It is a plain text file defining
3329 \begin_layout Itemize
3330 key-to-key or key-to-string translations
3333 \begin_layout Itemize
3337 \begin_layout Itemize
3338 dead keys exceptions
3341 \begin_layout Standard
3342 To define key-to-key or key-to-string translation, use this command:
3345 \begin_layout Quotation
3346 \begin_inset Flex CharStyle:Code
3349 \begin_layout Plain Layout
3358 \begin_inset Flex CharStyle:Code
3361 \begin_layout Plain Layout
3370 \begin_layout Standard
3372 \begin_inset Flex CharStyle:Code
3375 \begin_layout Plain Layout
3381 is the key to be translated and
3382 \begin_inset Flex CharStyle:Code
3385 \begin_layout Plain Layout
3391 is the string to be inserted into the document.
3392 To define dead keys, use:
3395 \begin_layout Quotation
3396 \begin_inset Flex CharStyle:Code
3399 \begin_layout Plain Layout
3408 \begin_inset Flex CharStyle:Code
3411 \begin_layout Plain Layout
3420 \begin_layout Standard
3422 \begin_inset Flex CharStyle:Code
3425 \begin_layout Plain Layout
3431 is a keyboard key and
3432 \begin_inset Flex CharStyle:Code
3435 \begin_layout Plain Layout
3442 The following dead keys are supported (shortcut name is in parentheses):
3445 \begin_layout Quotation
3449 \begin_inset space \hfill{}
3455 \begin_layout Quotation
3457 \begin_inset space \hfill{}
3463 \begin_layout Quotation
3465 \begin_inset space \hfill{}
3471 \begin_layout Quotation
3473 \begin_inset space \hfill{}
3479 \begin_layout Quotation
3481 \begin_inset space \hfill{}
3487 \begin_layout Quotation
3489 \begin_inset space \hfill{}
3496 \begin_layout Plain Layout
3508 \begin_layout Quotation
3510 \begin_inset space \hfill{}
3516 \begin_layout Quotation
3518 \begin_inset space \hfill{}
3525 \begin_layout Plain Layout
3537 \begin_layout Quotation
3539 \begin_inset space \hfill{}
3545 \begin_layout Quotation
3547 \begin_inset space \hfill{}
3553 \begin_layout Quotation
3555 \begin_inset space \hfill{}
3562 \begin_layout Plain Layout
3574 \begin_layout Quotation
3576 \begin_inset space \hfill{}
3583 \begin_layout Plain Layout
3595 \begin_layout Quotation
3597 \begin_inset space \hfill{}
3603 \begin_layout Quotation
3604 hungarian umlaut (hug)
3605 \begin_inset space \hfill{}
3611 \begin_layout Quotation
3613 \begin_inset space \hfill{}
3619 \begin_layout Quotation
3621 \begin_inset space \hfill{}
3628 \begin_layout Plain Layout
3640 \begin_layout Standard
3641 Since in many international keyboards there are exceptions to what some
3642 dead keys should do, you can define them using
3645 \begin_layout Quotation
3646 \begin_inset Flex CharStyle:Code
3649 \begin_layout Plain Layout
3657 deadkey key outstring
3660 \begin_layout Standard
3661 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3665 \begin_layout Quotation
3666 \begin_inset Flex CharStyle:Code
3669 \begin_layout Plain Layout
3682 \begin_layout Standard
3683 to make it work correctly.
3684 Also, you have to define as exceptions dead keys over i and j, to remove
3685 the dot from them before inserting an accent mark.
3686 I will change this when the time comes, but so far I haven't had time.
3689 \begin_layout Standard
3690 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3693 \begin_inset Flex CharStyle:Code
3696 \begin_layout Plain Layout
3702 have different meaning.
3704 \begin_inset Flex CharStyle:Code
3707 \begin_layout Plain Layout
3713 marks comments, quotes start and end LaTeX-style commands.
3714 To enter quote, you'll need to use
3715 \begin_inset Flex CharStyle:Code
3718 \begin_layout Plain Layout
3727 \begin_inset Flex CharStyle:Code
3730 \begin_layout Plain Layout
3737 \begin_inset Flex CharStyle:Code
3740 \begin_layout Plain Layout
3751 \begin_layout Standard
3752 If you make a keyboard description file that works for your language, please
3753 mail it to me, so I can include it in the next keymap distribution.
3756 \begin_layout Standard
3757 More keywords will be supported in keymap configuration file in future,
3761 \begin_layout Itemize
3762 \begin_inset Flex CharStyle:Code
3765 \begin_layout Plain Layout
3776 \begin_inset space \hfill{}
3780 \begin_inset Flex CharStyle:Code
3783 \begin_layout Plain Layout
3792 \begin_layout Itemize
3793 \begin_inset Flex CharStyle:Code
3796 \begin_layout Plain Layout
3807 \begin_inset space \hfill{}
3811 \begin_inset Flex CharStyle:Code
3814 \begin_layout Plain Layout
3820 an external keymap translation program
3823 \begin_layout Standard
3824 Also, it should look into
3825 \begin_inset Flex CharStyle:Code
3828 \begin_layout Plain Layout
3834 file for defaults, too (for example, a
3835 \begin_inset Flex CharStyle:Code
3838 \begin_layout Plain Layout
3846 option to include default keyboard).
3854 \begin_layout Section
3855 International Keymap Stuff
3856 \begin_inset CommandInset label
3858 name "sec:International-Keymap-Stuff"
3865 \begin_layout Standard
3866 \begin_inset Note Note
3869 \begin_layout Plain Layout
3870 In doing the revisions on this document in March 2008, I did not look over
3871 this stuff, as I do not understand it.
3872 It would be good if someone else could do so.
3881 \begin_layout Standard
3882 The next two sections describe the
3883 \begin_inset Flex CharStyle:Code
3886 \begin_layout Plain Layout
3895 \begin_inset Flex CharStyle:Code
3898 \begin_layout Plain Layout
3906 file syntax in detail.
3907 These sections should help you design your own key map if the ones provided
3908 do not meet your needs.
3911 \begin_layout Subsection
3915 \begin_layout Standard
3919 \begin_inset Flex CharStyle:Code
3922 \begin_layout Plain Layout
3928 file maps keystrokes to characters or strings.
3929 As the name suggests, it sets a keyboard mapping.
3931 \begin_inset Flex CharStyle:Code
3934 \begin_layout Plain Layout
3945 \begin_inset Flex CharStyle:Code
3948 \begin_layout Plain Layout
3963 \begin_inset Flex CharStyle:Code
3966 \begin_layout Plain Layout
3979 \begin_inset Flex CharStyle:Code
3982 \begin_layout Plain Layout
3991 \begin_inset Flex CharStyle:Code
3994 \begin_layout Plain Layout
4002 are described in this section.
4005 \begin_layout Labeling
4006 \labelwidthstring 00.00.0000
4007 \begin_inset Flex CharStyle:Code
4010 \begin_layout Plain Layout
4018 Map a character to a string
4021 \begin_layout LyX-Code
4036 \begin_layout Standard
4069 the double-quote (")
4086 must be escaped with a preceding backslash (
4097 \begin_layout Standard
4099 \begin_inset Flex CharStyle:MenuItem
4102 \begin_layout Plain Layout
4110 statement to cause the symbol
4111 \begin_inset Flex CharStyle:MenuItem
4114 \begin_layout Plain Layout
4122 to be output for the keystroke
4123 \begin_inset Flex CharStyle:MenuItem
4126 \begin_layout Plain Layout
4137 \begin_layout LyX-Code
4143 \begin_layout Labeling
4144 \labelwidthstring 00.00.0000
4145 \begin_inset Flex CharStyle:Code
4148 \begin_layout Plain Layout
4156 Specify an accent character
4159 \begin_layout LyX-Code
4168 \begin_layout Standard
4169 This will make the cha
4207 This is the dead key
4211 \begin_layout Plain Layout
4218 refers to a key that does not produce a character by itself, but when followed
4219 with another key, produces the desired accent character.
4220 For example, a German characte
4222 r with an umlaut like
4232 can be produced in this manner.
4241 \begin_layout Standard
4254 and then another key not in
4271 followed by the other, not allowed key, as output.
4275 \begin_inset Flex CharStyle:MenuItem
4278 \begin_layout Plain Layout
4286 cancels a dead key, so if
4297 \begin_inset Flex CharStyle:MenuItem
4300 \begin_layout Plain Layout
4309 , the cursor will not go one position backwards but will instead cancel
4325 might have had on the next keystroke.
4329 \begin_layout Standard
4330 The following example specifies that the character ' is to be an acute accent,
4331 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4334 \begin_layout LyX-Code
4337 kmod ' acute aeiouAEIOU
4340 \begin_layout Labeling
4341 \labelwidthstring 00.00.0000
4342 \begin_inset Flex CharStyle:Code
4345 \begin_layout Plain Layout
4351 Specify an exception to the accent character
4354 \begin_layout LyX-Code
4363 \begin_layout Standard
4364 This defines an exce
4405 have been assigned a keystroke with a previous
4408 \begin_inset Flex CharStyle:Code
4411 \begin_layout Plain Layout
4435 must not belong in the
4482 If such a declaration does not exist in
4490 \begin_inset Flex CharStyle:Code
4493 \begin_layout Plain Layout
4527 \begin_inset Flex CharStyle:Code
4530 \begin_layout Plain Layout
4544 \begin_layout Standard
4545 The following command produces causes äi to be produced when you enter acute-i
4549 \begin_layout LyX-Code
4563 \begin_layout Labeling
4564 \labelwidthstring 00.00.0000
4565 \begin_inset Flex CharStyle:Code
4568 \begin_layout Plain Layout
4574 Combine two accent characters
4577 \begin_layout LyX-Code
4583 accent1 accent2 allowed
4586 \begin_layout Standard
4587 This one is getting pretty esoteric.
4588 It allows you to combine the effect
4644 \begin_inset Flex CharStyle:Code
4647 \begin_layout Plain Layout
4675 \begin_layout Standard
4676 Consider this example from the
4677 \begin_inset Flex CharStyle:Code
4680 \begin_layout Plain Layout
4691 \begin_layout LyX-Code
4694 kmod ; acute aeioyvhAEIOYVH
4698 kcomb acute umlaut iyIY
4701 \begin_layout Standard
4702 This allows you to press
4703 \begin_inset Flex CharStyle:MenuItem
4706 \begin_layout Plain Layout
4714 and get the effect of
4715 \begin_inset Flex CharStyle:Code
4718 \begin_layout Plain Layout
4737 in this case cancels the last dead key, so if you press
4738 \begin_inset Flex CharStyle:MenuItem
4741 \begin_layout Plain Layout
4750 \begin_inset Flex CharStyle:Code
4753 \begin_layout Plain Layout
4766 \begin_layout Subsection
4770 \begin_layout Standard
4772 \begin_inset Flex CharStyle:Code
4775 \begin_layout Plain Layout
4783 mapping is performed, a
4784 \begin_inset Flex CharStyle:Code
4787 \begin_layout Plain Layout
4797 file maps the strings that the symbols generate to characters in the current
4799 The LyX distribution currently includes at least the
4800 \begin_inset Flex CharStyle:Code
4803 \begin_layout Plain Layout
4812 \begin_inset Flex CharStyle:Code
4815 \begin_layout Plain Layout
4826 \begin_layout Standard
4828 \begin_inset Flex CharStyle:Code
4831 \begin_layout Plain Layout
4839 file is a sequence of declarations of the form
4842 \begin_layout LyX-Code
4855 \begin_layout Standard
4856 For example, in order to map
4857 \begin_inset Flex CharStyle:MenuItem
4860 \begin_layout Plain Layout
4870 to the corresponding character in the iso-8859-1 set (233), the following
4874 \begin_layout LyX-Code
4882 \begin_layout Standard
4884 \begin_inset Flex CharStyle:Code
4887 \begin_layout Plain Layout
4896 \begin_inset Flex CharStyle:Code
4899 \begin_layout Plain Layout
4917 the same character can apply to more than one string.
4919 \begin_inset Flex CharStyle:Code
4922 \begin_layout Plain Layout
4933 \begin_layout LyX-Code
4945 \begin_inset Newline newline
4961 \begin_layout Standard
4962 If LyX cannot find a mapping for the string produced by the keystroke or
4963 a deadkey sequence, it will check if it looks like an accented char and
4964 try to draw an accent over the character on screen.
4967 \begin_layout Subsection
4971 \begin_layout Standard
4972 There is a second way to add support for international characters through
4973 so-called dead-keys.
4974 A dead-key works in combination with a letter to produce an accented character.
4975 Here, we'll explain how to create a really simple dead-key to illustrate
4979 \begin_layout Standard
4980 Suppose you happen to need the circumflex character,
4981 \begin_inset Quotes eld
4985 \begin_inset Quotes erd
4990 \begin_inset Flex CharStyle:MenuItem
4993 \begin_layout Plain Layout
5000 \begin_inset space ~
5004 \begin_inset Flex CharStyle:MenuItem
5007 \begin_layout Plain Layout
5013 ] to the LyX command
5014 \begin_inset Flex CharStyle:Code
5017 \begin_layout Plain Layout
5024 \begin_inset Flex CharStyle:Code
5027 \begin_layout Plain Layout
5034 Now, whenever you type the
5035 \begin_inset Flex CharStyle:MenuItem
5038 \begin_layout Plain Layout
5044 -key followed by a letter, that letter will have a circumflex accent on
5046 For example, the sequence
5047 \begin_inset Quotes eld
5051 \begin_inset Flex CharStyle:MenuItem
5054 \begin_layout Plain Layout
5061 \begin_inset Quotes erd
5064 produces the letter:
5065 \begin_inset Quotes eld
5069 \begin_inset Quotes erd
5073 If you tried to type
5074 \begin_inset Quotes eld
5078 \begin_inset Flex CharStyle:MenuItem
5081 \begin_layout Plain Layout
5088 \begin_inset Quotes erd
5091 , however, LyX will complain with a beep, since a
5092 \begin_inset Quotes eld
5096 \begin_inset Flex CharStyle:MenuItem
5099 \begin_layout Plain Layout
5106 \begin_inset Quotes erd
5109 never takes a circumflex accent.
5111 \begin_inset Flex CharStyle:MenuItem
5114 \begin_layout Plain Layout
5120 after a dead-key produces the bare-accent.
5121 Please note this last point! If you bind a key to a dead-key, you'll need
5122 to rebind the character on that key to yet another key.
5124 \begin_inset Flex CharStyle:MenuItem
5127 \begin_layout Plain Layout
5133 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5136 \begin_layout Standard
5137 One common way to bind dead-keys is to use
5138 \begin_inset Flex CharStyle:MenuItem
5141 \begin_layout Plain Layout
5148 \begin_inset Flex CharStyle:MenuItem
5151 \begin_layout Plain Layout
5158 \begin_inset Flex CharStyle:MenuItem
5161 \begin_layout Plain Layout
5167 in combination with an accent, like
5168 \begin_inset Quotes eld
5172 \begin_inset Flex CharStyle:MenuItem
5175 \begin_layout Plain Layout
5182 \begin_inset Quotes erd
5186 \begin_inset Quotes eld
5190 \begin_inset Flex CharStyle:MenuItem
5193 \begin_layout Plain Layout
5200 \begin_inset Quotes erd
5204 \begin_inset Quotes eld
5208 \begin_inset Flex CharStyle:MenuItem
5211 \begin_layout Plain Layout
5218 \begin_inset Quotes erd
5222 Another way involves using
5223 \begin_inset Flex CharStyle:Code
5226 \begin_layout Plain Layout
5233 \begin_inset Flex CharStyle:Code
5236 \begin_layout Plain Layout
5242 to set up the special
5243 \begin_inset Flex CharStyle:Code
5246 \begin_layout Plain Layout
5254 \begin_inset Flex CharStyle:Code
5257 \begin_layout Plain Layout
5263 acts in some ways just like
5264 \begin_inset Flex CharStyle:MenuItem
5267 \begin_layout Plain Layout
5273 and permits you to bind keys to accented characters.
5274 You can also turn keys into dead-keys by binding them to something like
5276 \begin_inset Flex CharStyle:Code
5279 \begin_layout Plain Layout
5285 and then binding this symbolic key to the corresponding LyX command.
5289 \begin_layout Plain Layout
5294 : This is exactly what I do in my
5295 \begin_inset Flex CharStyle:Code
5298 \begin_layout Plain Layout
5305 \begin_inset Flex CharStyle:Code
5308 \begin_layout Plain Layout
5316 \begin_inset Flex CharStyle:MenuItem
5319 \begin_layout Plain Layout
5321 \begin_inset space ~
5330 \begin_inset Flex CharStyle:Code
5333 \begin_layout Plain Layout
5339 and a bunch of these
5340 \begin_inset Quotes eld
5344 \begin_inset Flex CharStyle:Code
5347 \begin_layout Plain Layout
5354 \begin_inset Quotes erd
5357 symbolic keys bound such things as
5358 \begin_inset Flex CharStyle:MenuItem
5361 \begin_layout Plain Layout
5363 \begin_inset space ~
5372 \begin_inset Flex CharStyle:MenuItem
5375 \begin_layout Plain Layout
5377 \begin_inset space ~
5386 This is how I produce my accented characters.
5391 You can make just about anything into the
5392 \begin_inset Flex CharStyle:Code
5395 \begin_layout Plain Layout
5402 \begin_inset Flex CharStyle:MenuItem
5405 \begin_layout Plain Layout
5411 keys, a spare function key, etc.
5412 As for the LyX commands that produce accents, check the entry for
5413 \begin_inset Flex CharStyle:Code
5416 \begin_layout Plain Layout
5427 You'll find the complete list there.
5430 \begin_layout Subsection
5431 Saving your Language Configuration
5434 \begin_layout Standard
5435 You can edit your preferences so that your desired language environment
5436 is automatically configured when LyX starts up, via the
5437 \begin_inset Flex CharStyle:MenuItem
5440 \begin_layout Plain Layout
5441 Edit\SpecialChar \menuseparator
5450 \begin_layout Chapter
5451 Installing New Document Classes, Layouts, and Templates
5452 \begin_inset CommandInset label
5454 name "cha:Installing-New-Document"
5462 \begin_layout Plain Layout
5463 Installing New Document Classes
5471 \begin_layout Standard
5472 In this chapter, we describe the procedures for creating and installing
5473 new LyX layout and template files, as well as offer a refresher on correctly
5474 installing new LaTeX document classes.
5475 Some definitions: a document class is a LaTeX file (usually ending in
5476 \begin_inset Flex CharStyle:Code
5479 \begin_layout Plain Layout
5486 \begin_inset Flex CharStyle:Code
5489 \begin_layout Plain Layout
5495 ) that describes the format of a document such as an article, report, journal
5496 preprint, etc, and all the commands needed to realize that format.
5497 A layout file is a LyX file that corresponds to a LaTeX document class
5498 and that tells LyX how to
5499 \begin_inset Quotes eld
5503 \begin_inset Quotes erd
5506 things on the screen to make the display look something like the final
5508 More precisely, a layout file describes a
5509 \begin_inset Quotes eld
5513 \begin_inset Quotes erd
5516 which is the internal construct LyX uses to render the screen display.
5518 \begin_inset Quotes eld
5522 \begin_inset Quotes erd
5526 \begin_inset Quotes eld
5530 \begin_inset Quotes erd
5533 can be used somewhat interchangeably, but it is better to refer to the
5534 file as the layout, and the thing living in LyX's memory as the text class.
5535 A template file is simply a LyX document that contains a set of predefined
5536 entries for a given document class—entries that are generally required
5538 Templates are especially useful for things like journal manuscripts that
5539 are to be submitted electronically.
5542 \begin_layout Section
5543 Installing a new LaTeX package
5546 \begin_layout Standard
5547 Some installations may not include a LaTeX package that you would like to
5549 For example, you might need FoilTeX, a package for preparing slides or
5550 viewgraphs for overhead projectors.
5551 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5552 a user interface for that.
5553 For example on MiKTeX you start its program
5554 \begin_inset Quotes eld
5558 \begin_inset Quotes erd
5561 to get a list of available packages.
5562 To install one, right click on it or use the installing toolbar button.
5563 When the package you want to install is not in the list, but you have it
5565 \begin_inset Flex CharStyle:Code
5568 \begin_layout Plain Layout
5575 \begin_inset Flex CharStyle:Code
5578 \begin_layout Plain Layout
5584 -file, then copy these files to a subfolder of your LaTeX distribution,
5585 for example to the folder
5594 Then update the file name database of your LaTeX-distribution.
5595 For example on MiKTeX this is done by pressing the button
5598 \begin_inset space ~
5603 that you find in MiKTeX's
5604 \begin_inset Quotes eld
5608 \begin_inset Quotes erd
5612 In both cases you need afterwards to reconfigure LyX using the menu
5613 \begin_inset Flex CharStyle:MenuItem
5616 \begin_layout Plain Layout
5617 Tools\SpecialChar \menuseparator
5623 and then to restart LyX.
5626 \begin_layout Standard
5627 If your LaTeX distribution doesn't provide a user interface, then you can
5628 follow these steps by using a UNIX/Linux console.
5631 \begin_layout Enumerate
5632 Get the package from
5633 \begin_inset CommandInset href
5636 target "http://www.ctan.org/"
5643 \begin_layout Enumerate
5644 You can install this package in several different places.
5645 If you want it to be available for all users on your system, then you should
5646 install it in your `local' TeX tree; if you want (or need) it to be available
5647 just for you, then you can install it in your own `user' TeX tree.
5648 Where these should be created, if they do not already exist, depends upon
5649 the details of your system.
5650 To find out, look in the file
5651 \begin_inset Flex CharStyle:Code
5654 \begin_layout Plain Layout
5664 \begin_layout Plain Layout
5665 This usually lives in the directory
5666 \begin_inset Flex CharStyle:Code
5669 \begin_layout Plain Layout
5675 , though you can run
5676 \begin_inset Flex CharStyle:Code
5679 \begin_layout Plain Layout
5690 The location of the `local' TeX tree is defined by
5691 \begin_inset Flex CharStyle:Code
5694 \begin_layout Plain Layout
5700 ; this is usually somewhere like
5701 \begin_inset Flex CharStyle:Code
5704 \begin_layout Plain Layout
5705 /usr/local/share/texmf/
5711 The `user' TeX tree is defined by
5712 \begin_inset Flex CharStyle:Code
5715 \begin_layout Plain Layout
5722 \begin_inset Flex CharStyle:Code
5725 \begin_layout Plain Layout
5732 (If these variables are not predefined, you can define them.) You'll probably
5733 need root permissions to create or modify the `local' tree; but your `user'
5734 tree shouldn't have such limitations.
5737 \begin_layout Enumerate
5739 \begin_inset Flex CharStyle:Code
5742 \begin_layout Plain Layout
5749 \begin_inset Flex CharStyle:Code
5752 \begin_layout Plain Layout
5759 \begin_inset Flex CharStyle:Code
5762 \begin_layout Plain Layout
5769 \begin_inset space \thinspace{}
5773 \begin_inset Newline newline
5777 \begin_inset Flex CharStyle:Code
5780 \begin_layout Plain Layout
5781 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5787 \begin_inset Newline newline
5790 But, again, most of this will
5791 \begin_inset Quotes eld
5795 \begin_inset Quotes erd
5801 \begin_layout Enumerate
5806 \begin_layout Plain Layout
5807 We'll assume henceforth that you're defining `local' TeX tree.
5808 If you're defining a user tree, just adjust as necessary.
5814 You must follow the directory structure of your existing
5815 \begin_inset Flex CharStyle:Code
5818 \begin_layout Plain Layout
5824 directory, which will be found at
5825 \begin_inset Flex CharStyle:Code
5828 \begin_layout Plain Layout
5835 For example, latex packages should go under
5836 \begin_inset Flex CharStyle:Code
5839 \begin_layout Plain Layout
5840 $TEXMFLOCAL/tex/latex/
5848 \begin_layout Enumerate
5849 Install the package.
5850 For example, you would unpack the FoilTeX tarball and copy it to
5851 \begin_inset Flex CharStyle:Code
5854 \begin_layout Plain Layout
5855 $TEXMFLOCAL/tex/latex/foiltex
5862 \begin_inset Flex CharStyle:Code
5865 \begin_layout Plain Layout
5871 directory contains various files.
5874 \begin_layout Enumerate
5876 \begin_inset Flex CharStyle:Code
5879 \begin_layout Plain Layout
5887 \begin_inset Flex CharStyle:Code
5890 \begin_layout Plain Layout
5899 \begin_layout Standard
5900 Your package is now installed and available to LaTeX.
5901 To make it available to LyX, you need to create a Layout file, if one is
5902 not already available.
5903 (See the next section.) Once you have a layout file, you need only reconfigure
5905 \begin_inset Flex CharStyle:MenuItem
5908 \begin_layout Plain Layout
5909 Tools\SpecialChar \menuseparator
5915 ) and then restart LyX.
5916 You should then see your new package—for example
5917 \begin_inset Flex CharStyle:MenuItem
5920 \begin_layout Plain Layout
5927 \begin_inset Flex CharStyle:MenuItem
5930 \begin_layout Plain Layout
5931 Document\SpecialChar \menuseparator
5938 \begin_inset Flex CharStyle:MenuItem
5941 \begin_layout Plain Layout
5951 \begin_layout Section
5955 \begin_layout Standard
5956 This section describes how to write and install your own LyX layout files
5957 and walks through the
5958 \begin_inset Flex CharStyle:Code
5961 \begin_layout Plain Layout
5967 text class format as an example.
5969 \begin_inset Flex CharStyle:Code
5972 \begin_layout Plain Layout
5978 files describe what paragraph and character styles are available for a
5979 given document class and how LyX should display them.
5980 We try to provide a thorough description of the process here; however,
5981 there are so many different types of documents supported by LaTeX classes
5982 that we can't hope to cover every different possibility or problem you
5984 (The LyX users' list is frequented by people with lots of experience with
5985 layout design who are willing to share what they've learned.)
5988 \begin_layout Standard
5989 As you prepare to write a new layout, it is extremely helpful to look at
5990 the example layouts distributed with LyX.
5991 If you use a nice LaTeX document class that might be of interest for others,
5992 too, and have a nice corresponding LyX layout, feel free to contribute
5993 the stuff to us, so we may put it into the distribution.
5995 \begin_inset CommandInset href
5997 name "section on the LyX wiki"
5998 target "http://wiki.lyx.org/Layouts/Layouts"
6002 for this kind of material.
6005 \begin_layout Standard
6006 All the tags described in this chapter are case-insensitive; this means
6008 \begin_inset Flex CharStyle:Code
6011 \begin_layout Plain Layout
6018 \begin_inset Flex CharStyle:Code
6021 \begin_layout Plain Layout
6028 \begin_inset Flex CharStyle:Code
6031 \begin_layout Plain Layout
6037 are really the same command.
6038 The possible values are printed in brackets after the feature's name.
6039 The default value if a feature isn't specified inside a text class-description
6041 \begin_inset Flex CharStyle:Code
6044 \begin_layout Plain Layout
6053 If the argument has a data type like
6054 \begin_inset Quotes eld
6058 \begin_inset Quotes erd
6062 \begin_inset Quotes eld
6066 \begin_inset Quotes erd
6069 , the default is shown like this:
6070 \begin_inset Flex CharStyle:Code
6073 \begin_layout Plain Layout
6084 \begin_layout Subsection
6086 \begin_inset CommandInset label
6088 name "sub:Layout-modules"
6095 \begin_layout Standard
6096 Similar to layout files, and new with LyX 1.6, are layout
6101 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6102 some modules—such as the endnotes module—provide support for just such
6104 In a sense, layout modules are similar to included files—files like
6105 \begin_inset Flex CharStyle:Code
6108 \begin_layout Plain Layout
6114 —in that modules are not specific to a given document layout but may be
6115 used with many different layouts.
6116 The difference is that using a layout module does not require editing the
6118 Rather, modules are selected in the
6119 \begin_inset Flex CharStyle:MenuItem
6122 \begin_layout Plain Layout
6123 Document\SpecialChar \menuseparator
6132 \begin_layout Standard
6133 Building modules is the easiest way to get started with layout editing,
6134 since it can be as simple as adding a single new paragraph or flex inset.
6135 But modules may, in principle, contain anything a layout file can contain.
6138 \begin_layout Standard
6139 A module must begin with a line like the following:
6142 \begin_layout LyX-Code
6145 DeclareLyXModule[endnotes.sty]{Endnotes}
6148 \begin_layout Standard
6149 The mandatory argument, in curly brackets, is the name of the module, as
6151 \begin_inset Flex CharStyle:MenuItem
6154 \begin_layout Plain Layout
6155 Document\SpecialChar \menuseparator
6163 \change_inserted 0 1243500588
6167 \begin_layout Standard
6168 The argument in square brackets is optional: It declares any LaTeX packages
6169 on which the module depends.
6170 Please note that only packages about which LyX knows should be listed in
6171 the square brackets.
6175 \begin_layout Plain Layout
6176 The list of such packages is documented only in the source code.
6181 LyX will not check for arbitrary packages.
6183 \change_inserted 0 1243500694
6184 It is also possible to use the form
6185 \begin_inset Flex CharStyle:MenuItem
6188 \begin_layout Plain Layout
6190 \change_inserted 0 1243500706
6196 , which declares that the module can only be used when there exists a conversion
6197 chain between formats `from' and `to'.
6202 \begin_layout Standard
6203 The module declaration should then be followed by lines like the following:
6206 \begin_layout LyX-Code
6210 \begin_layout LyX-Code
6211 #Adds an endnote command, in addition to footnotes.
6215 \begin_layout LyX-Code
6216 #You will need to add
6218 theendnotes in TeX code where you
6221 \begin_layout LyX-Code
6222 #want the endnotes to appear.
6226 \begin_layout LyX-Code
6230 \begin_layout LyX-Code
6231 #Requires: somemodule | othermodule
6234 \begin_layout LyX-Code
6235 #Excludes: badmodule
6238 \begin_layout Standard
6239 The description is used in
6240 \begin_inset Flex CharStyle:MenuItem
6243 \begin_layout Plain Layout
6244 Document\SpecialChar \menuseparator
6250 to provide the user with information about what the module does.
6252 \begin_inset Flex CharStyle:Code
6255 \begin_layout Plain Layout
6261 line is used to identify other modules with which this one must be used;
6263 \begin_inset Flex CharStyle:Code
6266 \begin_layout Plain Layout
6272 line is used to identify modules with which this one may not be used.
6273 Both are optional, and, as shown, multiple modules should be separated
6274 with the pipe symbol: |.
6275 Note that the required modules are treated disjunctively:
6279 of the required modules must be used.
6284 excluded module may be used.
6285 Note that modules are identified here by their
6289 without the .module extension.
6291 \begin_inset Flex CharStyle:Code
6294 \begin_layout Plain Layout
6301 \begin_inset Flex CharStyle:Code
6304 \begin_layout Plain Layout
6313 \begin_layout Standard
6314 After creating a new module, you will need to reconfigure and then restart
6315 LyX for the module to appear in the menu.
6316 However, changes you make to the module will be seen immediately, if you
6318 \begin_inset Flex CharStyle:MenuItem
6321 \begin_layout Plain Layout
6322 Document\SpecialChar \menuseparator
6328 , highlight something, and then hit
6329 \begin_inset Quotes eld
6333 \begin_inset Quotes erd
6339 It is strongly recommended that you save your work before doing so
6344 it is strongly recommended that you not attempt to edit modules while simultaneo
6345 usly working on documents
6348 Though of course the developers strive to keep LyX stable in such situations,
6349 syntax errors and the like in your module file could cause strange behavior.
6352 \begin_layout Subsection
6353 Supporting new document classes
6356 \begin_layout Standard
6357 There are two situations you are likely to encounter when wanting to support
6358 a new LaTeX document class, involving LaTeX2e class (
6359 \begin_inset Flex CharStyle:Code
6362 \begin_layout Plain Layout
6369 \begin_inset Flex CharStyle:Code
6372 \begin_layout Plain Layout
6379 Supporting a style file is usually fairly easy.
6380 Supporting a new document class is a bit harder.
6383 \begin_layout Subsection
6385 \begin_inset Flex CharStyle:MenuItem
6388 \begin_layout Plain Layout
6397 \begin_layout Standard
6398 If your new document class is provided as a style file that is used in conjuncti
6399 on with an existing, supported document class—for the sake of the example,
6400 we'll assume that the style file is called
6401 \begin_inset Flex CharStyle:MenuItem
6404 \begin_layout Plain Layout
6410 and it is meant to be used with
6411 \begin_inset Flex CharStyle:MenuItem
6414 \begin_layout Plain Layout
6420 , which is a standard class—start by copying the existing class's layout
6421 file into your local directory:
6424 \begin_layout LyX-Code
6425 cp report.layout ~/.lyx/layouts/myclass.layout
6428 \begin_layout Standard
6430 \begin_inset Flex CharStyle:Code
6433 \begin_layout Plain Layout
6439 and change the line:
6442 \begin_layout LyX-Code
6445 DeclareLaTeXClass{report}
6448 \begin_layout Standard
6452 \begin_layout LyX-Code
6455 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6458 \begin_layout Standard
6462 \begin_layout LyX-Code
6464 \begin_inset Newline newline
6470 \begin_inset Newline newline
6476 \begin_layout Standard
6477 near the top of the file.
6480 \begin_layout Standard
6481 Start LyX and select
6482 \begin_inset Flex CharStyle:MenuItem
6485 \begin_layout Plain Layout
6486 Tools\SpecialChar \menuseparator
6493 Then restart LyX and try creating a new document.
6495 \begin_inset Flex CharStyle:MenuItem
6498 \begin_layout Plain Layout
6504 " as a document class option in the
6505 \begin_inset Flex CharStyle:MenuItem
6508 \begin_layout Plain Layout
6509 Document\SpecialChar \menuseparator
6516 It is likely that some of the sectioning commands and such in your new
6517 class will work differently from how they worked in the base class—
6518 \begin_inset Flex CharStyle:Code
6521 \begin_layout Plain Layout
6527 in this example—so you can fiddle around with the settings for the different
6528 sections if you wish.
6531 \begin_layout Subsection
6533 \begin_inset Flex CharStyle:MenuItem
6536 \begin_layout Plain Layout
6545 \begin_layout Standard
6546 There are two possibilities here.
6547 One is that the class file is itself based upon an existing document class.
6548 For example, many thesis classes are based upon
6549 \begin_inset Flex CharStyle:MenuItem
6552 \begin_layout Plain Layout
6559 To see whether yours is, look for a line like
6562 \begin_layout LyX-Code
6568 \begin_layout Standard
6570 If so, then you may proceed largely as in the previous section, though
6571 the DeclareLaTeXClass line will be different.
6572 If your new class is thesis, and it is based upon book, then the line should
6577 \begin_layout Plain Layout
6578 And it will be easiest if you save the file to
6579 \begin_inset Flex CharStyle:Code
6582 \begin_layout Plain Layout
6588 : LyX assumes that the document class has the same name as the layout file.
6597 \begin_layout LyX-Code
6600 DeclareLaTeXClass[thesis,book]{thesis}
6603 \begin_layout Standard
6604 If, on the other hand, the new class is not based upon an existing class,
6605 you will probably have to
6606 \begin_inset Quotes eld
6610 \begin_inset Quotes erd
6614 We strongly suggest copying an existing layout file which uses a similar
6615 LaTeX class and then modifying it, if you can do so.
6616 At least use an existing file as a starting point so you can find out what
6617 items you need to worry about.
6618 Again, the specifics are covered below.
6621 \begin_layout Section
6622 Declaring a new text class
6625 \begin_layout Standard
6626 When it's finally time to get your hands dirty and create or edit your own
6627 layout file, the following sections describe what you're up against.
6628 Our advice is to go slowly, save and test often, listen to soothing music,
6629 and enjoy one or two of your favorite adult beverages; more if you are
6630 getting particularly stuck.
6631 It's really not that hard, except that the multitude of options can become
6632 overwhelming if you try to do to much in one sitting.
6633 Go have another adult beverage, just for good measure.
6636 \begin_layout Standard
6640 \begin_layout Standard
6641 Lines in a layout file which begin with a
6642 \begin_inset Flex CharStyle:Code
6645 \begin_layout Plain Layout
6652 There is one exception to this rule: all layouts should begin with lines
6656 \begin_layout LyX-Code
6659 #% Do not delete the line below; configure depends on this
6662 \begin_layout LyX-Code
6667 DeclareLaTeXClass{article}
6670 \begin_layout Standard
6671 The second line is used when you configure LyX.
6672 The layout file is read by the LaTeX script
6673 \begin_inset Flex CharStyle:Code
6676 \begin_layout Plain Layout
6682 , in a special mode where
6683 \begin_inset Flex CharStyle:Code
6686 \begin_layout Plain Layout
6693 The first line is just a LaTeX comment, and the second one contains the
6694 declaration of the text class.
6695 If these lines appear in a file named
6696 \begin_inset Flex CharStyle:Code
6699 \begin_layout Plain Layout
6705 , then they define a text class of name
6706 \begin_inset Flex CharStyle:Code
6709 \begin_layout Plain Layout
6715 (the name of the layout file) which uses the LaTeX document class
6716 \begin_inset Flex CharStyle:Code
6719 \begin_layout Plain Layout
6725 (the default is to use the same name as the layout).
6727 \begin_inset Quotes eld
6731 \begin_inset Quotes erd
6734 that appears above is used as a description of the text class in the
6735 \begin_inset Flex CharStyle:MenuItem
6738 \begin_layout Plain Layout
6739 Document\SpecialChar \menuseparator
6748 \begin_layout Standard
6749 Let's assume that you wrote your own text class that uses the
6750 \begin_inset Flex CharStyle:Code
6753 \begin_layout Plain Layout
6759 document class, but where you changed the appearance of the section headings.
6760 If you put it in a file
6761 \begin_inset Flex CharStyle:Code
6764 \begin_layout Plain Layout
6770 , the header of this file should be:
6773 \begin_layout LyX-Code
6776 #% Do not delete the line below; configure depends on this
6779 \begin_layout LyX-Code
6784 DeclareLaTeXClass[article]{article (with my own headings)}
6787 \begin_layout Standard
6788 This declares a text class
6789 \begin_inset Flex CharStyle:Code
6792 \begin_layout Plain Layout
6798 , associated with the LaTeX document class
6799 \begin_inset Flex CharStyle:Code
6802 \begin_layout Plain Layout
6809 \begin_inset Quotes eld
6812 article (with my own headings)
6813 \begin_inset Quotes erd
6817 If your text class depends on several packages, you can declare it as:
6820 \begin_layout LyX-Code
6823 #% Do not delete the line below; configure depends on this
6826 \begin_layout LyX-Code
6831 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6834 \begin_layout Standard
6835 This indicates that your text class uses the foo.sty package.
6836 Finally, it is also possible to declare classes for DocBook code.
6837 Typical declarations will look like
6840 \begin_layout LyX-Code
6843 #% Do not delete the line below; configure depends on this
6846 \begin_layout LyX-Code
6851 DeclareDocBookClass[article]{SGML (DocBook article)}
6854 \begin_layout Standard
6855 Note that these declarations can also be given an optional parameter declaring
6856 the name of the document class (but not a list).
6859 \begin_layout Standard
6860 So, to be as explicit as possible, the form of the layout declaration is:
6863 \begin_layout LyX-Code
6868 DeclareLaTeXClass[class,package.sty]{layout description}
6871 \begin_layout Standard
6872 The class need only be specified if the name of the LaTeX class file and
6873 the name of the layout file are different; if the name of the class file
6874 is not specified, then LyX will simply assume that it is the same as the
6875 name of the layout file.
6878 \begin_layout Standard
6879 When the text class has been modified to your taste, all you have to do
6880 is to copy it either to
6881 \begin_inset Flex CharStyle:Code
6884 \begin_layout Plain Layout
6891 \begin_inset Flex CharStyle:Code
6894 \begin_layout Plain Layout
6901 \begin_inset Flex CharStyle:MenuItem
6904 \begin_layout Plain Layout
6905 Tools\SpecialChar \menuseparator
6911 , exit LyX and restart it.
6912 Then your new text class should be available along with the others.
6915 \begin_layout Standard
6916 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6917 you made to your layout files.
6918 As a result, editing layout files could be very time consuming.
6919 Beginning with 1.6, however, you can force a reload of the layout currently
6920 in use by using the LyX function
6921 \begin_inset Flex CharStyle:MenuItem
6924 \begin_layout Plain Layout
6931 There is no default binding for this function—though, of course, you can
6932 bind it to a key yourself.
6933 If you want to use this function, then, you should simply enter it in the
6939 : This is very much an `advanced feature'.
6944 recommended that you save your work before using this function.
6949 recommended that you not attempt to edit your layout while simultaneously
6950 working on a document that you care about.
6951 Use a test document.
6952 Syntax errors and the like in your layout file could cause peculiar behavior.
6953 In particular, such errors could cause LyX to regard the current layout
6954 as invalid and to attempt to switch to some other layout.
6955 The LyX team strives to keep LyX stable in such situations, but safe is
6959 \begin_layout Subsection
6963 \begin_layout Standard
6964 The first non-comment line must contain the file format number:
6967 \begin_layout Description
6968 \begin_inset Flex CharStyle:Code
6971 \begin_layout Plain Layout
6978 \begin_inset Flex CharStyle:Code
6981 \begin_layout Plain Layout
6987 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6988 don't have an explicit file format).
6989 The file format that is documented here is format 14.
6992 \begin_layout Subsection
6993 General text class parameters
6996 \begin_layout Standard
6997 These are the general parameters which describe the form of the entire document:
7000 \begin_layout Description
7001 \begin_inset Flex CharStyle:Code
7004 \begin_layout Plain Layout
7010 Adds information to the document preamble.
7012 \begin_inset Quotes eld
7016 \begin_inset Flex CharStyle:Code
7019 \begin_layout Plain Layout
7026 \begin_inset Quotes erd
7032 \begin_layout Description
7033 \begin_inset Flex CharStyle:Code
7036 \begin_layout Plain Layout
7042 Describes various global options supported by the document class.
7044 \begin_inset space ~
7048 \begin_inset CommandInset ref
7050 reference "sub:ClassOptions"
7056 \begin_inset Quotes eld
7060 \begin_inset Flex CharStyle:Code
7063 \begin_layout Plain Layout
7070 \begin_inset Quotes erd
7076 \begin_layout Description
7077 \begin_inset Flex CharStyle:Code
7080 \begin_layout Plain Layout
7087 \begin_inset Flex CharStyle:Code
7090 \begin_layout Plain Layout
7099 \begin_inset Flex CharStyle:Code
7102 \begin_layout Plain Layout
7108 ] Whether the class should default to having one or two columns.
7109 Can be changed in the
7110 \begin_inset Flex CharStyle:MenuItem
7113 \begin_layout Plain Layout
7114 Document\SpecialChar \menuseparator
7123 \begin_layout Description
7124 \begin_inset Flex CharStyle:Code
7127 \begin_layout Plain Layout
7133 This sequence defines a new counter.
7135 \begin_inset space ~
7139 \begin_inset CommandInset ref
7141 reference "sub:Counters"
7147 \begin_inset Quotes eld
7151 \begin_inset Flex CharStyle:Code
7154 \begin_layout Plain Layout
7161 \begin_inset Quotes erd
7167 \begin_layout Description
7168 \begin_inset Flex CharStyle:Code
7171 \begin_layout Plain Layout
7177 Sets the default font used to display the document.
7179 \begin_inset space ~
7183 \begin_inset CommandInset ref
7185 reference "sub:Font-description"
7189 for how to declare fonts.
7191 \begin_inset Quotes eld
7195 \begin_inset Flex CharStyle:Code
7198 \begin_layout Plain Layout
7205 \begin_inset Quotes erd
7211 \begin_layout Description
7212 \begin_inset Flex CharStyle:Code
7215 \begin_layout Plain Layout
7222 \begin_inset Flex CharStyle:Code
7225 \begin_layout Plain Layout
7231 Specifies a module to be included by default with this document class,
7232 which should be specified by filename without the
7233 \begin_inset Flex CharStyle:Code
7236 \begin_layout Plain Layout
7243 The user can still remove the module, but it will be active at the outset.
7244 (This applies only when new files are created, or when this class is chosen
7245 for an existing document.)
7248 \begin_layout Description
7249 \begin_inset Flex CharStyle:Code
7252 \begin_layout Plain Layout
7259 \begin_inset Flex CharStyle:Code
7262 \begin_layout Plain Layout
7268 ] This is the style that will be assigned to new paragraphs, usually
7269 \begin_inset Flex CharStyle:MenuItem
7272 \begin_layout Plain Layout
7279 This will default to the first defined style if not given, but you are
7280 highly encouraged to use this directive.
7283 \begin_layout Description
7284 \begin_inset Flex CharStyle:Code
7287 \begin_layout Plain Layout
7294 \begin_inset Flex CharStyle:Code
7297 \begin_layout Plain Layout
7303 ] Indicates that the module in question—which should be specified by filename
7305 \begin_inset Flex CharStyle:Code
7308 \begin_layout Plain Layout
7314 extension—cannot be used with this document class.
7315 This might be used in a journal-specific layout file to prevent, say, the
7317 \begin_inset Flex CharStyle:Code
7320 \begin_layout Plain Layout
7326 module that numbers theorems by section.
7331 be used in a module.
7332 Modules have their own way of excluding other modules (see
7333 \begin_inset CommandInset ref
7335 reference "sub:Layout-modules"
7342 \begin_layout Description
7343 \begin_inset Flex CharStyle:Code
7346 \begin_layout Plain Layout
7352 Defines a new float.
7354 \begin_inset space ~
7358 \begin_inset CommandInset ref
7360 reference "sub:Floats"
7366 \begin_inset Quotes eld
7370 \begin_inset Flex CharStyle:Code
7373 \begin_layout Plain Layout
7380 \begin_inset Quotes erd
7386 \begin_layout Description
7387 \begin_inset Flex CharStyle:Code
7390 \begin_layout Plain Layout
7396 As its name implies, this command allows you to include another layout
7397 definition file within yours to avoid duplicating commands.
7398 Common examples are the standard layout files, for example,
7399 \begin_inset Flex CharStyle:Code
7402 \begin_layout Plain Layout
7408 , which contains most of the basic layouts.
7411 \begin_layout Description
7412 \begin_inset Flex CharStyle:Code
7415 \begin_layout Plain Layout
7421 This section (re-)defines the layout of an inset.
7422 It can be applied to an existing inset of to a new, user-defined inset,
7424 \begin_inset space \thinspace{}
7428 \begin_inset space \space{}
7431 a new character style.
7433 \begin_inset space ~
7437 \begin_inset CommandInset ref
7439 reference "sub:Flex-insets-and"
7443 for more information.
7445 \begin_inset Quotes eld
7449 \begin_inset Flex CharStyle:Code
7452 \begin_layout Plain Layout
7459 \begin_inset Quotes erd
7465 \begin_layout Description
7466 \begin_inset Flex CharStyle:Code
7469 \begin_layout Plain Layout
7475 A string that indicates the width of the left margin on the screen, for
7477 \begin_inset Quotes eld
7481 \begin_inset Quotes erd
7487 \begin_layout Description
7488 \begin_inset Flex CharStyle:Code
7491 \begin_layout Plain Layout
7497 This command deletes an existing float.
7498 This is particularly useful when you want to suppress a float that has
7499 be defined in an input file.
7502 \begin_layout Description
7503 \begin_inset Flex CharStyle:Code
7506 \begin_layout Plain Layout
7512 This command deletes an existing style.
7513 This is particularly useful when you want to suppress a style that has
7514 be defined in an input file.
7517 \begin_layout Description
7518 \begin_inset Flex CharStyle:Code
7521 \begin_layout Plain Layout
7527 A string indicating what sort of output documents using this class will
7529 At present, the options are: `docbook', `latex', and `literate'.
7530 \change_inserted 0 1243500198
7534 \begin_layout Description
7536 \change_inserted 0 1243500505
7537 \begin_inset Flex CharStyle:Code
7540 \begin_layout Plain Layout
7542 \change_inserted 0 1243500208
7548 A string indicating the file format (as defined in the Preferences dialog)
7549 produced by this class.
7550 It is mainly useful when
7551 \begin_inset Flex CharStyle:Code
7554 \begin_layout Plain Layout
7556 \change_inserted 0 1243500394
7562 is `literate' and one wants to define a new type of literate document.
7563 This string is reset to `docbook', `latex', or `literate' when the correspondin
7565 \begin_inset Flex CharStyle:Code
7568 \begin_layout Plain Layout
7570 \change_inserted 0 1243500473
7576 parameter is encountered.
7581 \begin_layout Description
7582 \begin_inset Flex CharStyle:Code
7585 \begin_layout Plain Layout
7596 \begin_inset Flex CharStyle:Code
7599 \begin_layout Plain Layout
7610 \begin_inset Flex CharStyle:Code
7613 \begin_layout Plain Layout
7620 \begin_inset Flex CharStyle:Code
7623 \begin_layout Plain Layout
7629 ] The class default pagestyle.
7630 Can be changed in the
7631 \begin_inset Flex CharStyle:MenuItem
7634 \begin_layout Plain Layout
7635 Document\SpecialChar \menuseparator
7644 \begin_layout Description
7645 \begin_inset Flex CharStyle:Code
7648 \begin_layout Plain Layout
7654 Sets the preamble for the LaTeX document.
7655 Note that this will completely override any prior
7656 \begin_inset Flex CharStyle:Code
7659 \begin_layout Plain Layout
7666 \begin_inset Flex CharStyle:Code
7669 \begin_layout Plain Layout
7677 \begin_inset Quotes eld
7681 \begin_inset Flex CharStyle:Code
7684 \begin_layout Plain Layout
7691 \begin_inset Quotes erd
7697 \begin_layout Description
7698 \begin_inset Flex CharStyle:Code
7701 \begin_layout Plain Layout
7708 \begin_inset Flex CharStyle:Code
7711 \begin_layout Plain Layout
7718 \begin_inset Flex CharStyle:Code
7721 \begin_layout Plain Layout
7730 \begin_inset Flex CharStyle:Code
7733 \begin_layout Plain Layout
7739 ] Whether the class already provides the feature
7740 \begin_inset Flex CharStyle:Code
7743 \begin_layout Plain Layout
7750 A feature is in general the name of a package (
7751 \begin_inset Flex CharStyle:Code
7754 \begin_layout Plain Layout
7761 \begin_inset Flex CharStyle:Code
7764 \begin_layout Plain Layout
7770 , \SpecialChar \ldots{}
7772 \begin_inset Flex CharStyle:Code
7775 \begin_layout Plain Layout
7782 \begin_inset Flex CharStyle:Code
7785 \begin_layout Plain Layout
7791 ,\SpecialChar \ldots{}
7792 ); the complete list of supported features is unfortunately not documented
7793 outside the LyX source code—but see
7794 \begin_inset Flex CharStyle:Code
7797 \begin_layout Plain Layout
7803 if you're interested.
7805 \begin_inset Flex CharStyle:MenuItem
7808 \begin_layout Plain Layout
7809 Help\SpecialChar \menuseparator
7815 also gives an overview of the supported packages.
7818 \begin_layout Description
7819 \begin_inset Flex CharStyle:Code
7822 \begin_layout Plain Layout
7829 \begin_inset Flex CharStyle:Code
7832 \begin_layout Plain Layout
7838 ] Indicates that this layout provides the functionality of the module mentioned,
7839 which should be specified by the filename without the
7840 \begin_inset Flex CharStyle:Code
7843 \begin_layout Plain Layout
7850 This will typically be used if the layout includes the module directly,
7851 rather than using the
7852 \begin_inset Flex CharStyle:Code
7855 \begin_layout Plain Layout
7861 tag to indicate that it ought to be used.
7862 It could be used in a module that provided an alternate implementation
7863 of the same functionality.
7866 \begin_layout Description
7867 \begin_inset Flex CharStyle:Code
7870 \begin_layout Plain Layout
7877 \begin_inset Flex CharStyle:Code
7880 \begin_layout Plain Layout
7886 ] Whether the class requires the feature
7887 \begin_inset Flex CharStyle:Code
7890 \begin_layout Plain Layout
7897 Multiple features must be separated by commas.
7898 Note that you can only request supported features.
7901 \begin_layout Description
7902 \begin_inset Flex CharStyle:Code
7905 \begin_layout Plain Layout
7911 A string that indicates the width of the right margin on the screen, for
7913 \begin_inset Quotes eld
7917 \begin_inset Quotes erd
7923 \begin_layout Description
7924 \begin_inset Flex CharStyle:Code
7927 \begin_layout Plain Layout
7933 Sets which divisions get numbered.
7935 \begin_inset Flex CharStyle:Code
7938 \begin_layout Plain Layout
7947 \begin_layout Description
7948 \begin_inset Flex CharStyle:Code
7951 \begin_layout Plain Layout
7960 \begin_inset Flex CharStyle:Code
7963 \begin_layout Plain Layout
7974 \begin_inset Flex CharStyle:Code
7977 \begin_layout Plain Layout
7983 ] Whether the class-default should be printing on one or both sides of the
7985 Can be changed in the
7986 \begin_inset Flex CharStyle:MenuItem
7989 \begin_layout Plain Layout
7990 Document\SpecialChar \menuseparator
7999 \begin_layout Description
8000 \begin_inset Flex CharStyle:Code
8003 \begin_layout Plain Layout
8009 This sequence defines a new paragraph style.
8010 If the style already exists, it will redefine some of its parameters instead.
8012 \begin_inset space ~
8016 \begin_inset CommandInset ref
8018 reference "sub:Paragraph-Styles"
8024 \begin_inset Quotes eld
8028 \begin_inset Flex CharStyle:Code
8031 \begin_layout Plain Layout
8038 \begin_inset Quotes erd
8044 \begin_layout Description
8045 \begin_inset Flex CharStyle:Code
8048 \begin_layout Plain Layout
8055 \begin_inset Flex CharStyle:Code
8058 \begin_layout Plain Layout
8064 ] The name of the command or environment to be used with
8065 \begin_inset Flex CharStyle:Code
8068 \begin_layout Plain Layout
8077 \begin_layout Description
8078 \begin_inset Flex CharStyle:Code
8081 \begin_layout Plain Layout
8088 \begin_inset Flex CharStyle:Code
8091 \begin_layout Plain Layout
8100 \begin_inset Flex CharStyle:Code
8103 \begin_layout Plain Layout
8109 ] Indicates what kind of markup is used to define the title of a document.
8111 \begin_inset Flex CharStyle:Code
8114 \begin_layout Plain Layout
8120 means that the macro with name
8121 \begin_inset Flex CharStyle:Code
8124 \begin_layout Plain Layout
8130 will be inserted after the last layout which has
8131 \begin_inset Quotes eld
8135 \begin_inset Flex CharStyle:Code
8138 \begin_layout Plain Layout
8145 \begin_inset Quotes erd
8150 \begin_inset Flex CharStyle:Code
8153 \begin_layout Plain Layout
8159 corresponds to the case where the block of paragraphs which have
8160 \begin_inset Quotes eld
8164 \begin_inset Flex CharStyle:Code
8167 \begin_layout Plain Layout
8174 \begin_inset Quotes erd
8177 should be enclosed into the
8178 \begin_inset Flex CharStyle:Code
8181 \begin_layout Plain Layout
8190 \begin_layout Description
8191 \begin_inset Flex CharStyle:Code
8194 \begin_layout Plain Layout
8200 Sets which divisions are included in the table of contents.
8202 \begin_inset Flex CharStyle:Code
8205 \begin_layout Plain Layout
8214 \begin_layout Subsection
8215 \begin_inset Flex CharStyle:Code
8218 \begin_layout Plain Layout
8225 \begin_inset CommandInset label
8227 name "sub:ClassOptions"
8234 \begin_layout Standard
8236 \begin_inset Flex CharStyle:Code
8239 \begin_layout Plain Layout
8245 section can contain the following entries:
8248 \begin_layout Description
8249 \begin_inset Flex CharStyle:Code
8252 \begin_layout Plain Layout
8259 \begin_inset Flex CharStyle:Code
8262 \begin_layout Plain Layout
8268 ] The list of available font sizes for the document's main font, separated
8270 \begin_inset Quotes eld
8274 \begin_inset Flex CharStyle:Code
8277 \begin_layout Plain Layout
8284 \begin_inset Quotes erd
8290 \begin_layout Description
8291 \begin_inset Flex CharStyle:Code
8294 \begin_layout Plain Layout
8300 Used to set the DTD line with XML-based output classes.
8302 \begin_inset space \thinspace{}
8306 \begin_inset Quotes eld
8309 -//OASIS//DTD DocBook V4.2//EN
8310 \begin_inset Quotes erd
8316 \begin_layout Description
8317 \begin_inset Flex CharStyle:Code
8320 \begin_layout Plain Layout
8327 \begin_inset Flex CharStyle:Code
8330 \begin_layout Plain Layout
8331 string="empty|plain|headings|fancy"
8336 ] The list of available page styles, separated by
8337 \begin_inset Quotes eld
8341 \begin_inset Flex CharStyle:Code
8344 \begin_layout Plain Layout
8351 \begin_inset Quotes erd
8357 \begin_layout Description
8358 \begin_inset Flex CharStyle:Code
8361 \begin_layout Plain Layout
8368 \begin_inset Flex CharStyle:Code
8371 \begin_layout Plain Layout
8377 ] Some document class options, separated by a comma, that will be added
8378 to the optional part of the
8379 \begin_inset Flex CharStyle:Code
8382 \begin_layout Plain Layout
8393 \begin_layout Standard
8395 \begin_inset Flex CharStyle:Code
8398 \begin_layout Plain Layout
8404 section must end with
8405 \begin_inset Quotes eld
8409 \begin_inset Flex CharStyle:Code
8412 \begin_layout Plain Layout
8419 \begin_inset Quotes erd
8425 \begin_layout Subsection
8427 \begin_inset CommandInset label
8429 name "sub:Paragraph-Styles"
8436 \begin_layout Standard
8437 A paragraph style description looks like this:
8441 \begin_layout Plain Layout
8442 Note that this will either define a new layout or modify an existing one.
8450 \begin_layout LyX-Code
8457 \begin_layout LyX-Code
8461 \begin_layout LyX-Code
8465 \begin_layout Standard
8466 where the following commands are allowed:
8469 \begin_layout Description
8470 \begin_inset Flex CharStyle:Code
8473 \begin_layout Plain Layout
8480 \begin_inset Flex CharStyle:Code
8483 \begin_layout Plain Layout
8488 , left, right, center
8493 ] Paragraph alignment.
8496 \begin_layout Description
8497 \begin_inset Flex CharStyle:Code
8500 \begin_layout Plain Layout
8507 \begin_inset Flex CharStyle:Code
8510 \begin_layout Plain Layout
8515 , left, right, center
8520 ] A comma separated list of permitted alignments.
8521 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8523 For example a right-aligned or centered enumeration isn't possible.)
8526 \begin_layout Description
8527 \begin_inset Flex CharStyle:Code
8530 \begin_layout Plain Layout
8537 \begin_inset Flex CharStyle:Code
8540 \begin_layout Plain Layout
8550 \begin_layout Plain Layout
8551 Note that a `float' here is a real number, such as: 1.5.
8556 The vertical space with which the last of a chain of paragraphs with this
8557 layout is separated from the following paragraph.
8558 If the next paragraph has another layout, the separations are not simply
8559 added, but the maximum is taken.
8562 \begin_layout Description
8563 \begin_inset Flex CharStyle:Code
8566 \begin_layout Plain Layout
8573 \begin_inset Flex CharStyle:Code
8576 \begin_layout Plain Layout
8582 The category for this style.
8583 This is used to group related styles in the Layout combobox on the toolbar.
8584 Any string can be used, but you may want to use existing categories with
8589 \begin_layout Description
8590 \begin_inset Flex CharStyle:Code
8593 \begin_layout Plain Layout
8599 Depth of XML command.
8600 Used only with XML-type formats.
8603 \begin_layout Description
8604 \begin_inset Flex CharStyle:Code
8607 \begin_layout Plain Layout
8614 \begin_inset CommandInset label
8616 name "des:CopyStyle"
8621 \begin_inset Flex CharStyle:Code
8624 \begin_layout Plain Layout
8630 Copies all the features of an existing style into the current one.
8634 \begin_layout Description
8635 \begin_inset Flex CharStyle:Code
8638 \begin_layout Plain Layout
8644 The name of a style whose preamble should be output
8649 This allows to ensure some ordering of the preamble snippets when macros
8650 definitions depend on one another.
8654 \begin_layout Plain Layout
8655 Note that, besides that functionality, there is no way to ensure any ordering
8657 The ordering that you see in a given version of LyX may change without
8658 warning in later versions.
8666 \begin_layout Description
8667 \begin_inset Flex CharStyle:Code
8670 \begin_layout Plain Layout
8677 \begin_inset Flex CharStyle:Code
8680 \begin_layout Plain Layout
8685 , Box, Filled_Box, Static
8690 ] The type of label that stands at the end of the paragraph (or sequence
8692 \begin_inset Flex CharStyle:Code
8695 \begin_layout Plain Layout
8702 \begin_inset Flex CharStyle:Code
8705 \begin_layout Plain Layout
8712 \begin_inset Flex CharStyle:Code
8715 \begin_layout Plain Layout
8722 \begin_inset Flex CharStyle:Code
8725 \begin_layout Plain Layout
8733 \begin_inset Flex CharStyle:Code
8736 \begin_layout Plain Layout
8743 \begin_inset Quotes eld
8747 \begin_inset Quotes erd
8751 \begin_inset Flex CharStyle:Code
8754 \begin_layout Plain Layout
8761 \begin_inset Flex CharStyle:Code
8764 \begin_layout Plain Layout
8765 \begin_inset space ~
8774 \begin_inset space ~
8777 black) square suitable for end of proof markers,
8778 \begin_inset Flex CharStyle:Code
8781 \begin_layout Plain Layout
8787 is an explicit text string.
8790 \begin_layout Description
8791 \begin_inset Flex CharStyle:Code
8794 \begin_layout Plain Layout
8801 \begin_inset Flex CharStyle:Code
8804 \begin_layout Plain Layout
8810 ] The string used for a label with a
8811 \begin_inset Flex CharStyle:Code
8814 \begin_layout Plain Layout
8821 \begin_inset Flex CharStyle:Code
8824 \begin_layout Plain Layout
8834 \begin_layout Description
8835 \begin_inset Flex CharStyle:Code
8838 \begin_layout Plain Layout
8845 \begin_inset Flex CharStyle:Code
8848 \begin_layout Plain Layout
8859 \begin_inset Flex CharStyle:Code
8862 \begin_layout Plain Layout
8871 \begin_layout Description
8872 \begin_inset Flex CharStyle:Code
8875 \begin_layout Plain Layout
8882 \begin_inset Flex CharStyle:Code
8885 \begin_layout Plain Layout
8895 ] With this parameter the
8896 \begin_inset Flex CharStyle:MenuItem
8899 \begin_layout Plain Layout
8906 \begin_inset Quotes eld
8909 Vertical space above
8910 \begin_inset Quotes erd
8914 \begin_inset Flex CharStyle:MenuItem
8917 \begin_layout Plain Layout
8918 Edit\SpecialChar \menuseparator
8920 \begin_inset space ~
8928 dialog can be set when initializing a paragraph with this style.
8932 \begin_layout Plain Layout
8935 Note from Jean-Marc:
8937 I'm not sure that this setting has much use, and it should probably be
8938 removed in later versions.
8946 \begin_layout Description
8947 \begin_inset Flex CharStyle:Code
8950 \begin_layout Plain Layout
8956 The font used for both the text body
8962 \begin_inset space ~
8966 \begin_inset CommandInset ref
8968 reference "sub:Font-description"
8973 Note that defining this font automatically defines the
8974 \begin_inset Flex CharStyle:Code
8977 \begin_layout Plain Layout
8984 So you should define this one first if you also want to define
8985 \begin_inset Flex CharStyle:Code
8988 \begin_layout Plain Layout
8997 \begin_layout Description
8998 \begin_inset Flex CharStyle:Code
9001 \begin_layout Plain Layout
9008 \begin_inset CommandInset label
9010 name "des:FreeSpacing"
9017 \begin_inset Flex CharStyle:Code
9020 \begin_layout Plain Layout
9031 \begin_inset Flex CharStyle:Code
9034 \begin_layout Plain Layout
9040 ] Usually LyX doesn't allow you to insert more than one space between words,
9041 since a space is considered as the separation between two words, not a
9042 character or symbol of its own.
9043 This is a very fine thing but sometimes annoying, for example, when typing
9044 program code or plain LaTeX code.
9046 \begin_inset Flex CharStyle:Code
9049 \begin_layout Plain Layout
9056 Note that LyX will create protected blanks for the additional blanks when
9057 in another mode than LaTeX-mode.
9060 \begin_layout Description
9061 \begin_inset Flex CharStyle:Code
9064 \begin_layout Plain Layout
9070 Language dependent information to be included in the LaTeX preamble when
9072 Note that this will completely override any prior
9073 \begin_inset Flex CharStyle:Code
9076 \begin_layout Plain Layout
9084 \begin_inset Quotes eld
9088 \begin_inset Flex CharStyle:Code
9091 \begin_layout Plain Layout
9098 \begin_inset Quotes erd
9102 The contents of this tag will occur once in the LaTeX preamble for each
9103 language used by the document.
9104 Each time, the following substitutions are made:
9108 \begin_layout Itemize
9109 \begin_inset Flex CharStyle:Code
9112 \begin_layout Plain Layout
9118 is replaced by the language name (as used by the babel package).
9121 \begin_layout Itemize
9123 \begin_inset Quotes eld
9127 \begin_inset Quotes erd
9131 \begin_inset Flex CharStyle:Code
9134 \begin_layout Plain Layout
9140 replaces its argument by the translation of the argument to the current
9144 \begin_layout Standard
9145 This preamble snippet will only be used if the document contains more than
9146 one language and the babel package is used.
9150 \begin_layout Description
9151 \begin_inset Flex CharStyle:Code
9154 \begin_layout Plain Layout
9161 \begin_inset Flex CharStyle:Code
9164 \begin_layout Plain Layout
9170 , but this preamble snippet occurs independently from the babel package,
9171 and only for the document language.
9173 \begin_inset Quotes eld
9177 \begin_inset Flex CharStyle:Code
9180 \begin_layout Plain Layout
9187 \begin_inset Quotes erd
9194 \begin_layout Standard
9195 If the style defines text that appears in the typeset document, it may use
9197 \begin_inset Flex CharStyle:Code
9200 \begin_layout Plain Layout
9207 \begin_inset Flex CharStyle:Code
9210 \begin_layout Plain Layout
9216 to support non-english and even multilanguage documents correctly.
9217 The following excerpt (from the
9218 \begin_inset Flex CharStyle:Code
9221 \begin_layout Plain Layout
9227 file) shows how this works:
9230 \begin_layout LyX-Code
9234 \begin_layout LyX-Code
9237 theoremstyle{remark}
9240 \begin_layout LyX-Code
9243 newtheorem{claim}[thm]{
9250 \begin_layout LyX-Code
9254 \begin_layout LyX-Code
9258 \begin_layout LyX-Code
9263 claimname}{_(Claim)}
9266 \begin_layout LyX-Code
9270 \begin_layout LyX-Code
9274 \begin_layout LyX-Code
9278 \begin_layout LyX-Code
9287 claimname}{_(Claim)}}
9290 \begin_layout LyX-Code
9294 \begin_layout Standard
9295 The key to correct translation of the user visible text is the definition
9297 \begin_inset Flex CharStyle:Code
9300 \begin_layout Plain Layout
9308 in the language preamble.
9309 This command holds the name of the theorem that will appear in the output.
9311 \begin_inset Flex CharStyle:Code
9314 \begin_layout Plain Layout
9320 then uses the commands offered by the babel package to redefine
9321 \begin_inset Flex CharStyle:Code
9324 \begin_layout Plain Layout
9332 for each used language in multilanguage documents.
9336 \begin_layout Description
9337 \begin_inset Flex CharStyle:Code
9340 \begin_layout Plain Layout
9346 [[FIXME]] (Used only with XML-type formats.)
9349 \begin_layout Description
9350 \begin_inset Flex CharStyle:Code
9353 \begin_layout Plain Layout
9360 \begin_inset Flex CharStyle:Code
9363 \begin_layout Plain Layout
9369 If 1, marks the layout as being part of a title block (see also the
9370 \begin_inset Flex CharStyle:Code
9373 \begin_layout Plain Layout
9380 \begin_inset Flex CharStyle:Code
9383 \begin_layout Plain Layout
9392 \begin_layout Description
9393 \begin_inset Flex CharStyle:Code
9396 \begin_layout Plain Layout
9403 \begin_inset Flex CharStyle:Code
9406 \begin_layout Plain Layout
9412 ] This provides extra space between paragraphs that have the same layout.
9413 If you put other layouts into an environment, each is separated with the
9415 \begin_inset Flex CharStyle:Code
9418 \begin_layout Plain Layout
9425 But the whole items of the environment are additionally separated with
9427 \begin_inset Flex CharStyle:Code
9430 \begin_layout Plain Layout
9442 \begin_layout Description
9443 \begin_inset Flex CharStyle:Code
9446 \begin_layout Plain Layout
9452 [[FIXME]] (Used only with XML-type formats.)
9455 \begin_layout Description
9456 \begin_inset Flex CharStyle:Code
9459 \begin_layout Plain Layout
9466 \begin_inset CommandInset label
9468 name "des:KeepEmpty"
9475 \begin_inset Flex CharStyle:Code
9478 \begin_layout Plain Layout
9489 \begin_inset Flex CharStyle:Code
9492 \begin_layout Plain Layout
9498 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9499 lead to empty LaTeX output.
9500 There are some cases where this could be desirable however: in a letter
9501 template, the required fields can be provided as empty fields, so that
9502 people do not forget them; in some special classes, a layout can be used
9503 as some kind of break, which does not contain actual text.
9506 \begin_layout Description
9507 \begin_inset Flex CharStyle:Code
9510 \begin_layout Plain Layout
9516 [float=0] The vertical space between the label and the text body.
9517 Only used for labels that are above the text body (
9518 \begin_inset Flex CharStyle:Code
9521 \begin_layout Plain Layout
9528 \begin_inset Flex CharStyle:Code
9531 \begin_layout Plain Layout
9532 Centered_Top_Environment
9540 \begin_layout Description
9541 \begin_inset Flex CharStyle:Code
9544 \begin_layout Plain Layout
9551 \begin_inset Flex CharStyle:Code
9554 \begin_layout Plain Layout
9561 \begin_inset Newline newline
9564 The name of the counter for automatic numbering (see Section
9565 \begin_inset CommandInset ref
9567 reference "sub:Counters"
9572 This must be given if
9573 \begin_inset Flex CharStyle:Code
9576 \begin_layout Plain Layout
9583 \begin_inset Flex CharStyle:Code
9586 \begin_layout Plain Layout
9595 \begin_layout Description
9596 \begin_inset Flex CharStyle:Code
9599 \begin_layout Plain Layout
9605 The font used for the label.
9607 \begin_inset space ~
9611 \begin_inset CommandInset ref
9613 reference "sub:Font-description"
9620 \begin_layout Description
9621 \begin_inset Flex CharStyle:Code
9624 \begin_layout Plain Layout
9630 Text that indicates how far a label should be indented.
9633 \begin_layout Description
9634 \begin_inset Flex CharStyle:Code
9637 \begin_layout Plain Layout
9644 \begin_inset Flex CharStyle:Code
9647 \begin_layout Plain Layout
9653 ] The horizontal space between the label and the text body.
9654 Only used for labels that are not above the text body.
9657 \begin_layout Description
9658 \begin_inset Flex CharStyle:Code
9661 \begin_layout Plain Layout
9668 \begin_inset Flex CharStyle:Code
9671 \begin_layout Plain Layout
9677 ] The string used for a label with a
9678 \begin_inset Flex CharStyle:Code
9681 \begin_layout Plain Layout
9689 \begin_inset Flex CharStyle:Code
9692 \begin_layout Plain Layout
9698 is set, this string can be contain the special formatting commands described
9700 \begin_inset CommandInset ref
9702 reference "sub:Counters"
9710 \begin_layout Plain Layout
9711 For the sake of backwards compatibility, the string
9712 \begin_inset Flex CharStyle:Code
9715 \begin_layout Plain Layout
9725 will be replaced by the expanded
9726 \begin_inset Flex CharStyle:Code
9729 \begin_layout Plain Layout
9736 \begin_inset Flex CharStyle:Code
9739 \begin_layout Plain Layout
9748 This feature is now obsolete and should be replaced by the mechanisms of
9750 \begin_inset CommandInset ref
9752 reference "sub:Counters"
9764 \begin_layout Description
9765 \begin_inset Flex CharStyle:Code
9768 \begin_layout Plain Layout
9775 \begin_inset Flex CharStyle:Code
9778 \begin_layout Plain Layout
9784 ] This is used inside the appendix instead of
9785 \begin_inset Flex CharStyle:Code
9788 \begin_layout Plain Layout
9796 \begin_inset Flex CharStyle:Code
9799 \begin_layout Plain Layout
9806 \begin_inset Flex CharStyle:Code
9809 \begin_layout Plain Layout
9818 \begin_layout Description
9819 \begin_inset Flex CharStyle:Code
9822 \begin_layout Plain Layout
9828 [FIXME] (Used only with XML-type formats.)
9831 \begin_layout Description
9832 \begin_inset Flex CharStyle:Code
9835 \begin_layout Plain Layout
9842 \begin_inset Flex CharStyle:Code
9845 \begin_layout Plain Layout
9850 , Manual, Static, Top_Environment,
9851 \begin_inset Newline newline
9854 Centered_Top_Environment, Sensitive, Counter
9860 \begin_inset Newline newline
9864 \begin_inset Flex CharStyle:Code
9867 \begin_layout Plain Layout
9873 means the label is the very first word (up to the first real blank).
9877 \begin_layout Plain Layout
9878 Use protected spaces if you want more than one word as the label.
9884 \begin_inset Flex CharStyle:Code
9887 \begin_layout Plain Layout
9893 means it is defined in the layout (see
9894 \begin_inset Flex CharStyle:Code
9897 \begin_layout Plain Layout
9905 \begin_inset Flex CharStyle:Code
9908 \begin_layout Plain Layout
9915 \begin_inset Flex CharStyle:Code
9918 \begin_layout Plain Layout
9919 Centered_Top_Environment
9924 are special cases of
9925 \begin_inset Flex CharStyle:Code
9928 \begin_layout Plain Layout
9935 The label will be printed above the paragraph, but only at the top of an
9936 environment or the top of a chain of paragraphs with this layout.
9937 Usage is for example the
9938 \begin_inset Flex CharStyle:MenuItem
9941 \begin_layout Plain Layout
9948 \begin_inset Flex CharStyle:MenuItem
9951 \begin_layout Plain Layout
9958 This is also the case for
9959 \begin_inset Flex CharStyle:Code
9962 \begin_layout Plain Layout
9968 labels with latex type
9969 \begin_inset Flex CharStyle:Code
9972 \begin_layout Plain Layout
9978 , in order to make layouts for theorems work correctly.
9980 \begin_inset Flex CharStyle:Code
9983 \begin_layout Plain Layout
9989 is a special case for the caption-labels
9990 \begin_inset Quotes eld
9994 \begin_inset Quotes erd
9998 \begin_inset Quotes eld
10002 \begin_inset Quotes erd
10007 \begin_inset Flex CharStyle:Code
10010 \begin_layout Plain Layout
10016 means the (hardcoded) label string depends on the kind of float.
10018 \begin_inset Flex CharStyle:Code
10021 \begin_layout Plain Layout
10027 label type defines automatically numbered labels.
10029 \begin_inset CommandInset ref
10031 reference "sub:Counters"
10038 \begin_layout Description
10039 \begin_inset Flex CharStyle:Code
10042 \begin_layout Plain Layout
10048 The name of the corresponding LaTeX stuff.
10049 Either the environment or command name.
10052 \begin_layout Description
10053 \begin_inset Flex CharStyle:Code
10056 \begin_layout Plain Layout
10062 An optional parameter for the corresponding
10063 \begin_inset Flex CharStyle:Code
10066 \begin_layout Plain Layout
10073 This parameter cannot be changed from within LyX.
10076 \begin_layout Description
10077 \begin_inset Flex CharStyle:Code
10080 \begin_layout Plain Layout
10087 \begin_inset CommandInset label
10089 name "des:LatexType"
10094 \begin_inset Flex CharStyle:Code
10097 \begin_layout Plain Layout
10102 , Command, Environment, Item_Environment,
10108 \begin_inset Flex CharStyle:Code
10111 \begin_layout Plain Layout
10117 ] How the layout should be translated into LaTeX.
10119 \begin_inset Flex CharStyle:Code
10122 \begin_layout Plain Layout
10128 means nothing special.
10130 \begin_inset Flex CharStyle:Code
10133 \begin_layout Plain Layout
10140 \begin_inset Flex CharStyle:Code
10143 \begin_layout Plain Layout
10150 {\SpecialChar \ldots{}
10157 \begin_inset Flex CharStyle:Code
10160 \begin_layout Plain Layout
10167 \begin_inset Flex CharStyle:Code
10170 \begin_layout Plain Layout
10177 }\SpecialChar \ldots{}
10191 \begin_inset Flex CharStyle:Code
10194 \begin_layout Plain Layout
10201 \begin_inset Flex CharStyle:Code
10204 \begin_layout Plain Layout
10211 \begin_inset Flex CharStyle:Code
10214 \begin_layout Plain Layout
10222 is generated for each paragraph of this environment.
10224 \begin_inset Flex CharStyle:Code
10227 \begin_layout Plain Layout
10234 \begin_inset Flex CharStyle:Code
10237 \begin_layout Plain Layout
10244 \begin_inset Flex CharStyle:Code
10247 \begin_layout Plain Layout
10253 is passed as an argument to the environment.
10255 \begin_inset Flex CharStyle:Code
10258 \begin_layout Plain Layout
10264 can be defined in the
10265 \begin_inset Flex CharStyle:MenuItem
10268 \begin_layout Plain Layout
10273 ayout\SpecialChar \menuseparator
10285 \begin_inset Flex CharStyle:Code
10288 \begin_layout Plain Layout
10296 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10297 Visit the SGML class files for specific examples.
10300 \begin_layout Standard
10301 Putting the last few things together, the LaTeX output will be either:
10304 \begin_layout LyX-Code
10307 latexname[latexparam]{\SpecialChar \ldots{}
10311 \begin_layout Standard
10315 \begin_layout LyX-Code
10318 begin{latexname}[latexparam] \SpecialChar \ldots{}
10324 \begin_layout Standard
10325 depending upon the LaTeX type.
10328 \begin_layout Description
10329 \begin_inset Flex CharStyle:Code
10332 \begin_layout Plain Layout
10339 \begin_inset Flex CharStyle:Code
10342 \begin_layout Plain Layout
10348 ] If you put layouts into environments, the leftmargins are not simply added,
10349 but added with a factor
10350 \begin_inset Formula $\frac{4}{depth+4}$
10354 Note that this parameter is also used when the margin is defined as
10355 \begin_inset Flex CharStyle:Code
10358 \begin_layout Plain Layout
10365 \begin_inset Flex CharStyle:Code
10368 \begin_layout Plain Layout
10375 Then it is added to the manual or dynamic margin.
10377 \begin_inset Newline newline
10380 The argument is passed as a string.
10382 \begin_inset Quotes eld
10386 \begin_inset Flex CharStyle:Code
10389 \begin_layout Plain Layout
10396 \begin_inset Quotes erd
10399 means that the paragraph is indented with the width of
10400 \begin_inset Quotes eld
10404 \begin_inset Flex CharStyle:Code
10407 \begin_layout Plain Layout
10414 \begin_inset Quotes erd
10417 in the normal font.
10418 You can get a negative width by prefixing the string with
10419 \begin_inset Quotes eld
10423 \begin_inset Flex CharStyle:Code
10426 \begin_layout Plain Layout
10433 \begin_inset Quotes erd
10437 This way was chosen so that the look is the same with each used screen
10442 \begin_layout Description
10443 \begin_inset Flex CharStyle:Code
10446 \begin_layout Plain Layout
10453 \begin_inset Flex CharStyle:Code
10456 \begin_layout Plain Layout
10461 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10467 \begin_inset Newline newline
10470 The kind of margin that the layout has on the left side.
10472 \begin_inset Flex CharStyle:Code
10475 \begin_layout Plain Layout
10481 just means a fixed margin.
10483 \begin_inset Flex CharStyle:Code
10486 \begin_layout Plain Layout
10492 means that the left margin depends on the string entered in the
10493 \begin_inset Flex CharStyle:MenuItem
10496 \begin_layout Plain Layout
10497 Edit\SpecialChar \menuseparator
10499 \begin_inset space ~
10508 This is used to typeset nice lists without tabulators.
10510 \begin_inset Flex CharStyle:Code
10513 \begin_layout Plain Layout
10519 means that the margin depends on the size of the label.
10520 This is used for automatic enumerated headlines.
10521 It is obvious that the headline
10522 \begin_inset Quotes eld
10525 5.4.3.2.1 Very long headline
10526 \begin_inset Quotes erd
10529 must have a wider left margin (as wide as
10530 \begin_inset Quotes eld
10534 \begin_inset Quotes erd
10537 plus the space) than
10538 \begin_inset Quotes eld
10541 3.2 Very long headline
10542 \begin_inset Quotes erd
10546 \begin_inset Quotes eld
10550 \begin_inset Quotes erd
10553 are not able to do this.
10555 \begin_inset Flex CharStyle:Code
10558 \begin_layout Plain Layout
10564 is similar, but only the very first row of the paragraph is dynamic, while
10565 the others are static; this is used, for example, for descriptions.
10567 \begin_inset Flex CharStyle:Code
10570 \begin_layout Plain Layout
10576 means the margin is chosen in a way that the longest row of this paragraph
10577 fits to the right margin.
10578 This is used to typeset an address on the right edge of the page.
10581 \begin_layout Description
10582 \begin_inset Flex CharStyle:Code
10585 \begin_layout Plain Layout
10592 \begin_inset Flex CharStyle:Code
10595 \begin_layout Plain Layout
10604 \begin_inset Flex CharStyle:Code
10607 \begin_layout Plain Layout
10613 ] Whether fragile commands in this layout should be
10614 \begin_inset Flex CharStyle:Code
10617 \begin_layout Plain Layout
10630 whether this command should itself be protected.)
10633 \begin_layout Description
10634 \begin_inset Flex CharStyle:Code
10637 \begin_layout Plain Layout
10644 \begin_inset Flex CharStyle:Code
10647 \begin_layout Plain Layout
10654 \begin_inset Flex CharStyle:Code
10657 \begin_layout Plain Layout
10665 ] Whether newlines are translated into LaTeX newlines (
10666 \begin_inset Flex CharStyle:Code
10669 \begin_layout Plain Layout
10680 The translation can be switched off to allow more comfortable LaTeX editing
10684 \begin_layout Description
10685 \begin_inset Flex CharStyle:Code
10688 \begin_layout Plain Layout
10695 \begin_inset Flex CharStyle:Code
10698 \begin_layout Plain Layout
10705 \begin_inset Flex CharStyle:Code
10708 \begin_layout Plain Layout
10716 ] Whether the following Paragraph is allowed to indent its very first row.
10718 \begin_inset Flex CharStyle:Code
10721 \begin_layout Plain Layout
10727 means that it is not allowed to do so;
10728 \begin_inset Flex CharStyle:Code
10731 \begin_layout Plain Layout
10737 means it could do so if it wants to.
10740 \begin_layout Description
10741 \begin_inset Flex CharStyle:Code
10744 \begin_layout Plain Layout
10750 Name of a layout that has replaced this layout.
10751 This is used to rename a layout, while keeping backward compatibility.
10754 \begin_layout Description
10755 \begin_inset Flex CharStyle:Code
10758 \begin_layout Plain Layout
10765 \begin_inset Flex CharStyle:Code
10768 \begin_layout Plain Layout
10774 ] The number of optional arguments that can be used with this layout.
10775 This is useful for things like section headings, and only makes sense with
10779 \begin_layout Description
10780 \begin_inset Flex CharStyle:Code
10783 \begin_layout Plain Layout
10790 \begin_inset Flex CharStyle:Code
10793 \begin_layout Plain Layout
10799 ] The indent of the very first line of a paragraph.
10801 \begin_inset Flex CharStyle:Code
10804 \begin_layout Plain Layout
10810 will be fixed for a certain layout.
10811 The exception is Standard layout, since the indentation of a Standard layout
10812 paragraph can be prohibited with
10813 \begin_inset Flex CharStyle:Code
10816 \begin_layout Plain Layout
10823 Also, Standard layout paragraphs inside environments use the
10824 \begin_inset Flex CharStyle:Code
10827 \begin_layout Plain Layout
10833 of the environment, not their native one.
10834 For example, Standard paragraphs inside an enumeration are not indented.
10837 \begin_layout Description
10838 \begin_inset Flex CharStyle:Code
10841 \begin_layout Plain Layout
10848 \begin_inset Flex CharStyle:Code
10851 \begin_layout Plain Layout
10857 ] The vertical space between two paragraphs of this layout.
10860 \begin_layout Description
10861 \begin_inset Flex CharStyle:Code
10864 \begin_layout Plain Layout
10871 \begin_inset Flex CharStyle:Code
10874 \begin_layout Plain Layout
10880 ] LyX allows the user to choose either
10881 \begin_inset Quotes eld
10885 \begin_inset Quotes erd
10889 \begin_inset Quotes eld
10893 \begin_inset Quotes erd
10896 to typeset a document.
10898 \begin_inset Quotes eld
10902 \begin_inset Quotes erd
10905 is chosen, this value is completely ignored.
10907 \begin_inset Quotes eld
10911 \begin_inset Quotes erd
10914 is chosen, the parindent of a LaTeXtype
10915 \begin_inset Quotes eld
10919 \begin_inset Quotes erd
10922 layout is ignored and all paragraphs are separated by this parskip argument.
10923 The vertical space is calculated with
10924 \begin_inset Flex CharStyle:Code
10927 \begin_layout Plain Layout
10929 \begin_inset space ~
10938 \begin_inset Flex CharStyle:Code
10941 \begin_layout Plain Layout
10947 is the height of a row with the normal font.
10948 This way, the look stays the same with different screen fonts.
10951 \begin_layout Description
10952 \begin_inset Flex CharStyle:Code
10955 \begin_layout Plain Layout
10962 \begin_inset CommandInset label
10964 name "des:PathThru"
10971 \begin_inset Flex CharStyle:Code
10974 \begin_layout Plain Layout
10985 \begin_inset Flex CharStyle:Code
10988 \begin_layout Plain Layout
10994 ] Whether the contents of this paragraph should be output in raw form, meaning
10995 without special translations that LaTeX would require.
10998 \begin_layout Description
10999 \begin_inset Flex CharStyle:Code
11002 \begin_layout Plain Layout
11009 \begin_inset CommandInset label
11011 name "des:Preamble"
11015 Information to be included in the LaTeX preamble when this style is used.
11016 Used to define macros, load packages, etc., required by this particular
11019 \begin_inset Quotes eld
11023 \begin_inset Flex CharStyle:Code
11026 \begin_layout Plain Layout
11033 \begin_inset Quotes erd
11039 \begin_layout Description
11040 \begin_inset Flex CharStyle:Code
11043 \begin_layout Plain Layout
11050 \begin_inset Flex CharStyle:Code
11053 \begin_layout Plain Layout
11060 \begin_inset CommandInset label
11062 name "des:Requires"
11066 Whether the layout requires the feature
11067 \begin_inset Flex CharStyle:Code
11070 \begin_layout Plain Layout
11077 See the description of
11078 \begin_inset Flex CharStyle:Code
11081 \begin_layout Plain Layout
11088 \begin_inset CommandInset ref
11089 LatexCommand pageref
11090 reference "des:FreeSpacing"
11094 ) for information on `features'.
11098 \begin_layout Description
11099 \begin_inset Flex CharStyle:Code
11102 \begin_layout Plain Layout
11109 \begin_inset Flex CharStyle:Code
11112 \begin_layout Plain Layout
11119 \begin_inset Flex CharStyle:Code
11122 \begin_layout Plain Layout
11131 \begin_layout Description
11132 \begin_inset Flex CharStyle:Code
11135 \begin_layout Plain Layout
11142 \begin_inset Flex CharStyle:Code
11145 \begin_layout Plain Layout
11150 , onehalf, double, other
11159 ] This defines what the default spacing should be in the layout.
11161 \begin_inset Flex CharStyle:Code
11164 \begin_layout Plain Layout
11171 \begin_inset Flex CharStyle:Code
11174 \begin_layout Plain Layout
11181 \begin_inset Flex CharStyle:Code
11184 \begin_layout Plain Layout
11190 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11191 If you specify the argument
11192 \begin_inset Flex CharStyle:Code
11195 \begin_layout Plain Layout
11201 , then you should also provide a numerical argument which will be the actual
11203 Note that, contrary to other parameters,
11204 \begin_inset Flex CharStyle:Code
11207 \begin_layout Plain Layout
11213 implies the generation of specific LaTeX code, using the package
11216 \begin_inset Flex CharStyle:Code
11219 \begin_layout Plain Layout
11228 \begin_layout Description
11229 \begin_inset Flex CharStyle:Code
11232 \begin_layout Plain Layout
11238 The font used for the text body .
11240 \begin_inset CommandInset ref
11242 reference "sub:Font-description"
11249 \begin_layout Description
11250 \begin_inset Flex CharStyle:Code
11253 \begin_layout Plain Layout
11261 The level of the style in the table of contents.
11262 This is used for automatic numbering of section headings.
11265 \begin_layout Description
11266 \begin_inset Flex CharStyle:Code
11269 \begin_layout Plain Layout
11276 \begin_inset Flex CharStyle:Code
11279 \begin_layout Plain Layout
11285 ] The vertical space with which the very first of a chain of paragraphs
11286 with this layout is separated from the previous paragraph.
11287 If the previous paragraph has another layout, the separations are not simply
11288 added, but the maximum is taken.
11291 \begin_layout Subsection
11293 \begin_inset CommandInset label
11302 \begin_layout Standard
11303 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11304 define the floats (
11305 \begin_inset Flex CharStyle:MenuItem
11308 \begin_layout Plain Layout
11315 \begin_inset Flex CharStyle:MenuItem
11318 \begin_layout Plain Layout
11324 , \SpecialChar \ldots{}
11325 ) in the text class itself.
11326 Standard floats are included in the file
11327 \begin_inset Flex CharStyle:Code
11330 \begin_layout Plain Layout
11336 , so you may have to do no more than add
11339 \begin_layout LyX-Code
11340 Input stdfloats.inc
11343 \begin_layout Standard
11344 to your layout file.
11345 If you want to implement a text class that proposes some other float types
11346 (like the AGU class bundled with LyX), the information below will hopefully
11350 \begin_layout Description
11351 \begin_inset Flex CharStyle:Code
11354 \begin_layout Plain Layout
11361 \begin_inset Flex CharStyle:Code
11364 \begin_layout Plain Layout
11371 \begin_inset Quotes erd
11375 \begin_inset Quotes erd
11378 ] The file name extension of an auxiliary file for the list of figures (or
11380 LaTeX writes the captions to this file.
11383 \begin_layout Description
11384 \begin_inset Flex CharStyle:Code
11387 \begin_layout Plain Layout
11394 \begin_inset Flex CharStyle:Code
11397 \begin_layout Plain Layout
11404 \begin_inset Quotes erd
11408 \begin_inset Quotes erd
11411 ] The string that will be used in the menus and also for the caption.
11414 \begin_layout Description
11415 \begin_inset Flex CharStyle:Code
11418 \begin_layout Plain Layout
11425 \begin_inset Flex CharStyle:Code
11428 \begin_layout Plain Layout
11437 \begin_inset Flex CharStyle:Code
11440 \begin_layout Plain Layout
11447 \begin_inset Flex CharStyle:Code
11450 \begin_layout Plain Layout
11456 if the float is already defined by the LaTeX document class.
11458 \begin_inset Flex CharStyle:Code
11461 \begin_layout Plain Layout
11467 , the float will be defined using the LaTeX package
11468 \begin_inset Flex CharStyle:Code
11471 \begin_layout Plain Layout
11480 \begin_layout Description
11481 \begin_inset Flex CharStyle:Code
11484 \begin_layout Plain Layout
11491 \begin_inset Flex CharStyle:Code
11494 \begin_layout Plain Layout
11501 \begin_inset Quotes erd
11505 \begin_inset Quotes erd
11508 ] The heading used for the list of floats.
11511 \begin_layout Description
11512 \begin_inset Flex CharStyle:Code
11515 \begin_layout Plain Layout
11522 \begin_inset Flex CharStyle:Code
11525 \begin_layout Plain Layout
11532 \begin_inset Quotes erd
11536 \begin_inset Quotes erd
11539 ] This (optional) argument determines whether floats of this class will
11540 be numbered within some sectional unit of the document.
11541 For example, if within is equal to
11542 \begin_inset Flex CharStyle:Code
11545 \begin_layout Plain Layout
11551 , the floats will be numbered within chapters.
11555 \begin_layout Description
11556 \begin_inset Flex CharStyle:Code
11559 \begin_layout Plain Layout
11566 \begin_inset Flex CharStyle:Code
11569 \begin_layout Plain Layout
11576 \begin_inset Quotes erd
11580 \begin_inset Quotes erd
11583 ] The default placement for the given class of floats.
11584 The string should be as in standard LaTeX:
11585 \begin_inset Flex CharStyle:Code
11588 \begin_layout Plain Layout
11595 \begin_inset Flex CharStyle:Code
11598 \begin_layout Plain Layout
11605 \begin_inset Flex CharStyle:Code
11608 \begin_layout Plain Layout
11615 \begin_inset Flex CharStyle:Code
11618 \begin_layout Plain Layout
11624 for top, bottom, page, and here, respectively.
11628 \begin_layout Plain Layout
11629 Note that the order of these letters in the string is irrelevant, like in
11635 On top of that there is a new type,
11636 \begin_inset Flex CharStyle:Code
11639 \begin_layout Plain Layout
11645 , which does not really correspond to a float, since it means: put it
11646 \begin_inset Quotes eld
11650 \begin_inset Quotes erd
11654 Note however that the
11655 \begin_inset Flex CharStyle:Code
11658 \begin_layout Plain Layout
11664 specifier is special and, because of implementation details, cannot be
11665 used in non-built in float types.
11666 If you do not understand what this means, just use
11667 \begin_inset Quotes eld
11671 \begin_inset Flex CharStyle:Code
11674 \begin_layout Plain Layout
11681 \begin_inset Quotes erd
11687 \begin_layout Description
11688 \begin_inset Flex CharStyle:Code
11691 \begin_layout Plain Layout
11698 \begin_inset Flex CharStyle:Code
11701 \begin_layout Plain Layout
11708 \begin_inset Quotes erd
11712 \begin_inset Quotes erd
11715 ] The style used when defining the float using
11716 \begin_inset Flex CharStyle:Code
11719 \begin_layout Plain Layout
11730 \begin_layout Description
11731 \begin_inset Flex CharStyle:Code
11734 \begin_layout Plain Layout
11741 \begin_inset Flex CharStyle:Code
11744 \begin_layout Plain Layout
11751 \begin_inset Quotes erd
11755 \begin_inset Quotes erd
11759 \begin_inset Quotes eld
11763 \begin_inset Quotes erd
11766 of the new class of floats, like program or algorithm.
11767 After the appropriate
11768 \begin_inset Flex CharStyle:Code
11771 \begin_layout Plain Layout
11780 \begin_inset Flex CharStyle:Code
11783 \begin_layout Plain Layout
11792 \begin_inset Flex CharStyle:Code
11795 \begin_layout Plain Layout
11806 \begin_layout Standard
11807 Note that defining a float with type
11808 \begin_inset Flex CharStyle:Code
11811 \begin_layout Plain Layout
11819 automatically defines the corresponding counter with name
11820 \begin_inset Flex CharStyle:Code
11823 \begin_layout Plain Layout
11834 \begin_layout Subsection
11835 Flex insets and InsetLayout
11836 \begin_inset CommandInset label
11838 name "sub:Flex-insets-and"
11845 \begin_layout Standard
11846 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11847 these are called Flex insets.
11851 \begin_layout Standard
11852 Flex insets come in three different kinds:
11855 \begin_layout Itemize
11857 \begin_inset Flex CharStyle:Code
11860 \begin_layout Plain Layout
11866 ): These define semantic markup corresponding to such LaTeX commands as
11868 \begin_inset Flex CharStyle:Code
11871 \begin_layout Plain Layout
11880 \begin_inset Flex CharStyle:Code
11883 \begin_layout Plain Layout
11894 \begin_layout Itemize
11896 \begin_inset Flex CharStyle:Code
11899 \begin_layout Plain Layout
11905 ): These can be used to define custom collapsible insets, similar to TeX
11906 code, footnote, and the like.
11907 An obvious example is an endnote inset, which is defined in the
11908 \begin_inset Flex CharStyle:Code
11911 \begin_layout Plain Layout
11920 \begin_layout Itemize
11922 \begin_inset Flex CharStyle:Code
11925 \begin_layout Plain Layout
11931 ): For use with DocBook classes.
11934 \begin_layout Standard
11935 Flex insets are defined using the
11936 \begin_inset Flex CharStyle:Code
11939 \begin_layout Plain Layout
11945 tag, which shall be explained in a moment.
11948 \begin_layout Standard
11950 \begin_inset Flex CharStyle:Code
11953 \begin_layout Plain Layout
11959 tag also serves another function: It can be used to customize the general
11960 layout of many different types of insets.
11962 \begin_inset Flex CharStyle:Code
11965 \begin_layout Plain Layout
11971 can be used to customize the layout parameters for footnotes, marginal
11972 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11973 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11974 define Flex insets.
11977 \begin_layout Standard
11979 \begin_inset Flex CharStyle:Code
11982 \begin_layout Plain Layout
11988 definition must begin with a line of the form:
11991 \begin_layout LyX-Code
11995 \begin_layout Standard
11997 \begin_inset Flex CharStyle:Code
12000 \begin_layout Plain Layout
12006 indicates the inset whose layout is being defined, and here there are two
12010 \begin_layout Enumerate
12011 The layout for a pre-existing inset is being modified.
12012 In this case, can be
12013 \begin_inset Flex CharStyle:Code
12016 \begin_layout Plain Layout
12022 any one of the following:
12023 \begin_inset Flex CharStyle:Code
12026 \begin_layout Plain Layout
12033 \begin_inset Flex CharStyle:Code
12036 \begin_layout Plain Layout
12043 \begin_inset Flex CharStyle:Code
12046 \begin_layout Plain Layout
12053 \begin_inset Flex CharStyle:Code
12056 \begin_layout Plain Layout
12063 \begin_inset Flex CharStyle:Code
12066 \begin_layout Plain Layout
12073 \begin_inset Flex CharStyle:Code
12076 \begin_layout Plain Layout
12083 \begin_inset Flex CharStyle:Code
12086 \begin_layout Plain Layout
12093 \begin_inset Flex CharStyle:Code
12096 \begin_layout Plain Layout
12103 \begin_inset Flex CharStyle:Code
12106 \begin_layout Plain Layout
12113 \begin_inset Flex CharStyle:Code
12116 \begin_layout Plain Layout
12123 \begin_inset Flex CharStyle:Code
12126 \begin_layout Plain Layout
12133 \begin_inset Flex CharStyle:Code
12136 \begin_layout Plain Layout
12143 \begin_inset Flex CharStyle:Code
12146 \begin_layout Plain Layout
12153 \begin_inset Flex CharStyle:Code
12156 \begin_layout Plain Layout
12163 \begin_inset Flex CharStyle:Code
12166 \begin_layout Plain Layout
12173 \begin_inset Flex CharStyle:Code
12176 \begin_layout Plain Layout
12183 \begin_inset Flex CharStyle:Code
12186 \begin_layout Plain Layout
12193 \begin_inset Flex CharStyle:Code
12196 \begin_layout Plain Layout
12203 \begin_inset Flex CharStyle:Code
12206 \begin_layout Plain Layout
12213 \begin_inset Flex CharStyle:Code
12216 \begin_layout Plain Layout
12226 \begin_layout Enumerate
12227 The layout for a Flex inset is being defined.
12229 \begin_inset Flex CharStyle:Code
12232 \begin_layout Plain Layout
12238 can be any valid identifier not used by a pre-existing inset.
12239 Note that the definition of a flex inset must
12244 \begin_inset Flex CharStyle:Code
12247 \begin_layout Plain Layout
12256 \begin_layout Standard
12258 \begin_inset Flex CharStyle:Code
12261 \begin_layout Plain Layout
12267 definition can contain the following entries:
12270 \begin_layout Description
12271 \begin_inset Flex CharStyle:Code
12274 \begin_layout Plain Layout
12280 The color for the inset's background.
12281 The valid colors are defined in
12282 \begin_inset Flex CharStyle:Code
12285 \begin_layout Plain Layout
12294 \begin_layout Description
12295 \begin_inset Flex CharStyle:Code
12298 \begin_layout Plain Layout
12304 As with paragraph styles (see page
12305 \begin_inset CommandInset ref
12307 reference "des:CopyStyle"
12314 \begin_layout Description
12315 \begin_inset Flex CharStyle:Code
12318 \begin_layout Plain Layout
12325 \begin_inset Flex CharStyle:Code
12328 \begin_layout Plain Layout
12337 \begin_inset Flex CharStyle:Code
12340 \begin_layout Plain Layout
12346 ] Indicates whether the user may employ the Paragraph Settings dialog to
12347 customize the paragraph.
12350 \begin_layout Description
12351 \begin_inset Flex CharStyle:Code
12354 \begin_layout Plain Layout
12361 \begin_inset Flex CharStyle:Code
12364 \begin_layout Plain Layout
12371 \begin_inset Flex CharStyle:Code
12374 \begin_layout Plain Layout
12381 \begin_inset Flex CharStyle:Code
12384 \begin_layout Plain Layout
12390 , describing the rendering style used for the inset's frame and buttons.
12391 Footnotes generally use
12392 \begin_inset Flex CharStyle:Code
12395 \begin_layout Plain Layout
12401 , ERT insets generally
12402 \begin_inset Flex CharStyle:Code
12405 \begin_layout Plain Layout
12411 , and character styles
12412 \begin_inset Flex CharStyle:Code
12415 \begin_layout Plain Layout
12424 \begin_layout Description
12425 \begin_inset Flex CharStyle:Code
12428 \begin_layout Plain Layout
12434 Required at the end of the InsetLayout declarations.
12437 \begin_layout Description
12438 \begin_inset Flex CharStyle:Code
12441 \begin_layout Plain Layout
12447 The font used for both the text body
12453 \begin_inset space ~
12457 \begin_inset CommandInset ref
12459 reference "sub:Font-description"
12464 Note that defining this font automatically defines the
12465 \begin_inset Flex CharStyle:Code
12468 \begin_layout Plain Layout
12474 to the same value, so define this first and define
12475 \begin_inset Flex CharStyle:Code
12478 \begin_layout Plain Layout
12484 later if you want them to be different.
12487 \begin_layout Description
12488 \begin_inset Flex CharStyle:Code
12491 \begin_layout Plain Layout
12498 \begin_inset Quotes eld
12502 \begin_inset Quotes erd
12505 language, leading to Left-to-Right (latin) output, e.
12506 \begin_inset space \thinspace{}
12510 \begin_inset space \space{}
12513 in TeX code or URL.
12517 \begin_layout Description
12518 \begin_inset Flex CharStyle:Code
12521 \begin_layout Plain Layout
12528 \begin_inset Flex CharStyle:Code
12531 \begin_layout Plain Layout
12540 \begin_inset Flex CharStyle:Code
12543 \begin_layout Plain Layout
12549 ] Indicates whether the PlainLayout should be used or, instead, the user
12550 can change the paragraph style used in the inset.
12553 \begin_layout Description
12554 \begin_inset Flex CharStyle:Code
12557 \begin_layout Plain Layout
12563 As with paragraph styles (see page
12564 \begin_inset CommandInset ref
12565 LatexCommand pageref
12566 reference "des:FreeSpacing"
12573 \begin_layout Description
12574 \begin_inset Flex CharStyle:Code
12577 \begin_layout Plain Layout
12584 \begin_inset Flex CharStyle:Code
12587 \begin_layout Plain Layout
12596 \begin_inset Flex CharStyle:Code
12599 \begin_layout Plain Layout
12605 ] Whether to include the contents of this inset in the strings generated
12606 for the `Outline' pane.
12607 One would not, for example, want the content of a footnote in a section
12608 header to be included in the TOC displayed in the outline, but one would
12609 normally want the content of a character style displayed.
12610 Default is false: not to include.
12613 \begin_layout Description
12614 \begin_inset Flex CharStyle:Code
12617 \begin_layout Plain Layout
12623 As with paragraph styles (see page
12624 \begin_inset CommandInset ref
12625 LatexCommand pageref
12626 reference "des:KeepEmpty"
12633 \begin_layout Description
12634 \begin_inset Flex CharStyle:Code
12637 \begin_layout Plain Layout
12643 The font used for the label.
12645 \begin_inset space ~
12649 \begin_inset CommandInset ref
12651 reference "sub:Font-description"
12656 Note that this definition can never appear before
12657 \begin_inset Flex CharStyle:Code
12660 \begin_layout Plain Layout
12666 , lest it be ineffective.
12669 \begin_layout Description
12670 \begin_inset Flex CharStyle:Code
12673 \begin_layout Plain Layout
12679 What will be displayed on the button or elsewhere as the inset label.
12680 Some inset types (TeX code and Branch) modify this label on the fly.
12683 \begin_layout Description
12684 \begin_inset Flex CharStyle:Code
12687 \begin_layout Plain Layout
12693 The name of the corresponding LaTeX stuff.
12694 Either the environment or command name.
12697 \begin_layout Description
12698 \begin_inset Flex CharStyle:Code
12701 \begin_layout Plain Layout
12707 The optional parameter for the corresponding
12708 \begin_inset Flex CharStyle:Code
12711 \begin_layout Plain Layout
12717 stuff, including possible bracket pairs like
12718 \begin_inset Flex CharStyle:Code
12721 \begin_layout Plain Layout
12728 This parameter cannot be changed from within LyX.
12731 \begin_layout Description
12732 \begin_inset Flex CharStyle:Code
12735 \begin_layout Plain Layout
12741 As with paragraph styles (see page
12742 \begin_inset CommandInset ref
12743 LatexCommand pageref
12744 reference "des:LatexType"
12751 \begin_layout Description
12752 \begin_inset Flex CharStyle:Code
12755 \begin_layout Plain Layout
12762 \begin_inset Flex CharStyle:Code
12765 \begin_layout Plain Layout
12772 \begin_inset Flex CharStyle:Code
12775 \begin_layout Plain Layout
12782 \begin_inset Flex CharStyle:Code
12785 \begin_layout Plain Layout
12792 \begin_inset Flex CharStyle:Code
12795 \begin_layout Plain Layout
12801 (indicating a dummy definition ending definitions of charstyles, etc).
12802 This entry is required in and is only meaningful for Flex insets.
12803 Among other things, it determines on which menu this inset will appear.
12806 \begin_layout Description
12807 \begin_inset Flex CharStyle:Code
12810 \begin_layout Plain Layout
12817 \begin_inset Flex CharStyle:Code
12820 \begin_layout Plain Layout
12829 \begin_inset Flex CharStyle:Code
12832 \begin_layout Plain Layout
12838 ] Whether multiple paragraphs are permitted in this inset.
12839 This will also set CustomPars to the same value and ForcePlain to the opposite
12841 These can be reset to other values, if they are used
12848 \begin_layout Description
12849 \begin_inset Flex CharStyle:Code
12852 \begin_layout Plain Layout
12859 \begin_inset Flex CharStyle:Code
12862 \begin_layout Plain Layout
12871 \begin_inset Flex CharStyle:Code
12874 \begin_layout Plain Layout
12880 ] Whether fragile commands in this layout should be
12881 \begin_inset Flex CharStyle:Code
12884 \begin_layout Plain Layout
12897 whether the command should itself be protected.)
12900 \begin_layout Description
12901 \begin_inset Flex CharStyle:Code
12904 \begin_layout Plain Layout
12911 \begin_inset Flex CharStyle:Code
12914 \begin_layout Plain Layout
12923 \begin_inset Flex CharStyle:Code
12926 \begin_layout Plain Layout
12932 ] As with paragraph styles (see page
12933 \begin_inset CommandInset ref
12935 reference "des:PathThru"
12942 \begin_layout Description
12943 \begin_inset Flex CharStyle:Code
12946 \begin_layout Plain Layout
12952 As with paragraph styles (see page
12953 \begin_inset CommandInset ref
12954 LatexCommand pageref
12955 reference "des:Preamble"
12962 \begin_layout Description
12963 \begin_inset Flex CharStyle:Code
12966 \begin_layout Plain Layout
12973 \begin_inset Flex CharStyle:Code
12976 \begin_layout Plain Layout
12982 ] As with paragraph styles (see page
12983 \begin_inset CommandInset ref
12984 LatexCommand pageref
12985 reference "des:Requires"
12992 \begin_layout Subsection
12994 \begin_inset CommandInset label
12996 name "sub:Counters"
13003 \begin_layout Standard
13004 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13006 \begin_inset Flex CharStyle:MenuItem
13009 \begin_layout Plain Layout
13016 \begin_inset Flex CharStyle:MenuItem
13019 \begin_layout Plain Layout
13025 , \SpecialChar \ldots{}
13026 ) in the text class itself.
13027 The standard counters are defined in the file
13028 \begin_inset Flex CharStyle:Code
13031 \begin_layout Plain Layout
13037 , so you may have to do no more than add
13040 \begin_layout LyX-Code
13041 Input stdcounters.inc
13044 \begin_layout Standard
13045 to your layout file to get them to work.
13046 But if you want to define custom counters, then you can do so.
13047 The counter declaration must begin with:
13050 \begin_layout LyX-Code
13054 \begin_layout Standard
13055 where of course `name' is replaced by the name of the counter.
13056 And it must end with
13057 \begin_inset Quotes eld
13061 \begin_inset Flex CharStyle:Code
13064 \begin_layout Plain Layout
13071 \begin_inset Quotes erd
13075 The following parameters can also be used:
13078 \begin_layout Description
13079 \begin_inset Flex CharStyle:Code
13082 \begin_layout Plain Layout
13083 LabelString [string=""]
13088 when this is defined, this string defines how the counter is displayed.
13089 Setting this value sets
13090 \begin_inset Flex CharStyle:Code
13093 \begin_layout Plain Layout
13094 LabelStringAppendix
13100 The following special constructs can be used in the string:
13104 \begin_layout Itemize
13105 \begin_inset Flex CharStyle:Code
13108 \begin_layout Plain Layout
13116 will be replaced by the expansion of the
13117 \begin_inset Flex CharStyle:Code
13120 \begin_layout Plain Layout
13127 \begin_inset Flex CharStyle:Code
13130 \begin_layout Plain Layout
13131 LabelStringAppendix
13137 \begin_inset Flex CharStyle:Code
13140 \begin_layout Plain Layout
13150 \begin_layout Itemize
13151 counter values can be expressed using LaTeX-like macros
13152 \begin_inset Flex CharStyle:Code
13155 \begin_layout Plain Layout
13172 \begin_inset Flex CharStyle:Code
13175 \begin_layout Plain Layout
13187 \begin_layout Plain Layout
13197 Actually, the situation is a bit more complicated: any
13216 other than those described below will produce arabic numerals.
13217 It would not be surprising to see this change in the future.
13223 \begin_inset Flex CharStyle:Code
13226 \begin_layout Plain Layout
13232 : 1, 2, 3,\SpecialChar \ldots{}
13234 \begin_inset Flex CharStyle:Code
13237 \begin_layout Plain Layout
13243 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13245 \begin_inset Flex CharStyle:Code
13248 \begin_layout Plain Layout
13254 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13256 \begin_inset Flex CharStyle:Code
13259 \begin_layout Plain Layout
13265 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13267 \begin_inset Flex CharStyle:Code
13270 \begin_layout Plain Layout
13276 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13278 \begin_inset Flex CharStyle:Code
13281 \begin_layout Plain Layout
13287 for hebrew numerals.
13291 \begin_layout Standard
13292 If LabelString is not defined, a default value is constructed as follows:
13293 if the counter has a master counter
13294 \begin_inset Flex CharStyle:Code
13297 \begin_layout Plain Layout
13304 \begin_inset Flex CharStyle:Code
13307 \begin_layout Plain Layout
13314 \begin_inset Flex CharStyle:Code
13317 \begin_layout Plain Layout
13327 is used; otherwise the string
13328 \begin_inset Flex CharStyle:Code
13331 \begin_layout Plain Layout
13342 \begin_layout Description
13343 \begin_inset Flex CharStyle:Code
13346 \begin_layout Plain Layout
13347 LabelStringAppendix [string=""]
13353 \begin_inset Flex CharStyle:Code
13356 \begin_layout Plain Layout
13362 , but for use in the Appendix.
13365 \begin_layout Description
13366 \begin_inset Flex CharStyle:Code
13369 \begin_layout Plain Layout
13376 \begin_inset Flex CharStyle:Code
13379 \begin_layout Plain Layout
13386 \begin_inset Quotes erd
13390 \begin_inset Quotes erd
13393 ] If this is set to the name of another counter, the present counter will
13394 be reset every time the other one is increased.
13396 \begin_inset Flex CharStyle:Code
13399 \begin_layout Plain Layout
13406 \begin_inset Flex CharStyle:Code
13409 \begin_layout Plain Layout
13418 \begin_layout Subsection
13420 \begin_inset CommandInset label
13422 name "sub:Font-description"
13429 \begin_layout Standard
13430 A font description looks like this:
13433 \begin_layout LyX-Code
13443 \begin_layout LyX-Code
13447 \begin_layout LyX-Code
13451 \begin_layout Standard
13452 The following commands are available:
13455 \begin_layout Description
13456 \begin_inset Flex CharStyle:Code
13459 \begin_layout Plain Layout
13466 \begin_inset Flex CharStyle:Code
13469 \begin_layout Plain Layout
13478 \begin_inset Flex CharStyle:Code
13481 \begin_layout Plain Layout
13488 \begin_inset Flex CharStyle:Code
13491 \begin_layout Plain Layout
13498 \begin_inset Flex CharStyle:Code
13501 \begin_layout Plain Layout
13508 \begin_inset Flex CharStyle:Code
13511 \begin_layout Plain Layout
13518 \begin_inset Flex CharStyle:Code
13521 \begin_layout Plain Layout
13528 \begin_inset Flex CharStyle:Code
13531 \begin_layout Plain Layout
13538 \begin_inset Flex CharStyle:Code
13541 \begin_layout Plain Layout
13548 \begin_inset Flex CharStyle:Code
13551 \begin_layout Plain Layout
13560 \begin_layout Description
13561 \begin_inset Flex CharStyle:Code
13564 \begin_layout Plain Layout
13573 \begin_inset Flex CharStyle:Code
13576 \begin_layout Plain Layout
13587 \begin_inset Flex CharStyle:Code
13590 \begin_layout Plain Layout
13597 \begin_inset Flex CharStyle:Code
13600 \begin_layout Plain Layout
13609 \begin_layout Description
13610 \begin_inset Flex CharStyle:Code
13613 \begin_layout Plain Layout
13620 \begin_inset Flex CharStyle:Code
13623 \begin_layout Plain Layout
13629 ] Valid argument are:
13630 \begin_inset Flex CharStyle:Code
13633 \begin_layout Plain Layout
13640 \begin_inset Flex CharStyle:Code
13643 \begin_layout Plain Layout
13650 \begin_inset Flex CharStyle:Code
13653 \begin_layout Plain Layout
13660 \begin_inset Flex CharStyle:Code
13663 \begin_layout Plain Layout
13670 \begin_inset Flex CharStyle:Code
13673 \begin_layout Plain Layout
13680 \begin_inset Flex CharStyle:Code
13683 \begin_layout Plain Layout
13690 Each of these turns on or off the corresponding attribute.
13693 \begin_layout Description
13694 \begin_inset Flex CharStyle:Code
13697 \begin_layout Plain Layout
13706 \begin_inset Flex CharStyle:Code
13709 \begin_layout Plain Layout
13720 \begin_inset Flex CharStyle:Code
13723 \begin_layout Plain Layout
13732 \begin_layout Description
13733 \begin_inset Flex CharStyle:Code
13736 \begin_layout Plain Layout
13745 \begin_inset Flex CharStyle:Code
13748 \begin_layout Plain Layout
13759 \begin_inset Flex CharStyle:Code
13762 \begin_layout Plain Layout
13769 \begin_inset Flex CharStyle:Code
13772 \begin_layout Plain Layout
13779 \begin_inset Flex CharStyle:Code
13782 \begin_layout Plain Layout
13791 \begin_layout Description
13792 \begin_inset Flex CharStyle:Code
13795 \begin_layout Plain Layout
13802 \begin_inset Flex CharStyle:Code
13805 \begin_layout Plain Layout
13812 \begin_inset Flex CharStyle:Code
13815 \begin_layout Plain Layout
13822 \begin_inset Flex CharStyle:Code
13825 \begin_layout Plain Layout
13834 \begin_inset Flex CharStyle:Code
13837 \begin_layout Plain Layout
13844 \begin_inset Flex CharStyle:Code
13847 \begin_layout Plain Layout
13854 \begin_inset Flex CharStyle:Code
13857 \begin_layout Plain Layout
13864 \begin_inset Flex CharStyle:Code
13867 \begin_layout Plain Layout
13874 \begin_inset Flex CharStyle:Code
13877 \begin_layout Plain Layout
13886 \begin_layout Subsection
13887 Upgrading old layout files
13890 \begin_layout Standard
13891 The file format of layout files changes from time to time, so old layout
13892 files need to be converted.
13893 This process has been automated since LyX 1.4.0: If LyX reads an old format
13894 layout file it will call the conversion tool
13895 \begin_inset Flex CharStyle:Code
13898 \begin_layout Plain Layout
13899 LyXDir/scripts/layout2layout.py
13904 and convert it to a temporary file in current format.
13905 The original file is left untouched.
13906 If you want to convert the layout file permanently, just call the converter
13910 \begin_layout LyX-Code
13911 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13914 \begin_layout Standard
13915 (You need to replace
13916 \begin_inset Flex CharStyle:Code
13919 \begin_layout Plain Layout
13925 with the name of your LyX system directory, unless you happen to have defined
13926 such an environment variable.) Then copy
13927 \begin_inset Flex CharStyle:Code
13930 \begin_layout Plain Layout
13937 \begin_inset Flex CharStyle:Code
13940 \begin_layout Plain Layout
13949 \begin_layout Standard
13950 The automatic conversion only handles syntax changes.
13951 It cannot handle the case where the contents of included files was changed,
13952 so these will have to be converted separately.
13955 \begin_layout Section
13957 \begin_inset CommandInset label
13959 name "sec:Creating-Templates"
13966 \begin_layout Standard
13967 Templates are created just like usual documents.
13968 The only difference is that usual documents contain all possible settings,
13969 including the font scheme and the paper size.
13970 Usually a user doesn't want a template to overwrite his defaults in these
13972 For that reason, the designer of a template should remove the corresponding
13974 \begin_inset Flex CharStyle:Code
13977 \begin_layout Plain Layout
13986 \begin_inset Flex CharStyle:Code
13989 \begin_layout Plain Layout
13997 from the template LyX file.
13998 This can be done with any simple text-editor, for example
13999 \begin_inset Flex CharStyle:Code
14002 \begin_layout Plain Layout
14009 \begin_inset Flex CharStyle:Code
14012 \begin_layout Plain Layout
14022 \begin_layout Standard
14023 Put the edited template files you create in
14024 \begin_inset Flex CharStyle:Code
14027 \begin_layout Plain Layout
14033 , copy the ones you use from the global template directory in
14034 \begin_inset Flex CharStyle:Code
14037 \begin_layout Plain Layout
14043 to the same place, and redefine the template path in the
14044 \begin_inset Flex CharStyle:MenuItem
14047 \begin_layout Plain Layout
14048 Tools\SpecialChar \menuseparator
14049 Preferences\SpecialChar \menuseparator
14058 \begin_layout Standard
14059 Note that there is a template which has a particular meaning:
14060 \begin_inset Flex CharStyle:Code
14063 \begin_layout Plain Layout
14070 This template is loaded every time you create a new document with
14071 \begin_inset Flex CharStyle:MenuItem
14074 \begin_layout Plain Layout
14075 File\SpecialChar \menuseparator
14081 in order to provide useful defaults.
14082 To create this template from inside LyX, all you have to do is to open
14083 a document with the correct settings, and use the
14084 \begin_inset Flex CharStyle:MenuItem
14087 \begin_layout Plain Layout
14088 Save as Document Defaults
14096 \begin_layout Chapter
14097 Including External Material
14100 \begin_layout Standard
14101 \begin_inset Box Shadowbox
14110 height_special "totalheight"
14113 \begin_layout Plain Layout
14114 WARNING: This portion of the documentation has not been updated for some
14116 We certainly hope that it is still accurate, but there are no guarantees.
14124 \begin_layout Standard
14125 The use of material from sources external to LyX is covered in detail in
14131 This part of the manual covers what needs to happen behind the scenes for
14132 new sorts of material to be included.
14135 \begin_layout Section
14139 \begin_layout Standard
14140 The external material feature is based on the concept of a
14145 A template is a specification of how LyX should interface with a certain
14147 As bundled, LyX comes with predefined templates for Xfig figures, various
14148 raster format images, chess diagrams, and LilyPond music notation.
14149 You can check the actual list by using the menu
14150 \begin_inset Flex CharStyle:MenuItem
14153 \begin_layout Plain Layout
14154 Insert\SpecialChar \menuseparator
14155 File\SpecialChar \menuseparator
14162 Furthermore, it is possible to roll your own template to support a specific
14164 Later we'll describe in more detail what is involved, and hopefully you
14165 will submit all the templates you create so we can include them in a later
14169 \begin_layout Standard
14170 Another basic idea of the external material feature is to distinguish between
14171 the original file that serves as a base for final material and the produced
14172 file that is included in your exported or printed document.
14173 For example, consider the case of a figure produced with
14174 \begin_inset Flex CharStyle:Code
14177 \begin_layout Plain Layout
14184 The Xfig application itself works on an original file with the
14185 \begin_inset Flex CharStyle:Code
14188 \begin_layout Plain Layout
14195 Within Xfig, you create and change your figure, and when you are done,
14197 \begin_inset Flex CharStyle:Code
14200 \begin_layout Plain Layout
14207 When you want to include the figure in your document, you invoke
14208 \begin_inset Flex CharStyle:Code
14211 \begin_layout Plain Layout
14217 in order to create a PostScript file that can readily be included in your
14220 \begin_inset Flex CharStyle:Code
14223 \begin_layout Plain Layout
14229 file is the original file, and the PostScript file is the produced file.
14232 \begin_layout Standard
14233 This distinction is important in order to allow updating of the material
14234 while you are in the process of writing the document.
14235 Furthermore, it provides us with the flexibility that is needed to support
14236 multiple export formats.
14237 For instance, in the case of a plain text file, it is not exactly an award-winn
14238 ing idea to include the figure as raw PostScript.
14239 Instead, you'd either prefer to just include a reference to the figure
14240 or try to invoke some graphics to ASCII converter to make the final result
14241 look similar to the real graphics.
14242 The external material management allows you to do this, because it is parametri
14243 zed on the different export formats that LyX supports.
14246 \begin_layout Standard
14247 Besides supporting the production of different products according to the
14248 exported format, it supports tight integration with editing and viewing
14250 In the case of an Xfig figure, you are able to invoke Xfig on the original
14251 file with a single click from within the external material dialog in LyX,
14252 and also preview the produced PostScript file with Ghostview with another
14254 No more fiddling around with the command line and/or file browsers to locate
14255 and manipulate the original or produced files.
14256 In this way, you are finally able to take full advantage of the many different
14257 applications that are relevant to use when you write your documents, and
14258 ultimately be more productive.
14261 \begin_layout Section
14262 The external template configuration file
14265 \begin_layout Standard
14266 It is relatively easy to add custom external template definitions to LyX.
14267 However, be aware that doing this in an careless manner most probably
14271 introduce an easily exploitable security hole.
14272 So before you do this, please read the discussion about security in section
14274 \begin_inset CommandInset ref
14276 reference "sec:Security-discussion"
14283 \begin_layout Standard
14284 Having said that, we encourage you to submit any interesting templates that
14289 \begin_layout Standard
14290 The external templates are defined in the
14291 \begin_inset Flex CharStyle:Code
14294 \begin_layout Plain Layout
14295 LyXDir/lib/external_templates
14301 You can place your own version in
14302 \begin_inset Flex CharStyle:Code
14305 \begin_layout Plain Layout
14306 UserDir/external_templates
14314 \begin_layout Standard
14315 A typical template looks like this:
14318 \begin_layout LyX-Code
14322 \begin_layout LyX-Code
14323 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14326 \begin_layout LyX-Code
14330 \begin_layout LyX-Code
14334 \begin_layout LyX-Code
14338 \begin_layout LyX-Code
14342 \begin_layout LyX-Code
14346 \begin_layout LyX-Code
14347 AutomaticProduction true
14350 \begin_layout LyX-Code
14354 \begin_layout LyX-Code
14358 \begin_layout LyX-Code
14362 \begin_layout LyX-Code
14363 TransformCommand Rotate RotationLatexCommand
14366 \begin_layout LyX-Code
14367 TransformCommand Resize ResizeLatexCommand
14370 \begin_layout LyX-Code
14371 Product "$$RotateFront$$ResizeFront
14374 \begin_layout LyX-Code
14379 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14382 \begin_layout LyX-Code
14383 $$ResizeBack$$RotateBack"
14386 \begin_layout LyX-Code
14390 \begin_layout LyX-Code
14391 UpdateResult "$$AbsPath$$Basename.pstex_t"
14394 \begin_layout LyX-Code
14395 Requirement "graphicx"
14398 \begin_layout LyX-Code
14399 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14402 \begin_layout LyX-Code
14403 ReferencedFile latex "$$AbsPath$$Basename.eps"
14406 \begin_layout LyX-Code
14407 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14410 \begin_layout LyX-Code
14414 \begin_layout LyX-Code
14418 \begin_layout LyX-Code
14419 TransformCommand Rotate RotationLatexCommand
14422 \begin_layout LyX-Code
14423 TransformCommand Resize ResizeLatexCommand
14426 \begin_layout LyX-Code
14427 Product "$$RotateFront$$ResizeFront
14430 \begin_layout LyX-Code
14435 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14438 \begin_layout LyX-Code
14439 $$ResizeBack$$RotateBack"
14442 \begin_layout LyX-Code
14443 UpdateFormat pdftex
14446 \begin_layout LyX-Code
14447 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14450 \begin_layout LyX-Code
14451 Requirement "graphicx"
14454 \begin_layout LyX-Code
14455 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14458 \begin_layout LyX-Code
14459 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14462 \begin_layout LyX-Code
14466 \begin_layout LyX-Code
14470 \begin_layout LyX-Code
14471 Product "$$Contents(
14473 "$$AbsPath$$Basename.asc
14478 \begin_layout LyX-Code
14479 UpdateFormat asciixfig
14482 \begin_layout LyX-Code
14483 UpdateResult "$$AbsPath$$Basename.asc"
14486 \begin_layout LyX-Code
14490 \begin_layout LyX-Code
14494 \begin_layout LyX-Code
14495 Product "<graphic fileref=
14497 "$$AbsOrRelPathMaster$$Basename.eps
14502 \begin_layout LyX-Code
14506 \begin_layout LyX-Code
14510 \begin_layout LyX-Code
14511 UpdateResult "$$AbsPath$$Basename.eps"
14514 \begin_layout LyX-Code
14515 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14518 \begin_layout LyX-Code
14519 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14522 \begin_layout LyX-Code
14526 \begin_layout LyX-Code
14527 Product "[XFig: $$FName]"
14530 \begin_layout LyX-Code
14534 \begin_layout LyX-Code
14538 \begin_layout Standard
14539 As you can see, the template is enclosed in
14540 \begin_inset Flex CharStyle:Code
14543 \begin_layout Plain Layout
14549 \SpecialChar \ldots{}
14551 \begin_inset Flex CharStyle:Code
14554 \begin_layout Plain Layout
14561 It contains a header specifying some general settings and, for each supported
14562 primary document file format, a section
14563 \begin_inset Flex CharStyle:Code
14566 \begin_layout Plain Layout
14572 \SpecialChar \ldots{}
14574 \begin_inset Flex CharStyle:Code
14577 \begin_layout Plain Layout
14586 \begin_layout Subsection
14587 The template header
14590 \begin_layout Description
14591 \begin_inset Flex CharStyle:Code
14594 \begin_layout Plain Layout
14595 AutomaticProduction
14596 \begin_inset space ~
14604 Whether the file represented by the template must be generated by LyX.
14605 This command must occur exactly once.
14608 \begin_layout Description
14609 \begin_inset Flex CharStyle:Code
14612 \begin_layout Plain Layout
14614 \begin_inset space ~
14622 A glob pattern that is used in the file dialog to filter out the desired
14624 If there is more than one possible file extension (e.
14625 \begin_inset space \thinspace{}
14629 \begin_inset space \space{}
14633 \begin_inset Flex CharStyle:Code
14636 \begin_layout Plain Layout
14643 \begin_inset Flex CharStyle:Code
14646 \begin_layout Plain Layout
14652 ), use something like
14653 \begin_inset Flex CharStyle:Code
14656 \begin_layout Plain Layout
14663 This command must occur exactly once.
14666 \begin_layout Description
14667 \begin_inset Flex CharStyle:Code
14670 \begin_layout Plain Layout
14672 \begin_inset space ~
14680 The text that is displayed on the button.
14681 This command must occur exactly once.
14684 \begin_layout Description
14685 \begin_inset Flex CharStyle:Code
14688 \begin_layout Plain Layout
14690 \begin_inset space ~
14694 \begin_inset space ~
14702 The help text that is used in the External dialog.
14703 Provide enough information to explain to the user just what the template
14704 can provide him with.
14705 This command must occur exactly once.
14708 \begin_layout Description
14709 \begin_inset Flex CharStyle:Code
14712 \begin_layout Plain Layout
14714 \begin_inset space ~
14722 The file format of the original file.
14723 This must be the name of a format that is known to LyX (see section
14724 \begin_inset CommandInset ref
14726 reference "sec:Formats"
14732 \begin_inset Quotes eld
14736 \begin_inset Flex CharStyle:Code
14739 \begin_layout Plain Layout
14746 \begin_inset Quotes erd
14749 if the template can handle original files of more than one format.
14750 LyX will attempt to interrogate the file itself in order to deduce its
14751 format in this case.
14752 This command must occur exactly once.
14755 \begin_layout Description
14756 \begin_inset Flex CharStyle:Code
14759 \begin_layout Plain Layout
14761 \begin_inset space ~
14769 A unique name for the template.
14770 It must not contain substitution macros (see below).
14773 \begin_layout Description
14774 \begin_inset Flex CharStyle:Code
14777 \begin_layout Plain Layout
14779 \begin_inset space ~
14782 Rotate|Resize|Clip|Extra
14787 This command specifies which transformations are supported by this template.
14788 It may occur zero or more times.
14789 This command enables the corresponding tabs in the external dialog.
14791 \begin_inset Flex CharStyle:Code
14794 \begin_layout Plain Layout
14800 command must have either a corresponding
14801 \begin_inset Flex CharStyle:Code
14804 \begin_layout Plain Layout
14811 \begin_inset Flex CharStyle:Code
14814 \begin_layout Plain Layout
14821 \begin_inset Flex CharStyle:Code
14824 \begin_layout Plain Layout
14831 Otherwise the transformation will not be supported by that format.
14834 \begin_layout Subsection
14838 \begin_layout Description
14839 \begin_inset Flex CharStyle:Code
14842 \begin_layout Plain Layout
14844 \begin_inset space ~
14847 LaTeX|PDFLaTeX|PlainText|DocBook
14852 The primary document file format that this format definition is for.
14853 Not every template has a sensible representation in all document file formats.
14854 Please define nevertheless a
14855 \begin_inset Flex CharStyle:Code
14858 \begin_layout Plain Layout
14864 section for all formats.
14865 Use a dummy text when no representation is available.
14866 Then you can at least see a reference to the external material in the exported
14870 \begin_layout Description
14871 \begin_inset Flex CharStyle:Code
14874 \begin_layout Plain Layout
14876 \begin_inset space ~
14880 \begin_inset space ~
14888 This command defines an additional macro
14889 \begin_inset Flex CharStyle:Code
14892 \begin_layout Plain Layout
14898 for substitution in
14899 \begin_inset Flex CharStyle:Code
14902 \begin_layout Plain Layout
14910 \begin_inset Flex CharStyle:Code
14913 \begin_layout Plain Layout
14919 itself may contain substitution macros.
14920 The advantage over using
14921 \begin_inset Flex CharStyle:Code
14924 \begin_layout Plain Layout
14931 \begin_inset Flex CharStyle:Code
14934 \begin_layout Plain Layout
14940 is that the substituted value of
14941 \begin_inset Flex CharStyle:Code
14944 \begin_layout Plain Layout
14950 is sanitized so that it is a valid optional argument in the document format.
14951 This command may occur zero or more times.
14954 \begin_layout Description
14955 \begin_inset Flex CharStyle:Code
14958 \begin_layout Plain Layout
14960 \begin_inset space ~
14968 The text that is inserted in the exported document.
14969 This is actually the most important command and can be quite complex.
14970 This command must occur exactly once.
14973 \begin_layout Description
14974 \begin_inset Flex CharStyle:Code
14977 \begin_layout Plain Layout
14979 \begin_inset space ~
14987 This command specifies a preamble snippet that will be included in the
14989 It has to be defined using
14990 \begin_inset Flex CharStyle:Code
14993 \begin_layout Plain Layout
14999 \SpecialChar \ldots{}
15001 \begin_inset Flex CharStyle:Code
15004 \begin_layout Plain Layout
15011 This command may occur zero or more times.
15014 \begin_layout Description
15015 \begin_inset Flex CharStyle:Code
15018 \begin_layout Plain Layout
15020 \begin_inset space ~
15024 \begin_inset space ~
15032 This command denotes files that are created by the conversion process and
15033 are needed for a particular export format.
15034 If the filename is relative, it is interpreted relative to the master document.
15035 This command may be given zero or more times.
15038 \begin_layout Description
15039 \begin_inset Flex CharStyle:Code
15042 \begin_layout Plain Layout
15044 \begin_inset space ~
15052 The name of a required LaTeX package.
15053 The package is included via
15054 \begin_inset Flex CharStyle:Code
15057 \begin_layout Plain Layout
15065 in the LaTeX preamble.
15066 This command may occur zero or more times.
15069 \begin_layout Description
15070 \begin_inset Flex CharStyle:Code
15073 \begin_layout Plain Layout
15075 \begin_inset space ~
15079 \begin_inset space ~
15082 RotationLatexCommand
15087 This command specifies that the built in LaTeX command should be used for
15089 This command may occur once or not at all.
15092 \begin_layout Description
15093 \begin_inset Flex CharStyle:Code
15096 \begin_layout Plain Layout
15098 \begin_inset space ~
15102 \begin_inset space ~
15110 This command specifies that the built in LaTeX command should be used for
15112 This command may occur once or not at all.
15115 \begin_layout Description
15116 \begin_inset Flex CharStyle:Code
15119 \begin_layout Plain Layout
15121 \begin_inset space ~
15125 \begin_inset space ~
15128 RotationLatexOption
15133 This command specifies that rotation is done via an optional argument.
15134 This command may occur once or not at all.
15137 \begin_layout Description
15138 \begin_inset Flex CharStyle:Code
15141 \begin_layout Plain Layout
15143 \begin_inset space ~
15147 \begin_inset space ~
15155 This command specifies that resizing is done via an optional argument.
15156 This command may occur once or not at all.
15159 \begin_layout Description
15160 \begin_inset Flex CharStyle:Code
15163 \begin_layout Plain Layout
15165 \begin_inset space ~
15169 \begin_inset space ~
15177 This command specifies that clipping is done via an optional argument.
15178 This command may occur once or not at all.
15181 \begin_layout Description
15182 \begin_inset Flex CharStyle:Code
15185 \begin_layout Plain Layout
15187 \begin_inset space ~
15191 \begin_inset space ~
15199 This command specifies that an extra optional argument is used.
15200 This command may occur once or not at all.
15203 \begin_layout Description
15204 \begin_inset Flex CharStyle:Code
15207 \begin_layout Plain Layout
15209 \begin_inset space ~
15217 The file format of the converted file.
15218 This must be the name of a format that is known to LyX (see the
15219 \begin_inset Flex CharStyle:MenuItem
15222 \begin_layout Plain Layout
15227 ools\SpecialChar \menuseparator
15232 references:Conversion
15238 This command must occur exactly once.
15241 \begin_layout Description
15242 \begin_inset Flex CharStyle:Code
15245 \begin_layout Plain Layout
15247 \begin_inset space ~
15255 The file name of the converted file.
15256 The file name must be absolute.
15257 This command must occur exactly once.
15260 \begin_layout Subsection
15261 Preamble definitions
15264 \begin_layout Standard
15265 The external template configuration file may contain additional preamble
15266 definitions enclosed by
15267 \begin_inset Flex CharStyle:Code
15270 \begin_layout Plain Layout
15276 \SpecialChar \ldots{}
15278 \begin_inset Flex CharStyle:Code
15281 \begin_layout Plain Layout
15288 They can be used by the templates in the
15289 \begin_inset Flex CharStyle:Code
15292 \begin_layout Plain Layout
15301 \begin_layout Section
15302 The substitution mechanism
15305 \begin_layout Standard
15306 When the external material facility invokes an external program, it is done
15307 on the basis of a command defined in the template configuration file.
15308 These commands can contain various macros that are expanded before execution.
15309 Execution always take place in the directory of the containing document.
15312 \begin_layout Standard
15313 Also, whenever external material is to be displayed, the name will be produced
15314 by the substitution mechanism, and most other commands in the template
15315 definition support substitution as well.
15318 \begin_layout Standard
15319 The available macros are the following:
15322 \begin_layout Description
15323 \begin_inset Flex CharStyle:Code
15326 \begin_layout Plain Layout
15327 $$AbsOrRelPathMaster
15332 The file path, absolute or relative to the master LyX document.
15335 \begin_layout Description
15336 \begin_inset Flex CharStyle:Code
15339 \begin_layout Plain Layout
15340 $$AbsOrRelPathParent
15345 The file path, absolute or relative to the LyX document.
15348 \begin_layout Description
15349 \begin_inset Flex CharStyle:Code
15352 \begin_layout Plain Layout
15358 The absolute file path.
15361 \begin_layout Description
15362 \begin_inset Flex CharStyle:Code
15365 \begin_layout Plain Layout
15371 The filename without path and without the extension.
15374 \begin_layout Description
15375 \begin_inset Flex CharStyle:Code
15378 \begin_layout Plain Layout
15380 \begin_inset Quotes eld
15384 \begin_inset Quotes erd
15392 This macro will expand to the contents of the file with the name
15393 \begin_inset Flex CharStyle:Code
15396 \begin_layout Plain Layout
15405 \begin_layout Description
15406 \begin_inset Flex CharStyle:Code
15409 \begin_layout Plain Layout
15415 The file extension (including the dot).
15418 \begin_layout Description
15419 \begin_inset Flex CharStyle:Code
15422 \begin_layout Plain Layout
15428 The filename of the file specified in the external material dialog.
15429 This is either an absolute name, or it is relative to the LyX document.
15432 \begin_layout Description
15433 \begin_inset Flex CharStyle:Code
15436 \begin_layout Plain Layout
15443 \begin_inset Flex CharStyle:Code
15446 \begin_layout Plain Layout
15452 (absolute name or relative to the LyX document).
15455 \begin_layout Description
15456 \begin_inset Flex CharStyle:Code
15459 \begin_layout Plain Layout
15465 The file path, relative to the master LyX document.
15468 \begin_layout Description
15469 \begin_inset Flex CharStyle:Code
15472 \begin_layout Plain Layout
15478 The file path, relative to the LyX document.
15481 \begin_layout Description
15482 \begin_inset Flex CharStyle:Code
15485 \begin_layout Plain Layout
15491 This macro will expand to the absolute path of the system directory.
15492 This is typically used to point to the various helper scripts that are
15496 \begin_layout Description
15497 \begin_inset Flex CharStyle:Code
15500 \begin_layout Plain Layout
15506 A name and full path to a temporary file which will be automatically deleted
15507 whenever the containing document is closed, or the external material insertion
15511 \begin_layout Standard
15512 All path macros contain a trailing directory separator, so you can construct
15514 \begin_inset space \thinspace{}
15518 \begin_inset space \space{}
15521 the absolute filename with
15522 \begin_inset Flex CharStyle:Code
15525 \begin_layout Plain Layout
15526 $$AbsPath$$Basename$$Extension
15534 \begin_layout Standard
15535 The macros above are substituted in all commands unless otherwise noted.
15537 \begin_inset Flex CharStyle:Code
15540 \begin_layout Plain Layout
15546 supports additionally the following substitutions if they are enabled by
15548 \begin_inset Flex CharStyle:Code
15551 \begin_layout Plain Layout
15558 \begin_inset Flex CharStyle:Code
15561 \begin_layout Plain Layout
15570 \begin_layout Description
15571 \begin_inset Flex CharStyle:Code
15574 \begin_layout Plain Layout
15580 The front part of the resize command.
15583 \begin_layout Description
15584 \begin_inset Flex CharStyle:Code
15587 \begin_layout Plain Layout
15593 The back part of the resize command.
15596 \begin_layout Description
15597 \begin_inset Flex CharStyle:Code
15600 \begin_layout Plain Layout
15606 The front part of the rotation command.
15609 \begin_layout Description
15610 \begin_inset Flex CharStyle:Code
15613 \begin_layout Plain Layout
15619 The back part of the rotation command.
15622 \begin_layout Standard
15623 The value string of the
15624 \begin_inset Flex CharStyle:Code
15627 \begin_layout Plain Layout
15633 command supports additionally the following substitutions if they are enabled
15635 \begin_inset Flex CharStyle:Code
15638 \begin_layout Plain Layout
15645 \begin_inset Flex CharStyle:Code
15648 \begin_layout Plain Layout
15657 \begin_layout Description
15658 \begin_inset Flex CharStyle:Code
15661 \begin_layout Plain Layout
15670 \begin_layout Description
15671 \begin_inset Flex CharStyle:Code
15674 \begin_layout Plain Layout
15683 \begin_layout Description
15684 \begin_inset Flex CharStyle:Code
15687 \begin_layout Plain Layout
15696 \begin_layout Description
15697 \begin_inset Flex CharStyle:Code
15700 \begin_layout Plain Layout
15706 The rotation option.
15709 \begin_layout Standard
15710 You may ask why there are so many path macros.
15711 There are mainly two reasons:
15714 \begin_layout Enumerate
15715 Relative and absolute file names should remain relative or absolute, respectivel
15717 Users may have reasons to prefer either form.
15718 Relative names are useful for portable documents that should work on different
15719 machines, for example.
15720 Absolute names may be required by some programs.
15723 \begin_layout Enumerate
15724 LaTeX treats relative file names differently than LyX and other programs
15725 in nested included files.
15726 For LyX, a relative file name is always relative to the document that contains
15728 For LaTeX, it is always relative to the master document.
15729 These two definitions are identical if you have only one document, but
15730 differ if you have a master document that includes part documents.
15731 That means that relative filenames must be transformed when presented to
15733 Fortunately LyX does this automatically for you if you choose the right
15737 \begin_layout Standard
15738 So which path macro should be used in new template definitions? The rule
15742 \begin_layout Itemize
15744 \begin_inset Flex CharStyle:Code
15747 \begin_layout Plain Layout
15753 if an absolute path is required.
15756 \begin_layout Itemize
15758 \begin_inset Flex CharStyle:Code
15761 \begin_layout Plain Layout
15762 $$AbsOrRelPathMaster
15767 if the substituted string is some kind of LaTeX input.
15770 \begin_layout Itemize
15772 \begin_inset Flex CharStyle:Code
15775 \begin_layout Plain Layout
15776 $$AbsOrRelPathParent
15781 in order to preserve the user's choice.
15784 \begin_layout Standard
15785 There are special cases where this rule does not work and e.
15786 \begin_inset space \thinspace{}
15790 \begin_inset space \space{}
15793 relative names are needed, but normally it will work just fine.
15794 One example for such a case is the command
15795 \begin_inset Flex CharStyle:Code
15798 \begin_layout Plain Layout
15799 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15804 in the XFig template above: We can't use the absolute name because the
15806 \begin_inset Flex CharStyle:Code
15809 \begin_layout Plain Layout
15815 files needs the relative name in order to rewrite the file content.
15818 \begin_layout Section
15819 Security discussion
15820 \begin_inset CommandInset label
15822 name "sec:Security-discussion"
15829 \begin_layout Standard
15830 The external material feature interfaces with a lot of external programs
15831 and does so automatically, so we have to consider the security implications
15833 In particular, since you have the option of including your own filenames
15834 and/or parameter strings and those are expanded into a command, it seems
15835 that it would be possible to create a malicious document which executes
15836 arbitrary commands when a user views or prints the document.
15837 This is something we definitely want to avoid.
15840 \begin_layout Standard
15841 However, since the external program commands are specified in the template
15842 configuration file only, there are no security issues if LyX is properly
15843 configured with safe templates only.
15844 This is so because the external programs are invoked with the
15845 \begin_inset Flex CharStyle:Code
15848 \begin_layout Plain Layout
15854 -system call rather than the
15855 \begin_inset Flex CharStyle:Code
15858 \begin_layout Plain Layout
15864 system-call, so it's not possible to execute arbitrary commands from the
15865 filename or parameter section via the shell.
15868 \begin_layout Standard
15869 This also implies that you are restricted in what command strings you can
15870 use in the external material templates.
15871 In particular, pipes and redirection are not readily available.
15872 This has to be so if LyX should remain safe.
15873 If you want to use some of the shell features, you should write a safe
15874 script to do this in a controlled manner, and then invoke the script from
15875 the command string.
15879 \begin_layout Standard
15880 It is possible to design a template that interacts directly with the shell,
15881 but since this would allow a malicious user to execute arbitrary commands
15882 by writing clever filenames and/or parameters, we generally recommend that
15883 you only use safe scripts that work with the
15884 \begin_inset Flex CharStyle:Code
15887 \begin_layout Plain Layout
15893 system call in a controlled manner.
15894 Of course, for use in a controlled environment, it can be tempting to just
15895 fall back to use ordinary shell scripts.
15896 If you do so, be aware that you
15900 provide an easily exploitable security hole in your system.
15901 Of course it stands to reason that such unsafe templates will never be
15902 included in the standard LyX distribution, although we do encourage people
15903 to submit new templates in the open source tradition.
15904 But LyX as shipped from the official distribution channels will never have
15908 \begin_layout Standard
15909 Including external material provides a lot of power, and you have to be
15910 careful not to introduce security hazards with this power.
15911 A subtle error in a single line in an innocent looking script can open
15912 the door to huge security problems.
15913 So if you do not fully understand the issues, we recommend that you consult
15914 a knowledgeable security professional or the LyX development team if you
15915 have any questions about whether a given template is safe or not.
15916 And do this before you use it in an uncontrolled environment.