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 the User's Guide prints
10 % out as advertised. If you mess with this preamble,
11 % parts of the User's Guide may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
44 \use_default_options false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
67 \font_typewriter default
68 \font_default_family default
78 \pdf_title "LyX Configuration Manual"
79 \pdf_author "LyX Team"
80 \pdf_subject "LyX-documentation Customization"
81 \pdf_keywords "LyX, documentation, customization"
83 \pdf_bookmarksnumbered true
84 \pdf_bookmarksopen true
85 \pdf_bookmarksopenlevel 1
90 \pdf_pdfusetitle false
91 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
98 \paperorientation portrait
105 \paragraph_separation indent
107 \quotes_language english
110 \paperpagestyle headings
111 \tracking_changes true
112 \output_changes false
113 \author "Georg Baum,,,"
120 Customizing LyX: Features for the Advanced User
128 \begin_layout Plain Layout
130 If you have comments or error corrections, please send them to the LyX Documenta
132 \begin_inset CommandInset href
134 target "lyx-docs@lists.lyx.org"
141 \begin_inset Quotes eld
145 \begin_inset Quotes erd
148 in the subject header, and please cc the current maintainer of this file,
149 Richard Heck <rgheck@comcast.net>.
155 \begin_inset Newline newline
159 \begin_inset Newline newline
165 \begin_layout Standard
166 \begin_inset CommandInset toc
167 LatexCommand tableofcontents
174 \begin_layout Standard
175 \begin_inset Note Note
178 \begin_layout Plain Layout
179 Please use change tracking when modifying this document.
180 This makes it easier for our translators to recognize things that have
181 been changed, and it helps the maintainer keep up-to-date with what's been
190 \begin_layout Chapter
194 \begin_layout Standard
195 This manual covers the customization features present in LyX.
196 In it, we discuss issues like keyboard shortcuts, screen previewing options,
197 printer options, sending commands to LyX via the LyX Server, internationalizati
198 on, installing new LaTeX classes and LyX layouts, etc.
199 We can't possibly hope to touch on everything you can change—our developers
200 add new features faster than we can document them—but we will explain the
201 most common customizations and hopefully point you in the right direction
202 for some of the more obscure ones.
205 \begin_layout Standard
206 \begin_inset Branch OutDated
209 \begin_layout Standard
210 Information from previous versions of this document that now seems to be
211 outdated is contained in the OutDated branch of this document.
212 By default, this information will not appear in the LaTeX output.
220 \begin_layout Chapter
221 LyX configuration files
224 \begin_layout Standard
225 This chapter aims to help you to find your way through the LyX configuration
227 Before continuing to read this chapter, you should find out where your
228 LyX library and user directories are by using
229 \begin_inset Flex CharStyle:MenuItem
232 \begin_layout Plain Layout
233 Help\SpecialChar \menuseparator
244 The library directory is the place where LyX places its system-wide configurati
245 on files; the user directory is where you can place your modified versions.
246 We will call the former
247 \begin_inset Flex CharStyle:Code
250 \begin_layout Plain Layout
257 \begin_inset Flex CharStyle:MenuItem
260 \begin_layout Plain Layout
266 in the remainder of this document.
270 \begin_layout Section
272 \begin_inset Flex CharStyle:Code
275 \begin_layout Plain Layout
284 \begin_layout Standard
285 \begin_inset Flex CharStyle:Code
288 \begin_layout Plain Layout
294 and its sub-directories contain a number of files and that can be used
295 to customize LyX's behavior.
296 You can change many of these files from within LyX itself through the
297 \begin_inset Flex CharStyle:MenuItem
300 \begin_layout Plain Layout
301 Tools\SpecialChar \menuseparator
308 Most customization that you will want to do in LyX is possible through
310 However, many other inner aspects of LyX can be customized by modifying
312 \begin_inset Flex CharStyle:Code
315 \begin_layout Plain Layout
322 These files fall in different categories, described in the following subsection
326 \begin_layout Subsection
327 Automatically generated files
330 \begin_layout Standard
331 The files, which are to be found in
332 \begin_inset Flex CharStyle:MenuItem
335 \begin_layout Plain Layout
341 , are generated when you configure LyX.
342 They contain various default values that are guessed by inspection.
343 In general, it is not a good idea to modify them, since they might be overwritt
347 \begin_layout Labeling
348 \labelwidthstring 00.00.0000
349 \begin_inset Flex CharStyle:Code
352 \begin_layout Plain Layout
358 contains defaults for various commands.
361 \begin_layout Labeling
362 \labelwidthstring 00.00.0000
363 \begin_inset Flex CharStyle:Code
366 \begin_layout Plain Layout
372 contains the list of packages that have been recognized by LyX.
373 It is currently unused by the LyX program itself, but the information extracted
374 , and more, is made available with
375 \begin_inset Flex CharStyle:MenuItem
378 \begin_layout Plain Layout
379 Help\SpecialChar \menuseparator
392 \begin_layout Labeling
393 \labelwidthstring 00.00.0000
394 \begin_inset Flex CharStyle:Code
397 \begin_layout Plain Layout
403 the list of text classes that have been found in your
404 \begin_inset Flex CharStyle:Code
407 \begin_layout Plain Layout
413 directories, along with the associated LaTeX document class and their descripti
417 \begin_layout Labeling
418 \labelwidthstring 00.00.0000
419 \begin_inset Flex CharStyle:Code
422 \begin_layout Plain Layout
428 the list of layout modules found in your
429 \begin_inset Flex CharStyle:Code
432 \begin_layout Plain Layout
441 \begin_layout Labeling
442 \labelwidthstring 00.00.0000
443 \begin_inset Flex CharStyle:Code
446 \begin_layout Plain Layout
452 lists of various sorts of LaTeX-related files found on your system
455 \begin_layout Labeling
456 \labelwidthstring 00.00.0000
457 \begin_inset Flex CharStyle:Code
460 \begin_layout Plain Layout
466 is automatically generated during configuration from the file
467 \begin_inset Flex CharStyle:Code
470 \begin_layout Plain Layout
477 It contains information on your LaTeX configuration.
480 \begin_layout Subsection
484 \begin_layout Standard
485 These directories are duplicated between
486 \begin_inset Flex CharStyle:Code
489 \begin_layout Plain Layout
496 \begin_inset Flex CharStyle:Code
499 \begin_layout Plain Layout
506 If a particular files exists in both places, the one in
507 \begin_inset Flex CharStyle:Code
510 \begin_layout Plain Layout
519 \begin_layout Labeling
520 \labelwidthstring 00.00.0000
521 \begin_inset Flex CharStyle:Code
524 \begin_layout Plain Layout
530 this directory contains files with the extension
531 \begin_inset Flex CharStyle:Code
534 \begin_layout Plain Layout
540 that define the keybindings used in LyX.
541 If there exists an internationalized version of the bind file named
542 \begin_inset Flex CharStyle:Code
545 \begin_layout Plain Layout
551 , that will be used first.
554 \begin_layout Labeling
555 \labelwidthstring 00.00.0000
556 \begin_inset Flex CharStyle:Code
559 \begin_layout Plain Layout
565 contains graphics files that can be included in documents.
569 \begin_layout Labeling
570 \labelwidthstring 00.00.0000
571 \begin_inset Flex CharStyle:Code
574 \begin_layout Plain Layout
580 contains LyX documentation files (including the one you are currently reading).
582 \begin_inset Flex CharStyle:Code
585 \begin_layout Plain Layout
591 deserves special attention, as noted above.
592 The internationalized help docs are in subdirectories
593 \begin_inset Flex CharStyle:Code
596 \begin_layout Plain Layout
603 \begin_inset Quotes eld
607 \begin_inset Quotes erd
610 is the ISO language code.
616 \begin_inset CommandInset ref
618 reference "chap:i18n"
625 \begin_layout Labeling
626 \labelwidthstring 00.00.0000
627 \begin_inset Flex CharStyle:Code
630 \begin_layout Plain Layout
636 contains example files that explain how to use some features.
637 In the file browser, press the
638 \begin_inset Flex CharStyle:MenuItem
641 \begin_layout Plain Layout
650 \begin_layout Labeling
651 \labelwidthstring 00.00.0000
652 \begin_inset Flex CharStyle:Code
655 \begin_layout Plain Layout
661 contains image files that are used by the
662 \begin_inset Flex CharStyle:MenuItem
665 \begin_layout Plain Layout
672 In addition, it also contains the individual icons used in the toolbar
673 and the banners that can be shown when LyX is launched.
676 \begin_layout Labeling
677 \labelwidthstring 00.00.0000
678 \begin_inset Flex CharStyle:Code
681 \begin_layout Plain Layout
687 contains keyboard keymapping files.
693 \begin_inset CommandInset ref
695 reference "sec:keymap"
702 \begin_layout Labeling
703 \labelwidthstring 00.00.0000
704 \begin_inset Flex CharStyle:Code
707 \begin_layout Plain Layout
713 contains the text class and module files described in Chapter
718 \begin_inset CommandInset ref
720 reference "chap:textclass"
727 \begin_layout Labeling
728 \labelwidthstring 00.00.0000
729 \begin_inset Flex CharStyle:Code
732 \begin_layout Plain Layout
739 \begin_inset Flex CharStyle:Code
742 \begin_layout Plain Layout
748 Python scripts used to convert between LyX versions.
749 These can be run from the command line if, say, you want to batch-convert
753 \begin_layout Labeling
754 \labelwidthstring 00.00.0000
755 \begin_inset Flex CharStyle:Code
758 \begin_layout Plain Layout
764 contains some files that demonstrate the capabilities of the
765 \begin_inset Flex CharStyle:MenuItem
768 \begin_layout Plain Layout
779 Also contains some scripts used by LyX itself.
782 \begin_layout Labeling
783 \labelwidthstring 00.00.0000
784 \begin_inset Flex CharStyle:Code
787 \begin_layout Plain Layout
793 contains the standard LyX template files described in Chapter
798 \begin_inset CommandInset ref
800 reference "sec:templates"
807 \begin_layout Labeling
808 \labelwidthstring 00.00.0000
809 \begin_inset Flex CharStyle:Code
812 \begin_layout Plain Layout
818 contains files with the extension
819 \begin_inset Flex CharStyle:Code
822 \begin_layout Plain Layout
828 that define the user interface to LyX.
829 That is, the files define which items appear in which menus and the items
830 appearing on the toolbar.
833 \begin_layout Subsection
834 Files you don't want to modify
837 \begin_layout Standard
838 These files are used internally by LyX and you generally do not need to
839 modify them unless you are a developer.
842 \begin_layout Labeling
843 \labelwidthstring 00.00.0000
844 \begin_inset Flex CharStyle:Code
847 \begin_layout Plain Layout
853 this file contains the list of LyX developers.
854 The contents are displayed with the menu entry
855 \begin_inset Flex CharStyle:MenuItem
858 \begin_layout Plain Layout
859 Help\SpecialChar \menuseparator
872 \begin_layout Labeling
873 \labelwidthstring 00.00.0000
874 \begin_inset Flex CharStyle:Code
877 \begin_layout Plain Layout
883 this is a LaTeX script used during the configuration process.
887 \begin_layout Labeling
888 \labelwidthstring 00.00.0000
889 \begin_inset Flex CharStyle:Code
892 \begin_layout Plain Layout
898 this is the script that is used to re-configure LyX.
899 It creates configuration files in the directory it was run from.
902 \begin_layout Subsection
903 Other files needing a line or two...
906 \begin_layout Labeling
907 \labelwidthstring 00.00.0000
908 \begin_inset Flex CharStyle:Code
911 \begin_layout Plain Layout
917 this contains tables describing how different character encodings can be
921 \begin_layout Labeling
922 \labelwidthstring 00.00.0000
923 \begin_inset Flex CharStyle:Code
926 \begin_layout Plain Layout
932 this file contains the templates available to the new
933 \begin_inset Flex CharStyle:MenuItem
936 \begin_layout Plain Layout
949 \begin_layout Labeling
950 \labelwidthstring 00.00.0000
951 \begin_inset Flex CharStyle:Code
954 \begin_layout Plain Layout
960 this file contains a list of all the languages currently supported by LyX.
963 \begin_layout Section
964 Your local configuration directory
967 \begin_layout Standard
968 Even if you are using LyX as an unprivileged user, you might want to change
969 LyX configuration for your own use.
971 \begin_inset Flex CharStyle:Code
974 \begin_layout Plain Layout
980 directory contains all your personal configuration files.
981 This is the directory described as
982 \begin_inset Quotes eld
986 \begin_inset Quotes erd
990 \begin_inset Flex CharStyle:MenuItem
993 \begin_layout Plain Layout
994 Help\SpecialChar \menuseparator
1005 This directory is used as a mirror of
1006 \begin_inset Flex CharStyle:Code
1009 \begin_layout Plain Layout
1015 , which means that every file in
1016 \begin_inset Flex CharStyle:Code
1019 \begin_layout Plain Layout
1025 is a replacement for the corresponding file in
1026 \begin_inset Flex CharStyle:Code
1029 \begin_layout Plain Layout
1036 Any configuration file described in the above sections can be placed either
1037 in the system-wide directory, in which case it will affect all users, or
1038 in your local directory for your own use.
1041 \begin_layout Standard
1042 To make things clearer, let's provide a few examples:
1045 \begin_layout Itemize
1046 The preferences set in the
1047 \begin_inset Flex CharStyle:MenuItem
1050 \begin_layout Plain Layout
1051 Tools\SpecialChar \menuseparator
1057 dialog are saved to a file
1058 \begin_inset Flex CharStyle:Code
1061 \begin_layout Plain Layout
1068 \begin_inset Flex CharStyle:Code
1071 \begin_layout Plain Layout
1080 \begin_layout Itemize
1081 When you reconfigure using
1082 \begin_inset Flex CharStyle:MenuItem
1085 \begin_layout Plain Layout
1086 Tools\SpecialChar \menuseparator
1093 \begin_inset Flex CharStyle:Code
1096 \begin_layout Plain Layout
1102 script, and the resulting files are written in your local configuration
1104 This means that any additional text class file that you might have added
1106 \begin_inset Flex CharStyle:Code
1109 \begin_layout Plain Layout
1115 will be added to the list of classes in the
1116 \begin_inset Flex CharStyle:MenuItem
1119 \begin_layout Plain Layout
1120 Document\SpecialChar \menuseparator
1129 \begin_layout Itemize
1130 If you get some updated documentation from LyX ftp site and cannot install
1131 it because you do not have sysadmin rights on your system, you can just
1133 \begin_inset Flex CharStyle:Code
1136 \begin_layout Plain Layout
1142 and the items in the
1143 \begin_inset Flex CharStyle:MenuItem
1146 \begin_layout Plain Layout
1152 menu will open them!
1155 \begin_layout Section
1156 Running LyX with multiple configurations
1159 \begin_layout Standard
1160 The configuration freedom of the local configuration directory may not suffice
1161 if you want to have more than one configuration at your disposal.
1162 For example, you may want to be use different key bindings or printer settings
1164 You can achieve this by having several such directories.
1165 You then specify which directory to use at run-time.
1168 \begin_layout Standard
1169 Invoking LyX with the command line switch
1170 \begin_inset Flex CharStyle:Code
1173 \begin_layout Plain Layout
1183 instructs the program to read the configuration from that directory, and
1184 not from the default directory.
1185 (You can determine the default directory by running LyX without the
1186 \begin_inset Flex CharStyle:Code
1189 \begin_layout Plain Layout
1195 switch.) If the specified directory does not exist, LyX offers to create
1196 it for you, just like it does for the default directory on the first time
1197 you run the program.
1198 You can modify the configuration options in this additional user directory
1199 exactly as you would for the default directory.
1200 These directories are completely independent (but read on).
1201 Note that setting the environment variable
1202 \begin_inset Flex CharStyle:Code
1205 \begin_layout Plain Layout
1211 to some value has exactly the same effect.
1214 \begin_layout Standard
1215 Having several configurations also requires more maintenance: if you want
1216 to add a new layout to
1217 \begin_inset Flex CharStyle:Code
1220 \begin_layout Plain Layout
1226 which you want available from all your configurations, you must add it
1227 to each directory separately.
1228 You can avoid this with the following trick: after LyX creates the additional
1229 directory, most of the subdirectories (see above) are empty.
1230 If you want the new configuration to mirror an existing one, replace the
1231 empty subdirectory with a symbolic link to the matching subdirectory in
1232 the existing configuration.
1234 \begin_inset Flex CharStyle:Code
1237 \begin_layout Plain Layout
1243 subdirectory, however, since it contains a file written by the configuration
1244 script (also accessible through
1245 \begin_inset Flex CharStyle:MenuItem
1248 \begin_layout Plain Layout
1249 Tools\SpecialChar \menuseparator
1255 ) which is configuration-specific.
1258 \begin_layout Chapter
1259 The Preferences dialog
1262 \begin_layout Standard
1263 All options of the preferences dialog are described in the Appendix
1265 The Preferences Dialog
1272 For some options you might find here more details.
1275 \begin_layout Section
1276 Using the dialog for the first time
1279 \begin_layout Standard
1281 \begin_inset Flex CharStyle:Code
1284 \begin_layout Plain Layout
1290 file will contain only changes that you have made to the default behavior,
1291 some of which is hard-coded into LyX and some of which is contained in
1293 \begin_inset Flex CharStyle:Code
1296 \begin_layout Plain Layout
1297 LyXDir/lyxrc.defaults
1303 Note that in both files lines beginning with a
1304 \begin_inset Quotes eld
1308 \begin_inset Quotes erd
1311 are just comments and are not interpreted.
1312 However, only system administrators should edit
1313 \begin_inset Flex CharStyle:Code
1316 \begin_layout Plain Layout
1317 LyXDir/lyxrc.defaults
1323 Users should use the
1324 \begin_inset Flex CharStyle:MenuItem
1327 \begin_layout Plain Layout
1328 Tools\SpecialChar \menuseparator
1334 dialog to create and modify their own
1335 \begin_inset Flex CharStyle:Code
1338 \begin_layout Plain Layout
1347 \begin_layout Standard
1349 \begin_inset Flex CharStyle:MenuItem
1352 \begin_layout Plain Layout
1353 Tools\SpecialChar \menuseparator
1359 dialog will be largely self-explanatory.
1360 Most things in the dialog have associated `tool tips': hover your mouse
1361 pointer over something for more information.
1362 Before we highlight a few of the more important commands below, however,
1363 a word of warning: Applying some of your changes (e.
1364 \begin_inset space \thinspace{}
1368 \begin_inset space \space{}
1371 screen fonts) will have an instant effect.
1373 \begin_inset space \thinspace{}
1377 \begin_inset space \space{}
1380 changing the bind file) will not.
1381 If nothing appears to have changed, just
1382 \begin_inset Flex CharStyle:MenuItem
1385 \begin_layout Plain Layout
1391 the changes and restart LyX.
1394 \begin_layout Section
1398 \begin_layout Standard
1399 LyX has a powerful mechanism to convert to and from any file format using
1404 \begin_layout Subsection
1405 \begin_inset CommandInset label
1414 \begin_layout Standard
1415 The first step is to define your file formats if they are not already defined.
1417 \begin_inset Flex CharStyle:MenuItem
1420 \begin_layout Plain Layout
1421 Tools\SpecialChar \menuseparator
1429 \begin_inset Flex CharStyle:MenuItem
1432 \begin_layout Plain Layout
1433 File Handling\SpecialChar \menuseparator
1440 \begin_inset Flex CharStyle:MenuItem
1443 \begin_layout Plain Layout
1444 New\SpecialChar \ldots{}
1450 button to define your new format.
1452 \begin_inset Flex CharStyle:MenuItem
1455 \begin_layout Plain Layout
1461 field contains the named used to identify the format in the GUI.
1463 \begin_inset Flex CharStyle:MenuItem
1466 \begin_layout Plain Layout
1472 is used to identify the format internally.
1473 You will also need to enter a file extension.
1474 These are all required.
1476 \begin_inset Flex CharStyle:MenuItem
1479 \begin_layout Plain Layout
1485 field is used to provide a keyboard shortcut on the menus.
1486 (For example, pressing
1487 \begin_inset Flex CharStyle:MenuItem
1490 \begin_layout Plain Layout
1497 \begin_inset Flex CharStyle:MenuItem
1500 \begin_layout Plain Layout
1501 View\SpecialChar \menuseparator
1510 \begin_layout Standard
1512 \begin_inset Flex CharStyle:MenuItem
1515 \begin_layout Plain Layout
1522 \begin_inset Flex CharStyle:MenuItem
1525 \begin_layout Plain Layout
1532 For example, you might want to use
1533 \begin_inset Flex CharStyle:MenuItem
1536 \begin_layout Plain Layout
1542 to view PostScript files.
1543 You can enter the command needed to start the program in the corresponding
1545 In defining this command, you can use the four variables listed in the
1547 The viewer is launched when you view an image in LyX or use the
1548 \begin_inset Flex CharStyle:MenuItem
1551 \begin_layout Plain Layout
1558 The editor is for example launched when you press the
1559 \begin_inset Flex CharStyle:MenuItem
1562 \begin_layout Plain Layout
1569 \begin_inset Flex CharStyle:MenuItem
1572 \begin_layout Plain Layout
1579 \begin_inset Flex CharStyle:MenuItem
1582 \begin_layout Plain Layout
1591 \begin_layout Standard
1593 \begin_inset Flex CharStyle:MenuItem
1596 \begin_layout Plain Layout
1602 option tells LyX that a format is suitable for document export.
1603 If this is is set and if a suitable conversion route exists (see
1604 \begin_inset CommandInset ref
1606 reference "sub:Converters"
1610 ), the format will appear in the
1611 \begin_inset Flex CharStyle:MenuItem
1614 \begin_layout Plain Layout
1615 File\SpecialChar \menuseparator
1622 The format will also appear in the
1623 \begin_inset Flex CharStyle:MenuItem
1626 \begin_layout Plain Layout
1632 menu if a viewer is specified for the format.
1633 Pure image formats, such as
1634 \begin_inset Flex CharStyle:Code
1637 \begin_layout Plain Layout
1643 , should not use this option.
1644 Formats that can both represent vector graphics and documents like
1645 \begin_inset Flex CharStyle:Code
1648 \begin_layout Plain Layout
1657 \begin_layout Standard
1659 \begin_inset Flex CharStyle:MenuItem
1662 \begin_layout Plain Layout
1663 Vector graphics format
1668 tells LyX that a format can contain vector graphics.
1669 This information is used to determine the target format of included graphics
1671 \begin_inset Flex CharStyle:MenuItem
1674 \begin_layout Plain Layout
1681 Included graphics may need to be converted to either
1682 \begin_inset Flex CharStyle:MenuItem
1685 \begin_layout Plain Layout
1692 \begin_inset Flex CharStyle:MenuItem
1695 \begin_layout Plain Layout
1702 \begin_inset Flex CharStyle:MenuItem
1705 \begin_layout Plain Layout
1712 \begin_inset Flex CharStyle:MenuItem
1715 \begin_layout Plain Layout
1721 cannot handle other image formats.
1722 If an included graphic is not already in
1723 \begin_inset Flex CharStyle:MenuItem
1726 \begin_layout Plain Layout
1733 \begin_inset Flex CharStyle:MenuItem
1736 \begin_layout Plain Layout
1743 \begin_inset Flex CharStyle:MenuItem
1746 \begin_layout Plain Layout
1752 format, it is converted to
1753 \begin_inset Flex CharStyle:MenuItem
1756 \begin_layout Plain Layout
1762 if the vector format option is set, and otherwise to
1763 \begin_inset Flex CharStyle:MenuItem
1766 \begin_layout Plain Layout
1775 \begin_layout Subsection
1779 \begin_layout Standard
1780 Since all conversions from one format to another take place in LyX's temporary
1781 directory, it is sometimes necessary to modify a file before copying it
1782 to the temporary directory in order that the conversion may be performed.
1786 \begin_layout Plain Layout
1787 For example, the file may refer to other files—images, for example—using
1788 relative file names, and these may become invalid when the file is copied
1789 to the temporary directory.
1794 This is done by a Copier: It copies a file to (or from) the temporary directory
1795 and may modify it in the process.
1798 \begin_layout Standard
1799 The definitions of the copiers may use four variables:
1802 \begin_layout Labeling
1803 \labelwidthstring 00.00.0000
1804 \begin_inset Flex CharStyle:Code
1807 \begin_layout Plain Layout
1813 The LyX system directory (e.
1814 \begin_inset space \thinspace{}
1818 \begin_inset space \space{}
1822 \begin_inset Flex CharStyle:MenuItem
1825 \begin_layout Plain Layout
1834 \begin_layout Labeling
1835 \labelwidthstring 00.00.0000
1836 \begin_inset Flex CharStyle:Code
1839 \begin_layout Plain Layout
1848 \begin_layout Labeling
1849 \labelwidthstring 00.00.0000
1850 \begin_inset Flex CharStyle:Code
1853 \begin_layout Plain Layout
1862 \begin_layout Labeling
1863 \labelwidthstring 00.00.0000
1864 \begin_inset Flex CharStyle:Code
1867 \begin_layout Plain Layout
1876 \begin_layout Standard
1877 The latter should be the filename as it would be used in a LaTeX's
1884 It is relevant only when exporting files suitable for such inclusion.
1887 \begin_layout Standard
1888 Copiers can be used to do almost anything with output files.
1889 For example, suppose you want generated pdf files to be copied to a special
1891 \begin_inset Flex CharStyle:Code
1894 \begin_layout Plain Layout
1901 Then you could write a shell script such as this one:
1904 \begin_layout Standard
1905 \begin_inset listings
1909 \begin_layout Plain Layout
1914 \begin_layout Plain Layout
1919 \begin_layout Plain Layout
1921 TOFILE=`basename $2`
1924 \begin_layout Plain Layout
1926 cp $FROMFILE /home/you/pdf/$TOFILE
1931 Save that in your local LyX directory—say,
1932 \begin_inset Flex CharStyle:Code
1935 \begin_layout Plain Layout
1936 /home/you/.lyx/scripts/pdfcopier.sh
1941 —and make it executable, if you need to do so on your platform.
1943 \begin_inset Flex CharStyle:MenuItem
1946 \begin_layout Plain Layout
1947 Tools\SpecialChar \menuseparator
1953 dialog, select under
1954 \begin_inset Flex CharStyle:MenuItem
1957 \begin_layout Plain Layout
1958 File Handling\SpecialChar \menuseparator
1965 \begin_inset Flex CharStyle:MenuItem
1968 \begin_layout Plain Layout
1974 format—or one of the other pdf formats—and enter
1975 \begin_inset Flex CharStyle:Code
1978 \begin_layout Plain Layout
1979 pdfcopier.sh $$i $$o
1985 \begin_inset Flex CharStyle:MenuItem
1988 \begin_layout Plain Layout
1998 \begin_layout Standard
1999 Copiers are used by LyX in various of its own conversions.
2000 For example, if appropriate programs are found, LyX will automatically
2001 install copiers for the
2002 \begin_inset Flex CharStyle:MenuItem
2005 \begin_layout Plain Layout
2012 \begin_inset Flex CharStyle:MenuItem
2015 \begin_layout Plain Layout
2017 \begin_inset space ~
2026 When these formats are exported, the copier sees that not just the main
2027 HTML file but various associated files (style files, images, etc.) are also
2029 All these files are written to a subdirectory of the directory in which
2030 the original LyX file was found.
2034 \begin_layout Plain Layout
2035 This copier can be customized.
2037 \begin_inset Quotes eld
2041 \begin_inset Quotes erd
2044 argument takes a comma-separated list of extensions to be copied; if it
2045 is omitted, all files will be copied.
2047 \begin_inset Quotes eld
2051 \begin_inset Quotes erd
2054 argument determines the extension added to the generated directory.
2056 \begin_inset Quotes eld
2060 \begin_inset Flex CharStyle:MenuItem
2063 \begin_layout Plain Layout
2070 \begin_inset Quotes erd
2073 , so HTML generated from
2074 \begin_inset Flex CharStyle:MenuItem
2077 \begin_layout Plain Layout
2078 /path/to/filename.lyx
2084 \begin_inset Flex CharStyle:MenuItem
2087 \begin_layout Plain Layout
2088 /path/to/filename.html.LyXconv
2102 \begin_layout Subsection
2103 \begin_inset CommandInset label
2105 name "sub:Converters"
2112 \begin_layout Standard
2113 You can define your own Converters to convert files between different formats.
2115 \begin_inset Flex CharStyle:MenuItem
2118 \begin_layout Plain Layout
2119 Tools\SpecialChar \menuseparator
2120 Preferences\SpecialChar \menuseparator
2121 File Handling\SpecialChar \menuseparator
2130 \begin_layout Standard
2131 To define a new converter, select the
2132 \begin_inset Flex CharStyle:MenuItem
2135 \begin_layout Plain Layout
2137 \begin_inset space ~
2146 \begin_inset Flex CharStyle:MenuItem
2149 \begin_layout Plain Layout
2151 \begin_inset space ~
2159 from the drop-down lists, enter the command needed for the conversion,
2161 \begin_inset Flex CharStyle:MenuItem
2164 \begin_layout Plain Layout
2171 Several variables can be used in the definition of converters:
2174 \begin_layout Labeling
2175 \labelwidthstring 00.00.0000
2176 \begin_inset Flex CharStyle:Code
2179 \begin_layout Plain Layout
2185 The LyX system directory
2188 \begin_layout Labeling
2189 \labelwidthstring 00.00.0000
2190 \begin_inset Flex CharStyle:Code
2193 \begin_layout Plain Layout
2202 \begin_layout Labeling
2203 \labelwidthstring 00.00.0000
2204 \begin_inset Flex CharStyle:Code
2207 \begin_layout Plain Layout
2216 \begin_layout Labeling
2217 \labelwidthstring 00.00.0000
2218 \begin_inset Flex CharStyle:Code
2221 \begin_layout Plain Layout
2227 The base filename of the input file (i.
2228 \begin_inset space \thinspace{}
2231 g., without the extension)
2234 \begin_layout Labeling
2235 \labelwidthstring 00.00.0000
2236 \begin_inset Flex CharStyle:Code
2239 \begin_layout Plain Layout
2245 The path to the input file
2248 \begin_layout Labeling
2249 \labelwidthstring 00.00.0000
2250 \begin_inset Flex CharStyle:Code
2253 \begin_layout Plain Layout
2259 The path to the original input file (this is different from $$p when chain
2260 of converters is called).
2263 \begin_layout Standard
2265 \begin_inset Flex CharStyle:MenuItem
2268 \begin_layout Plain Layout
2270 \begin_inset space ~
2278 field you can enter the following flags, separated by commas:
2281 \begin_layout Labeling
2282 \labelwidthstring 00.00.0000
2283 \begin_inset Flex CharStyle:Code
2286 \begin_layout Plain Layout
2292 This converter runs some form of LaTeX.
2293 This will make LyX's LaTeX error logs available.
2296 \begin_layout Labeling
2297 \labelwidthstring 00.00.0000
2298 \begin_inset Flex CharStyle:Code
2301 \begin_layout Plain Layout
2308 \begin_inset Flex CharStyle:MenuItem
2311 \begin_layout Plain Layout
2317 file for the conversion.
2320 \begin_layout Labeling
2321 \labelwidthstring 00.00.0000
2322 \begin_inset Flex CharStyle:Code
2325 \begin_layout Plain Layout
2334 \begin_layout Standard
2335 The following three flags are not really flags at all because they take
2337 \begin_inset Flex CharStyle:MenuItem
2340 \begin_layout Plain Layout
2342 \begin_inset space ~
2346 \begin_inset space ~
2357 \begin_layout Labeling
2358 \labelwidthstring 00.00.0000
2359 \begin_inset Flex CharStyle:Code
2362 \begin_layout Plain Layout
2368 If set, the converter's standard error will be redirected to a file
2369 \begin_inset Flex CharStyle:Code
2372 \begin_layout Plain Layout
2378 , and the script given as argument will be run as:
2379 \begin_inset Flex CharStyle:Code
2382 \begin_layout Plain Layout
2383 script <infile.out >infile.log
2389 The argument may contain
2390 \begin_inset Flex CharStyle:Code
2393 \begin_layout Plain Layout
2402 \begin_layout Labeling
2403 \labelwidthstring 00.00.0000
2404 \begin_inset Flex CharStyle:Code
2407 \begin_layout Plain Layout
2413 The name of the directory in which the converter will dump the generated
2415 LyX will not create this directory, and it does not copy anything into
2416 it, though it will copy this directory to the destination.
2417 The argument may contain
2418 \begin_inset Flex CharStyle:Code
2421 \begin_layout Plain Layout
2427 , which will be replaced by the base name of the input and output files,
2428 respectively, when the directory is copied.
2429 \begin_inset Newline newline
2432 Note that resultdir and usetempdir make no sense together.
2433 The latter will be ignored if the former is given.
2436 \begin_layout Labeling
2437 \labelwidthstring 00.00.0000
2438 \begin_inset Flex CharStyle:Code
2441 \begin_layout Plain Layout
2447 Determines the output file name and may, contain
2448 \begin_inset Flex CharStyle:Code
2451 \begin_layout Plain Layout
2458 Sensible only with resultdir and optional even then; if not given, it defaults
2462 \begin_layout Standard
2463 None of these last three are presently used in any of the converters that
2464 are installed with LyX.
2468 \begin_layout Standard
2469 You do not have to define converters between all the formats between which
2470 you want to convert.
2471 For example, you will note that there is no `LyX to PostScript' converter,
2472 but LyX will export PostScript.
2473 It does so by first creating a LaTeX file (no converter needs to be defined
2474 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2475 and finally converting the resulting DVI file to PostScript.
2476 LyX finds such `chains' of converters automatically, and it will always
2477 choose the shortest possible chain.
2478 You can, though, still define multiple conversion methods between file
2480 For example, the standard LyX configuration provides three ways to convert
2481 LaTeX to PDF: Directly, using
2482 \begin_inset Flex CharStyle:MenuItem
2485 \begin_layout Plain Layout
2491 ; via (DVI and) PostScript, using
2492 \begin_inset Flex CharStyle:MenuItem
2495 \begin_layout Plain Layout
2502 \begin_inset Flex CharStyle:MenuItem
2505 \begin_layout Plain Layout
2512 To define such alternate chains, you must define multiple target `file
2513 formats', as described in section
2514 \begin_inset CommandInset ref
2516 reference "sub:Formats"
2521 For example, in the standard configuration, the formats named
2522 \begin_inset Flex CharStyle:MenuItem
2525 \begin_layout Plain Layout
2532 \begin_inset Flex CharStyle:MenuItem
2535 \begin_layout Plain Layout
2542 \begin_inset Flex CharStyle:MenuItem
2545 \begin_layout Plain Layout
2551 are defined, all of which share the extension
2552 \begin_inset Flex CharStyle:MenuItem
2555 \begin_layout Plain Layout
2561 , and which correspond to the conversion methods just mentioned.
2564 \begin_layout Chapter
2565 Internationalizing LyX
2566 \begin_inset CommandInset label
2575 \begin_layout Standard
2576 LyX supports using a translated interface.
2577 Last time we checked, LyX provided text in thirty languages.
2578 The language of choice is called your
2583 (For further reading on locale settings, see also the documentation for
2584 locale that comes with your operating system.
2585 For Linux, the manual page for
2586 \begin_inset Flex CharStyle:Code
2589 \begin_layout Plain Layout
2595 could be a good place to start).
2598 \begin_layout Standard
2599 Notice that these translations will work, but do contain a few flaws.
2600 In particular, all dialogs have been designed with the English text in
2601 mind, which means that some of the translated text will be too large to
2602 fit within the space allocated.
2603 This is only a display problem and will not cause any harm.
2604 Also, you will find that some of the translations do not define shortcut
2605 keys for everything.
2606 Sometimes, there are simply not enough free letters to do it.
2607 Other times, the translator just hasn't got around to doing it yet.
2608 Our localization team, which you may wish to join,
2612 \begin_layout Plain Layout
2613 If you are a fluent speaker of a language other than English, joining these
2614 teams is a great way to give back to the LyX community!
2619 will of course try to fix these shortcomings in future versions of LyX.
2622 \begin_layout Section
2626 \begin_layout Subsection
2627 Translating the graphical user interface (text messages).
2630 \begin_layout Standard
2632 \begin_inset Flex CharStyle:Code
2635 \begin_layout Plain Layout
2641 library to handle the internationalization of the interface.
2642 To have LyX speak your favorite language in all menus and dialogs, you
2644 \begin_inset Flex CharStyle:Code
2647 \begin_layout Plain Layout
2653 -file for that language.
2654 When this is available, you'll have to generate a
2655 \begin_inset Flex CharStyle:Code
2658 \begin_layout Plain Layout
2664 -file from it and install the
2665 \begin_inset Flex CharStyle:Code
2668 \begin_layout Plain Layout
2675 The process of doing all of this is explained in the documentation for
2677 \begin_inset Flex CharStyle:Code
2680 \begin_layout Plain Layout
2687 It is possible to do this just for yourself, but if you're going to do
2688 it, you might as well share the results of your labors with the rest of
2690 Send a message to the LyX developers' list for more information about how
2694 \begin_layout Standard
2695 In short, this is what you should do (xx denotes the language code):
2698 \begin_layout Itemize
2699 Check out the LyX source code.
2701 \begin_inset CommandInset href
2703 name "information on the web"
2704 target "http://www.lyx.org/devel/cvs.php"
2711 \begin_layout Itemize
2713 \begin_inset Flex CharStyle:Code
2716 \begin_layout Plain Layout
2722 to the folder of the
2723 \begin_inset Flex CharStyle:Code
2726 \begin_layout Plain Layout
2734 \begin_inset Flex CharStyle:Code
2737 \begin_layout Plain Layout
2745 \begin_inset Flex CharStyle:Code
2748 \begin_layout Plain Layout
2754 doesn't exist anywhere, it can be remade with the console command
2755 \begin_inset Flex CharStyle:Code
2758 \begin_layout Plain Layout
2764 in that directory, or you can use an existing po-file for some other language
2768 \begin_layout Itemize
2770 \begin_inset Flex CharStyle:Code
2773 \begin_layout Plain Layout
2783 \begin_layout Plain Layout
2784 This is just a text file, so it can be edited in any text editor.
2785 But there are also specialized programs that support such editing, such
2790 (for all platforms) or
2799 contains a `mode' for editing
2800 \begin_inset Flex CharStyle:Code
2803 \begin_layout Plain Layout
2814 For some menu- and widget-labels, there are also shortcut keys that should
2816 Those keys are marked after a `|', and should be translated according to
2817 the words and phrases of the language.
2818 You should also fill also out the information at the beginning of the new
2820 \begin_inset Flex CharStyle:Code
2823 \begin_layout Plain Layout
2829 -file with your email-address, etc., so people know where to reach you with
2830 suggestions and entertaining flames.
2833 \begin_layout Standard
2834 If you are just doing this on your own, then:
2837 \begin_layout Itemize
2839 \begin_inset Flex CharStyle:Code
2842 \begin_layout Plain Layout
2849 This can be done with
2850 \begin_inset Flex CharStyle:Code
2853 \begin_layout Plain Layout
2854 msgfmt -o xx.mo < xx.po
2862 \begin_layout Itemize
2864 \begin_inset Flex CharStyle:Code
2867 \begin_layout Plain Layout
2873 -file to your locale-tree, at the correct directory for application messages
2878 xx, and under the name
2879 \begin_inset Flex CharStyle:Code
2882 \begin_layout Plain Layout
2889 \begin_inset space \thinspace{}
2893 \begin_inset space \space{}
2897 \begin_inset Flex CharStyle:Code
2900 \begin_layout Plain Layout
2901 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2911 \begin_layout Standard
2912 As said, however, it would be best if the new
2913 \begin_inset Flex CharStyle:Code
2916 \begin_layout Plain Layout
2922 -file could be added to the LyX distribution, so others can use it.
2923 Adding it involves making additional changes to LyX.
2924 So send an email to the developers' mailing list if you're interested in
2928 \begin_layout Subsubsection
2932 \begin_layout Standard
2933 Sometimes it turns out that one English message needs to be translated into
2934 different messages in the target language.
2935 One example is the message
2936 \begin_inset Flex CharStyle:Code
2939 \begin_layout Plain Layout
2945 which has the German translation
2953 , depending upon exactly what the English
2954 \begin_inset Quotes eld
2958 \begin_inset Quotes erd
2963 \begin_inset Flex CharStyle:Code
2966 \begin_layout Plain Layout
2972 does not handle such ambiguous translations.
2973 Therefore you have to add some context information to the message: Instead
2975 \begin_inset Flex CharStyle:Code
2978 \begin_layout Plain Layout
2985 \begin_inset Flex CharStyle:Code
2988 \begin_layout Plain Layout
2989 To[[as in 'From format x to format y']]
2995 \begin_inset Flex CharStyle:Code
2998 \begin_layout Plain Layout
2999 To[[as in 'From page x to page y']].
3004 Now the two occurrences of
3005 \begin_inset Flex CharStyle:Code
3008 \begin_layout Plain Layout
3015 \begin_inset Flex CharStyle:Code
3018 \begin_layout Plain Layout
3024 and can be translated correctly to
3035 \begin_layout Standard
3036 Of course the context information needs to be stripped off the original
3037 message when no translation is used.
3038 Therefore you have to put it in double square brackets at the end of the
3039 message (see the example above).
3040 The translation mechanism of LyX ensures that everything in double square
3041 brackets at the end of messages is removed before displaying the message.
3044 \begin_layout Subsection
3045 Translating the documentation.
3048 \begin_layout Standard
3049 The online documentation (in the
3050 \begin_inset Flex CharStyle:MenuItem
3053 \begin_layout Plain Layout
3059 -menu) can (and should!) be translated.
3060 If there are translated versions of the documentation available
3064 \begin_layout Plain Layout
3065 As of March 2008, at least some of the documents have been translated into
3066 fourteen languages, with the Tutorial available in a few more.
3071 and the locale is set accordingly, these will be used automagically by
3073 LyX looks for translated versions as
3074 \begin_inset Flex CharStyle:Code
3077 \begin_layout Plain Layout
3078 LyXDir/doc/xx/DocName.lyx
3084 \begin_inset Flex CharStyle:Code
3087 \begin_layout Plain Layout
3093 is the code for the language currently in use.
3094 If there are no translated documents, the default English versions will
3096 Note that the translated versions must have the same filenames (
3097 \begin_inset Flex CharStyle:Code
3100 \begin_layout Plain Layout
3106 above) as the original.
3107 If you feel up to translating the documentation (an excellent way to proof-read
3108 the original documentation by the way!), there are a few things you should
3112 \begin_layout Itemize
3114 \begin_inset Flex CharStyle:Code
3117 \begin_layout Plain Layout
3123 , the guide to writing LyX documentation.
3124 Pay special attention to the translator's section.
3127 \begin_layout Itemize
3128 Check out the documentation translation web page at
3129 \begin_inset CommandInset href
3131 name "http://www.lyx.org/Translation"
3132 target "http://www.lyx.org/Translation"
3137 That way, you can find out which (if any) documents have already been translate
3138 d into your language.
3139 You can also find out who (if anyone) is organizing the effort to translate
3140 the documentation into your language.
3141 If no one is organizing the effort, please let us know that you're interested.
3144 \begin_layout Standard
3145 Once you get to actually translating, here's a few hints for you that may
3149 \begin_layout Itemize
3150 Join the documentation team! There is information on how to do that in
3151 \begin_inset Flex CharStyle:Code
3154 \begin_layout Plain Layout
3161 \begin_inset Flex CharStyle:MenuItem
3164 \begin_layout Plain Layout
3165 Help\SpecialChar \menuseparator
3175 ), which by the way is the first document you should translate.
3178 \begin_layout Itemize
3179 Learn the typographic conventions for the language you are translating to.
3180 Typography is an ancient art and over the centuries, a great variety of
3181 conventions have developed throughout different parts of the world.
3182 Also study the professional terminology amongst typographers in your country.
3183 Inventing your own terminology will only confuse the users.
3186 (Warning! Typography is addictive!)
3189 \begin_layout Itemize
3190 Make a copy of the document.
3191 This will be your working copy.
3192 You can use this as your personal translated help-file by placing it in
3194 \begin_inset Flex CharStyle:Code
3197 \begin_layout Plain Layout
3206 \begin_layout Itemize
3207 Sometimes the original document (from the LyX-team) will be updated.
3208 Use the source viewer at
3209 \begin_inset CommandInset href
3211 name "http://www.lyx.org/trac/timeline"
3212 target "http://www.lyx.org/trac/timeline"
3216 to see what has been changed.
3217 That way you can easily see which parts of the translated document need
3221 \begin_layout Standard
3222 If you ever find an error in the original document, fix it and notify the
3223 rest of the documentation team of the changes! (You didn't forget to join
3224 the documentation team, did you?)
3227 \begin_layout Standard
3228 \begin_inset Branch OutDated
3231 \begin_layout Section
3232 International Keyboard Support
3235 \begin_layout Standard
3238 [Editor's Note: The following section is by
3246 It needs to be fixed to conform to the new Documentation Style sheet and
3247 to make use of the new v1.0 features.
3248 The whole thing also needs to be merged with the section following it.-jw
3249 It may also be badly out of date.-rh (2008)]
3252 \begin_layout Subsection
3253 Defining Own Keymaps: Keymap File Format
3256 \begin_layout Standard
3257 Let's look at a keyboard definition file a little closer.
3258 It is a plain text file defining
3261 \begin_layout Itemize
3262 key-to-key or key-to-string translations
3265 \begin_layout Itemize
3269 \begin_layout Itemize
3270 dead keys exceptions
3273 \begin_layout Standard
3274 To define key-to-key or key-to-string translation, use this command:
3277 \begin_layout Quotation
3278 \begin_inset Flex CharStyle:Code
3281 \begin_layout Plain Layout
3290 \begin_inset Flex CharStyle:Code
3293 \begin_layout Plain Layout
3302 \begin_layout Standard
3304 \begin_inset Flex CharStyle:Code
3307 \begin_layout Plain Layout
3313 is the key to be translated and
3314 \begin_inset Flex CharStyle:Code
3317 \begin_layout Plain Layout
3323 is the string to be inserted into the document.
3324 To define dead keys, use:
3327 \begin_layout Quotation
3328 \begin_inset Flex CharStyle:Code
3331 \begin_layout Plain Layout
3340 \begin_inset Flex CharStyle:Code
3343 \begin_layout Plain Layout
3352 \begin_layout Standard
3354 \begin_inset Flex CharStyle:Code
3357 \begin_layout Plain Layout
3363 is a keyboard key and
3364 \begin_inset Flex CharStyle:Code
3367 \begin_layout Plain Layout
3374 The following dead keys are supported (shortcut name is in parentheses):
3377 \begin_layout Quotation
3381 \begin_inset space \hfill{}
3387 \begin_layout Quotation
3389 \begin_inset space \hfill{}
3395 \begin_layout Quotation
3397 \begin_inset space \hfill{}
3403 \begin_layout Quotation
3405 \begin_inset space \hfill{}
3411 \begin_layout Quotation
3413 \begin_inset space \hfill{}
3419 \begin_layout Quotation
3421 \begin_inset space \hfill{}
3428 \begin_layout Plain Layout
3440 \begin_layout Quotation
3442 \begin_inset space \hfill{}
3448 \begin_layout Quotation
3450 \begin_inset space \hfill{}
3457 \begin_layout Plain Layout
3469 \begin_layout Quotation
3471 \begin_inset space \hfill{}
3477 \begin_layout Quotation
3479 \begin_inset space \hfill{}
3485 \begin_layout Quotation
3487 \begin_inset space \hfill{}
3494 \begin_layout Plain Layout
3506 \begin_layout Quotation
3508 \begin_inset space \hfill{}
3515 \begin_layout Plain Layout
3527 \begin_layout Quotation
3529 \begin_inset space \hfill{}
3535 \begin_layout Quotation
3536 hungarian umlaut (hug)
3537 \begin_inset space \hfill{}
3543 \begin_layout Quotation
3545 \begin_inset space \hfill{}
3551 \begin_layout Quotation
3553 \begin_inset space \hfill{}
3560 \begin_layout Plain Layout
3572 \begin_layout Standard
3573 Since in many international keyboards there are exceptions to what some
3574 dead keys should do, you can define them using
3577 \begin_layout Quotation
3578 \begin_inset Flex CharStyle:Code
3581 \begin_layout Plain Layout
3589 deadkey key outstring
3592 \begin_layout Standard
3593 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3597 \begin_layout Quotation
3598 \begin_inset Flex CharStyle:Code
3601 \begin_layout Plain Layout
3614 \begin_layout Standard
3615 to make it work correctly.
3616 Also, you have to define as exceptions dead keys over i and j, to remove
3617 the dot from them before inserting an accent mark.
3618 I will change this when the time comes, but so far I haven't had time.
3621 \begin_layout Standard
3622 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3625 \begin_inset Flex CharStyle:Code
3628 \begin_layout Plain Layout
3634 have different meaning.
3636 \begin_inset Flex CharStyle:Code
3639 \begin_layout Plain Layout
3645 marks comments, quotes start and end LaTeX-style commands.
3646 To enter quote, you'll need to use
3647 \begin_inset Flex CharStyle:Code
3650 \begin_layout Plain Layout
3659 \begin_inset Flex CharStyle:Code
3662 \begin_layout Plain Layout
3669 \begin_inset Flex CharStyle:Code
3672 \begin_layout Plain Layout
3683 \begin_layout Standard
3684 If you make a keyboard description file that works for your language, please
3685 mail it to me, so I can include it in the next keymap distribution.
3688 \begin_layout Standard
3689 More keywords will be supported in keymap configuration file in future,
3693 \begin_layout Itemize
3694 \begin_inset Flex CharStyle:Code
3697 \begin_layout Plain Layout
3708 \begin_inset space \hfill{}
3712 \begin_inset Flex CharStyle:Code
3715 \begin_layout Plain Layout
3724 \begin_layout Itemize
3725 \begin_inset Flex CharStyle:Code
3728 \begin_layout Plain Layout
3739 \begin_inset space \hfill{}
3743 \begin_inset Flex CharStyle:Code
3746 \begin_layout Plain Layout
3752 an external keymap translation program
3755 \begin_layout Standard
3756 Also, it should look into
3757 \begin_inset Flex CharStyle:Code
3760 \begin_layout Plain Layout
3766 file for defaults, too (for example, a
3767 \begin_inset Flex CharStyle:Code
3770 \begin_layout Plain Layout
3778 option to include default keyboard).
3786 \begin_layout Section
3787 \begin_inset CommandInset label
3793 International Keymap Stuff
3796 \begin_layout Standard
3797 \begin_inset Note Note
3800 \begin_layout Plain Layout
3801 In doing the revisions on this document in March 2008, I did not look over
3802 this stuff, as I do not understand it.
3803 It would be good if someone else could do so.
3812 \begin_layout Standard
3813 The next two sections describe the
3814 \begin_inset Flex CharStyle:Code
3817 \begin_layout Plain Layout
3826 \begin_inset Flex CharStyle:Code
3829 \begin_layout Plain Layout
3837 file syntax in detail.
3838 These sections should help you design your own key map if the ones provided
3839 do not meet your needs.
3842 \begin_layout Subsection
3846 \begin_layout Standard
3850 \begin_inset Flex CharStyle:Code
3853 \begin_layout Plain Layout
3859 file maps keystrokes to characters or strings.
3860 As the name suggests, it sets a keyboard mapping.
3862 \begin_inset Flex CharStyle:Code
3865 \begin_layout Plain Layout
3876 \begin_inset Flex CharStyle:Code
3879 \begin_layout Plain Layout
3894 \begin_inset Flex CharStyle:Code
3897 \begin_layout Plain Layout
3910 \begin_inset Flex CharStyle:Code
3913 \begin_layout Plain Layout
3922 \begin_inset Flex CharStyle:Code
3925 \begin_layout Plain Layout
3933 are described in this section.
3936 \begin_layout Labeling
3937 \labelwidthstring 00.00.0000
3938 \begin_inset Flex CharStyle:Code
3941 \begin_layout Plain Layout
3949 Map a character to a string
3952 \begin_layout LyX-Code
3967 \begin_layout Standard
4000 the double-quote (")
4017 must be escaped with a preceding backslash (
4028 \begin_layout Standard
4030 \begin_inset Flex CharStyle:MenuItem
4033 \begin_layout Plain Layout
4041 statement to cause the symbol
4042 \begin_inset Flex CharStyle:MenuItem
4045 \begin_layout Plain Layout
4053 to be output for the keystroke
4054 \begin_inset Flex CharStyle:MenuItem
4057 \begin_layout Plain Layout
4068 \begin_layout LyX-Code
4074 \begin_layout Labeling
4075 \labelwidthstring 00.00.0000
4076 \begin_inset Flex CharStyle:Code
4079 \begin_layout Plain Layout
4087 Specify an accent character
4090 \begin_layout LyX-Code
4099 \begin_layout Standard
4100 This will make the cha
4138 This is the dead key
4142 \begin_layout Plain Layout
4149 refers to a key that does not produce a character by itself, but when followed
4150 with another key, produces the desired accent character.
4151 For example, a German characte
4153 r with an umlaut like
4163 can be produced in this manner.
4172 \begin_layout Standard
4185 and then another key not in
4202 followed by the other, not allowed key, as output.
4206 \begin_inset Flex CharStyle:MenuItem
4209 \begin_layout Plain Layout
4217 cancels a dead key, so if
4228 \begin_inset Flex CharStyle:MenuItem
4231 \begin_layout Plain Layout
4240 , the cursor will not go one position backwards but will instead cancel
4256 might have had on the next keystroke.
4260 \begin_layout Standard
4261 The following example specifies that the character ' is to be an acute accent,
4262 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4265 \begin_layout LyX-Code
4268 kmod ' acute aeiouAEIOU
4271 \begin_layout Labeling
4272 \labelwidthstring 00.00.0000
4273 \begin_inset Flex CharStyle:Code
4276 \begin_layout Plain Layout
4282 Specify an exception to the accent character
4285 \begin_layout LyX-Code
4294 \begin_layout Standard
4295 This defines an exce
4336 have been assigned a keystroke with a previous
4339 \begin_inset Flex CharStyle:Code
4342 \begin_layout Plain Layout
4366 must not belong in the
4413 If such a declaration does not exist in
4421 \begin_inset Flex CharStyle:Code
4424 \begin_layout Plain Layout
4458 \begin_inset Flex CharStyle:Code
4461 \begin_layout Plain Layout
4475 \begin_layout Standard
4476 The following command produces causes äi to be produced when you enter acute-i
4480 \begin_layout LyX-Code
4494 \begin_layout Labeling
4495 \labelwidthstring 00.00.0000
4496 \begin_inset Flex CharStyle:Code
4499 \begin_layout Plain Layout
4505 Combine two accent characters
4508 \begin_layout LyX-Code
4514 accent1 accent2 allowed
4517 \begin_layout Standard
4518 This one is getting pretty esoteric.
4519 It allows you to combine the effect
4575 \begin_inset Flex CharStyle:Code
4578 \begin_layout Plain Layout
4606 \begin_layout Standard
4607 Consider this example from the
4608 \begin_inset Flex CharStyle:Code
4611 \begin_layout Plain Layout
4622 \begin_layout LyX-Code
4625 kmod ; acute aeioyvhAEIOYVH
4629 kcomb acute umlaut iyIY
4632 \begin_layout Standard
4633 This allows you to press
4634 \begin_inset Flex CharStyle:MenuItem
4637 \begin_layout Plain Layout
4645 and get the effect of
4646 \begin_inset Flex CharStyle:Code
4649 \begin_layout Plain Layout
4668 in this case cancels the last dead key, so if you press
4669 \begin_inset Flex CharStyle:MenuItem
4672 \begin_layout Plain Layout
4681 \begin_inset Flex CharStyle:Code
4684 \begin_layout Plain Layout
4697 \begin_layout Subsection
4701 \begin_layout Standard
4703 \begin_inset Flex CharStyle:Code
4706 \begin_layout Plain Layout
4714 mapping is performed, a
4715 \begin_inset Flex CharStyle:Code
4718 \begin_layout Plain Layout
4728 file maps the strings that the symbols generate to characters in the current
4730 The LyX distribution currently includes at least the
4731 \begin_inset Flex CharStyle:Code
4734 \begin_layout Plain Layout
4743 \begin_inset Flex CharStyle:Code
4746 \begin_layout Plain Layout
4757 \begin_layout Standard
4759 \begin_inset Flex CharStyle:Code
4762 \begin_layout Plain Layout
4770 file is a sequence of declarations of the form
4773 \begin_layout LyX-Code
4786 \begin_layout Standard
4787 For example, in order to map
4788 \begin_inset Flex CharStyle:MenuItem
4791 \begin_layout Plain Layout
4801 to the corresponding character in the iso-8859-1 set (233), the following
4805 \begin_layout LyX-Code
4813 \begin_layout Standard
4815 \begin_inset Flex CharStyle:Code
4818 \begin_layout Plain Layout
4827 \begin_inset Flex CharStyle:Code
4830 \begin_layout Plain Layout
4848 the same character can apply to more than one string.
4850 \begin_inset Flex CharStyle:Code
4853 \begin_layout Plain Layout
4864 \begin_layout LyX-Code
4876 \begin_inset Newline newline
4892 \begin_layout Standard
4893 If LyX cannot find a mapping for the string produced by the keystroke or
4894 a deadkey sequence, it will check if it looks like an accented char and
4895 try to draw an accent over the character on screen.
4898 \begin_layout Subsection
4902 \begin_layout Standard
4903 There is a second way to add support for international characters through
4904 so-called dead-keys.
4905 A dead-key works in combination with a letter to produce an accented character.
4906 Here, we'll explain how to create a really simple dead-key to illustrate
4910 \begin_layout Standard
4911 Suppose you happen to need the circumflex character,
4912 \begin_inset Quotes eld
4916 \begin_inset Quotes erd
4921 \begin_inset Flex CharStyle:MenuItem
4924 \begin_layout Plain Layout
4931 \begin_inset space ~
4935 \begin_inset Flex CharStyle:MenuItem
4938 \begin_layout Plain Layout
4944 ] to the LyX command
4945 \begin_inset Flex CharStyle:Code
4948 \begin_layout Plain Layout
4955 \begin_inset Flex CharStyle:Code
4958 \begin_layout Plain Layout
4965 Now, whenever you type the
4966 \begin_inset Flex CharStyle:MenuItem
4969 \begin_layout Plain Layout
4975 -key followed by a letter, that letter will have a circumflex accent on
4977 For example, the sequence
4978 \begin_inset Quotes eld
4982 \begin_inset Flex CharStyle:MenuItem
4985 \begin_layout Plain Layout
4992 \begin_inset Quotes erd
4995 produces the letter:
4996 \begin_inset Quotes eld
5000 \begin_inset Quotes erd
5004 If you tried to type
5005 \begin_inset Quotes eld
5009 \begin_inset Flex CharStyle:MenuItem
5012 \begin_layout Plain Layout
5019 \begin_inset Quotes erd
5022 , however, LyX will complain with a beep, since a
5023 \begin_inset Quotes eld
5027 \begin_inset Flex CharStyle:MenuItem
5030 \begin_layout Plain Layout
5037 \begin_inset Quotes erd
5040 never takes a circumflex accent.
5042 \begin_inset Flex CharStyle:MenuItem
5045 \begin_layout Plain Layout
5051 after a dead-key produces the bare-accent.
5052 Please note this last point! If you bind a key to a dead-key, you'll need
5053 to rebind the character on that key to yet another key.
5055 \begin_inset Flex CharStyle:MenuItem
5058 \begin_layout Plain Layout
5064 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5067 \begin_layout Standard
5068 One common way to bind dead-keys is to use
5069 \begin_inset Flex CharStyle:MenuItem
5072 \begin_layout Plain Layout
5079 \begin_inset Flex CharStyle:MenuItem
5082 \begin_layout Plain Layout
5089 \begin_inset Flex CharStyle:MenuItem
5092 \begin_layout Plain Layout
5098 in combination with an accent, like
5099 \begin_inset Quotes eld
5103 \begin_inset Flex CharStyle:MenuItem
5106 \begin_layout Plain Layout
5113 \begin_inset Quotes erd
5117 \begin_inset Quotes eld
5121 \begin_inset Flex CharStyle:MenuItem
5124 \begin_layout Plain Layout
5131 \begin_inset Quotes erd
5135 \begin_inset Quotes eld
5139 \begin_inset Flex CharStyle:MenuItem
5142 \begin_layout Plain Layout
5149 \begin_inset Quotes erd
5153 Another way involves using
5154 \begin_inset Flex CharStyle:Code
5157 \begin_layout Plain Layout
5164 \begin_inset Flex CharStyle:Code
5167 \begin_layout Plain Layout
5173 to set up the special
5174 \begin_inset Flex CharStyle:Code
5177 \begin_layout Plain Layout
5185 \begin_inset Flex CharStyle:Code
5188 \begin_layout Plain Layout
5194 acts in some ways just like
5195 \begin_inset Flex CharStyle:MenuItem
5198 \begin_layout Plain Layout
5204 and permits you to bind keys to accented characters.
5205 You can also turn keys into dead-keys by binding them to something like
5207 \begin_inset Flex CharStyle:Code
5210 \begin_layout Plain Layout
5216 and then binding this symbolic key to the corresponding LyX command.
5220 \begin_layout Plain Layout
5225 : This is exactly what I do in my
5226 \begin_inset Flex CharStyle:Code
5229 \begin_layout Plain Layout
5236 \begin_inset Flex CharStyle:Code
5239 \begin_layout Plain Layout
5247 \begin_inset Flex CharStyle:MenuItem
5250 \begin_layout Plain Layout
5252 \begin_inset space ~
5261 \begin_inset Flex CharStyle:Code
5264 \begin_layout Plain Layout
5270 and a bunch of these
5271 \begin_inset Quotes eld
5275 \begin_inset Flex CharStyle:Code
5278 \begin_layout Plain Layout
5285 \begin_inset Quotes erd
5288 symbolic keys bound such things as
5289 \begin_inset Flex CharStyle:MenuItem
5292 \begin_layout Plain Layout
5294 \begin_inset space ~
5303 \begin_inset Flex CharStyle:MenuItem
5306 \begin_layout Plain Layout
5308 \begin_inset space ~
5317 This is how I produce my accented characters.
5322 You can make just about anything into the
5323 \begin_inset Flex CharStyle:Code
5326 \begin_layout Plain Layout
5333 \begin_inset Flex CharStyle:MenuItem
5336 \begin_layout Plain Layout
5342 keys, a spare function key, etc.
5343 As for the LyX commands that produce accents, check the entry for
5344 \begin_inset Flex CharStyle:Code
5347 \begin_layout Plain Layout
5358 You'll find the complete list there.
5361 \begin_layout Subsection
5362 Saving your Language Configuration
5365 \begin_layout Standard
5366 You can edit your preferences so that your desired language environment
5367 is automatically configured when LyX starts up, via the
5368 \begin_inset Flex CharStyle:MenuItem
5371 \begin_layout Plain Layout
5372 Edit\SpecialChar \menuseparator
5381 \begin_layout Chapter
5382 Installing New Document Classes, Layouts, and Templates
5383 \begin_inset CommandInset label
5385 name "chap:textclass"
5393 \begin_layout Plain Layout
5394 Installing New Document Classes
5402 \begin_layout Standard
5403 In this chapter, we describe the procedures for creating and installing
5404 new LyX layout and template files, as well as offer a refresher on correctly
5405 installing new LaTeX document classes.
5406 Some definitions: a document class is a LaTeX file (usually ending in
5407 \begin_inset Flex CharStyle:Code
5410 \begin_layout Plain Layout
5417 \begin_inset Flex CharStyle:Code
5420 \begin_layout Plain Layout
5426 ) that describes the format of a document such as an article, report, journal
5427 preprint, etc, and all the commands needed to realize that format.
5428 A layout file is a LyX file that corresponds to a LaTeX document class
5429 and that tells LyX how to
5430 \begin_inset Quotes eld
5434 \begin_inset Quotes erd
5437 things on the screen to make the display look something like the final
5439 More precisely, a layout file describes a
5440 \begin_inset Quotes eld
5444 \begin_inset Quotes erd
5447 which is the internal construct LyX uses to render the screen display.
5449 \begin_inset Quotes eld
5453 \begin_inset Quotes erd
5457 \begin_inset Quotes eld
5461 \begin_inset Quotes erd
5464 can be used somewhat interchangeably, but it is better to refer to the
5465 file as the layout, and the thing living in LyX's memory as the text class.
5466 A template file is simply a LyX document that contains a set of predefined
5467 entries for a given document class—entries that are generally required
5469 Templates are especially useful for things like journal manuscripts that
5470 are to be submitted electronically.
5473 \begin_layout Section
5474 Installing a new LaTeX package
5477 \begin_layout Standard
5478 Some installations may not include a LaTeX package that you would like to
5480 For example, you might need FoilTeX, a package for preparing slides or
5481 viewgraphs for overhead projectors.
5482 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5483 a user interface for that.
5484 For example on MiKTeX you start its program
5485 \begin_inset Quotes eld
5489 \begin_inset Quotes erd
5492 to get a list of available packages.
5493 To install one, right click on it or use the installing toolbar button.
5494 When the package you want to install is not in the list, but you have it
5496 \begin_inset Flex CharStyle:Code
5499 \begin_layout Plain Layout
5506 \begin_inset Flex CharStyle:Code
5509 \begin_layout Plain Layout
5515 -file, then copy these files to a subfolder of your LaTeX distribution,
5516 for example to the folder
5525 Then update the file name database of your LaTeX-distribution.
5526 For example on MiKTeX this is done by pressing the button
5529 \begin_inset space ~
5534 that you find in MiKTeX's
5535 \begin_inset Quotes eld
5539 \begin_inset Quotes erd
5543 In both cases you need afterwards to reconfigure LyX using the menu
5544 \begin_inset Flex CharStyle:MenuItem
5547 \begin_layout Plain Layout
5548 Tools\SpecialChar \menuseparator
5554 and then to restart LyX.
5557 \begin_layout Standard
5558 If your LaTeX distribution doesn't provide a user interface, then you can
5559 follow these steps by using a UNIX/Linux console.
5562 \begin_layout Enumerate
5563 Get the package from
5564 \begin_inset CommandInset href
5567 target "http://www.ctan.org/"
5574 \begin_layout Enumerate
5575 You can install this package in several different places.
5576 If you want it to be available for all users on your system, then you should
5577 install it in your `local' TeX tree; if you want (or need) it to be available
5578 just for you, then you can install it in your own `user' TeX tree.
5579 Where these should be created, if they do not already exist, depends upon
5580 the details of your system.
5581 To find out, look in the file
5582 \begin_inset Flex CharStyle:Code
5585 \begin_layout Plain Layout
5595 \begin_layout Plain Layout
5596 This usually lives in the directory
5597 \begin_inset Flex CharStyle:Code
5600 \begin_layout Plain Layout
5606 , though you can run
5607 \begin_inset Flex CharStyle:Code
5610 \begin_layout Plain Layout
5621 The location of the `local' TeX tree is defined by
5622 \begin_inset Flex CharStyle:Code
5625 \begin_layout Plain Layout
5631 ; this is usually somewhere like
5632 \begin_inset Flex CharStyle:Code
5635 \begin_layout Plain Layout
5636 /usr/local/share/texmf/
5642 The `user' TeX tree is defined by
5643 \begin_inset Flex CharStyle:Code
5646 \begin_layout Plain Layout
5653 \begin_inset Flex CharStyle:Code
5656 \begin_layout Plain Layout
5663 (If these variables are not predefined, you can define them.) You'll probably
5664 need root permissions to create or modify the `local' tree; but your `user'
5665 tree shouldn't have such limitations.
5668 \begin_layout Enumerate
5670 \begin_inset Flex CharStyle:Code
5673 \begin_layout Plain Layout
5680 \begin_inset Flex CharStyle:Code
5683 \begin_layout Plain Layout
5690 \begin_inset Flex CharStyle:Code
5693 \begin_layout Plain Layout
5700 \begin_inset space \thinspace{}
5704 \begin_inset Newline newline
5708 \begin_inset Flex CharStyle:Code
5711 \begin_layout Plain Layout
5712 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5718 \begin_inset Newline newline
5721 But, again, most of this will
5722 \begin_inset Quotes eld
5726 \begin_inset Quotes erd
5732 \begin_layout Enumerate
5737 \begin_layout Plain Layout
5738 We'll assume henceforth that you're defining `local' TeX tree.
5739 If you're defining a user tree, just adjust as necessary.
5745 You must follow the directory structure of your existing
5746 \begin_inset Flex CharStyle:Code
5749 \begin_layout Plain Layout
5755 directory, which will be found at
5756 \begin_inset Flex CharStyle:Code
5759 \begin_layout Plain Layout
5766 For example, latex packages should go under
5767 \begin_inset Flex CharStyle:Code
5770 \begin_layout Plain Layout
5771 $TEXMFLOCAL/tex/latex/
5779 \begin_layout Enumerate
5780 Install the package.
5781 For example, you would unpack the FoilTeX tarball and copy it to
5782 \begin_inset Flex CharStyle:Code
5785 \begin_layout Plain Layout
5786 $TEXMFLOCAL/tex/latex/foiltex
5793 \begin_inset Flex CharStyle:Code
5796 \begin_layout Plain Layout
5802 directory contains various files.
5805 \begin_layout Enumerate
5807 \begin_inset Flex CharStyle:Code
5810 \begin_layout Plain Layout
5818 \begin_inset Flex CharStyle:Code
5821 \begin_layout Plain Layout
5830 \begin_layout Standard
5831 Your package is now installed and available to LaTeX.
5832 To make it available to LyX, you need to create a Layout file, if one is
5833 not already available.
5834 (See the next section.) Once you have a layout file, you need only reconfigure
5836 \begin_inset Flex CharStyle:MenuItem
5839 \begin_layout Plain Layout
5840 Tools\SpecialChar \menuseparator
5846 ) and then restart LyX.
5847 You should then see your new package—for example
5848 \begin_inset Flex CharStyle:MenuItem
5851 \begin_layout Plain Layout
5858 \begin_inset Flex CharStyle:MenuItem
5861 \begin_layout Plain Layout
5862 Document\SpecialChar \menuseparator
5869 \begin_inset Flex CharStyle:MenuItem
5872 \begin_layout Plain Layout
5882 \begin_layout Section
5886 \begin_layout Standard
5887 This section describes how to write and install your own LyX layout files
5888 and walks through the
5889 \begin_inset Flex CharStyle:Code
5892 \begin_layout Plain Layout
5898 text class format as an example.
5900 \begin_inset Flex CharStyle:Code
5903 \begin_layout Plain Layout
5909 files describe what paragraph and character styles are available for a
5910 given document class and how LyX should display them.
5911 We try to provide a thorough description of the process here; however,
5912 there are so many different types of documents supported by LaTeX classes
5913 that we can't hope to cover every different possibility or problem you
5915 (The LyX users' list is frequented by people with lots of experience with
5916 layout design who are willing to share what they've learned.)
5919 \begin_layout Standard
5920 As you prepare to write a new layout, it is extremely helpful to look at
5921 the example layouts distributed with LyX.
5922 If you use a nice LaTeX document class that might be of interest for others,
5923 too, and have a nice corresponding LyX layout, feel free to contribute
5924 the stuff to us, so we may put it into the distribution.
5926 \begin_inset CommandInset href
5928 name "section on the LyX wiki"
5929 target "http://wiki.lyx.org/Layouts/Layouts"
5933 for this kind of material.
5936 \begin_layout Standard
5937 All the tags described in this chapter are case-insensitive; this means
5939 \begin_inset Flex CharStyle:Code
5942 \begin_layout Plain Layout
5949 \begin_inset Flex CharStyle:Code
5952 \begin_layout Plain Layout
5959 \begin_inset Flex CharStyle:Code
5962 \begin_layout Plain Layout
5968 are really the same command.
5969 The possible values are printed in brackets after the feature's name.
5970 The default value if a feature isn't specified inside a text class-description
5972 \begin_inset Flex CharStyle:Code
5975 \begin_layout Plain Layout
5984 If the argument has a data type like
5985 \begin_inset Quotes eld
5989 \begin_inset Quotes erd
5993 \begin_inset Quotes eld
5997 \begin_inset Quotes erd
6000 , the default is shown like this:
6001 \begin_inset Flex CharStyle:Code
6004 \begin_layout Plain Layout
6015 \begin_layout Subsection
6016 \begin_inset CommandInset label
6018 name "sub:Layout-modules"
6025 \begin_layout Standard
6026 Similar to layout files, and new with LyX 1.6, are layout
6031 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6032 some modules—such as the endnotes module—provide support for just such
6034 In a sense, layout modules are similar to included files—files like
6035 \begin_inset Flex CharStyle:Code
6038 \begin_layout Plain Layout
6044 —in that modules are not specific to a given document layout but may be
6045 used with many different layouts.
6046 The difference is that using a layout module does not require editing the
6048 Rather, modules are selected in the
6049 \begin_inset Flex CharStyle:MenuItem
6052 \begin_layout Plain Layout
6053 Document\SpecialChar \menuseparator
6062 \begin_layout Standard
6063 Building modules is the easiest way to get started with layout editing,
6064 since it can be as simple as adding a single new paragraph or flex inset.
6065 But modules may, in principle, contain anything a layout file can contain.
6068 \begin_layout Standard
6069 A module must begin with a line like the following:
6072 \begin_layout LyX-Code
6075 DeclareLyXModule[endnotes.sty]{Endnotes}
6078 \begin_layout Standard
6079 The argument in square brackets is optional: It declares any LaTeX packages
6080 on which the module depends.
6081 The mandatory argument, in curly brackets, is the name of the module, as
6083 \begin_inset Flex CharStyle:MenuItem
6086 \begin_layout Plain Layout
6087 Document\SpecialChar \menuseparator
6097 \begin_layout Standard
6098 The module declaration should then be followed by lines like the following:
6101 \begin_layout LyX-Code
6105 \begin_layout LyX-Code
6106 #Adds an endnote command, in addition to footnotes.
6110 \begin_layout LyX-Code
6111 #You will need to add
6113 theendnotes in TeX code where you
6116 \begin_layout LyX-Code
6117 #want the endnotes to appear.
6121 \begin_layout LyX-Code
6125 \begin_layout LyX-Code
6126 #Requires: somemodule | othermodule
6129 \begin_layout LyX-Code
6130 #Excludes: badmodule
6133 \begin_layout Standard
6134 The description is used in
6135 \begin_inset Flex CharStyle:MenuItem
6138 \begin_layout Plain Layout
6139 Document\SpecialChar \menuseparator
6145 to provide the user with information about what the module does.
6147 \begin_inset Flex CharStyle:Code
6150 \begin_layout Plain Layout
6156 line is used to identify other modules with which this one must be used;
6158 \begin_inset Flex CharStyle:Code
6161 \begin_layout Plain Layout
6167 line is used to identify modules with which this one may not be used.
6168 Both are optional, and, as shown, multiple modules should be separated
6169 with the pipe symbol: |.
6170 Note that the required modules are treated disjunctively:
6174 of the required modules must be used.
6179 excluded module may be used.
6180 Note that modules are identified here by their
6184 without the .module extension.
6186 \begin_inset Flex CharStyle:Code
6189 \begin_layout Plain Layout
6196 \begin_inset Flex CharStyle:Code
6199 \begin_layout Plain Layout
6208 \begin_layout Standard
6209 After creating a new module, you will need to reconfigure and then restart
6210 LyX for the module to appear in the menu.
6211 However, changes you make to the module will be seen immediately, if you
6213 \begin_inset Flex CharStyle:MenuItem
6216 \begin_layout Plain Layout
6217 Document\SpecialChar \menuseparator
6223 , highlight something, and then hit
6224 \begin_inset Quotes eld
6228 \begin_inset Quotes erd
6234 It is strongly recommended that you save your work before doing so
6239 it is strongly recommended that you not attempt to edit modules while simultaneo
6240 usly working on documents
6243 Though of course the developers strive to keep LyX stable in such situations,
6244 syntax errors and the like in your module file could cause strange behavior.
6247 \begin_layout Subsection
6248 Supporting new document classes
6251 \begin_layout Standard
6252 There are two situations you are likely to encounter when wanting to support
6253 a new LaTeX document class, involving LaTeX2e class (
6254 \begin_inset Flex CharStyle:Code
6257 \begin_layout Plain Layout
6264 \begin_inset Flex CharStyle:Code
6267 \begin_layout Plain Layout
6274 Supporting a style file is usually fairly easy.
6275 Supporting a new document class is a bit harder.
6278 \begin_layout Subsection
6280 \begin_inset Flex CharStyle:MenuItem
6283 \begin_layout Plain Layout
6292 \begin_layout Standard
6293 If your new document class is provided as a style file that is used in conjuncti
6294 on with an existing, supported document class—for the sake of the example,
6295 we'll assume that the style file is called
6296 \begin_inset Flex CharStyle:MenuItem
6299 \begin_layout Plain Layout
6305 and it is meant to be used with
6306 \begin_inset Flex CharStyle:MenuItem
6309 \begin_layout Plain Layout
6315 , which is a standard class—start by copying the existing class's layout
6316 file into your local directory:
6319 \begin_layout LyX-Code
6320 cp report.layout ~/.lyx/layouts/myclass.layout
6323 \begin_layout Standard
6325 \begin_inset Flex CharStyle:Code
6328 \begin_layout Plain Layout
6334 and change the line:
6337 \begin_layout LyX-Code
6340 DeclareLaTeXClass{report}
6343 \begin_layout Standard
6347 \begin_layout LyX-Code
6350 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6353 \begin_layout Standard
6357 \begin_layout LyX-Code
6359 \begin_inset Newline newline
6365 \begin_inset Newline newline
6371 \begin_layout Standard
6372 near the top of the file.
6375 \begin_layout Standard
6376 Start LyX and select
6377 \begin_inset Flex CharStyle:MenuItem
6380 \begin_layout Plain Layout
6381 Tools\SpecialChar \menuseparator
6388 Then restart LyX and try creating a new document.
6390 \begin_inset Flex CharStyle:MenuItem
6393 \begin_layout Plain Layout
6399 " as a document class option in the
6400 \begin_inset Flex CharStyle:MenuItem
6403 \begin_layout Plain Layout
6404 Document\SpecialChar \menuseparator
6411 It is likely that some of the sectioning commands and such in your new
6412 class will work differently from how they worked in the base class—
6413 \begin_inset Flex CharStyle:Code
6416 \begin_layout Plain Layout
6422 in this example—so you can fiddle around with the settings for the different
6423 sections if you wish.
6426 \begin_layout Subsection
6428 \begin_inset Flex CharStyle:MenuItem
6431 \begin_layout Plain Layout
6440 \begin_layout Standard
6441 There are two possibilities here.
6442 One is that the class file is itself based upon an existing document class.
6443 For example, many thesis classes are based upon
6444 \begin_inset Flex CharStyle:MenuItem
6447 \begin_layout Plain Layout
6454 To see whether yours is, look for a line like
6457 \begin_layout LyX-Code
6463 \begin_layout Standard
6465 If so, then you may proceed largely as in the previous section, though
6466 the DeclareLaTeXClass line will be different.
6467 If your new class is thesis, and it is based upon book, then the line should
6472 \begin_layout Plain Layout
6473 And it will be easiest if you save the file to
6474 \begin_inset Flex CharStyle:Code
6477 \begin_layout Plain Layout
6483 : LyX assumes that the document class has the same name as the layout file.
6492 \begin_layout LyX-Code
6495 DeclareLaTeXClass[thesis,book]{thesis}
6498 \begin_layout Standard
6499 If, on the other hand, the new class is not based upon an existing class,
6500 you will probably have to
6501 \begin_inset Quotes eld
6505 \begin_inset Quotes erd
6509 We strongly suggest copying an existing layout file which uses a similar
6510 LaTeX class and then modifying it, if you can do so.
6511 At least use an existing file as a starting point so you can find out what
6512 items you need to worry about.
6513 Again, the specifics are covered below.
6516 \begin_layout Section
6517 Declaring a new text class
6520 \begin_layout Standard
6521 When it's finally time to get your hands dirty and create or edit your own
6522 layout file, the following sections describe what you're up against.
6523 Our advice is to go slowly, save and test often, listen to soothing music,
6524 and enjoy one or two of your favorite adult beverages; more if you are
6525 getting particularly stuck.
6526 It's really not that hard, except that the multitude of options can become
6527 overwhelming if you try to do to much in one sitting.
6528 Go have another adult beverage, just for good measure.
6531 \begin_layout Standard
6535 \begin_layout Standard
6536 Lines in a layout file which begin with a
6537 \begin_inset Flex CharStyle:Code
6540 \begin_layout Plain Layout
6547 There is one exception to this rule: all layouts should begin with lines
6551 \begin_layout LyX-Code
6554 #% Do not delete the line below; configure depends on this
6557 \begin_layout LyX-Code
6562 DeclareLaTeXClass{article}
6565 \begin_layout Standard
6566 The second line is used when you configure LyX.
6567 The layout file is read by the LaTeX script
6568 \begin_inset Flex CharStyle:Code
6571 \begin_layout Plain Layout
6577 , in a special mode where
6578 \begin_inset Flex CharStyle:Code
6581 \begin_layout Plain Layout
6588 The first line is just a LaTeX comment, and the second one contains the
6589 declaration of the text class.
6590 If these lines appear in a file named
6591 \begin_inset Flex CharStyle:Code
6594 \begin_layout Plain Layout
6600 , then they define a text class of name
6601 \begin_inset Flex CharStyle:Code
6604 \begin_layout Plain Layout
6610 (the name of the layout file) which uses the LaTeX document class
6611 \begin_inset Flex CharStyle:Code
6614 \begin_layout Plain Layout
6620 (the default is to use the same name as the layout).
6622 \begin_inset Quotes eld
6626 \begin_inset Quotes erd
6629 that appears above is used as a description of the text class in the
6630 \begin_inset Flex CharStyle:MenuItem
6633 \begin_layout Plain Layout
6634 Document\SpecialChar \menuseparator
6643 \begin_layout Standard
6644 Let's assume that you wrote your own text class that uses the
6645 \begin_inset Flex CharStyle:Code
6648 \begin_layout Plain Layout
6654 document class, but where you changed the appearance of the section headings.
6655 If you put it in a file
6656 \begin_inset Flex CharStyle:Code
6659 \begin_layout Plain Layout
6665 , the header of this file should be:
6668 \begin_layout LyX-Code
6671 #% Do not delete the line below; configure depends on this
6674 \begin_layout LyX-Code
6679 DeclareLaTeXClass[article]{article (with my own headings)}
6682 \begin_layout Standard
6683 This declares a text class
6684 \begin_inset Flex CharStyle:Code
6687 \begin_layout Plain Layout
6693 , associated with the LaTeX document class
6694 \begin_inset Flex CharStyle:Code
6697 \begin_layout Plain Layout
6704 \begin_inset Quotes eld
6707 article (with my own headings)
6708 \begin_inset Quotes erd
6712 If your text class depends on several packages, you can declare it as:
6715 \begin_layout LyX-Code
6718 #% Do not delete the line below; configure depends on this
6721 \begin_layout LyX-Code
6726 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6729 \begin_layout Standard
6730 This indicates that your text class uses the foo.sty package.
6731 Finally, it is also possible to declare classes for DocBook code.
6732 Typical declarations will look like
6735 \begin_layout LyX-Code
6738 #% Do not delete the line below; configure depends on this
6741 \begin_layout LyX-Code
6746 DeclareDocBookClass[article]{SGML (DocBook article)}
6749 \begin_layout Standard
6750 Note that these declarations can also be given an optional parameter declaring
6751 the name of the document class (but not a list).
6754 \begin_layout Standard
6755 So, to be as explicit as possible, the form of the layout declaration is:
6758 \begin_layout LyX-Code
6763 DeclareLaTeXClass[class,package.sty]{layout description}
6766 \begin_layout Standard
6767 The class need only be specified if the name of the LaTeX class file and
6768 the name of the layout file are different; if the name of the class file
6769 is not specified, then LyX will simply assume that it is the same as the
6770 name of the layout file.
6773 \begin_layout Standard
6774 When the text class has been modified to your taste, all you have to do
6775 is to copy it either to
6776 \begin_inset Flex CharStyle:Code
6779 \begin_layout Plain Layout
6786 \begin_inset Flex CharStyle:Code
6789 \begin_layout Plain Layout
6796 \begin_inset Flex CharStyle:MenuItem
6799 \begin_layout Plain Layout
6800 Tools\SpecialChar \menuseparator
6806 , exit LyX and restart it.
6807 Then your new text class should be available along with the others.
6810 \begin_layout Standard
6811 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6812 you made to your layout files.
6813 As a result, editing layout files could be very time consuming.
6814 Beginning with 1.6, however, you can force a reload of the layout currently
6815 in use by using the LyX function
6816 \begin_inset Flex CharStyle:MenuItem
6819 \begin_layout Plain Layout
6826 There is no default binding for this function—though, of course, you can
6827 bind it to a key yourself.
6828 If you want to use this function, then, you should simply enter it in the
6834 : This is very much an `advanced feature'.
6839 recommended that you save your work before using this function.
6844 recommended that you not attempt to edit your layout while simultaneously
6845 working on a document that you care about.
6846 Use a test document.
6847 Syntax errors and the like in your layout file could cause peculiar behavior.
6848 In particular, such errors could cause LyX to regard the current layout
6849 as invalid and to attempt to switch to some other layout.
6850 The LyX team strives to keep LyX stable in such situations, but safe is
6854 \begin_layout Subsection
6858 \begin_layout Standard
6859 The first non-comment line must contain the file format number:
6862 \begin_layout Description
6863 \begin_inset Flex CharStyle:Code
6866 \begin_layout Plain Layout
6873 \begin_inset Flex CharStyle:Code
6876 \begin_layout Plain Layout
6882 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6883 don't have an explicit file format).
6884 The file format that is documented here is format 1
6885 \change_deleted 0 1234611237
6887 \change_inserted 0 1234611237
6891 \change_inserted 0 1234613411
6895 \begin_layout Description
6897 \change_inserted 0 1234613417
6898 FIXME: Format 13 is missing!
6903 \begin_layout Subsection
6904 General text class parameters
6907 \begin_layout Standard
6908 These are the general parameters which describe the form of the entire document:
6911 \begin_layout Description
6912 \begin_inset Flex CharStyle:Code
6915 \begin_layout Plain Layout
6921 Adds information to the document preamble.
6923 \begin_inset Quotes eld
6927 \begin_inset Flex CharStyle:Code
6930 \begin_layout Plain Layout
6937 \begin_inset Quotes erd
6943 \begin_layout Description
6944 \begin_inset Flex CharStyle:Code
6947 \begin_layout Plain Layout
6953 Describes various global options supported by the document class.
6955 \begin_inset space ~
6959 \begin_inset CommandInset ref
6961 reference "sec:classoptions"
6967 \begin_inset Quotes eld
6971 \begin_inset Flex CharStyle:Code
6974 \begin_layout Plain Layout
6981 \begin_inset Quotes erd
6987 \begin_layout Description
6988 \begin_inset Flex CharStyle:Code
6991 \begin_layout Plain Layout
6998 \begin_inset Flex CharStyle:Code
7001 \begin_layout Plain Layout
7010 \begin_inset Flex CharStyle:Code
7013 \begin_layout Plain Layout
7019 ] Whether the class should default to having one or two columns.
7020 Can be changed in the
7021 \begin_inset Flex CharStyle:MenuItem
7024 \begin_layout Plain Layout
7025 Document\SpecialChar \menuseparator
7034 \begin_layout Description
7035 \begin_inset Flex CharStyle:Code
7038 \begin_layout Plain Layout
7044 This sequence defines a new counter.
7046 \begin_inset space ~
7050 \begin_inset CommandInset ref
7052 reference "sec:counter"
7058 \begin_inset Quotes eld
7062 \begin_inset Flex CharStyle:Code
7065 \begin_layout Plain Layout
7072 \begin_inset Quotes erd
7078 \begin_layout Description
7079 \begin_inset Flex CharStyle:Code
7082 \begin_layout Plain Layout
7088 Sets the default font used to display the document.
7090 \begin_inset space ~
7094 \begin_inset CommandInset ref
7096 reference "sec:fonts"
7100 for how to declare fonts.
7102 \begin_inset Quotes eld
7106 \begin_inset Flex CharStyle:Code
7109 \begin_layout Plain Layout
7116 \begin_inset Quotes erd
7122 \begin_layout Description
7123 \begin_inset Flex CharStyle:Code
7126 \begin_layout Plain Layout
7133 \begin_inset Flex CharStyle:Code
7136 \begin_layout Plain Layout
7142 Specifies a module to be included by default with this document class,
7143 which should be specified by filename without the
7144 \begin_inset Flex CharStyle:Code
7147 \begin_layout Plain Layout
7154 The user can still remove the module, but it will be active at the outset.
7155 (This applies only when new files are created, or when this class is chosen
7156 for an existing document.)
7159 \begin_layout Description
7160 \begin_inset Flex CharStyle:Code
7163 \begin_layout Plain Layout
7170 \begin_inset Flex CharStyle:Code
7173 \begin_layout Plain Layout
7179 ] This is the style that will be assigned to new paragraphs, usually
7180 \begin_inset Flex CharStyle:MenuItem
7183 \begin_layout Plain Layout
7190 This will default to the first defined style if not given, but you are
7191 highly encouraged to use this directive.
7194 \begin_layout Description
7195 \begin_inset Flex CharStyle:Code
7198 \begin_layout Plain Layout
7205 \begin_inset Flex CharStyle:Code
7208 \begin_layout Plain Layout
7214 ] Indicates that the module in question—which should be specified by filename
7216 \begin_inset Flex CharStyle:Code
7219 \begin_layout Plain Layout
7225 extension—cannot be used with this document class.
7226 This might be used in a journal-specific layout file to prevent, say, the
7228 \begin_inset Flex CharStyle:Code
7231 \begin_layout Plain Layout
7237 module that numbers theorems by section.
7242 be used in a module.
7243 Modules have their own way of excluding other modules (see
7244 \begin_inset CommandInset ref
7246 reference "sub:Layout-modules"
7253 \begin_layout Description
7254 \begin_inset Flex CharStyle:Code
7257 \begin_layout Plain Layout
7263 Defines a new float.
7265 \begin_inset space ~
7269 \begin_inset CommandInset ref
7271 reference "sec:floats"
7277 \begin_inset Quotes eld
7281 \begin_inset Flex CharStyle:Code
7284 \begin_layout Plain Layout
7291 \begin_inset Quotes erd
7297 \begin_layout Description
7298 \begin_inset Flex CharStyle:Code
7301 \begin_layout Plain Layout
7307 As its name implies, this command allows you to include another layout
7308 definition file within yours to avoid duplicating commands.
7309 Common examples are the standard layout files, for example,
7310 \begin_inset Flex CharStyle:Code
7313 \begin_layout Plain Layout
7319 , which contains most of the basic layouts.
7322 \begin_layout Description
7323 \begin_inset Flex CharStyle:Code
7326 \begin_layout Plain Layout
7332 This section (re-)defines the layout of an inset.
7333 It can be applied to an existing inset of to a new, user-defined inset,
7335 \begin_inset space \thinspace{}
7339 \begin_inset space \space{}
7342 a new character style.
7344 \begin_inset space ~
7348 \begin_inset CommandInset ref
7350 reference "sec:charstyle"
7354 for more information.
7356 \begin_inset Quotes eld
7360 \begin_inset Flex CharStyle:Code
7363 \begin_layout Plain Layout
7370 \begin_inset Quotes erd
7376 \begin_layout Description
7377 \begin_inset Flex CharStyle:Code
7380 \begin_layout Plain Layout
7386 A string that indicates the width of the left margin on the screen, for
7388 \begin_inset Quotes eld
7392 \begin_inset Quotes erd
7398 \begin_layout Description
7399 \begin_inset Flex CharStyle:Code
7402 \begin_layout Plain Layout
7408 This command deletes an existing float.
7409 This is particularly useful when you want to suppress a float that has
7410 be defined in an input file.
7413 \begin_layout Description
7414 \begin_inset Flex CharStyle:Code
7417 \begin_layout Plain Layout
7423 This command deletes an existing style.
7424 This is particularly useful when you want to suppress a style that has
7425 be defined in an input file.
7428 \begin_layout Description
7429 \begin_inset Flex CharStyle:Code
7432 \begin_layout Plain Layout
7438 A string indicating what sort of output documents using this class will
7440 At present, the options are: `docbook', `latex', and `literate'.
7443 \begin_layout Description
7444 \begin_inset Flex CharStyle:Code
7447 \begin_layout Plain Layout
7458 \begin_inset Flex CharStyle:Code
7461 \begin_layout Plain Layout
7472 \begin_inset Flex CharStyle:Code
7475 \begin_layout Plain Layout
7482 \begin_inset Flex CharStyle:Code
7485 \begin_layout Plain Layout
7491 ] The class default pagestyle.
7492 Can be changed in the
7493 \begin_inset Flex CharStyle:MenuItem
7496 \begin_layout Plain Layout
7497 Document\SpecialChar \menuseparator
7506 \begin_layout Description
7507 \begin_inset Flex CharStyle:Code
7510 \begin_layout Plain Layout
7516 Sets the preamble for the LaTeX document.
7517 Note that this will completely override any prior
7518 \begin_inset Flex CharStyle:Code
7521 \begin_layout Plain Layout
7528 \begin_inset Flex CharStyle:Code
7531 \begin_layout Plain Layout
7539 \begin_inset Quotes eld
7543 \begin_inset Flex CharStyle:Code
7546 \begin_layout Plain Layout
7553 \begin_inset Quotes erd
7559 \begin_layout Description
7560 \begin_inset Flex CharStyle:Code
7563 \begin_layout Plain Layout
7570 \begin_inset Flex CharStyle:Code
7573 \begin_layout Plain Layout
7580 \begin_inset Flex CharStyle:Code
7583 \begin_layout Plain Layout
7592 \begin_inset Flex CharStyle:Code
7595 \begin_layout Plain Layout
7601 ] Whether the class already provides the feature
7602 \begin_inset Flex CharStyle:Code
7605 \begin_layout Plain Layout
7612 A feature is in general the name of a package (
7613 \begin_inset Flex CharStyle:Code
7616 \begin_layout Plain Layout
7623 \begin_inset Flex CharStyle:Code
7626 \begin_layout Plain Layout
7632 , \SpecialChar \ldots{}
7634 \begin_inset Flex CharStyle:Code
7637 \begin_layout Plain Layout
7644 \begin_inset Flex CharStyle:Code
7647 \begin_layout Plain Layout
7653 ,\SpecialChar \ldots{}
7654 ); the complete list of supported features is unfortunately not documented
7655 outside the LyX source code—but see
7656 \begin_inset Flex CharStyle:Code
7659 \begin_layout Plain Layout
7665 if you're interested.
7667 \begin_inset Flex CharStyle:MenuItem
7670 \begin_layout Plain Layout
7671 Help\SpecialChar \menuseparator
7677 also gives an overview of the supported packages.
7680 \begin_layout Description
7681 \begin_inset Flex CharStyle:Code
7684 \begin_layout Plain Layout
7691 \begin_inset Flex CharStyle:Code
7694 \begin_layout Plain Layout
7700 ] Indicates that this layout provides the functionality of the module mentioned,
7701 which should be specified by the filename without the
7702 \begin_inset Flex CharStyle:Code
7705 \begin_layout Plain Layout
7712 This will typically be used if the layout includes the module directly,
7713 rather than using the
7714 \begin_inset Flex CharStyle:Code
7717 \begin_layout Plain Layout
7723 tag to indicate that it ought to be used.
7724 It could be used in a module that provided an alternate implementation
7725 of the same functionality.
7728 \begin_layout Description
7729 \begin_inset Flex CharStyle:Code
7732 \begin_layout Plain Layout
7739 \begin_inset Flex CharStyle:Code
7742 \begin_layout Plain Layout
7748 ] Whether the class requires the feature
7749 \begin_inset Flex CharStyle:Code
7752 \begin_layout Plain Layout
7759 Multiple features must be separated by commas.
7760 Note that you can only request supported features.
7763 \begin_layout Description
7764 \begin_inset Flex CharStyle:Code
7767 \begin_layout Plain Layout
7773 A string that indicates the width of the right margin on the screen, for
7775 \begin_inset Quotes eld
7779 \begin_inset Quotes erd
7785 \begin_layout Description
7786 \begin_inset Flex CharStyle:Code
7789 \begin_layout Plain Layout
7795 Sets which divisions get numbered.
7797 \begin_inset Flex CharStyle:Code
7800 \begin_layout Plain Layout
7809 \begin_layout Description
7810 \begin_inset Flex CharStyle:Code
7813 \begin_layout Plain Layout
7822 \begin_inset Flex CharStyle:Code
7825 \begin_layout Plain Layout
7836 \begin_inset Flex CharStyle:Code
7839 \begin_layout Plain Layout
7845 ] Whether the class-default should be printing on one or both sides of the
7847 Can be changed in the
7848 \begin_inset Flex CharStyle:MenuItem
7851 \begin_layout Plain Layout
7852 Document\SpecialChar \menuseparator
7861 \begin_layout Description
7862 \begin_inset Flex CharStyle:Code
7865 \begin_layout Plain Layout
7871 This sequence defines a new paragraph style.
7872 If the style already exists, it will redefine some of its parameters instead.
7874 \begin_inset space ~
7878 \begin_inset CommandInset ref
7880 reference "sec:style"
7886 \begin_inset Quotes eld
7890 \begin_inset Flex CharStyle:Code
7893 \begin_layout Plain Layout
7900 \begin_inset Quotes erd
7906 \begin_layout Description
7907 \begin_inset Flex CharStyle:Code
7910 \begin_layout Plain Layout
7917 \begin_inset Flex CharStyle:Code
7920 \begin_layout Plain Layout
7926 ] The name of the command or environment to be used with
7927 \begin_inset Flex CharStyle:Code
7930 \begin_layout Plain Layout
7939 \begin_layout Description
7940 \begin_inset Flex CharStyle:Code
7943 \begin_layout Plain Layout
7950 \begin_inset Flex CharStyle:Code
7953 \begin_layout Plain Layout
7962 \begin_inset Flex CharStyle:Code
7965 \begin_layout Plain Layout
7971 ] Indicates what kind of markup is used to define the title of a document.
7973 \begin_inset Flex CharStyle:Code
7976 \begin_layout Plain Layout
7982 means that the macro with name
7983 \begin_inset Flex CharStyle:Code
7986 \begin_layout Plain Layout
7992 will be inserted after the last layout which has
7993 \begin_inset Quotes eld
7997 \begin_inset Flex CharStyle:Code
8000 \begin_layout Plain Layout
8007 \begin_inset Quotes erd
8012 \begin_inset Flex CharStyle:Code
8015 \begin_layout Plain Layout
8021 corresponds to the case where the block of paragraphs which have
8022 \begin_inset Quotes eld
8026 \begin_inset Flex CharStyle:Code
8029 \begin_layout Plain Layout
8036 \begin_inset Quotes erd
8039 should be enclosed into the
8040 \begin_inset Flex CharStyle:Code
8043 \begin_layout Plain Layout
8052 \begin_layout Description
8053 \begin_inset Flex CharStyle:Code
8056 \begin_layout Plain Layout
8062 Sets which divisions are included in the table of contents.
8064 \begin_inset Flex CharStyle:Code
8067 \begin_layout Plain Layout
8076 \begin_layout Subsection
8077 \begin_inset Flex CharStyle:Code
8080 \begin_layout Plain Layout
8089 \begin_layout Standard
8090 \begin_inset CommandInset label
8092 name "sec:classoptions"
8097 \begin_inset Flex CharStyle:Code
8100 \begin_layout Plain Layout
8106 section can contain the following entries:
8109 \begin_layout Description
8110 \begin_inset Flex CharStyle:Code
8113 \begin_layout Plain Layout
8120 \begin_inset Flex CharStyle:Code
8123 \begin_layout Plain Layout
8129 ] The list of available font sizes for the document's main font, separated
8131 \begin_inset Quotes eld
8135 \begin_inset Flex CharStyle:Code
8138 \begin_layout Plain Layout
8145 \begin_inset Quotes erd
8151 \begin_layout Description
8152 \begin_inset Flex CharStyle:Code
8155 \begin_layout Plain Layout
8161 Used to set the DTD line with XML-based output classes.
8163 \begin_inset space \thinspace{}
8167 \begin_inset Quotes eld
8170 -//OASIS//DTD DocBook V4.2//EN
8171 \begin_inset Quotes erd
8177 \begin_layout Description
8178 \begin_inset Flex CharStyle:Code
8181 \begin_layout Plain Layout
8188 \begin_inset Flex CharStyle:Code
8191 \begin_layout Plain Layout
8192 string="empty|plain|headings|fancy"
8197 ] The list of available page styles, separated by
8198 \begin_inset Quotes eld
8202 \begin_inset Flex CharStyle:Code
8205 \begin_layout Plain Layout
8212 \begin_inset Quotes erd
8218 \begin_layout Description
8219 \begin_inset Flex CharStyle:Code
8222 \begin_layout Plain Layout
8229 \begin_inset Flex CharStyle:Code
8232 \begin_layout Plain Layout
8238 ] Some document class options, separated by a comma, that will be added
8239 to the optional part of the
8240 \begin_inset Flex CharStyle:Code
8243 \begin_layout Plain Layout
8254 \begin_layout Standard
8256 \begin_inset Flex CharStyle:Code
8259 \begin_layout Plain Layout
8265 section must end with
8266 \begin_inset Quotes eld
8270 \begin_inset Flex CharStyle:Code
8273 \begin_layout Plain Layout
8280 \begin_inset Quotes erd
8286 \begin_layout Subsection
8290 \begin_layout Standard
8291 \begin_inset CommandInset label
8297 A paragraph style description looks like this:
8301 \begin_layout Plain Layout
8302 Note that this will either define a new layout or modify an existing one.
8310 \begin_layout LyX-Code
8317 \begin_layout LyX-Code
8321 \begin_layout LyX-Code
8325 \begin_layout Standard
8326 where the following commands are allowed:
8329 \begin_layout Description
8330 \begin_inset Flex CharStyle:Code
8333 \begin_layout Plain Layout
8340 \begin_inset Flex CharStyle:Code
8343 \begin_layout Plain Layout
8348 , left, right, center
8353 ] Paragraph alignment.
8356 \begin_layout Description
8357 \begin_inset Flex CharStyle:Code
8360 \begin_layout Plain Layout
8367 \begin_inset Flex CharStyle:Code
8370 \begin_layout Plain Layout
8375 , left, right, center
8380 ] A comma separated list of permitted alignments.
8381 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8383 For example a right-aligned or centered enumeration isn't possible.)
8386 \begin_layout Description
8387 \begin_inset Flex CharStyle:Code
8390 \begin_layout Plain Layout
8397 \begin_inset Flex CharStyle:Code
8400 \begin_layout Plain Layout
8410 \begin_layout Plain Layout
8411 Note that a `float' here is a real number, such as: 1.5.
8416 The vertical space with which the last of a chain of paragraphs with this
8417 layout is separated from the following paragraph.
8418 If the next paragraph has another layout, the separations are not simply
8419 added, but the maximum is taken.
8422 \begin_layout Description
8423 \begin_inset Flex CharStyle:Code
8426 \begin_layout Plain Layout
8433 \begin_inset Flex CharStyle:Code
8436 \begin_layout Plain Layout
8442 The category for this style.
8443 This is used to group related styles in the Layout combobox on the toolbar.
8444 Any string can be used, but you may want to use existing categories with
8449 \begin_layout Description
8450 \begin_inset Flex CharStyle:Code
8453 \begin_layout Plain Layout
8459 Depth of XML command.
8460 Used only with XML-type formats.
8463 \begin_layout Description
8464 \begin_inset Flex CharStyle:Code
8467 \begin_layout Plain Layout
8474 \begin_inset CommandInset label
8476 name "des:CopyStyle"
8481 \begin_inset Flex CharStyle:Code
8484 \begin_layout Plain Layout
8490 Copies all the features of an existing style into the current one.
8494 \begin_layout Description
8495 \begin_inset Flex CharStyle:Code
8498 \begin_layout Plain Layout
8504 The name of a style whose preamble should be output
8509 This allows to ensure some ordering of the preamble snippets when macros
8510 definitions depend on one another.
8514 \begin_layout Plain Layout
8515 Note that, besides that functionality, there is no way to ensure any ordering
8517 The ordering that you see in a given version of LyX may change without
8518 warning in later versions.
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
8545 , Box, Filled_Box, Static
8550 ] The type of label that stands at the end of the paragraph (or sequence
8552 \begin_inset Flex CharStyle:Code
8555 \begin_layout Plain Layout
8562 \begin_inset Flex CharStyle:Code
8565 \begin_layout Plain Layout
8572 \begin_inset Flex CharStyle:Code
8575 \begin_layout Plain Layout
8582 \begin_inset Flex CharStyle:Code
8585 \begin_layout Plain Layout
8593 \begin_inset Flex CharStyle:Code
8596 \begin_layout Plain Layout
8603 \begin_inset Quotes eld
8607 \begin_inset Quotes erd
8611 \begin_inset Flex CharStyle:Code
8614 \begin_layout Plain Layout
8621 \begin_inset Flex CharStyle:Code
8624 \begin_layout Plain Layout
8625 \begin_inset space ~
8634 \begin_inset space ~
8637 black) square suitable for end of proof markers,
8638 \begin_inset Flex CharStyle:Code
8641 \begin_layout Plain Layout
8647 is an explicit text string.
8650 \begin_layout Description
8651 \begin_inset Flex CharStyle:Code
8654 \begin_layout Plain Layout
8661 \begin_inset Flex CharStyle:Code
8664 \begin_layout Plain Layout
8670 ] The string used for a label with a
8671 \begin_inset Flex CharStyle:Code
8674 \begin_layout Plain Layout
8681 \begin_inset Flex CharStyle:Code
8684 \begin_layout Plain Layout
8694 \begin_layout Description
8695 \begin_inset Flex CharStyle:Code
8698 \begin_layout Plain Layout
8705 \begin_inset Flex CharStyle:Code
8708 \begin_layout Plain Layout
8719 \begin_inset Flex CharStyle:Code
8722 \begin_layout Plain Layout
8731 \begin_layout Description
8732 \begin_inset Flex CharStyle:Code
8735 \begin_layout Plain Layout
8742 \begin_inset Flex CharStyle:Code
8745 \begin_layout Plain Layout
8755 ] With this parameter the
8756 \begin_inset Flex CharStyle:MenuItem
8759 \begin_layout Plain Layout
8766 \begin_inset Quotes eld
8769 Vertical space above
8770 \begin_inset Quotes erd
8774 \begin_inset Flex CharStyle:MenuItem
8777 \begin_layout Plain Layout
8778 Edit\SpecialChar \menuseparator
8780 \begin_inset space ~
8788 dialog can be set when initializing a paragraph with this style.
8792 \begin_layout Plain Layout
8795 Note from Jean-Marc:
8797 I'm not sure that this setting has much use, and it should probably be
8798 removed in later versions.
8806 \begin_layout Description
8807 \begin_inset Flex CharStyle:Code
8810 \begin_layout Plain Layout
8816 The font used for both the text body
8822 \begin_inset space ~
8826 \begin_inset CommandInset ref
8828 reference "sec:fonts"
8833 Note that defining this font automatically defines the
8834 \begin_inset Flex CharStyle:Code
8837 \begin_layout Plain Layout
8844 So you should define this one first if you also want to define
8845 \begin_inset Flex CharStyle:Code
8848 \begin_layout Plain Layout
8857 \begin_layout Description
8858 \begin_inset Flex CharStyle:Code
8861 \begin_layout Plain Layout
8868 \begin_inset CommandInset label
8870 name "des:FreeSpacing"
8877 \begin_inset Flex CharStyle:Code
8880 \begin_layout Plain Layout
8891 \begin_inset Flex CharStyle:Code
8894 \begin_layout Plain Layout
8900 ] Usually LyX doesn't allow you to insert more than one space between words,
8901 since a space is considered as the separation between two words, not a
8902 character or symbol of its own.
8903 This is a very fine thing but sometimes annoying, for example, when typing
8904 program code or plain LaTeX code.
8906 \begin_inset Flex CharStyle:Code
8909 \begin_layout Plain Layout
8916 Note that LyX will create protected blanks for the additional blanks when
8917 in another mode than LaTeX-mode.
8920 \begin_layout Description
8921 \begin_inset Flex CharStyle:Code
8924 \begin_layout Plain Layout
8926 \change_inserted 0 1234613251
8928 \change_deleted 0 1234611266
8936 Language dependent information to be included in the LaTeX preamble when
8938 Note that this will completely override any prior
8939 \begin_inset Flex CharStyle:Code
8942 \begin_layout Plain Layout
8944 \change_inserted 0 1234613436
8946 \change_deleted 0 1234611275
8956 \begin_inset Quotes eld
8960 \begin_inset Flex CharStyle:Code
8963 \begin_layout Plain Layout
8965 \change_deleted 0 1234611280
8967 \change_inserted 0 1234613262
8976 \begin_inset Quotes erd
8980 The contents of this tag will occur once in the LaTeX preamble for each
8981 language used by the document.
8982 Each time, the following substitutions are made:
8986 \begin_layout Itemize
8987 \begin_inset Flex CharStyle:Code
8990 \begin_layout Plain Layout
8996 is replaced by the language name (as used by the babel package).
8999 \begin_layout Itemize
9001 \begin_inset Quotes eld
9005 \begin_inset Quotes erd
9009 \begin_inset Flex CharStyle:Code
9012 \begin_layout Plain Layout
9018 replaces its argument by the translation of the argument to the current
9020 \change_inserted 0 1234611470
9024 \begin_layout Standard
9026 \change_inserted 0 1234615134
9027 This preamble snippet will only be used if the document contains more than
9028 one language and the babel package is used.
9034 \begin_layout Description
9036 \change_inserted 0 1234614203
9037 \begin_inset Flex CharStyle:Code
9040 \begin_layout Plain Layout
9042 \change_inserted 0 1234614202
9049 \begin_inset Flex CharStyle:Code
9052 \begin_layout Plain Layout
9054 \change_inserted 0 1234614202
9060 , but this preamble snippet occurs independently from the babel package,
9061 and only for the document language.
9063 \begin_inset Quotes eld
9067 \begin_inset Flex CharStyle:Code
9070 \begin_layout Plain Layout
9072 \change_inserted 0 1234614202
9079 \begin_inset Quotes erd
9086 \begin_layout Standard
9087 If the style defines text that appears in the typeset document, it may use
9089 \begin_inset Flex CharStyle:Code
9092 \begin_layout Plain Layout
9094 \change_inserted 0 1234611302
9096 \change_deleted 0 1234611306
9105 \change_inserted 0 1234611823
9109 \change_inserted 0 1234611832
9111 \begin_inset Flex CharStyle:Code
9114 \begin_layout Plain Layout
9116 \change_inserted 0 1234611838
9124 to support non-english and even multilanguage documents correctly.
9125 The following excerpt (from the
9126 \begin_inset Flex CharStyle:Code
9129 \begin_layout Plain Layout
9135 file) shows how this works:
9138 \begin_layout LyX-Code
9142 \begin_layout LyX-Code
9144 \change_deleted 0 1234612061
9152 \begin_layout LyX-Code
9155 theoremstyle{remark}
9158 \begin_layout LyX-Code
9161 newtheorem{claim}[thm]{
9168 \begin_layout LyX-Code
9172 \begin_layout LyX-Code
9174 \change_inserted 0 1234612037
9178 \begin_layout LyX-Code
9180 \change_inserted 0 1234612045
9185 claimname}{_(Claim)}
9188 \begin_layout LyX-Code
9190 \change_inserted 0 1234611897
9194 \begin_layout LyX-Code
9196 \change_inserted 0 1234612050
9200 \begin_layout LyX-Code
9202 \change_inserted 0 1234611892
9204 \change_deleted 0 1234611847
9210 \begin_layout LyX-Code
9212 \change_deleted 0 1234612079
9228 \begin_layout LyX-Code
9237 claimname}{_(Claim)}}
9238 \change_deleted 0 1234612086
9242 \begin_layout LyX-Code
9244 \change_deleted 0 1234612089
9252 \begin_layout LyX-Code
9254 \change_inserted 0 1234611859
9256 \change_deleted 0 1234611856
9262 \begin_layout Standard
9263 The key to correct translation of the user visible text is the definition
9265 \begin_inset Flex CharStyle:Code
9268 \begin_layout Plain Layout
9277 \change_inserted 0 1234612144
9279 \change_deleted 0 1234612146
9283 This command holds the name of the theorem that will appear in the output.
9285 \begin_inset Flex CharStyle:Code
9288 \begin_layout Plain Layout
9290 \change_inserted 0 1234612157
9292 \change_deleted 0 1234612155
9300 then uses the commands offered by the babel package to redefine
9301 \begin_inset Flex CharStyle:Code
9304 \begin_layout Plain Layout
9312 for each used language
9313 \change_inserted 0 1234622073
9314 in multilanguage documents
9318 \change_deleted 0 1234612171
9320 \begin_inset Flex CharStyle:Code
9323 \begin_layout Plain Layout
9333 test ensures that no LaTeX error occurs in documents that do not use babel.
9334 Since LyX loads babel after the style-specific preamble, the whole command
9335 is deferred to the actual start of the document with
9336 \begin_inset Flex CharStyle:Code
9339 \begin_layout Plain Layout
9353 \begin_layout Description
9354 \begin_inset Flex CharStyle:Code
9357 \begin_layout Plain Layout
9363 [[FIXME]] (Used only with XML-type formats.)
9366 \begin_layout Description
9367 \begin_inset Flex CharStyle:Code
9370 \begin_layout Plain Layout
9377 \begin_inset Flex CharStyle:Code
9380 \begin_layout Plain Layout
9386 If 1, marks the layout as being part of a title block (see also the
9387 \begin_inset Flex CharStyle:Code
9390 \begin_layout Plain Layout
9397 \begin_inset Flex CharStyle:Code
9400 \begin_layout Plain Layout
9409 \begin_layout Description
9410 \begin_inset Flex CharStyle:Code
9413 \begin_layout Plain Layout
9420 \begin_inset Flex CharStyle:Code
9423 \begin_layout Plain Layout
9429 ] This provides extra space between paragraphs that have the same layout.
9430 If you put other layouts into an environment, each is separated with the
9432 \begin_inset Flex CharStyle:Code
9435 \begin_layout Plain Layout
9442 But the whole items of the environment are additionally separated with
9444 \begin_inset Flex CharStyle:Code
9447 \begin_layout Plain Layout
9459 \begin_layout Description
9460 \begin_inset Flex CharStyle:Code
9463 \begin_layout Plain Layout
9469 [[FIXME]] (Used only with XML-type formats.)
9472 \begin_layout Description
9473 \begin_inset Flex CharStyle:Code
9476 \begin_layout Plain Layout
9483 \begin_inset CommandInset label
9485 name "des:KeepEmpty"
9492 \begin_inset Flex CharStyle:Code
9495 \begin_layout Plain Layout
9506 \begin_inset Flex CharStyle:Code
9509 \begin_layout Plain Layout
9515 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9516 lead to empty LaTeX output.
9517 There are some cases where this could be desirable however: in a letter
9518 template, the required fields can be provided as empty fields, so that
9519 people do not forget them; in some special classes, a layout can be used
9520 as some kind of break, which does not contain actual text.
9523 \begin_layout Description
9524 \begin_inset Flex CharStyle:Code
9527 \begin_layout Plain Layout
9533 [float=0] The vertical space between the label and the text body.
9534 Only used for labels that are above the text body (
9535 \begin_inset Flex CharStyle:Code
9538 \begin_layout Plain Layout
9545 \begin_inset Flex CharStyle:Code
9548 \begin_layout Plain Layout
9549 Centered_Top_Environment
9557 \begin_layout Description
9558 \begin_inset Flex CharStyle:Code
9561 \begin_layout Plain Layout
9568 \begin_inset Flex CharStyle:Code
9571 \begin_layout Plain Layout
9578 \begin_inset Newline newline
9581 The name of the counter for automatic numbering (see Section
9582 \begin_inset CommandInset ref
9584 reference "sec:counter"
9589 This must be given if
9590 \begin_inset Flex CharStyle:Code
9593 \begin_layout Plain Layout
9600 \begin_inset Flex CharStyle:Code
9603 \begin_layout Plain Layout
9612 \begin_layout Description
9613 \begin_inset Flex CharStyle:Code
9616 \begin_layout Plain Layout
9622 The font used for the label.
9624 \begin_inset space ~
9628 \begin_inset CommandInset ref
9630 reference "sec:fonts"
9637 \begin_layout Description
9638 \begin_inset Flex CharStyle:Code
9641 \begin_layout Plain Layout
9647 Text that indicates how far a label should be indented.
9650 \begin_layout Description
9651 \begin_inset Flex CharStyle:Code
9654 \begin_layout Plain Layout
9661 \begin_inset Flex CharStyle:Code
9664 \begin_layout Plain Layout
9670 ] The horizontal space between the label and the text body.
9671 Only used for labels that are not above the text body.
9674 \begin_layout Description
9675 \begin_inset Flex CharStyle:Code
9678 \begin_layout Plain Layout
9685 \begin_inset Flex CharStyle:Code
9688 \begin_layout Plain Layout
9694 ] The string used for a label with a
9695 \begin_inset Flex CharStyle:Code
9698 \begin_layout Plain Layout
9706 \begin_inset Flex CharStyle:Code
9709 \begin_layout Plain Layout
9715 is set, this string can be contain the special formatting commands described
9717 \begin_inset CommandInset ref
9719 reference "sec:counter"
9727 \begin_layout Plain Layout
9728 For the sake of backwards compatibility, the string
9729 \begin_inset Flex CharStyle:Code
9732 \begin_layout Plain Layout
9742 will be replaced by the expanded
9743 \begin_inset Flex CharStyle:Code
9746 \begin_layout Plain Layout
9753 \begin_inset Flex CharStyle:Code
9756 \begin_layout Plain Layout
9765 This feature is now obsolete and should be replaced by the mechanisms of
9767 \begin_inset CommandInset ref
9769 reference "sec:counter"
9781 \begin_layout Description
9782 \begin_inset Flex CharStyle:Code
9785 \begin_layout Plain Layout
9792 \begin_inset Flex CharStyle:Code
9795 \begin_layout Plain Layout
9801 ] This is used inside the appendix instead of
9802 \begin_inset Flex CharStyle:Code
9805 \begin_layout Plain Layout
9813 \begin_inset Flex CharStyle:Code
9816 \begin_layout Plain Layout
9823 \begin_inset Flex CharStyle:Code
9826 \begin_layout Plain Layout
9835 \begin_layout Description
9836 \begin_inset Flex CharStyle:Code
9839 \begin_layout Plain Layout
9845 [FIXME] (Used only with XML-type formats.)
9848 \begin_layout Description
9849 \begin_inset Flex CharStyle:Code
9852 \begin_layout Plain Layout
9859 \begin_inset Flex CharStyle:Code
9862 \begin_layout Plain Layout
9867 , Manual, Static, Top_Environment,
9868 \begin_inset Newline newline
9871 Centered_Top_Environment, Sensitive, Counter
9877 \begin_inset Newline newline
9881 \begin_inset Flex CharStyle:Code
9884 \begin_layout Plain Layout
9890 means the label is the very first word (up to the first real blank).
9894 \begin_layout Plain Layout
9895 Use protected spaces if you want more than one word as the label.
9901 \begin_inset Flex CharStyle:Code
9904 \begin_layout Plain Layout
9910 means it is defined in the layout (see
9911 \begin_inset Flex CharStyle:Code
9914 \begin_layout Plain Layout
9922 \begin_inset Flex CharStyle:Code
9925 \begin_layout Plain Layout
9932 \begin_inset Flex CharStyle:Code
9935 \begin_layout Plain Layout
9936 Centered_Top_Environment
9941 are special cases of
9942 \begin_inset Flex CharStyle:Code
9945 \begin_layout Plain Layout
9952 The label will be printed above the paragraph, but only at the top of an
9953 environment or the top of a chain of paragraphs with this layout.
9954 Usage is for example the
9955 \begin_inset Flex CharStyle:MenuItem
9958 \begin_layout Plain Layout
9965 \begin_inset Flex CharStyle:MenuItem
9968 \begin_layout Plain Layout
9975 This is also the case for
9976 \begin_inset Flex CharStyle:Code
9979 \begin_layout Plain Layout
9985 labels with latex type
9986 \begin_inset Flex CharStyle:Code
9989 \begin_layout Plain Layout
9995 , in order to make layouts for theorems work correctly.
9997 \begin_inset Flex CharStyle:Code
10000 \begin_layout Plain Layout
10006 is a special case for the caption-labels
10007 \begin_inset Quotes eld
10011 \begin_inset Quotes erd
10015 \begin_inset Quotes eld
10019 \begin_inset Quotes erd
10024 \begin_inset Flex CharStyle:Code
10027 \begin_layout Plain Layout
10033 means the (hardcoded) label string depends on the kind of float.
10035 \begin_inset Flex CharStyle:Code
10038 \begin_layout Plain Layout
10044 label type defines automatically numbered labels.
10046 \begin_inset CommandInset ref
10048 reference "sec:counter"
10055 \begin_layout Description
10056 \begin_inset Flex CharStyle:Code
10059 \begin_layout Plain Layout
10065 The name of the corresponding LaTeX stuff.
10066 Either the environment or command name.
10069 \begin_layout Description
10070 \begin_inset Flex CharStyle:Code
10073 \begin_layout Plain Layout
10079 An optional parameter for the corresponding
10080 \begin_inset Flex CharStyle:Code
10083 \begin_layout Plain Layout
10090 This parameter cannot be changed from within LyX.
10093 \begin_layout Description
10094 \begin_inset Flex CharStyle:Code
10097 \begin_layout Plain Layout
10104 \begin_inset CommandInset label
10106 name "des:LatexType"
10111 \begin_inset Flex CharStyle:Code
10114 \begin_layout Plain Layout
10119 , Command, Environment, Item_Environment,
10125 \begin_inset Flex CharStyle:Code
10128 \begin_layout Plain Layout
10134 ] How the layout should be translated into LaTeX.
10136 \begin_inset Flex CharStyle:Code
10139 \begin_layout Plain Layout
10145 means nothing special.
10147 \begin_inset Flex CharStyle:Code
10150 \begin_layout Plain Layout
10157 \begin_inset Flex CharStyle:Code
10160 \begin_layout Plain Layout
10167 {\SpecialChar \ldots{}
10174 \begin_inset Flex CharStyle:Code
10177 \begin_layout Plain Layout
10184 \begin_inset Flex CharStyle:Code
10187 \begin_layout Plain Layout
10194 }\SpecialChar \ldots{}
10208 \begin_inset Flex CharStyle:Code
10211 \begin_layout Plain Layout
10218 \begin_inset Flex CharStyle:Code
10221 \begin_layout Plain Layout
10228 \begin_inset Flex CharStyle:Code
10231 \begin_layout Plain Layout
10239 is generated for each paragraph of this environment.
10241 \begin_inset Flex CharStyle:Code
10244 \begin_layout Plain Layout
10251 \begin_inset Flex CharStyle:Code
10254 \begin_layout Plain Layout
10261 \begin_inset Flex CharStyle:Code
10264 \begin_layout Plain Layout
10270 is passed as an argument to the environment.
10272 \begin_inset Flex CharStyle:Code
10275 \begin_layout Plain Layout
10281 can be defined in the
10282 \begin_inset Flex CharStyle:MenuItem
10285 \begin_layout Plain Layout
10290 ayout\SpecialChar \menuseparator
10302 \begin_inset Flex CharStyle:Code
10305 \begin_layout Plain Layout
10313 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10314 Visit the SGML class files for specific examples.
10317 \begin_layout Standard
10318 Putting the last few things together, the LaTeX output will be either:
10321 \begin_layout LyX-Code
10324 latexname[latexparam]{\SpecialChar \ldots{}
10328 \begin_layout Standard
10332 \begin_layout LyX-Code
10335 begin{latexname}[latexparam] \SpecialChar \ldots{}
10341 \begin_layout Standard
10342 depending upon the LaTeX type.
10345 \begin_layout Description
10346 \begin_inset Flex CharStyle:Code
10349 \begin_layout Plain Layout
10356 \begin_inset Flex CharStyle:Code
10359 \begin_layout Plain Layout
10365 ] If you put layouts into environments, the leftmargins are not simply added,
10366 but added with a factor
10367 \begin_inset Formula $\frac{4}{depth+4}$
10371 Note that this parameter is also used when the margin is defined as
10372 \begin_inset Flex CharStyle:Code
10375 \begin_layout Plain Layout
10382 \begin_inset Flex CharStyle:Code
10385 \begin_layout Plain Layout
10392 Then it is added to the manual or dynamic margin.
10394 \begin_inset Newline newline
10397 The argument is passed as a string.
10399 \begin_inset Quotes eld
10403 \begin_inset Flex CharStyle:Code
10406 \begin_layout Plain Layout
10413 \begin_inset Quotes erd
10416 means that the paragraph is indented with the width of
10417 \begin_inset Quotes eld
10421 \begin_inset Flex CharStyle:Code
10424 \begin_layout Plain Layout
10431 \begin_inset Quotes erd
10434 in the normal font.
10435 You can get a negative width by prefixing the string with
10436 \begin_inset Quotes eld
10440 \begin_inset Flex CharStyle:Code
10443 \begin_layout Plain Layout
10450 \begin_inset Quotes erd
10454 This way was chosen so that the look is the same with each used screen
10459 \begin_layout Description
10460 \begin_inset Flex CharStyle:Code
10463 \begin_layout Plain Layout
10470 \begin_inset Flex CharStyle:Code
10473 \begin_layout Plain Layout
10478 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10484 \begin_inset Newline newline
10487 The kind of margin that the layout has on the left side.
10489 \begin_inset Flex CharStyle:Code
10492 \begin_layout Plain Layout
10498 just means a fixed margin.
10500 \begin_inset Flex CharStyle:Code
10503 \begin_layout Plain Layout
10509 means that the left margin depends on the string entered in the
10510 \begin_inset Flex CharStyle:MenuItem
10513 \begin_layout Plain Layout
10514 Edit\SpecialChar \menuseparator
10516 \begin_inset space ~
10525 This is used to typeset nice lists without tabulators.
10527 \begin_inset Flex CharStyle:Code
10530 \begin_layout Plain Layout
10536 means that the margin depends on the size of the label.
10537 This is used for automatic enumerated headlines.
10538 It is obvious that the headline
10539 \begin_inset Quotes eld
10542 5.4.3.2.1 Very long headline
10543 \begin_inset Quotes erd
10546 must have a wider left margin (as wide as
10547 \begin_inset Quotes eld
10551 \begin_inset Quotes erd
10554 plus the space) than
10555 \begin_inset Quotes eld
10558 3.2 Very long headline
10559 \begin_inset Quotes erd
10563 \begin_inset Quotes eld
10567 \begin_inset Quotes erd
10570 are not able to do this.
10572 \begin_inset Flex CharStyle:Code
10575 \begin_layout Plain Layout
10581 is similar, but only the very first row of the paragraph is dynamic, while
10582 the others are static; this is used, for example, for descriptions.
10584 \begin_inset Flex CharStyle:Code
10587 \begin_layout Plain Layout
10593 means the margin is chosen in a way that the longest row of this paragraph
10594 fits to the right margin.
10595 This is used to typeset an address on the right edge of the page.
10598 \begin_layout Description
10599 \begin_inset Flex CharStyle:Code
10602 \begin_layout Plain Layout
10609 \begin_inset Flex CharStyle:Code
10612 \begin_layout Plain Layout
10621 \begin_inset Flex CharStyle:Code
10624 \begin_layout Plain Layout
10630 ] Whether fragile commands in this layout should be
10631 \begin_inset Flex CharStyle:Code
10634 \begin_layout Plain Layout
10647 whether this command should itself be protected.)
10650 \begin_layout Description
10651 \begin_inset Flex CharStyle:Code
10654 \begin_layout Plain Layout
10661 \begin_inset Flex CharStyle:Code
10664 \begin_layout Plain Layout
10671 \begin_inset Flex CharStyle:Code
10674 \begin_layout Plain Layout
10682 ] Whether newlines are translated into LaTeX newlines (
10683 \begin_inset Flex CharStyle:Code
10686 \begin_layout Plain Layout
10697 The translation can be switched off to allow more comfortable LaTeX editing
10701 \begin_layout Description
10702 \begin_inset Flex CharStyle:Code
10705 \begin_layout Plain Layout
10712 \begin_inset Flex CharStyle:Code
10715 \begin_layout Plain Layout
10722 \begin_inset Flex CharStyle:Code
10725 \begin_layout Plain Layout
10733 ] Whether the following Paragraph is allowed to indent its very first row.
10735 \begin_inset Flex CharStyle:Code
10738 \begin_layout Plain Layout
10744 means that it is not allowed to do so;
10745 \begin_inset Flex CharStyle:Code
10748 \begin_layout Plain Layout
10754 means it could do so if it wants to.
10757 \begin_layout Description
10758 \begin_inset Flex CharStyle:Code
10761 \begin_layout Plain Layout
10767 Name of a layout that has replaced this layout.
10768 This is used to rename a layout, while keeping backward compatibility.
10771 \begin_layout Description
10772 \begin_inset Flex CharStyle:Code
10775 \begin_layout Plain Layout
10782 \begin_inset Flex CharStyle:Code
10785 \begin_layout Plain Layout
10791 ] The number of optional arguments that can be used with this layout.
10792 This is useful for things like section headings, and only makes sense with
10796 \begin_layout Description
10797 \begin_inset Flex CharStyle:Code
10800 \begin_layout Plain Layout
10807 \begin_inset Flex CharStyle:Code
10810 \begin_layout Plain Layout
10816 ] The indent of the very first line of a paragraph.
10818 \begin_inset Flex CharStyle:Code
10821 \begin_layout Plain Layout
10827 will be fixed for a certain layout.
10828 The exception is Standard layout, since the indentation of a Standard layout
10829 paragraph can be prohibited with
10830 \begin_inset Flex CharStyle:Code
10833 \begin_layout Plain Layout
10840 Also, Standard layout paragraphs inside environments use the
10841 \begin_inset Flex CharStyle:Code
10844 \begin_layout Plain Layout
10850 of the environment, not their native one.
10851 For example, Standard paragraphs inside an enumeration are not indented.
10854 \begin_layout Description
10855 \begin_inset Flex CharStyle:Code
10858 \begin_layout Plain Layout
10865 \begin_inset Flex CharStyle:Code
10868 \begin_layout Plain Layout
10874 ] The vertical space between two paragraphs of this layout.
10877 \begin_layout Description
10878 \begin_inset Flex CharStyle:Code
10881 \begin_layout Plain Layout
10888 \begin_inset Flex CharStyle:Code
10891 \begin_layout Plain Layout
10897 ] LyX allows the user to choose either
10898 \begin_inset Quotes eld
10902 \begin_inset Quotes erd
10906 \begin_inset Quotes eld
10910 \begin_inset Quotes erd
10913 to typeset a document.
10915 \begin_inset Quotes eld
10919 \begin_inset Quotes erd
10922 is chosen, this value is completely ignored.
10924 \begin_inset Quotes eld
10928 \begin_inset Quotes erd
10931 is chosen, the parindent of a LaTeXtype
10932 \begin_inset Quotes eld
10936 \begin_inset Quotes erd
10939 layout is ignored and all paragraphs are separated by this parskip argument.
10940 The vertical space is calculated with
10941 \begin_inset Flex CharStyle:Code
10944 \begin_layout Plain Layout
10946 \begin_inset space ~
10955 \begin_inset Flex CharStyle:Code
10958 \begin_layout Plain Layout
10964 is the height of a row with the normal font.
10965 This way, the look stays the same with different screen fonts.
10968 \begin_layout Description
10969 \begin_inset Flex CharStyle:Code
10972 \begin_layout Plain Layout
10979 \begin_inset CommandInset label
10981 name "des:PathThru"
10988 \begin_inset Flex CharStyle:Code
10991 \begin_layout Plain Layout
11002 \begin_inset Flex CharStyle:Code
11005 \begin_layout Plain Layout
11011 ] Whether the contents of this paragraph should be output in raw form, meaning
11012 without special translations that LaTeX would require.
11015 \begin_layout Description
11016 \begin_inset Flex CharStyle:Code
11019 \begin_layout Plain Layout
11026 \begin_inset CommandInset label
11028 name "des:Preamble"
11032 Information to be included in the LaTeX preamble when this style is used.
11033 Used to define macros, load packages, etc., required by this particular
11036 \begin_inset Quotes eld
11040 \begin_inset Flex CharStyle:Code
11043 \begin_layout Plain Layout
11050 \begin_inset Quotes erd
11056 \begin_layout Description
11057 \begin_inset Flex CharStyle:Code
11060 \begin_layout Plain Layout
11067 \begin_inset Flex CharStyle:Code
11070 \begin_layout Plain Layout
11077 \begin_inset CommandInset label
11079 name "des:Requires"
11083 Whether the layout requires the feature
11084 \begin_inset Flex CharStyle:Code
11087 \begin_layout Plain Layout
11094 See the description of
11095 \begin_inset Flex CharStyle:Code
11098 \begin_layout Plain Layout
11105 \begin_inset CommandInset ref
11106 LatexCommand pageref
11107 reference "des:FreeSpacing"
11111 ) for information on `features'.
11115 \begin_layout Description
11116 \begin_inset Flex CharStyle:Code
11119 \begin_layout Plain Layout
11126 \begin_inset Flex CharStyle:Code
11129 \begin_layout Plain Layout
11136 \begin_inset Flex CharStyle:Code
11139 \begin_layout Plain Layout
11148 \begin_layout Description
11149 \begin_inset Flex CharStyle:Code
11152 \begin_layout Plain Layout
11159 \begin_inset Flex CharStyle:Code
11162 \begin_layout Plain Layout
11167 , onehalf, double, other
11176 ] This defines what the default spacing should be in the layout.
11178 \begin_inset Flex CharStyle:Code
11181 \begin_layout Plain Layout
11188 \begin_inset Flex CharStyle:Code
11191 \begin_layout Plain Layout
11198 \begin_inset Flex CharStyle:Code
11201 \begin_layout Plain Layout
11207 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11208 If you specify the argument
11209 \begin_inset Flex CharStyle:Code
11212 \begin_layout Plain Layout
11218 , then you should also provide a numerical argument which will be the actual
11220 Note that, contrary to other parameters,
11221 \begin_inset Flex CharStyle:Code
11224 \begin_layout Plain Layout
11230 implies the generation of specific LaTeX code, using the package
11233 \begin_inset Flex CharStyle:Code
11236 \begin_layout Plain Layout
11245 \begin_layout Description
11246 \begin_inset Flex CharStyle:Code
11249 \begin_layout Plain Layout
11255 The font used for the text body .
11257 \begin_inset CommandInset ref
11259 reference "sec:fonts"
11266 \begin_layout Description
11267 \begin_inset Flex CharStyle:Code
11270 \begin_layout Plain Layout
11278 The level of the style in the table of contents.
11279 This is used for automatic numbering of section headings.
11282 \begin_layout Description
11283 \begin_inset Flex CharStyle:Code
11286 \begin_layout Plain Layout
11293 \begin_inset Flex CharStyle:Code
11296 \begin_layout Plain Layout
11302 ] The vertical space with which the very first of a chain of paragraphs
11303 with this layout is separated from the previous paragraph.
11304 If the previous paragraph has another layout, the separations are not simply
11305 added, but the maximum is taken.
11308 \begin_layout Subsection
11312 \begin_layout Standard
11313 \begin_inset CommandInset label
11319 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11320 define the floats (
11321 \begin_inset Flex CharStyle:MenuItem
11324 \begin_layout Plain Layout
11331 \begin_inset Flex CharStyle:MenuItem
11334 \begin_layout Plain Layout
11340 , \SpecialChar \ldots{}
11341 ) in the text class itself.
11342 Standard floats are included in the file
11343 \begin_inset Flex CharStyle:Code
11346 \begin_layout Plain Layout
11352 , so you may have to do no more than add
11355 \begin_layout LyX-Code
11356 Input stdfloats.inc
11359 \begin_layout Standard
11360 to your layout file.
11361 If you want to implement a text class that proposes some other float types
11362 (like the AGU class bundled with LyX), the information below will hopefully
11366 \begin_layout Description
11367 \begin_inset Flex CharStyle:Code
11370 \begin_layout Plain Layout
11377 \begin_inset Flex CharStyle:Code
11380 \begin_layout Plain Layout
11387 \begin_inset Quotes erd
11391 \begin_inset Quotes erd
11394 ] The file name extension of an auxiliary file for the list of figures (or
11396 LaTeX writes the captions to this file.
11399 \begin_layout Description
11400 \begin_inset Flex CharStyle:Code
11403 \begin_layout Plain Layout
11410 \begin_inset Flex CharStyle:Code
11413 \begin_layout Plain Layout
11420 \begin_inset Quotes erd
11424 \begin_inset Quotes erd
11427 ] The string that will be used in the menus and also for the caption.
11430 \begin_layout Description
11431 \begin_inset Flex CharStyle:Code
11434 \begin_layout Plain Layout
11441 \begin_inset Flex CharStyle:Code
11444 \begin_layout Plain Layout
11453 \begin_inset Flex CharStyle:Code
11456 \begin_layout Plain Layout
11463 \begin_inset Flex CharStyle:Code
11466 \begin_layout Plain Layout
11472 if the float is already defined by the LaTeX document class.
11474 \begin_inset Flex CharStyle:Code
11477 \begin_layout Plain Layout
11483 , the float will be defined using the LaTeX package
11484 \begin_inset Flex CharStyle:Code
11487 \begin_layout Plain Layout
11496 \begin_layout Description
11497 \begin_inset Flex CharStyle:Code
11500 \begin_layout Plain Layout
11507 \begin_inset Flex CharStyle:Code
11510 \begin_layout Plain Layout
11517 \begin_inset Quotes erd
11521 \begin_inset Quotes erd
11524 ] The heading used for the list of floats.
11527 \begin_layout Description
11528 \begin_inset Flex CharStyle:Code
11531 \begin_layout Plain Layout
11538 \begin_inset Flex CharStyle:Code
11541 \begin_layout Plain Layout
11548 \begin_inset Quotes erd
11552 \begin_inset Quotes erd
11555 ] This (optional) argument determines whether floats of this class will
11556 be numbered within some sectional unit of the document.
11557 For example, if within is equal to
11558 \begin_inset Flex CharStyle:Code
11561 \begin_layout Plain Layout
11567 , the floats will be numbered within chapters.
11571 \begin_layout Description
11572 \begin_inset Flex CharStyle:Code
11575 \begin_layout Plain Layout
11582 \begin_inset Flex CharStyle:Code
11585 \begin_layout Plain Layout
11592 \begin_inset Quotes erd
11596 \begin_inset Quotes erd
11599 ] The default placement for the given class of floats.
11600 The string should be as in standard LaTeX:
11601 \begin_inset Flex CharStyle:Code
11604 \begin_layout Plain Layout
11611 \begin_inset Flex CharStyle:Code
11614 \begin_layout Plain Layout
11621 \begin_inset Flex CharStyle:Code
11624 \begin_layout Plain Layout
11631 \begin_inset Flex CharStyle:Code
11634 \begin_layout Plain Layout
11640 for top, bottom, page, and here, respectively.
11644 \begin_layout Plain Layout
11645 Note that the order of these letters in the string is irrelevant, like in
11651 On top of that there is a new type,
11652 \begin_inset Flex CharStyle:Code
11655 \begin_layout Plain Layout
11661 , which does not really correspond to a float, since it means: put it
11662 \begin_inset Quotes eld
11666 \begin_inset Quotes erd
11670 Note however that the
11671 \begin_inset Flex CharStyle:Code
11674 \begin_layout Plain Layout
11680 specifier is special and, because of implementation details, cannot be
11681 used in non-built in float types.
11682 If you do not understand what this means, just use
11683 \begin_inset Quotes eld
11687 \begin_inset Flex CharStyle:Code
11690 \begin_layout Plain Layout
11697 \begin_inset Quotes erd
11703 \begin_layout Description
11704 \begin_inset Flex CharStyle:Code
11707 \begin_layout Plain Layout
11714 \begin_inset Flex CharStyle:Code
11717 \begin_layout Plain Layout
11724 \begin_inset Quotes erd
11728 \begin_inset Quotes erd
11731 ] The style used when defining the float using
11732 \begin_inset Flex CharStyle:Code
11735 \begin_layout Plain Layout
11746 \begin_layout Description
11747 \begin_inset Flex CharStyle:Code
11750 \begin_layout Plain Layout
11757 \begin_inset Flex CharStyle:Code
11760 \begin_layout Plain Layout
11767 \begin_inset Quotes erd
11771 \begin_inset Quotes erd
11775 \begin_inset Quotes eld
11779 \begin_inset Quotes erd
11782 of the new class of floats, like program or algorithm.
11783 After the appropriate
11784 \begin_inset Flex CharStyle:Code
11787 \begin_layout Plain Layout
11796 \begin_inset Flex CharStyle:Code
11799 \begin_layout Plain Layout
11808 \begin_inset Flex CharStyle:Code
11811 \begin_layout Plain Layout
11822 \begin_layout Standard
11823 Note that defining a float with type
11824 \begin_inset Flex CharStyle:Code
11827 \begin_layout Plain Layout
11835 automatically defines the corresponding counter with name
11836 \begin_inset Flex CharStyle:Code
11839 \begin_layout Plain Layout
11850 \begin_layout Subsection
11851 Flex insets and InsetLayout
11854 \begin_layout Standard
11855 \begin_inset CommandInset label
11857 name "sec:charstyle"
11861 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11862 these are called Flex insets.
11866 \begin_layout Standard
11867 Flex insets come in three different kinds:
11870 \begin_layout Itemize
11872 \begin_inset Flex CharStyle:Code
11875 \begin_layout Plain Layout
11881 ): These define semantic markup corresponding to such LaTeX commands as
11883 \begin_inset Flex CharStyle:Code
11886 \begin_layout Plain Layout
11895 \begin_inset Flex CharStyle:Code
11898 \begin_layout Plain Layout
11909 \begin_layout Itemize
11911 \begin_inset Flex CharStyle:Code
11914 \begin_layout Plain Layout
11920 ): These can be used to define custom collapsible insets, similar to TeX
11921 code, footnote, and the like.
11922 An obvious example is an endnote inset, which is defined in the
11923 \begin_inset Flex CharStyle:Code
11926 \begin_layout Plain Layout
11935 \begin_layout Itemize
11937 \begin_inset Flex CharStyle:Code
11940 \begin_layout Plain Layout
11946 ): For use with DocBook classes.
11949 \begin_layout Standard
11950 Flex insets are defined using the
11951 \begin_inset Flex CharStyle:Code
11954 \begin_layout Plain Layout
11960 tag, which shall be explained in a moment.
11963 \begin_layout Standard
11965 \begin_inset Flex CharStyle:Code
11968 \begin_layout Plain Layout
11974 tag also serves another function: It can be used to customize the general
11975 layout of many different types of insets.
11977 \begin_inset Flex CharStyle:Code
11980 \begin_layout Plain Layout
11986 can be used to customize the layout parameters for footnotes, marginal
11987 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11988 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11989 define Flex insets.
11992 \begin_layout Standard
11994 \begin_inset Flex CharStyle:Code
11997 \begin_layout Plain Layout
12003 definition must begin with a line of the form:
12006 \begin_layout LyX-Code
12010 \begin_layout Standard
12012 \begin_inset Flex CharStyle:Code
12015 \begin_layout Plain Layout
12021 indicates the inset whose layout is being defined, and here there are two
12025 \begin_layout Enumerate
12026 The layout for a pre-existing inset is being modified.
12027 In this case, can be
12028 \begin_inset Flex CharStyle:Code
12031 \begin_layout Plain Layout
12037 any one of the following:
12038 \begin_inset Flex CharStyle:Code
12041 \begin_layout Plain Layout
12048 \begin_inset Flex CharStyle:Code
12051 \begin_layout Plain Layout
12058 \begin_inset Flex CharStyle:Code
12061 \begin_layout Plain Layout
12068 \begin_inset Flex CharStyle:Code
12071 \begin_layout Plain Layout
12078 \begin_inset Flex CharStyle:Code
12081 \begin_layout Plain Layout
12088 \begin_inset Flex CharStyle:Code
12091 \begin_layout Plain Layout
12098 \begin_inset Flex CharStyle:Code
12101 \begin_layout Plain Layout
12108 \begin_inset Flex CharStyle:Code
12111 \begin_layout Plain Layout
12118 \begin_inset Flex CharStyle:Code
12121 \begin_layout Plain Layout
12128 \begin_inset Flex CharStyle:Code
12131 \begin_layout Plain Layout
12138 \begin_inset Flex CharStyle:Code
12141 \begin_layout Plain Layout
12148 \begin_inset Flex CharStyle:Code
12151 \begin_layout Plain Layout
12158 \begin_inset Flex CharStyle:Code
12161 \begin_layout Plain Layout
12168 \begin_inset Flex CharStyle:Code
12171 \begin_layout Plain Layout
12178 \begin_inset Flex CharStyle:Code
12181 \begin_layout Plain Layout
12188 \begin_inset Flex CharStyle:Code
12191 \begin_layout Plain Layout
12198 \begin_inset Flex CharStyle:Code
12201 \begin_layout Plain Layout
12208 \begin_inset Flex CharStyle:Code
12211 \begin_layout Plain Layout
12218 \begin_inset Flex CharStyle:Code
12221 \begin_layout Plain Layout
12228 \begin_inset Flex CharStyle:Code
12231 \begin_layout Plain Layout
12241 \begin_layout Enumerate
12242 The layout for a Flex inset is being defined.
12244 \begin_inset Flex CharStyle:Code
12247 \begin_layout Plain Layout
12253 can be any valid identifier not used by a pre-existing inset.
12254 Note that the definition of a flex inset must
12259 \begin_inset Flex CharStyle:Code
12262 \begin_layout Plain Layout
12271 \begin_layout Standard
12273 \begin_inset Flex CharStyle:Code
12276 \begin_layout Plain Layout
12282 definition can contain the following entries:
12285 \begin_layout Description
12286 \begin_inset Flex CharStyle:Code
12289 \begin_layout Plain Layout
12295 The color for the inset's background.
12296 The valid colors are defined in
12297 \begin_inset Flex CharStyle:Code
12300 \begin_layout Plain Layout
12309 \begin_layout Description
12310 \begin_inset Flex CharStyle:Code
12313 \begin_layout Plain Layout
12319 As with paragraph styles (see page
12320 \begin_inset CommandInset ref
12322 reference "des:CopyStyle"
12329 \begin_layout Description
12330 \begin_inset Flex CharStyle:Code
12333 \begin_layout Plain Layout
12340 \begin_inset Flex CharStyle:Code
12343 \begin_layout Plain Layout
12352 \begin_inset Flex CharStyle:Code
12355 \begin_layout Plain Layout
12361 ] Indicates whether the user may employ the Paragraph Settings dialog to
12362 customize the paragraph.
12365 \begin_layout Description
12366 \begin_inset Flex CharStyle:Code
12369 \begin_layout Plain Layout
12376 \begin_inset Flex CharStyle:Code
12379 \begin_layout Plain Layout
12386 \begin_inset Flex CharStyle:Code
12389 \begin_layout Plain Layout
12396 \begin_inset Flex CharStyle:Code
12399 \begin_layout Plain Layout
12405 , describing the rendering style used for the inset's frame and buttons.
12406 Footnotes generally use
12407 \begin_inset Flex CharStyle:Code
12410 \begin_layout Plain Layout
12416 , ERT insets generally
12417 \begin_inset Flex CharStyle:Code
12420 \begin_layout Plain Layout
12426 , and character styles
12427 \begin_inset Flex CharStyle:Code
12430 \begin_layout Plain Layout
12439 \begin_layout Description
12440 \begin_inset Flex CharStyle:Code
12443 \begin_layout Plain Layout
12449 Required at the end of the InsetLayout declarations.
12452 \begin_layout Description
12453 \begin_inset Flex CharStyle:Code
12456 \begin_layout Plain Layout
12462 The font used for both the text body
12468 \begin_inset space ~
12472 \begin_inset CommandInset ref
12474 reference "sec:fonts"
12479 Note that defining this font automatically defines the
12480 \begin_inset Flex CharStyle:Code
12483 \begin_layout Plain Layout
12489 to the same value, so define this first and define
12490 \begin_inset Flex CharStyle:Code
12493 \begin_layout Plain Layout
12499 later if you want them to be different.
12502 \begin_layout Description
12503 \begin_inset Flex CharStyle:Code
12506 \begin_layout Plain Layout
12513 \begin_inset Quotes eld
12517 \begin_inset Quotes erd
12520 language, leading to Left-to-Right (latin) output, e.
12521 \begin_inset space \thinspace{}
12525 \begin_inset space \space{}
12528 in TeX code or URL.
12532 \begin_layout Description
12533 \begin_inset Flex CharStyle:Code
12536 \begin_layout Plain Layout
12543 \begin_inset Flex CharStyle:Code
12546 \begin_layout Plain Layout
12555 \begin_inset Flex CharStyle:Code
12558 \begin_layout Plain Layout
12564 ] Indicates whether the PlainLayout should be used or, instead, the user
12565 can change the paragraph style used in the inset.
12568 \begin_layout Description
12569 \begin_inset Flex CharStyle:Code
12572 \begin_layout Plain Layout
12578 As with paragraph styles (see page
12579 \begin_inset CommandInset ref
12580 LatexCommand pageref
12581 reference "des:FreeSpacing"
12588 \begin_layout Description
12589 \begin_inset Flex CharStyle:Code
12592 \begin_layout Plain Layout
12599 \begin_inset Flex CharStyle:Code
12602 \begin_layout Plain Layout
12611 \begin_inset Flex CharStyle:Code
12614 \begin_layout Plain Layout
12620 ] Whether to include the contents of this inset in the strings generated
12621 for the `Outline' pane.
12622 One would not, for example, want the content of a footnote in a section
12623 header to be included in the TOC displayed in the outline, but one would
12624 normally want the content of a character style displayed.
12625 Default is false: not to include.
12628 \begin_layout Description
12629 \begin_inset Flex CharStyle:Code
12632 \begin_layout Plain Layout
12638 As with paragraph styles (see page
12639 \begin_inset CommandInset ref
12640 LatexCommand pageref
12641 reference "des:KeepEmpty"
12648 \begin_layout Description
12649 \begin_inset Flex CharStyle:Code
12652 \begin_layout Plain Layout
12658 The font used for the label.
12660 \begin_inset space ~
12664 \begin_inset CommandInset ref
12666 reference "sec:fonts"
12671 Note that this definition can never appear before
12672 \begin_inset Flex CharStyle:Code
12675 \begin_layout Plain Layout
12681 , lest it be ineffective.
12684 \begin_layout Description
12685 \begin_inset Flex CharStyle:Code
12688 \begin_layout Plain Layout
12694 What will be displayed on the button or elsewhere as the inset label.
12695 Some inset types (TeX code and Branch) modify this label on the fly.
12698 \begin_layout Description
12699 \begin_inset Flex CharStyle:Code
12702 \begin_layout Plain Layout
12708 The name of the corresponding LaTeX stuff.
12709 Either the environment or command name.
12712 \begin_layout Description
12713 \begin_inset Flex CharStyle:Code
12716 \begin_layout Plain Layout
12722 The optional parameter for the corresponding
12723 \begin_inset Flex CharStyle:Code
12726 \begin_layout Plain Layout
12732 stuff, including possible bracket pairs like
12733 \begin_inset Flex CharStyle:Code
12736 \begin_layout Plain Layout
12743 This parameter cannot be changed from within LyX.
12746 \begin_layout Description
12747 \begin_inset Flex CharStyle:Code
12750 \begin_layout Plain Layout
12756 As with paragraph styles (see page
12757 \begin_inset CommandInset ref
12758 LatexCommand pageref
12759 reference "des:LatexType"
12766 \begin_layout Description
12767 \begin_inset Flex CharStyle:Code
12770 \begin_layout Plain Layout
12777 \begin_inset Flex CharStyle:Code
12780 \begin_layout Plain Layout
12787 \begin_inset Flex CharStyle:Code
12790 \begin_layout Plain Layout
12797 \begin_inset Flex CharStyle:Code
12800 \begin_layout Plain Layout
12807 \begin_inset Flex CharStyle:Code
12810 \begin_layout Plain Layout
12816 (indicating a dummy definition ending definitions of charstyles, etc).
12817 This entry is required in and is only meaningful for Flex insets.
12818 Among other things, it determines on which menu this inset will appear.
12821 \begin_layout Description
12822 \begin_inset Flex CharStyle:Code
12825 \begin_layout Plain Layout
12832 \begin_inset Flex CharStyle:Code
12835 \begin_layout Plain Layout
12844 \begin_inset Flex CharStyle:Code
12847 \begin_layout Plain Layout
12853 ] Whether multiple paragraphs are permitted in this inset.
12854 This will also set CustomPars to the same value and ForcePlain to the opposite
12856 These can be reset to other values, if they are used
12863 \begin_layout Description
12864 \begin_inset Flex CharStyle:Code
12867 \begin_layout Plain Layout
12874 \begin_inset Flex CharStyle:Code
12877 \begin_layout Plain Layout
12886 \begin_inset Flex CharStyle:Code
12889 \begin_layout Plain Layout
12895 ] Whether fragile commands in this layout should be
12896 \begin_inset Flex CharStyle:Code
12899 \begin_layout Plain Layout
12912 whether the command should itself be protected.)
12915 \begin_layout Description
12916 \begin_inset Flex CharStyle:Code
12919 \begin_layout Plain Layout
12926 \begin_inset Flex CharStyle:Code
12929 \begin_layout Plain Layout
12938 \begin_inset Flex CharStyle:Code
12941 \begin_layout Plain Layout
12947 ] As with paragraph styles (see page
12948 \begin_inset CommandInset ref
12950 reference "des:PathThru"
12957 \begin_layout Description
12958 \begin_inset Flex CharStyle:Code
12961 \begin_layout Plain Layout
12967 As with paragraph styles (see page
12968 \begin_inset CommandInset ref
12969 LatexCommand pageref
12970 reference "des:Preamble"
12977 \begin_layout Description
12978 \begin_inset Flex CharStyle:Code
12981 \begin_layout Plain Layout
12988 \begin_inset Flex CharStyle:Code
12991 \begin_layout Plain Layout
12997 ] As with paragraph styles (see page
12998 \begin_inset CommandInset ref
12999 LatexCommand pageref
13000 reference "des:Requires"
13007 \begin_layout Subsection
13011 \begin_layout Standard
13012 \begin_inset CommandInset label
13018 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13020 \begin_inset Flex CharStyle:MenuItem
13023 \begin_layout Plain Layout
13030 \begin_inset Flex CharStyle:MenuItem
13033 \begin_layout Plain Layout
13039 , \SpecialChar \ldots{}
13040 ) in the text class itself.
13041 The standard counters are defined in the file
13042 \begin_inset Flex CharStyle:Code
13045 \begin_layout Plain Layout
13051 , so you may have to do no more than add
13054 \begin_layout LyX-Code
13055 Input stdcounters.inc
13058 \begin_layout Standard
13059 to your layout file to get them to work.
13060 But if you want to define custom counters, then you can do so.
13061 The counter declaration must begin with:
13064 \begin_layout LyX-Code
13068 \begin_layout Standard
13069 where of course `name' is replaced by the name of the counter.
13070 And it must end with
13071 \begin_inset Quotes eld
13075 \begin_inset Flex CharStyle:Code
13078 \begin_layout Plain Layout
13085 \begin_inset Quotes erd
13089 The following parameters can also be used:
13092 \begin_layout Description
13093 \begin_inset Flex CharStyle:Code
13096 \begin_layout Plain Layout
13097 LabelString [string=""]
13102 when this is defined, this string defines how the counter is displayed.
13103 Setting this value sets
13104 \begin_inset Flex CharStyle:Code
13107 \begin_layout Plain Layout
13108 LabelStringAppendix
13114 The following special constructs can be used in the string:
13118 \begin_layout Itemize
13119 \begin_inset Flex CharStyle:Code
13122 \begin_layout Plain Layout
13130 will be replaced by the expansion of the
13131 \begin_inset Flex CharStyle:Code
13134 \begin_layout Plain Layout
13141 \begin_inset Flex CharStyle:Code
13144 \begin_layout Plain Layout
13145 LabelStringAppendix
13151 \begin_inset Flex CharStyle:Code
13154 \begin_layout Plain Layout
13164 \begin_layout Itemize
13165 counter values can be expressed using LaTeX-like macros
13166 \begin_inset Flex CharStyle:Code
13169 \begin_layout Plain Layout
13186 \begin_inset Flex CharStyle:Code
13189 \begin_layout Plain Layout
13201 \begin_layout Plain Layout
13211 Actually, the situation is a bit more complicated: any
13230 other than those described below will produce arabic numerals.
13231 It would not be surprising to see this change in the future.
13237 \begin_inset Flex CharStyle:Code
13240 \begin_layout Plain Layout
13246 : 1, 2, 3,\SpecialChar \ldots{}
13248 \begin_inset Flex CharStyle:Code
13251 \begin_layout Plain Layout
13257 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13259 \begin_inset Flex CharStyle:Code
13262 \begin_layout Plain Layout
13268 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13270 \begin_inset Flex CharStyle:Code
13273 \begin_layout Plain Layout
13279 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13281 \begin_inset Flex CharStyle:Code
13284 \begin_layout Plain Layout
13290 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13292 \begin_inset Flex CharStyle:Code
13295 \begin_layout Plain Layout
13301 for hebrew numerals.
13305 \begin_layout Standard
13306 If LabelString is not defined, a default value is constructed as follows:
13307 if the counter has a master counter
13308 \begin_inset Flex CharStyle:Code
13311 \begin_layout Plain Layout
13318 \begin_inset Flex CharStyle:Code
13321 \begin_layout Plain Layout
13328 \begin_inset Flex CharStyle:Code
13331 \begin_layout Plain Layout
13341 is used; otherwise the string
13342 \begin_inset Flex CharStyle:Code
13345 \begin_layout Plain Layout
13356 \begin_layout Description
13357 \begin_inset Flex CharStyle:Code
13360 \begin_layout Plain Layout
13361 LabelStringAppendix [string=""]
13367 \begin_inset Flex CharStyle:Code
13370 \begin_layout Plain Layout
13376 , but for use in the Appendix.
13379 \begin_layout Description
13380 \begin_inset Flex CharStyle:Code
13383 \begin_layout Plain Layout
13390 \begin_inset Flex CharStyle:Code
13393 \begin_layout Plain Layout
13400 \begin_inset Quotes erd
13404 \begin_inset Quotes erd
13407 ] If this is set to the name of another counter, the present counter will
13408 be reset every time the other one is increased.
13410 \begin_inset Flex CharStyle:Code
13413 \begin_layout Plain Layout
13420 \begin_inset Flex CharStyle:Code
13423 \begin_layout Plain Layout
13432 \begin_layout Subsection
13436 \begin_layout Standard
13437 \begin_inset CommandInset label
13443 A font description looks like this:
13446 \begin_layout LyX-Code
13456 \begin_layout LyX-Code
13460 \begin_layout LyX-Code
13464 \begin_layout Standard
13465 The following commands are available:
13468 \begin_layout Description
13469 \begin_inset Flex CharStyle:Code
13472 \begin_layout Plain Layout
13479 \begin_inset Flex CharStyle:Code
13482 \begin_layout Plain Layout
13491 \begin_inset Flex CharStyle:Code
13494 \begin_layout Plain Layout
13501 \begin_inset Flex CharStyle:Code
13504 \begin_layout Plain Layout
13511 \begin_inset Flex CharStyle:Code
13514 \begin_layout Plain Layout
13521 \begin_inset Flex CharStyle:Code
13524 \begin_layout Plain Layout
13531 \begin_inset Flex CharStyle:Code
13534 \begin_layout Plain Layout
13541 \begin_inset Flex CharStyle:Code
13544 \begin_layout Plain Layout
13551 \begin_inset Flex CharStyle:Code
13554 \begin_layout Plain Layout
13561 \begin_inset Flex CharStyle:Code
13564 \begin_layout Plain Layout
13573 \begin_layout Description
13574 \begin_inset Flex CharStyle:Code
13577 \begin_layout Plain Layout
13586 \begin_inset Flex CharStyle:Code
13589 \begin_layout Plain Layout
13600 \begin_inset Flex CharStyle:Code
13603 \begin_layout Plain Layout
13610 \begin_inset Flex CharStyle:Code
13613 \begin_layout Plain Layout
13622 \begin_layout Description
13623 \begin_inset Flex CharStyle:Code
13626 \begin_layout Plain Layout
13633 \begin_inset Flex CharStyle:Code
13636 \begin_layout Plain Layout
13642 ] Valid argument are:
13643 \begin_inset Flex CharStyle:Code
13646 \begin_layout Plain Layout
13653 \begin_inset Flex CharStyle:Code
13656 \begin_layout Plain Layout
13663 \begin_inset Flex CharStyle:Code
13666 \begin_layout Plain Layout
13673 \begin_inset Flex CharStyle:Code
13676 \begin_layout Plain Layout
13683 \begin_inset Flex CharStyle:Code
13686 \begin_layout Plain Layout
13693 \begin_inset Flex CharStyle:Code
13696 \begin_layout Plain Layout
13703 Each of these turns on or off the corresponding attribute.
13706 \begin_layout Description
13707 \begin_inset Flex CharStyle:Code
13710 \begin_layout Plain Layout
13719 \begin_inset Flex CharStyle:Code
13722 \begin_layout Plain Layout
13733 \begin_inset Flex CharStyle:Code
13736 \begin_layout Plain Layout
13745 \begin_layout Description
13746 \begin_inset Flex CharStyle:Code
13749 \begin_layout Plain Layout
13758 \begin_inset Flex CharStyle:Code
13761 \begin_layout Plain Layout
13772 \begin_inset Flex CharStyle:Code
13775 \begin_layout Plain Layout
13782 \begin_inset Flex CharStyle:Code
13785 \begin_layout Plain Layout
13792 \begin_inset Flex CharStyle:Code
13795 \begin_layout Plain Layout
13804 \begin_layout Description
13805 \begin_inset Flex CharStyle:Code
13808 \begin_layout Plain Layout
13815 \begin_inset Flex CharStyle:Code
13818 \begin_layout Plain Layout
13825 \begin_inset Flex CharStyle:Code
13828 \begin_layout Plain Layout
13835 \begin_inset Flex CharStyle:Code
13838 \begin_layout Plain Layout
13847 \begin_inset Flex CharStyle:Code
13850 \begin_layout Plain Layout
13857 \begin_inset Flex CharStyle:Code
13860 \begin_layout Plain Layout
13867 \begin_inset Flex CharStyle:Code
13870 \begin_layout Plain Layout
13877 \begin_inset Flex CharStyle:Code
13880 \begin_layout Plain Layout
13887 \begin_inset Flex CharStyle:Code
13890 \begin_layout Plain Layout
13899 \begin_layout Subsection
13900 Upgrading old layout files
13903 \begin_layout Standard
13904 The file format of layout files changes from time to time, so old layout
13905 files need to be converted.
13906 This process has been automated since LyX 1.4.0: If LyX reads an old format
13907 layout file it will call the conversion tool
13908 \begin_inset Flex CharStyle:Code
13911 \begin_layout Plain Layout
13912 LyXDir/scripts/layout2layout.py
13917 and convert it to a temporary file in current format.
13918 The original file is left untouched.
13919 If you want to convert the layout file permanently, just call the converter
13923 \begin_layout LyX-Code
13924 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13927 \begin_layout Standard
13928 (You need to replace
13929 \begin_inset Flex CharStyle:Code
13932 \begin_layout Plain Layout
13938 with the name of your LyX system directory, unless you happen to have defined
13939 such an environment variable.) Then copy
13940 \begin_inset Flex CharStyle:Code
13943 \begin_layout Plain Layout
13950 \begin_inset Flex CharStyle:Code
13953 \begin_layout Plain Layout
13962 \begin_layout Standard
13963 The automatic conversion only handles syntax changes.
13964 It cannot handle the case where the contents of included files was changed,
13965 so these will have to be converted separately.
13968 \begin_layout Section
13970 \begin_inset CommandInset label
13972 name "sec:templates"
13979 \begin_layout Standard
13980 Templates are created just like usual documents.
13981 The only difference is that usual documents contain all possible settings,
13982 including the font scheme and the paper size.
13983 Usually a user doesn't want a template to overwrite his defaults in these
13985 For that reason, the designer of a template should remove the corresponding
13987 \begin_inset Flex CharStyle:Code
13990 \begin_layout Plain Layout
13999 \begin_inset Flex CharStyle:Code
14002 \begin_layout Plain Layout
14010 from the template LyX file.
14011 This can be done with any simple text-editor, for example
14012 \begin_inset Flex CharStyle:Code
14015 \begin_layout Plain Layout
14022 \begin_inset Flex CharStyle:Code
14025 \begin_layout Plain Layout
14035 \begin_layout Standard
14036 Put the edited template files you create in
14037 \begin_inset Flex CharStyle:Code
14040 \begin_layout Plain Layout
14046 , copy the ones you use from the global template directory in
14047 \begin_inset Flex CharStyle:Code
14050 \begin_layout Plain Layout
14056 to the same place, and redefine the template path in the
14057 \begin_inset Flex CharStyle:MenuItem
14060 \begin_layout Plain Layout
14061 Tools\SpecialChar \menuseparator
14062 Preferences\SpecialChar \menuseparator
14071 \begin_layout Standard
14072 Note that there is a template which has a particular meaning:
14073 \begin_inset Flex CharStyle:Code
14076 \begin_layout Plain Layout
14083 This template is loaded every time you create a new document with
14084 \begin_inset Flex CharStyle:MenuItem
14087 \begin_layout Plain Layout
14088 File\SpecialChar \menuseparator
14094 in order to provide useful defaults.
14095 To create this template from inside LyX, all you have to do is to open
14096 a document with the correct settings, and use the
14097 \begin_inset Flex CharStyle:MenuItem
14100 \begin_layout Plain Layout
14101 Save as Document Defaults
14109 \begin_layout Chapter
14110 Including External Material
14113 \begin_layout Standard
14114 \begin_inset Box Shadowbox
14123 height_special "totalheight"
14126 \begin_layout Plain Layout
14127 WARNING: This portion of the documentation has not been updated for some
14129 We certainly hope that it is still accurate, but there are no guarantees.
14137 \begin_layout Standard
14138 The use of material from sources external to LyX is covered in detail in
14144 This part of the manual covers what needs to happen behind the scenes for
14145 new sorts of material to be included.
14148 \begin_layout Section
14152 \begin_layout Standard
14153 The external material feature is based on the concept of a
14158 A template is a specification of how LyX should interface with a certain
14160 As bundled, LyX comes with predefined templates for Xfig figures, various
14161 raster format images, chess diagrams, and LilyPond music notation.
14162 You can check the actual list by using the menu
14163 \begin_inset Flex CharStyle:MenuItem
14166 \begin_layout Plain Layout
14167 Insert\SpecialChar \menuseparator
14168 File\SpecialChar \menuseparator
14175 Furthermore, it is possible to roll your own template to support a specific
14177 Later we'll describe in more detail what is involved, and hopefully you
14178 will submit all the templates you create so we can include them in a later
14182 \begin_layout Standard
14183 Another basic idea of the external material feature is to distinguish between
14184 the original file that serves as a base for final material and the produced
14185 file that is included in your exported or printed document.
14186 For example, consider the case of a figure produced with
14187 \begin_inset Flex CharStyle:Code
14190 \begin_layout Plain Layout
14197 The Xfig application itself works on an original file with the
14198 \begin_inset Flex CharStyle:Code
14201 \begin_layout Plain Layout
14208 Within Xfig, you create and change your figure, and when you are done,
14210 \begin_inset Flex CharStyle:Code
14213 \begin_layout Plain Layout
14220 When you want to include the figure in your document, you invoke
14221 \begin_inset Flex CharStyle:Code
14224 \begin_layout Plain Layout
14230 in order to create a PostScript file that can readily be included in your
14233 \begin_inset Flex CharStyle:Code
14236 \begin_layout Plain Layout
14242 file is the original file, and the PostScript file is the produced file.
14245 \begin_layout Standard
14246 This distinction is important in order to allow updating of the material
14247 while you are in the process of writing the document.
14248 Furthermore, it provides us with the flexibility that is needed to support
14249 multiple export formats.
14250 For instance, in the case of a plain text file, it is not exactly an award-winn
14251 ing idea to include the figure as raw PostScript.
14252 Instead, you'd either prefer to just include a reference to the figure
14253 or try to invoke some graphics to ASCII converter to make the final result
14254 look similar to the real graphics.
14255 The external material management allows you to do this, because it is parametri
14256 zed on the different export formats that LyX supports.
14259 \begin_layout Standard
14260 Besides supporting the production of different products according to the
14261 exported format, it supports tight integration with editing and viewing
14263 In the case of an Xfig figure, you are able to invoke Xfig on the original
14264 file with a single click from within the external material dialog in LyX,
14265 and also preview the produced PostScript file with Ghostview with another
14267 No more fiddling around with the command line and/or file browsers to locate
14268 and manipulate the original or produced files.
14269 In this way, you are finally able to take full advantage of the many different
14270 applications that are relevant to use when you write your documents, and
14271 ultimately be more productive.
14274 \begin_layout Section
14275 The external template configuration file
14278 \begin_layout Standard
14279 It is relatively easy to add custom external template definitions to LyX.
14280 However, be aware that doing this in an careless manner most probably
14284 introduce an easily exploitable security hole.
14285 So before you do this, please read the discussion about security in section
14287 \begin_inset CommandInset ref
14289 reference "sec:Security-discussion"
14296 \begin_layout Standard
14297 Having said that, we encourage you to submit any interesting templates that
14302 \begin_layout Standard
14303 The external templates are defined in the
14304 \begin_inset Flex CharStyle:Code
14307 \begin_layout Plain Layout
14308 LyXDir/lib/external_templates
14314 You can place your own version in
14315 \begin_inset Flex CharStyle:Code
14318 \begin_layout Plain Layout
14319 UserDir/external_templates
14327 \begin_layout Standard
14328 A typical template looks like this:
14331 \begin_layout LyX-Code
14335 \begin_layout LyX-Code
14336 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14339 \begin_layout LyX-Code
14343 \begin_layout LyX-Code
14347 \begin_layout LyX-Code
14351 \begin_layout LyX-Code
14355 \begin_layout LyX-Code
14359 \begin_layout LyX-Code
14360 AutomaticProduction true
14363 \begin_layout LyX-Code
14367 \begin_layout LyX-Code
14371 \begin_layout LyX-Code
14375 \begin_layout LyX-Code
14376 TransformCommand Rotate RotationLatexCommand
14379 \begin_layout LyX-Code
14380 TransformCommand Resize ResizeLatexCommand
14383 \begin_layout LyX-Code
14384 Product "$$RotateFront$$ResizeFront
14387 \begin_layout LyX-Code
14392 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14395 \begin_layout LyX-Code
14396 $$ResizeBack$$RotateBack"
14399 \begin_layout LyX-Code
14403 \begin_layout LyX-Code
14404 UpdateResult "$$AbsPath$$Basename.pstex_t"
14407 \begin_layout LyX-Code
14408 Requirement "graphicx"
14411 \begin_layout LyX-Code
14412 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14415 \begin_layout LyX-Code
14416 ReferencedFile latex "$$AbsPath$$Basename.eps"
14419 \begin_layout LyX-Code
14420 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14423 \begin_layout LyX-Code
14427 \begin_layout LyX-Code
14431 \begin_layout LyX-Code
14432 TransformCommand Rotate RotationLatexCommand
14435 \begin_layout LyX-Code
14436 TransformCommand Resize ResizeLatexCommand
14439 \begin_layout LyX-Code
14440 Product "$$RotateFront$$ResizeFront
14443 \begin_layout LyX-Code
14448 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14451 \begin_layout LyX-Code
14452 $$ResizeBack$$RotateBack"
14455 \begin_layout LyX-Code
14456 UpdateFormat pdftex
14459 \begin_layout LyX-Code
14460 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14463 \begin_layout LyX-Code
14464 Requirement "graphicx"
14467 \begin_layout LyX-Code
14468 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14471 \begin_layout LyX-Code
14472 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14475 \begin_layout LyX-Code
14479 \begin_layout LyX-Code
14483 \begin_layout LyX-Code
14484 Product "$$Contents(
14486 "$$AbsPath$$Basename.asc
14491 \begin_layout LyX-Code
14492 UpdateFormat asciixfig
14495 \begin_layout LyX-Code
14496 UpdateResult "$$AbsPath$$Basename.asc"
14499 \begin_layout LyX-Code
14503 \begin_layout LyX-Code
14507 \begin_layout LyX-Code
14508 Product "<graphic fileref=
14510 "$$AbsOrRelPathMaster$$Basename.eps
14515 \begin_layout LyX-Code
14519 \begin_layout LyX-Code
14523 \begin_layout LyX-Code
14524 UpdateResult "$$AbsPath$$Basename.eps"
14527 \begin_layout LyX-Code
14528 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14531 \begin_layout LyX-Code
14532 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14535 \begin_layout LyX-Code
14539 \begin_layout LyX-Code
14540 Product "[XFig: $$FName]"
14543 \begin_layout LyX-Code
14547 \begin_layout LyX-Code
14551 \begin_layout Standard
14552 As you can see, the template is enclosed in
14553 \begin_inset Flex CharStyle:Code
14556 \begin_layout Plain Layout
14562 \SpecialChar \ldots{}
14564 \begin_inset Flex CharStyle:Code
14567 \begin_layout Plain Layout
14574 It contains a header specifying some general settings and, for each supported
14575 primary document file format, a section
14576 \begin_inset Flex CharStyle:Code
14579 \begin_layout Plain Layout
14585 \SpecialChar \ldots{}
14587 \begin_inset Flex CharStyle:Code
14590 \begin_layout Plain Layout
14599 \begin_layout Subsection
14600 The template header
14603 \begin_layout Description
14604 \begin_inset Flex CharStyle:Code
14607 \begin_layout Plain Layout
14608 AutomaticProduction
14609 \begin_inset space ~
14617 Whether the file represented by the template must be generated by LyX.
14618 This command must occur exactly once.
14621 \begin_layout Description
14622 \begin_inset Flex CharStyle:Code
14625 \begin_layout Plain Layout
14627 \begin_inset space ~
14635 A glob pattern that is used in the file dialog to filter out the desired
14637 If there is more than one possible file extension (e.
14638 \begin_inset space \thinspace{}
14642 \begin_inset space \space{}
14646 \begin_inset Flex CharStyle:Code
14649 \begin_layout Plain Layout
14656 \begin_inset Flex CharStyle:Code
14659 \begin_layout Plain Layout
14665 ), use something like
14666 \begin_inset Flex CharStyle:Code
14669 \begin_layout Plain Layout
14676 This command must occur exactly once.
14679 \begin_layout Description
14680 \begin_inset Flex CharStyle:Code
14683 \begin_layout Plain Layout
14685 \begin_inset space ~
14693 The text that is displayed on the button.
14694 This command must occur exactly once.
14697 \begin_layout Description
14698 \begin_inset Flex CharStyle:Code
14701 \begin_layout Plain Layout
14703 \begin_inset space ~
14707 \begin_inset space ~
14715 The help text that is used in the External dialog.
14716 Provide enough information to explain to the user just what the template
14717 can provide him with.
14718 This command must occur exactly once.
14721 \begin_layout Description
14722 \begin_inset Flex CharStyle:Code
14725 \begin_layout Plain Layout
14727 \begin_inset space ~
14735 The file format of the original file.
14736 This must be the name of a format that is known to LyX (see section
14737 \begin_inset CommandInset ref
14739 reference "sub:Formats"
14745 \begin_inset Quotes eld
14749 \begin_inset Flex CharStyle:Code
14752 \begin_layout Plain Layout
14759 \begin_inset Quotes erd
14762 if the template can handle original files of more than one format.
14763 LyX will attempt to interrogate the file itself in order to deduce its
14764 format in this case.
14765 This command must occur exactly once.
14768 \begin_layout Description
14769 \begin_inset Flex CharStyle:Code
14772 \begin_layout Plain Layout
14774 \begin_inset space ~
14782 A unique name for the template.
14783 It must not contain substitution macros (see below).
14786 \begin_layout Description
14787 \begin_inset Flex CharStyle:Code
14790 \begin_layout Plain Layout
14792 \begin_inset space ~
14795 Rotate|Resize|Clip|Extra
14800 This command specifies which transformations are supported by this template.
14801 It may occur zero or more times.
14802 This command enables the corresponding tabs in the external dialog.
14804 \begin_inset Flex CharStyle:Code
14807 \begin_layout Plain Layout
14813 command must have either a corresponding
14814 \begin_inset Flex CharStyle:Code
14817 \begin_layout Plain Layout
14824 \begin_inset Flex CharStyle:Code
14827 \begin_layout Plain Layout
14834 \begin_inset Flex CharStyle:Code
14837 \begin_layout Plain Layout
14844 Otherwise the transformation will not be supported by that format.
14847 \begin_layout Subsection
14851 \begin_layout Description
14852 \begin_inset Flex CharStyle:Code
14855 \begin_layout Plain Layout
14857 \begin_inset space ~
14860 LaTeX|PDFLaTeX|PlainText|DocBook
14865 The primary document file format that this format definition is for.
14866 Not every template has a sensible representation in all document file formats.
14867 Please define nevertheless a
14868 \begin_inset Flex CharStyle:Code
14871 \begin_layout Plain Layout
14877 section for all formats.
14878 Use a dummy text when no representation is available.
14879 Then you can at least see a reference to the external material in the exported
14883 \begin_layout Description
14884 \begin_inset Flex CharStyle:Code
14887 \begin_layout Plain Layout
14889 \begin_inset space ~
14893 \begin_inset space ~
14901 This command defines an additional macro
14902 \begin_inset Flex CharStyle:Code
14905 \begin_layout Plain Layout
14911 for substitution in
14912 \begin_inset Flex CharStyle:Code
14915 \begin_layout Plain Layout
14923 \begin_inset Flex CharStyle:Code
14926 \begin_layout Plain Layout
14932 itself may contain substitution macros.
14933 The advantage over using
14934 \begin_inset Flex CharStyle:Code
14937 \begin_layout Plain Layout
14944 \begin_inset Flex CharStyle:Code
14947 \begin_layout Plain Layout
14953 is that the substituted value of
14954 \begin_inset Flex CharStyle:Code
14957 \begin_layout Plain Layout
14963 is sanitized so that it is a valid optional argument in the document format.
14964 This command may occur zero or more times.
14967 \begin_layout Description
14968 \begin_inset Flex CharStyle:Code
14971 \begin_layout Plain Layout
14973 \begin_inset space ~
14981 The text that is inserted in the exported document.
14982 This is actually the most important command and can be quite complex.
14983 This command must occur exactly once.
14986 \begin_layout Description
14987 \begin_inset Flex CharStyle:Code
14990 \begin_layout Plain Layout
14992 \begin_inset space ~
15000 This command specifies a preamble snippet that will be included in the
15002 It has to be defined using
15003 \begin_inset Flex CharStyle:Code
15006 \begin_layout Plain Layout
15012 \SpecialChar \ldots{}
15014 \begin_inset Flex CharStyle:Code
15017 \begin_layout Plain Layout
15024 This command may occur zero or more times.
15027 \begin_layout Description
15028 \begin_inset Flex CharStyle:Code
15031 \begin_layout Plain Layout
15033 \begin_inset space ~
15037 \begin_inset space ~
15045 This command denotes files that are created by the conversion process and
15046 are needed for a particular export format.
15047 If the filename is relative, it is interpreted relative to the master document.
15048 This command may be given zero or more times.
15051 \begin_layout Description
15052 \begin_inset Flex CharStyle:Code
15055 \begin_layout Plain Layout
15057 \begin_inset space ~
15065 The name of a required LaTeX package.
15066 The package is included via
15067 \begin_inset Flex CharStyle:Code
15070 \begin_layout Plain Layout
15078 in the LaTeX preamble.
15079 This command may occur zero or more times.
15082 \begin_layout Description
15083 \begin_inset Flex CharStyle:Code
15086 \begin_layout Plain Layout
15088 \begin_inset space ~
15092 \begin_inset space ~
15095 RotationLatexCommand
15100 This command specifies that the built in LaTeX command should be used for
15102 This command may occur once or not at all.
15105 \begin_layout Description
15106 \begin_inset Flex CharStyle:Code
15109 \begin_layout Plain Layout
15111 \begin_inset space ~
15115 \begin_inset space ~
15123 This command specifies that the built in LaTeX command should be used for
15125 This command may occur once or not at all.
15128 \begin_layout Description
15129 \begin_inset Flex CharStyle:Code
15132 \begin_layout Plain Layout
15134 \begin_inset space ~
15138 \begin_inset space ~
15141 RotationLatexOption
15146 This command specifies that rotation is done via an optional argument.
15147 This command may occur once or not at all.
15150 \begin_layout Description
15151 \begin_inset Flex CharStyle:Code
15154 \begin_layout Plain Layout
15156 \begin_inset space ~
15160 \begin_inset space ~
15168 This command specifies that resizing is done via an optional argument.
15169 This command may occur once or not at all.
15172 \begin_layout Description
15173 \begin_inset Flex CharStyle:Code
15176 \begin_layout Plain Layout
15178 \begin_inset space ~
15182 \begin_inset space ~
15190 This command specifies that clipping is done via an optional argument.
15191 This command may occur once or not at all.
15194 \begin_layout Description
15195 \begin_inset Flex CharStyle:Code
15198 \begin_layout Plain Layout
15200 \begin_inset space ~
15204 \begin_inset space ~
15212 This command specifies that an extra optional argument is used.
15213 This command may occur once or not at all.
15216 \begin_layout Description
15217 \begin_inset Flex CharStyle:Code
15220 \begin_layout Plain Layout
15222 \begin_inset space ~
15230 The file format of the converted file.
15231 This must be the name of a format that is known to LyX (see the
15232 \begin_inset Flex CharStyle:MenuItem
15235 \begin_layout Plain Layout
15240 ools\SpecialChar \menuseparator
15245 references:Conversion
15251 This command must occur exactly once.
15254 \begin_layout Description
15255 \begin_inset Flex CharStyle:Code
15258 \begin_layout Plain Layout
15260 \begin_inset space ~
15268 The file name of the converted file.
15269 The file name must be absolute.
15270 This command must occur exactly once.
15273 \begin_layout Subsection
15274 Preamble definitions
15277 \begin_layout Standard
15278 The external template configuration file may contain additional preamble
15279 definitions enclosed by
15280 \begin_inset Flex CharStyle:Code
15283 \begin_layout Plain Layout
15289 \SpecialChar \ldots{}
15291 \begin_inset Flex CharStyle:Code
15294 \begin_layout Plain Layout
15301 They can be used by the templates in the
15302 \begin_inset Flex CharStyle:Code
15305 \begin_layout Plain Layout
15314 \begin_layout Section
15315 The substitution mechanism
15318 \begin_layout Standard
15319 When the external material facility invokes an external program, it is done
15320 on the basis of a command defined in the template configuration file.
15321 These commands can contain various macros that are expanded before execution.
15322 Execution always take place in the directory of the containing document.
15325 \begin_layout Standard
15326 Also, whenever external material is to be displayed, the name will be produced
15327 by the substitution mechanism, and most other commands in the template
15328 definition support substitution as well.
15331 \begin_layout Standard
15332 The available macros are the following:
15335 \begin_layout Description
15336 \begin_inset Flex CharStyle:Code
15339 \begin_layout Plain Layout
15340 $$AbsOrRelPathMaster
15345 The file path, absolute or relative to the master LyX document.
15348 \begin_layout Description
15349 \begin_inset Flex CharStyle:Code
15352 \begin_layout Plain Layout
15353 $$AbsOrRelPathParent
15358 The file path, absolute or relative to the LyX document.
15361 \begin_layout Description
15362 \begin_inset Flex CharStyle:Code
15365 \begin_layout Plain Layout
15371 The absolute file path.
15374 \begin_layout Description
15375 \begin_inset Flex CharStyle:Code
15378 \begin_layout Plain Layout
15384 The filename without path and without the extension.
15387 \begin_layout Description
15388 \begin_inset Flex CharStyle:Code
15391 \begin_layout Plain Layout
15393 \begin_inset Quotes eld
15397 \begin_inset Quotes erd
15405 This macro will expand to the contents of the file with the name
15406 \begin_inset Flex CharStyle:Code
15409 \begin_layout Plain Layout
15418 \begin_layout Description
15419 \begin_inset Flex CharStyle:Code
15422 \begin_layout Plain Layout
15428 The file extension (including the dot).
15431 \begin_layout Description
15432 \begin_inset Flex CharStyle:Code
15435 \begin_layout Plain Layout
15441 The filename of the file specified in the external material dialog.
15442 This is either an absolute name, or it is relative to the LyX document.
15445 \begin_layout Description
15446 \begin_inset Flex CharStyle:Code
15449 \begin_layout Plain Layout
15456 \begin_inset Flex CharStyle:Code
15459 \begin_layout Plain Layout
15465 (absolute name or relative to the LyX document).
15468 \begin_layout Description
15469 \begin_inset Flex CharStyle:Code
15472 \begin_layout Plain Layout
15478 The file path, relative to the master LyX document.
15481 \begin_layout Description
15482 \begin_inset Flex CharStyle:Code
15485 \begin_layout Plain Layout
15491 The file path, relative to the LyX document.
15494 \begin_layout Description
15495 \begin_inset Flex CharStyle:Code
15498 \begin_layout Plain Layout
15504 This macro will expand to the absolute path of the system directory.
15505 This is typically used to point to the various helper scripts that are
15509 \begin_layout Description
15510 \begin_inset Flex CharStyle:Code
15513 \begin_layout Plain Layout
15519 A name and full path to a temporary file which will be automatically deleted
15520 whenever the containing document is closed, or the external material insertion
15524 \begin_layout Standard
15525 All path macros contain a trailing directory separator, so you can construct
15527 \begin_inset space \thinspace{}
15531 \begin_inset space \space{}
15534 the absolute filename with
15535 \begin_inset Flex CharStyle:Code
15538 \begin_layout Plain Layout
15539 $$AbsPath$$Basename$$Extension
15547 \begin_layout Standard
15548 The macros above are substituted in all commands unless otherwise noted.
15550 \begin_inset Flex CharStyle:Code
15553 \begin_layout Plain Layout
15559 supports additionally the following substitutions if they are enabled by
15561 \begin_inset Flex CharStyle:Code
15564 \begin_layout Plain Layout
15571 \begin_inset Flex CharStyle:Code
15574 \begin_layout Plain Layout
15583 \begin_layout Description
15584 \begin_inset Flex CharStyle:Code
15587 \begin_layout Plain Layout
15593 The front part of the resize command.
15596 \begin_layout Description
15597 \begin_inset Flex CharStyle:Code
15600 \begin_layout Plain Layout
15606 The back part of the resize command.
15609 \begin_layout Description
15610 \begin_inset Flex CharStyle:Code
15613 \begin_layout Plain Layout
15619 The front part of the rotation command.
15622 \begin_layout Description
15623 \begin_inset Flex CharStyle:Code
15626 \begin_layout Plain Layout
15632 The back part of the rotation command.
15635 \begin_layout Standard
15636 The value string of the
15637 \begin_inset Flex CharStyle:Code
15640 \begin_layout Plain Layout
15646 command supports additionally the following substitutions if they are enabled
15648 \begin_inset Flex CharStyle:Code
15651 \begin_layout Plain Layout
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
15709 \begin_layout Description
15710 \begin_inset Flex CharStyle:Code
15713 \begin_layout Plain Layout
15719 The rotation option.
15722 \begin_layout Standard
15723 You may ask why there are so many path macros.
15724 There are mainly two reasons:
15727 \begin_layout Enumerate
15728 Relative and absolute file names should remain relative or absolute, respectivel
15730 Users may have reasons to prefer either form.
15731 Relative names are useful for portable documents that should work on different
15732 machines, for example.
15733 Absolute names may be required by some programs.
15736 \begin_layout Enumerate
15737 LaTeX treats relative file names differently than LyX and other programs
15738 in nested included files.
15739 For LyX, a relative file name is always relative to the document that contains
15741 For LaTeX, it is always relative to the master document.
15742 These two definitions are identical if you have only one document, but
15743 differ if you have a master document that includes part documents.
15744 That means that relative filenames must be transformed when presented to
15746 Fortunately LyX does this automatically for you if you choose the right
15750 \begin_layout Standard
15751 So which path macro should be used in new template definitions? The rule
15755 \begin_layout Itemize
15757 \begin_inset Flex CharStyle:Code
15760 \begin_layout Plain Layout
15766 if an absolute path is required.
15769 \begin_layout Itemize
15771 \begin_inset Flex CharStyle:Code
15774 \begin_layout Plain Layout
15775 $$AbsOrRelPathMaster
15780 if the substituted string is some kind of LaTeX input.
15783 \begin_layout Itemize
15785 \begin_inset Flex CharStyle:Code
15788 \begin_layout Plain Layout
15789 $$AbsOrRelPathParent
15794 in order to preserve the user's choice.
15797 \begin_layout Standard
15798 There are special cases where this rule does not work and e.
15799 \begin_inset space \thinspace{}
15803 \begin_inset space \space{}
15806 relative names are needed, but normally it will work just fine.
15807 One example for such a case is the command
15808 \begin_inset Flex CharStyle:Code
15811 \begin_layout Plain Layout
15812 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15817 in the XFig template above: We can't use the absolute name because the
15819 \begin_inset Flex CharStyle:Code
15822 \begin_layout Plain Layout
15828 files needs the relative name in order to rewrite the file content.
15831 \begin_layout Section
15832 \begin_inset CommandInset label
15834 name "sec:Security-discussion"
15838 Security discussion
15841 \begin_layout Standard
15842 \begin_inset Box Shadowbox
15851 height_special "totalheight"
15854 \begin_layout Plain Layout
15855 WARNING: This section is definitely outdated.
15863 \begin_layout Standard
15864 The external material feature interfaces with a lot of external programs
15865 and does so automatically, so we have to consider the security implications
15867 In particular, since you have the option of including your own filenames
15868 and/or parameter strings and those are expanded into a command, it seems
15869 that it would be possible to create a malicious document which executes
15870 arbitrary commands when a user views or prints the document.
15871 This is something we definitely want to avoid.
15874 \begin_layout Standard
15875 However, since the external program commands are specified in the template
15876 configuration file only, there are no security issues if LyX is properly
15877 configured with safe templates only.
15878 This is so because the external programs are invoked with the
15879 \begin_inset Flex CharStyle:Code
15882 \begin_layout Plain Layout
15888 -system call rather than the
15889 \begin_inset Flex CharStyle:Code
15892 \begin_layout Plain Layout
15898 system-call, so it's not possible to execute arbitrary commands from the
15899 filename or parameter section via the shell.
15902 \begin_layout Standard
15903 This also implies that you are restricted in what command strings you can
15904 use in the external material templates.
15905 In particular, pipes and redirection are not readily available.
15906 This has to be so if LyX should remain safe.
15907 If you want to use some of the shell features, you should write a safe
15908 script to do this in a controlled manner, and then invoke the script from
15909 the command string.
15911 \begin_inset Flex CharStyle:Code
15914 \begin_layout Plain Layout
15920 directory of the LyX installation, you can find a safe wrapper script
15921 \begin_inset Flex CharStyle:Code
15924 \begin_layout Plain Layout
15925 general_command_wrapper.py
15930 that supports redirection of input and output.
15931 That can serve as an example for how to write safe template scripts.
15932 For a more advanced example that uses
15933 \begin_inset Flex CharStyle:Code
15936 \begin_layout Plain Layout
15942 and friends, take a look at the
15943 \begin_inset Flex CharStyle:Code
15946 \begin_layout Plain Layout
15955 \begin_layout Standard
15956 It is possible to design a template that interacts directly with the shell,
15957 but since this would allow a malicious user to execute arbitrary commands
15958 by writing clever filenames and/or parameters, we generally recommend that
15959 you only use safe scripts that work with the
15960 \begin_inset Flex CharStyle:Code
15963 \begin_layout Plain Layout
15969 system call in a controlled manner.
15970 Of course, for use in a controlled environment, it can be tempting to just
15971 fall back to use ordinary shell scripts.
15972 If you do so, be aware that you
15976 provide an easily exploitable security hole in your system.
15977 Of course it stands to reason that such unsafe templates will never be
15978 included in the standard LyX distribution, although we do encourage people
15979 to submit new templates in the open source tradition.
15980 But LyX as shipped from the official distribution channels will never have
15984 \begin_layout Standard
15985 Including external material provides a lot of power, and you have to be
15986 careful not to introduce security hazards with this power.
15987 A subtle error in a single line in an innocent looking script can open
15988 the door to huge security problems.
15989 So if you do not fully understand the issues, we recommend that you consult
15990 a knowledgeable security professional or the LyX development team if you
15991 have any questions about whether a given template is safe or not.
15992 And do this before you use it in an uncontrolled environment.