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
115 \author "Georg Baum,,,"
122 Customizing LyX: Features for the Advanced User
130 \begin_layout Plain Layout
132 If you have comments or error corrections, please send them to the LyX Documenta
134 \begin_inset CommandInset href
136 target "lyx-docs@lists.lyx.org"
143 \begin_inset Quotes eld
147 \begin_inset Quotes erd
150 in the subject header, and please cc the current maintainer of this file,
151 Richard Heck <rgheck@comcast.net>.
157 \begin_inset Newline newline
161 \begin_inset Newline newline
167 \begin_layout Standard
168 \begin_inset CommandInset toc
169 LatexCommand tableofcontents
176 \begin_layout Standard
177 \begin_inset Note Note
180 \begin_layout Plain Layout
181 Please use change tracking when modifying this document.
182 This makes it easier for our translators to recognize things that have
183 been changed, and it helps the maintainer keep up-to-date with what's been
192 \begin_layout Chapter
196 \begin_layout Standard
197 This manual covers the customization features present in LyX.
198 In it, we discuss issues like keyboard shortcuts, screen previewing options,
199 printer options, sending commands to LyX via the LyX Server, internationalizati
200 on, installing new LaTeX classes and LyX layouts, etc.
201 We can't possibly hope to touch on everything you can change—our developers
202 add new features faster than we can document them—but we will explain the
203 most common customizations and hopefully point you in the right direction
204 for some of the more obscure ones.
207 \begin_layout Standard
208 \begin_inset Branch OutDated
211 \begin_layout Standard
212 Information from previous versions of this document that now seems to be
213 outdated is contained in the OutDated branch of this document.
214 By default, this information will not appear in the LaTeX output.
222 \begin_layout Chapter
223 LyX configuration files
226 \begin_layout Standard
227 This chapter aims to help you to find your way through the LyX configuration
229 Before continuing to read this chapter, you should find out where your
230 LyX library and user directories are by using
231 \begin_inset Flex CharStyle:MenuItem
234 \begin_layout Plain Layout
235 Help\SpecialChar \menuseparator
246 The library directory is the place where LyX places its system-wide configurati
247 on files; the user directory is where you can place your modified versions.
248 We will call the former
249 \begin_inset Flex CharStyle:Code
252 \begin_layout Plain Layout
259 \begin_inset Flex CharStyle:MenuItem
262 \begin_layout Plain Layout
268 in the remainder of this document.
272 \begin_layout Section
274 \begin_inset Flex CharStyle:Code
277 \begin_layout Plain Layout
286 \begin_layout Standard
287 \begin_inset Flex CharStyle:Code
290 \begin_layout Plain Layout
296 and its sub-directories contain a number of files and that can be used
297 to customize LyX's behavior.
298 You can change many of these files from within LyX itself through the
299 \begin_inset Flex CharStyle:MenuItem
302 \begin_layout Plain Layout
303 Tools\SpecialChar \menuseparator
310 Most customization that you will want to do in LyX is possible through
312 However, many other inner aspects of LyX can be customized by modifying
314 \begin_inset Flex CharStyle:Code
317 \begin_layout Plain Layout
324 These files fall in different categories, described in the following subsection
328 \begin_layout Subsection
329 Automatically generated files
332 \begin_layout Standard
333 The files, which are to be found in
334 \begin_inset Flex CharStyle:MenuItem
337 \begin_layout Plain Layout
343 , are generated when you configure LyX.
344 They contain various default values that are guessed by inspection.
345 In general, it is not a good idea to modify them, since they might be overwritt
349 \begin_layout Labeling
350 \labelwidthstring 00.00.0000
351 \begin_inset Flex CharStyle:Code
354 \begin_layout Plain Layout
360 contains defaults for various commands.
363 \begin_layout Labeling
364 \labelwidthstring 00.00.0000
365 \begin_inset Flex CharStyle:Code
368 \begin_layout Plain Layout
374 contains the list of packages that have been recognized by LyX.
375 It is currently unused by the LyX program itself, but the information extracted
376 , and more, is made available with
377 \begin_inset Flex CharStyle:MenuItem
380 \begin_layout Plain Layout
381 Help\SpecialChar \menuseparator
394 \begin_layout Labeling
395 \labelwidthstring 00.00.0000
396 \begin_inset Flex CharStyle:Code
399 \begin_layout Plain Layout
405 the list of text classes that have been found in your
406 \begin_inset Flex CharStyle:Code
409 \begin_layout Plain Layout
415 directories, along with the associated LaTeX document class and their descripti
419 \begin_layout Labeling
420 \labelwidthstring 00.00.0000
421 \begin_inset Flex CharStyle:Code
424 \begin_layout Plain Layout
430 the list of layout modules found in your
431 \begin_inset Flex CharStyle:Code
434 \begin_layout Plain Layout
443 \begin_layout Labeling
444 \labelwidthstring 00.00.0000
445 \begin_inset Flex CharStyle:Code
448 \begin_layout Plain Layout
454 lists of various sorts of LaTeX-related files found on your system
457 \begin_layout Labeling
458 \labelwidthstring 00.00.0000
459 \begin_inset Flex CharStyle:Code
462 \begin_layout Plain Layout
468 is automatically generated during configuration from the file
469 \begin_inset Flex CharStyle:Code
472 \begin_layout Plain Layout
479 It contains information on your LaTeX configuration.
482 \begin_layout Subsection
486 \begin_layout Standard
487 These directories are duplicated between
488 \begin_inset Flex CharStyle:Code
491 \begin_layout Plain Layout
498 \begin_inset Flex CharStyle:Code
501 \begin_layout Plain Layout
508 If a particular files exists in both places, the one in
509 \begin_inset Flex CharStyle:Code
512 \begin_layout Plain Layout
521 \begin_layout Labeling
522 \labelwidthstring 00.00.0000
523 \begin_inset Flex CharStyle:Code
526 \begin_layout Plain Layout
532 this directory contains files with the extension
533 \begin_inset Flex CharStyle:Code
536 \begin_layout Plain Layout
542 that define the keybindings used in LyX.
543 If there exists an internationalized version of the bind file named
544 \begin_inset Flex CharStyle:Code
547 \begin_layout Plain Layout
553 , that will be used first.
556 \begin_layout Labeling
557 \labelwidthstring 00.00.0000
558 \begin_inset Flex CharStyle:Code
561 \begin_layout Plain Layout
567 contains graphics files that can be included in documents.
571 \begin_layout Labeling
572 \labelwidthstring 00.00.0000
573 \begin_inset Flex CharStyle:Code
576 \begin_layout Plain Layout
582 contains LyX documentation files (including the one you are currently reading).
584 \begin_inset Flex CharStyle:Code
587 \begin_layout Plain Layout
593 deserves special attention, as noted above.
594 The internationalized help docs are in subdirectories
595 \begin_inset Flex CharStyle:Code
598 \begin_layout Plain Layout
605 \begin_inset Quotes eld
609 \begin_inset Quotes erd
612 is the ISO language code.
618 \begin_inset CommandInset ref
620 reference "chap:i18n"
627 \begin_layout Labeling
628 \labelwidthstring 00.00.0000
629 \begin_inset Flex CharStyle:Code
632 \begin_layout Plain Layout
638 contains example files that explain how to use some features.
639 In the file browser, press the
640 \begin_inset Flex CharStyle:MenuItem
643 \begin_layout Plain Layout
652 \begin_layout Labeling
653 \labelwidthstring 00.00.0000
654 \begin_inset Flex CharStyle:Code
657 \begin_layout Plain Layout
663 contains image files that are used by the
664 \begin_inset Flex CharStyle:MenuItem
667 \begin_layout Plain Layout
674 In addition, it also contains the individual icons used in the toolbar
675 and the banners that can be shown when LyX is launched.
678 \begin_layout Labeling
679 \labelwidthstring 00.00.0000
680 \begin_inset Flex CharStyle:Code
683 \begin_layout Plain Layout
689 contains keyboard keymapping files.
695 \begin_inset CommandInset ref
697 reference "sec:keymap"
704 \begin_layout Labeling
705 \labelwidthstring 00.00.0000
706 \begin_inset Flex CharStyle:Code
709 \begin_layout Plain Layout
715 contains the text class and module files described in Chapter
720 \begin_inset CommandInset ref
722 reference "chap:textclass"
729 \begin_layout Labeling
730 \labelwidthstring 00.00.0000
731 \begin_inset Flex CharStyle:Code
734 \begin_layout Plain Layout
741 \begin_inset Flex CharStyle:Code
744 \begin_layout Plain Layout
750 Python scripts used to convert between LyX versions.
751 These can be run from the command line if, say, you want to batch-convert
755 \begin_layout Labeling
756 \labelwidthstring 00.00.0000
757 \begin_inset Flex CharStyle:Code
760 \begin_layout Plain Layout
766 contains some files that demonstrate the capabilities of the
767 \begin_inset Flex CharStyle:MenuItem
770 \begin_layout Plain Layout
781 Also contains some scripts used by LyX itself.
784 \begin_layout Labeling
785 \labelwidthstring 00.00.0000
786 \begin_inset Flex CharStyle:Code
789 \begin_layout Plain Layout
795 contains the standard LyX template files described in Chapter
800 \begin_inset CommandInset ref
802 reference "sec:templates"
809 \begin_layout Labeling
810 \labelwidthstring 00.00.0000
811 \begin_inset Flex CharStyle:Code
814 \begin_layout Plain Layout
820 contains files with the extension
821 \begin_inset Flex CharStyle:Code
824 \begin_layout Plain Layout
830 that define the user interface to LyX.
831 That is, the files define which items appear in which menus and the items
832 appearing on the toolbar.
835 \begin_layout Subsection
836 Files you don't want to modify
839 \begin_layout Standard
840 These files are used internally by LyX and you generally do not need to
841 modify them unless you are a developer.
844 \begin_layout Labeling
845 \labelwidthstring 00.00.0000
846 \begin_inset Flex CharStyle:Code
849 \begin_layout Plain Layout
855 this file contains the list of LyX developers.
856 The contents are displayed with the menu entry
857 \begin_inset Flex CharStyle:MenuItem
860 \begin_layout Plain Layout
861 Help\SpecialChar \menuseparator
874 \begin_layout Labeling
875 \labelwidthstring 00.00.0000
876 \begin_inset Flex CharStyle:Code
879 \begin_layout Plain Layout
885 this is a LaTeX script used during the configuration process.
889 \begin_layout Labeling
890 \labelwidthstring 00.00.0000
891 \begin_inset Flex CharStyle:Code
894 \begin_layout Plain Layout
900 this is the script that is used to re-configure LyX.
901 It creates configuration files in the directory it was run from.
904 \begin_layout Subsection
905 Other files needing a line or two...
908 \begin_layout Labeling
909 \labelwidthstring 00.00.0000
910 \begin_inset Flex CharStyle:Code
913 \begin_layout Plain Layout
919 this contains tables describing how different character encodings can be
923 \begin_layout Labeling
924 \labelwidthstring 00.00.0000
925 \begin_inset Flex CharStyle:Code
928 \begin_layout Plain Layout
934 this file contains the templates available to the new
935 \begin_inset Flex CharStyle:MenuItem
938 \begin_layout Plain Layout
951 \begin_layout Labeling
952 \labelwidthstring 00.00.0000
953 \begin_inset Flex CharStyle:Code
956 \begin_layout Plain Layout
962 this file contains a list of all the languages currently supported by LyX.
965 \begin_layout Section
966 Your local configuration directory
969 \begin_layout Standard
970 Even if you are using LyX as an unprivileged user, you might want to change
971 LyX configuration for your own use.
973 \begin_inset Flex CharStyle:Code
976 \begin_layout Plain Layout
982 directory contains all your personal configuration files.
983 This is the directory described as
984 \begin_inset Quotes eld
988 \begin_inset Quotes erd
992 \begin_inset Flex CharStyle:MenuItem
995 \begin_layout Plain Layout
996 Help\SpecialChar \menuseparator
1007 This directory is used as a mirror of
1008 \begin_inset Flex CharStyle:Code
1011 \begin_layout Plain Layout
1017 , which means that every file in
1018 \begin_inset Flex CharStyle:Code
1021 \begin_layout Plain Layout
1027 is a replacement for the corresponding file in
1028 \begin_inset Flex CharStyle:Code
1031 \begin_layout Plain Layout
1038 Any configuration file described in the above sections can be placed either
1039 in the system-wide directory, in which case it will affect all users, or
1040 in your local directory for your own use.
1043 \begin_layout Standard
1044 To make things clearer, let's provide a few examples:
1047 \begin_layout Itemize
1048 The preferences set in the
1049 \begin_inset Flex CharStyle:MenuItem
1052 \begin_layout Plain Layout
1053 Tools\SpecialChar \menuseparator
1059 dialog are saved to a file
1060 \begin_inset Flex CharStyle:Code
1063 \begin_layout Plain Layout
1070 \begin_inset Flex CharStyle:Code
1073 \begin_layout Plain Layout
1082 \begin_layout Itemize
1083 When you reconfigure using
1084 \begin_inset Flex CharStyle:MenuItem
1087 \begin_layout Plain Layout
1088 Tools\SpecialChar \menuseparator
1095 \begin_inset Flex CharStyle:Code
1098 \begin_layout Plain Layout
1104 script, and the resulting files are written in your local configuration
1106 This means that any additional text class file that you might have added
1108 \begin_inset Flex CharStyle:Code
1111 \begin_layout Plain Layout
1117 will be added to the list of classes in the
1118 \begin_inset Flex CharStyle:MenuItem
1121 \begin_layout Plain Layout
1122 Document\SpecialChar \menuseparator
1131 \begin_layout Itemize
1132 If you get some updated documentation from LyX ftp site and cannot install
1133 it because you do not have sysadmin rights on your system, you can just
1135 \begin_inset Flex CharStyle:Code
1138 \begin_layout Plain Layout
1144 and the items in the
1145 \begin_inset Flex CharStyle:MenuItem
1148 \begin_layout Plain Layout
1154 menu will open them!
1157 \begin_layout Section
1158 Running LyX with multiple configurations
1161 \begin_layout Standard
1162 The configuration freedom of the local configuration directory may not suffice
1163 if you want to have more than one configuration at your disposal.
1164 For example, you may want to be use different key bindings or printer settings
1166 You can achieve this by having several such directories.
1167 You then specify which directory to use at run-time.
1170 \begin_layout Standard
1171 Invoking LyX with the command line switch
1172 \begin_inset Flex CharStyle:Code
1175 \begin_layout Plain Layout
1185 instructs the program to read the configuration from that directory, and
1186 not from the default directory.
1187 (You can determine the default directory by running LyX without the
1188 \begin_inset Flex CharStyle:Code
1191 \begin_layout Plain Layout
1197 switch.) If the specified directory does not exist, LyX offers to create
1198 it for you, just like it does for the default directory on the first time
1199 you run the program.
1200 You can modify the configuration options in this additional user directory
1201 exactly as you would for the default directory.
1202 These directories are completely independent (but read on).
1203 Note that setting the environment variable
1204 \begin_inset Flex CharStyle:Code
1207 \begin_layout Plain Layout
1213 to some value has exactly the same effect.
1216 \begin_layout Standard
1217 Having several configurations also requires more maintenance: if you want
1218 to add a new layout to
1219 \begin_inset Flex CharStyle:Code
1222 \begin_layout Plain Layout
1228 which you want available from all your configurations, you must add it
1229 to each directory separately.
1230 You can avoid this with the following trick: after LyX creates the additional
1231 directory, most of the subdirectories (see above) are empty.
1232 If you want the new configuration to mirror an existing one, replace the
1233 empty subdirectory with a symbolic link to the matching subdirectory in
1234 the existing configuration.
1236 \begin_inset Flex CharStyle:Code
1239 \begin_layout Plain Layout
1245 subdirectory, however, since it contains a file written by the configuration
1246 script (also accessible through
1247 \begin_inset Flex CharStyle:MenuItem
1250 \begin_layout Plain Layout
1251 Tools\SpecialChar \menuseparator
1257 ) which is configuration-specific.
1260 \begin_layout Chapter
1261 The Preferences dialog
1264 \begin_layout Standard
1265 All options of the preferences dialog are described in the Appendix
1267 The Preferences Dialog
1274 For some options you might find here more details.
1277 \begin_layout Section
1278 Using the dialog for the first time
1281 \begin_layout Standard
1283 \begin_inset Flex CharStyle:Code
1286 \begin_layout Plain Layout
1292 file will contain only changes that you have made to the default behavior,
1293 some of which is hard-coded into LyX and some of which is contained in
1295 \begin_inset Flex CharStyle:Code
1298 \begin_layout Plain Layout
1299 LyXDir/lyxrc.defaults
1305 Note that in both files lines beginning with a
1306 \begin_inset Quotes eld
1310 \begin_inset Quotes erd
1313 are just comments and are not interpreted.
1314 However, only system administrators should edit
1315 \begin_inset Flex CharStyle:Code
1318 \begin_layout Plain Layout
1319 LyXDir/lyxrc.defaults
1325 Users should use the
1326 \begin_inset Flex CharStyle:MenuItem
1329 \begin_layout Plain Layout
1330 Tools\SpecialChar \menuseparator
1336 dialog to create and modify their own
1337 \begin_inset Flex CharStyle:Code
1340 \begin_layout Plain Layout
1349 \begin_layout Standard
1351 \begin_inset Flex CharStyle:MenuItem
1354 \begin_layout Plain Layout
1355 Tools\SpecialChar \menuseparator
1361 dialog will be largely self-explanatory.
1362 Most things in the dialog have associated `tool tips': hover your mouse
1363 pointer over something for more information.
1364 Before we highlight a few of the more important commands below, however,
1365 a word of warning: Applying some of your changes (e.
1366 \begin_inset space \thinspace{}
1370 \begin_inset space \space{}
1373 screen fonts) will have an instant effect.
1375 \begin_inset space \thinspace{}
1379 \begin_inset space \space{}
1382 changing the bind file) will not.
1383 If nothing appears to have changed, just
1384 \begin_inset Flex CharStyle:MenuItem
1387 \begin_layout Plain Layout
1393 the changes and restart LyX.
1396 \begin_layout Section
1400 \begin_layout Standard
1401 LyX has a powerful mechanism to convert to and from any file format using
1406 \begin_layout Subsection
1407 \begin_inset CommandInset label
1416 \begin_layout Standard
1417 The first step is to define your file formats if they are not already defined.
1419 \begin_inset Flex CharStyle:MenuItem
1422 \begin_layout Plain Layout
1423 Tools\SpecialChar \menuseparator
1431 \begin_inset Flex CharStyle:MenuItem
1434 \begin_layout Plain Layout
1435 File Handling\SpecialChar \menuseparator
1442 \begin_inset Flex CharStyle:MenuItem
1445 \begin_layout Plain Layout
1446 New\SpecialChar \ldots{}
1452 button to define your new format.
1454 \begin_inset Flex CharStyle:MenuItem
1457 \begin_layout Plain Layout
1463 field contains the named used to identify the format in the GUI.
1465 \begin_inset Flex CharStyle:MenuItem
1468 \begin_layout Plain Layout
1474 is used to identify the format internally.
1475 You will also need to enter a file extension.
1476 These are all required.
1478 \begin_inset Flex CharStyle:MenuItem
1481 \begin_layout Plain Layout
1487 field is used to provide a keyboard shortcut on the menus.
1488 (For example, pressing
1489 \begin_inset Flex CharStyle:MenuItem
1492 \begin_layout Plain Layout
1499 \begin_inset Flex CharStyle:MenuItem
1502 \begin_layout Plain Layout
1503 View\SpecialChar \menuseparator
1512 \begin_layout Standard
1514 \begin_inset Flex CharStyle:MenuItem
1517 \begin_layout Plain Layout
1524 \begin_inset Flex CharStyle:MenuItem
1527 \begin_layout Plain Layout
1534 For example, you might want to use
1535 \begin_inset Flex CharStyle:MenuItem
1538 \begin_layout Plain Layout
1544 to view PostScript files.
1545 You can enter the command needed to start the program in the corresponding
1547 In defining this command, you can use the four variables listed in the
1549 The viewer is launched when you view an image in LyX or use the
1550 \begin_inset Flex CharStyle:MenuItem
1553 \begin_layout Plain Layout
1560 The editor is for example launched when you press the
1561 \begin_inset Flex CharStyle:MenuItem
1564 \begin_layout Plain Layout
1571 \begin_inset Flex CharStyle:MenuItem
1574 \begin_layout Plain Layout
1581 \begin_inset Flex CharStyle:MenuItem
1584 \begin_layout Plain Layout
1593 \begin_layout Standard
1595 \begin_inset Flex CharStyle:MenuItem
1598 \begin_layout Plain Layout
1604 option tells LyX that a format is suitable for document export.
1605 If this is is set and if a suitable conversion route exists (see
1606 \begin_inset CommandInset ref
1608 reference "sub:Converters"
1612 ), the format will appear in the
1613 \begin_inset Flex CharStyle:MenuItem
1616 \begin_layout Plain Layout
1617 File\SpecialChar \menuseparator
1624 The format will also appear in the
1625 \begin_inset Flex CharStyle:MenuItem
1628 \begin_layout Plain Layout
1634 menu if a viewer is specified for the format.
1635 Pure image formats, such as
1636 \begin_inset Flex CharStyle:Code
1639 \begin_layout Plain Layout
1645 , should not use this option.
1646 Formats that can both represent vector graphics and documents like
1647 \begin_inset Flex CharStyle:Code
1650 \begin_layout Plain Layout
1659 \begin_layout Standard
1661 \begin_inset Flex CharStyle:MenuItem
1664 \begin_layout Plain Layout
1665 Vector graphics format
1670 tells LyX that a format can contain vector graphics.
1671 This information is used to determine the target format of included graphics
1673 \begin_inset Flex CharStyle:MenuItem
1676 \begin_layout Plain Layout
1683 Included graphics may need to be converted to either
1684 \begin_inset Flex CharStyle:MenuItem
1687 \begin_layout Plain Layout
1694 \begin_inset Flex CharStyle:MenuItem
1697 \begin_layout Plain Layout
1704 \begin_inset Flex CharStyle:MenuItem
1707 \begin_layout Plain Layout
1714 \begin_inset Flex CharStyle:MenuItem
1717 \begin_layout Plain Layout
1723 cannot handle other image formats.
1724 If an included graphic is not already in
1725 \begin_inset Flex CharStyle:MenuItem
1728 \begin_layout Plain Layout
1735 \begin_inset Flex CharStyle:MenuItem
1738 \begin_layout Plain Layout
1745 \begin_inset Flex CharStyle:MenuItem
1748 \begin_layout Plain Layout
1754 format, it is converted to
1755 \begin_inset Flex CharStyle:MenuItem
1758 \begin_layout Plain Layout
1764 if the vector format option is set, and otherwise to
1765 \begin_inset Flex CharStyle:MenuItem
1768 \begin_layout Plain Layout
1777 \begin_layout Subsection
1781 \begin_layout Standard
1782 Since all conversions from one format to another take place in LyX's temporary
1783 directory, it is sometimes necessary to modify a file before copying it
1784 to the temporary directory in order that the conversion may be performed.
1788 \begin_layout Plain Layout
1789 For example, the file may refer to other files—images, for example—using
1790 relative file names, and these may become invalid when the file is copied
1791 to the temporary directory.
1796 This is done by a Copier: It copies a file to (or from) the temporary directory
1797 and may modify it in the process.
1800 \begin_layout Standard
1801 The definitions of the copiers may use four variables:
1804 \begin_layout Labeling
1805 \labelwidthstring 00.00.0000
1806 \begin_inset Flex CharStyle:Code
1809 \begin_layout Plain Layout
1815 The LyX system directory (e.
1816 \begin_inset space \thinspace{}
1820 \begin_inset space \space{}
1824 \begin_inset Flex CharStyle:MenuItem
1827 \begin_layout Plain Layout
1836 \begin_layout Labeling
1837 \labelwidthstring 00.00.0000
1838 \begin_inset Flex CharStyle:Code
1841 \begin_layout Plain Layout
1850 \begin_layout Labeling
1851 \labelwidthstring 00.00.0000
1852 \begin_inset Flex CharStyle:Code
1855 \begin_layout Plain Layout
1864 \begin_layout Labeling
1865 \labelwidthstring 00.00.0000
1866 \begin_inset Flex CharStyle:Code
1869 \begin_layout Plain Layout
1878 \begin_layout Standard
1879 The latter should be the filename as it would be used in a LaTeX's
1886 It is relevant only when exporting files suitable for such inclusion.
1889 \begin_layout Standard
1890 Copiers can be used to do almost anything with output files.
1891 For example, suppose you want generated pdf files to be copied to a special
1893 \begin_inset Flex CharStyle:Code
1896 \begin_layout Plain Layout
1903 Then you could write a shell script such as this one:
1906 \begin_layout Standard
1907 \begin_inset listings
1911 \begin_layout Plain Layout
1916 \begin_layout Plain Layout
1921 \begin_layout Plain Layout
1923 TOFILE=`basename $2`
1926 \begin_layout Plain Layout
1928 cp $FROMFILE /home/you/pdf/$TOFILE
1933 Save that in your local LyX directory—say,
1934 \begin_inset Flex CharStyle:Code
1937 \begin_layout Plain Layout
1938 /home/you/.lyx/scripts/pdfcopier.sh
1943 —and make it executable, if you need to do so on your platform.
1945 \begin_inset Flex CharStyle:MenuItem
1948 \begin_layout Plain Layout
1949 Tools\SpecialChar \menuseparator
1955 dialog, select under
1956 \begin_inset Flex CharStyle:MenuItem
1959 \begin_layout Plain Layout
1960 File Handling\SpecialChar \menuseparator
1967 \begin_inset Flex CharStyle:MenuItem
1970 \begin_layout Plain Layout
1976 format—or one of the other pdf formats—and enter
1977 \begin_inset Flex CharStyle:Code
1980 \begin_layout Plain Layout
1981 pdfcopier.sh $$i $$o
1987 \begin_inset Flex CharStyle:MenuItem
1990 \begin_layout Plain Layout
2000 \begin_layout Standard
2001 Copiers are used by LyX in various of its own conversions.
2002 For example, if appropriate programs are found, LyX will automatically
2003 install copiers for the
2004 \begin_inset Flex CharStyle:MenuItem
2007 \begin_layout Plain Layout
2014 \begin_inset Flex CharStyle:MenuItem
2017 \begin_layout Plain Layout
2019 \begin_inset space ~
2028 When these formats are exported, the copier sees that not just the main
2029 HTML file but various associated files (style files, images, etc.) are also
2031 All these files are written to a subdirectory of the directory in which
2032 the original LyX file was found.
2036 \begin_layout Plain Layout
2037 This copier can be customized.
2039 \begin_inset Quotes eld
2043 \begin_inset Quotes erd
2046 argument takes a comma-separated list of extensions to be copied; if it
2047 is omitted, all files will be copied.
2049 \begin_inset Quotes eld
2053 \begin_inset Quotes erd
2056 argument determines the extension added to the generated directory.
2058 \begin_inset Quotes eld
2062 \begin_inset Flex CharStyle:MenuItem
2065 \begin_layout Plain Layout
2072 \begin_inset Quotes erd
2075 , so HTML generated from
2076 \begin_inset Flex CharStyle:MenuItem
2079 \begin_layout Plain Layout
2080 /path/to/filename.lyx
2086 \begin_inset Flex CharStyle:MenuItem
2089 \begin_layout Plain Layout
2090 /path/to/filename.html.LyXconv
2104 \begin_layout Subsection
2105 \begin_inset CommandInset label
2107 name "sub:Converters"
2114 \begin_layout Standard
2115 You can define your own Converters to convert files between different formats.
2117 \begin_inset Flex CharStyle:MenuItem
2120 \begin_layout Plain Layout
2121 Tools\SpecialChar \menuseparator
2122 Preferences\SpecialChar \menuseparator
2123 File Handling\SpecialChar \menuseparator
2132 \begin_layout Standard
2133 To define a new converter, select the
2134 \begin_inset Flex CharStyle:MenuItem
2137 \begin_layout Plain Layout
2139 \begin_inset space ~
2148 \begin_inset Flex CharStyle:MenuItem
2151 \begin_layout Plain Layout
2153 \begin_inset space ~
2161 from the drop-down lists, enter the command needed for the conversion,
2163 \begin_inset Flex CharStyle:MenuItem
2166 \begin_layout Plain Layout
2173 Several variables can be used in the definition of converters:
2176 \begin_layout Labeling
2177 \labelwidthstring 00.00.0000
2178 \begin_inset Flex CharStyle:Code
2181 \begin_layout Plain Layout
2187 The LyX system directory
2190 \begin_layout Labeling
2191 \labelwidthstring 00.00.0000
2192 \begin_inset Flex CharStyle:Code
2195 \begin_layout Plain Layout
2204 \begin_layout Labeling
2205 \labelwidthstring 00.00.0000
2206 \begin_inset Flex CharStyle:Code
2209 \begin_layout Plain Layout
2218 \begin_layout Labeling
2219 \labelwidthstring 00.00.0000
2220 \begin_inset Flex CharStyle:Code
2223 \begin_layout Plain Layout
2229 The base filename of the input file (i.
2230 \begin_inset space \thinspace{}
2233 g., without the extension)
2236 \begin_layout Labeling
2237 \labelwidthstring 00.00.0000
2238 \begin_inset Flex CharStyle:Code
2241 \begin_layout Plain Layout
2247 The path to the input file
2250 \begin_layout Labeling
2251 \labelwidthstring 00.00.0000
2252 \begin_inset Flex CharStyle:Code
2255 \begin_layout Plain Layout
2261 The path to the original input file (this is different from $$p when chain
2262 of converters is called).
2265 \begin_layout Standard
2267 \begin_inset Flex CharStyle:MenuItem
2270 \begin_layout Plain Layout
2272 \begin_inset space ~
2280 field you can enter the following flags, separated by commas:
2283 \begin_layout Labeling
2284 \labelwidthstring 00.00.0000
2285 \begin_inset Flex CharStyle:Code
2288 \begin_layout Plain Layout
2294 This converter runs some form of LaTeX.
2295 This will make LyX's LaTeX error logs available.
2298 \begin_layout Labeling
2299 \labelwidthstring 00.00.0000
2300 \begin_inset Flex CharStyle:Code
2303 \begin_layout Plain Layout
2310 \begin_inset Flex CharStyle:MenuItem
2313 \begin_layout Plain Layout
2319 file for the conversion.
2322 \begin_layout Labeling
2323 \labelwidthstring 00.00.0000
2324 \begin_inset Flex CharStyle:Code
2327 \begin_layout Plain Layout
2336 \begin_layout Standard
2337 The following three flags are not really flags at all because they take
2339 \begin_inset Flex CharStyle:MenuItem
2342 \begin_layout Plain Layout
2344 \begin_inset space ~
2348 \begin_inset space ~
2359 \begin_layout Labeling
2360 \labelwidthstring 00.00.0000
2361 \begin_inset Flex CharStyle:Code
2364 \begin_layout Plain Layout
2370 If set, the converter's standard error will be redirected to a file
2371 \begin_inset Flex CharStyle:Code
2374 \begin_layout Plain Layout
2380 , and the script given as argument will be run as:
2381 \begin_inset Flex CharStyle:Code
2384 \begin_layout Plain Layout
2385 script <infile.out >infile.log
2391 The argument may contain
2392 \begin_inset Flex CharStyle:Code
2395 \begin_layout Plain Layout
2404 \begin_layout Labeling
2405 \labelwidthstring 00.00.0000
2406 \begin_inset Flex CharStyle:Code
2409 \begin_layout Plain Layout
2415 The name of the directory in which the converter will dump the generated
2417 LyX will not create this directory, and it does not copy anything into
2418 it, though it will copy this directory to the destination.
2419 The argument may contain
2420 \begin_inset Flex CharStyle:Code
2423 \begin_layout Plain Layout
2429 , which will be replaced by the base name of the input and output files,
2430 respectively, when the directory is copied.
2431 \begin_inset Newline newline
2434 Note that resultdir and usetempdir make no sense together.
2435 The latter will be ignored if the former is given.
2438 \begin_layout Labeling
2439 \labelwidthstring 00.00.0000
2440 \begin_inset Flex CharStyle:Code
2443 \begin_layout Plain Layout
2449 Determines the output file name and may, contain
2450 \begin_inset Flex CharStyle:Code
2453 \begin_layout Plain Layout
2460 Sensible only with resultdir and optional even then; if not given, it defaults
2464 \begin_layout Standard
2465 None of these last three are presently used in any of the converters that
2466 are installed with LyX.
2470 \begin_layout Standard
2471 You do not have to define converters between all the formats between which
2472 you want to convert.
2473 For example, you will note that there is no `LyX to PostScript' converter,
2474 but LyX will export PostScript.
2475 It does so by first creating a LaTeX file (no converter needs to be defined
2476 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2477 and finally converting the resulting DVI file to PostScript.
2478 LyX finds such `chains' of converters automatically, and it will always
2479 choose the shortest possible chain.
2480 You can, though, still define multiple conversion methods between file
2482 For example, the standard LyX configuration provides three ways to convert
2483 LaTeX to PDF: Directly, using
2484 \begin_inset Flex CharStyle:MenuItem
2487 \begin_layout Plain Layout
2493 ; via (DVI and) PostScript, using
2494 \begin_inset Flex CharStyle:MenuItem
2497 \begin_layout Plain Layout
2504 \begin_inset Flex CharStyle:MenuItem
2507 \begin_layout Plain Layout
2514 To define such alternate chains, you must define multiple target `file
2515 formats', as described in section
2516 \begin_inset CommandInset ref
2518 reference "sub:Formats"
2523 For example, in the standard configuration, the formats named
2524 \begin_inset Flex CharStyle:MenuItem
2527 \begin_layout Plain Layout
2534 \begin_inset Flex CharStyle:MenuItem
2537 \begin_layout Plain Layout
2544 \begin_inset Flex CharStyle:MenuItem
2547 \begin_layout Plain Layout
2553 are defined, all of which share the extension
2554 \begin_inset Flex CharStyle:MenuItem
2557 \begin_layout Plain Layout
2563 , and which correspond to the conversion methods just mentioned.
2566 \begin_layout Chapter
2567 Internationalizing LyX
2568 \begin_inset CommandInset label
2577 \begin_layout Standard
2578 LyX supports using a translated interface.
2579 Last time we checked, LyX provided text in thirty languages.
2580 The language of choice is called your
2585 (For further reading on locale settings, see also the documentation for
2586 locale that comes with your operating system.
2587 For Linux, the manual page for
2588 \begin_inset Flex CharStyle:Code
2591 \begin_layout Plain Layout
2597 could be a good place to start).
2600 \begin_layout Standard
2601 Notice that these translations will work, but do contain a few flaws.
2602 In particular, all dialogs have been designed with the English text in
2603 mind, which means that some of the translated text will be too large to
2604 fit within the space allocated.
2605 This is only a display problem and will not cause any harm.
2606 Also, you will find that some of the translations do not define shortcut
2607 keys for everything.
2608 Sometimes, there are simply not enough free letters to do it.
2609 Other times, the translator just hasn't got around to doing it yet.
2610 Our localization team, which you may wish to join,
2614 \begin_layout Plain Layout
2615 If you are a fluent speaker of a language other than English, joining these
2616 teams is a great way to give back to the LyX community!
2621 will of course try to fix these shortcomings in future versions of LyX.
2624 \begin_layout Section
2628 \begin_layout Subsection
2629 Translating the graphical user interface (text messages).
2632 \begin_layout Standard
2634 \begin_inset Flex CharStyle:Code
2637 \begin_layout Plain Layout
2643 library to handle the internationalization of the interface.
2644 To have LyX speak your favorite language in all menus and dialogs, you
2646 \begin_inset Flex CharStyle:Code
2649 \begin_layout Plain Layout
2655 -file for that language.
2656 When this is available, you'll have to generate a
2657 \begin_inset Flex CharStyle:Code
2660 \begin_layout Plain Layout
2666 -file from it and install the
2667 \begin_inset Flex CharStyle:Code
2670 \begin_layout Plain Layout
2677 The process of doing all of this is explained in the documentation for
2679 \begin_inset Flex CharStyle:Code
2682 \begin_layout Plain Layout
2689 It is possible to do this just for yourself, but if you're going to do
2690 it, you might as well share the results of your labors with the rest of
2692 Send a message to the LyX developers' list for more information about how
2696 \begin_layout Standard
2697 In short, this is what you should do (xx denotes the language code):
2700 \begin_layout Itemize
2701 Check out the LyX source code.
2703 \begin_inset CommandInset href
2705 name "information on the web"
2706 target "http://www.lyx.org/devel/cvs.php"
2713 \begin_layout Itemize
2715 \begin_inset Flex CharStyle:Code
2718 \begin_layout Plain Layout
2724 to the folder of the
2725 \begin_inset Flex CharStyle:Code
2728 \begin_layout Plain Layout
2736 \begin_inset Flex CharStyle:Code
2739 \begin_layout Plain Layout
2747 \begin_inset Flex CharStyle:Code
2750 \begin_layout Plain Layout
2756 doesn't exist anywhere, it can be remade with the console command
2757 \begin_inset Flex CharStyle:Code
2760 \begin_layout Plain Layout
2766 in that directory, or you can use an existing po-file for some other language
2770 \begin_layout Itemize
2772 \begin_inset Flex CharStyle:Code
2775 \begin_layout Plain Layout
2785 \begin_layout Plain Layout
2786 This is just a text file, so it can be edited in any text editor.
2787 But there are also specialized programs that support such editing, such
2792 (for all platforms) or
2801 contains a `mode' for editing
2802 \begin_inset Flex CharStyle:Code
2805 \begin_layout Plain Layout
2816 For some menu- and widget-labels, there are also shortcut keys that should
2818 Those keys are marked after a `|', and should be translated according to
2819 the words and phrases of the language.
2820 You should also fill also out the information at the beginning of the new
2822 \begin_inset Flex CharStyle:Code
2825 \begin_layout Plain Layout
2831 -file with your email-address, etc., so people know where to reach you with
2832 suggestions and entertaining flames.
2835 \begin_layout Standard
2836 If you are just doing this on your own, then:
2839 \begin_layout Itemize
2841 \begin_inset Flex CharStyle:Code
2844 \begin_layout Plain Layout
2851 This can be done with
2852 \begin_inset Flex CharStyle:Code
2855 \begin_layout Plain Layout
2856 msgfmt -o xx.mo < xx.po
2864 \begin_layout Itemize
2866 \begin_inset Flex CharStyle:Code
2869 \begin_layout Plain Layout
2875 -file to your locale-tree, at the correct directory for application messages
2880 xx, and under the name
2881 \begin_inset Flex CharStyle:Code
2884 \begin_layout Plain Layout
2891 \begin_inset space \thinspace{}
2895 \begin_inset space \space{}
2899 \begin_inset Flex CharStyle:Code
2902 \begin_layout Plain Layout
2903 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2913 \begin_layout Standard
2914 As said, however, it would be best if the new
2915 \begin_inset Flex CharStyle:Code
2918 \begin_layout Plain Layout
2924 -file could be added to the LyX distribution, so others can use it.
2925 Adding it involves making additional changes to LyX.
2926 So send an email to the developers' mailing list if you're interested in
2930 \begin_layout Subsubsection
2934 \begin_layout Standard
2935 Sometimes it turns out that one English message needs to be translated into
2936 different messages in the target language.
2937 One example is the message
2938 \begin_inset Flex CharStyle:Code
2941 \begin_layout Plain Layout
2947 which has the German translation
2955 , depending upon exactly what the English
2956 \begin_inset Quotes eld
2960 \begin_inset Quotes erd
2965 \begin_inset Flex CharStyle:Code
2968 \begin_layout Plain Layout
2974 does not handle such ambiguous translations.
2975 Therefore you have to add some context information to the message: Instead
2977 \begin_inset Flex CharStyle:Code
2980 \begin_layout Plain Layout
2987 \begin_inset Flex CharStyle:Code
2990 \begin_layout Plain Layout
2991 To[[as in 'From format x to format y']]
2997 \begin_inset Flex CharStyle:Code
3000 \begin_layout Plain Layout
3001 To[[as in 'From page x to page y']].
3006 Now the two occurrences of
3007 \begin_inset Flex CharStyle:Code
3010 \begin_layout Plain Layout
3017 \begin_inset Flex CharStyle:Code
3020 \begin_layout Plain Layout
3026 and can be translated correctly to
3037 \begin_layout Standard
3038 Of course the context information needs to be stripped off the original
3039 message when no translation is used.
3040 Therefore you have to put it in double square brackets at the end of the
3041 message (see the example above).
3042 The translation mechanism of LyX ensures that everything in double square
3043 brackets at the end of messages is removed before displaying the message.
3046 \begin_layout Subsection
3047 Translating the documentation.
3050 \begin_layout Standard
3051 The online documentation (in the
3052 \begin_inset Flex CharStyle:MenuItem
3055 \begin_layout Plain Layout
3061 -menu) can (and should!) be translated.
3062 If there are translated versions of the documentation available
3066 \begin_layout Plain Layout
3067 As of March 2008, at least some of the documents have been translated into
3068 fourteen languages, with the Tutorial available in a few more.
3073 and the locale is set accordingly, these will be used automagically by
3075 LyX looks for translated versions as
3076 \begin_inset Flex CharStyle:Code
3079 \begin_layout Plain Layout
3080 LyXDir/doc/xx/DocName.lyx
3086 \begin_inset Flex CharStyle:Code
3089 \begin_layout Plain Layout
3095 is the code for the language currently in use.
3096 If there are no translated documents, the default English versions will
3098 Note that the translated versions must have the same filenames (
3099 \begin_inset Flex CharStyle:Code
3102 \begin_layout Plain Layout
3108 above) as the original.
3109 If you feel up to translating the documentation (an excellent way to proof-read
3110 the original documentation by the way!), there are a few things you should
3114 \begin_layout Itemize
3116 \begin_inset Flex CharStyle:Code
3119 \begin_layout Plain Layout
3125 , the guide to writing LyX documentation.
3126 Pay special attention to the translator's section.
3129 \begin_layout Itemize
3130 Check out the documentation translation web page at
3131 \begin_inset CommandInset href
3133 name "http://www.lyx.org/Translation"
3134 target "http://www.lyx.org/Translation"
3139 That way, you can find out which (if any) documents have already been translate
3140 d into your language.
3141 You can also find out who (if anyone) is organizing the effort to translate
3142 the documentation into your language.
3143 If no one is organizing the effort, please let us know that you're interested.
3146 \begin_layout Standard
3147 Once you get to actually translating, here's a few hints for you that may
3151 \begin_layout Itemize
3152 Join the documentation team! There is information on how to do that in
3153 \begin_inset Flex CharStyle:Code
3156 \begin_layout Plain Layout
3163 \begin_inset Flex CharStyle:MenuItem
3166 \begin_layout Plain Layout
3167 Help\SpecialChar \menuseparator
3177 ), which by the way is the first document you should translate.
3180 \begin_layout Itemize
3181 Learn the typographic conventions for the language you are translating to.
3182 Typography is an ancient art and over the centuries, a great variety of
3183 conventions have developed throughout different parts of the world.
3184 Also study the professional terminology amongst typographers in your country.
3185 Inventing your own terminology will only confuse the users.
3188 (Warning! Typography is addictive!)
3191 \begin_layout Itemize
3192 Make a copy of the document.
3193 This will be your working copy.
3194 You can use this as your personal translated help-file by placing it in
3196 \begin_inset Flex CharStyle:Code
3199 \begin_layout Plain Layout
3208 \begin_layout Itemize
3209 Sometimes the original document (from the LyX-team) will be updated.
3210 Use the source viewer at
3211 \begin_inset CommandInset href
3213 name "http://www.lyx.org/trac/timeline"
3214 target "http://www.lyx.org/trac/timeline"
3218 to see what has been changed.
3219 That way you can easily see which parts of the translated document need
3223 \begin_layout Standard
3224 If you ever find an error in the original document, fix it and notify the
3225 rest of the documentation team of the changes! (You didn't forget to join
3226 the documentation team, did you?)
3229 \begin_layout Standard
3230 \begin_inset Branch OutDated
3233 \begin_layout Section
3234 International Keyboard Support
3237 \begin_layout Standard
3240 [Editor's Note: The following section is by
3248 It needs to be fixed to conform to the new Documentation Style sheet and
3249 to make use of the new v1.0 features.
3250 The whole thing also needs to be merged with the section following it.-jw
3251 It may also be badly out of date.-rh (2008)]
3254 \begin_layout Subsection
3255 Defining Own Keymaps: Keymap File Format
3258 \begin_layout Standard
3259 Let's look at a keyboard definition file a little closer.
3260 It is a plain text file defining
3263 \begin_layout Itemize
3264 key-to-key or key-to-string translations
3267 \begin_layout Itemize
3271 \begin_layout Itemize
3272 dead keys exceptions
3275 \begin_layout Standard
3276 To define key-to-key or key-to-string translation, use this command:
3279 \begin_layout Quotation
3280 \begin_inset Flex CharStyle:Code
3283 \begin_layout Plain Layout
3292 \begin_inset Flex CharStyle:Code
3295 \begin_layout Plain Layout
3304 \begin_layout Standard
3306 \begin_inset Flex CharStyle:Code
3309 \begin_layout Plain Layout
3315 is the key to be translated and
3316 \begin_inset Flex CharStyle:Code
3319 \begin_layout Plain Layout
3325 is the string to be inserted into the document.
3326 To define dead keys, use:
3329 \begin_layout Quotation
3330 \begin_inset Flex CharStyle:Code
3333 \begin_layout Plain Layout
3342 \begin_inset Flex CharStyle:Code
3345 \begin_layout Plain Layout
3354 \begin_layout Standard
3356 \begin_inset Flex CharStyle:Code
3359 \begin_layout Plain Layout
3365 is a keyboard key and
3366 \begin_inset Flex CharStyle:Code
3369 \begin_layout Plain Layout
3376 The following dead keys are supported (shortcut name is in parentheses):
3379 \begin_layout Quotation
3383 \begin_inset space \hfill{}
3389 \begin_layout Quotation
3391 \begin_inset space \hfill{}
3397 \begin_layout Quotation
3399 \begin_inset space \hfill{}
3405 \begin_layout Quotation
3407 \begin_inset space \hfill{}
3413 \begin_layout Quotation
3415 \begin_inset space \hfill{}
3421 \begin_layout Quotation
3423 \begin_inset space \hfill{}
3430 \begin_layout Plain Layout
3442 \begin_layout Quotation
3444 \begin_inset space \hfill{}
3450 \begin_layout Quotation
3452 \begin_inset space \hfill{}
3459 \begin_layout Plain Layout
3471 \begin_layout Quotation
3473 \begin_inset space \hfill{}
3479 \begin_layout Quotation
3481 \begin_inset space \hfill{}
3487 \begin_layout Quotation
3489 \begin_inset space \hfill{}
3496 \begin_layout Plain Layout
3508 \begin_layout Quotation
3510 \begin_inset space \hfill{}
3517 \begin_layout Plain Layout
3529 \begin_layout Quotation
3531 \begin_inset space \hfill{}
3537 \begin_layout Quotation
3538 hungarian umlaut (hug)
3539 \begin_inset space \hfill{}
3545 \begin_layout Quotation
3547 \begin_inset space \hfill{}
3553 \begin_layout Quotation
3555 \begin_inset space \hfill{}
3562 \begin_layout Plain Layout
3574 \begin_layout Standard
3575 Since in many international keyboards there are exceptions to what some
3576 dead keys should do, you can define them using
3579 \begin_layout Quotation
3580 \begin_inset Flex CharStyle:Code
3583 \begin_layout Plain Layout
3591 deadkey key outstring
3594 \begin_layout Standard
3595 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3599 \begin_layout Quotation
3600 \begin_inset Flex CharStyle:Code
3603 \begin_layout Plain Layout
3616 \begin_layout Standard
3617 to make it work correctly.
3618 Also, you have to define as exceptions dead keys over i and j, to remove
3619 the dot from them before inserting an accent mark.
3620 I will change this when the time comes, but so far I haven't had time.
3623 \begin_layout Standard
3624 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3627 \begin_inset Flex CharStyle:Code
3630 \begin_layout Plain Layout
3636 have different meaning.
3638 \begin_inset Flex CharStyle:Code
3641 \begin_layout Plain Layout
3647 marks comments, quotes start and end LaTeX-style commands.
3648 To enter quote, you'll need to use
3649 \begin_inset Flex CharStyle:Code
3652 \begin_layout Plain Layout
3661 \begin_inset Flex CharStyle:Code
3664 \begin_layout Plain Layout
3671 \begin_inset Flex CharStyle:Code
3674 \begin_layout Plain Layout
3685 \begin_layout Standard
3686 If you make a keyboard description file that works for your language, please
3687 mail it to me, so I can include it in the next keymap distribution.
3690 \begin_layout Standard
3691 More keywords will be supported in keymap configuration file in future,
3695 \begin_layout Itemize
3696 \begin_inset Flex CharStyle:Code
3699 \begin_layout Plain Layout
3710 \begin_inset space \hfill{}
3714 \begin_inset Flex CharStyle:Code
3717 \begin_layout Plain Layout
3726 \begin_layout Itemize
3727 \begin_inset Flex CharStyle:Code
3730 \begin_layout Plain Layout
3741 \begin_inset space \hfill{}
3745 \begin_inset Flex CharStyle:Code
3748 \begin_layout Plain Layout
3754 an external keymap translation program
3757 \begin_layout Standard
3758 Also, it should look into
3759 \begin_inset Flex CharStyle:Code
3762 \begin_layout Plain Layout
3768 file for defaults, too (for example, a
3769 \begin_inset Flex CharStyle:Code
3772 \begin_layout Plain Layout
3780 option to include default keyboard).
3788 \begin_layout Section
3789 \begin_inset CommandInset label
3795 International Keymap Stuff
3798 \begin_layout Standard
3799 \begin_inset Note Note
3802 \begin_layout Plain Layout
3803 In doing the revisions on this document in March 2008, I did not look over
3804 this stuff, as I do not understand it.
3805 It would be good if someone else could do so.
3814 \begin_layout Standard
3815 The next two sections describe the
3816 \begin_inset Flex CharStyle:Code
3819 \begin_layout Plain Layout
3828 \begin_inset Flex CharStyle:Code
3831 \begin_layout Plain Layout
3839 file syntax in detail.
3840 These sections should help you design your own key map if the ones provided
3841 do not meet your needs.
3844 \begin_layout Subsection
3848 \begin_layout Standard
3852 \begin_inset Flex CharStyle:Code
3855 \begin_layout Plain Layout
3861 file maps keystrokes to characters or strings.
3862 As the name suggests, it sets a keyboard mapping.
3864 \begin_inset Flex CharStyle:Code
3867 \begin_layout Plain Layout
3878 \begin_inset Flex CharStyle:Code
3881 \begin_layout Plain Layout
3896 \begin_inset Flex CharStyle:Code
3899 \begin_layout Plain Layout
3912 \begin_inset Flex CharStyle:Code
3915 \begin_layout Plain Layout
3924 \begin_inset Flex CharStyle:Code
3927 \begin_layout Plain Layout
3935 are described in this section.
3938 \begin_layout Labeling
3939 \labelwidthstring 00.00.0000
3940 \begin_inset Flex CharStyle:Code
3943 \begin_layout Plain Layout
3951 Map a character to a string
3954 \begin_layout LyX-Code
3969 \begin_layout Standard
4002 the double-quote (")
4019 must be escaped with a preceding backslash (
4030 \begin_layout Standard
4032 \begin_inset Flex CharStyle:MenuItem
4035 \begin_layout Plain Layout
4043 statement to cause the symbol
4044 \begin_inset Flex CharStyle:MenuItem
4047 \begin_layout Plain Layout
4055 to be output for the keystroke
4056 \begin_inset Flex CharStyle:MenuItem
4059 \begin_layout Plain Layout
4070 \begin_layout LyX-Code
4076 \begin_layout Labeling
4077 \labelwidthstring 00.00.0000
4078 \begin_inset Flex CharStyle:Code
4081 \begin_layout Plain Layout
4089 Specify an accent character
4092 \begin_layout LyX-Code
4101 \begin_layout Standard
4102 This will make the cha
4140 This is the dead key
4144 \begin_layout Plain Layout
4151 refers to a key that does not produce a character by itself, but when followed
4152 with another key, produces the desired accent character.
4153 For example, a German characte
4155 r with an umlaut like
4165 can be produced in this manner.
4174 \begin_layout Standard
4187 and then another key not in
4204 followed by the other, not allowed key, as output.
4208 \begin_inset Flex CharStyle:MenuItem
4211 \begin_layout Plain Layout
4219 cancels a dead key, so if
4230 \begin_inset Flex CharStyle:MenuItem
4233 \begin_layout Plain Layout
4242 , the cursor will not go one position backwards but will instead cancel
4258 might have had on the next keystroke.
4262 \begin_layout Standard
4263 The following example specifies that the character ' is to be an acute accent,
4264 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4267 \begin_layout LyX-Code
4270 kmod ' acute aeiouAEIOU
4273 \begin_layout Labeling
4274 \labelwidthstring 00.00.0000
4275 \begin_inset Flex CharStyle:Code
4278 \begin_layout Plain Layout
4284 Specify an exception to the accent character
4287 \begin_layout LyX-Code
4296 \begin_layout Standard
4297 This defines an exce
4338 have been assigned a keystroke with a previous
4341 \begin_inset Flex CharStyle:Code
4344 \begin_layout Plain Layout
4368 must not belong in the
4415 If such a declaration does not exist in
4423 \begin_inset Flex CharStyle:Code
4426 \begin_layout Plain Layout
4460 \begin_inset Flex CharStyle:Code
4463 \begin_layout Plain Layout
4477 \begin_layout Standard
4478 The following command produces causes äi to be produced when you enter acute-i
4482 \begin_layout LyX-Code
4496 \begin_layout Labeling
4497 \labelwidthstring 00.00.0000
4498 \begin_inset Flex CharStyle:Code
4501 \begin_layout Plain Layout
4507 Combine two accent characters
4510 \begin_layout LyX-Code
4516 accent1 accent2 allowed
4519 \begin_layout Standard
4520 This one is getting pretty esoteric.
4521 It allows you to combine the effect
4577 \begin_inset Flex CharStyle:Code
4580 \begin_layout Plain Layout
4608 \begin_layout Standard
4609 Consider this example from the
4610 \begin_inset Flex CharStyle:Code
4613 \begin_layout Plain Layout
4624 \begin_layout LyX-Code
4627 kmod ; acute aeioyvhAEIOYVH
4631 kcomb acute umlaut iyIY
4634 \begin_layout Standard
4635 This allows you to press
4636 \begin_inset Flex CharStyle:MenuItem
4639 \begin_layout Plain Layout
4647 and get the effect of
4648 \begin_inset Flex CharStyle:Code
4651 \begin_layout Plain Layout
4670 in this case cancels the last dead key, so if you press
4671 \begin_inset Flex CharStyle:MenuItem
4674 \begin_layout Plain Layout
4683 \begin_inset Flex CharStyle:Code
4686 \begin_layout Plain Layout
4699 \begin_layout Subsection
4703 \begin_layout Standard
4705 \begin_inset Flex CharStyle:Code
4708 \begin_layout Plain Layout
4716 mapping is performed, a
4717 \begin_inset Flex CharStyle:Code
4720 \begin_layout Plain Layout
4730 file maps the strings that the symbols generate to characters in the current
4732 The LyX distribution currently includes at least the
4733 \begin_inset Flex CharStyle:Code
4736 \begin_layout Plain Layout
4745 \begin_inset Flex CharStyle:Code
4748 \begin_layout Plain Layout
4759 \begin_layout Standard
4761 \begin_inset Flex CharStyle:Code
4764 \begin_layout Plain Layout
4772 file is a sequence of declarations of the form
4775 \begin_layout LyX-Code
4788 \begin_layout Standard
4789 For example, in order to map
4790 \begin_inset Flex CharStyle:MenuItem
4793 \begin_layout Plain Layout
4803 to the corresponding character in the iso-8859-1 set (233), the following
4807 \begin_layout LyX-Code
4815 \begin_layout Standard
4817 \begin_inset Flex CharStyle:Code
4820 \begin_layout Plain Layout
4829 \begin_inset Flex CharStyle:Code
4832 \begin_layout Plain Layout
4850 the same character can apply to more than one string.
4852 \begin_inset Flex CharStyle:Code
4855 \begin_layout Plain Layout
4866 \begin_layout LyX-Code
4878 \begin_inset Newline newline
4894 \begin_layout Standard
4895 If LyX cannot find a mapping for the string produced by the keystroke or
4896 a deadkey sequence, it will check if it looks like an accented char and
4897 try to draw an accent over the character on screen.
4900 \begin_layout Subsection
4904 \begin_layout Standard
4905 There is a second way to add support for international characters through
4906 so-called dead-keys.
4907 A dead-key works in combination with a letter to produce an accented character.
4908 Here, we'll explain how to create a really simple dead-key to illustrate
4912 \begin_layout Standard
4913 Suppose you happen to need the circumflex character,
4914 \begin_inset Quotes eld
4918 \begin_inset Quotes erd
4923 \begin_inset Flex CharStyle:MenuItem
4926 \begin_layout Plain Layout
4933 \begin_inset space ~
4937 \begin_inset Flex CharStyle:MenuItem
4940 \begin_layout Plain Layout
4946 ] to the LyX command
4947 \begin_inset Flex CharStyle:Code
4950 \begin_layout Plain Layout
4957 \begin_inset Flex CharStyle:Code
4960 \begin_layout Plain Layout
4967 Now, whenever you type the
4968 \begin_inset Flex CharStyle:MenuItem
4971 \begin_layout Plain Layout
4977 -key followed by a letter, that letter will have a circumflex accent on
4979 For example, the sequence
4980 \begin_inset Quotes eld
4984 \begin_inset Flex CharStyle:MenuItem
4987 \begin_layout Plain Layout
4994 \begin_inset Quotes erd
4997 produces the letter:
4998 \begin_inset Quotes eld
5002 \begin_inset Quotes erd
5006 If you tried to type
5007 \begin_inset Quotes eld
5011 \begin_inset Flex CharStyle:MenuItem
5014 \begin_layout Plain Layout
5021 \begin_inset Quotes erd
5024 , however, LyX will complain with a beep, since a
5025 \begin_inset Quotes eld
5029 \begin_inset Flex CharStyle:MenuItem
5032 \begin_layout Plain Layout
5039 \begin_inset Quotes erd
5042 never takes a circumflex accent.
5044 \begin_inset Flex CharStyle:MenuItem
5047 \begin_layout Plain Layout
5053 after a dead-key produces the bare-accent.
5054 Please note this last point! If you bind a key to a dead-key, you'll need
5055 to rebind the character on that key to yet another key.
5057 \begin_inset Flex CharStyle:MenuItem
5060 \begin_layout Plain Layout
5066 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5069 \begin_layout Standard
5070 One common way to bind dead-keys is to use
5071 \begin_inset Flex CharStyle:MenuItem
5074 \begin_layout Plain Layout
5081 \begin_inset Flex CharStyle:MenuItem
5084 \begin_layout Plain Layout
5091 \begin_inset Flex CharStyle:MenuItem
5094 \begin_layout Plain Layout
5100 in combination with an accent, like
5101 \begin_inset Quotes eld
5105 \begin_inset Flex CharStyle:MenuItem
5108 \begin_layout Plain Layout
5115 \begin_inset Quotes erd
5119 \begin_inset Quotes eld
5123 \begin_inset Flex CharStyle:MenuItem
5126 \begin_layout Plain Layout
5133 \begin_inset Quotes erd
5137 \begin_inset Quotes eld
5141 \begin_inset Flex CharStyle:MenuItem
5144 \begin_layout Plain Layout
5151 \begin_inset Quotes erd
5155 Another way involves using
5156 \begin_inset Flex CharStyle:Code
5159 \begin_layout Plain Layout
5166 \begin_inset Flex CharStyle:Code
5169 \begin_layout Plain Layout
5175 to set up the special
5176 \begin_inset Flex CharStyle:Code
5179 \begin_layout Plain Layout
5187 \begin_inset Flex CharStyle:Code
5190 \begin_layout Plain Layout
5196 acts in some ways just like
5197 \begin_inset Flex CharStyle:MenuItem
5200 \begin_layout Plain Layout
5206 and permits you to bind keys to accented characters.
5207 You can also turn keys into dead-keys by binding them to something like
5209 \begin_inset Flex CharStyle:Code
5212 \begin_layout Plain Layout
5218 and then binding this symbolic key to the corresponding LyX command.
5222 \begin_layout Plain Layout
5227 : This is exactly what I do in my
5228 \begin_inset Flex CharStyle:Code
5231 \begin_layout Plain Layout
5238 \begin_inset Flex CharStyle:Code
5241 \begin_layout Plain Layout
5249 \begin_inset Flex CharStyle:MenuItem
5252 \begin_layout Plain Layout
5254 \begin_inset space ~
5263 \begin_inset Flex CharStyle:Code
5266 \begin_layout Plain Layout
5272 and a bunch of these
5273 \begin_inset Quotes eld
5277 \begin_inset Flex CharStyle:Code
5280 \begin_layout Plain Layout
5287 \begin_inset Quotes erd
5290 symbolic keys bound such things as
5291 \begin_inset Flex CharStyle:MenuItem
5294 \begin_layout Plain Layout
5296 \begin_inset space ~
5305 \begin_inset Flex CharStyle:MenuItem
5308 \begin_layout Plain Layout
5310 \begin_inset space ~
5319 This is how I produce my accented characters.
5324 You can make just about anything into the
5325 \begin_inset Flex CharStyle:Code
5328 \begin_layout Plain Layout
5335 \begin_inset Flex CharStyle:MenuItem
5338 \begin_layout Plain Layout
5344 keys, a spare function key, etc.
5345 As for the LyX commands that produce accents, check the entry for
5346 \begin_inset Flex CharStyle:Code
5349 \begin_layout Plain Layout
5360 You'll find the complete list there.
5363 \begin_layout Subsection
5364 Saving your Language Configuration
5367 \begin_layout Standard
5368 You can edit your preferences so that your desired language environment
5369 is automatically configured when LyX starts up, via the
5370 \begin_inset Flex CharStyle:MenuItem
5373 \begin_layout Plain Layout
5374 Edit\SpecialChar \menuseparator
5383 \begin_layout Chapter
5384 Installing New Document Classes, Layouts, and Templates
5385 \begin_inset CommandInset label
5387 name "chap:textclass"
5395 \begin_layout Plain Layout
5396 Installing New Document Classes
5404 \begin_layout Standard
5405 In this chapter, we describe the procedures for creating and installing
5406 new LyX layout and template files, as well as offer a refresher on correctly
5407 installing new LaTeX document classes.
5408 Some definitions: a document class is a LaTeX file (usually ending in
5409 \begin_inset Flex CharStyle:Code
5412 \begin_layout Plain Layout
5419 \begin_inset Flex CharStyle:Code
5422 \begin_layout Plain Layout
5428 ) that describes the format of a document such as an article, report, journal
5429 preprint, etc, and all the commands needed to realize that format.
5430 A layout file is a LyX file that corresponds to a LaTeX document class
5431 and that tells LyX how to
5432 \begin_inset Quotes eld
5436 \begin_inset Quotes erd
5439 things on the screen to make the display look something like the final
5441 More precisely, a layout file describes a
5442 \begin_inset Quotes eld
5446 \begin_inset Quotes erd
5449 which is the internal construct LyX uses to render the screen display.
5451 \begin_inset Quotes eld
5455 \begin_inset Quotes erd
5459 \begin_inset Quotes eld
5463 \begin_inset Quotes erd
5466 can be used somewhat interchangeably, but it is better to refer to the
5467 file as the layout, and the thing living in LyX's memory as the text class.
5468 A template file is simply a LyX document that contains a set of predefined
5469 entries for a given document class—entries that are generally required
5471 Templates are especially useful for things like journal manuscripts that
5472 are to be submitted electronically.
5475 \begin_layout Section
5476 Installing a new LaTeX package
5479 \begin_layout Standard
5480 Some installations may not include a LaTeX package that you would like to
5482 For example, you might need FoilTeX, a package for preparing slides or
5483 viewgraphs for overhead projectors.
5484 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5485 a user interface for that.
5486 For example on MiKTeX you start its program
5487 \begin_inset Quotes eld
5491 \begin_inset Quotes erd
5494 to get a list of available packages.
5495 To install one, right click on it or use the installing toolbar button.
5496 When the package you want to install is not in the list, but you have it
5498 \begin_inset Flex CharStyle:Code
5501 \begin_layout Plain Layout
5508 \begin_inset Flex CharStyle:Code
5511 \begin_layout Plain Layout
5517 -file, then copy these files to a subfolder of your LaTeX distribution,
5518 for example to the folder
5527 Then update the file name database of your LaTeX-distribution.
5528 For example on MiKTeX this is done by pressing the button
5531 \begin_inset space ~
5536 that you find in MiKTeX's
5537 \begin_inset Quotes eld
5541 \begin_inset Quotes erd
5545 In both cases you need afterwards to reconfigure LyX using the menu
5546 \begin_inset Flex CharStyle:MenuItem
5549 \begin_layout Plain Layout
5550 Tools\SpecialChar \menuseparator
5556 and then to restart LyX.
5559 \begin_layout Standard
5560 If your LaTeX distribution doesn't provide a user interface, then you can
5561 follow these steps by using a UNIX/Linux console.
5564 \begin_layout Enumerate
5565 Get the package from
5566 \begin_inset CommandInset href
5569 target "http://www.ctan.org/"
5576 \begin_layout Enumerate
5577 You can install this package in several different places.
5578 If you want it to be available for all users on your system, then you should
5579 install it in your `local' TeX tree; if you want (or need) it to be available
5580 just for you, then you can install it in your own `user' TeX tree.
5581 Where these should be created, if they do not already exist, depends upon
5582 the details of your system.
5583 To find out, look in the file
5584 \begin_inset Flex CharStyle:Code
5587 \begin_layout Plain Layout
5597 \begin_layout Plain Layout
5598 This usually lives in the directory
5599 \begin_inset Flex CharStyle:Code
5602 \begin_layout Plain Layout
5608 , though you can run
5609 \begin_inset Flex CharStyle:Code
5612 \begin_layout Plain Layout
5623 The location of the `local' TeX tree is defined by
5624 \begin_inset Flex CharStyle:Code
5627 \begin_layout Plain Layout
5633 ; this is usually somewhere like
5634 \begin_inset Flex CharStyle:Code
5637 \begin_layout Plain Layout
5638 /usr/local/share/texmf/
5644 The `user' TeX tree is defined by
5645 \begin_inset Flex CharStyle:Code
5648 \begin_layout Plain Layout
5655 \begin_inset Flex CharStyle:Code
5658 \begin_layout Plain Layout
5665 (If these variables are not predefined, you can define them.) You'll probably
5666 need root permissions to create or modify the `local' tree; but your `user'
5667 tree shouldn't have such limitations.
5670 \begin_layout Enumerate
5672 \begin_inset Flex CharStyle:Code
5675 \begin_layout Plain Layout
5682 \begin_inset Flex CharStyle:Code
5685 \begin_layout Plain Layout
5692 \begin_inset Flex CharStyle:Code
5695 \begin_layout Plain Layout
5702 \begin_inset space \thinspace{}
5706 \begin_inset Newline newline
5710 \begin_inset Flex CharStyle:Code
5713 \begin_layout Plain Layout
5714 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5720 \begin_inset Newline newline
5723 But, again, most of this will
5724 \begin_inset Quotes eld
5728 \begin_inset Quotes erd
5734 \begin_layout Enumerate
5739 \begin_layout Plain Layout
5740 We'll assume henceforth that you're defining `local' TeX tree.
5741 If you're defining a user tree, just adjust as necessary.
5747 You must follow the directory structure of your existing
5748 \begin_inset Flex CharStyle:Code
5751 \begin_layout Plain Layout
5757 directory, which will be found at
5758 \begin_inset Flex CharStyle:Code
5761 \begin_layout Plain Layout
5768 For example, latex packages should go under
5769 \begin_inset Flex CharStyle:Code
5772 \begin_layout Plain Layout
5773 $TEXMFLOCAL/tex/latex/
5781 \begin_layout Enumerate
5782 Install the package.
5783 For example, you would unpack the FoilTeX tarball and copy it to
5784 \begin_inset Flex CharStyle:Code
5787 \begin_layout Plain Layout
5788 $TEXMFLOCAL/tex/latex/foiltex
5795 \begin_inset Flex CharStyle:Code
5798 \begin_layout Plain Layout
5804 directory contains various files.
5807 \begin_layout Enumerate
5809 \begin_inset Flex CharStyle:Code
5812 \begin_layout Plain Layout
5820 \begin_inset Flex CharStyle:Code
5823 \begin_layout Plain Layout
5832 \begin_layout Standard
5833 Your package is now installed and available to LaTeX.
5834 To make it available to LyX, you need to create a Layout file, if one is
5835 not already available.
5836 (See the next section.) Once you have a layout file, you need only reconfigure
5838 \begin_inset Flex CharStyle:MenuItem
5841 \begin_layout Plain Layout
5842 Tools\SpecialChar \menuseparator
5848 ) and then restart LyX.
5849 You should then see your new package—for example
5850 \begin_inset Flex CharStyle:MenuItem
5853 \begin_layout Plain Layout
5860 \begin_inset Flex CharStyle:MenuItem
5863 \begin_layout Plain Layout
5864 Document\SpecialChar \menuseparator
5871 \begin_inset Flex CharStyle:MenuItem
5874 \begin_layout Plain Layout
5884 \begin_layout Section
5888 \begin_layout Standard
5889 This section describes how to write and install your own LyX layout files
5890 and walks through the
5891 \begin_inset Flex CharStyle:Code
5894 \begin_layout Plain Layout
5900 text class format as an example.
5902 \begin_inset Flex CharStyle:Code
5905 \begin_layout Plain Layout
5911 files describe what paragraph and character styles are available for a
5912 given document class and how LyX should display them.
5913 We try to provide a thorough description of the process here; however,
5914 there are so many different types of documents supported by LaTeX classes
5915 that we can't hope to cover every different possibility or problem you
5917 (The LyX users' list is frequented by people with lots of experience with
5918 layout design who are willing to share what they've learned.)
5921 \begin_layout Standard
5922 As you prepare to write a new layout, it is extremely helpful to look at
5923 the example layouts distributed with LyX.
5924 If you use a nice LaTeX document class that might be of interest for others,
5925 too, and have a nice corresponding LyX layout, feel free to contribute
5926 the stuff to us, so we may put it into the distribution.
5928 \begin_inset CommandInset href
5930 name "section on the LyX wiki"
5931 target "http://wiki.lyx.org/Layouts/Layouts"
5935 for this kind of material.
5938 \begin_layout Standard
5939 All the tags described in this chapter are case-insensitive; this means
5941 \begin_inset Flex CharStyle:Code
5944 \begin_layout Plain Layout
5951 \begin_inset Flex CharStyle:Code
5954 \begin_layout Plain Layout
5961 \begin_inset Flex CharStyle:Code
5964 \begin_layout Plain Layout
5970 are really the same command.
5971 The possible values are printed in brackets after the feature's name.
5972 The default value if a feature isn't specified inside a text class-description
5974 \begin_inset Flex CharStyle:Code
5977 \begin_layout Plain Layout
5986 If the argument has a data type like
5987 \begin_inset Quotes eld
5991 \begin_inset Quotes erd
5995 \begin_inset Quotes eld
5999 \begin_inset Quotes erd
6002 , the default is shown like this:
6003 \begin_inset Flex CharStyle:Code
6006 \begin_layout Plain Layout
6017 \begin_layout Subsection
6018 \begin_inset CommandInset label
6020 name "sub:Layout-modules"
6027 \begin_layout Standard
6028 Similar to layout files, and new with LyX 1.6, are layout
6033 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6034 some modules—such as the endnotes module—provide support for just such
6036 In a sense, layout modules are similar to included files—files like
6037 \begin_inset Flex CharStyle:Code
6040 \begin_layout Plain Layout
6046 —in that modules are not specific to a given document layout but may be
6047 used with many different layouts.
6048 The difference is that using a layout module does not require editing the
6050 Rather, modules are selected in the
6051 \begin_inset Flex CharStyle:MenuItem
6054 \begin_layout Plain Layout
6055 Document\SpecialChar \menuseparator
6064 \begin_layout Standard
6065 Building modules is the easiest way to get started with layout editing,
6066 since it can be as simple as adding a single new paragraph or flex inset.
6067 But modules may, in principle, contain anything a layout file can contain.
6070 \begin_layout Standard
6071 A module must begin with a line like the following:
6074 \begin_layout LyX-Code
6077 DeclareLyXModule[endnotes.sty]{Endnotes}
6080 \begin_layout Standard
6082 \change_inserted 0 1235082501
6083 The mandatory argument, in curly brackets, is the name of the module, as
6085 \begin_inset Flex CharStyle:MenuItem
6088 \begin_layout Plain Layout
6090 \change_inserted 0 1235082501
6091 Document\SpecialChar \menuseparator
6100 The argument in square brackets is optional: It declares any LaTeX packages
6101 on which the module depends.
6103 \change_deleted 0 1235082500
6104 The mandatory argument, in curly brackets, is the name of the module, as
6106 \begin_inset Flex CharStyle:MenuItem
6109 \begin_layout Plain Layout
6110 Document\SpecialChar \menuseparator
6118 \change_inserted 0 1235082535
6119 Please note that only packages about which LyX knows should be listed in
6120 the square brackets.
6124 \begin_layout Plain Layout
6126 \change_inserted 0 1235082591
6127 The list of such packages is documented only in the source code.
6134 LyX will not check for arbitrary packages.
6139 \begin_layout Standard
6140 The module declaration should then be followed by lines like the following:
6143 \begin_layout LyX-Code
6147 \begin_layout LyX-Code
6148 #Adds an endnote command, in addition to footnotes.
6152 \begin_layout LyX-Code
6153 #You will need to add
6155 theendnotes in TeX code where you
6158 \begin_layout LyX-Code
6159 #want the endnotes to appear.
6163 \begin_layout LyX-Code
6167 \begin_layout LyX-Code
6168 #Requires: somemodule | othermodule
6171 \begin_layout LyX-Code
6172 #Excludes: badmodule
6175 \begin_layout Standard
6176 The description is used in
6177 \begin_inset Flex CharStyle:MenuItem
6180 \begin_layout Plain Layout
6181 Document\SpecialChar \menuseparator
6187 to provide the user with information about what the module does.
6189 \begin_inset Flex CharStyle:Code
6192 \begin_layout Plain Layout
6198 line is used to identify other modules with which this one must be used;
6200 \begin_inset Flex CharStyle:Code
6203 \begin_layout Plain Layout
6209 line is used to identify modules with which this one may not be used.
6210 Both are optional, and, as shown, multiple modules should be separated
6211 with the pipe symbol: |.
6212 Note that the required modules are treated disjunctively:
6216 of the required modules must be used.
6221 excluded module may be used.
6222 Note that modules are identified here by their
6226 without the .module extension.
6228 \begin_inset Flex CharStyle:Code
6231 \begin_layout Plain Layout
6238 \begin_inset Flex CharStyle:Code
6241 \begin_layout Plain Layout
6250 \begin_layout Standard
6251 After creating a new module, you will need to reconfigure and then restart
6252 LyX for the module to appear in the menu.
6253 However, changes you make to the module will be seen immediately, if you
6255 \begin_inset Flex CharStyle:MenuItem
6258 \begin_layout Plain Layout
6259 Document\SpecialChar \menuseparator
6265 , highlight something, and then hit
6266 \begin_inset Quotes eld
6270 \begin_inset Quotes erd
6276 It is strongly recommended that you save your work before doing so
6281 it is strongly recommended that you not attempt to edit modules while simultaneo
6282 usly working on documents
6285 Though of course the developers strive to keep LyX stable in such situations,
6286 syntax errors and the like in your module file could cause strange behavior.
6289 \begin_layout Subsection
6290 Supporting new document classes
6293 \begin_layout Standard
6294 There are two situations you are likely to encounter when wanting to support
6295 a new LaTeX document class, involving LaTeX2e class (
6296 \begin_inset Flex CharStyle:Code
6299 \begin_layout Plain Layout
6306 \begin_inset Flex CharStyle:Code
6309 \begin_layout Plain Layout
6316 Supporting a style file is usually fairly easy.
6317 Supporting a new document class is a bit harder.
6320 \begin_layout Subsection
6322 \begin_inset Flex CharStyle:MenuItem
6325 \begin_layout Plain Layout
6334 \begin_layout Standard
6335 If your new document class is provided as a style file that is used in conjuncti
6336 on with an existing, supported document class—for the sake of the example,
6337 we'll assume that the style file is called
6338 \begin_inset Flex CharStyle:MenuItem
6341 \begin_layout Plain Layout
6347 and it is meant to be used with
6348 \begin_inset Flex CharStyle:MenuItem
6351 \begin_layout Plain Layout
6357 , which is a standard class—start by copying the existing class's layout
6358 file into your local directory:
6361 \begin_layout LyX-Code
6362 cp report.layout ~/.lyx/layouts/myclass.layout
6365 \begin_layout Standard
6367 \begin_inset Flex CharStyle:Code
6370 \begin_layout Plain Layout
6376 and change the line:
6379 \begin_layout LyX-Code
6382 DeclareLaTeXClass{report}
6385 \begin_layout Standard
6389 \begin_layout LyX-Code
6392 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6395 \begin_layout Standard
6399 \begin_layout LyX-Code
6401 \begin_inset Newline newline
6407 \begin_inset Newline newline
6413 \begin_layout Standard
6414 near the top of the file.
6417 \begin_layout Standard
6418 Start LyX and select
6419 \begin_inset Flex CharStyle:MenuItem
6422 \begin_layout Plain Layout
6423 Tools\SpecialChar \menuseparator
6430 Then restart LyX and try creating a new document.
6432 \begin_inset Flex CharStyle:MenuItem
6435 \begin_layout Plain Layout
6441 " as a document class option in the
6442 \begin_inset Flex CharStyle:MenuItem
6445 \begin_layout Plain Layout
6446 Document\SpecialChar \menuseparator
6453 It is likely that some of the sectioning commands and such in your new
6454 class will work differently from how they worked in the base class—
6455 \begin_inset Flex CharStyle:Code
6458 \begin_layout Plain Layout
6464 in this example—so you can fiddle around with the settings for the different
6465 sections if you wish.
6468 \begin_layout Subsection
6470 \begin_inset Flex CharStyle:MenuItem
6473 \begin_layout Plain Layout
6482 \begin_layout Standard
6483 There are two possibilities here.
6484 One is that the class file is itself based upon an existing document class.
6485 For example, many thesis classes are based upon
6486 \begin_inset Flex CharStyle:MenuItem
6489 \begin_layout Plain Layout
6496 To see whether yours is, look for a line like
6499 \begin_layout LyX-Code
6505 \begin_layout Standard
6507 If so, then you may proceed largely as in the previous section, though
6508 the DeclareLaTeXClass line will be different.
6509 If your new class is thesis, and it is based upon book, then the line should
6514 \begin_layout Plain Layout
6515 And it will be easiest if you save the file to
6516 \begin_inset Flex CharStyle:Code
6519 \begin_layout Plain Layout
6525 : LyX assumes that the document class has the same name as the layout file.
6534 \begin_layout LyX-Code
6537 DeclareLaTeXClass[thesis,book]{thesis}
6540 \begin_layout Standard
6541 If, on the other hand, the new class is not based upon an existing class,
6542 you will probably have to
6543 \begin_inset Quotes eld
6547 \begin_inset Quotes erd
6551 We strongly suggest copying an existing layout file which uses a similar
6552 LaTeX class and then modifying it, if you can do so.
6553 At least use an existing file as a starting point so you can find out what
6554 items you need to worry about.
6555 Again, the specifics are covered below.
6558 \begin_layout Section
6559 Declaring a new text class
6562 \begin_layout Standard
6563 When it's finally time to get your hands dirty and create or edit your own
6564 layout file, the following sections describe what you're up against.
6565 Our advice is to go slowly, save and test often, listen to soothing music,
6566 and enjoy one or two of your favorite adult beverages; more if you are
6567 getting particularly stuck.
6568 It's really not that hard, except that the multitude of options can become
6569 overwhelming if you try to do to much in one sitting.
6570 Go have another adult beverage, just for good measure.
6573 \begin_layout Standard
6577 \begin_layout Standard
6578 Lines in a layout file which begin with a
6579 \begin_inset Flex CharStyle:Code
6582 \begin_layout Plain Layout
6589 There is one exception to this rule: all layouts should begin with lines
6593 \begin_layout LyX-Code
6596 #% Do not delete the line below; configure depends on this
6599 \begin_layout LyX-Code
6604 DeclareLaTeXClass{article}
6607 \begin_layout Standard
6608 The second line is used when you configure LyX.
6609 The layout file is read by the LaTeX script
6610 \begin_inset Flex CharStyle:Code
6613 \begin_layout Plain Layout
6619 , in a special mode where
6620 \begin_inset Flex CharStyle:Code
6623 \begin_layout Plain Layout
6630 The first line is just a LaTeX comment, and the second one contains the
6631 declaration of the text class.
6632 If these lines appear in a file named
6633 \begin_inset Flex CharStyle:Code
6636 \begin_layout Plain Layout
6642 , then they define a text class of name
6643 \begin_inset Flex CharStyle:Code
6646 \begin_layout Plain Layout
6652 (the name of the layout file) which uses the LaTeX document class
6653 \begin_inset Flex CharStyle:Code
6656 \begin_layout Plain Layout
6662 (the default is to use the same name as the layout).
6664 \begin_inset Quotes eld
6668 \begin_inset Quotes erd
6671 that appears above is used as a description of the text class in the
6672 \begin_inset Flex CharStyle:MenuItem
6675 \begin_layout Plain Layout
6676 Document\SpecialChar \menuseparator
6685 \begin_layout Standard
6686 Let's assume that you wrote your own text class that uses the
6687 \begin_inset Flex CharStyle:Code
6690 \begin_layout Plain Layout
6696 document class, but where you changed the appearance of the section headings.
6697 If you put it in a file
6698 \begin_inset Flex CharStyle:Code
6701 \begin_layout Plain Layout
6707 , the header of this file should be:
6710 \begin_layout LyX-Code
6713 #% Do not delete the line below; configure depends on this
6716 \begin_layout LyX-Code
6721 DeclareLaTeXClass[article]{article (with my own headings)}
6724 \begin_layout Standard
6725 This declares a text class
6726 \begin_inset Flex CharStyle:Code
6729 \begin_layout Plain Layout
6735 , associated with the LaTeX document class
6736 \begin_inset Flex CharStyle:Code
6739 \begin_layout Plain Layout
6746 \begin_inset Quotes eld
6749 article (with my own headings)
6750 \begin_inset Quotes erd
6754 If your text class depends on several packages, you can declare it as:
6757 \begin_layout LyX-Code
6760 #% Do not delete the line below; configure depends on this
6763 \begin_layout LyX-Code
6768 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6771 \begin_layout Standard
6772 This indicates that your text class uses the foo.sty package.
6773 Finally, it is also possible to declare classes for DocBook code.
6774 Typical declarations will look like
6777 \begin_layout LyX-Code
6780 #% Do not delete the line below; configure depends on this
6783 \begin_layout LyX-Code
6788 DeclareDocBookClass[article]{SGML (DocBook article)}
6791 \begin_layout Standard
6792 Note that these declarations can also be given an optional parameter declaring
6793 the name of the document class (but not a list).
6796 \begin_layout Standard
6797 So, to be as explicit as possible, the form of the layout declaration is:
6800 \begin_layout LyX-Code
6805 DeclareLaTeXClass[class,package.sty]{layout description}
6808 \begin_layout Standard
6809 The class need only be specified if the name of the LaTeX class file and
6810 the name of the layout file are different; if the name of the class file
6811 is not specified, then LyX will simply assume that it is the same as the
6812 name of the layout file.
6815 \begin_layout Standard
6816 When the text class has been modified to your taste, all you have to do
6817 is to copy it either to
6818 \begin_inset Flex CharStyle:Code
6821 \begin_layout Plain Layout
6828 \begin_inset Flex CharStyle:Code
6831 \begin_layout Plain Layout
6838 \begin_inset Flex CharStyle:MenuItem
6841 \begin_layout Plain Layout
6842 Tools\SpecialChar \menuseparator
6848 , exit LyX and restart it.
6849 Then your new text class should be available along with the others.
6852 \begin_layout Standard
6853 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6854 you made to your layout files.
6855 As a result, editing layout files could be very time consuming.
6856 Beginning with 1.6, however, you can force a reload of the layout currently
6857 in use by using the LyX function
6858 \begin_inset Flex CharStyle:MenuItem
6861 \begin_layout Plain Layout
6868 There is no default binding for this function—though, of course, you can
6869 bind it to a key yourself.
6870 If you want to use this function, then, you should simply enter it in the
6876 : This is very much an `advanced feature'.
6881 recommended that you save your work before using this function.
6886 recommended that you not attempt to edit your layout while simultaneously
6887 working on a document that you care about.
6888 Use a test document.
6889 Syntax errors and the like in your layout file could cause peculiar behavior.
6890 In particular, such errors could cause LyX to regard the current layout
6891 as invalid and to attempt to switch to some other layout.
6892 The LyX team strives to keep LyX stable in such situations, but safe is
6896 \begin_layout Subsection
6900 \begin_layout Standard
6901 The first non-comment line must contain the file format number:
6904 \begin_layout Description
6905 \begin_inset Flex CharStyle:Code
6908 \begin_layout Plain Layout
6915 \begin_inset Flex CharStyle:Code
6918 \begin_layout Plain Layout
6924 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6925 don't have an explicit file format).
6926 The file format that is documented here is format 1
6927 \change_deleted 2 1234611237
6929 \change_inserted 2 1234611237
6933 \change_deleted 1 1234946903
6937 \begin_layout Subsection
6938 General text class parameters
6941 \begin_layout Standard
6942 These are the general parameters which describe the form of the entire document:
6945 \begin_layout Description
6946 \begin_inset Flex CharStyle:Code
6949 \begin_layout Plain Layout
6955 Adds information to the document preamble.
6957 \begin_inset Quotes eld
6961 \begin_inset Flex CharStyle:Code
6964 \begin_layout Plain Layout
6971 \begin_inset Quotes erd
6977 \begin_layout Description
6978 \begin_inset Flex CharStyle:Code
6981 \begin_layout Plain Layout
6987 Describes various global options supported by the document class.
6989 \begin_inset space ~
6993 \begin_inset CommandInset ref
6995 reference "sec:classoptions"
7001 \begin_inset Quotes eld
7005 \begin_inset Flex CharStyle:Code
7008 \begin_layout Plain Layout
7015 \begin_inset Quotes erd
7021 \begin_layout Description
7022 \begin_inset Flex CharStyle:Code
7025 \begin_layout Plain Layout
7032 \begin_inset Flex CharStyle:Code
7035 \begin_layout Plain Layout
7044 \begin_inset Flex CharStyle:Code
7047 \begin_layout Plain Layout
7053 ] Whether the class should default to having one or two columns.
7054 Can be changed in the
7055 \begin_inset Flex CharStyle:MenuItem
7058 \begin_layout Plain Layout
7059 Document\SpecialChar \menuseparator
7068 \begin_layout Description
7069 \begin_inset Flex CharStyle:Code
7072 \begin_layout Plain Layout
7078 This sequence defines a new counter.
7080 \begin_inset space ~
7084 \begin_inset CommandInset ref
7086 reference "sec:counter"
7092 \begin_inset Quotes eld
7096 \begin_inset Flex CharStyle:Code
7099 \begin_layout Plain Layout
7106 \begin_inset Quotes erd
7112 \begin_layout Description
7113 \begin_inset Flex CharStyle:Code
7116 \begin_layout Plain Layout
7122 Sets the default font used to display the document.
7124 \begin_inset space ~
7128 \begin_inset CommandInset ref
7130 reference "sec:fonts"
7134 for how to declare fonts.
7136 \begin_inset Quotes eld
7140 \begin_inset Flex CharStyle:Code
7143 \begin_layout Plain Layout
7150 \begin_inset Quotes erd
7156 \begin_layout Description
7157 \begin_inset Flex CharStyle:Code
7160 \begin_layout Plain Layout
7167 \begin_inset Flex CharStyle:Code
7170 \begin_layout Plain Layout
7176 Specifies a module to be included by default with this document class,
7177 which should be specified by filename without the
7178 \begin_inset Flex CharStyle:Code
7181 \begin_layout Plain Layout
7188 The user can still remove the module, but it will be active at the outset.
7189 (This applies only when new files are created, or when this class is chosen
7190 for an existing document.)
7193 \begin_layout Description
7194 \begin_inset Flex CharStyle:Code
7197 \begin_layout Plain Layout
7204 \begin_inset Flex CharStyle:Code
7207 \begin_layout Plain Layout
7213 ] This is the style that will be assigned to new paragraphs, usually
7214 \begin_inset Flex CharStyle:MenuItem
7217 \begin_layout Plain Layout
7224 This will default to the first defined style if not given, but you are
7225 highly encouraged to use this directive.
7228 \begin_layout Description
7229 \begin_inset Flex CharStyle:Code
7232 \begin_layout Plain Layout
7239 \begin_inset Flex CharStyle:Code
7242 \begin_layout Plain Layout
7248 ] Indicates that the module in question—which should be specified by filename
7250 \begin_inset Flex CharStyle:Code
7253 \begin_layout Plain Layout
7259 extension—cannot be used with this document class.
7260 This might be used in a journal-specific layout file to prevent, say, the
7262 \begin_inset Flex CharStyle:Code
7265 \begin_layout Plain Layout
7271 module that numbers theorems by section.
7276 be used in a module.
7277 Modules have their own way of excluding other modules (see
7278 \begin_inset CommandInset ref
7280 reference "sub:Layout-modules"
7287 \begin_layout Description
7288 \begin_inset Flex CharStyle:Code
7291 \begin_layout Plain Layout
7297 Defines a new float.
7299 \begin_inset space ~
7303 \begin_inset CommandInset ref
7305 reference "sec:floats"
7311 \begin_inset Quotes eld
7315 \begin_inset Flex CharStyle:Code
7318 \begin_layout Plain Layout
7325 \begin_inset Quotes erd
7331 \begin_layout Description
7332 \begin_inset Flex CharStyle:Code
7335 \begin_layout Plain Layout
7341 As its name implies, this command allows you to include another layout
7342 definition file within yours to avoid duplicating commands.
7343 Common examples are the standard layout files, for example,
7344 \begin_inset Flex CharStyle:Code
7347 \begin_layout Plain Layout
7353 , which contains most of the basic layouts.
7356 \begin_layout Description
7357 \begin_inset Flex CharStyle:Code
7360 \begin_layout Plain Layout
7366 This section (re-)defines the layout of an inset.
7367 It can be applied to an existing inset of to a new, user-defined inset,
7369 \begin_inset space \thinspace{}
7373 \begin_inset space \space{}
7376 a new character style.
7378 \begin_inset space ~
7382 \begin_inset CommandInset ref
7384 reference "sec:charstyle"
7388 for more information.
7390 \begin_inset Quotes eld
7394 \begin_inset Flex CharStyle:Code
7397 \begin_layout Plain Layout
7404 \begin_inset Quotes erd
7410 \begin_layout Description
7411 \begin_inset Flex CharStyle:Code
7414 \begin_layout Plain Layout
7420 A string that indicates the width of the left margin on the screen, for
7422 \begin_inset Quotes eld
7426 \begin_inset Quotes erd
7432 \begin_layout Description
7433 \begin_inset Flex CharStyle:Code
7436 \begin_layout Plain Layout
7442 This command deletes an existing float.
7443 This is particularly useful when you want to suppress a float that has
7444 be defined in an input file.
7447 \begin_layout Description
7448 \begin_inset Flex CharStyle:Code
7451 \begin_layout Plain Layout
7457 This command deletes an existing style.
7458 This is particularly useful when you want to suppress a style that has
7459 be defined in an input file.
7462 \begin_layout Description
7463 \begin_inset Flex CharStyle:Code
7466 \begin_layout Plain Layout
7472 A string indicating what sort of output documents using this class will
7474 At present, the options are: `docbook', `latex', and `literate'.
7477 \begin_layout Description
7478 \begin_inset Flex CharStyle:Code
7481 \begin_layout Plain Layout
7492 \begin_inset Flex CharStyle:Code
7495 \begin_layout Plain Layout
7506 \begin_inset Flex CharStyle:Code
7509 \begin_layout Plain Layout
7516 \begin_inset Flex CharStyle:Code
7519 \begin_layout Plain Layout
7525 ] The class default pagestyle.
7526 Can be changed in the
7527 \begin_inset Flex CharStyle:MenuItem
7530 \begin_layout Plain Layout
7531 Document\SpecialChar \menuseparator
7540 \begin_layout Description
7541 \begin_inset Flex CharStyle:Code
7544 \begin_layout Plain Layout
7550 Sets the preamble for the LaTeX document.
7551 Note that this will completely override any prior
7552 \begin_inset Flex CharStyle:Code
7555 \begin_layout Plain Layout
7562 \begin_inset Flex CharStyle:Code
7565 \begin_layout Plain Layout
7573 \begin_inset Quotes eld
7577 \begin_inset Flex CharStyle:Code
7580 \begin_layout Plain Layout
7587 \begin_inset Quotes erd
7593 \begin_layout Description
7594 \begin_inset Flex CharStyle:Code
7597 \begin_layout Plain Layout
7604 \begin_inset Flex CharStyle:Code
7607 \begin_layout Plain Layout
7614 \begin_inset Flex CharStyle:Code
7617 \begin_layout Plain Layout
7626 \begin_inset Flex CharStyle:Code
7629 \begin_layout Plain Layout
7635 ] Whether the class already provides the feature
7636 \begin_inset Flex CharStyle:Code
7639 \begin_layout Plain Layout
7646 A feature is in general the name of a package (
7647 \begin_inset Flex CharStyle:Code
7650 \begin_layout Plain Layout
7657 \begin_inset Flex CharStyle:Code
7660 \begin_layout Plain Layout
7666 , \SpecialChar \ldots{}
7668 \begin_inset Flex CharStyle:Code
7671 \begin_layout Plain Layout
7678 \begin_inset Flex CharStyle:Code
7681 \begin_layout Plain Layout
7687 ,\SpecialChar \ldots{}
7688 ); the complete list of supported features is unfortunately not documented
7689 outside the LyX source code—but see
7690 \begin_inset Flex CharStyle:Code
7693 \begin_layout Plain Layout
7699 if you're interested.
7701 \begin_inset Flex CharStyle:MenuItem
7704 \begin_layout Plain Layout
7705 Help\SpecialChar \menuseparator
7711 also gives an overview of the supported packages.
7714 \begin_layout Description
7715 \begin_inset Flex CharStyle:Code
7718 \begin_layout Plain Layout
7725 \begin_inset Flex CharStyle:Code
7728 \begin_layout Plain Layout
7734 ] Indicates that this layout provides the functionality of the module mentioned,
7735 which should be specified by the filename without the
7736 \begin_inset Flex CharStyle:Code
7739 \begin_layout Plain Layout
7746 This will typically be used if the layout includes the module directly,
7747 rather than using the
7748 \begin_inset Flex CharStyle:Code
7751 \begin_layout Plain Layout
7757 tag to indicate that it ought to be used.
7758 It could be used in a module that provided an alternate implementation
7759 of the same functionality.
7762 \begin_layout Description
7763 \begin_inset Flex CharStyle:Code
7766 \begin_layout Plain Layout
7773 \begin_inset Flex CharStyle:Code
7776 \begin_layout Plain Layout
7782 ] Whether the class requires the feature
7783 \begin_inset Flex CharStyle:Code
7786 \begin_layout Plain Layout
7793 Multiple features must be separated by commas.
7794 Note that you can only request supported features.
7797 \begin_layout Description
7798 \begin_inset Flex CharStyle:Code
7801 \begin_layout Plain Layout
7807 A string that indicates the width of the right margin on the screen, for
7809 \begin_inset Quotes eld
7813 \begin_inset Quotes erd
7819 \begin_layout Description
7820 \begin_inset Flex CharStyle:Code
7823 \begin_layout Plain Layout
7829 Sets which divisions get numbered.
7831 \begin_inset Flex CharStyle:Code
7834 \begin_layout Plain Layout
7843 \begin_layout Description
7844 \begin_inset Flex CharStyle:Code
7847 \begin_layout Plain Layout
7856 \begin_inset Flex CharStyle:Code
7859 \begin_layout Plain Layout
7870 \begin_inset Flex CharStyle:Code
7873 \begin_layout Plain Layout
7879 ] Whether the class-default should be printing on one or both sides of the
7881 Can be changed in the
7882 \begin_inset Flex CharStyle:MenuItem
7885 \begin_layout Plain Layout
7886 Document\SpecialChar \menuseparator
7895 \begin_layout Description
7896 \begin_inset Flex CharStyle:Code
7899 \begin_layout Plain Layout
7905 This sequence defines a new paragraph style.
7906 If the style already exists, it will redefine some of its parameters instead.
7908 \begin_inset space ~
7912 \begin_inset CommandInset ref
7914 reference "sec:style"
7920 \begin_inset Quotes eld
7924 \begin_inset Flex CharStyle:Code
7927 \begin_layout Plain Layout
7934 \begin_inset Quotes erd
7940 \begin_layout Description
7941 \begin_inset Flex CharStyle:Code
7944 \begin_layout Plain Layout
7951 \begin_inset Flex CharStyle:Code
7954 \begin_layout Plain Layout
7960 ] The name of the command or environment to be used with
7961 \begin_inset Flex CharStyle:Code
7964 \begin_layout Plain Layout
7973 \begin_layout Description
7974 \begin_inset Flex CharStyle:Code
7977 \begin_layout Plain Layout
7984 \begin_inset Flex CharStyle:Code
7987 \begin_layout Plain Layout
7996 \begin_inset Flex CharStyle:Code
7999 \begin_layout Plain Layout
8005 ] Indicates what kind of markup is used to define the title of a document.
8007 \begin_inset Flex CharStyle:Code
8010 \begin_layout Plain Layout
8016 means that the macro with name
8017 \begin_inset Flex CharStyle:Code
8020 \begin_layout Plain Layout
8026 will be inserted after the last layout which has
8027 \begin_inset Quotes eld
8031 \begin_inset Flex CharStyle:Code
8034 \begin_layout Plain Layout
8041 \begin_inset Quotes erd
8046 \begin_inset Flex CharStyle:Code
8049 \begin_layout Plain Layout
8055 corresponds to the case where the block of paragraphs which have
8056 \begin_inset Quotes eld
8060 \begin_inset Flex CharStyle:Code
8063 \begin_layout Plain Layout
8070 \begin_inset Quotes erd
8073 should be enclosed into the
8074 \begin_inset Flex CharStyle:Code
8077 \begin_layout Plain Layout
8086 \begin_layout Description
8087 \begin_inset Flex CharStyle:Code
8090 \begin_layout Plain Layout
8096 Sets which divisions are included in the table of contents.
8098 \begin_inset Flex CharStyle:Code
8101 \begin_layout Plain Layout
8110 \begin_layout Subsection
8111 \begin_inset Flex CharStyle:Code
8114 \begin_layout Plain Layout
8123 \begin_layout Standard
8124 \begin_inset CommandInset label
8126 name "sec:classoptions"
8131 \begin_inset Flex CharStyle:Code
8134 \begin_layout Plain Layout
8140 section can contain the following entries:
8143 \begin_layout Description
8144 \begin_inset Flex CharStyle:Code
8147 \begin_layout Plain Layout
8154 \begin_inset Flex CharStyle:Code
8157 \begin_layout Plain Layout
8163 ] The list of available font sizes for the document's main font, separated
8165 \begin_inset Quotes eld
8169 \begin_inset Flex CharStyle:Code
8172 \begin_layout Plain Layout
8179 \begin_inset Quotes erd
8185 \begin_layout Description
8186 \begin_inset Flex CharStyle:Code
8189 \begin_layout Plain Layout
8195 Used to set the DTD line with XML-based output classes.
8197 \begin_inset space \thinspace{}
8201 \begin_inset Quotes eld
8204 -//OASIS//DTD DocBook V4.2//EN
8205 \begin_inset Quotes erd
8211 \begin_layout Description
8212 \begin_inset Flex CharStyle:Code
8215 \begin_layout Plain Layout
8222 \begin_inset Flex CharStyle:Code
8225 \begin_layout Plain Layout
8226 string="empty|plain|headings|fancy"
8231 ] The list of available page styles, separated by
8232 \begin_inset Quotes eld
8236 \begin_inset Flex CharStyle:Code
8239 \begin_layout Plain Layout
8246 \begin_inset Quotes erd
8252 \begin_layout Description
8253 \begin_inset Flex CharStyle:Code
8256 \begin_layout Plain Layout
8263 \begin_inset Flex CharStyle:Code
8266 \begin_layout Plain Layout
8272 ] Some document class options, separated by a comma, that will be added
8273 to the optional part of the
8274 \begin_inset Flex CharStyle:Code
8277 \begin_layout Plain Layout
8288 \begin_layout Standard
8290 \begin_inset Flex CharStyle:Code
8293 \begin_layout Plain Layout
8299 section must end with
8300 \begin_inset Quotes eld
8304 \begin_inset Flex CharStyle:Code
8307 \begin_layout Plain Layout
8314 \begin_inset Quotes erd
8320 \begin_layout Subsection
8324 \begin_layout Standard
8325 \begin_inset CommandInset label
8331 A paragraph style description looks like this:
8335 \begin_layout Plain Layout
8336 Note that this will either define a new layout or modify an existing one.
8344 \begin_layout LyX-Code
8351 \begin_layout LyX-Code
8355 \begin_layout LyX-Code
8359 \begin_layout Standard
8360 where the following commands are allowed:
8363 \begin_layout Description
8364 \begin_inset Flex CharStyle:Code
8367 \begin_layout Plain Layout
8374 \begin_inset Flex CharStyle:Code
8377 \begin_layout Plain Layout
8382 , left, right, center
8387 ] Paragraph alignment.
8390 \begin_layout Description
8391 \begin_inset Flex CharStyle:Code
8394 \begin_layout Plain Layout
8401 \begin_inset Flex CharStyle:Code
8404 \begin_layout Plain Layout
8409 , left, right, center
8414 ] A comma separated list of permitted alignments.
8415 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8417 For example a right-aligned or centered enumeration isn't possible.)
8420 \begin_layout Description
8421 \begin_inset Flex CharStyle:Code
8424 \begin_layout Plain Layout
8431 \begin_inset Flex CharStyle:Code
8434 \begin_layout Plain Layout
8444 \begin_layout Plain Layout
8445 Note that a `float' here is a real number, such as: 1.5.
8450 The vertical space with which the last of a chain of paragraphs with this
8451 layout is separated from the following paragraph.
8452 If the next paragraph has another layout, the separations are not simply
8453 added, but the maximum is taken.
8456 \begin_layout Description
8457 \begin_inset Flex CharStyle:Code
8460 \begin_layout Plain Layout
8467 \begin_inset Flex CharStyle:Code
8470 \begin_layout Plain Layout
8476 The category for this style.
8477 This is used to group related styles in the Layout combobox on the toolbar.
8478 Any string can be used, but you may want to use existing categories with
8483 \begin_layout Description
8484 \begin_inset Flex CharStyle:Code
8487 \begin_layout Plain Layout
8493 Depth of XML command.
8494 Used only with XML-type formats.
8497 \begin_layout Description
8498 \begin_inset Flex CharStyle:Code
8501 \begin_layout Plain Layout
8508 \begin_inset CommandInset label
8510 name "des:CopyStyle"
8515 \begin_inset Flex CharStyle:Code
8518 \begin_layout Plain Layout
8524 Copies all the features of an existing style into the current one.
8528 \begin_layout Description
8529 \begin_inset Flex CharStyle:Code
8532 \begin_layout Plain Layout
8538 The name of a style whose preamble should be output
8543 This allows to ensure some ordering of the preamble snippets when macros
8544 definitions depend on one another.
8548 \begin_layout Plain Layout
8549 Note that, besides that functionality, there is no way to ensure any ordering
8551 The ordering that you see in a given version of LyX may change without
8552 warning in later versions.
8560 \begin_layout Description
8561 \begin_inset Flex CharStyle:Code
8564 \begin_layout Plain Layout
8571 \begin_inset Flex CharStyle:Code
8574 \begin_layout Plain Layout
8579 , Box, Filled_Box, Static
8584 ] The type of label that stands at the end of the paragraph (or sequence
8586 \begin_inset Flex CharStyle:Code
8589 \begin_layout Plain Layout
8596 \begin_inset Flex CharStyle:Code
8599 \begin_layout Plain Layout
8606 \begin_inset Flex CharStyle:Code
8609 \begin_layout Plain Layout
8616 \begin_inset Flex CharStyle:Code
8619 \begin_layout Plain Layout
8627 \begin_inset Flex CharStyle:Code
8630 \begin_layout Plain Layout
8637 \begin_inset Quotes eld
8641 \begin_inset Quotes erd
8645 \begin_inset Flex CharStyle:Code
8648 \begin_layout Plain Layout
8655 \begin_inset Flex CharStyle:Code
8658 \begin_layout Plain Layout
8659 \begin_inset space ~
8668 \begin_inset space ~
8671 black) square suitable for end of proof markers,
8672 \begin_inset Flex CharStyle:Code
8675 \begin_layout Plain Layout
8681 is an explicit text string.
8684 \begin_layout Description
8685 \begin_inset Flex CharStyle:Code
8688 \begin_layout Plain Layout
8695 \begin_inset Flex CharStyle:Code
8698 \begin_layout Plain Layout
8704 ] The string used for a label with a
8705 \begin_inset Flex CharStyle:Code
8708 \begin_layout Plain Layout
8715 \begin_inset Flex CharStyle:Code
8718 \begin_layout Plain Layout
8728 \begin_layout Description
8729 \begin_inset Flex CharStyle:Code
8732 \begin_layout Plain Layout
8739 \begin_inset Flex CharStyle:Code
8742 \begin_layout Plain Layout
8753 \begin_inset Flex CharStyle:Code
8756 \begin_layout Plain Layout
8765 \begin_layout Description
8766 \begin_inset Flex CharStyle:Code
8769 \begin_layout Plain Layout
8776 \begin_inset Flex CharStyle:Code
8779 \begin_layout Plain Layout
8789 ] With this parameter the
8790 \begin_inset Flex CharStyle:MenuItem
8793 \begin_layout Plain Layout
8800 \begin_inset Quotes eld
8803 Vertical space above
8804 \begin_inset Quotes erd
8808 \begin_inset Flex CharStyle:MenuItem
8811 \begin_layout Plain Layout
8812 Edit\SpecialChar \menuseparator
8814 \begin_inset space ~
8822 dialog can be set when initializing a paragraph with this style.
8826 \begin_layout Plain Layout
8829 Note from Jean-Marc:
8831 I'm not sure that this setting has much use, and it should probably be
8832 removed in later versions.
8840 \begin_layout Description
8841 \begin_inset Flex CharStyle:Code
8844 \begin_layout Plain Layout
8850 The font used for both the text body
8856 \begin_inset space ~
8860 \begin_inset CommandInset ref
8862 reference "sec:fonts"
8867 Note that defining this font automatically defines the
8868 \begin_inset Flex CharStyle:Code
8871 \begin_layout Plain Layout
8878 So you should define this one first if you also want to define
8879 \begin_inset Flex CharStyle:Code
8882 \begin_layout Plain Layout
8891 \begin_layout Description
8892 \begin_inset Flex CharStyle:Code
8895 \begin_layout Plain Layout
8902 \begin_inset CommandInset label
8904 name "des:FreeSpacing"
8911 \begin_inset Flex CharStyle:Code
8914 \begin_layout Plain Layout
8925 \begin_inset Flex CharStyle:Code
8928 \begin_layout Plain Layout
8934 ] Usually LyX doesn't allow you to insert more than one space between words,
8935 since a space is considered as the separation between two words, not a
8936 character or symbol of its own.
8937 This is a very fine thing but sometimes annoying, for example, when typing
8938 program code or plain LaTeX code.
8940 \begin_inset Flex CharStyle:Code
8943 \begin_layout Plain Layout
8950 Note that LyX will create protected blanks for the additional blanks when
8951 in another mode than LaTeX-mode.
8954 \begin_layout Description
8955 \begin_inset Flex CharStyle:Code
8958 \begin_layout Plain Layout
8960 \change_inserted 2 1234613251
8962 \change_deleted 2 1234611266
8970 Language dependent information to be included in the LaTeX preamble when
8972 Note that this will completely override any prior
8973 \begin_inset Flex CharStyle:Code
8976 \begin_layout Plain Layout
8978 \change_inserted 2 1234613436
8980 \change_deleted 2 1234611275
8990 \begin_inset Quotes eld
8994 \begin_inset Flex CharStyle:Code
8997 \begin_layout Plain Layout
8999 \change_deleted 2 1234611280
9001 \change_inserted 2 1234613262
9010 \begin_inset Quotes erd
9014 The contents of this tag will occur once in the LaTeX preamble for each
9015 language used by the document.
9016 Each time, the following substitutions are made:
9020 \begin_layout Itemize
9021 \begin_inset Flex CharStyle:Code
9024 \begin_layout Plain Layout
9030 is replaced by the language name (as used by the babel package).
9033 \begin_layout Itemize
9035 \begin_inset Quotes eld
9039 \begin_inset Quotes erd
9043 \begin_inset Flex CharStyle:Code
9046 \begin_layout Plain Layout
9052 replaces its argument by the translation of the argument to the current
9054 \change_inserted 2 1234611470
9058 \begin_layout Standard
9060 \change_inserted 2 1234615134
9061 This preamble snippet will only be used if the document contains more than
9062 one language and the babel package is used.
9068 \begin_layout Description
9070 \change_inserted 2 1234614203
9071 \begin_inset Flex CharStyle:Code
9074 \begin_layout Plain Layout
9076 \change_inserted 2 1234614202
9083 \begin_inset Flex CharStyle:Code
9086 \begin_layout Plain Layout
9088 \change_inserted 2 1234614202
9094 , but this preamble snippet occurs independently from the babel package,
9095 and only for the document language.
9097 \begin_inset Quotes eld
9101 \begin_inset Flex CharStyle:Code
9104 \begin_layout Plain Layout
9106 \change_inserted 2 1234614202
9113 \begin_inset Quotes erd
9120 \begin_layout Standard
9121 If the style defines text that appears in the typeset document, it may use
9123 \begin_inset Flex CharStyle:Code
9126 \begin_layout Plain Layout
9128 \change_inserted 2 1234611302
9130 \change_deleted 2 1234611306
9139 \change_inserted 2 1234611823
9143 \change_inserted 2 1234611832
9145 \begin_inset Flex CharStyle:Code
9148 \begin_layout Plain Layout
9150 \change_inserted 2 1234611838
9158 to support non-english and even multilanguage documents correctly.
9159 The following excerpt (from the
9160 \begin_inset Flex CharStyle:Code
9163 \begin_layout Plain Layout
9169 file) shows how this works:
9172 \begin_layout LyX-Code
9176 \begin_layout LyX-Code
9178 \change_deleted 2 1234612061
9186 \begin_layout LyX-Code
9189 theoremstyle{remark}
9192 \begin_layout LyX-Code
9195 newtheorem{claim}[thm]{
9202 \begin_layout LyX-Code
9206 \begin_layout LyX-Code
9208 \change_inserted 2 1234612037
9212 \begin_layout LyX-Code
9214 \change_inserted 2 1234612045
9219 claimname}{_(Claim)}
9222 \begin_layout LyX-Code
9224 \change_inserted 2 1234611897
9228 \begin_layout LyX-Code
9230 \change_inserted 2 1234612050
9234 \begin_layout LyX-Code
9236 \change_inserted 2 1234611892
9238 \change_deleted 2 1234611847
9244 \begin_layout LyX-Code
9246 \change_deleted 2 1234612079
9262 \begin_layout LyX-Code
9271 claimname}{_(Claim)}}
9272 \change_deleted 2 1234612086
9276 \begin_layout LyX-Code
9278 \change_deleted 2 1234612089
9286 \begin_layout LyX-Code
9288 \change_inserted 2 1234611859
9290 \change_deleted 2 1234611856
9296 \begin_layout Standard
9297 The key to correct translation of the user visible text is the definition
9299 \begin_inset Flex CharStyle:Code
9302 \begin_layout Plain Layout
9311 \change_inserted 2 1234612144
9313 \change_deleted 2 1234612146
9317 This command holds the name of the theorem that will appear in the output.
9319 \begin_inset Flex CharStyle:Code
9322 \begin_layout Plain Layout
9324 \change_inserted 2 1234612157
9326 \change_deleted 2 1234612155
9334 then uses the commands offered by the babel package to redefine
9335 \begin_inset Flex CharStyle:Code
9338 \begin_layout Plain Layout
9346 for each used language
9347 \change_inserted 2 1234622073
9348 in multilanguage documents
9352 \change_deleted 2 1234612171
9354 \begin_inset Flex CharStyle:Code
9357 \begin_layout Plain Layout
9367 test ensures that no LaTeX error occurs in documents that do not use babel.
9368 Since LyX loads babel after the style-specific preamble, the whole command
9369 is deferred to the actual start of the document with
9370 \begin_inset Flex CharStyle:Code
9373 \begin_layout Plain Layout
9387 \begin_layout Description
9388 \begin_inset Flex CharStyle:Code
9391 \begin_layout Plain Layout
9397 [[FIXME]] (Used only with XML-type formats.)
9400 \begin_layout Description
9401 \begin_inset Flex CharStyle:Code
9404 \begin_layout Plain Layout
9411 \begin_inset Flex CharStyle:Code
9414 \begin_layout Plain Layout
9420 If 1, marks the layout as being part of a title block (see also the
9421 \begin_inset Flex CharStyle:Code
9424 \begin_layout Plain Layout
9431 \begin_inset Flex CharStyle:Code
9434 \begin_layout Plain Layout
9443 \begin_layout Description
9444 \begin_inset Flex CharStyle:Code
9447 \begin_layout Plain Layout
9454 \begin_inset Flex CharStyle:Code
9457 \begin_layout Plain Layout
9463 ] This provides extra space between paragraphs that have the same layout.
9464 If you put other layouts into an environment, each is separated with the
9466 \begin_inset Flex CharStyle:Code
9469 \begin_layout Plain Layout
9476 But the whole items of the environment are additionally separated with
9478 \begin_inset Flex CharStyle:Code
9481 \begin_layout Plain Layout
9493 \begin_layout Description
9494 \begin_inset Flex CharStyle:Code
9497 \begin_layout Plain Layout
9503 [[FIXME]] (Used only with XML-type formats.)
9506 \begin_layout Description
9507 \begin_inset Flex CharStyle:Code
9510 \begin_layout Plain Layout
9517 \begin_inset CommandInset label
9519 name "des:KeepEmpty"
9526 \begin_inset Flex CharStyle:Code
9529 \begin_layout Plain Layout
9540 \begin_inset Flex CharStyle:Code
9543 \begin_layout Plain Layout
9549 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9550 lead to empty LaTeX output.
9551 There are some cases where this could be desirable however: in a letter
9552 template, the required fields can be provided as empty fields, so that
9553 people do not forget them; in some special classes, a layout can be used
9554 as some kind of break, which does not contain actual text.
9557 \begin_layout Description
9558 \begin_inset Flex CharStyle:Code
9561 \begin_layout Plain Layout
9567 [float=0] The vertical space between the label and the text body.
9568 Only used for labels that are above the text body (
9569 \begin_inset Flex CharStyle:Code
9572 \begin_layout Plain Layout
9579 \begin_inset Flex CharStyle:Code
9582 \begin_layout Plain Layout
9583 Centered_Top_Environment
9591 \begin_layout Description
9592 \begin_inset Flex CharStyle:Code
9595 \begin_layout Plain Layout
9602 \begin_inset Flex CharStyle:Code
9605 \begin_layout Plain Layout
9612 \begin_inset Newline newline
9615 The name of the counter for automatic numbering (see Section
9616 \begin_inset CommandInset ref
9618 reference "sec:counter"
9623 This must be given if
9624 \begin_inset Flex CharStyle:Code
9627 \begin_layout Plain Layout
9634 \begin_inset Flex CharStyle:Code
9637 \begin_layout Plain Layout
9646 \begin_layout Description
9647 \begin_inset Flex CharStyle:Code
9650 \begin_layout Plain Layout
9656 The font used for the label.
9658 \begin_inset space ~
9662 \begin_inset CommandInset ref
9664 reference "sec:fonts"
9671 \begin_layout Description
9672 \begin_inset Flex CharStyle:Code
9675 \begin_layout Plain Layout
9681 Text that indicates how far a label should be indented.
9684 \begin_layout Description
9685 \begin_inset Flex CharStyle:Code
9688 \begin_layout Plain Layout
9695 \begin_inset Flex CharStyle:Code
9698 \begin_layout Plain Layout
9704 ] The horizontal space between the label and the text body.
9705 Only used for labels that are not above the text body.
9708 \begin_layout Description
9709 \begin_inset Flex CharStyle:Code
9712 \begin_layout Plain Layout
9719 \begin_inset Flex CharStyle:Code
9722 \begin_layout Plain Layout
9728 ] The string used for a label with a
9729 \begin_inset Flex CharStyle:Code
9732 \begin_layout Plain Layout
9740 \begin_inset Flex CharStyle:Code
9743 \begin_layout Plain Layout
9749 is set, this string can be contain the special formatting commands described
9751 \begin_inset CommandInset ref
9753 reference "sec:counter"
9761 \begin_layout Plain Layout
9762 For the sake of backwards compatibility, the string
9763 \begin_inset Flex CharStyle:Code
9766 \begin_layout Plain Layout
9776 will be replaced by the expanded
9777 \begin_inset Flex CharStyle:Code
9780 \begin_layout Plain Layout
9787 \begin_inset Flex CharStyle:Code
9790 \begin_layout Plain Layout
9799 This feature is now obsolete and should be replaced by the mechanisms of
9801 \begin_inset CommandInset ref
9803 reference "sec:counter"
9815 \begin_layout Description
9816 \begin_inset Flex CharStyle:Code
9819 \begin_layout Plain Layout
9826 \begin_inset Flex CharStyle:Code
9829 \begin_layout Plain Layout
9835 ] This is used inside the appendix instead of
9836 \begin_inset Flex CharStyle:Code
9839 \begin_layout Plain Layout
9847 \begin_inset Flex CharStyle:Code
9850 \begin_layout Plain Layout
9857 \begin_inset Flex CharStyle:Code
9860 \begin_layout Plain Layout
9869 \begin_layout Description
9870 \begin_inset Flex CharStyle:Code
9873 \begin_layout Plain Layout
9879 [FIXME] (Used only with XML-type formats.)
9882 \begin_layout Description
9883 \begin_inset Flex CharStyle:Code
9886 \begin_layout Plain Layout
9893 \begin_inset Flex CharStyle:Code
9896 \begin_layout Plain Layout
9901 , Manual, Static, Top_Environment,
9902 \begin_inset Newline newline
9905 Centered_Top_Environment, Sensitive, Counter
9911 \begin_inset Newline newline
9915 \begin_inset Flex CharStyle:Code
9918 \begin_layout Plain Layout
9924 means the label is the very first word (up to the first real blank).
9928 \begin_layout Plain Layout
9929 Use protected spaces if you want more than one word as the label.
9935 \begin_inset Flex CharStyle:Code
9938 \begin_layout Plain Layout
9944 means it is defined in the layout (see
9945 \begin_inset Flex CharStyle:Code
9948 \begin_layout Plain Layout
9956 \begin_inset Flex CharStyle:Code
9959 \begin_layout Plain Layout
9966 \begin_inset Flex CharStyle:Code
9969 \begin_layout Plain Layout
9970 Centered_Top_Environment
9975 are special cases of
9976 \begin_inset Flex CharStyle:Code
9979 \begin_layout Plain Layout
9986 The label will be printed above the paragraph, but only at the top of an
9987 environment or the top of a chain of paragraphs with this layout.
9988 Usage is for example the
9989 \begin_inset Flex CharStyle:MenuItem
9992 \begin_layout Plain Layout
9999 \begin_inset Flex CharStyle:MenuItem
10002 \begin_layout Plain Layout
10009 This is also the case for
10010 \begin_inset Flex CharStyle:Code
10013 \begin_layout Plain Layout
10019 labels with latex type
10020 \begin_inset Flex CharStyle:Code
10023 \begin_layout Plain Layout
10029 , in order to make layouts for theorems work correctly.
10031 \begin_inset Flex CharStyle:Code
10034 \begin_layout Plain Layout
10040 is a special case for the caption-labels
10041 \begin_inset Quotes eld
10045 \begin_inset Quotes erd
10049 \begin_inset Quotes eld
10053 \begin_inset Quotes erd
10058 \begin_inset Flex CharStyle:Code
10061 \begin_layout Plain Layout
10067 means the (hardcoded) label string depends on the kind of float.
10069 \begin_inset Flex CharStyle:Code
10072 \begin_layout Plain Layout
10078 label type defines automatically numbered labels.
10080 \begin_inset CommandInset ref
10082 reference "sec:counter"
10089 \begin_layout Description
10090 \begin_inset Flex CharStyle:Code
10093 \begin_layout Plain Layout
10099 The name of the corresponding LaTeX stuff.
10100 Either the environment or command name.
10103 \begin_layout Description
10104 \begin_inset Flex CharStyle:Code
10107 \begin_layout Plain Layout
10113 An optional parameter for the corresponding
10114 \begin_inset Flex CharStyle:Code
10117 \begin_layout Plain Layout
10124 This parameter cannot be changed from within LyX.
10127 \begin_layout Description
10128 \begin_inset Flex CharStyle:Code
10131 \begin_layout Plain Layout
10138 \begin_inset CommandInset label
10140 name "des:LatexType"
10145 \begin_inset Flex CharStyle:Code
10148 \begin_layout Plain Layout
10153 , Command, Environment, Item_Environment,
10159 \begin_inset Flex CharStyle:Code
10162 \begin_layout Plain Layout
10168 ] How the layout should be translated into LaTeX.
10170 \begin_inset Flex CharStyle:Code
10173 \begin_layout Plain Layout
10179 means nothing special.
10181 \begin_inset Flex CharStyle:Code
10184 \begin_layout Plain Layout
10191 \begin_inset Flex CharStyle:Code
10194 \begin_layout Plain Layout
10201 {\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 }\SpecialChar \ldots{}
10242 \begin_inset Flex CharStyle:Code
10245 \begin_layout Plain Layout
10252 \begin_inset Flex CharStyle:Code
10255 \begin_layout Plain Layout
10262 \begin_inset Flex CharStyle:Code
10265 \begin_layout Plain Layout
10273 is generated for each paragraph of this environment.
10275 \begin_inset Flex CharStyle:Code
10278 \begin_layout Plain Layout
10285 \begin_inset Flex CharStyle:Code
10288 \begin_layout Plain Layout
10295 \begin_inset Flex CharStyle:Code
10298 \begin_layout Plain Layout
10304 is passed as an argument to the environment.
10306 \begin_inset Flex CharStyle:Code
10309 \begin_layout Plain Layout
10315 can be defined in the
10316 \begin_inset Flex CharStyle:MenuItem
10319 \begin_layout Plain Layout
10324 ayout\SpecialChar \menuseparator
10336 \begin_inset Flex CharStyle:Code
10339 \begin_layout Plain Layout
10347 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10348 Visit the SGML class files for specific examples.
10351 \begin_layout Standard
10352 Putting the last few things together, the LaTeX output will be either:
10355 \begin_layout LyX-Code
10358 latexname[latexparam]{\SpecialChar \ldots{}
10362 \begin_layout Standard
10366 \begin_layout LyX-Code
10369 begin{latexname}[latexparam] \SpecialChar \ldots{}
10375 \begin_layout Standard
10376 depending upon the LaTeX type.
10379 \begin_layout Description
10380 \begin_inset Flex CharStyle:Code
10383 \begin_layout Plain Layout
10390 \begin_inset Flex CharStyle:Code
10393 \begin_layout Plain Layout
10399 ] If you put layouts into environments, the leftmargins are not simply added,
10400 but added with a factor
10401 \begin_inset Formula $\frac{4}{depth+4}$
10405 Note that this parameter is also used when the margin is defined as
10406 \begin_inset Flex CharStyle:Code
10409 \begin_layout Plain Layout
10416 \begin_inset Flex CharStyle:Code
10419 \begin_layout Plain Layout
10426 Then it is added to the manual or dynamic margin.
10428 \begin_inset Newline newline
10431 The argument is passed as a string.
10433 \begin_inset Quotes eld
10437 \begin_inset Flex CharStyle:Code
10440 \begin_layout Plain Layout
10447 \begin_inset Quotes erd
10450 means that the paragraph is indented with the width of
10451 \begin_inset Quotes eld
10455 \begin_inset Flex CharStyle:Code
10458 \begin_layout Plain Layout
10465 \begin_inset Quotes erd
10468 in the normal font.
10469 You can get a negative width by prefixing the string with
10470 \begin_inset Quotes eld
10474 \begin_inset Flex CharStyle:Code
10477 \begin_layout Plain Layout
10484 \begin_inset Quotes erd
10488 This way was chosen so that the look is the same with each used screen
10493 \begin_layout Description
10494 \begin_inset Flex CharStyle:Code
10497 \begin_layout Plain Layout
10504 \begin_inset Flex CharStyle:Code
10507 \begin_layout Plain Layout
10512 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10518 \begin_inset Newline newline
10521 The kind of margin that the layout has on the left side.
10523 \begin_inset Flex CharStyle:Code
10526 \begin_layout Plain Layout
10532 just means a fixed margin.
10534 \begin_inset Flex CharStyle:Code
10537 \begin_layout Plain Layout
10543 means that the left margin depends on the string entered in the
10544 \begin_inset Flex CharStyle:MenuItem
10547 \begin_layout Plain Layout
10548 Edit\SpecialChar \menuseparator
10550 \begin_inset space ~
10559 This is used to typeset nice lists without tabulators.
10561 \begin_inset Flex CharStyle:Code
10564 \begin_layout Plain Layout
10570 means that the margin depends on the size of the label.
10571 This is used for automatic enumerated headlines.
10572 It is obvious that the headline
10573 \begin_inset Quotes eld
10576 5.4.3.2.1 Very long headline
10577 \begin_inset Quotes erd
10580 must have a wider left margin (as wide as
10581 \begin_inset Quotes eld
10585 \begin_inset Quotes erd
10588 plus the space) than
10589 \begin_inset Quotes eld
10592 3.2 Very long headline
10593 \begin_inset Quotes erd
10597 \begin_inset Quotes eld
10601 \begin_inset Quotes erd
10604 are not able to do this.
10606 \begin_inset Flex CharStyle:Code
10609 \begin_layout Plain Layout
10615 is similar, but only the very first row of the paragraph is dynamic, while
10616 the others are static; this is used, for example, for descriptions.
10618 \begin_inset Flex CharStyle:Code
10621 \begin_layout Plain Layout
10627 means the margin is chosen in a way that the longest row of this paragraph
10628 fits to the right margin.
10629 This is used to typeset an address on the right edge of the page.
10632 \begin_layout Description
10633 \begin_inset Flex CharStyle:Code
10636 \begin_layout Plain Layout
10643 \begin_inset Flex CharStyle:Code
10646 \begin_layout Plain Layout
10655 \begin_inset Flex CharStyle:Code
10658 \begin_layout Plain Layout
10664 ] Whether fragile commands in this layout should be
10665 \begin_inset Flex CharStyle:Code
10668 \begin_layout Plain Layout
10681 whether this command should itself be protected.)
10684 \begin_layout Description
10685 \begin_inset Flex CharStyle:Code
10688 \begin_layout Plain Layout
10695 \begin_inset Flex CharStyle:Code
10698 \begin_layout Plain Layout
10705 \begin_inset Flex CharStyle:Code
10708 \begin_layout Plain Layout
10716 ] Whether newlines are translated into LaTeX newlines (
10717 \begin_inset Flex CharStyle:Code
10720 \begin_layout Plain Layout
10731 The translation can be switched off to allow more comfortable LaTeX editing
10735 \begin_layout Description
10736 \begin_inset Flex CharStyle:Code
10739 \begin_layout Plain Layout
10746 \begin_inset Flex CharStyle:Code
10749 \begin_layout Plain Layout
10756 \begin_inset Flex CharStyle:Code
10759 \begin_layout Plain Layout
10767 ] Whether the following Paragraph is allowed to indent its very first row.
10769 \begin_inset Flex CharStyle:Code
10772 \begin_layout Plain Layout
10778 means that it is not allowed to do so;
10779 \begin_inset Flex CharStyle:Code
10782 \begin_layout Plain Layout
10788 means it could do so if it wants to.
10791 \begin_layout Description
10792 \begin_inset Flex CharStyle:Code
10795 \begin_layout Plain Layout
10801 Name of a layout that has replaced this layout.
10802 This is used to rename a layout, while keeping backward compatibility.
10805 \begin_layout Description
10806 \begin_inset Flex CharStyle:Code
10809 \begin_layout Plain Layout
10816 \begin_inset Flex CharStyle:Code
10819 \begin_layout Plain Layout
10825 ] The number of optional arguments that can be used with this layout.
10826 This is useful for things like section headings, and only makes sense with
10830 \begin_layout Description
10831 \begin_inset Flex CharStyle:Code
10834 \begin_layout Plain Layout
10841 \begin_inset Flex CharStyle:Code
10844 \begin_layout Plain Layout
10850 ] The indent of the very first line of a paragraph.
10852 \begin_inset Flex CharStyle:Code
10855 \begin_layout Plain Layout
10861 will be fixed for a certain layout.
10862 The exception is Standard layout, since the indentation of a Standard layout
10863 paragraph can be prohibited with
10864 \begin_inset Flex CharStyle:Code
10867 \begin_layout Plain Layout
10874 Also, Standard layout paragraphs inside environments use the
10875 \begin_inset Flex CharStyle:Code
10878 \begin_layout Plain Layout
10884 of the environment, not their native one.
10885 For example, Standard paragraphs inside an enumeration are not indented.
10888 \begin_layout Description
10889 \begin_inset Flex CharStyle:Code
10892 \begin_layout Plain Layout
10899 \begin_inset Flex CharStyle:Code
10902 \begin_layout Plain Layout
10908 ] The vertical space between two paragraphs of this layout.
10911 \begin_layout Description
10912 \begin_inset Flex CharStyle:Code
10915 \begin_layout Plain Layout
10922 \begin_inset Flex CharStyle:Code
10925 \begin_layout Plain Layout
10931 ] LyX allows the user to choose either
10932 \begin_inset Quotes eld
10936 \begin_inset Quotes erd
10940 \begin_inset Quotes eld
10944 \begin_inset Quotes erd
10947 to typeset a document.
10949 \begin_inset Quotes eld
10953 \begin_inset Quotes erd
10956 is chosen, this value is completely ignored.
10958 \begin_inset Quotes eld
10962 \begin_inset Quotes erd
10965 is chosen, the parindent of a LaTeXtype
10966 \begin_inset Quotes eld
10970 \begin_inset Quotes erd
10973 layout is ignored and all paragraphs are separated by this parskip argument.
10974 The vertical space is calculated with
10975 \begin_inset Flex CharStyle:Code
10978 \begin_layout Plain Layout
10980 \begin_inset space ~
10989 \begin_inset Flex CharStyle:Code
10992 \begin_layout Plain Layout
10998 is the height of a row with the normal font.
10999 This way, the look stays the same with different screen fonts.
11002 \begin_layout Description
11003 \begin_inset Flex CharStyle:Code
11006 \begin_layout Plain Layout
11013 \begin_inset CommandInset label
11015 name "des:PathThru"
11022 \begin_inset Flex CharStyle:Code
11025 \begin_layout Plain Layout
11036 \begin_inset Flex CharStyle:Code
11039 \begin_layout Plain Layout
11045 ] Whether the contents of this paragraph should be output in raw form, meaning
11046 without special translations that LaTeX would require.
11049 \begin_layout Description
11050 \begin_inset Flex CharStyle:Code
11053 \begin_layout Plain Layout
11060 \begin_inset CommandInset label
11062 name "des:Preamble"
11066 Information to be included in the LaTeX preamble when this style is used.
11067 Used to define macros, load packages, etc., required by this particular
11070 \begin_inset Quotes eld
11074 \begin_inset Flex CharStyle:Code
11077 \begin_layout Plain Layout
11084 \begin_inset Quotes erd
11090 \begin_layout Description
11091 \begin_inset Flex CharStyle:Code
11094 \begin_layout Plain Layout
11101 \begin_inset Flex CharStyle:Code
11104 \begin_layout Plain Layout
11111 \begin_inset CommandInset label
11113 name "des:Requires"
11117 Whether the layout requires the feature
11118 \begin_inset Flex CharStyle:Code
11121 \begin_layout Plain Layout
11128 See the description of
11129 \begin_inset Flex CharStyle:Code
11132 \begin_layout Plain Layout
11139 \begin_inset CommandInset ref
11140 LatexCommand pageref
11141 reference "des:FreeSpacing"
11145 ) for information on `features'.
11149 \begin_layout Description
11150 \begin_inset Flex CharStyle:Code
11153 \begin_layout Plain Layout
11160 \begin_inset Flex CharStyle:Code
11163 \begin_layout Plain Layout
11170 \begin_inset Flex CharStyle:Code
11173 \begin_layout Plain Layout
11182 \begin_layout Description
11183 \begin_inset Flex CharStyle:Code
11186 \begin_layout Plain Layout
11193 \begin_inset Flex CharStyle:Code
11196 \begin_layout Plain Layout
11201 , onehalf, double, other
11210 ] This defines what the default spacing should be in the layout.
11212 \begin_inset Flex CharStyle:Code
11215 \begin_layout Plain Layout
11222 \begin_inset Flex CharStyle:Code
11225 \begin_layout Plain Layout
11232 \begin_inset Flex CharStyle:Code
11235 \begin_layout Plain Layout
11241 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11242 If you specify the argument
11243 \begin_inset Flex CharStyle:Code
11246 \begin_layout Plain Layout
11252 , then you should also provide a numerical argument which will be the actual
11254 Note that, contrary to other parameters,
11255 \begin_inset Flex CharStyle:Code
11258 \begin_layout Plain Layout
11264 implies the generation of specific LaTeX code, using the package
11267 \begin_inset Flex CharStyle:Code
11270 \begin_layout Plain Layout
11279 \begin_layout Description
11280 \begin_inset Flex CharStyle:Code
11283 \begin_layout Plain Layout
11289 The font used for the text body .
11291 \begin_inset CommandInset ref
11293 reference "sec:fonts"
11300 \begin_layout Description
11301 \begin_inset Flex CharStyle:Code
11304 \begin_layout Plain Layout
11312 The level of the style in the table of contents.
11313 This is used for automatic numbering of section headings.
11316 \begin_layout Description
11317 \begin_inset Flex CharStyle:Code
11320 \begin_layout Plain Layout
11327 \begin_inset Flex CharStyle:Code
11330 \begin_layout Plain Layout
11336 ] The vertical space with which the very first of a chain of paragraphs
11337 with this layout is separated from the previous paragraph.
11338 If the previous paragraph has another layout, the separations are not simply
11339 added, but the maximum is taken.
11342 \begin_layout Subsection
11346 \begin_layout Standard
11347 \begin_inset CommandInset label
11353 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11354 define the floats (
11355 \begin_inset Flex CharStyle:MenuItem
11358 \begin_layout Plain Layout
11365 \begin_inset Flex CharStyle:MenuItem
11368 \begin_layout Plain Layout
11374 , \SpecialChar \ldots{}
11375 ) in the text class itself.
11376 Standard floats are included in the file
11377 \begin_inset Flex CharStyle:Code
11380 \begin_layout Plain Layout
11386 , so you may have to do no more than add
11389 \begin_layout LyX-Code
11390 Input stdfloats.inc
11393 \begin_layout Standard
11394 to your layout file.
11395 If you want to implement a text class that proposes some other float types
11396 (like the AGU class bundled with LyX), the information below will hopefully
11400 \begin_layout Description
11401 \begin_inset Flex CharStyle:Code
11404 \begin_layout Plain Layout
11411 \begin_inset Flex CharStyle:Code
11414 \begin_layout Plain Layout
11421 \begin_inset Quotes erd
11425 \begin_inset Quotes erd
11428 ] The file name extension of an auxiliary file for the list of figures (or
11430 LaTeX writes the captions to this file.
11433 \begin_layout Description
11434 \begin_inset Flex CharStyle:Code
11437 \begin_layout Plain Layout
11444 \begin_inset Flex CharStyle:Code
11447 \begin_layout Plain Layout
11454 \begin_inset Quotes erd
11458 \begin_inset Quotes erd
11461 ] The string that will be used in the menus and also for the caption.
11464 \begin_layout Description
11465 \begin_inset Flex CharStyle:Code
11468 \begin_layout Plain Layout
11475 \begin_inset Flex CharStyle:Code
11478 \begin_layout Plain Layout
11487 \begin_inset Flex CharStyle:Code
11490 \begin_layout Plain Layout
11497 \begin_inset Flex CharStyle:Code
11500 \begin_layout Plain Layout
11506 if the float is already defined by the LaTeX document class.
11508 \begin_inset Flex CharStyle:Code
11511 \begin_layout Plain Layout
11517 , the float will be defined using the LaTeX package
11518 \begin_inset Flex CharStyle:Code
11521 \begin_layout Plain Layout
11530 \begin_layout Description
11531 \begin_inset Flex CharStyle:Code
11534 \begin_layout Plain Layout
11541 \begin_inset Flex CharStyle:Code
11544 \begin_layout Plain Layout
11551 \begin_inset Quotes erd
11555 \begin_inset Quotes erd
11558 ] The heading used for the list of floats.
11561 \begin_layout Description
11562 \begin_inset Flex CharStyle:Code
11565 \begin_layout Plain Layout
11572 \begin_inset Flex CharStyle:Code
11575 \begin_layout Plain Layout
11582 \begin_inset Quotes erd
11586 \begin_inset Quotes erd
11589 ] This (optional) argument determines whether floats of this class will
11590 be numbered within some sectional unit of the document.
11591 For example, if within is equal to
11592 \begin_inset Flex CharStyle:Code
11595 \begin_layout Plain Layout
11601 , the floats will be numbered within chapters.
11605 \begin_layout Description
11606 \begin_inset Flex CharStyle:Code
11609 \begin_layout Plain Layout
11616 \begin_inset Flex CharStyle:Code
11619 \begin_layout Plain Layout
11626 \begin_inset Quotes erd
11630 \begin_inset Quotes erd
11633 ] The default placement for the given class of floats.
11634 The string should be as in standard LaTeX:
11635 \begin_inset Flex CharStyle:Code
11638 \begin_layout Plain Layout
11645 \begin_inset Flex CharStyle:Code
11648 \begin_layout Plain Layout
11655 \begin_inset Flex CharStyle:Code
11658 \begin_layout Plain Layout
11665 \begin_inset Flex CharStyle:Code
11668 \begin_layout Plain Layout
11674 for top, bottom, page, and here, respectively.
11678 \begin_layout Plain Layout
11679 Note that the order of these letters in the string is irrelevant, like in
11685 On top of that there is a new type,
11686 \begin_inset Flex CharStyle:Code
11689 \begin_layout Plain Layout
11695 , which does not really correspond to a float, since it means: put it
11696 \begin_inset Quotes eld
11700 \begin_inset Quotes erd
11704 Note however that the
11705 \begin_inset Flex CharStyle:Code
11708 \begin_layout Plain Layout
11714 specifier is special and, because of implementation details, cannot be
11715 used in non-built in float types.
11716 If you do not understand what this means, just use
11717 \begin_inset Quotes eld
11721 \begin_inset Flex CharStyle:Code
11724 \begin_layout Plain Layout
11731 \begin_inset Quotes erd
11737 \begin_layout Description
11738 \begin_inset Flex CharStyle:Code
11741 \begin_layout Plain Layout
11748 \begin_inset Flex CharStyle:Code
11751 \begin_layout Plain Layout
11758 \begin_inset Quotes erd
11762 \begin_inset Quotes erd
11765 ] The style used when defining the float using
11766 \begin_inset Flex CharStyle:Code
11769 \begin_layout Plain Layout
11780 \begin_layout Description
11781 \begin_inset Flex CharStyle:Code
11784 \begin_layout Plain Layout
11791 \begin_inset Flex CharStyle:Code
11794 \begin_layout Plain Layout
11801 \begin_inset Quotes erd
11805 \begin_inset Quotes erd
11809 \begin_inset Quotes eld
11813 \begin_inset Quotes erd
11816 of the new class of floats, like program or algorithm.
11817 After the appropriate
11818 \begin_inset Flex CharStyle:Code
11821 \begin_layout Plain Layout
11830 \begin_inset Flex CharStyle:Code
11833 \begin_layout Plain Layout
11842 \begin_inset Flex CharStyle:Code
11845 \begin_layout Plain Layout
11856 \begin_layout Standard
11857 Note that defining a float with type
11858 \begin_inset Flex CharStyle:Code
11861 \begin_layout Plain Layout
11869 automatically defines the corresponding counter with name
11870 \begin_inset Flex CharStyle:Code
11873 \begin_layout Plain Layout
11884 \begin_layout Subsection
11885 Flex insets and InsetLayout
11888 \begin_layout Standard
11889 \begin_inset CommandInset label
11891 name "sec:charstyle"
11895 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11896 these are called Flex insets.
11900 \begin_layout Standard
11901 Flex insets come in three different kinds:
11904 \begin_layout Itemize
11906 \begin_inset Flex CharStyle:Code
11909 \begin_layout Plain Layout
11915 ): These define semantic markup corresponding to such LaTeX commands as
11917 \begin_inset Flex CharStyle:Code
11920 \begin_layout Plain Layout
11929 \begin_inset Flex CharStyle:Code
11932 \begin_layout Plain Layout
11943 \begin_layout Itemize
11945 \begin_inset Flex CharStyle:Code
11948 \begin_layout Plain Layout
11954 ): These can be used to define custom collapsible insets, similar to TeX
11955 code, footnote, and the like.
11956 An obvious example is an endnote inset, which is defined in the
11957 \begin_inset Flex CharStyle:Code
11960 \begin_layout Plain Layout
11969 \begin_layout Itemize
11971 \begin_inset Flex CharStyle:Code
11974 \begin_layout Plain Layout
11980 ): For use with DocBook classes.
11983 \begin_layout Standard
11984 Flex insets are defined using the
11985 \begin_inset Flex CharStyle:Code
11988 \begin_layout Plain Layout
11994 tag, which shall be explained in a moment.
11997 \begin_layout Standard
11999 \begin_inset Flex CharStyle:Code
12002 \begin_layout Plain Layout
12008 tag also serves another function: It can be used to customize the general
12009 layout of many different types of insets.
12011 \begin_inset Flex CharStyle:Code
12014 \begin_layout Plain Layout
12020 can be used to customize the layout parameters for footnotes, marginal
12021 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
12022 boxes, tables, algorithms, URLs, and optional arguments, as well as to
12023 define Flex insets.
12026 \begin_layout Standard
12028 \begin_inset Flex CharStyle:Code
12031 \begin_layout Plain Layout
12037 definition must begin with a line of the form:
12040 \begin_layout LyX-Code
12044 \begin_layout Standard
12046 \begin_inset Flex CharStyle:Code
12049 \begin_layout Plain Layout
12055 indicates the inset whose layout is being defined, and here there are two
12059 \begin_layout Enumerate
12060 The layout for a pre-existing inset is being modified.
12061 In this case, can be
12062 \begin_inset Flex CharStyle:Code
12065 \begin_layout Plain Layout
12071 any one of the following:
12072 \begin_inset Flex CharStyle:Code
12075 \begin_layout Plain Layout
12082 \begin_inset Flex CharStyle:Code
12085 \begin_layout Plain Layout
12092 \begin_inset Flex CharStyle:Code
12095 \begin_layout Plain Layout
12102 \begin_inset Flex CharStyle:Code
12105 \begin_layout Plain Layout
12112 \begin_inset Flex CharStyle:Code
12115 \begin_layout Plain Layout
12122 \begin_inset Flex CharStyle:Code
12125 \begin_layout Plain Layout
12132 \begin_inset Flex CharStyle:Code
12135 \begin_layout Plain Layout
12142 \begin_inset Flex CharStyle:Code
12145 \begin_layout Plain Layout
12152 \begin_inset Flex CharStyle:Code
12155 \begin_layout Plain Layout
12162 \begin_inset Flex CharStyle:Code
12165 \begin_layout Plain Layout
12172 \begin_inset Flex CharStyle:Code
12175 \begin_layout Plain Layout
12182 \begin_inset Flex CharStyle:Code
12185 \begin_layout Plain Layout
12192 \begin_inset Flex CharStyle:Code
12195 \begin_layout Plain Layout
12202 \begin_inset Flex CharStyle:Code
12205 \begin_layout Plain Layout
12212 \begin_inset Flex CharStyle:Code
12215 \begin_layout Plain Layout
12222 \begin_inset Flex CharStyle:Code
12225 \begin_layout Plain Layout
12232 \begin_inset Flex CharStyle:Code
12235 \begin_layout Plain Layout
12242 \begin_inset Flex CharStyle:Code
12245 \begin_layout Plain Layout
12252 \begin_inset Flex CharStyle:Code
12255 \begin_layout Plain Layout
12262 \begin_inset Flex CharStyle:Code
12265 \begin_layout Plain Layout
12275 \begin_layout Enumerate
12276 The layout for a Flex inset is being defined.
12278 \begin_inset Flex CharStyle:Code
12281 \begin_layout Plain Layout
12287 can be any valid identifier not used by a pre-existing inset.
12288 Note that the definition of a flex inset must
12293 \begin_inset Flex CharStyle:Code
12296 \begin_layout Plain Layout
12305 \begin_layout Standard
12307 \begin_inset Flex CharStyle:Code
12310 \begin_layout Plain Layout
12316 definition can contain the following entries:
12319 \begin_layout Description
12320 \begin_inset Flex CharStyle:Code
12323 \begin_layout Plain Layout
12329 The color for the inset's background.
12330 The valid colors are defined in
12331 \begin_inset Flex CharStyle:Code
12334 \begin_layout Plain Layout
12343 \begin_layout Description
12344 \begin_inset Flex CharStyle:Code
12347 \begin_layout Plain Layout
12353 As with paragraph styles (see page
12354 \begin_inset CommandInset ref
12356 reference "des:CopyStyle"
12363 \begin_layout Description
12364 \begin_inset Flex CharStyle:Code
12367 \begin_layout Plain Layout
12374 \begin_inset Flex CharStyle:Code
12377 \begin_layout Plain Layout
12386 \begin_inset Flex CharStyle:Code
12389 \begin_layout Plain Layout
12395 ] Indicates whether the user may employ the Paragraph Settings dialog to
12396 customize the paragraph.
12399 \begin_layout Description
12400 \begin_inset Flex CharStyle:Code
12403 \begin_layout Plain Layout
12410 \begin_inset Flex CharStyle:Code
12413 \begin_layout Plain Layout
12420 \begin_inset Flex CharStyle:Code
12423 \begin_layout Plain Layout
12430 \begin_inset Flex CharStyle:Code
12433 \begin_layout Plain Layout
12439 , describing the rendering style used for the inset's frame and buttons.
12440 Footnotes generally use
12441 \begin_inset Flex CharStyle:Code
12444 \begin_layout Plain Layout
12450 , ERT insets generally
12451 \begin_inset Flex CharStyle:Code
12454 \begin_layout Plain Layout
12460 , and character styles
12461 \begin_inset Flex CharStyle:Code
12464 \begin_layout Plain Layout
12473 \begin_layout Description
12474 \begin_inset Flex CharStyle:Code
12477 \begin_layout Plain Layout
12483 Required at the end of the InsetLayout declarations.
12486 \begin_layout Description
12487 \begin_inset Flex CharStyle:Code
12490 \begin_layout Plain Layout
12496 The font used for both the text body
12502 \begin_inset space ~
12506 \begin_inset CommandInset ref
12508 reference "sec:fonts"
12513 Note that defining this font automatically defines the
12514 \begin_inset Flex CharStyle:Code
12517 \begin_layout Plain Layout
12523 to the same value, so define this first and define
12524 \begin_inset Flex CharStyle:Code
12527 \begin_layout Plain Layout
12533 later if you want them to be different.
12536 \begin_layout Description
12537 \begin_inset Flex CharStyle:Code
12540 \begin_layout Plain Layout
12547 \begin_inset Quotes eld
12551 \begin_inset Quotes erd
12554 language, leading to Left-to-Right (latin) output, e.
12555 \begin_inset space \thinspace{}
12559 \begin_inset space \space{}
12562 in TeX code or URL.
12566 \begin_layout Description
12567 \begin_inset Flex CharStyle:Code
12570 \begin_layout Plain Layout
12577 \begin_inset Flex CharStyle:Code
12580 \begin_layout Plain Layout
12589 \begin_inset Flex CharStyle:Code
12592 \begin_layout Plain Layout
12598 ] Indicates whether the PlainLayout should be used or, instead, the user
12599 can change the paragraph style used in the inset.
12602 \begin_layout Description
12603 \begin_inset Flex CharStyle:Code
12606 \begin_layout Plain Layout
12612 As with paragraph styles (see page
12613 \begin_inset CommandInset ref
12614 LatexCommand pageref
12615 reference "des:FreeSpacing"
12622 \begin_layout Description
12623 \begin_inset Flex CharStyle:Code
12626 \begin_layout Plain Layout
12633 \begin_inset Flex CharStyle:Code
12636 \begin_layout Plain Layout
12645 \begin_inset Flex CharStyle:Code
12648 \begin_layout Plain Layout
12654 ] Whether to include the contents of this inset in the strings generated
12655 for the `Outline' pane.
12656 One would not, for example, want the content of a footnote in a section
12657 header to be included in the TOC displayed in the outline, but one would
12658 normally want the content of a character style displayed.
12659 Default is false: not to include.
12662 \begin_layout Description
12663 \begin_inset Flex CharStyle:Code
12666 \begin_layout Plain Layout
12672 As with paragraph styles (see page
12673 \begin_inset CommandInset ref
12674 LatexCommand pageref
12675 reference "des:KeepEmpty"
12682 \begin_layout Description
12683 \begin_inset Flex CharStyle:Code
12686 \begin_layout Plain Layout
12692 The font used for the label.
12694 \begin_inset space ~
12698 \begin_inset CommandInset ref
12700 reference "sec:fonts"
12705 Note that this definition can never appear before
12706 \begin_inset Flex CharStyle:Code
12709 \begin_layout Plain Layout
12715 , lest it be ineffective.
12718 \begin_layout Description
12719 \begin_inset Flex CharStyle:Code
12722 \begin_layout Plain Layout
12728 What will be displayed on the button or elsewhere as the inset label.
12729 Some inset types (TeX code and Branch) modify this label on the fly.
12732 \begin_layout Description
12733 \begin_inset Flex CharStyle:Code
12736 \begin_layout Plain Layout
12742 The name of the corresponding LaTeX stuff.
12743 Either the environment or command name.
12746 \begin_layout Description
12747 \begin_inset Flex CharStyle:Code
12750 \begin_layout Plain Layout
12756 The optional parameter for the corresponding
12757 \begin_inset Flex CharStyle:Code
12760 \begin_layout Plain Layout
12766 stuff, including possible bracket pairs like
12767 \begin_inset Flex CharStyle:Code
12770 \begin_layout Plain Layout
12777 This parameter cannot be changed from within LyX.
12780 \begin_layout Description
12781 \begin_inset Flex CharStyle:Code
12784 \begin_layout Plain Layout
12790 As with paragraph styles (see page
12791 \begin_inset CommandInset ref
12792 LatexCommand pageref
12793 reference "des:LatexType"
12800 \begin_layout Description
12801 \begin_inset Flex CharStyle:Code
12804 \begin_layout Plain Layout
12811 \begin_inset Flex CharStyle:Code
12814 \begin_layout Plain Layout
12821 \begin_inset Flex CharStyle:Code
12824 \begin_layout Plain Layout
12831 \begin_inset Flex CharStyle:Code
12834 \begin_layout Plain Layout
12841 \begin_inset Flex CharStyle:Code
12844 \begin_layout Plain Layout
12850 (indicating a dummy definition ending definitions of charstyles, etc).
12851 This entry is required in and is only meaningful for Flex insets.
12852 Among other things, it determines on which menu this inset will appear.
12855 \begin_layout Description
12856 \begin_inset Flex CharStyle:Code
12859 \begin_layout Plain Layout
12866 \begin_inset Flex CharStyle:Code
12869 \begin_layout Plain Layout
12878 \begin_inset Flex CharStyle:Code
12881 \begin_layout Plain Layout
12887 ] Whether multiple paragraphs are permitted in this inset.
12888 This will also set CustomPars to the same value and ForcePlain to the opposite
12890 These can be reset to other values, if they are used
12897 \begin_layout Description
12898 \begin_inset Flex CharStyle:Code
12901 \begin_layout Plain Layout
12908 \begin_inset Flex CharStyle:Code
12911 \begin_layout Plain Layout
12920 \begin_inset Flex CharStyle:Code
12923 \begin_layout Plain Layout
12929 ] Whether fragile commands in this layout should be
12930 \begin_inset Flex CharStyle:Code
12933 \begin_layout Plain Layout
12946 whether the command should itself be protected.)
12949 \begin_layout Description
12950 \begin_inset Flex CharStyle:Code
12953 \begin_layout Plain Layout
12960 \begin_inset Flex CharStyle:Code
12963 \begin_layout Plain Layout
12972 \begin_inset Flex CharStyle:Code
12975 \begin_layout Plain Layout
12981 ] As with paragraph styles (see page
12982 \begin_inset CommandInset ref
12984 reference "des:PathThru"
12991 \begin_layout Description
12992 \begin_inset Flex CharStyle:Code
12995 \begin_layout Plain Layout
13001 As with paragraph styles (see page
13002 \begin_inset CommandInset ref
13003 LatexCommand pageref
13004 reference "des:Preamble"
13011 \begin_layout Description
13012 \begin_inset Flex CharStyle:Code
13015 \begin_layout Plain Layout
13022 \begin_inset Flex CharStyle:Code
13025 \begin_layout Plain Layout
13031 ] As with paragraph styles (see page
13032 \begin_inset CommandInset ref
13033 LatexCommand pageref
13034 reference "des:Requires"
13041 \begin_layout Subsection
13045 \begin_layout Standard
13046 \begin_inset CommandInset label
13052 Since version 1.3.0 of LyX, it is both possible and necessary to define the
13054 \begin_inset Flex CharStyle:MenuItem
13057 \begin_layout Plain Layout
13064 \begin_inset Flex CharStyle:MenuItem
13067 \begin_layout Plain Layout
13073 , \SpecialChar \ldots{}
13074 ) in the text class itself.
13075 The standard counters are defined in the file
13076 \begin_inset Flex CharStyle:Code
13079 \begin_layout Plain Layout
13085 , so you may have to do no more than add
13088 \begin_layout LyX-Code
13089 Input stdcounters.inc
13092 \begin_layout Standard
13093 to your layout file to get them to work.
13094 But if you want to define custom counters, then you can do so.
13095 The counter declaration must begin with:
13098 \begin_layout LyX-Code
13102 \begin_layout Standard
13103 where of course `name' is replaced by the name of the counter.
13104 And it must end with
13105 \begin_inset Quotes eld
13109 \begin_inset Flex CharStyle:Code
13112 \begin_layout Plain Layout
13119 \begin_inset Quotes erd
13123 The following parameters can also be used:
13126 \begin_layout Description
13127 \begin_inset Flex CharStyle:Code
13130 \begin_layout Plain Layout
13131 LabelString [string=""]
13136 when this is defined, this string defines how the counter is displayed.
13137 Setting this value sets
13138 \begin_inset Flex CharStyle:Code
13141 \begin_layout Plain Layout
13142 LabelStringAppendix
13148 The following special constructs can be used in the string:
13152 \begin_layout Itemize
13153 \begin_inset Flex CharStyle:Code
13156 \begin_layout Plain Layout
13164 will be replaced by the expansion of the
13165 \begin_inset Flex CharStyle:Code
13168 \begin_layout Plain Layout
13175 \begin_inset Flex CharStyle:Code
13178 \begin_layout Plain Layout
13179 LabelStringAppendix
13185 \begin_inset Flex CharStyle:Code
13188 \begin_layout Plain Layout
13198 \begin_layout Itemize
13199 counter values can be expressed using LaTeX-like macros
13200 \begin_inset Flex CharStyle:Code
13203 \begin_layout Plain Layout
13220 \begin_inset Flex CharStyle:Code
13223 \begin_layout Plain Layout
13235 \begin_layout Plain Layout
13245 Actually, the situation is a bit more complicated: any
13264 other than those described below will produce arabic numerals.
13265 It would not be surprising to see this change in the future.
13271 \begin_inset Flex CharStyle:Code
13274 \begin_layout Plain Layout
13280 : 1, 2, 3,\SpecialChar \ldots{}
13282 \begin_inset Flex CharStyle:Code
13285 \begin_layout Plain Layout
13291 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13293 \begin_inset Flex CharStyle:Code
13296 \begin_layout Plain Layout
13302 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13304 \begin_inset Flex CharStyle:Code
13307 \begin_layout Plain Layout
13313 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13315 \begin_inset Flex CharStyle:Code
13318 \begin_layout Plain Layout
13324 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13326 \begin_inset Flex CharStyle:Code
13329 \begin_layout Plain Layout
13335 for hebrew numerals.
13339 \begin_layout Standard
13340 If LabelString is not defined, a default value is constructed as follows:
13341 if the counter has a master counter
13342 \begin_inset Flex CharStyle:Code
13345 \begin_layout Plain Layout
13352 \begin_inset Flex CharStyle:Code
13355 \begin_layout Plain Layout
13362 \begin_inset Flex CharStyle:Code
13365 \begin_layout Plain Layout
13375 is used; otherwise the string
13376 \begin_inset Flex CharStyle:Code
13379 \begin_layout Plain Layout
13390 \begin_layout Description
13391 \begin_inset Flex CharStyle:Code
13394 \begin_layout Plain Layout
13395 LabelStringAppendix [string=""]
13401 \begin_inset Flex CharStyle:Code
13404 \begin_layout Plain Layout
13410 , but for use in the Appendix.
13413 \begin_layout Description
13414 \begin_inset Flex CharStyle:Code
13417 \begin_layout Plain Layout
13424 \begin_inset Flex CharStyle:Code
13427 \begin_layout Plain Layout
13434 \begin_inset Quotes erd
13438 \begin_inset Quotes erd
13441 ] If this is set to the name of another counter, the present counter will
13442 be reset every time the other one is increased.
13444 \begin_inset Flex CharStyle:Code
13447 \begin_layout Plain Layout
13454 \begin_inset Flex CharStyle:Code
13457 \begin_layout Plain Layout
13466 \begin_layout Subsection
13470 \begin_layout Standard
13471 \begin_inset CommandInset label
13477 A font description looks like this:
13480 \begin_layout LyX-Code
13490 \begin_layout LyX-Code
13494 \begin_layout LyX-Code
13498 \begin_layout Standard
13499 The following commands are available:
13502 \begin_layout Description
13503 \begin_inset Flex CharStyle:Code
13506 \begin_layout Plain Layout
13513 \begin_inset Flex CharStyle:Code
13516 \begin_layout Plain Layout
13525 \begin_inset Flex CharStyle:Code
13528 \begin_layout Plain Layout
13535 \begin_inset Flex CharStyle:Code
13538 \begin_layout Plain Layout
13545 \begin_inset Flex CharStyle:Code
13548 \begin_layout Plain Layout
13555 \begin_inset Flex CharStyle:Code
13558 \begin_layout Plain Layout
13565 \begin_inset Flex CharStyle:Code
13568 \begin_layout Plain Layout
13575 \begin_inset Flex CharStyle:Code
13578 \begin_layout Plain Layout
13585 \begin_inset Flex CharStyle:Code
13588 \begin_layout Plain Layout
13595 \begin_inset Flex CharStyle:Code
13598 \begin_layout Plain Layout
13607 \begin_layout Description
13608 \begin_inset Flex CharStyle:Code
13611 \begin_layout Plain Layout
13620 \begin_inset Flex CharStyle:Code
13623 \begin_layout Plain Layout
13634 \begin_inset Flex CharStyle:Code
13637 \begin_layout Plain Layout
13644 \begin_inset Flex CharStyle:Code
13647 \begin_layout Plain Layout
13656 \begin_layout Description
13657 \begin_inset Flex CharStyle:Code
13660 \begin_layout Plain Layout
13667 \begin_inset Flex CharStyle:Code
13670 \begin_layout Plain Layout
13676 ] Valid argument are:
13677 \begin_inset Flex CharStyle:Code
13680 \begin_layout Plain Layout
13687 \begin_inset Flex CharStyle:Code
13690 \begin_layout Plain Layout
13697 \begin_inset Flex CharStyle:Code
13700 \begin_layout Plain Layout
13707 \begin_inset Flex CharStyle:Code
13710 \begin_layout Plain Layout
13717 \begin_inset Flex CharStyle:Code
13720 \begin_layout Plain Layout
13727 \begin_inset Flex CharStyle:Code
13730 \begin_layout Plain Layout
13737 Each of these turns on or off the corresponding attribute.
13740 \begin_layout Description
13741 \begin_inset Flex CharStyle:Code
13744 \begin_layout Plain Layout
13753 \begin_inset Flex CharStyle:Code
13756 \begin_layout Plain Layout
13767 \begin_inset Flex CharStyle:Code
13770 \begin_layout Plain Layout
13779 \begin_layout Description
13780 \begin_inset Flex CharStyle:Code
13783 \begin_layout Plain Layout
13792 \begin_inset Flex CharStyle:Code
13795 \begin_layout Plain Layout
13806 \begin_inset Flex CharStyle:Code
13809 \begin_layout Plain Layout
13816 \begin_inset Flex CharStyle:Code
13819 \begin_layout Plain Layout
13826 \begin_inset Flex CharStyle:Code
13829 \begin_layout Plain Layout
13838 \begin_layout Description
13839 \begin_inset Flex CharStyle:Code
13842 \begin_layout Plain Layout
13849 \begin_inset Flex CharStyle:Code
13852 \begin_layout Plain Layout
13859 \begin_inset Flex CharStyle:Code
13862 \begin_layout Plain Layout
13869 \begin_inset Flex CharStyle:Code
13872 \begin_layout Plain Layout
13881 \begin_inset Flex CharStyle:Code
13884 \begin_layout Plain Layout
13891 \begin_inset Flex CharStyle:Code
13894 \begin_layout Plain Layout
13901 \begin_inset Flex CharStyle:Code
13904 \begin_layout Plain Layout
13911 \begin_inset Flex CharStyle:Code
13914 \begin_layout Plain Layout
13921 \begin_inset Flex CharStyle:Code
13924 \begin_layout Plain Layout
13933 \begin_layout Subsection
13934 Upgrading old layout files
13937 \begin_layout Standard
13938 The file format of layout files changes from time to time, so old layout
13939 files need to be converted.
13940 This process has been automated since LyX 1.4.0: If LyX reads an old format
13941 layout file it will call the conversion tool
13942 \begin_inset Flex CharStyle:Code
13945 \begin_layout Plain Layout
13946 LyXDir/scripts/layout2layout.py
13951 and convert it to a temporary file in current format.
13952 The original file is left untouched.
13953 If you want to convert the layout file permanently, just call the converter
13957 \begin_layout LyX-Code
13958 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13961 \begin_layout Standard
13962 (You need to replace
13963 \begin_inset Flex CharStyle:Code
13966 \begin_layout Plain Layout
13972 with the name of your LyX system directory, unless you happen to have defined
13973 such an environment variable.) Then copy
13974 \begin_inset Flex CharStyle:Code
13977 \begin_layout Plain Layout
13984 \begin_inset Flex CharStyle:Code
13987 \begin_layout Plain Layout
13996 \begin_layout Standard
13997 The automatic conversion only handles syntax changes.
13998 It cannot handle the case where the contents of included files was changed,
13999 so these will have to be converted separately.
14002 \begin_layout Section
14004 \begin_inset CommandInset label
14006 name "sec:templates"
14013 \begin_layout Standard
14014 Templates are created just like usual documents.
14015 The only difference is that usual documents contain all possible settings,
14016 including the font scheme and the paper size.
14017 Usually a user doesn't want a template to overwrite his defaults in these
14019 For that reason, the designer of a template should remove the corresponding
14021 \begin_inset Flex CharStyle:Code
14024 \begin_layout Plain Layout
14033 \begin_inset Flex CharStyle:Code
14036 \begin_layout Plain Layout
14044 from the template LyX file.
14045 This can be done with any simple text-editor, for example
14046 \begin_inset Flex CharStyle:Code
14049 \begin_layout Plain Layout
14056 \begin_inset Flex CharStyle:Code
14059 \begin_layout Plain Layout
14069 \begin_layout Standard
14070 Put the edited template files you create in
14071 \begin_inset Flex CharStyle:Code
14074 \begin_layout Plain Layout
14080 , copy the ones you use from the global template directory in
14081 \begin_inset Flex CharStyle:Code
14084 \begin_layout Plain Layout
14090 to the same place, and redefine the template path in the
14091 \begin_inset Flex CharStyle:MenuItem
14094 \begin_layout Plain Layout
14095 Tools\SpecialChar \menuseparator
14096 Preferences\SpecialChar \menuseparator
14105 \begin_layout Standard
14106 Note that there is a template which has a particular meaning:
14107 \begin_inset Flex CharStyle:Code
14110 \begin_layout Plain Layout
14117 This template is loaded every time you create a new document with
14118 \begin_inset Flex CharStyle:MenuItem
14121 \begin_layout Plain Layout
14122 File\SpecialChar \menuseparator
14128 in order to provide useful defaults.
14129 To create this template from inside LyX, all you have to do is to open
14130 a document with the correct settings, and use the
14131 \begin_inset Flex CharStyle:MenuItem
14134 \begin_layout Plain Layout
14135 Save as Document Defaults
14143 \begin_layout Chapter
14144 Including External Material
14147 \begin_layout Standard
14148 \begin_inset Box Shadowbox
14157 height_special "totalheight"
14160 \begin_layout Plain Layout
14161 WARNING: This portion of the documentation has not been updated for some
14163 We certainly hope that it is still accurate, but there are no guarantees.
14171 \begin_layout Standard
14172 The use of material from sources external to LyX is covered in detail in
14178 This part of the manual covers what needs to happen behind the scenes for
14179 new sorts of material to be included.
14182 \begin_layout Section
14186 \begin_layout Standard
14187 The external material feature is based on the concept of a
14192 A template is a specification of how LyX should interface with a certain
14194 As bundled, LyX comes with predefined templates for Xfig figures, various
14195 raster format images, chess diagrams, and LilyPond music notation.
14196 You can check the actual list by using the menu
14197 \begin_inset Flex CharStyle:MenuItem
14200 \begin_layout Plain Layout
14201 Insert\SpecialChar \menuseparator
14202 File\SpecialChar \menuseparator
14209 Furthermore, it is possible to roll your own template to support a specific
14211 Later we'll describe in more detail what is involved, and hopefully you
14212 will submit all the templates you create so we can include them in a later
14216 \begin_layout Standard
14217 Another basic idea of the external material feature is to distinguish between
14218 the original file that serves as a base for final material and the produced
14219 file that is included in your exported or printed document.
14220 For example, consider the case of a figure produced with
14221 \begin_inset Flex CharStyle:Code
14224 \begin_layout Plain Layout
14231 The Xfig application itself works on an original file with the
14232 \begin_inset Flex CharStyle:Code
14235 \begin_layout Plain Layout
14242 Within Xfig, you create and change your figure, and when you are done,
14244 \begin_inset Flex CharStyle:Code
14247 \begin_layout Plain Layout
14254 When you want to include the figure in your document, you invoke
14255 \begin_inset Flex CharStyle:Code
14258 \begin_layout Plain Layout
14264 in order to create a PostScript file that can readily be included in your
14267 \begin_inset Flex CharStyle:Code
14270 \begin_layout Plain Layout
14276 file is the original file, and the PostScript file is the produced file.
14279 \begin_layout Standard
14280 This distinction is important in order to allow updating of the material
14281 while you are in the process of writing the document.
14282 Furthermore, it provides us with the flexibility that is needed to support
14283 multiple export formats.
14284 For instance, in the case of a plain text file, it is not exactly an award-winn
14285 ing idea to include the figure as raw PostScript.
14286 Instead, you'd either prefer to just include a reference to the figure
14287 or try to invoke some graphics to ASCII converter to make the final result
14288 look similar to the real graphics.
14289 The external material management allows you to do this, because it is parametri
14290 zed on the different export formats that LyX supports.
14293 \begin_layout Standard
14294 Besides supporting the production of different products according to the
14295 exported format, it supports tight integration with editing and viewing
14297 In the case of an Xfig figure, you are able to invoke Xfig on the original
14298 file with a single click from within the external material dialog in LyX,
14299 and also preview the produced PostScript file with Ghostview with another
14301 No more fiddling around with the command line and/or file browsers to locate
14302 and manipulate the original or produced files.
14303 In this way, you are finally able to take full advantage of the many different
14304 applications that are relevant to use when you write your documents, and
14305 ultimately be more productive.
14308 \begin_layout Section
14309 The external template configuration file
14312 \begin_layout Standard
14313 It is relatively easy to add custom external template definitions to LyX.
14314 However, be aware that doing this in an careless manner most probably
14318 introduce an easily exploitable security hole.
14319 So before you do this, please read the discussion about security in section
14321 \begin_inset CommandInset ref
14323 reference "sec:Security-discussion"
14330 \begin_layout Standard
14331 Having said that, we encourage you to submit any interesting templates that
14336 \begin_layout Standard
14337 The external templates are defined in the
14338 \begin_inset Flex CharStyle:Code
14341 \begin_layout Plain Layout
14342 LyXDir/lib/external_templates
14348 You can place your own version in
14349 \begin_inset Flex CharStyle:Code
14352 \begin_layout Plain Layout
14353 UserDir/external_templates
14361 \begin_layout Standard
14362 A typical template looks like this:
14365 \begin_layout LyX-Code
14369 \begin_layout LyX-Code
14370 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14373 \begin_layout LyX-Code
14377 \begin_layout LyX-Code
14381 \begin_layout LyX-Code
14385 \begin_layout LyX-Code
14389 \begin_layout LyX-Code
14393 \begin_layout LyX-Code
14394 AutomaticProduction true
14397 \begin_layout LyX-Code
14401 \begin_layout LyX-Code
14405 \begin_layout LyX-Code
14409 \begin_layout LyX-Code
14410 TransformCommand Rotate RotationLatexCommand
14413 \begin_layout LyX-Code
14414 TransformCommand Resize ResizeLatexCommand
14417 \begin_layout LyX-Code
14418 Product "$$RotateFront$$ResizeFront
14421 \begin_layout LyX-Code
14426 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14429 \begin_layout LyX-Code
14430 $$ResizeBack$$RotateBack"
14433 \begin_layout LyX-Code
14437 \begin_layout LyX-Code
14438 UpdateResult "$$AbsPath$$Basename.pstex_t"
14441 \begin_layout LyX-Code
14442 Requirement "graphicx"
14445 \begin_layout LyX-Code
14446 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14449 \begin_layout LyX-Code
14450 ReferencedFile latex "$$AbsPath$$Basename.eps"
14453 \begin_layout LyX-Code
14454 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14457 \begin_layout LyX-Code
14461 \begin_layout LyX-Code
14465 \begin_layout LyX-Code
14466 TransformCommand Rotate RotationLatexCommand
14469 \begin_layout LyX-Code
14470 TransformCommand Resize ResizeLatexCommand
14473 \begin_layout LyX-Code
14474 Product "$$RotateFront$$ResizeFront
14477 \begin_layout LyX-Code
14482 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14485 \begin_layout LyX-Code
14486 $$ResizeBack$$RotateBack"
14489 \begin_layout LyX-Code
14490 UpdateFormat pdftex
14493 \begin_layout LyX-Code
14494 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14497 \begin_layout LyX-Code
14498 Requirement "graphicx"
14501 \begin_layout LyX-Code
14502 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14505 \begin_layout LyX-Code
14506 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14509 \begin_layout LyX-Code
14513 \begin_layout LyX-Code
14517 \begin_layout LyX-Code
14518 Product "$$Contents(
14520 "$$AbsPath$$Basename.asc
14525 \begin_layout LyX-Code
14526 UpdateFormat asciixfig
14529 \begin_layout LyX-Code
14530 UpdateResult "$$AbsPath$$Basename.asc"
14533 \begin_layout LyX-Code
14537 \begin_layout LyX-Code
14541 \begin_layout LyX-Code
14542 Product "<graphic fileref=
14544 "$$AbsOrRelPathMaster$$Basename.eps
14549 \begin_layout LyX-Code
14553 \begin_layout LyX-Code
14557 \begin_layout LyX-Code
14558 UpdateResult "$$AbsPath$$Basename.eps"
14561 \begin_layout LyX-Code
14562 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14565 \begin_layout LyX-Code
14566 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14569 \begin_layout LyX-Code
14573 \begin_layout LyX-Code
14574 Product "[XFig: $$FName]"
14577 \begin_layout LyX-Code
14581 \begin_layout LyX-Code
14585 \begin_layout Standard
14586 As you can see, the template is enclosed in
14587 \begin_inset Flex CharStyle:Code
14590 \begin_layout Plain Layout
14596 \SpecialChar \ldots{}
14598 \begin_inset Flex CharStyle:Code
14601 \begin_layout Plain Layout
14608 It contains a header specifying some general settings and, for each supported
14609 primary document file format, a section
14610 \begin_inset Flex CharStyle:Code
14613 \begin_layout Plain Layout
14619 \SpecialChar \ldots{}
14621 \begin_inset Flex CharStyle:Code
14624 \begin_layout Plain Layout
14633 \begin_layout Subsection
14634 The template header
14637 \begin_layout Description
14638 \begin_inset Flex CharStyle:Code
14641 \begin_layout Plain Layout
14642 AutomaticProduction
14643 \begin_inset space ~
14651 Whether the file represented by the template must be generated by LyX.
14652 This command must occur exactly once.
14655 \begin_layout Description
14656 \begin_inset Flex CharStyle:Code
14659 \begin_layout Plain Layout
14661 \begin_inset space ~
14669 A glob pattern that is used in the file dialog to filter out the desired
14671 If there is more than one possible file extension (e.
14672 \begin_inset space \thinspace{}
14676 \begin_inset space \space{}
14680 \begin_inset Flex CharStyle:Code
14683 \begin_layout Plain Layout
14690 \begin_inset Flex CharStyle:Code
14693 \begin_layout Plain Layout
14699 ), use something like
14700 \begin_inset Flex CharStyle:Code
14703 \begin_layout Plain Layout
14710 This command must occur exactly once.
14713 \begin_layout Description
14714 \begin_inset Flex CharStyle:Code
14717 \begin_layout Plain Layout
14719 \begin_inset space ~
14727 The text that is displayed on the button.
14728 This command must occur exactly once.
14731 \begin_layout Description
14732 \begin_inset Flex CharStyle:Code
14735 \begin_layout Plain Layout
14737 \begin_inset space ~
14741 \begin_inset space ~
14749 The help text that is used in the External dialog.
14750 Provide enough information to explain to the user just what the template
14751 can provide him with.
14752 This command must occur exactly once.
14755 \begin_layout Description
14756 \begin_inset Flex CharStyle:Code
14759 \begin_layout Plain Layout
14761 \begin_inset space ~
14769 The file format of the original file.
14770 This must be the name of a format that is known to LyX (see section
14771 \begin_inset CommandInset ref
14773 reference "sub:Formats"
14779 \begin_inset Quotes eld
14783 \begin_inset Flex CharStyle:Code
14786 \begin_layout Plain Layout
14793 \begin_inset Quotes erd
14796 if the template can handle original files of more than one format.
14797 LyX will attempt to interrogate the file itself in order to deduce its
14798 format in this case.
14799 This command must occur exactly once.
14802 \begin_layout Description
14803 \begin_inset Flex CharStyle:Code
14806 \begin_layout Plain Layout
14808 \begin_inset space ~
14816 A unique name for the template.
14817 It must not contain substitution macros (see below).
14820 \begin_layout Description
14821 \begin_inset Flex CharStyle:Code
14824 \begin_layout Plain Layout
14826 \begin_inset space ~
14829 Rotate|Resize|Clip|Extra
14834 This command specifies which transformations are supported by this template.
14835 It may occur zero or more times.
14836 This command enables the corresponding tabs in the external dialog.
14838 \begin_inset Flex CharStyle:Code
14841 \begin_layout Plain Layout
14847 command must have either a corresponding
14848 \begin_inset Flex CharStyle:Code
14851 \begin_layout Plain Layout
14858 \begin_inset Flex CharStyle:Code
14861 \begin_layout Plain Layout
14868 \begin_inset Flex CharStyle:Code
14871 \begin_layout Plain Layout
14878 Otherwise the transformation will not be supported by that format.
14881 \begin_layout Subsection
14885 \begin_layout Description
14886 \begin_inset Flex CharStyle:Code
14889 \begin_layout Plain Layout
14891 \begin_inset space ~
14894 LaTeX|PDFLaTeX|PlainText|DocBook
14899 The primary document file format that this format definition is for.
14900 Not every template has a sensible representation in all document file formats.
14901 Please define nevertheless a
14902 \begin_inset Flex CharStyle:Code
14905 \begin_layout Plain Layout
14911 section for all formats.
14912 Use a dummy text when no representation is available.
14913 Then you can at least see a reference to the external material in the exported
14917 \begin_layout Description
14918 \begin_inset Flex CharStyle:Code
14921 \begin_layout Plain Layout
14923 \begin_inset space ~
14927 \begin_inset space ~
14935 This command defines an additional macro
14936 \begin_inset Flex CharStyle:Code
14939 \begin_layout Plain Layout
14945 for substitution in
14946 \begin_inset Flex CharStyle:Code
14949 \begin_layout Plain Layout
14957 \begin_inset Flex CharStyle:Code
14960 \begin_layout Plain Layout
14966 itself may contain substitution macros.
14967 The advantage over using
14968 \begin_inset Flex CharStyle:Code
14971 \begin_layout Plain Layout
14978 \begin_inset Flex CharStyle:Code
14981 \begin_layout Plain Layout
14987 is that the substituted value of
14988 \begin_inset Flex CharStyle:Code
14991 \begin_layout Plain Layout
14997 is sanitized so that it is a valid optional argument in the document format.
14998 This command may occur zero or more times.
15001 \begin_layout Description
15002 \begin_inset Flex CharStyle:Code
15005 \begin_layout Plain Layout
15007 \begin_inset space ~
15015 The text that is inserted in the exported document.
15016 This is actually the most important command and can be quite complex.
15017 This command must occur exactly once.
15020 \begin_layout Description
15021 \begin_inset Flex CharStyle:Code
15024 \begin_layout Plain Layout
15026 \begin_inset space ~
15034 This command specifies a preamble snippet that will be included in the
15036 It has to be defined using
15037 \begin_inset Flex CharStyle:Code
15040 \begin_layout Plain Layout
15046 \SpecialChar \ldots{}
15048 \begin_inset Flex CharStyle:Code
15051 \begin_layout Plain Layout
15058 This command may occur zero or more times.
15061 \begin_layout Description
15062 \begin_inset Flex CharStyle:Code
15065 \begin_layout Plain Layout
15067 \begin_inset space ~
15071 \begin_inset space ~
15079 This command denotes files that are created by the conversion process and
15080 are needed for a particular export format.
15081 If the filename is relative, it is interpreted relative to the master document.
15082 This command may be given zero or more times.
15085 \begin_layout Description
15086 \begin_inset Flex CharStyle:Code
15089 \begin_layout Plain Layout
15091 \begin_inset space ~
15099 The name of a required LaTeX package.
15100 The package is included via
15101 \begin_inset Flex CharStyle:Code
15104 \begin_layout Plain Layout
15112 in the LaTeX preamble.
15113 This command may occur zero or more times.
15116 \begin_layout Description
15117 \begin_inset Flex CharStyle:Code
15120 \begin_layout Plain Layout
15122 \begin_inset space ~
15126 \begin_inset space ~
15129 RotationLatexCommand
15134 This command specifies that the built in LaTeX command should be used for
15136 This command may occur once or not at all.
15139 \begin_layout Description
15140 \begin_inset Flex CharStyle:Code
15143 \begin_layout Plain Layout
15145 \begin_inset space ~
15149 \begin_inset space ~
15157 This command specifies that the built in LaTeX command should be used for
15159 This command may occur once or not at all.
15162 \begin_layout Description
15163 \begin_inset Flex CharStyle:Code
15166 \begin_layout Plain Layout
15168 \begin_inset space ~
15172 \begin_inset space ~
15175 RotationLatexOption
15180 This command specifies that rotation is done via an optional argument.
15181 This command may occur once or not at all.
15184 \begin_layout Description
15185 \begin_inset Flex CharStyle:Code
15188 \begin_layout Plain Layout
15190 \begin_inset space ~
15194 \begin_inset space ~
15202 This command specifies that resizing is done via an optional argument.
15203 This command may occur once or not at all.
15206 \begin_layout Description
15207 \begin_inset Flex CharStyle:Code
15210 \begin_layout Plain Layout
15212 \begin_inset space ~
15216 \begin_inset space ~
15224 This command specifies that clipping is done via an optional argument.
15225 This command may occur once or not at all.
15228 \begin_layout Description
15229 \begin_inset Flex CharStyle:Code
15232 \begin_layout Plain Layout
15234 \begin_inset space ~
15238 \begin_inset space ~
15246 This command specifies that an extra optional argument is used.
15247 This command may occur once or not at all.
15250 \begin_layout Description
15251 \begin_inset Flex CharStyle:Code
15254 \begin_layout Plain Layout
15256 \begin_inset space ~
15264 The file format of the converted file.
15265 This must be the name of a format that is known to LyX (see the
15266 \begin_inset Flex CharStyle:MenuItem
15269 \begin_layout Plain Layout
15274 ools\SpecialChar \menuseparator
15279 references:Conversion
15285 This command must occur exactly once.
15288 \begin_layout Description
15289 \begin_inset Flex CharStyle:Code
15292 \begin_layout Plain Layout
15294 \begin_inset space ~
15302 The file name of the converted file.
15303 The file name must be absolute.
15304 This command must occur exactly once.
15307 \begin_layout Subsection
15308 Preamble definitions
15311 \begin_layout Standard
15312 The external template configuration file may contain additional preamble
15313 definitions enclosed by
15314 \begin_inset Flex CharStyle:Code
15317 \begin_layout Plain Layout
15323 \SpecialChar \ldots{}
15325 \begin_inset Flex CharStyle:Code
15328 \begin_layout Plain Layout
15335 They can be used by the templates in the
15336 \begin_inset Flex CharStyle:Code
15339 \begin_layout Plain Layout
15348 \begin_layout Section
15349 The substitution mechanism
15352 \begin_layout Standard
15353 When the external material facility invokes an external program, it is done
15354 on the basis of a command defined in the template configuration file.
15355 These commands can contain various macros that are expanded before execution.
15356 Execution always take place in the directory of the containing document.
15359 \begin_layout Standard
15360 Also, whenever external material is to be displayed, the name will be produced
15361 by the substitution mechanism, and most other commands in the template
15362 definition support substitution as well.
15365 \begin_layout Standard
15366 The available macros are the following:
15369 \begin_layout Description
15370 \begin_inset Flex CharStyle:Code
15373 \begin_layout Plain Layout
15374 $$AbsOrRelPathMaster
15379 The file path, absolute or relative to the master LyX document.
15382 \begin_layout Description
15383 \begin_inset Flex CharStyle:Code
15386 \begin_layout Plain Layout
15387 $$AbsOrRelPathParent
15392 The file path, absolute or relative to the LyX document.
15395 \begin_layout Description
15396 \begin_inset Flex CharStyle:Code
15399 \begin_layout Plain Layout
15405 The absolute file path.
15408 \begin_layout Description
15409 \begin_inset Flex CharStyle:Code
15412 \begin_layout Plain Layout
15418 The filename without path and without the extension.
15421 \begin_layout Description
15422 \begin_inset Flex CharStyle:Code
15425 \begin_layout Plain Layout
15427 \begin_inset Quotes eld
15431 \begin_inset Quotes erd
15439 This macro will expand to the contents of the file with the name
15440 \begin_inset Flex CharStyle:Code
15443 \begin_layout Plain Layout
15452 \begin_layout Description
15453 \begin_inset Flex CharStyle:Code
15456 \begin_layout Plain Layout
15462 The file extension (including the dot).
15465 \begin_layout Description
15466 \begin_inset Flex CharStyle:Code
15469 \begin_layout Plain Layout
15475 The filename of the file specified in the external material dialog.
15476 This is either an absolute name, or it is relative to the LyX document.
15479 \begin_layout Description
15480 \begin_inset Flex CharStyle:Code
15483 \begin_layout Plain Layout
15490 \begin_inset Flex CharStyle:Code
15493 \begin_layout Plain Layout
15499 (absolute name or relative to the LyX document).
15502 \begin_layout Description
15503 \begin_inset Flex CharStyle:Code
15506 \begin_layout Plain Layout
15512 The file path, relative to the master LyX document.
15515 \begin_layout Description
15516 \begin_inset Flex CharStyle:Code
15519 \begin_layout Plain Layout
15525 The file path, relative to the LyX document.
15528 \begin_layout Description
15529 \begin_inset Flex CharStyle:Code
15532 \begin_layout Plain Layout
15538 This macro will expand to the absolute path of the system directory.
15539 This is typically used to point to the various helper scripts that are
15543 \begin_layout Description
15544 \begin_inset Flex CharStyle:Code
15547 \begin_layout Plain Layout
15553 A name and full path to a temporary file which will be automatically deleted
15554 whenever the containing document is closed, or the external material insertion
15558 \begin_layout Standard
15559 All path macros contain a trailing directory separator, so you can construct
15561 \begin_inset space \thinspace{}
15565 \begin_inset space \space{}
15568 the absolute filename with
15569 \begin_inset Flex CharStyle:Code
15572 \begin_layout Plain Layout
15573 $$AbsPath$$Basename$$Extension
15581 \begin_layout Standard
15582 The macros above are substituted in all commands unless otherwise noted.
15584 \begin_inset Flex CharStyle:Code
15587 \begin_layout Plain Layout
15593 supports additionally the following substitutions if they are enabled by
15595 \begin_inset Flex CharStyle:Code
15598 \begin_layout Plain Layout
15605 \begin_inset Flex CharStyle:Code
15608 \begin_layout Plain Layout
15617 \begin_layout Description
15618 \begin_inset Flex CharStyle:Code
15621 \begin_layout Plain Layout
15627 The front part of the resize command.
15630 \begin_layout Description
15631 \begin_inset Flex CharStyle:Code
15634 \begin_layout Plain Layout
15640 The back part of the resize command.
15643 \begin_layout Description
15644 \begin_inset Flex CharStyle:Code
15647 \begin_layout Plain Layout
15653 The front part of the rotation command.
15656 \begin_layout Description
15657 \begin_inset Flex CharStyle:Code
15660 \begin_layout Plain Layout
15666 The back part of the rotation command.
15669 \begin_layout Standard
15670 The value string of the
15671 \begin_inset Flex CharStyle:Code
15674 \begin_layout Plain Layout
15680 command supports additionally the following substitutions if they are enabled
15682 \begin_inset Flex CharStyle:Code
15685 \begin_layout Plain Layout
15692 \begin_inset Flex CharStyle:Code
15695 \begin_layout Plain Layout
15704 \begin_layout Description
15705 \begin_inset Flex CharStyle:Code
15708 \begin_layout Plain Layout
15717 \begin_layout Description
15718 \begin_inset Flex CharStyle:Code
15721 \begin_layout Plain Layout
15730 \begin_layout Description
15731 \begin_inset Flex CharStyle:Code
15734 \begin_layout Plain Layout
15743 \begin_layout Description
15744 \begin_inset Flex CharStyle:Code
15747 \begin_layout Plain Layout
15753 The rotation option.
15756 \begin_layout Standard
15757 You may ask why there are so many path macros.
15758 There are mainly two reasons:
15761 \begin_layout Enumerate
15762 Relative and absolute file names should remain relative or absolute, respectivel
15764 Users may have reasons to prefer either form.
15765 Relative names are useful for portable documents that should work on different
15766 machines, for example.
15767 Absolute names may be required by some programs.
15770 \begin_layout Enumerate
15771 LaTeX treats relative file names differently than LyX and other programs
15772 in nested included files.
15773 For LyX, a relative file name is always relative to the document that contains
15775 For LaTeX, it is always relative to the master document.
15776 These two definitions are identical if you have only one document, but
15777 differ if you have a master document that includes part documents.
15778 That means that relative filenames must be transformed when presented to
15780 Fortunately LyX does this automatically for you if you choose the right
15784 \begin_layout Standard
15785 So which path macro should be used in new template definitions? The rule
15789 \begin_layout Itemize
15791 \begin_inset Flex CharStyle:Code
15794 \begin_layout Plain Layout
15800 if an absolute path is required.
15803 \begin_layout Itemize
15805 \begin_inset Flex CharStyle:Code
15808 \begin_layout Plain Layout
15809 $$AbsOrRelPathMaster
15814 if the substituted string is some kind of LaTeX input.
15817 \begin_layout Itemize
15819 \begin_inset Flex CharStyle:Code
15822 \begin_layout Plain Layout
15823 $$AbsOrRelPathParent
15828 in order to preserve the user's choice.
15831 \begin_layout Standard
15832 There are special cases where this rule does not work and e.
15833 \begin_inset space \thinspace{}
15837 \begin_inset space \space{}
15840 relative names are needed, but normally it will work just fine.
15841 One example for such a case is the command
15842 \begin_inset Flex CharStyle:Code
15845 \begin_layout Plain Layout
15846 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15851 in the XFig template above: We can't use the absolute name because the
15853 \begin_inset Flex CharStyle:Code
15856 \begin_layout Plain Layout
15862 files needs the relative name in order to rewrite the file content.
15865 \begin_layout Section
15866 \begin_inset CommandInset label
15868 name "sec:Security-discussion"
15872 Security discussion
15875 \begin_layout Standard
15876 \begin_inset Box Shadowbox
15885 height_special "totalheight"
15888 \begin_layout Plain Layout
15889 WARNING: This section is definitely outdated.
15897 \begin_layout Standard
15898 The external material feature interfaces with a lot of external programs
15899 and does so automatically, so we have to consider the security implications
15901 In particular, since you have the option of including your own filenames
15902 and/or parameter strings and those are expanded into a command, it seems
15903 that it would be possible to create a malicious document which executes
15904 arbitrary commands when a user views or prints the document.
15905 This is something we definitely want to avoid.
15908 \begin_layout Standard
15909 However, since the external program commands are specified in the template
15910 configuration file only, there are no security issues if LyX is properly
15911 configured with safe templates only.
15912 This is so because the external programs are invoked with the
15913 \begin_inset Flex CharStyle:Code
15916 \begin_layout Plain Layout
15922 -system call rather than the
15923 \begin_inset Flex CharStyle:Code
15926 \begin_layout Plain Layout
15932 system-call, so it's not possible to execute arbitrary commands from the
15933 filename or parameter section via the shell.
15936 \begin_layout Standard
15937 This also implies that you are restricted in what command strings you can
15938 use in the external material templates.
15939 In particular, pipes and redirection are not readily available.
15940 This has to be so if LyX should remain safe.
15941 If you want to use some of the shell features, you should write a safe
15942 script to do this in a controlled manner, and then invoke the script from
15943 the command string.
15945 \begin_inset Flex CharStyle:Code
15948 \begin_layout Plain Layout
15954 directory of the LyX installation, you can find a safe wrapper script
15955 \begin_inset Flex CharStyle:Code
15958 \begin_layout Plain Layout
15959 general_command_wrapper.py
15964 that supports redirection of input and output.
15965 That can serve as an example for how to write safe template scripts.
15966 For a more advanced example that uses
15967 \begin_inset Flex CharStyle:Code
15970 \begin_layout Plain Layout
15976 and friends, take a look at the
15977 \begin_inset Flex CharStyle:Code
15980 \begin_layout Plain Layout
15989 \begin_layout Standard
15990 It is possible to design a template that interacts directly with the shell,
15991 but since this would allow a malicious user to execute arbitrary commands
15992 by writing clever filenames and/or parameters, we generally recommend that
15993 you only use safe scripts that work with the
15994 \begin_inset Flex CharStyle:Code
15997 \begin_layout Plain Layout
16003 system call in a controlled manner.
16004 Of course, for use in a controlled environment, it can be tempting to just
16005 fall back to use ordinary shell scripts.
16006 If you do so, be aware that you
16010 provide an easily exploitable security hole in your system.
16011 Of course it stands to reason that such unsafe templates will never be
16012 included in the standard LyX distribution, although we do encourage people
16013 to submit new templates in the open source tradition.
16014 But LyX as shipped from the official distribution channels will never have
16018 \begin_layout Standard
16019 Including external material provides a lot of power, and you have to be
16020 careful not to introduce security hazards with this power.
16021 A subtle error in a single line in an innocent looking script can open
16022 the door to huge security problems.
16023 So if you do not fully understand the issues, we recommend that you consult
16024 a knowledgeable security professional or the LyX development team if you
16025 have any questions about whether a given template is safe or not.
16026 And do this before you use it in an uncontrolled environment.