1 #LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
44 \use_default_options false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
67 \font_typewriter default
68 \font_default_family default
76 \default_output_format default
77 \bibtex_command default
78 \index_command default
82 \pdf_title "LyX Configuration Manual"
83 \pdf_author "LyX Team"
84 \pdf_subject "LyX-documentation Customization"
85 \pdf_keywords "LyX, documentation, customization"
87 \pdf_bookmarksnumbered true
88 \pdf_bookmarksopen true
89 \pdf_bookmarksopenlevel 1
94 \pdf_pdfusetitle false
95 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
103 \paperorientation portrait
110 \paragraph_separation indent
112 \quotes_language english
115 \paperpagestyle headings
116 \tracking_changes false
117 \output_changes false
127 Customizing LyX: Features for the Advanced User
135 \begin_layout Plain Layout
137 If you have comments or error corrections, please send them to the LyX Documenta
139 \begin_inset CommandInset href
141 target "lyx-docs@lists.lyx.org"
148 \begin_inset Quotes eld
152 \begin_inset Quotes erd
155 in the subject header, and please cc the current maintainer of this file,
156 Richard Heck <rgheck@comcast.net>.
162 \begin_inset Newline newline
166 \begin_inset Newline newline
172 \begin_layout Standard
173 \begin_inset CommandInset toc
174 LatexCommand tableofcontents
181 \begin_layout Standard
182 \begin_inset Note Note
185 \begin_layout Plain Layout
186 Please use change tracking when modifying this document.
187 This makes it easier for our translators to recognize things that have
188 been changed, and it helps the maintainer keep up-to-date with what's been
197 \begin_layout Chapter
201 \begin_layout Standard
202 This manual covers the customization features present in LyX.
203 In it, we discuss issues like keyboard shortcuts, screen previewing options,
204 printer options, sending commands to LyX via the LyX Server, internationalizati
205 on, installing new LaTeX classes and LyX layouts, etc.
206 We can't possibly hope to touch on everything you can change—our developers
207 add new features faster than we can document them—but we will explain the
208 most common customizations and hopefully point you in the right direction
209 for some of the more obscure ones.
212 \begin_layout Standard
213 \begin_inset Branch OutDated
216 \begin_layout Standard
217 Information from previous versions of this document that now seems to be
218 outdated is contained in the OutDated branch of this document.
219 By default, this information will not appear in the LaTeX output.
227 \begin_layout Chapter
228 LyX configuration files
231 \begin_layout Standard
232 This chapter aims to help you to find your way through the LyX configuration
234 Before continuing to read this chapter, you should find out where your
235 LyX library and user directories are by using
236 \begin_inset Flex CharStyle:MenuItem
239 \begin_layout Plain Layout
240 Help\SpecialChar \menuseparator
251 The library directory is the place where LyX places its system-wide configurati
252 on files; the user directory is where you can place your modified versions.
253 We will call the former
254 \begin_inset Flex CharStyle:Code
257 \begin_layout Plain Layout
264 \begin_inset Flex CharStyle:MenuItem
267 \begin_layout Plain Layout
273 in the remainder of this document.
277 \begin_layout Section
279 \begin_inset Flex CharStyle:Code
282 \begin_layout Plain Layout
291 \begin_layout Standard
292 \begin_inset Flex CharStyle:Code
295 \begin_layout Plain Layout
301 and its sub-directories contain a number of files and that can be used
302 to customize LyX's behavior.
303 You can change many of these files from within LyX itself through the
304 \begin_inset Flex CharStyle:MenuItem
307 \begin_layout Plain Layout
308 Tools\SpecialChar \menuseparator
315 Most customization that you will want to do in LyX is possible through
317 However, many other inner aspects of LyX can be customized by modifying
319 \begin_inset Flex CharStyle:Code
322 \begin_layout Plain Layout
329 These files fall in different categories, described in the following subsection
333 \begin_layout Subsection
334 Automatically generated files
337 \begin_layout Standard
338 The files, which are to be found in
339 \begin_inset Flex CharStyle:MenuItem
342 \begin_layout Plain Layout
348 , are generated when you configure LyX.
349 They contain various default values that are guessed by inspection.
350 In general, it is not a good idea to modify them, since they might be overwritt
354 \begin_layout Labeling
355 \labelwidthstring 00.00.0000
356 \begin_inset Flex CharStyle:Code
359 \begin_layout Plain Layout
365 contains defaults for various commands.
368 \begin_layout Labeling
369 \labelwidthstring 00.00.0000
370 \begin_inset Flex CharStyle:Code
373 \begin_layout Plain Layout
379 contains the list of packages that have been recognized by LyX.
380 It is currently unused by the LyX program itself, but the information extracted
381 , and more, is made available with
382 \begin_inset Flex CharStyle:MenuItem
385 \begin_layout Plain Layout
386 Help\SpecialChar \menuseparator
399 \begin_layout Labeling
400 \labelwidthstring 00.00.0000
401 \begin_inset Flex CharStyle:Code
404 \begin_layout Plain Layout
410 the list of text classes that have been found in your
411 \begin_inset Flex CharStyle:Code
414 \begin_layout Plain Layout
420 directories, along with the associated LaTeX document class and their descripti
424 \begin_layout Labeling
425 \labelwidthstring 00.00.0000
426 \begin_inset Flex CharStyle:Code
429 \begin_layout Plain Layout
435 the list of layout modules found in your
436 \begin_inset Flex CharStyle:Code
439 \begin_layout Plain Layout
448 \begin_layout Labeling
449 \labelwidthstring 00.00.0000
450 \begin_inset Flex CharStyle:Code
453 \begin_layout Plain Layout
459 lists of various sorts of LaTeX-related files found on your system
462 \begin_layout Labeling
463 \labelwidthstring 00.00.0000
464 \begin_inset Flex CharStyle:Code
467 \begin_layout Plain Layout
473 is automatically generated during configuration from the file
474 \begin_inset Flex CharStyle:Code
477 \begin_layout Plain Layout
484 It contains information on your LaTeX configuration.
487 \begin_layout Subsection
491 \begin_layout Standard
492 These directories are duplicated between
493 \begin_inset Flex CharStyle:Code
496 \begin_layout Plain Layout
503 \begin_inset Flex CharStyle:Code
506 \begin_layout Plain Layout
513 If a particular files exists in both places, the one in
514 \begin_inset Flex CharStyle:Code
517 \begin_layout Plain Layout
526 \begin_layout Labeling
527 \labelwidthstring 00.00.0000
528 \begin_inset Flex CharStyle:Code
531 \begin_layout Plain Layout
537 this directory contains files with the extension
538 \begin_inset Flex CharStyle:Code
541 \begin_layout Plain Layout
547 that define the keybindings used in LyX.
548 If there exists an internationalized version of the bind file named
549 \begin_inset Flex CharStyle:Code
552 \begin_layout Plain Layout
558 , that will be used first.
561 \begin_layout Labeling
562 \labelwidthstring 00.00.0000
563 \begin_inset Flex CharStyle:Code
566 \begin_layout Plain Layout
572 contains graphics files that can be included in documents.
576 \begin_layout Labeling
577 \labelwidthstring 00.00.0000
578 \begin_inset Flex CharStyle:Code
581 \begin_layout Plain Layout
587 contains LyX documentation files (including the one you are currently reading).
589 \begin_inset Flex CharStyle:Code
592 \begin_layout Plain Layout
598 deserves special attention, as noted above.
599 The internationalized help docs are in subdirectories
600 \begin_inset Flex CharStyle:Code
603 \begin_layout Plain Layout
610 \begin_inset Quotes eld
614 \begin_inset Quotes erd
617 is the ISO language code.
623 \begin_inset CommandInset ref
625 reference "cha:Internationalizing-LyX"
632 \begin_layout Labeling
633 \labelwidthstring 00.00.0000
634 \begin_inset Flex CharStyle:Code
637 \begin_layout Plain Layout
643 contains example files that explain how to use some features.
644 In the file browser, press the
645 \begin_inset Flex CharStyle:MenuItem
648 \begin_layout Plain Layout
657 \begin_layout Labeling
658 \labelwidthstring 00.00.0000
659 \begin_inset Flex CharStyle:Code
662 \begin_layout Plain Layout
668 contains image files that are used by the
669 \begin_inset Flex CharStyle:MenuItem
672 \begin_layout Plain Layout
679 In addition, it also contains the individual icons used in the toolbar
680 and the banners that can be shown when LyX is launched.
683 \begin_layout Labeling
684 \labelwidthstring 00.00.0000
685 \begin_inset Flex CharStyle:Code
688 \begin_layout Plain Layout
694 contains keyboard keymapping files.
700 \begin_inset CommandInset ref
702 reference "sec:International-Keymap-Stuff"
709 \begin_layout Labeling
710 \labelwidthstring 00.00.0000
711 \begin_inset Flex CharStyle:Code
714 \begin_layout Plain Layout
720 contains the text class and module files described in Chapter
725 \begin_inset CommandInset ref
727 reference "cha:Installing-New-Document"
734 \begin_layout Labeling
735 \labelwidthstring 00.00.0000
736 \begin_inset Flex CharStyle:Code
739 \begin_layout Plain Layout
746 \begin_inset Flex CharStyle:Code
749 \begin_layout Plain Layout
755 Python scripts used to convert between LyX versions.
756 These can be run from the command line if, say, you want to batch-convert
760 \begin_layout Labeling
761 \labelwidthstring 00.00.0000
762 \begin_inset Flex CharStyle:Code
765 \begin_layout Plain Layout
771 contains some files that demonstrate the capabilities of the
772 \begin_inset Flex CharStyle:MenuItem
775 \begin_layout Plain Layout
786 Also contains some scripts used by LyX itself.
789 \begin_layout Labeling
790 \labelwidthstring 00.00.0000
791 \begin_inset Flex CharStyle:Code
794 \begin_layout Plain Layout
800 contains the standard LyX template files described in Chapter
805 \begin_inset CommandInset ref
807 reference "sec:Creating-Templates"
814 \begin_layout Labeling
815 \labelwidthstring 00.00.0000
816 \begin_inset Flex CharStyle:Code
819 \begin_layout Plain Layout
825 contains files with the extension
826 \begin_inset Flex CharStyle:Code
829 \begin_layout Plain Layout
835 that define the user interface to LyX.
836 That is, the files define which items appear in which menus and the items
837 appearing on the toolbar.
840 \begin_layout Subsection
841 Files you don't want to modify
844 \begin_layout Standard
845 These files are used internally by LyX and you generally do not need to
846 modify them unless you are a developer.
849 \begin_layout Labeling
850 \labelwidthstring 00.00.0000
851 \begin_inset Flex CharStyle:Code
854 \begin_layout Plain Layout
860 this file contains the list of LyX developers.
861 The contents are displayed with the menu entry
862 \begin_inset Flex CharStyle:MenuItem
865 \begin_layout Plain Layout
866 Help\SpecialChar \menuseparator
879 \begin_layout Labeling
880 \labelwidthstring 00.00.0000
881 \begin_inset Flex CharStyle:Code
884 \begin_layout Plain Layout
890 this is a LaTeX script used during the configuration process.
894 \begin_layout Labeling
895 \labelwidthstring 00.00.0000
896 \begin_inset Flex CharStyle:Code
899 \begin_layout Plain Layout
905 this is the script that is used to re-configure LyX.
906 It creates configuration files in the directory it was run from.
909 \begin_layout Subsection
910 Other files needing a line or two...
913 \begin_layout Labeling
914 \labelwidthstring 00.00.0000
915 \begin_inset Flex CharStyle:Code
918 \begin_layout Plain Layout
924 this contains tables describing how different character encodings can be
928 \begin_layout Labeling
929 \labelwidthstring 00.00.0000
930 \begin_inset Flex CharStyle:Code
933 \begin_layout Plain Layout
939 this file contains the templates available to the new
940 \begin_inset Flex CharStyle:MenuItem
943 \begin_layout Plain Layout
956 \begin_layout Labeling
957 \labelwidthstring 00.00.0000
958 \begin_inset Flex CharStyle:Code
961 \begin_layout Plain Layout
967 this file contains a list of all the languages currently supported by LyX.
970 \begin_layout Section
971 Your local configuration directory
974 \begin_layout Standard
975 Even if you are using LyX as an unprivileged user, you might want to change
976 LyX configuration for your own use.
978 \begin_inset Flex CharStyle:Code
981 \begin_layout Plain Layout
987 directory contains all your personal configuration files.
988 This is the directory described as
989 \begin_inset Quotes eld
993 \begin_inset Quotes erd
997 \begin_inset Flex CharStyle:MenuItem
1000 \begin_layout Plain Layout
1001 Help\SpecialChar \menuseparator
1003 \begin_inset space ~
1012 This directory is used as a mirror of
1013 \begin_inset Flex CharStyle:Code
1016 \begin_layout Plain Layout
1022 , which means that every file in
1023 \begin_inset Flex CharStyle:Code
1026 \begin_layout Plain Layout
1032 is a replacement for the corresponding file in
1033 \begin_inset Flex CharStyle:Code
1036 \begin_layout Plain Layout
1043 Any configuration file described in the above sections can be placed either
1044 in the system-wide directory, in which case it will affect all users, or
1045 in your local directory for your own use.
1048 \begin_layout Standard
1049 To make things clearer, let's provide a few examples:
1052 \begin_layout Itemize
1053 The preferences set in the
1054 \begin_inset Flex CharStyle:MenuItem
1057 \begin_layout Plain Layout
1058 Tools\SpecialChar \menuseparator
1064 dialog are saved to a file
1065 \begin_inset Flex CharStyle:Code
1068 \begin_layout Plain Layout
1075 \begin_inset Flex CharStyle:Code
1078 \begin_layout Plain Layout
1087 \begin_layout Itemize
1088 When you reconfigure using
1089 \begin_inset Flex CharStyle:MenuItem
1092 \begin_layout Plain Layout
1093 Tools\SpecialChar \menuseparator
1100 \begin_inset Flex CharStyle:Code
1103 \begin_layout Plain Layout
1109 script, and the resulting files are written in your local configuration
1111 This means that any additional text class file that you might have added
1113 \begin_inset Flex CharStyle:Code
1116 \begin_layout Plain Layout
1122 will be added to the list of classes in the
1123 \begin_inset Flex CharStyle:MenuItem
1126 \begin_layout Plain Layout
1127 Document\SpecialChar \menuseparator
1136 \begin_layout Itemize
1137 If you get some updated documentation from LyX ftp site and cannot install
1138 it because you do not have sysadmin rights on your system, you can just
1140 \begin_inset Flex CharStyle:Code
1143 \begin_layout Plain Layout
1149 and the items in the
1150 \begin_inset Flex CharStyle:MenuItem
1153 \begin_layout Plain Layout
1159 menu will open them!
1162 \begin_layout Section
1163 Running LyX with multiple configurations
1166 \begin_layout Standard
1167 The configuration freedom of the local configuration directory may not suffice
1168 if you want to have more than one configuration at your disposal.
1169 For example, you may want to be use different key bindings or printer settings
1171 You can achieve this by having several such directories.
1172 You then specify which directory to use at run-time.
1175 \begin_layout Standard
1176 Invoking LyX with the command line switch
1177 \begin_inset Flex CharStyle:Code
1180 \begin_layout Plain Layout
1190 instructs the program to read the configuration from that directory, and
1191 not from the default directory.
1192 (You can determine the default directory by running LyX without the
1193 \begin_inset Flex CharStyle:Code
1196 \begin_layout Plain Layout
1202 switch.) If the specified directory does not exist, LyX offers to create
1203 it for you, just like it does for the default directory on the first time
1204 you run the program.
1205 You can modify the configuration options in this additional user directory
1206 exactly as you would for the default directory.
1207 These directories are completely independent (but read on).
1208 Note that setting the environment variable
1209 \begin_inset Flex CharStyle:Code
1212 \begin_layout Plain Layout
1218 to some value has exactly the same effect.
1221 \begin_layout Standard
1222 Having several configurations also requires more maintenance: if you want
1223 to add a new layout to
1224 \begin_inset Flex CharStyle:Code
1227 \begin_layout Plain Layout
1233 which you want available from all your configurations, you must add it
1234 to each directory separately.
1235 You can avoid this with the following trick: after LyX creates the additional
1236 directory, most of the subdirectories (see above) are empty.
1237 If you want the new configuration to mirror an existing one, replace the
1238 empty subdirectory with a symbolic link to the matching subdirectory in
1239 the existing configuration.
1241 \begin_inset Flex CharStyle:Code
1244 \begin_layout Plain Layout
1250 subdirectory, however, since it contains a file written by the configuration
1251 script (also accessible through
1252 \begin_inset Flex CharStyle:MenuItem
1255 \begin_layout Plain Layout
1256 Tools\SpecialChar \menuseparator
1262 ) which is configuration-specific.
1265 \begin_layout Chapter
1266 The Preferences dialog
1269 \begin_layout Standard
1270 All options of the preferences dialog are described in the Appendix
1272 The Preferences Dialog
1279 For some options you might find here more details.
1282 \begin_layout Section
1284 \begin_inset CommandInset label
1293 \begin_layout Standard
1294 The first step is to define your file formats if they are not already defined.
1296 \begin_inset Flex CharStyle:MenuItem
1299 \begin_layout Plain Layout
1300 Tools\SpecialChar \menuseparator
1308 \begin_inset Flex CharStyle:MenuItem
1311 \begin_layout Plain Layout
1312 File Handling\SpecialChar \menuseparator
1319 \begin_inset Flex CharStyle:MenuItem
1322 \begin_layout Plain Layout
1323 New\SpecialChar \ldots{}
1329 button to define your new format.
1331 \begin_inset Flex CharStyle:MenuItem
1334 \begin_layout Plain Layout
1340 field contains the name used to identify the format in the GUI.
1342 \begin_inset Flex CharStyle:MenuItem
1345 \begin_layout Plain Layout
1351 is used to identify the format internally.
1352 You will also need to enter a file extension.
1353 These are all required.
1355 \begin_inset Flex CharStyle:MenuItem
1358 \begin_layout Plain Layout
1364 field is used to provide a keyboard shortcut on the menus.
1365 (For example, pressing
1366 \begin_inset Flex CharStyle:MenuItem
1369 \begin_layout Plain Layout
1376 \begin_inset Flex CharStyle:MenuItem
1379 \begin_layout Plain Layout
1380 View\SpecialChar \menuseparator
1389 \begin_layout Standard
1391 \begin_inset Flex CharStyle:MenuItem
1394 \begin_layout Plain Layout
1401 \begin_inset Flex CharStyle:MenuItem
1404 \begin_layout Plain Layout
1411 For example, you might want to use
1412 \begin_inset Flex CharStyle:MenuItem
1415 \begin_layout Plain Layout
1421 to view PostScript files.
1422 You can enter the command needed to start the program in the corresponding
1424 In defining this command, you can use the four variables listed in the
1426 The viewer is launched when you view an image in LyX or use the
1427 \begin_inset Flex CharStyle:MenuItem
1430 \begin_layout Plain Layout
1437 The editor is for example launched when you right-click on an image and
1439 \begin_inset Flex CharStyle:MenuItem
1442 \begin_layout Plain Layout
1448 in the appearing context menu.
1451 \begin_layout Standard
1453 \begin_inset Flex CharStyle:MenuItem
1456 \begin_layout Plain Layout
1462 option tells LyX that a format is suitable for document export.
1463 If this is set and if a suitable conversion route exists (see sec.
1464 \begin_inset space \thinspace{}
1468 \begin_inset CommandInset ref
1470 reference "sec:Converters"
1474 ), the format will appear in the
1475 \begin_inset Flex CharStyle:MenuItem
1478 \begin_layout Plain Layout
1479 File\SpecialChar \menuseparator
1486 The format will also appear in the
1487 \begin_inset Flex CharStyle:MenuItem
1490 \begin_layout Plain Layout
1496 menu if a viewer is specified for the format.
1497 Pure image formats, such as
1498 \begin_inset Flex CharStyle:Code
1501 \begin_layout Plain Layout
1507 , should not use this option.
1508 Formats that can both represent vector graphics and documents like
1509 \begin_inset Flex CharStyle:Code
1512 \begin_layout Plain Layout
1521 \begin_layout Standard
1523 \begin_inset Flex CharStyle:MenuItem
1526 \begin_layout Plain Layout
1527 Vector graphics format
1532 tells LyX that a format can contain vector graphics.
1533 This information is used to determine the target format of included graphics
1535 \begin_inset Flex CharStyle:MenuItem
1538 \begin_layout Plain Layout
1545 Included graphics may need to be converted to either
1546 \begin_inset Flex CharStyle:MenuItem
1549 \begin_layout Plain Layout
1556 \begin_inset Flex CharStyle:MenuItem
1559 \begin_layout Plain Layout
1566 \begin_inset Flex CharStyle:MenuItem
1569 \begin_layout Plain Layout
1576 \begin_inset Flex CharStyle:MenuItem
1579 \begin_layout Plain Layout
1585 cannot handle other image formats.
1586 If an included graphic is not already in
1587 \begin_inset Flex CharStyle:MenuItem
1590 \begin_layout Plain Layout
1597 \begin_inset Flex CharStyle:MenuItem
1600 \begin_layout Plain Layout
1607 \begin_inset Flex CharStyle:MenuItem
1610 \begin_layout Plain Layout
1616 format, it is converted to
1617 \begin_inset Flex CharStyle:MenuItem
1620 \begin_layout Plain Layout
1626 if the vector format option is set, and otherwise to
1627 \begin_inset Flex CharStyle:MenuItem
1630 \begin_layout Plain Layout
1639 \begin_layout Section
1643 \begin_layout Standard
1644 Since all conversions from one format to another take place in LyX's temporary
1645 directory, it is sometimes necessary to modify a file before copying it
1646 to the temporary directory in order that the conversion may be performed.
1650 \begin_layout Plain Layout
1651 For example, the file may refer to other files—images, for example—using
1652 relative file names, and these may become invalid when the file is copied
1653 to the temporary directory.
1658 This is done by a Copier: It copies a file to (or from) the temporary directory
1659 and may modify it in the process.
1662 \begin_layout Standard
1663 The definitions of the copiers may use four variables:
1666 \begin_layout Labeling
1667 \labelwidthstring 00.00.0000
1668 \begin_inset Flex CharStyle:Code
1671 \begin_layout Plain Layout
1677 The LyX system directory (e.
1678 \begin_inset space \thinspace{}
1682 \begin_inset space \space{}
1686 \begin_inset Flex CharStyle:MenuItem
1689 \begin_layout Plain Layout
1698 \begin_layout Labeling
1699 \labelwidthstring 00.00.0000
1700 \begin_inset Flex CharStyle:Code
1703 \begin_layout Plain Layout
1712 \begin_layout Labeling
1713 \labelwidthstring 00.00.0000
1714 \begin_inset Flex CharStyle:Code
1717 \begin_layout Plain Layout
1726 \begin_layout Labeling
1727 \labelwidthstring 00.00.0000
1728 \begin_inset Flex CharStyle:Code
1731 \begin_layout Plain Layout
1740 \begin_layout Standard
1741 The latter should be the filename as it would be used in a LaTeX's
1748 It is relevant only when exporting files suitable for such inclusion.
1751 \begin_layout Standard
1752 Copiers can be used to do almost anything with output files.
1753 For example, suppose you want generated pdf files to be copied to a special
1755 \begin_inset Flex CharStyle:Code
1758 \begin_layout Plain Layout
1765 Then you could write a shell script such as this one:
1768 \begin_layout Standard
1769 \begin_inset listings
1773 \begin_layout Plain Layout
1778 \begin_layout Plain Layout
1783 \begin_layout Plain Layout
1785 TOFILE=`basename $2`
1788 \begin_layout Plain Layout
1790 cp $FROMFILE /home/you/pdf/$TOFILE
1795 Save it in your local LyX directory—say,
1796 \begin_inset Flex CharStyle:Code
1799 \begin_layout Plain Layout
1800 /home/you/.lyx/scripts/pdfcopier.sh
1805 —and make it executable, if you need to do so on your platform.
1807 \begin_inset Flex CharStyle:MenuItem
1810 \begin_layout Plain Layout
1811 Tools\SpecialChar \menuseparator
1817 dialog, select under
1818 \begin_inset Flex CharStyle:MenuItem
1821 \begin_layout Plain Layout
1822 File Handling\SpecialChar \menuseparator
1829 \begin_inset Flex CharStyle:MenuItem
1832 \begin_layout Plain Layout
1838 format—or one of the other pdf formats—and enter
1839 \begin_inset Flex CharStyle:Code
1842 \begin_layout Plain Layout
1843 pdfcopier.sh $$i $$o
1849 \begin_inset Flex CharStyle:MenuItem
1852 \begin_layout Plain Layout
1862 \begin_layout Standard
1863 Copiers are used by LyX in various of its own conversions.
1864 For example, if appropriate programs are found, LyX will automatically
1865 install copiers for the
1866 \begin_inset Flex CharStyle:MenuItem
1869 \begin_layout Plain Layout
1876 \begin_inset Flex CharStyle:MenuItem
1879 \begin_layout Plain Layout
1881 \begin_inset space ~
1890 When these formats are exported, the copier sees that not just the main
1891 HTML file but various associated files (style files, images, etc.) are also
1893 All these files are written to a subdirectory of the directory in which
1894 the original LyX file was found.
1898 \begin_layout Plain Layout
1899 This copier can be customized.
1901 \begin_inset Quotes eld
1905 \begin_inset Quotes erd
1908 argument takes a comma-separated list of extensions to be copied; if it
1909 is omitted, all files will be copied.
1911 \begin_inset Quotes eld
1915 \begin_inset Quotes erd
1918 argument determines the extension added to the generated directory.
1920 \begin_inset Quotes eld
1924 \begin_inset Flex CharStyle:MenuItem
1927 \begin_layout Plain Layout
1934 \begin_inset Quotes erd
1937 , so HTML generated from
1938 \begin_inset Flex CharStyle:MenuItem
1941 \begin_layout Plain Layout
1942 /path/to/filename.lyx
1948 \begin_inset Flex CharStyle:MenuItem
1951 \begin_layout Plain Layout
1952 /path/to/filename.html.LyXconv
1966 \begin_layout Section
1968 \begin_inset CommandInset label
1970 name "sec:Converters"
1977 \begin_layout Standard
1978 You can define your own Converters to convert files between different formats.
1980 \begin_inset Flex CharStyle:MenuItem
1983 \begin_layout Plain Layout
1984 Tools\SpecialChar \menuseparator
1985 Preferences\SpecialChar \menuseparator
1986 File Handling\SpecialChar \menuseparator
1995 \begin_layout Standard
1996 To define a new converter, select the
1997 \begin_inset Flex CharStyle:MenuItem
2000 \begin_layout Plain Layout
2002 \begin_inset space ~
2011 \begin_inset Flex CharStyle:MenuItem
2014 \begin_layout Plain Layout
2016 \begin_inset space ~
2024 from the drop-down lists, enter the command needed for the conversion,
2026 \begin_inset Flex CharStyle:MenuItem
2029 \begin_layout Plain Layout
2036 Several variables can be used in the definition of converters:
2039 \begin_layout Labeling
2040 \labelwidthstring 00.00.0000
2041 \begin_inset Flex CharStyle:Code
2044 \begin_layout Plain Layout
2050 The LyX system directory
2053 \begin_layout Labeling
2054 \labelwidthstring 00.00.0000
2055 \begin_inset Flex CharStyle:Code
2058 \begin_layout Plain Layout
2067 \begin_layout Labeling
2068 \labelwidthstring 00.00.0000
2069 \begin_inset Flex CharStyle:Code
2072 \begin_layout Plain Layout
2081 \begin_layout Labeling
2082 \labelwidthstring 00.00.0000
2083 \begin_inset Flex CharStyle:Code
2086 \begin_layout Plain Layout
2092 The base filename of the input file (i.
2093 \begin_inset space \thinspace{}
2096 g., without the extension)
2099 \begin_layout Labeling
2100 \labelwidthstring 00.00.0000
2101 \begin_inset Flex CharStyle:Code
2104 \begin_layout Plain Layout
2110 The path to the input file
2113 \begin_layout Labeling
2114 \labelwidthstring 00.00.0000
2115 \begin_inset Flex CharStyle:Code
2118 \begin_layout Plain Layout
2124 The path to the original input file (this is different from $$p when a
2125 chain of converters is called).
2128 \begin_layout Standard
2130 \begin_inset Flex CharStyle:MenuItem
2133 \begin_layout Plain Layout
2135 \begin_inset space ~
2143 field you can enter the following flags, separated by commas:
2146 \begin_layout Labeling
2147 \labelwidthstring 00.00.0000
2148 \begin_inset Flex CharStyle:Code
2151 \begin_layout Plain Layout
2157 This converter runs some form of LaTeX.
2158 This will make LyX's LaTeX error logs available.
2161 \begin_layout Labeling
2162 \labelwidthstring 00.00.0000
2163 \begin_inset Flex CharStyle:Code
2166 \begin_layout Plain Layout
2173 \begin_inset Flex CharStyle:MenuItem
2176 \begin_layout Plain Layout
2182 file for the conversion.
2185 \begin_layout Labeling
2186 \labelwidthstring 00.00.0000
2187 \begin_inset Flex CharStyle:Code
2190 \begin_layout Plain Layout
2199 \begin_layout Standard
2200 The following three flags are not really flags at all because they take
2202 \begin_inset Flex CharStyle:MenuItem
2205 \begin_layout Plain Layout
2207 \begin_inset space ~
2211 \begin_inset space ~
2222 \begin_layout Labeling
2223 \labelwidthstring 00.00.0000
2224 \begin_inset Flex CharStyle:Code
2227 \begin_layout Plain Layout
2233 If set, the converter's standard error will be redirected to a file
2234 \begin_inset Flex CharStyle:Code
2237 \begin_layout Plain Layout
2243 , and the script given as argument will be run as:
2244 \begin_inset Flex CharStyle:Code
2247 \begin_layout Plain Layout
2248 script < infile.out > infile.log
2254 The argument may contain
2255 \begin_inset Flex CharStyle:Code
2258 \begin_layout Plain Layout
2267 \begin_layout Labeling
2268 \labelwidthstring 00.00.0000
2269 \begin_inset Flex CharStyle:Code
2272 \begin_layout Plain Layout
2278 The name of the directory in which the converter will dump the generated
2280 LyX will not create this directory, and it does not copy anything into
2281 it, though it will copy this directory to the destination.
2282 The argument may contain
2283 \begin_inset Flex CharStyle:Code
2286 \begin_layout Plain Layout
2292 , which will be replaced by the base name of the input and output files,
2293 respectively, when the directory is copied.
2294 \begin_inset Newline newline
2297 Note that resultdir and usetempdir make no sense together.
2298 The latter will be ignored if the former is given.
2301 \begin_layout Labeling
2302 \labelwidthstring 00.00.0000
2303 \begin_inset Flex CharStyle:Code
2306 \begin_layout Plain Layout
2312 Determines the output file name and may, contain
2313 \begin_inset Flex CharStyle:Code
2316 \begin_layout Plain Layout
2323 Sensible only with resultdir and optional even then; if not given, it defaults
2327 \begin_layout Standard
2328 None of these last three are presently used in any of the converters that
2329 are installed with LyX.
2333 \begin_layout Standard
2334 You do not have to define converters for all formats between which you want
2336 For example, you will note that there is no `LyX to PostScript' converter,
2337 but LyX will export PostScript.
2338 It does so by first creating a LaTeX file (no converter needs to be defined
2339 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2340 and finally converting the resulting DVI file to PostScript.
2341 LyX finds such `chains' of converters automatically, and it will always
2342 choose the shortest possible chain.
2343 You can, though, still define multiple conversion methods between file
2345 For example, the standard LyX configuration provides three ways to convert
2346 LaTeX to PDF: Directly, using
2347 \begin_inset Flex CharStyle:MenuItem
2350 \begin_layout Plain Layout
2356 ; via (DVI and) PostScript, using
2357 \begin_inset Flex CharStyle:MenuItem
2360 \begin_layout Plain Layout
2367 \begin_inset Flex CharStyle:MenuItem
2370 \begin_layout Plain Layout
2377 To define such alternate chains, you must define multiple target `file
2378 formats', as described in section
2379 \begin_inset CommandInset ref
2381 reference "sec:Formats"
2386 For example, in the standard configuration, the formats named
2387 \begin_inset Flex CharStyle:MenuItem
2390 \begin_layout Plain Layout
2397 \begin_inset Flex CharStyle:MenuItem
2400 \begin_layout Plain Layout
2407 \begin_inset Flex CharStyle:MenuItem
2410 \begin_layout Plain Layout
2416 are defined, all of which share the extension
2417 \begin_inset Flex CharStyle:MenuItem
2420 \begin_layout Plain Layout
2426 , and which correspond to the conversion methods just mentioned.
2429 \begin_layout Chapter
2430 Internationalizing LyX
2431 \begin_inset CommandInset label
2433 name "cha:Internationalizing-LyX"
2440 \begin_layout Standard
2441 LyX supports using a translated interface.
2442 Last time we checked, LyX provided text in thirty languages.
2443 The language of choice is called your
2448 (For further reading on locale settings, see also the documentation for
2449 locale that comes with your operating system.
2450 For Linux, the manual page for
2451 \begin_inset Flex CharStyle:Code
2454 \begin_layout Plain Layout
2460 could be a good place to start).
2463 \begin_layout Standard
2464 Notice that these translations will work, but do contain a few flaws.
2465 In particular, all dialogs have been designed with the English text in
2466 mind, which means that some of the translated text will be too large to
2467 fit within the space allocated.
2468 This is only a display problem and will not cause any harm.
2469 Also, you will find that some of the translations do not define shortcut
2470 keys for everything.
2471 Sometimes, there are simply not enough free letters to do it.
2472 Other times, the translator just hasn't got around to doing it yet.
2473 Our localization team, which you may wish to join,
2477 \begin_layout Plain Layout
2478 If you are a fluent speaker of a language other than English, joining these
2479 teams is a great way to give back to the LyX community!
2484 will of course try to fix these shortcomings in future versions of LyX.
2487 \begin_layout Section
2491 \begin_layout Subsection
2492 Translating the graphical user interface (text messages).
2495 \begin_layout Standard
2497 \begin_inset Flex CharStyle:Code
2500 \begin_layout Plain Layout
2506 library to handle the internationalization of the interface.
2507 To have LyX speak your favorite language in all menus and dialogs, you
2509 \begin_inset Flex CharStyle:Code
2512 \begin_layout Plain Layout
2518 -file for that language.
2519 When this is available, you'll have to generate a
2520 \begin_inset Flex CharStyle:Code
2523 \begin_layout Plain Layout
2529 -file from it and install the
2530 \begin_inset Flex CharStyle:Code
2533 \begin_layout Plain Layout
2540 The process of doing all of this is explained in the documentation for
2542 \begin_inset Flex CharStyle:Code
2545 \begin_layout Plain Layout
2552 It is possible to do this just for yourself, but if you're going to do
2553 it, you might as well share the results of your labors with the rest of
2555 Send a message to the LyX developers' list for more information about how
2559 \begin_layout Standard
2560 In short, this is what you should do (xx denotes the language code):
2563 \begin_layout Itemize
2564 Check out the LyX source code.
2566 \begin_inset CommandInset href
2568 name "information on the web"
2569 target "http://www.lyx.org/devel/cvs.php"
2576 \begin_layout Itemize
2578 \begin_inset Flex CharStyle:Code
2581 \begin_layout Plain Layout
2587 to the folder of the
2588 \begin_inset Flex CharStyle:Code
2591 \begin_layout Plain Layout
2599 \begin_inset Flex CharStyle:Code
2602 \begin_layout Plain Layout
2610 \begin_inset Flex CharStyle:Code
2613 \begin_layout Plain Layout
2619 doesn't exist anywhere, it can be remade with the console command
2620 \begin_inset Flex CharStyle:Code
2623 \begin_layout Plain Layout
2629 in that directory, or you can use an existing po-file for some other language
2633 \begin_layout Itemize
2635 \begin_inset Flex CharStyle:Code
2638 \begin_layout Plain Layout
2648 \begin_layout Plain Layout
2649 This is just a text file, so it can be edited in any text editor.
2650 But there are also specialized programs that support such editing, such
2655 (for all platforms) or
2664 contains a `mode' for editing
2665 \begin_inset Flex CharStyle:Code
2668 \begin_layout Plain Layout
2679 For some menu- and widget-labels, there are also shortcut keys that should
2681 Those keys are marked after a `|', and should be translated according to
2682 the words and phrases of the language.
2683 You should also fill also out the information at the beginning of the new
2685 \begin_inset Flex CharStyle:Code
2688 \begin_layout Plain Layout
2694 -file with your email-address, etc., so people know where to reach you with
2695 suggestions and entertaining flames.
2698 \begin_layout Standard
2699 If you are just doing this on your own, then:
2702 \begin_layout Itemize
2704 \begin_inset Flex CharStyle:Code
2707 \begin_layout Plain Layout
2714 This can be done with
2715 \begin_inset Flex CharStyle:Code
2718 \begin_layout Plain Layout
2719 msgfmt -o xx.mo < xx.po
2727 \begin_layout Itemize
2729 \begin_inset Flex CharStyle:Code
2732 \begin_layout Plain Layout
2738 -file to your locale-tree, at the correct directory for application messages
2743 xx, and under the name
2744 \begin_inset Flex CharStyle:Code
2747 \begin_layout Plain Layout
2754 \begin_inset space \thinspace{}
2758 \begin_inset space \space{}
2762 \begin_inset Flex CharStyle:Code
2765 \begin_layout Plain Layout
2766 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2776 \begin_layout Standard
2777 As said, however, it would be best if the new
2778 \begin_inset Flex CharStyle:Code
2781 \begin_layout Plain Layout
2787 -file could be added to the LyX distribution, so others can use it.
2788 Adding it involves making additional changes to LyX.
2789 So send an email to the developers' mailing list if you're interested in
2793 \begin_layout Subsubsection
2797 \begin_layout Standard
2798 Sometimes it turns out that one English message needs to be translated into
2799 different messages in the target language.
2800 One example is the message
2801 \begin_inset Flex CharStyle:Code
2804 \begin_layout Plain Layout
2810 which has the German translation
2818 , depending upon exactly what the English
2819 \begin_inset Quotes eld
2823 \begin_inset Quotes erd
2828 \begin_inset Flex CharStyle:Code
2831 \begin_layout Plain Layout
2837 does not handle such ambiguous translations.
2838 Therefore you have to add some context information to the message: Instead
2840 \begin_inset Flex CharStyle:Code
2843 \begin_layout Plain Layout
2850 \begin_inset Flex CharStyle:Code
2853 \begin_layout Plain Layout
2854 To[[as in 'From format x to format y']]
2860 \begin_inset Flex CharStyle:Code
2863 \begin_layout Plain Layout
2864 To[[as in 'From page x to page y']].
2869 Now the two occurrences of
2870 \begin_inset Flex CharStyle:Code
2873 \begin_layout Plain Layout
2880 \begin_inset Flex CharStyle:Code
2883 \begin_layout Plain Layout
2889 and can be translated correctly to
2900 \begin_layout Standard
2901 Of course the context information needs to be stripped off the original
2902 message when no translation is used.
2903 Therefore you have to put it in double square brackets at the end of the
2904 message (see the example above).
2905 The translation mechanism of LyX ensures that everything in double square
2906 brackets at the end of messages is removed before displaying the message.
2909 \begin_layout Subsection
2910 Translating the documentation.
2913 \begin_layout Standard
2914 The online documentation (in the
2915 \begin_inset Flex CharStyle:MenuItem
2918 \begin_layout Plain Layout
2924 -menu) can (and should!) be translated.
2925 If there are translated versions of the documentation available
2929 \begin_layout Plain Layout
2930 As of March 2008, at least some of the documents have been translated into
2931 fourteen languages, with the Tutorial available in a few more.
2936 and the locale is set accordingly, these will be used automagically by
2938 LyX looks for translated versions as
2939 \begin_inset Flex CharStyle:Code
2942 \begin_layout Plain Layout
2943 LyXDir/doc/xx/DocName.lyx
2949 \begin_inset Flex CharStyle:Code
2952 \begin_layout Plain Layout
2958 is the code for the language currently in use.
2959 If there are no translated documents, the default English versions will
2961 Note that the translated versions must have the same filenames (
2962 \begin_inset Flex CharStyle:Code
2965 \begin_layout Plain Layout
2971 above) as the original.
2972 If you feel up to translating the documentation (an excellent way to proof-read
2973 the original documentation by the way!), there are a few things you should
2977 \begin_layout Itemize
2978 Check out the documentation translation web page at
2979 \begin_inset CommandInset href
2981 name "http://www.lyx.org/Translation"
2982 target "http://www.lyx.org/Translation"
2987 That way, you can find out which (if any) documents have already been translate
2988 d into your language.
2989 You can also find out who (if anyone) is organizing the effort to translate
2990 the documentation into your language.
2991 If no one is organizing the effort, please let us know that you're interested.
2994 \begin_layout Standard
2995 Once you get to actually translating, here's a few hints for you that may
2999 \begin_layout Itemize
3000 Join the documentation team! There is information on how to do that in
3001 \begin_inset Flex CharStyle:Code
3004 \begin_layout Plain Layout
3011 \begin_inset Flex CharStyle:MenuItem
3014 \begin_layout Plain Layout
3015 Help\SpecialChar \menuseparator
3021 ), which by the way is the first document you should translate.
3024 \begin_layout Itemize
3025 Learn the typographic conventions for the language you are translating to.
3026 Typography is an ancient art and over the centuries, a great variety of
3027 conventions have developed throughout different parts of the world.
3028 Also study the professional terminology amongst typographers in your country.
3029 Inventing your own terminology will only confuse the users.
3032 (Warning! Typography is addictive!)
3035 \begin_layout Itemize
3036 Make a copy of the document.
3037 This will be your working copy.
3038 You can use this as your personal translated help-file by placing it in
3040 \begin_inset Flex CharStyle:Code
3043 \begin_layout Plain Layout
3052 \begin_layout Itemize
3053 Sometimes the original document (from the LyX-team) will be updated.
3054 Use the source viewer at
3055 \begin_inset CommandInset href
3057 name "http://www.lyx.org/trac/timeline"
3058 target "http://www.lyx.org/trac/timeline"
3062 to see what has been changed.
3063 That way you can easily see which parts of the translated document need
3067 \begin_layout Standard
3068 If you ever find an error in the original document, fix it and notify the
3069 rest of the documentation team of the changes! (You didn't forget to join
3070 the documentation team, did you?)
3073 \begin_layout Standard
3074 \begin_inset Branch OutDated
3077 \begin_layout Section
3078 International Keyboard Support
3081 \begin_layout Standard
3084 [Editor's Note: The following section is by
3092 It needs to be fixed to conform to the new Documentation Style sheet and
3093 to make use of the new v1.0 features.
3094 The whole thing also needs to be merged with the section following it.-jw
3095 It may also be badly out of date.-rh (2008)]
3098 \begin_layout Subsection
3099 Defining Own Keymaps: Keymap File Format
3102 \begin_layout Standard
3103 Let's look at a keyboard definition file a little closer.
3104 It is a plain text file defining
3107 \begin_layout Itemize
3108 key-to-key or key-to-string translations
3111 \begin_layout Itemize
3115 \begin_layout Itemize
3116 dead keys exceptions
3119 \begin_layout Standard
3120 To define key-to-key or key-to-string translation, use this command:
3123 \begin_layout Quotation
3124 \begin_inset Flex CharStyle:Code
3127 \begin_layout Plain Layout
3136 \begin_inset Flex CharStyle:Code
3139 \begin_layout Plain Layout
3148 \begin_layout Standard
3150 \begin_inset Flex CharStyle:Code
3153 \begin_layout Plain Layout
3159 is the key to be translated and
3160 \begin_inset Flex CharStyle:Code
3163 \begin_layout Plain Layout
3169 is the string to be inserted into the document.
3170 To define dead keys, use:
3173 \begin_layout Quotation
3174 \begin_inset Flex CharStyle:Code
3177 \begin_layout Plain Layout
3186 \begin_inset Flex CharStyle:Code
3189 \begin_layout Plain Layout
3198 \begin_layout Standard
3200 \begin_inset Flex CharStyle:Code
3203 \begin_layout Plain Layout
3209 is a keyboard key and
3210 \begin_inset Flex CharStyle:Code
3213 \begin_layout Plain Layout
3220 The following dead keys are supported (shortcut name is in parentheses):
3223 \begin_layout Quotation
3227 \begin_inset space \hfill{}
3233 \begin_layout Quotation
3235 \begin_inset space \hfill{}
3241 \begin_layout Quotation
3243 \begin_inset space \hfill{}
3249 \begin_layout Quotation
3251 \begin_inset space \hfill{}
3257 \begin_layout Quotation
3259 \begin_inset space \hfill{}
3265 \begin_layout Quotation
3267 \begin_inset space \hfill{}
3274 \begin_layout Plain Layout
3286 \begin_layout Quotation
3288 \begin_inset space \hfill{}
3294 \begin_layout Quotation
3296 \begin_inset space \hfill{}
3303 \begin_layout Plain Layout
3315 \begin_layout Quotation
3317 \begin_inset space \hfill{}
3323 \begin_layout Quotation
3325 \begin_inset space \hfill{}
3331 \begin_layout Quotation
3333 \begin_inset space \hfill{}
3340 \begin_layout Plain Layout
3352 \begin_layout Quotation
3354 \begin_inset space \hfill{}
3361 \begin_layout Plain Layout
3373 \begin_layout Quotation
3375 \begin_inset space \hfill{}
3381 \begin_layout Quotation
3382 hungarian umlaut (hug)
3383 \begin_inset space \hfill{}
3389 \begin_layout Quotation
3391 \begin_inset space \hfill{}
3397 \begin_layout Quotation
3399 \begin_inset space \hfill{}
3406 \begin_layout Plain Layout
3418 \begin_layout Standard
3419 Since in many international keyboards there are exceptions to what some
3420 dead keys should do, you can define them using
3423 \begin_layout Quotation
3424 \begin_inset Flex CharStyle:Code
3427 \begin_layout Plain Layout
3435 deadkey key outstring
3438 \begin_layout Standard
3439 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3443 \begin_layout Quotation
3444 \begin_inset Flex CharStyle:Code
3447 \begin_layout Plain Layout
3460 \begin_layout Standard
3461 to make it work correctly.
3462 Also, you have to define as exceptions dead keys over i and j, to remove
3463 the dot from them before inserting an accent mark.
3464 I will change this when the time comes, but so far I haven't had time.
3467 \begin_layout Standard
3468 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3471 \begin_inset Flex CharStyle:Code
3474 \begin_layout Plain Layout
3480 have different meaning.
3482 \begin_inset Flex CharStyle:Code
3485 \begin_layout Plain Layout
3491 marks comments, quotes start and end LaTeX-style commands.
3492 To enter quote, you'll need to use
3493 \begin_inset Flex CharStyle:Code
3496 \begin_layout Plain Layout
3505 \begin_inset Flex CharStyle:Code
3508 \begin_layout Plain Layout
3515 \begin_inset Flex CharStyle:Code
3518 \begin_layout Plain Layout
3529 \begin_layout Standard
3530 If you make a keyboard description file that works for your language, please
3531 mail it to me, so I can include it in the next keymap distribution.
3534 \begin_layout Standard
3535 More keywords will be supported in keymap configuration file in future,
3539 \begin_layout Itemize
3540 \begin_inset Flex CharStyle:Code
3543 \begin_layout Plain Layout
3554 \begin_inset space \hfill{}
3558 \begin_inset Flex CharStyle:Code
3561 \begin_layout Plain Layout
3570 \begin_layout Itemize
3571 \begin_inset Flex CharStyle:Code
3574 \begin_layout Plain Layout
3585 \begin_inset space \hfill{}
3589 \begin_inset Flex CharStyle:Code
3592 \begin_layout Plain Layout
3598 an external keymap translation program
3601 \begin_layout Standard
3602 Also, it should look into
3603 \begin_inset Flex CharStyle:Code
3606 \begin_layout Plain Layout
3612 file for defaults, too (for example, a
3613 \begin_inset Flex CharStyle:Code
3616 \begin_layout Plain Layout
3624 option to include default keyboard).
3632 \begin_layout Section
3633 International Keymap Stuff
3634 \begin_inset CommandInset label
3636 name "sec:International-Keymap-Stuff"
3643 \begin_layout Standard
3644 \begin_inset Note Note
3647 \begin_layout Plain Layout
3648 In doing the revisions on this document in March 2008, I did not look over
3649 this stuff, as I do not understand it.
3650 It would be good if someone else could do so.
3659 \begin_layout Standard
3660 The next two sections describe the
3661 \begin_inset Flex CharStyle:Code
3664 \begin_layout Plain Layout
3673 \begin_inset Flex CharStyle:Code
3676 \begin_layout Plain Layout
3684 file syntax in detail.
3685 These sections should help you design your own key map if the ones provided
3686 do not meet your needs.
3689 \begin_layout Subsection
3693 \begin_layout Standard
3697 \begin_inset Flex CharStyle:Code
3700 \begin_layout Plain Layout
3706 file maps keystrokes to characters or strings.
3707 As the name suggests, it sets a keyboard mapping.
3709 \begin_inset Flex CharStyle:Code
3712 \begin_layout Plain Layout
3723 \begin_inset Flex CharStyle:Code
3726 \begin_layout Plain Layout
3741 \begin_inset Flex CharStyle:Code
3744 \begin_layout Plain Layout
3757 \begin_inset Flex CharStyle:Code
3760 \begin_layout Plain Layout
3769 \begin_inset Flex CharStyle:Code
3772 \begin_layout Plain Layout
3780 are described in this section.
3783 \begin_layout Labeling
3784 \labelwidthstring 00.00.0000
3785 \begin_inset Flex CharStyle:Code
3788 \begin_layout Plain Layout
3796 Map a character to a string
3799 \begin_layout LyX-Code
3814 \begin_layout Standard
3847 the double-quote (")
3864 must be escaped with a preceding backslash (
3875 \begin_layout Standard
3877 \begin_inset Flex CharStyle:MenuItem
3880 \begin_layout Plain Layout
3888 statement to cause the symbol
3889 \begin_inset Flex CharStyle:MenuItem
3892 \begin_layout Plain Layout
3900 to be output for the keystroke
3901 \begin_inset Flex CharStyle:MenuItem
3904 \begin_layout Plain Layout
3915 \begin_layout LyX-Code
3921 \begin_layout Labeling
3922 \labelwidthstring 00.00.0000
3923 \begin_inset Flex CharStyle:Code
3926 \begin_layout Plain Layout
3934 Specify an accent character
3937 \begin_layout LyX-Code
3946 \begin_layout Standard
3947 This will make the cha
3985 This is the dead key
3989 \begin_layout Plain Layout
3996 refers to a key that does not produce a character by itself, but when followed
3997 with another key, produces the desired accent character.
3998 For example, a German characte
4000 r with an umlaut like
4010 can be produced in this manner.
4019 \begin_layout Standard
4032 and then another key not in
4049 followed by the other, not allowed key, as output.
4053 \begin_inset Flex CharStyle:MenuItem
4056 \begin_layout Plain Layout
4064 cancels a dead key, so if
4075 \begin_inset Flex CharStyle:MenuItem
4078 \begin_layout Plain Layout
4087 , the cursor will not go one position backwards but will instead cancel
4103 might have had on the next keystroke.
4107 \begin_layout Standard
4108 The following example specifies that the character ' is to be an acute accent,
4109 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4112 \begin_layout LyX-Code
4115 kmod ' acute aeiouAEIOU
4118 \begin_layout Labeling
4119 \labelwidthstring 00.00.0000
4120 \begin_inset Flex CharStyle:Code
4123 \begin_layout Plain Layout
4129 Specify an exception to the accent character
4132 \begin_layout LyX-Code
4141 \begin_layout Standard
4142 This defines an exce
4183 have been assigned a keystroke with a previous
4186 \begin_inset Flex CharStyle:Code
4189 \begin_layout Plain Layout
4213 must not belong in the
4260 If such a declaration does not exist in
4268 \begin_inset Flex CharStyle:Code
4271 \begin_layout Plain Layout
4305 \begin_inset Flex CharStyle:Code
4308 \begin_layout Plain Layout
4322 \begin_layout Standard
4323 The following command produces causes äi to be produced when you enter acute-i
4327 \begin_layout LyX-Code
4341 \begin_layout Labeling
4342 \labelwidthstring 00.00.0000
4343 \begin_inset Flex CharStyle:Code
4346 \begin_layout Plain Layout
4352 Combine two accent characters
4355 \begin_layout LyX-Code
4361 accent1 accent2 allowed
4364 \begin_layout Standard
4365 This one is getting pretty esoteric.
4366 It allows you to combine the effect
4422 \begin_inset Flex CharStyle:Code
4425 \begin_layout Plain Layout
4453 \begin_layout Standard
4454 Consider this example from the
4455 \begin_inset Flex CharStyle:Code
4458 \begin_layout Plain Layout
4469 \begin_layout LyX-Code
4472 kmod ; acute aeioyvhAEIOYVH
4476 kcomb acute umlaut iyIY
4479 \begin_layout Standard
4480 This allows you to press
4481 \begin_inset Flex CharStyle:MenuItem
4484 \begin_layout Plain Layout
4492 and get the effect of
4493 \begin_inset Flex CharStyle:Code
4496 \begin_layout Plain Layout
4515 in this case cancels the last dead key, so if you press
4516 \begin_inset Flex CharStyle:MenuItem
4519 \begin_layout Plain Layout
4528 \begin_inset Flex CharStyle:Code
4531 \begin_layout Plain Layout
4544 \begin_layout Subsection
4548 \begin_layout Standard
4550 \begin_inset Flex CharStyle:Code
4553 \begin_layout Plain Layout
4561 mapping is performed, a
4562 \begin_inset Flex CharStyle:Code
4565 \begin_layout Plain Layout
4575 file maps the strings that the symbols generate to characters in the current
4577 The LyX distribution currently includes at least the
4578 \begin_inset Flex CharStyle:Code
4581 \begin_layout Plain Layout
4590 \begin_inset Flex CharStyle:Code
4593 \begin_layout Plain Layout
4604 \begin_layout Standard
4606 \begin_inset Flex CharStyle:Code
4609 \begin_layout Plain Layout
4617 file is a sequence of declarations of the form
4620 \begin_layout LyX-Code
4633 \begin_layout Standard
4634 For example, in order to map
4635 \begin_inset Flex CharStyle:MenuItem
4638 \begin_layout Plain Layout
4648 to the corresponding character in the iso-8859-1 set (233), the following
4652 \begin_layout LyX-Code
4660 \begin_layout Standard
4662 \begin_inset Flex CharStyle:Code
4665 \begin_layout Plain Layout
4674 \begin_inset Flex CharStyle:Code
4677 \begin_layout Plain Layout
4695 the same character can apply to more than one string.
4697 \begin_inset Flex CharStyle:Code
4700 \begin_layout Plain Layout
4711 \begin_layout LyX-Code
4723 \begin_inset Newline newline
4739 \begin_layout Standard
4740 If LyX cannot find a mapping for the string produced by the keystroke or
4741 a deadkey sequence, it will check if it looks like an accented char and
4742 try to draw an accent over the character on screen.
4745 \begin_layout Subsection
4749 \begin_layout Standard
4750 There is a second way to add support for international characters through
4751 so-called dead-keys.
4752 A dead-key works in combination with a letter to produce an accented character.
4753 Here, we'll explain how to create a really simple dead-key to illustrate
4757 \begin_layout Standard
4758 Suppose you happen to need the circumflex character,
4759 \begin_inset Quotes eld
4763 \begin_inset Quotes erd
4768 \begin_inset Flex CharStyle:MenuItem
4771 \begin_layout Plain Layout
4778 \begin_inset space ~
4782 \begin_inset Flex CharStyle:MenuItem
4785 \begin_layout Plain Layout
4791 ] to the LyX command
4792 \begin_inset Flex CharStyle:Code
4795 \begin_layout Plain Layout
4802 \begin_inset Flex CharStyle:Code
4805 \begin_layout Plain Layout
4812 Now, whenever you type the
4813 \begin_inset Flex CharStyle:MenuItem
4816 \begin_layout Plain Layout
4822 -key followed by a letter, that letter will have a circumflex accent on
4824 For example, the sequence
4825 \begin_inset Quotes eld
4829 \begin_inset Flex CharStyle:MenuItem
4832 \begin_layout Plain Layout
4839 \begin_inset Quotes erd
4842 produces the letter:
4843 \begin_inset Quotes eld
4847 \begin_inset Quotes erd
4851 If you tried to type
4852 \begin_inset Quotes eld
4856 \begin_inset Flex CharStyle:MenuItem
4859 \begin_layout Plain Layout
4866 \begin_inset Quotes erd
4869 , however, LyX will complain with a beep, since a
4870 \begin_inset Quotes eld
4874 \begin_inset Flex CharStyle:MenuItem
4877 \begin_layout Plain Layout
4884 \begin_inset Quotes erd
4887 never takes a circumflex accent.
4889 \begin_inset Flex CharStyle:MenuItem
4892 \begin_layout Plain Layout
4898 after a dead-key produces the bare-accent.
4899 Please note this last point! If you bind a key to a dead-key, you'll need
4900 to rebind the character on that key to yet another key.
4902 \begin_inset Flex CharStyle:MenuItem
4905 \begin_layout Plain Layout
4911 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4914 \begin_layout Standard
4915 One common way to bind dead-keys is to use
4916 \begin_inset Flex CharStyle:MenuItem
4919 \begin_layout Plain Layout
4926 \begin_inset Flex CharStyle:MenuItem
4929 \begin_layout Plain Layout
4936 \begin_inset Flex CharStyle:MenuItem
4939 \begin_layout Plain Layout
4945 in combination with an accent, like
4946 \begin_inset Quotes eld
4950 \begin_inset Flex CharStyle:MenuItem
4953 \begin_layout Plain Layout
4960 \begin_inset Quotes erd
4964 \begin_inset Quotes eld
4968 \begin_inset Flex CharStyle:MenuItem
4971 \begin_layout Plain Layout
4978 \begin_inset Quotes erd
4982 \begin_inset Quotes eld
4986 \begin_inset Flex CharStyle:MenuItem
4989 \begin_layout Plain Layout
4996 \begin_inset Quotes erd
5000 Another way involves using
5001 \begin_inset Flex CharStyle:Code
5004 \begin_layout Plain Layout
5011 \begin_inset Flex CharStyle:Code
5014 \begin_layout Plain Layout
5020 to set up the special
5021 \begin_inset Flex CharStyle:Code
5024 \begin_layout Plain Layout
5032 \begin_inset Flex CharStyle:Code
5035 \begin_layout Plain Layout
5041 acts in some ways just like
5042 \begin_inset Flex CharStyle:MenuItem
5045 \begin_layout Plain Layout
5051 and permits you to bind keys to accented characters.
5052 You can also turn keys into dead-keys by binding them to something like
5054 \begin_inset Flex CharStyle:Code
5057 \begin_layout Plain Layout
5063 and then binding this symbolic key to the corresponding LyX command.
5067 \begin_layout Plain Layout
5072 : This is exactly what I do in my
5073 \begin_inset Flex CharStyle:Code
5076 \begin_layout Plain Layout
5083 \begin_inset Flex CharStyle:Code
5086 \begin_layout Plain Layout
5094 \begin_inset Flex CharStyle:MenuItem
5097 \begin_layout Plain Layout
5099 \begin_inset space ~
5108 \begin_inset Flex CharStyle:Code
5111 \begin_layout Plain Layout
5117 and a bunch of these
5118 \begin_inset Quotes eld
5122 \begin_inset Flex CharStyle:Code
5125 \begin_layout Plain Layout
5132 \begin_inset Quotes erd
5135 symbolic keys bound such things as
5136 \begin_inset Flex CharStyle:MenuItem
5139 \begin_layout Plain Layout
5141 \begin_inset space ~
5150 \begin_inset Flex CharStyle:MenuItem
5153 \begin_layout Plain Layout
5155 \begin_inset space ~
5164 This is how I produce my accented characters.
5169 You can make just about anything into the
5170 \begin_inset Flex CharStyle:Code
5173 \begin_layout Plain Layout
5180 \begin_inset Flex CharStyle:MenuItem
5183 \begin_layout Plain Layout
5189 keys, a spare function key, etc.
5190 As for the LyX commands that produce accents, check the entry for
5191 \begin_inset Flex CharStyle:Code
5194 \begin_layout Plain Layout
5205 You'll find the complete list there.
5208 \begin_layout Subsection
5209 Saving your Language Configuration
5212 \begin_layout Standard
5213 You can edit your preferences so that your desired language environment
5214 is automatically configured when LyX starts up, via the
5215 \begin_inset Flex CharStyle:MenuItem
5218 \begin_layout Plain Layout
5219 Edit\SpecialChar \menuseparator
5228 \begin_layout Chapter
5229 Installing New Document Classes, Layouts, and Templates
5230 \begin_inset CommandInset label
5232 name "cha:Installing-New-Document"
5240 \begin_layout Plain Layout
5241 Installing New Document Classes
5249 \begin_layout Standard
5250 In this chapter, we describe the procedures for creating and installing
5251 new LyX layout and template files, as well as offer a refresher on correctly
5252 installing new LaTeX document classes.
5253 Some definitions: a document class is a LaTeX file (usually ending in
5254 \begin_inset Flex CharStyle:Code
5257 \begin_layout Plain Layout
5264 \begin_inset Flex CharStyle:Code
5267 \begin_layout Plain Layout
5273 ) that describes the format of a document such as an article, report, journal
5274 preprint, etc, and all the commands needed to realize that format.
5275 A layout file is a LyX file that corresponds to a LaTeX document class
5276 and that tells LyX how to
5277 \begin_inset Quotes eld
5281 \begin_inset Quotes erd
5284 things on the screen to make the display look something like the final
5286 More precisely, a layout file describes a
5287 \begin_inset Quotes eld
5291 \begin_inset Quotes erd
5294 which is the internal construct LyX uses to render the screen display.
5296 \begin_inset Quotes eld
5300 \begin_inset Quotes erd
5304 \begin_inset Quotes eld
5308 \begin_inset Quotes erd
5311 can be used somewhat interchangeably, but it is better to refer to the
5312 file as the layout, and the thing living in LyX's memory as the text class.
5313 A template file is simply a LyX document that contains a set of predefined
5314 entries for a given document class—entries that are generally required
5316 Templates are especially useful for things like journal manuscripts that
5317 are to be submitted electronically.
5320 \begin_layout Section
5321 Installing a new LaTeX package
5324 \begin_layout Standard
5325 Some installations may not include a LaTeX package that you would like to
5327 For example, you might need FoilTeX, a package for preparing slides or
5328 viewgraphs for overhead projectors.
5329 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5330 a user interface for that.
5331 For example on MiKTeX you start its program
5332 \begin_inset Quotes eld
5336 \begin_inset Quotes erd
5339 to get a list of available packages.
5340 To install one, right click on it or use the installing toolbar button.
5341 When the package you want to install is not in the list, but you have it
5343 \begin_inset Flex CharStyle:Code
5346 \begin_layout Plain Layout
5353 \begin_inset Flex CharStyle:Code
5356 \begin_layout Plain Layout
5362 -file, then copy these files to a subfolder of your LaTeX distribution,
5363 for example to the folder
5372 Then update the file name database of your LaTeX-distribution.
5373 For example on MiKTeX this is done by pressing the button
5376 \begin_inset space ~
5381 that you find in MiKTeX's
5382 \begin_inset Quotes eld
5386 \begin_inset Quotes erd
5390 In both cases you need afterwards to reconfigure LyX using the menu
5391 \begin_inset Flex CharStyle:MenuItem
5394 \begin_layout Plain Layout
5395 Tools\SpecialChar \menuseparator
5401 and then to restart LyX.
5404 \begin_layout Standard
5405 If your LaTeX distribution doesn't provide a user interface, then you can
5406 follow these steps by using a UNIX/Linux console.
5409 \begin_layout Enumerate
5410 Get the package from
5411 \begin_inset CommandInset href
5414 target "http://www.ctan.org/"
5421 \begin_layout Enumerate
5422 You can install this package in several different places.
5423 If you want it to be available for all users on your system, then you should
5424 install it in your `local' TeX tree; if you want (or need) it to be available
5425 just for you, then you can install it in your own `user' TeX tree.
5426 Where these should be created, if they do not already exist, depends upon
5427 the details of your system.
5428 To find out, look in the file
5429 \begin_inset Flex CharStyle:Code
5432 \begin_layout Plain Layout
5442 \begin_layout Plain Layout
5443 This usually lives in the directory
5444 \begin_inset Flex CharStyle:Code
5447 \begin_layout Plain Layout
5453 , though you can run
5454 \begin_inset Flex CharStyle:Code
5457 \begin_layout Plain Layout
5468 The location of the `local' TeX tree is defined by
5469 \begin_inset Flex CharStyle:Code
5472 \begin_layout Plain Layout
5478 ; this is usually somewhere like
5479 \begin_inset Flex CharStyle:Code
5482 \begin_layout Plain Layout
5483 /usr/local/share/texmf/
5489 The `user' TeX tree is defined by
5490 \begin_inset Flex CharStyle:Code
5493 \begin_layout Plain Layout
5500 \begin_inset Flex CharStyle:Code
5503 \begin_layout Plain Layout
5510 (If these variables are not predefined, you can define them.) You'll probably
5511 need root permissions to create or modify the `local' tree; but your `user'
5512 tree shouldn't have such limitations.
5515 \begin_layout Enumerate
5517 \begin_inset Flex CharStyle:Code
5520 \begin_layout Plain Layout
5527 \begin_inset Flex CharStyle:Code
5530 \begin_layout Plain Layout
5537 \begin_inset Flex CharStyle:Code
5540 \begin_layout Plain Layout
5547 \begin_inset space \thinspace{}
5551 \begin_inset Newline newline
5555 \begin_inset Flex CharStyle:Code
5558 \begin_layout Plain Layout
5559 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5565 \begin_inset Newline newline
5568 But, again, most of this will
5569 \begin_inset Quotes eld
5573 \begin_inset Quotes erd
5579 \begin_layout Enumerate
5584 \begin_layout Plain Layout
5585 We'll assume henceforth that you're defining `local' TeX tree.
5586 If you're defining a user tree, just adjust as necessary.
5592 You must follow the directory structure of your existing
5593 \begin_inset Flex CharStyle:Code
5596 \begin_layout Plain Layout
5602 directory, which will be found at
5603 \begin_inset Flex CharStyle:Code
5606 \begin_layout Plain Layout
5613 For example, latex packages should go under
5614 \begin_inset Flex CharStyle:Code
5617 \begin_layout Plain Layout
5618 $TEXMFLOCAL/tex/latex/
5626 \begin_layout Enumerate
5627 Install the package.
5628 For example, you would unpack the FoilTeX tarball and copy it to
5629 \begin_inset Flex CharStyle:Code
5632 \begin_layout Plain Layout
5633 $TEXMFLOCAL/tex/latex/foiltex
5640 \begin_inset Flex CharStyle:Code
5643 \begin_layout Plain Layout
5649 directory contains various files.
5652 \begin_layout Enumerate
5654 \begin_inset Flex CharStyle:Code
5657 \begin_layout Plain Layout
5665 \begin_inset Flex CharStyle:Code
5668 \begin_layout Plain Layout
5677 \begin_layout Standard
5678 Your package is now installed and available to LaTeX.
5679 To make it available to LyX, you need to create a Layout file, if one is
5680 not already available.
5681 (See the next section.) Once you have a layout file, you need only reconfigure
5683 \begin_inset Flex CharStyle:MenuItem
5686 \begin_layout Plain Layout
5687 Tools\SpecialChar \menuseparator
5693 ) and then restart LyX.
5694 You should then see your new package—for example
5695 \begin_inset Flex CharStyle:MenuItem
5698 \begin_layout Plain Layout
5705 \begin_inset Flex CharStyle:MenuItem
5708 \begin_layout Plain Layout
5709 Document\SpecialChar \menuseparator
5716 \begin_inset Flex CharStyle:MenuItem
5719 \begin_layout Plain Layout
5729 \begin_layout Section
5733 \begin_layout Standard
5734 This section describes how to write and install your own LyX layout files
5735 and walks through the
5736 \begin_inset Flex CharStyle:Code
5739 \begin_layout Plain Layout
5745 text class format as an example.
5747 \begin_inset Flex CharStyle:Code
5750 \begin_layout Plain Layout
5756 files describe what paragraph and character styles are available for a
5757 given document class and how LyX should display them.
5758 We try to provide a thorough description of the process here; however,
5759 there are so many different types of documents supported by LaTeX classes
5760 that we can't hope to cover every different possibility or problem you
5762 (The LyX users' list is frequented by people with lots of experience with
5763 layout design who are willing to share what they've learned.)
5766 \begin_layout Standard
5767 As you prepare to write a new layout, it is extremely helpful to look at
5768 the example layouts distributed with LyX.
5769 If you use a nice LaTeX document class that might be of interest for others,
5770 too, and have a nice corresponding LyX layout, feel free to contribute
5771 the stuff to us, so we may put it into the distribution.
5773 \begin_inset CommandInset href
5775 name "section on the LyX wiki"
5776 target "http://wiki.lyx.org/Layouts/Layouts"
5780 for this kind of material.
5783 \begin_layout Standard
5784 All the tags described in this chapter are case-insensitive; this means
5786 \begin_inset Flex CharStyle:Code
5789 \begin_layout Plain Layout
5796 \begin_inset Flex CharStyle:Code
5799 \begin_layout Plain Layout
5806 \begin_inset Flex CharStyle:Code
5809 \begin_layout Plain Layout
5815 are really the same command.
5816 The possible values are printed in brackets after the feature's name.
5817 The default value if a feature isn't specified inside a text class-description
5819 \begin_inset Flex CharStyle:Code
5822 \begin_layout Plain Layout
5831 If the argument has a data type like
5832 \begin_inset Quotes eld
5836 \begin_inset Quotes erd
5840 \begin_inset Quotes eld
5844 \begin_inset Quotes erd
5847 , the default is shown like this:
5848 \begin_inset Flex CharStyle:Code
5851 \begin_layout Plain Layout
5862 \begin_layout Subsection
5864 \begin_inset CommandInset label
5866 name "sub:Layout-modules"
5873 \begin_layout Standard
5874 Similar to layout files, and new with LyX 1.6, are layout
5879 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
5880 some modules—such as the endnotes module—provide support for just such
5882 In a sense, layout modules are similar to included files—files like
5883 \begin_inset Flex CharStyle:Code
5886 \begin_layout Plain Layout
5892 —in that modules are not specific to a given document layout but may be
5893 used with many different layouts.
5894 The difference is that using a layout module does not require editing the
5896 Rather, modules are selected in the
5897 \begin_inset Flex CharStyle:MenuItem
5900 \begin_layout Plain Layout
5901 Document\SpecialChar \menuseparator
5910 \begin_layout Standard
5911 Building modules is the easiest way to get started with layout editing,
5912 since it can be as simple as adding a single new paragraph or flex inset.
5913 But modules may, in principle, contain anything a layout file can contain.
5916 \begin_layout Standard
5917 A module must begin with a line like the following:
5920 \begin_layout LyX-Code
5923 DeclareLyXModule[endnotes.sty]{Endnotes}
5926 \begin_layout Standard
5927 The mandatory argument, in curly brackets, is the name of the module, as
5929 \begin_inset Flex CharStyle:MenuItem
5932 \begin_layout Plain Layout
5933 Document\SpecialChar \menuseparator
5940 The argument in square brackets is optional: It declares any LaTeX packages
5941 on which the module depends.
5942 Please note that only packages about which LyX knows should be listed in
5943 the square brackets.
5947 \begin_layout Plain Layout
5948 The list of such packages is documented only in the source code.
5953 LyX will not check for arbitrary packages.
5954 It is also possible to use the form
5955 \begin_inset Flex CharStyle:MenuItem
5958 \begin_layout Plain Layout
5964 , which declares that the module can only be used when there exists a conversion
5965 chain between formats `from' and `to'.
5968 \begin_layout Standard
5969 The module declaration should then be followed by lines like the following:
5972 \begin_layout LyX-Code
5976 \begin_layout LyX-Code
5977 #Adds an endnote command, in addition to footnotes.
5981 \begin_layout LyX-Code
5982 #You will need to add
5984 theendnotes in TeX code where you
5987 \begin_layout LyX-Code
5988 #want the endnotes to appear.
5992 \begin_layout LyX-Code
5996 \begin_layout LyX-Code
5997 #Requires: somemodule | othermodule
6000 \begin_layout LyX-Code
6001 #Excludes: badmodule
6004 \begin_layout Standard
6005 The description is used in
6006 \begin_inset Flex CharStyle:MenuItem
6009 \begin_layout Plain Layout
6010 Document\SpecialChar \menuseparator
6016 to provide the user with information about what the module does.
6018 \begin_inset Flex CharStyle:Code
6021 \begin_layout Plain Layout
6027 line is used to identify other modules with which this one must be used;
6029 \begin_inset Flex CharStyle:Code
6032 \begin_layout Plain Layout
6038 line is used to identify modules with which this one may not be used.
6039 Both are optional, and, as shown, multiple modules should be separated
6040 with the pipe symbol: |.
6041 Note that the required modules are treated disjunctively:
6045 of the required modules must be used.
6050 excluded module may be used.
6051 Note that modules are identified here by their
6055 without the .module extension.
6057 \begin_inset Flex CharStyle:Code
6060 \begin_layout Plain Layout
6067 \begin_inset Flex CharStyle:Code
6070 \begin_layout Plain Layout
6079 \begin_layout Standard
6080 After creating a new module, you will need to reconfigure and then restart
6081 LyX for the module to appear in the menu.
6082 However, changes you make to the module will be seen immediately, if you
6084 \begin_inset Flex CharStyle:MenuItem
6087 \begin_layout Plain Layout
6088 Document\SpecialChar \menuseparator
6094 , highlight something, and then hit
6095 \begin_inset Quotes eld
6099 \begin_inset Quotes erd
6105 It is strongly recommended that you save your work before doing so
6110 it is strongly recommended that you not attempt to edit modules while simultaneo
6111 usly working on documents
6114 Though of course the developers strive to keep LyX stable in such situations,
6115 syntax errors and the like in your module file could cause strange behavior.
6118 \begin_layout Subsection
6119 Supporting new document classes
6122 \begin_layout Standard
6123 There are two situations you are likely to encounter when wanting to support
6124 a new LaTeX document class, involving LaTeX2e class (
6125 \begin_inset Flex CharStyle:Code
6128 \begin_layout Plain Layout
6135 \begin_inset Flex CharStyle:Code
6138 \begin_layout Plain Layout
6145 Supporting a style file is usually fairly easy.
6146 Supporting a new document class is a bit harder.
6149 \begin_layout Subsection
6151 \begin_inset Flex CharStyle:MenuItem
6154 \begin_layout Plain Layout
6163 \begin_layout Standard
6164 If your new document class is provided as a style file that is used in conjuncti
6165 on with an existing, supported document class—for the sake of the example,
6166 we'll assume that the style file is called
6167 \begin_inset Flex CharStyle:MenuItem
6170 \begin_layout Plain Layout
6176 and it is meant to be used with
6177 \begin_inset Flex CharStyle:MenuItem
6180 \begin_layout Plain Layout
6186 , which is a standard class—start by copying the existing class's layout
6187 file into your local directory:
6190 \begin_layout LyX-Code
6191 cp report.layout ~/.lyx/layouts/myclass.layout
6194 \begin_layout Standard
6196 \begin_inset Flex CharStyle:Code
6199 \begin_layout Plain Layout
6205 and change the line:
6208 \begin_layout LyX-Code
6211 DeclareLaTeXClass{report}
6214 \begin_layout Standard
6218 \begin_layout LyX-Code
6221 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6224 \begin_layout Standard
6228 \begin_layout LyX-Code
6230 \begin_inset Newline newline
6236 \begin_inset Newline newline
6242 \begin_layout Standard
6243 near the top of the file.
6246 \begin_layout Standard
6247 Start LyX and select
6248 \begin_inset Flex CharStyle:MenuItem
6251 \begin_layout Plain Layout
6252 Tools\SpecialChar \menuseparator
6259 Then restart LyX and try creating a new document.
6261 \begin_inset Flex CharStyle:MenuItem
6264 \begin_layout Plain Layout
6270 " as a document class option in the
6271 \begin_inset Flex CharStyle:MenuItem
6274 \begin_layout Plain Layout
6275 Document\SpecialChar \menuseparator
6282 It is likely that some of the sectioning commands and such in your new
6283 class will work differently from how they worked in the base class—
6284 \begin_inset Flex CharStyle:Code
6287 \begin_layout Plain Layout
6293 in this example—so you can fiddle around with the settings for the different
6294 sections if you wish.
6297 \begin_layout Subsection
6299 \begin_inset Flex CharStyle:MenuItem
6302 \begin_layout Plain Layout
6311 \begin_layout Standard
6312 There are two possibilities here.
6313 One is that the class file is itself based upon an existing document class.
6314 For example, many thesis classes are based upon
6315 \begin_inset Flex CharStyle:MenuItem
6318 \begin_layout Plain Layout
6325 To see whether yours is, look for a line like
6328 \begin_layout LyX-Code
6334 \begin_layout Standard
6336 If so, then you may proceed largely as in the previous section, though
6337 the DeclareLaTeXClass line will be different.
6338 If your new class is thesis, and it is based upon book, then the line should
6343 \begin_layout Plain Layout
6344 And it will be easiest if you save the file to
6345 \begin_inset Flex CharStyle:Code
6348 \begin_layout Plain Layout
6354 : LyX assumes that the document class has the same name as the layout file.
6363 \begin_layout LyX-Code
6366 DeclareLaTeXClass[thesis,book]{thesis}
6369 \begin_layout Standard
6370 If, on the other hand, the new class is not based upon an existing class,
6371 you will probably have to
6372 \begin_inset Quotes eld
6376 \begin_inset Quotes erd
6380 We strongly suggest copying an existing layout file which uses a similar
6381 LaTeX class and then modifying it, if you can do so.
6382 At least use an existing file as a starting point so you can find out what
6383 items you need to worry about.
6384 Again, the specifics are covered below.
6387 \begin_layout Section
6388 Declaring a new text class
6391 \begin_layout Standard
6392 When it's finally time to get your hands dirty and create or edit your own
6393 layout file, the following sections describe what you're up against.
6394 Our advice is to go slowly, save and test often, listen to soothing music,
6395 and enjoy one or two of your favorite adult beverages; more if you are
6396 getting particularly stuck.
6397 It's really not that hard, except that the multitude of options can become
6398 overwhelming if you try to do to much in one sitting.
6399 Go have another adult beverage, just for good measure.
6402 \begin_layout Standard
6406 \begin_layout Standard
6407 Lines in a layout file which begin with a
6408 \begin_inset Flex CharStyle:Code
6411 \begin_layout Plain Layout
6418 There is one exception to this rule: all layouts should begin with lines
6422 \begin_layout LyX-Code
6425 #% Do not delete the line below; configure depends on this
6428 \begin_layout LyX-Code
6433 DeclareLaTeXClass{article}
6436 \begin_layout Standard
6437 The second line is used when you configure LyX.
6438 The layout file is read by the LaTeX script
6439 \begin_inset Flex CharStyle:Code
6442 \begin_layout Plain Layout
6448 , in a special mode where
6449 \begin_inset Flex CharStyle:Code
6452 \begin_layout Plain Layout
6459 The first line is just a LaTeX comment, and the second one contains the
6460 declaration of the text class.
6461 If these lines appear in a file named
6462 \begin_inset Flex CharStyle:Code
6465 \begin_layout Plain Layout
6471 , then they define a text class of name
6472 \begin_inset Flex CharStyle:Code
6475 \begin_layout Plain Layout
6481 (the name of the layout file) which uses the LaTeX document class
6482 \begin_inset Flex CharStyle:Code
6485 \begin_layout Plain Layout
6491 (the default is to use the same name as the layout).
6493 \begin_inset Quotes eld
6497 \begin_inset Quotes erd
6500 that appears above is used as a description of the text class in the
6501 \begin_inset Flex CharStyle:MenuItem
6504 \begin_layout Plain Layout
6505 Document\SpecialChar \menuseparator
6514 \begin_layout Standard
6515 Let's assume that you wrote your own text class that uses the
6516 \begin_inset Flex CharStyle:Code
6519 \begin_layout Plain Layout
6525 document class, but where you changed the appearance of the section headings.
6526 If you put it in a file
6527 \begin_inset Flex CharStyle:Code
6530 \begin_layout Plain Layout
6536 , the header of this file should be:
6539 \begin_layout LyX-Code
6542 #% Do not delete the line below; configure depends on this
6545 \begin_layout LyX-Code
6550 DeclareLaTeXClass[article]{article (with my own headings)}
6553 \begin_layout Standard
6554 This declares a text class
6555 \begin_inset Flex CharStyle:Code
6558 \begin_layout Plain Layout
6564 , associated with the LaTeX document class
6565 \begin_inset Flex CharStyle:Code
6568 \begin_layout Plain Layout
6575 \begin_inset Quotes eld
6578 article (with my own headings)
6579 \begin_inset Quotes erd
6583 If your text class depends on several packages, you can declare it as:
6586 \begin_layout LyX-Code
6589 #% Do not delete the line below; configure depends on this
6592 \begin_layout LyX-Code
6597 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6600 \begin_layout Standard
6601 This indicates that your text class uses the foo.sty package.
6602 Finally, it is also possible to declare classes for DocBook code.
6603 Typical declarations will look like
6606 \begin_layout LyX-Code
6609 #% Do not delete the line below; configure depends on this
6612 \begin_layout LyX-Code
6617 DeclareDocBookClass[article]{SGML (DocBook article)}
6620 \begin_layout Standard
6621 Note that these declarations can also be given an optional parameter declaring
6622 the name of the document class (but not a list).
6625 \begin_layout Standard
6626 So, to be as explicit as possible, the form of the layout declaration is:
6629 \begin_layout LyX-Code
6634 DeclareLaTeXClass[class,package.sty]{layout description}
6637 \begin_layout Standard
6638 The class need only be specified if the name of the LaTeX class file and
6639 the name of the layout file are different; if the name of the class file
6640 is not specified, then LyX will simply assume that it is the same as the
6641 name of the layout file.
6644 \begin_layout Standard
6645 When the text class has been modified to your taste, all you have to do
6646 is to copy it either to
6647 \begin_inset Flex CharStyle:Code
6650 \begin_layout Plain Layout
6657 \begin_inset Flex CharStyle:Code
6660 \begin_layout Plain Layout
6667 \begin_inset Flex CharStyle:MenuItem
6670 \begin_layout Plain Layout
6671 Tools\SpecialChar \menuseparator
6677 , exit LyX and restart it.
6678 Then your new text class should be available along with the others.
6681 \begin_layout Standard
6682 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6683 you made to your layout files.
6684 As a result, editing layout files could be very time consuming.
6685 Beginning with 1.6, however, you can force a reload of the layout currently
6686 in use by using the LyX function
6687 \begin_inset Flex CharStyle:MenuItem
6690 \begin_layout Plain Layout
6697 There is no default binding for this function—though, of course, you can
6698 bind it to a key yourself.
6699 If you want to use this function, then, you should simply enter it in the
6705 : This is very much an `advanced feature'.
6710 recommended that you save your work before using this function.
6715 recommended that you not attempt to edit your layout while simultaneously
6716 working on a document that you care about.
6717 Use a test document.
6718 Syntax errors and the like in your layout file could cause peculiar behavior.
6719 In particular, such errors could cause LyX to regard the current layout
6720 as invalid and to attempt to switch to some other layout.
6721 The LyX team strives to keep LyX stable in such situations, but safe is
6725 \begin_layout Subsection
6729 \begin_layout Standard
6730 The first non-comment line must contain the file format number:
6733 \begin_layout Description
6734 \begin_inset Flex CharStyle:Code
6737 \begin_layout Plain Layout
6744 \begin_inset Flex CharStyle:Code
6747 \begin_layout Plain Layout
6753 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6754 don't have an explicit file format).
6755 The file format that is documented here is format 14.
6758 \begin_layout Subsection
6759 General text class parameters
6762 \begin_layout Standard
6763 These are the general parameters which describe the form of the entire document:
6766 \begin_layout Description
6767 \begin_inset Flex CharStyle:Code
6770 \begin_layout Plain Layout
6776 Adds information to the document preamble.
6778 \begin_inset Quotes eld
6782 \begin_inset Flex CharStyle:Code
6785 \begin_layout Plain Layout
6792 \begin_inset Quotes erd
6798 \begin_layout Description
6799 \begin_inset Flex CharStyle:Code
6802 \begin_layout Plain Layout
6808 Describes various global options supported by the document class.
6810 \begin_inset space ~
6814 \begin_inset CommandInset ref
6816 reference "sub:ClassOptions"
6822 \begin_inset Quotes eld
6826 \begin_inset Flex CharStyle:Code
6829 \begin_layout Plain Layout
6836 \begin_inset Quotes erd
6842 \begin_layout Description
6843 \begin_inset Flex CharStyle:Code
6846 \begin_layout Plain Layout
6853 \begin_inset Flex CharStyle:Code
6856 \begin_layout Plain Layout
6865 \begin_inset Flex CharStyle:Code
6868 \begin_layout Plain Layout
6874 ] Whether the class should default to having one or two columns.
6875 Can be changed in the
6876 \begin_inset Flex CharStyle:MenuItem
6879 \begin_layout Plain Layout
6880 Document\SpecialChar \menuseparator
6889 \begin_layout Description
6890 \begin_inset Flex CharStyle:Code
6893 \begin_layout Plain Layout
6899 This sequence defines a new counter.
6901 \begin_inset space ~
6905 \begin_inset CommandInset ref
6907 reference "sub:Counters"
6913 \begin_inset Quotes eld
6917 \begin_inset Flex CharStyle:Code
6920 \begin_layout Plain Layout
6927 \begin_inset Quotes erd
6933 \begin_layout Description
6934 \begin_inset Flex CharStyle:Code
6937 \begin_layout Plain Layout
6943 Sets the default font used to display the document.
6945 \begin_inset space ~
6949 \begin_inset CommandInset ref
6951 reference "sub:Font-description"
6955 for how to declare fonts.
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
6988 \begin_inset Flex CharStyle:Code
6991 \begin_layout Plain Layout
6997 Specifies a module to be included by default with this document class,
6998 which should be specified by filename without the
6999 \begin_inset Flex CharStyle:Code
7002 \begin_layout Plain Layout
7009 The user can still remove the module, but it will be active at the outset.
7010 (This applies only when new files are created, or when this class is chosen
7011 for an existing document.)
7014 \begin_layout Description
7015 \begin_inset Flex CharStyle:Code
7018 \begin_layout Plain Layout
7025 \begin_inset Flex CharStyle:Code
7028 \begin_layout Plain Layout
7034 ] This is the style that will be assigned to new paragraphs, usually
7035 \begin_inset Flex CharStyle:MenuItem
7038 \begin_layout Plain Layout
7045 This will default to the first defined style if not given, but you are
7046 highly encouraged to use this directive.
7049 \begin_layout Description
7050 \begin_inset Flex CharStyle:Code
7053 \begin_layout Plain Layout
7060 \begin_inset Flex CharStyle:Code
7063 \begin_layout Plain Layout
7069 ] Indicates that the module in question—which should be specified by filename
7071 \begin_inset Flex CharStyle:Code
7074 \begin_layout Plain Layout
7080 extension—cannot be used with this document class.
7081 This might be used in a journal-specific layout file to prevent, say, the
7083 \begin_inset Flex CharStyle:Code
7086 \begin_layout Plain Layout
7092 module that numbers theorems by section.
7097 be used in a module.
7098 Modules have their own way of excluding other modules (see
7099 \begin_inset CommandInset ref
7101 reference "sub:Layout-modules"
7108 \begin_layout Description
7109 \begin_inset Flex CharStyle:Code
7112 \begin_layout Plain Layout
7118 Defines a new float.
7120 \begin_inset space ~
7124 \begin_inset CommandInset ref
7126 reference "sub:Floats"
7132 \begin_inset Quotes eld
7136 \begin_inset Flex CharStyle:Code
7139 \begin_layout Plain Layout
7146 \begin_inset Quotes erd
7152 \begin_layout Description
7153 \begin_inset Flex CharStyle:Code
7156 \begin_layout Plain Layout
7162 As its name implies, this command allows you to include another layout
7163 definition file within yours to avoid duplicating commands.
7164 Common examples are the standard layout files, for example,
7165 \begin_inset Flex CharStyle:Code
7168 \begin_layout Plain Layout
7174 , which contains most of the basic layouts.
7177 \begin_layout Description
7178 \begin_inset Flex CharStyle:Code
7181 \begin_layout Plain Layout
7187 This section (re-)defines the layout of an inset.
7188 It can be applied to an existing inset of to a new, user-defined inset,
7190 \begin_inset space \thinspace{}
7194 \begin_inset space \space{}
7197 a new character style.
7199 \begin_inset space ~
7203 \begin_inset CommandInset ref
7205 reference "sub:Flex-insets-and"
7209 for more information.
7211 \begin_inset Quotes eld
7215 \begin_inset Flex CharStyle:Code
7218 \begin_layout Plain Layout
7225 \begin_inset Quotes erd
7231 \begin_layout Description
7232 \begin_inset Flex CharStyle:Code
7235 \begin_layout Plain Layout
7241 A string that indicates the width of the left margin on the screen, for
7243 \begin_inset Quotes eld
7247 \begin_inset Quotes erd
7253 \begin_layout Description
7254 \begin_inset Flex CharStyle:Code
7257 \begin_layout Plain Layout
7263 This command deletes an existing float.
7264 This is particularly useful when you want to suppress a float that has
7265 be defined in an input file.
7268 \begin_layout Description
7269 \begin_inset Flex CharStyle:Code
7272 \begin_layout Plain Layout
7278 This command deletes an existing style.
7279 This is particularly useful when you want to suppress a style that has
7280 be defined in an input file.
7283 \begin_layout Description
7284 \begin_inset Flex CharStyle:Code
7287 \begin_layout Plain Layout
7293 A string indicating the file format (as defined in the Preferences dialog)
7294 produced by this class.
7295 It is mainly useful when
7296 \begin_inset Flex CharStyle:Code
7299 \begin_layout Plain Layout
7305 is `literate' and one wants to define a new type of literate document.
7306 This string is reset to `docbook', `latex', or `literate' when the correspondin
7308 \begin_inset Flex CharStyle:Code
7311 \begin_layout Plain Layout
7317 parameter is encountered.
7320 \begin_layout Description
7321 \begin_inset Flex CharStyle:Code
7324 \begin_layout Plain Layout
7330 A string indicating what sort of output documents using this class will
7332 At present, the options are: `docbook', `latex', and `literate'.
7335 \begin_layout Description
7336 \begin_inset Flex CharStyle:Code
7339 \begin_layout Plain Layout
7350 \begin_inset Flex CharStyle:Code
7353 \begin_layout Plain Layout
7364 \begin_inset Flex CharStyle:Code
7367 \begin_layout Plain Layout
7374 \begin_inset Flex CharStyle:Code
7377 \begin_layout Plain Layout
7383 ] The class default pagestyle.
7384 Can be changed in the
7385 \begin_inset Flex CharStyle:MenuItem
7388 \begin_layout Plain Layout
7389 Document\SpecialChar \menuseparator
7398 \begin_layout Description
7399 \begin_inset Flex CharStyle:Code
7402 \begin_layout Plain Layout
7408 Sets the preamble for the LaTeX document.
7409 Note that this will completely override any prior
7410 \begin_inset Flex CharStyle:Code
7413 \begin_layout Plain Layout
7420 \begin_inset Flex CharStyle:Code
7423 \begin_layout Plain Layout
7431 \begin_inset Quotes eld
7435 \begin_inset Flex CharStyle:Code
7438 \begin_layout Plain Layout
7445 \begin_inset Quotes erd
7451 \begin_layout Description
7452 \begin_inset Flex CharStyle:Code
7455 \begin_layout Plain Layout
7462 \begin_inset Flex CharStyle:Code
7465 \begin_layout Plain Layout
7472 \begin_inset Flex CharStyle:Code
7475 \begin_layout Plain Layout
7484 \begin_inset Flex CharStyle:Code
7487 \begin_layout Plain Layout
7493 ] Whether the class already provides the feature
7494 \begin_inset Flex CharStyle:Code
7497 \begin_layout Plain Layout
7504 A feature is in general the name of a package (
7505 \begin_inset Flex CharStyle:Code
7508 \begin_layout Plain Layout
7515 \begin_inset Flex CharStyle:Code
7518 \begin_layout Plain Layout
7524 , \SpecialChar \ldots{}
7526 \begin_inset Flex CharStyle:Code
7529 \begin_layout Plain Layout
7536 \begin_inset Flex CharStyle:Code
7539 \begin_layout Plain Layout
7545 ,\SpecialChar \ldots{}
7546 ); the complete list of supported features is unfortunately not documented
7547 outside the LyX source code—but see
7548 \begin_inset Flex CharStyle:Code
7551 \begin_layout Plain Layout
7557 if you're interested.
7559 \begin_inset Flex CharStyle:MenuItem
7562 \begin_layout Plain Layout
7563 Help\SpecialChar \menuseparator
7569 also gives an overview of the supported packages.
7572 \begin_layout Description
7573 \begin_inset Flex CharStyle:Code
7576 \begin_layout Plain Layout
7583 \begin_inset Flex CharStyle:Code
7586 \begin_layout Plain Layout
7592 ] Indicates that this layout provides the functionality of the module mentioned,
7593 which should be specified by the filename without the
7594 \begin_inset Flex CharStyle:Code
7597 \begin_layout Plain Layout
7604 This will typically be used if the layout includes the module directly,
7605 rather than using the
7606 \begin_inset Flex CharStyle:Code
7609 \begin_layout Plain Layout
7615 tag to indicate that it ought to be used.
7616 It could be used in a module that provided an alternate implementation
7617 of the same functionality.
7620 \begin_layout Description
7621 \begin_inset Flex CharStyle:Code
7624 \begin_layout Plain Layout
7631 \begin_inset Flex CharStyle:Code
7634 \begin_layout Plain Layout
7640 ] Whether the class requires the feature
7641 \begin_inset Flex CharStyle:Code
7644 \begin_layout Plain Layout
7651 Multiple features must be separated by commas.
7652 Note that you can only request supported features.
7655 \begin_layout Description
7656 \begin_inset Flex CharStyle:Code
7659 \begin_layout Plain Layout
7665 A string that indicates the width of the right margin on the screen, for
7667 \begin_inset Quotes eld
7671 \begin_inset Quotes erd
7677 \begin_layout Description
7678 \begin_inset Flex CharStyle:Code
7681 \begin_layout Plain Layout
7687 Sets which divisions get numbered.
7689 \begin_inset Flex CharStyle:Code
7692 \begin_layout Plain Layout
7701 \begin_layout Description
7702 \begin_inset Flex CharStyle:Code
7705 \begin_layout Plain Layout
7714 \begin_inset Flex CharStyle:Code
7717 \begin_layout Plain Layout
7728 \begin_inset Flex CharStyle:Code
7731 \begin_layout Plain Layout
7737 ] Whether the class-default should be printing on one or both sides of the
7739 Can be changed in the
7740 \begin_inset Flex CharStyle:MenuItem
7743 \begin_layout Plain Layout
7744 Document\SpecialChar \menuseparator
7753 \begin_layout Description
7754 \begin_inset Flex CharStyle:Code
7757 \begin_layout Plain Layout
7763 This sequence defines a new paragraph style.
7764 If the style already exists, it will redefine some of its parameters instead.
7766 \begin_inset space ~
7770 \begin_inset CommandInset ref
7772 reference "sub:Paragraph-Styles"
7778 \begin_inset Quotes eld
7782 \begin_inset Flex CharStyle:Code
7785 \begin_layout Plain Layout
7792 \begin_inset Quotes erd
7798 \begin_layout Description
7799 \begin_inset Flex CharStyle:Code
7802 \begin_layout Plain Layout
7809 \begin_inset Flex CharStyle:Code
7812 \begin_layout Plain Layout
7818 ] The name of the command or environment to be used with
7819 \begin_inset Flex CharStyle:Code
7822 \begin_layout Plain Layout
7831 \begin_layout Description
7832 \begin_inset Flex CharStyle:Code
7835 \begin_layout Plain Layout
7842 \begin_inset Flex CharStyle:Code
7845 \begin_layout Plain Layout
7854 \begin_inset Flex CharStyle:Code
7857 \begin_layout Plain Layout
7863 ] Indicates what kind of markup is used to define the title of a document.
7865 \begin_inset Flex CharStyle:Code
7868 \begin_layout Plain Layout
7874 means that the macro with name
7875 \begin_inset Flex CharStyle:Code
7878 \begin_layout Plain Layout
7884 will be inserted after the last layout which has
7885 \begin_inset Quotes eld
7889 \begin_inset Flex CharStyle:Code
7892 \begin_layout Plain Layout
7899 \begin_inset Quotes erd
7904 \begin_inset Flex CharStyle:Code
7907 \begin_layout Plain Layout
7913 corresponds to the case where the block of paragraphs which have
7914 \begin_inset Quotes eld
7918 \begin_inset Flex CharStyle:Code
7921 \begin_layout Plain Layout
7928 \begin_inset Quotes erd
7931 should be enclosed into the
7932 \begin_inset Flex CharStyle:Code
7935 \begin_layout Plain Layout
7944 \begin_layout Description
7945 \begin_inset Flex CharStyle:Code
7948 \begin_layout Plain Layout
7954 Sets which divisions are included in the table of contents.
7956 \begin_inset Flex CharStyle:Code
7959 \begin_layout Plain Layout
7968 \begin_layout Subsection
7969 \begin_inset Flex CharStyle:Code
7972 \begin_layout Plain Layout
7979 \begin_inset CommandInset label
7981 name "sub:ClassOptions"
7988 \begin_layout Standard
7990 \begin_inset Flex CharStyle:Code
7993 \begin_layout Plain Layout
7999 section can contain the following entries:
8002 \begin_layout Description
8003 \begin_inset Flex CharStyle:Code
8006 \begin_layout Plain Layout
8013 \begin_inset Flex CharStyle:Code
8016 \begin_layout Plain Layout
8022 ] The list of available font sizes for the document's main font, separated
8024 \begin_inset Quotes eld
8028 \begin_inset Flex CharStyle:Code
8031 \begin_layout Plain Layout
8038 \begin_inset Quotes erd
8044 \begin_layout Description
8045 \begin_inset Flex CharStyle:Code
8048 \begin_layout Plain Layout
8054 Used to set the DTD line with XML-based output classes.
8056 \begin_inset space \thinspace{}
8060 \begin_inset Quotes eld
8063 -//OASIS//DTD DocBook V4.2//EN
8064 \begin_inset Quotes erd
8070 \begin_layout Description
8071 \begin_inset Flex CharStyle:Code
8074 \begin_layout Plain Layout
8081 \begin_inset Flex CharStyle:Code
8084 \begin_layout Plain Layout
8085 string="empty|plain|headings|fancy"
8090 ] The list of available page styles, separated by
8091 \begin_inset Quotes eld
8095 \begin_inset Flex CharStyle:Code
8098 \begin_layout Plain Layout
8105 \begin_inset Quotes erd
8111 \begin_layout Description
8112 \begin_inset Flex CharStyle:Code
8115 \begin_layout Plain Layout
8122 \begin_inset Flex CharStyle:Code
8125 \begin_layout Plain Layout
8131 ] Some document class options, separated by a comma, that will be added
8132 to the optional part of the
8133 \begin_inset Flex CharStyle:Code
8136 \begin_layout Plain Layout
8147 \begin_layout Standard
8149 \begin_inset Flex CharStyle:Code
8152 \begin_layout Plain Layout
8158 section must end with
8159 \begin_inset Quotes eld
8163 \begin_inset Flex CharStyle:Code
8166 \begin_layout Plain Layout
8173 \begin_inset Quotes erd
8179 \begin_layout Subsection
8181 \begin_inset CommandInset label
8183 name "sub:Paragraph-Styles"
8190 \begin_layout Standard
8191 A paragraph style description looks like this:
8195 \begin_layout Plain Layout
8196 Note that this will either define a new layout or modify an existing one.
8204 \begin_layout LyX-Code
8211 \begin_layout LyX-Code
8215 \begin_layout LyX-Code
8219 \begin_layout Standard
8220 where the following commands are allowed:
8223 \begin_layout Description
8224 \begin_inset Flex CharStyle:Code
8227 \begin_layout Plain Layout
8234 \begin_inset Flex CharStyle:Code
8237 \begin_layout Plain Layout
8242 , left, right, center
8247 ] Paragraph alignment.
8250 \begin_layout Description
8251 \begin_inset Flex CharStyle:Code
8254 \begin_layout Plain Layout
8261 \begin_inset Flex CharStyle:Code
8264 \begin_layout Plain Layout
8269 , left, right, center
8274 ] A comma separated list of permitted alignments.
8275 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8277 For example a right-aligned or centered enumeration isn't possible.)
8280 \begin_layout Description
8281 \begin_inset Flex CharStyle:Code
8284 \begin_layout Plain Layout
8290 Language dependent information to be included in the LaTeX preamble when
8292 Note that this will completely override any prior
8293 \begin_inset Flex CharStyle:Code
8296 \begin_layout Plain Layout
8304 \begin_inset Quotes eld
8308 \begin_inset Flex CharStyle:Code
8311 \begin_layout Plain Layout
8318 \begin_inset Quotes erd
8322 The contents of this tag will occur once in the LaTeX preamble for each
8323 language used by the document.
8324 Each time, the following substitutions are made:
8328 \begin_layout Itemize
8329 \begin_inset Flex CharStyle:Code
8332 \begin_layout Plain Layout
8338 is replaced by the language name (as used by the babel package).
8341 \begin_layout Itemize
8343 \begin_inset Quotes eld
8347 \begin_inset Quotes erd
8351 \begin_inset Flex CharStyle:Code
8354 \begin_layout Plain Layout
8360 replaces its argument by the translation of the argument to the current
8364 \begin_layout Standard
8365 This preamble snippet will only be used if the document contains more than
8366 one language and the babel package is used.
8370 \begin_layout Description
8371 \begin_inset Flex CharStyle:Code
8374 \begin_layout Plain Layout
8381 \begin_inset Flex CharStyle:Code
8384 \begin_layout Plain Layout
8394 \begin_layout Plain Layout
8395 Note that a `float' here is a real number, such as: 1.5.
8400 The vertical space with which the last of a chain of paragraphs with this
8401 layout is separated from the following paragraph.
8402 If the next paragraph has another layout, the separations are not simply
8403 added, but the maximum is taken.
8406 \begin_layout Description
8407 \begin_inset Flex CharStyle:Code
8410 \begin_layout Plain Layout
8417 \begin_inset Flex CharStyle:Code
8420 \begin_layout Plain Layout
8426 The category for this style.
8427 This is used to group related styles in the Layout combobox on the toolbar.
8428 Any string can be used, but you may want to use existing categories with
8433 \begin_layout Description
8434 \begin_inset Flex CharStyle:Code
8437 \begin_layout Plain Layout
8443 Depth of XML command.
8444 Used only with XML-type formats.
8447 \begin_layout Description
8448 \begin_inset Flex CharStyle:Code
8451 \begin_layout Plain Layout
8458 \begin_inset CommandInset label
8460 name "des:CopyStyle"
8465 \begin_inset Flex CharStyle:Code
8468 \begin_layout Plain Layout
8474 Copies all the features of an existing style into the current one.
8478 \begin_layout Description
8479 \begin_inset Flex CharStyle:Code
8482 \begin_layout Plain Layout
8488 The name of a style whose preamble should be output
8493 This allows to ensure some ordering of the preamble snippets when macros
8494 definitions depend on one another.
8498 \begin_layout Plain Layout
8499 Note that, besides that functionality, there is no way to ensure any ordering
8501 The ordering that you see in a given version of LyX may change without
8502 warning in later versions.
8510 \begin_layout Description
8511 \begin_inset Flex CharStyle:Code
8514 \begin_layout Plain Layout
8521 \begin_inset Flex CharStyle:Code
8524 \begin_layout Plain Layout
8529 , Box, Filled_Box, Static
8534 ] The type of label that stands at the end of the paragraph (or sequence
8536 \begin_inset Flex CharStyle:Code
8539 \begin_layout Plain Layout
8546 \begin_inset Flex CharStyle:Code
8549 \begin_layout Plain Layout
8556 \begin_inset Flex CharStyle:Code
8559 \begin_layout Plain Layout
8566 \begin_inset Flex CharStyle:Code
8569 \begin_layout Plain Layout
8577 \begin_inset Flex CharStyle:Code
8580 \begin_layout Plain Layout
8587 \begin_inset Quotes eld
8591 \begin_inset Quotes erd
8595 \begin_inset Flex CharStyle:Code
8598 \begin_layout Plain Layout
8605 \begin_inset Flex CharStyle:Code
8608 \begin_layout Plain Layout
8609 \begin_inset space ~
8618 \begin_inset space ~
8621 black) square suitable for end of proof markers,
8622 \begin_inset Flex CharStyle:Code
8625 \begin_layout Plain Layout
8631 is an explicit text string.
8634 \begin_layout Description
8635 \begin_inset Flex CharStyle:Code
8638 \begin_layout Plain Layout
8645 \begin_inset Flex CharStyle:Code
8648 \begin_layout Plain Layout
8654 ] The string used for a label with a
8655 \begin_inset Flex CharStyle:Code
8658 \begin_layout Plain Layout
8665 \begin_inset Flex CharStyle:Code
8668 \begin_layout Plain Layout
8678 \begin_layout Description
8679 \begin_inset Flex CharStyle:Code
8682 \begin_layout Plain Layout
8689 \begin_inset Flex CharStyle:Code
8692 \begin_layout Plain Layout
8703 \begin_inset Flex CharStyle:Code
8706 \begin_layout Plain Layout
8715 \begin_layout Description
8716 \begin_inset Flex CharStyle:Code
8719 \begin_layout Plain Layout
8726 \begin_inset Flex CharStyle:Code
8729 \begin_layout Plain Layout
8739 ] With this parameter the
8740 \begin_inset Flex CharStyle:MenuItem
8743 \begin_layout Plain Layout
8750 \begin_inset Quotes eld
8753 Vertical space above
8754 \begin_inset Quotes erd
8758 \begin_inset Flex CharStyle:MenuItem
8761 \begin_layout Plain Layout
8762 Edit\SpecialChar \menuseparator
8764 \begin_inset space ~
8772 dialog can be set when initializing a paragraph with this style.
8776 \begin_layout Plain Layout
8779 Note from Jean-Marc:
8781 I'm not sure that this setting has much use, and it should probably be
8782 removed in later versions.
8790 \begin_layout Description
8791 \begin_inset Flex CharStyle:Code
8794 \begin_layout Plain Layout
8800 The font used for both the text body
8806 \begin_inset space ~
8810 \begin_inset CommandInset ref
8812 reference "sub:Font-description"
8817 Note that defining this font automatically defines the
8818 \begin_inset Flex CharStyle:Code
8821 \begin_layout Plain Layout
8828 So you should define this one first if you also want to define
8829 \begin_inset Flex CharStyle:Code
8832 \begin_layout Plain Layout
8841 \begin_layout Description
8842 \begin_inset Flex CharStyle:Code
8845 \begin_layout Plain Layout
8852 \begin_inset CommandInset label
8854 name "des:FreeSpacing"
8861 \begin_inset Flex CharStyle:Code
8864 \begin_layout Plain Layout
8875 \begin_inset Flex CharStyle:Code
8878 \begin_layout Plain Layout
8884 ] Usually LyX doesn't allow you to insert more than one space between words,
8885 since a space is considered as the separation between two words, not a
8886 character or symbol of its own.
8887 This is a very fine thing but sometimes annoying, for example, when typing
8888 program code or plain LaTeX code.
8890 \begin_inset Flex CharStyle:Code
8893 \begin_layout Plain Layout
8900 Note that LyX will create protected blanks for the additional blanks when
8901 in another mode than LaTeX-mode.
8904 \begin_layout Description
8905 \begin_inset Flex CharStyle:Code
8908 \begin_layout Plain Layout
8914 [[FIXME]] (Used only with XML-type formats.)
8917 \begin_layout Description
8918 \begin_inset Flex CharStyle:Code
8921 \begin_layout Plain Layout
8928 \begin_inset Flex CharStyle:Code
8931 \begin_layout Plain Layout
8937 If 1, marks the layout as being part of a title block (see also the
8938 \begin_inset Flex CharStyle:Code
8941 \begin_layout Plain Layout
8948 \begin_inset Flex CharStyle:Code
8951 \begin_layout Plain Layout
8960 \begin_layout Description
8961 \begin_inset Flex CharStyle:Code
8964 \begin_layout Plain Layout
8971 \begin_inset Flex CharStyle:Code
8974 \begin_layout Plain Layout
8980 ] This provides extra space between paragraphs that have the same layout.
8981 If you put other layouts into an environment, each is separated with the
8983 \begin_inset Flex CharStyle:Code
8986 \begin_layout Plain Layout
8993 But the whole items of the environment are additionally separated with
8995 \begin_inset Flex CharStyle:Code
8998 \begin_layout Plain Layout
9010 \begin_layout Description
9011 \begin_inset Flex CharStyle:Code
9014 \begin_layout Plain Layout
9020 [[FIXME]] (Used only with XML-type formats.)
9023 \begin_layout Description
9024 \begin_inset Flex CharStyle:Code
9027 \begin_layout Plain Layout
9034 \begin_inset CommandInset label
9036 name "des:KeepEmpty"
9043 \begin_inset Flex CharStyle:Code
9046 \begin_layout Plain Layout
9057 \begin_inset Flex CharStyle:Code
9060 \begin_layout Plain Layout
9066 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9067 lead to empty LaTeX output.
9068 There are some cases where this could be desirable however: in a letter
9069 template, the required fields can be provided as empty fields, so that
9070 people do not forget them; in some special classes, a layout can be used
9071 as some kind of break, which does not contain actual text.
9074 \begin_layout Description
9075 \begin_inset Flex CharStyle:Code
9078 \begin_layout Plain Layout
9084 [float=0] The vertical space between the label and the text body.
9085 Only used for labels that are above the text body (
9086 \begin_inset Flex CharStyle:Code
9089 \begin_layout Plain Layout
9096 \begin_inset Flex CharStyle:Code
9099 \begin_layout Plain Layout
9100 Centered_Top_Environment
9108 \begin_layout Description
9109 \begin_inset Flex CharStyle:Code
9112 \begin_layout Plain Layout
9119 \begin_inset Flex CharStyle:Code
9122 \begin_layout Plain Layout
9129 \begin_inset Newline newline
9132 The name of the counter for automatic numbering.
9134 \begin_inset Newline newline
9142 \begin_inset Flex CharStyle:Code
9145 \begin_layout Plain Layout
9152 \begin_inset Flex CharStyle:Code
9155 \begin_layout Plain Layout
9162 In that case, the counter will be stepped each time the layout appears.
9164 \begin_inset Newline newline
9172 \begin_inset Flex CharStyle:Code
9175 \begin_layout Plain Layout
9182 \begin_inset Flex CharStyle:Code
9185 \begin_layout Plain Layout
9191 , though this case is a bit complicated.
9193 \begin_inset Quotes eld
9197 \begin_inset Flex CharStyle:Code
9200 \begin_layout Plain Layout
9207 \begin_inset Quotes erd
9211 Then the actual counters used are
9212 \begin_inset Flex CharStyle:Code
9215 \begin_layout Plain Layout
9222 \begin_inset Flex CharStyle:Code
9225 \begin_layout Plain Layout
9232 \begin_inset Flex CharStyle:Code
9235 \begin_layout Plain Layout
9242 \begin_inset Flex CharStyle:Code
9245 \begin_layout Plain Layout
9252 These counters must all be declared separately.
9253 \begin_inset Newline newline
9257 \begin_inset CommandInset ref
9259 reference "sub:Counters"
9263 for details on counters.
9266 \begin_layout Description
9267 \begin_inset Flex CharStyle:Code
9270 \begin_layout Plain Layout
9276 The font used for the label.
9278 \begin_inset space ~
9282 \begin_inset CommandInset ref
9284 reference "sub:Font-description"
9291 \begin_layout Description
9292 \begin_inset Flex CharStyle:Code
9295 \begin_layout Plain Layout
9301 Text that indicates how far a label should be indented.
9304 \begin_layout Description
9305 \begin_inset Flex CharStyle:Code
9308 \begin_layout Plain Layout
9315 \begin_inset Flex CharStyle:Code
9318 \begin_layout Plain Layout
9324 ] The horizontal space between the label and the text body.
9325 Only used for labels that are not above the text body.
9328 \begin_layout Description
9329 \begin_inset Flex CharStyle:Code
9332 \begin_layout Plain Layout
9339 \begin_inset Flex CharStyle:Code
9342 \begin_layout Plain Layout
9348 ] The string used for a label with a
9349 \begin_inset Flex CharStyle:Code
9352 \begin_layout Plain Layout
9360 \begin_inset Flex CharStyle:Code
9363 \begin_layout Plain Layout
9369 is set, this string can be contain the special formatting commands described
9371 \begin_inset CommandInset ref
9373 reference "sub:Counters"
9381 \begin_layout Plain Layout
9382 For the sake of backwards compatibility, the string
9383 \begin_inset Flex CharStyle:Code
9386 \begin_layout Plain Layout
9396 will be replaced by the expanded
9397 \begin_inset Flex CharStyle:Code
9400 \begin_layout Plain Layout
9407 \begin_inset Flex CharStyle:Code
9410 \begin_layout Plain Layout
9419 This feature is now obsolete and should be replaced by the mechanisms of
9421 \begin_inset CommandInset ref
9423 reference "sub:Counters"
9435 \begin_layout Description
9436 \begin_inset Flex CharStyle:Code
9439 \begin_layout Plain Layout
9446 \begin_inset Flex CharStyle:Code
9449 \begin_layout Plain Layout
9455 ] This is used inside the appendix instead of
9456 \begin_inset Flex CharStyle:Code
9459 \begin_layout Plain Layout
9467 \begin_inset Flex CharStyle:Code
9470 \begin_layout Plain Layout
9477 \begin_inset Flex CharStyle:Code
9480 \begin_layout Plain Layout
9489 \begin_layout Description
9490 \begin_inset Flex CharStyle:Code
9493 \begin_layout Plain Layout
9499 [FIXME] (Used only with XML-type formats.)
9502 \begin_layout Description
9503 \begin_inset Flex CharStyle:Code
9506 \begin_layout Plain Layout
9513 \begin_inset Flex CharStyle:Code
9516 \begin_layout Plain Layout
9521 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
9522 Enumerate, Itemize, Bibliography
9531 \begin_layout Itemize
9532 \begin_inset Flex CharStyle:Code
9535 \begin_layout Plain Layout
9541 means the label is the very first word (up to the first real blank).
9542 Use protected spaces (like
9543 \begin_inset space ~
9546 that one) if you want more than one word as the label.
9550 \begin_layout Itemize
9551 \begin_inset Flex CharStyle:Code
9554 \begin_layout Plain Layout
9560 means the label is simply whatever
9561 \begin_inset Flex CharStyle:Code
9564 \begin_layout Plain Layout
9571 Note that this really is `static'.
9574 \begin_layout Itemize
9575 \begin_inset Flex CharStyle:Code
9578 \begin_layout Plain Layout
9585 \begin_inset Flex CharStyle:Code
9588 \begin_layout Plain Layout
9589 Centered_Top_Environment
9594 are special cases of
9595 \begin_inset Flex CharStyle:Code
9598 \begin_layout Plain Layout
9605 The label will be printed above the paragraph, but only at the top of an
9606 environment or the top of a chain of paragraphs with this layout.
9607 This might be used with the
9608 \begin_inset Flex CharStyle:MenuItem
9611 \begin_layout Plain Layout
9617 layout, for example.
9620 \begin_layout Itemize
9621 \begin_inset Flex CharStyle:Code
9624 \begin_layout Plain Layout
9630 is a special case for the caption-labels
9631 \begin_inset Quotes eld
9635 \begin_inset Quotes erd
9639 \begin_inset Quotes eld
9643 \begin_inset Quotes erd
9648 \begin_inset Flex CharStyle:Code
9651 \begin_layout Plain Layout
9657 means the (hardcoded) label string depends on the kind of float: It is
9658 hardcoded to be `FloatType N', where N is the value of the counter associated
9662 \begin_layout Itemize
9664 \begin_inset Flex CharStyle:Code
9667 \begin_layout Plain Layout
9673 label type defines automatically numbered labels.
9675 \begin_inset Flex CharStyle:Code
9678 \begin_layout Plain Layout
9684 will be expanded to resolve any counter references it contains: For example,
9686 \begin_inset Quotes eld
9690 \begin_inset Flex CharStyle:Code
9693 \begin_layout Plain Layout
9704 \begin_inset Quotes erd
9709 \begin_inset CommandInset ref
9711 reference "sub:Counters"
9715 for more information on counters.
9718 \begin_layout Itemize
9719 \begin_inset Flex CharStyle:Code
9722 \begin_layout Plain Layout
9728 produces the usual sort of enumeration labels.
9729 At present, it is hardcoded to use Arabic numerals, lowercase letters,
9730 small Roman numerals, and uppercase letters for the four possible depths.
9733 \begin_layout Itemize
9734 \begin_inset Flex CharStyle:Code
9737 \begin_layout Plain Layout
9743 produces various bullets at the different levels.
9744 It is also hardcoded.
9747 \begin_layout Itemize
9748 \begin_inset Flex CharStyle:Code
9751 \begin_layout Plain Layout
9757 is used internally by LyX and should be used only with
9758 \begin_inset Flex CharStyle:Code
9761 \begin_layout Plain Layout
9762 LatexType BibEnvironment
9771 \begin_layout Description
9772 \begin_inset Flex CharStyle:Code
9775 \begin_layout Plain Layout
9782 \begin_inset Flex CharStyle:Code
9785 \begin_layout Plain Layout
9791 , but this preamble snippet occurs independently from the babel package,
9792 and only for the document language.
9794 \begin_inset Quotes eld
9798 \begin_inset Flex CharStyle:Code
9801 \begin_layout Plain Layout
9808 \begin_inset Quotes erd
9815 \begin_layout Standard
9816 If the style defines text that appears in the typeset document, it may use
9818 \begin_inset Flex CharStyle:Code
9821 \begin_layout Plain Layout
9828 \begin_inset Flex CharStyle:Code
9831 \begin_layout Plain Layout
9837 to support non-english and even multilanguage documents correctly.
9838 The following excerpt (from the
9839 \begin_inset Flex CharStyle:Code
9842 \begin_layout Plain Layout
9848 file) shows how this works:
9851 \begin_layout LyX-Code
9855 \begin_layout LyX-Code
9858 theoremstyle{remark}
9861 \begin_layout LyX-Code
9864 newtheorem{claim}[thm]{
9871 \begin_layout LyX-Code
9875 \begin_layout LyX-Code
9879 \begin_layout LyX-Code
9884 claimname}{_(Claim)}
9887 \begin_layout LyX-Code
9891 \begin_layout LyX-Code
9895 \begin_layout LyX-Code
9899 \begin_layout LyX-Code
9908 claimname}{_(Claim)}}
9911 \begin_layout LyX-Code
9915 \begin_layout Standard
9916 The key to correct translation of the user visible text is the definition
9918 \begin_inset Flex CharStyle:Code
9921 \begin_layout Plain Layout
9929 in the language preamble.
9930 This command holds the name of the theorem that will appear in the output.
9932 \begin_inset Flex CharStyle:Code
9935 \begin_layout Plain Layout
9941 then uses the commands offered by the babel package to redefine
9942 \begin_inset Flex CharStyle:Code
9945 \begin_layout Plain Layout
9953 for each used language in multilanguage documents.
9957 \begin_layout Description
9958 \begin_inset Flex CharStyle:Code
9961 \begin_layout Plain Layout
9967 The name of the corresponding LaTeX stuff.
9968 Either the environment or command name.
9971 \begin_layout Description
9972 \begin_inset Flex CharStyle:Code
9975 \begin_layout Plain Layout
9981 An optional parameter for the corresponding
9982 \begin_inset Flex CharStyle:Code
9985 \begin_layout Plain Layout
9992 This parameter cannot be changed from within LyX.
9995 \begin_layout Description
9996 \begin_inset Flex CharStyle:Code
9999 \begin_layout Plain Layout
10006 \begin_inset CommandInset label
10008 name "des:LatexType"
10013 \begin_inset Flex CharStyle:Code
10016 \begin_layout Plain Layout
10021 , Command, Environment, Item_Environment,
10027 \begin_inset Flex CharStyle:Code
10030 \begin_layout Plain Layout
10031 List_Environment, Bib_Environment
10036 ] How the layout should be translated into LaTeX.
10040 \begin_layout Plain Layout
10041 \begin_inset Flex CharStyle:Code
10044 \begin_layout Plain Layout
10050 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10051 Visit the SGML class files for specific examples.
10060 \begin_layout Itemize
10061 \begin_inset Flex CharStyle:Code
10064 \begin_layout Plain Layout
10070 means nothing special.
10074 \begin_layout Itemize
10075 \begin_inset Flex CharStyle:Code
10078 \begin_layout Plain Layout
10085 \begin_inset Flex CharStyle:Code
10088 \begin_layout Plain Layout
10095 {\SpecialChar \ldots{}
10104 \begin_layout Itemize
10105 \begin_inset Flex CharStyle:Code
10108 \begin_layout Plain Layout
10115 \begin_inset Flex CharStyle:Code
10118 \begin_layout Plain Layout
10125 }\SpecialChar \ldots{}
10141 \begin_layout Itemize
10142 \begin_inset Flex CharStyle:Code
10145 \begin_layout Plain Layout
10152 \begin_inset Flex CharStyle:Code
10155 \begin_layout Plain Layout
10162 \begin_inset Flex CharStyle:Code
10165 \begin_layout Plain Layout
10173 is generated for each paragraph of this environment.
10177 \begin_layout Itemize
10178 \begin_inset Flex CharStyle:Code
10181 \begin_layout Plain Layout
10188 \begin_inset Flex CharStyle:Code
10191 \begin_layout Plain Layout
10198 \begin_inset Flex CharStyle:Code
10201 \begin_layout Plain Layout
10207 is passed as an argument to the environment.
10209 \begin_inset Flex CharStyle:Code
10212 \begin_layout Plain Layout
10218 can be defined in the
10219 \begin_inset Flex CharStyle:MenuItem
10222 \begin_layout Plain Layout
10227 ayout\SpecialChar \menuseparator
10241 \begin_layout Standard
10242 Putting the last few things together, the LaTeX output will be either:
10245 \begin_layout LyX-Code
10248 latexname[latexparam]{\SpecialChar \ldots{}
10252 \begin_layout Standard
10256 \begin_layout LyX-Code
10259 begin{latexname}[latexparam] \SpecialChar \ldots{}
10265 \begin_layout Standard
10266 depending upon the LaTeX type.
10270 \begin_layout Description
10271 \begin_inset Flex CharStyle:Code
10274 \begin_layout Plain Layout
10281 \begin_inset Flex CharStyle:Code
10284 \begin_layout Plain Layout
10290 ] If you put layouts into environments, the leftmargins are not simply added,
10291 but added with a factor
10292 \begin_inset Formula $\frac{4}{depth+4}$
10296 Note that this parameter is also used when the margin is defined as
10297 \begin_inset Flex CharStyle:Code
10300 \begin_layout Plain Layout
10307 \begin_inset Flex CharStyle:Code
10310 \begin_layout Plain Layout
10317 Then it is added to the manual or dynamic margin.
10319 \begin_inset Newline newline
10322 The argument is passed as a string.
10324 \begin_inset Quotes eld
10328 \begin_inset Flex CharStyle:Code
10331 \begin_layout Plain Layout
10338 \begin_inset Quotes erd
10341 means that the paragraph is indented with the width of
10342 \begin_inset Quotes eld
10346 \begin_inset Flex CharStyle:Code
10349 \begin_layout Plain Layout
10356 \begin_inset Quotes erd
10359 in the normal font.
10360 You can get a negative width by prefixing the string with
10361 \begin_inset Quotes eld
10365 \begin_inset Flex CharStyle:Code
10368 \begin_layout Plain Layout
10375 \begin_inset Quotes erd
10379 This way was chosen so that the look is the same with each used screen
10384 \begin_layout Description
10385 \begin_inset Flex CharStyle:Code
10388 \begin_layout Plain Layout
10395 \begin_inset Flex CharStyle:Code
10398 \begin_layout Plain Layout
10403 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10409 \begin_inset Newline newline
10412 The kind of margin that the layout has on the left side.
10414 \begin_inset Flex CharStyle:Code
10417 \begin_layout Plain Layout
10423 just means a fixed margin.
10425 \begin_inset Flex CharStyle:Code
10428 \begin_layout Plain Layout
10434 means that the left margin depends on the string entered in the
10435 \begin_inset Flex CharStyle:MenuItem
10438 \begin_layout Plain Layout
10439 Edit\SpecialChar \menuseparator
10441 \begin_inset space ~
10450 This is used to typeset nice lists without tabulators.
10452 \begin_inset Flex CharStyle:Code
10455 \begin_layout Plain Layout
10461 means that the margin depends on the size of the label.
10462 This is used for automatic enumerated headlines.
10463 It is obvious that the headline
10464 \begin_inset Quotes eld
10467 5.4.3.2.1 Very long headline
10468 \begin_inset Quotes erd
10471 must have a wider left margin (as wide as
10472 \begin_inset Quotes eld
10476 \begin_inset Quotes erd
10479 plus the space) than
10480 \begin_inset Quotes eld
10483 3.2 Very long headline
10484 \begin_inset Quotes erd
10488 \begin_inset Quotes eld
10492 \begin_inset Quotes erd
10495 are not able to do this.
10497 \begin_inset Flex CharStyle:Code
10500 \begin_layout Plain Layout
10506 is similar, but only the very first row of the paragraph is dynamic, while
10507 the others are static; this is used, for example, for descriptions.
10509 \begin_inset Flex CharStyle:Code
10512 \begin_layout Plain Layout
10518 means the margin is chosen in a way that the longest row of this paragraph
10519 fits to the right margin.
10520 This is used to typeset an address on the right edge of the page.
10523 \begin_layout Description
10524 \begin_inset Flex CharStyle:Code
10527 \begin_layout Plain Layout
10534 \begin_inset Flex CharStyle:Code
10537 \begin_layout Plain Layout
10546 \begin_inset Flex CharStyle:Code
10549 \begin_layout Plain Layout
10555 ] Whether fragile commands in this layout should be
10556 \begin_inset Flex CharStyle:Code
10559 \begin_layout Plain Layout
10572 whether this command should itself be protected.)
10575 \begin_layout Description
10576 \begin_inset Flex CharStyle:Code
10579 \begin_layout Plain Layout
10586 \begin_inset Flex CharStyle:Code
10589 \begin_layout Plain Layout
10596 \begin_inset Flex CharStyle:Code
10599 \begin_layout Plain Layout
10607 ] Whether newlines are translated into LaTeX newlines (
10608 \begin_inset Flex CharStyle:Code
10611 \begin_layout Plain Layout
10622 The translation can be switched off to allow more comfortable LaTeX editing
10626 \begin_layout Description
10627 \begin_inset Flex CharStyle:Code
10630 \begin_layout Plain Layout
10637 \begin_inset Flex CharStyle:Code
10640 \begin_layout Plain Layout
10647 \begin_inset Flex CharStyle:Code
10650 \begin_layout Plain Layout
10658 ] Whether the following Paragraph is allowed to indent its very first row.
10660 \begin_inset Flex CharStyle:Code
10663 \begin_layout Plain Layout
10669 means that it is not allowed to do so;
10670 \begin_inset Flex CharStyle:Code
10673 \begin_layout Plain Layout
10679 means it could do so if it wants to.
10682 \begin_layout Description
10683 \begin_inset Flex CharStyle:Code
10686 \begin_layout Plain Layout
10692 Name of a layout that has replaced this layout.
10693 This is used to rename a layout, while keeping backward compatibility.
10696 \begin_layout Description
10697 \begin_inset Flex CharStyle:Code
10700 \begin_layout Plain Layout
10707 \begin_inset Flex CharStyle:Code
10710 \begin_layout Plain Layout
10716 ] The number of optional arguments that can be used with this layout.
10717 This is useful for things like section headings, and only makes sense with
10721 \begin_layout Description
10722 \begin_inset Flex CharStyle:Code
10725 \begin_layout Plain Layout
10732 \begin_inset Flex CharStyle:Code
10735 \begin_layout Plain Layout
10741 ] The indent of the very first line of a paragraph.
10743 \begin_inset Flex CharStyle:Code
10746 \begin_layout Plain Layout
10752 will be fixed for a certain layout.
10753 The exception is Standard layout, since the indentation of a Standard layout
10754 paragraph can be prohibited with
10755 \begin_inset Flex CharStyle:Code
10758 \begin_layout Plain Layout
10765 Also, Standard layout paragraphs inside environments use the
10766 \begin_inset Flex CharStyle:Code
10769 \begin_layout Plain Layout
10775 of the environment, not their native one.
10776 For example, Standard paragraphs inside an enumeration are not indented.
10779 \begin_layout Description
10780 \begin_inset Flex CharStyle:Code
10783 \begin_layout Plain Layout
10790 \begin_inset Flex CharStyle:Code
10793 \begin_layout Plain Layout
10799 ] The vertical space between two paragraphs of this layout.
10802 \begin_layout Description
10803 \begin_inset Flex CharStyle:Code
10806 \begin_layout Plain Layout
10813 \begin_inset Flex CharStyle:Code
10816 \begin_layout Plain Layout
10822 ] LyX allows the user to choose either
10823 \begin_inset Quotes eld
10827 \begin_inset Quotes erd
10831 \begin_inset Quotes eld
10835 \begin_inset Quotes erd
10838 to typeset a document.
10840 \begin_inset Quotes eld
10844 \begin_inset Quotes erd
10847 is chosen, this value is completely ignored.
10849 \begin_inset Quotes eld
10853 \begin_inset Quotes erd
10856 is chosen, the parindent of a LaTeXtype
10857 \begin_inset Quotes eld
10861 \begin_inset Quotes erd
10864 layout is ignored and all paragraphs are separated by this parskip argument.
10865 The vertical space is calculated with
10866 \begin_inset Flex CharStyle:Code
10869 \begin_layout Plain Layout
10871 \begin_inset space ~
10880 \begin_inset Flex CharStyle:Code
10883 \begin_layout Plain Layout
10889 is the height of a row with the normal font.
10890 This way, the look stays the same with different screen fonts.
10893 \begin_layout Description
10894 \begin_inset Flex CharStyle:Code
10897 \begin_layout Plain Layout
10904 \begin_inset CommandInset label
10906 name "des:PathThru"
10913 \begin_inset Flex CharStyle:Code
10916 \begin_layout Plain Layout
10927 \begin_inset Flex CharStyle:Code
10930 \begin_layout Plain Layout
10936 ] Whether the contents of this paragraph should be output in raw form, meaning
10937 without special translations that LaTeX would require.
10940 \begin_layout Description
10941 \begin_inset Flex CharStyle:Code
10944 \begin_layout Plain Layout
10951 \begin_inset CommandInset label
10953 name "des:Preamble"
10957 Information to be included in the LaTeX preamble when this style is used.
10958 Used to define macros, load packages, etc., required by this particular
10961 \begin_inset Quotes eld
10965 \begin_inset Flex CharStyle:Code
10968 \begin_layout Plain Layout
10975 \begin_inset Quotes erd
10981 \begin_layout Description
10982 \begin_inset Flex CharStyle:Code
10985 \begin_layout Plain Layout
10992 \begin_inset Flex CharStyle:Code
10995 \begin_layout Plain Layout
11002 \begin_inset CommandInset label
11004 name "des:Requires"
11008 Whether the layout requires the feature
11009 \begin_inset Flex CharStyle:Code
11012 \begin_layout Plain Layout
11019 See the description of
11020 \begin_inset Flex CharStyle:Code
11023 \begin_layout Plain Layout
11030 \begin_inset CommandInset ref
11031 LatexCommand pageref
11032 reference "des:FreeSpacing"
11036 ) for information on `features'.
11040 \begin_layout Description
11041 \begin_inset Flex CharStyle:Code
11044 \begin_layout Plain Layout
11051 \begin_inset Flex CharStyle:Code
11054 \begin_layout Plain Layout
11061 \begin_inset Flex CharStyle:Code
11064 \begin_layout Plain Layout
11073 \begin_layout Description
11074 \begin_inset Flex CharStyle:Code
11077 \begin_layout Plain Layout
11084 \begin_inset Flex CharStyle:Code
11087 \begin_layout Plain Layout
11092 , onehalf, double, other
11101 ] This defines what the default spacing should be in the layout.
11103 \begin_inset Flex CharStyle:Code
11106 \begin_layout Plain Layout
11113 \begin_inset Flex CharStyle:Code
11116 \begin_layout Plain Layout
11123 \begin_inset Flex CharStyle:Code
11126 \begin_layout Plain Layout
11132 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11133 If you specify the argument
11134 \begin_inset Flex CharStyle:Code
11137 \begin_layout Plain Layout
11143 , then you should also provide a numerical argument which will be the actual
11145 Note that, contrary to other parameters,
11146 \begin_inset Flex CharStyle:Code
11149 \begin_layout Plain Layout
11155 implies the generation of specific LaTeX code, using the package
11158 \begin_inset Flex CharStyle:Code
11161 \begin_layout Plain Layout
11170 \begin_layout Description
11171 \begin_inset Flex CharStyle:Code
11174 \begin_layout Plain Layout
11180 The font used for the text body .
11182 \begin_inset CommandInset ref
11184 reference "sub:Font-description"
11191 \begin_layout Description
11192 \begin_inset Flex CharStyle:Code
11195 \begin_layout Plain Layout
11203 The level of the style in the table of contents.
11204 This is used for automatic numbering of section headings.
11207 \begin_layout Description
11208 \begin_inset Flex CharStyle:Code
11211 \begin_layout Plain Layout
11218 \begin_inset Flex CharStyle:Code
11221 \begin_layout Plain Layout
11227 ] The vertical space with which the very first of a chain of paragraphs
11228 with this layout is separated from the previous paragraph.
11229 If the previous paragraph has another layout, the separations are not simply
11230 added, but the maximum is taken.
11233 \begin_layout Subsection
11235 \begin_inset CommandInset label
11244 \begin_layout Standard
11245 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11246 define the floats (
11247 \begin_inset Flex CharStyle:MenuItem
11250 \begin_layout Plain Layout
11257 \begin_inset Flex CharStyle:MenuItem
11260 \begin_layout Plain Layout
11266 , \SpecialChar \ldots{}
11267 ) in the text class itself.
11268 Standard floats are included in the file
11269 \begin_inset Flex CharStyle:Code
11272 \begin_layout Plain Layout
11278 , so you may have to do no more than add
11281 \begin_layout LyX-Code
11282 Input stdfloats.inc
11285 \begin_layout Standard
11286 to your layout file.
11287 If you want to implement a text class that proposes some other float types
11288 (like the AGU class bundled with LyX), the information below will hopefully
11292 \begin_layout Description
11293 \begin_inset Flex CharStyle:Code
11296 \begin_layout Plain Layout
11303 \begin_inset Flex CharStyle:Code
11306 \begin_layout Plain Layout
11313 \begin_inset Quotes erd
11317 \begin_inset Quotes erd
11320 ] The file name extension of an auxiliary file for the list of figures (or
11322 LaTeX writes the captions to this file.
11325 \begin_layout Description
11326 \begin_inset Flex CharStyle:Code
11329 \begin_layout Plain Layout
11336 \begin_inset Flex CharStyle:Code
11339 \begin_layout Plain Layout
11346 \begin_inset Quotes erd
11350 \begin_inset Quotes erd
11353 ] The string that will be used in the menus and also for the caption.
11354 This is translated to the current language if babel is used.
11357 \begin_layout Description
11358 \begin_inset Flex CharStyle:Code
11361 \begin_layout Plain Layout
11368 \begin_inset Flex CharStyle:Code
11371 \begin_layout Plain Layout
11380 \begin_inset Flex CharStyle:Code
11383 \begin_layout Plain Layout
11390 \begin_inset Flex CharStyle:Code
11393 \begin_layout Plain Layout
11399 if the float is already defined by the LaTeX document class.
11401 \begin_inset Flex CharStyle:Code
11404 \begin_layout Plain Layout
11410 , the float will be defined using the LaTeX package
11411 \begin_inset Flex CharStyle:Code
11414 \begin_layout Plain Layout
11423 \begin_layout Description
11424 \begin_inset Flex CharStyle:Code
11427 \begin_layout Plain Layout
11434 \begin_inset Flex CharStyle:Code
11437 \begin_layout Plain Layout
11444 \begin_inset Quotes erd
11448 \begin_inset Quotes erd
11451 ] The heading used for the list of floats.
11452 This is translated to the document language.
11455 \begin_layout Description
11456 \begin_inset Flex CharStyle:Code
11459 \begin_layout Plain Layout
11466 \begin_inset Flex CharStyle:Code
11469 \begin_layout Plain Layout
11476 \begin_inset Quotes erd
11480 \begin_inset Quotes erd
11483 ] This (optional) argument determines whether floats of this class will
11484 be numbered within some sectional unit of the document.
11485 For example, if within is equal to
11486 \begin_inset Flex CharStyle:Code
11489 \begin_layout Plain Layout
11495 , the floats will be numbered within chapters.
11499 \begin_layout Description
11500 \begin_inset Flex CharStyle:Code
11503 \begin_layout Plain Layout
11510 \begin_inset Flex CharStyle:Code
11513 \begin_layout Plain Layout
11520 \begin_inset Quotes erd
11524 \begin_inset Quotes erd
11527 ] The default placement for the given class of floats.
11528 The string should be as in standard LaTeX:
11529 \begin_inset Flex CharStyle:Code
11532 \begin_layout Plain Layout
11539 \begin_inset Flex CharStyle:Code
11542 \begin_layout Plain Layout
11549 \begin_inset Flex CharStyle:Code
11552 \begin_layout Plain Layout
11559 \begin_inset Flex CharStyle:Code
11562 \begin_layout Plain Layout
11568 for top, bottom, page, and here, respectively.
11572 \begin_layout Plain Layout
11573 Note that the order of these letters in the string is irrelevant, like in
11579 On top of that there is a new type,
11580 \begin_inset Flex CharStyle:Code
11583 \begin_layout Plain Layout
11589 , which does not really correspond to a float, since it means: put it
11590 \begin_inset Quotes eld
11594 \begin_inset Quotes erd
11598 Note however that the
11599 \begin_inset Flex CharStyle:Code
11602 \begin_layout Plain Layout
11608 specifier is special and, because of implementation details, cannot be
11609 used in non-built in float types.
11610 If you do not understand what this means, just use
11611 \begin_inset Quotes eld
11615 \begin_inset Flex CharStyle:Code
11618 \begin_layout Plain Layout
11625 \begin_inset Quotes erd
11631 \begin_layout Description
11632 \begin_inset Flex CharStyle:Code
11635 \begin_layout Plain Layout
11642 \begin_inset Flex CharStyle:Code
11645 \begin_layout Plain Layout
11652 \begin_inset Quotes erd
11656 \begin_inset Quotes erd
11659 ] The style used when defining the float using
11660 \begin_inset Flex CharStyle:Code
11663 \begin_layout Plain Layout
11674 \begin_layout Description
11675 \begin_inset Flex CharStyle:Code
11678 \begin_layout Plain Layout
11685 \begin_inset Flex CharStyle:Code
11688 \begin_layout Plain Layout
11695 \begin_inset Quotes erd
11699 \begin_inset Quotes erd
11703 \begin_inset Quotes eld
11707 \begin_inset Quotes erd
11710 of the new class of floats, like program or algorithm.
11711 After the appropriate
11712 \begin_inset Flex CharStyle:Code
11715 \begin_layout Plain Layout
11724 \begin_inset Flex CharStyle:Code
11727 \begin_layout Plain Layout
11736 \begin_inset Flex CharStyle:Code
11739 \begin_layout Plain Layout
11750 \begin_layout Standard
11751 Note that defining a float with type
11752 \begin_inset Flex CharStyle:Code
11755 \begin_layout Plain Layout
11763 automatically defines the corresponding counter with name
11764 \begin_inset Flex CharStyle:Code
11767 \begin_layout Plain Layout
11778 \begin_layout Subsection
11779 Flex insets and InsetLayout
11780 \begin_inset CommandInset label
11782 name "sub:Flex-insets-and"
11789 \begin_layout Standard
11790 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11791 these are called Flex insets.
11795 \begin_layout Standard
11796 Flex insets come in three different kinds:
11799 \begin_layout Itemize
11801 \begin_inset Flex CharStyle:Code
11804 \begin_layout Plain Layout
11810 ): These define semantic markup corresponding to such LaTeX commands as
11812 \begin_inset Flex CharStyle:Code
11815 \begin_layout Plain Layout
11824 \begin_inset Flex CharStyle:Code
11827 \begin_layout Plain Layout
11838 \begin_layout Itemize
11840 \begin_inset Flex CharStyle:Code
11843 \begin_layout Plain Layout
11849 ): These can be used to define custom collapsible insets, similar to TeX
11850 code, footnote, and the like.
11851 An obvious example is an endnote inset, which is defined in the
11852 \begin_inset Flex CharStyle:Code
11855 \begin_layout Plain Layout
11864 \begin_layout Itemize
11866 \begin_inset Flex CharStyle:Code
11869 \begin_layout Plain Layout
11875 ): For use with DocBook classes.
11878 \begin_layout Standard
11879 Flex insets are defined using the
11880 \begin_inset Flex CharStyle:Code
11883 \begin_layout Plain Layout
11889 tag, which shall be explained in a moment.
11892 \begin_layout Standard
11894 \begin_inset Flex CharStyle:Code
11897 \begin_layout Plain Layout
11903 tag also serves another function: It can be used to customize the general
11904 layout of many different types of insets.
11906 \begin_inset Flex CharStyle:Code
11909 \begin_layout Plain Layout
11915 can be used to customize the layout parameters for footnotes, marginal
11916 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11917 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11918 define Flex insets.
11921 \begin_layout Standard
11923 \begin_inset Flex CharStyle:Code
11926 \begin_layout Plain Layout
11932 definition must begin with a line of the form:
11935 \begin_layout LyX-Code
11939 \begin_layout Standard
11941 \begin_inset Flex CharStyle:Code
11944 \begin_layout Plain Layout
11950 indicates the inset whose layout is being defined, and here there are two
11954 \begin_layout Enumerate
11955 The layout for a pre-existing inset is being modified.
11956 In this case, can be
11957 \begin_inset Flex CharStyle:Code
11960 \begin_layout Plain Layout
11966 any one of the following:
11967 \begin_inset Flex CharStyle:Code
11970 \begin_layout Plain Layout
11977 \begin_inset Flex CharStyle:Code
11980 \begin_layout Plain Layout
11987 \begin_inset Flex CharStyle:Code
11990 \begin_layout Plain Layout
11997 \begin_inset Flex CharStyle:Code
12000 \begin_layout Plain Layout
12007 \begin_inset Flex CharStyle:Code
12010 \begin_layout Plain Layout
12017 \begin_inset Flex CharStyle:Code
12020 \begin_layout Plain Layout
12027 \begin_inset Flex CharStyle:Code
12030 \begin_layout Plain Layout
12037 \begin_inset Flex CharStyle:Code
12040 \begin_layout Plain Layout
12047 \begin_inset Flex CharStyle:Code
12050 \begin_layout Plain Layout
12057 \begin_inset Flex CharStyle:Code
12060 \begin_layout Plain Layout
12067 \begin_inset Flex CharStyle:Code
12070 \begin_layout Plain Layout
12077 \begin_inset Flex CharStyle:Code
12080 \begin_layout Plain Layout
12087 \begin_inset Flex CharStyle:Code
12090 \begin_layout Plain Layout
12097 \begin_inset Flex CharStyle:Code
12100 \begin_layout Plain Layout
12107 \begin_inset Flex CharStyle:Code
12110 \begin_layout Plain Layout
12117 \begin_inset Flex CharStyle:Code
12120 \begin_layout Plain Layout
12127 \begin_inset Flex CharStyle:Code
12130 \begin_layout Plain Layout
12137 \begin_inset Flex CharStyle:Code
12140 \begin_layout Plain Layout
12147 \begin_inset Flex CharStyle:Code
12150 \begin_layout Plain Layout
12157 \begin_inset Flex CharStyle:Code
12160 \begin_layout Plain Layout
12170 \begin_layout Enumerate
12171 The layout for a Flex inset is being defined.
12173 \begin_inset Flex CharStyle:Code
12176 \begin_layout Plain Layout
12182 can be any valid identifier not used by a pre-existing inset.
12183 Note that the definition of a flex inset must
12188 \begin_inset Flex CharStyle:Code
12191 \begin_layout Plain Layout
12200 \begin_layout Standard
12202 \begin_inset Flex CharStyle:Code
12205 \begin_layout Plain Layout
12211 definition can contain the following entries:
12214 \begin_layout Description
12215 \begin_inset Flex CharStyle:Code
12218 \begin_layout Plain Layout
12224 The color for the inset's background.
12225 The valid colors are defined in
12226 \begin_inset Flex CharStyle:Code
12229 \begin_layout Plain Layout
12238 \begin_layout Description
12239 \begin_inset Flex CharStyle:Code
12242 \begin_layout Plain Layout
12248 As with paragraph styles (see page
12249 \begin_inset CommandInset ref
12251 reference "des:CopyStyle"
12258 \begin_layout Description
12259 \begin_inset Flex CharStyle:Code
12262 \begin_layout Plain Layout
12269 \begin_inset Flex CharStyle:Code
12272 \begin_layout Plain Layout
12281 \begin_inset Flex CharStyle:Code
12284 \begin_layout Plain Layout
12290 ] Indicates whether the user may employ the Paragraph Settings dialog to
12291 customize the paragraph.
12294 \begin_layout Description
12295 \begin_inset Flex CharStyle:Code
12298 \begin_layout Plain Layout
12305 \begin_inset Flex CharStyle:Code
12308 \begin_layout Plain Layout
12315 \begin_inset Flex CharStyle:Code
12318 \begin_layout Plain Layout
12325 \begin_inset Flex CharStyle:Code
12328 \begin_layout Plain Layout
12334 , describing the rendering style used for the inset's frame and buttons.
12335 Footnotes generally use
12336 \begin_inset Flex CharStyle:Code
12339 \begin_layout Plain Layout
12345 , ERT insets generally
12346 \begin_inset Flex CharStyle:Code
12349 \begin_layout Plain Layout
12355 , and character styles
12356 \begin_inset Flex CharStyle:Code
12359 \begin_layout Plain Layout
12368 \begin_layout Description
12369 \begin_inset Flex CharStyle:Code
12372 \begin_layout Plain Layout
12378 Required at the end of the InsetLayout declarations.
12381 \begin_layout Description
12382 \begin_inset Flex CharStyle:Code
12385 \begin_layout Plain Layout
12391 The font used for both the text body
12397 \begin_inset space ~
12401 \begin_inset CommandInset ref
12403 reference "sub:Font-description"
12408 Note that defining this font automatically defines the
12409 \begin_inset Flex CharStyle:Code
12412 \begin_layout Plain Layout
12418 to the same value, so define this first and define
12419 \begin_inset Flex CharStyle:Code
12422 \begin_layout Plain Layout
12428 later if you want them to be different.
12431 \begin_layout Description
12432 \begin_inset Flex CharStyle:Code
12435 \begin_layout Plain Layout
12442 \begin_inset Quotes eld
12446 \begin_inset Quotes erd
12449 language, leading to Left-to-Right (latin) output, e.
12450 \begin_inset space \thinspace{}
12454 \begin_inset space \space{}
12457 in TeX code or URL.
12461 \begin_layout Description
12462 \begin_inset Flex CharStyle:Code
12465 \begin_layout Plain Layout
12472 \begin_inset Flex CharStyle:Code
12475 \begin_layout Plain Layout
12484 \begin_inset Flex CharStyle:Code
12487 \begin_layout Plain Layout
12493 ] Indicates whether the PlainLayout should be used or, instead, the user
12494 can change the paragraph style used in the inset.
12497 \begin_layout Description
12498 \begin_inset Flex CharStyle:Code
12501 \begin_layout Plain Layout
12507 As with paragraph styles (see page
12508 \begin_inset CommandInset ref
12509 LatexCommand pageref
12510 reference "des:FreeSpacing"
12517 \begin_layout Description
12518 \begin_inset Flex CharStyle:Code
12521 \begin_layout Plain Layout
12528 \begin_inset Flex CharStyle:Code
12531 \begin_layout Plain Layout
12540 \begin_inset Flex CharStyle:Code
12543 \begin_layout Plain Layout
12549 ] Whether to include the contents of this inset in the strings generated
12550 for the `Outline' pane.
12551 One would not, for example, want the content of a footnote in a section
12552 header to be included in the TOC displayed in the outline, but one would
12553 normally want the content of a character style displayed.
12554 Default is false: not to include.
12557 \begin_layout Description
12558 \begin_inset Flex CharStyle:Code
12561 \begin_layout Plain Layout
12567 As with paragraph styles (see page
12568 \begin_inset CommandInset ref
12569 LatexCommand pageref
12570 reference "des:KeepEmpty"
12577 \begin_layout Description
12578 \begin_inset Flex CharStyle:Code
12581 \begin_layout Plain Layout
12587 The font used for the label.
12589 \begin_inset space ~
12593 \begin_inset CommandInset ref
12595 reference "sub:Font-description"
12600 Note that this definition can never appear before
12601 \begin_inset Flex CharStyle:Code
12604 \begin_layout Plain Layout
12610 , lest it be ineffective.
12613 \begin_layout Description
12614 \begin_inset Flex CharStyle:Code
12617 \begin_layout Plain Layout
12623 What will be displayed on the button or elsewhere as the inset label.
12624 Some inset types (TeX code and Branch) modify this label on the fly.
12627 \begin_layout Description
12628 \begin_inset Flex CharStyle:Code
12631 \begin_layout Plain Layout
12637 The name of the corresponding LaTeX stuff.
12638 Either the environment or command name.
12641 \begin_layout Description
12642 \begin_inset Flex CharStyle:Code
12645 \begin_layout Plain Layout
12651 The optional parameter for the corresponding
12652 \begin_inset Flex CharStyle:Code
12655 \begin_layout Plain Layout
12661 stuff, including possible bracket pairs like
12662 \begin_inset Flex CharStyle:Code
12665 \begin_layout Plain Layout
12672 This parameter cannot be changed from within LyX.
12675 \begin_layout Description
12676 \begin_inset Flex CharStyle:Code
12679 \begin_layout Plain Layout
12685 As with paragraph styles (see page
12686 \begin_inset CommandInset ref
12687 LatexCommand pageref
12688 reference "des:LatexType"
12695 \begin_layout Description
12696 \begin_inset Flex CharStyle:Code
12699 \begin_layout Plain Layout
12706 \begin_inset Flex CharStyle:Code
12709 \begin_layout Plain Layout
12716 \begin_inset Flex CharStyle:Code
12719 \begin_layout Plain Layout
12726 \begin_inset Flex CharStyle:Code
12729 \begin_layout Plain Layout
12736 \begin_inset Flex CharStyle:Code
12739 \begin_layout Plain Layout
12745 (indicating a dummy definition ending definitions of charstyles, etc).
12746 This entry is required in and is only meaningful for Flex insets.
12747 Among other things, it determines on which menu this inset will appear.
12750 \begin_layout Description
12751 \begin_inset Flex CharStyle:Code
12754 \begin_layout Plain Layout
12761 \begin_inset Flex CharStyle:Code
12764 \begin_layout Plain Layout
12773 \begin_inset Flex CharStyle:Code
12776 \begin_layout Plain Layout
12782 ] Whether multiple paragraphs are permitted in this inset.
12783 This will also set CustomPars to the same value and ForcePlain to the opposite
12785 These can be reset to other values, if they are used
12792 \begin_layout Description
12793 \begin_inset Flex CharStyle:Code
12796 \begin_layout Plain Layout
12803 \begin_inset Flex CharStyle:Code
12806 \begin_layout Plain Layout
12815 \begin_inset Flex CharStyle:Code
12818 \begin_layout Plain Layout
12824 ] Whether fragile commands in this layout should be
12825 \begin_inset Flex CharStyle:Code
12828 \begin_layout Plain Layout
12841 whether the command should itself be protected.)
12844 \begin_layout Description
12845 \begin_inset Flex CharStyle:Code
12848 \begin_layout Plain Layout
12855 \begin_inset Flex CharStyle:Code
12858 \begin_layout Plain Layout
12867 \begin_inset Flex CharStyle:Code
12870 \begin_layout Plain Layout
12876 ] As with paragraph styles (see page
12877 \begin_inset CommandInset ref
12879 reference "des:PathThru"
12886 \begin_layout Description
12887 \begin_inset Flex CharStyle:Code
12890 \begin_layout Plain Layout
12896 As with paragraph styles (see page
12897 \begin_inset CommandInset ref
12898 LatexCommand pageref
12899 reference "des:Preamble"
12906 \begin_layout Description
12907 \begin_inset Flex CharStyle:Code
12910 \begin_layout Plain Layout
12917 \begin_inset Flex CharStyle:Code
12920 \begin_layout Plain Layout
12926 ] As with paragraph styles (see page
12927 \begin_inset CommandInset ref
12928 LatexCommand pageref
12929 reference "des:Requires"
12936 \begin_layout Subsection
12938 \begin_inset CommandInset label
12940 name "sub:Counters"
12947 \begin_layout Standard
12948 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12950 \begin_inset Flex CharStyle:MenuItem
12953 \begin_layout Plain Layout
12960 \begin_inset Flex CharStyle:MenuItem
12963 \begin_layout Plain Layout
12969 , \SpecialChar \ldots{}
12970 ) in the text class itself.
12971 The standard counters are defined in the file
12972 \begin_inset Flex CharStyle:Code
12975 \begin_layout Plain Layout
12981 , so you may have to do no more than add
12984 \begin_layout LyX-Code
12985 Input stdcounters.inc
12988 \begin_layout Standard
12989 to your layout file to get them to work.
12990 But if you want to define custom counters, then you can do so.
12991 The counter declaration must begin with:
12994 \begin_layout LyX-Code
12998 \begin_layout Standard
12999 where of course `name' is replaced by the name of the counter.
13000 And it must end with
13001 \begin_inset Quotes eld
13005 \begin_inset Flex CharStyle:Code
13008 \begin_layout Plain Layout
13015 \begin_inset Quotes erd
13019 The following parameters can also be used:
13022 \begin_layout Description
13023 \begin_inset Flex CharStyle:Code
13026 \begin_layout Plain Layout
13027 LabelString [string=""]
13032 when this is defined, this string defines how the counter is displayed.
13033 Setting this value sets
13034 \begin_inset Flex CharStyle:Code
13037 \begin_layout Plain Layout
13038 LabelStringAppendix
13044 The following special constructs can be used in the string:
13048 \begin_layout Itemize
13049 \begin_inset Flex CharStyle:Code
13052 \begin_layout Plain Layout
13060 will be replaced by the expansion of the
13061 \begin_inset Flex CharStyle:Code
13064 \begin_layout Plain Layout
13071 \begin_inset Flex CharStyle:Code
13074 \begin_layout Plain Layout
13075 LabelStringAppendix
13081 \begin_inset Flex CharStyle:Code
13084 \begin_layout Plain Layout
13094 \begin_layout Itemize
13095 counter values can be expressed using LaTeX-like macros
13096 \begin_inset Flex CharStyle:Code
13099 \begin_layout Plain Layout
13116 \begin_inset Flex CharStyle:Code
13119 \begin_layout Plain Layout
13131 \begin_layout Plain Layout
13141 Actually, the situation is a bit more complicated: any
13160 other than those described below will produce arabic numerals.
13161 It would not be surprising to see this change in the future.
13167 \begin_inset Flex CharStyle:Code
13170 \begin_layout Plain Layout
13176 : 1, 2, 3,\SpecialChar \ldots{}
13178 \begin_inset Flex CharStyle:Code
13181 \begin_layout Plain Layout
13187 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13189 \begin_inset Flex CharStyle:Code
13192 \begin_layout Plain Layout
13198 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13200 \begin_inset Flex CharStyle:Code
13203 \begin_layout Plain Layout
13209 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13211 \begin_inset Flex CharStyle:Code
13214 \begin_layout Plain Layout
13220 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13222 \begin_inset Flex CharStyle:Code
13225 \begin_layout Plain Layout
13231 for hebrew numerals.
13235 \begin_layout Standard
13236 If LabelString is not defined, a default value is constructed as follows:
13237 if the counter has a master counter
13238 \begin_inset Flex CharStyle:Code
13241 \begin_layout Plain Layout
13248 \begin_inset Flex CharStyle:Code
13251 \begin_layout Plain Layout
13258 \begin_inset Flex CharStyle:Code
13261 \begin_layout Plain Layout
13271 is used; otherwise the string
13272 \begin_inset Flex CharStyle:Code
13275 \begin_layout Plain Layout
13286 \begin_layout Description
13287 \begin_inset Flex CharStyle:Code
13290 \begin_layout Plain Layout
13291 LabelStringAppendix [string=""]
13297 \begin_inset Flex CharStyle:Code
13300 \begin_layout Plain Layout
13306 , but for use in the Appendix.
13309 \begin_layout Description
13310 \begin_inset Flex CharStyle:Code
13313 \begin_layout Plain Layout
13320 \begin_inset Flex CharStyle:Code
13323 \begin_layout Plain Layout
13330 \begin_inset Quotes erd
13334 \begin_inset Quotes erd
13337 ] If this is set to the name of another counter, the present counter will
13338 be reset every time the other one is increased.
13340 \begin_inset Flex CharStyle:Code
13343 \begin_layout Plain Layout
13350 \begin_inset Flex CharStyle:Code
13353 \begin_layout Plain Layout
13362 \begin_layout Subsection
13364 \begin_inset CommandInset label
13366 name "sub:Font-description"
13373 \begin_layout Standard
13374 A font description looks like this:
13377 \begin_layout LyX-Code
13387 \begin_layout LyX-Code
13391 \begin_layout LyX-Code
13395 \begin_layout Standard
13396 The following commands are available:
13399 \begin_layout Description
13400 \begin_inset Flex CharStyle:Code
13403 \begin_layout Plain Layout
13410 \begin_inset Flex CharStyle:Code
13413 \begin_layout Plain Layout
13422 \begin_inset Flex CharStyle:Code
13425 \begin_layout Plain Layout
13432 \begin_inset Flex CharStyle:Code
13435 \begin_layout Plain Layout
13442 \begin_inset Flex CharStyle:Code
13445 \begin_layout Plain Layout
13452 \begin_inset Flex CharStyle:Code
13455 \begin_layout Plain Layout
13462 \begin_inset Flex CharStyle:Code
13465 \begin_layout Plain Layout
13472 \begin_inset Flex CharStyle:Code
13475 \begin_layout Plain Layout
13482 \begin_inset Flex CharStyle:Code
13485 \begin_layout Plain Layout
13492 \begin_inset Flex CharStyle:Code
13495 \begin_layout Plain Layout
13504 \begin_layout Description
13505 \begin_inset Flex CharStyle:Code
13508 \begin_layout Plain Layout
13517 \begin_inset Flex CharStyle:Code
13520 \begin_layout Plain Layout
13531 \begin_inset Flex CharStyle:Code
13534 \begin_layout Plain Layout
13541 \begin_inset Flex CharStyle:Code
13544 \begin_layout Plain Layout
13553 \begin_layout Description
13554 \begin_inset Flex CharStyle:Code
13557 \begin_layout Plain Layout
13564 \begin_inset Flex CharStyle:Code
13567 \begin_layout Plain Layout
13573 ] Valid argument are:
13574 \begin_inset Flex CharStyle:Code
13577 \begin_layout Plain Layout
13584 \begin_inset Flex CharStyle:Code
13587 \begin_layout Plain Layout
13594 \begin_inset Flex CharStyle:Code
13597 \begin_layout Plain Layout
13604 \begin_inset Flex CharStyle:Code
13607 \begin_layout Plain Layout
13614 \begin_inset Flex CharStyle:Code
13617 \begin_layout Plain Layout
13624 \begin_inset Flex CharStyle:Code
13627 \begin_layout Plain Layout
13634 Each of these turns on or off the corresponding attribute.
13637 \begin_layout Description
13638 \begin_inset Flex CharStyle:Code
13641 \begin_layout Plain Layout
13650 \begin_inset Flex CharStyle:Code
13653 \begin_layout Plain Layout
13664 \begin_inset Flex CharStyle:Code
13667 \begin_layout Plain Layout
13676 \begin_layout Description
13677 \begin_inset Flex CharStyle:Code
13680 \begin_layout Plain Layout
13689 \begin_inset Flex CharStyle:Code
13692 \begin_layout Plain Layout
13703 \begin_inset Flex CharStyle:Code
13706 \begin_layout Plain Layout
13713 \begin_inset Flex CharStyle:Code
13716 \begin_layout Plain Layout
13723 \begin_inset Flex CharStyle:Code
13726 \begin_layout Plain Layout
13735 \begin_layout Description
13736 \begin_inset Flex CharStyle:Code
13739 \begin_layout Plain Layout
13746 \begin_inset Flex CharStyle:Code
13749 \begin_layout Plain Layout
13756 \begin_inset Flex CharStyle:Code
13759 \begin_layout Plain Layout
13766 \begin_inset Flex CharStyle:Code
13769 \begin_layout Plain Layout
13778 \begin_inset Flex CharStyle:Code
13781 \begin_layout Plain Layout
13788 \begin_inset Flex CharStyle:Code
13791 \begin_layout Plain Layout
13798 \begin_inset Flex CharStyle:Code
13801 \begin_layout Plain Layout
13808 \begin_inset Flex CharStyle:Code
13811 \begin_layout Plain Layout
13818 \begin_inset Flex CharStyle:Code
13821 \begin_layout Plain Layout
13830 \begin_layout Subsection
13831 Upgrading old layout files
13834 \begin_layout Standard
13835 The file format of layout files changes from time to time, so old layout
13836 files need to be converted.
13837 This process has been automated since LyX 1.4.0: If LyX reads an old format
13838 layout file it will call the conversion tool
13839 \begin_inset Flex CharStyle:Code
13842 \begin_layout Plain Layout
13843 LyXDir/scripts/layout2layout.py
13848 and convert it to a temporary file in current format.
13849 The original file is left untouched.
13850 If you want to convert the layout file permanently, just call the converter
13854 \begin_layout LyX-Code
13855 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13858 \begin_layout Standard
13859 (You need to replace
13860 \begin_inset Flex CharStyle:Code
13863 \begin_layout Plain Layout
13869 with the name of your LyX system directory, unless you happen to have defined
13870 such an environment variable.) Then copy
13871 \begin_inset Flex CharStyle:Code
13874 \begin_layout Plain Layout
13881 \begin_inset Flex CharStyle:Code
13884 \begin_layout Plain Layout
13893 \begin_layout Standard
13894 The automatic conversion only handles syntax changes.
13895 It cannot handle the case where the contents of included files was changed,
13896 so these will have to be converted separately.
13899 \begin_layout Section
13901 \begin_inset CommandInset label
13903 name "sec:Creating-Templates"
13910 \begin_layout Standard
13911 Templates are created just like usual documents.
13912 The only difference is that usual documents contain all possible settings,
13913 including the font scheme and the paper size.
13914 Usually a user doesn't want a template to overwrite his defaults in these
13916 For that reason, the designer of a template should remove the corresponding
13918 \begin_inset Flex CharStyle:Code
13921 \begin_layout Plain Layout
13930 \begin_inset Flex CharStyle:Code
13933 \begin_layout Plain Layout
13941 from the template LyX file.
13942 This can be done with any simple text-editor, for example
13943 \begin_inset Flex CharStyle:Code
13946 \begin_layout Plain Layout
13953 \begin_inset Flex CharStyle:Code
13956 \begin_layout Plain Layout
13966 \begin_layout Standard
13967 Put the edited template files you create in
13968 \begin_inset Flex CharStyle:Code
13971 \begin_layout Plain Layout
13977 , copy the ones you use from the global template directory in
13978 \begin_inset Flex CharStyle:Code
13981 \begin_layout Plain Layout
13987 to the same place, and redefine the template path in the
13988 \begin_inset Flex CharStyle:MenuItem
13991 \begin_layout Plain Layout
13992 Tools\SpecialChar \menuseparator
13993 Preferences\SpecialChar \menuseparator
14002 \begin_layout Standard
14003 Note that there is a template which has a particular meaning:
14004 \begin_inset Flex CharStyle:Code
14007 \begin_layout Plain Layout
14014 This template is loaded every time you create a new document with
14015 \begin_inset Flex CharStyle:MenuItem
14018 \begin_layout Plain Layout
14019 File\SpecialChar \menuseparator
14025 in order to provide useful defaults.
14026 To create this template from inside LyX, all you have to do is to open
14027 a document with the correct settings, and use the
14028 \begin_inset Flex CharStyle:MenuItem
14031 \begin_layout Plain Layout
14032 Save as Document Defaults
14040 \begin_layout Chapter
14041 Including External Material
14044 \begin_layout Standard
14045 \begin_inset Box Shadowbox
14054 height_special "totalheight"
14057 \begin_layout Plain Layout
14058 WARNING: This portion of the documentation has not been updated for some
14060 We certainly hope that it is still accurate, but there are no guarantees.
14068 \begin_layout Standard
14069 The use of material from sources external to LyX is covered in detail in
14075 This part of the manual covers what needs to happen behind the scenes for
14076 new sorts of material to be included.
14079 \begin_layout Section
14083 \begin_layout Standard
14084 The external material feature is based on the concept of a
14089 A template is a specification of how LyX should interface with a certain
14091 As bundled, LyX comes with predefined templates for Xfig figures, various
14092 raster format images, chess diagrams, and LilyPond music notation.
14093 You can check the actual list by using the menu
14094 \begin_inset Flex CharStyle:MenuItem
14097 \begin_layout Plain Layout
14098 Insert\SpecialChar \menuseparator
14099 File\SpecialChar \menuseparator
14106 Furthermore, it is possible to roll your own template to support a specific
14108 Later we'll describe in more detail what is involved, and hopefully you
14109 will submit all the templates you create so we can include them in a later
14113 \begin_layout Standard
14114 Another basic idea of the external material feature is to distinguish between
14115 the original file that serves as a base for final material and the produced
14116 file that is included in your exported or printed document.
14117 For example, consider the case of a figure produced with
14118 \begin_inset Flex CharStyle:Code
14121 \begin_layout Plain Layout
14128 The Xfig application itself works on an original file with the
14129 \begin_inset Flex CharStyle:Code
14132 \begin_layout Plain Layout
14139 Within Xfig, you create and change your figure, and when you are done,
14141 \begin_inset Flex CharStyle:Code
14144 \begin_layout Plain Layout
14151 When you want to include the figure in your document, you invoke
14152 \begin_inset Flex CharStyle:Code
14155 \begin_layout Plain Layout
14161 in order to create a PostScript file that can readily be included in your
14164 \begin_inset Flex CharStyle:Code
14167 \begin_layout Plain Layout
14173 file is the original file, and the PostScript file is the produced file.
14176 \begin_layout Standard
14177 This distinction is important in order to allow updating of the material
14178 while you are in the process of writing the document.
14179 Furthermore, it provides us with the flexibility that is needed to support
14180 multiple export formats.
14181 For instance, in the case of a plain text file, it is not exactly an award-winn
14182 ing idea to include the figure as raw PostScript.
14183 Instead, you'd either prefer to just include a reference to the figure
14184 or try to invoke some graphics to ASCII converter to make the final result
14185 look similar to the real graphics.
14186 The external material management allows you to do this, because it is parametri
14187 zed on the different export formats that LyX supports.
14190 \begin_layout Standard
14191 Besides supporting the production of different products according to the
14192 exported format, it supports tight integration with editing and viewing
14194 In the case of an Xfig figure, you are able to invoke Xfig on the original
14195 file with a single click from within the external material dialog in LyX,
14196 and also preview the produced PostScript file with Ghostview with another
14198 No more fiddling around with the command line and/or file browsers to locate
14199 and manipulate the original or produced files.
14200 In this way, you are finally able to take full advantage of the many different
14201 applications that are relevant to use when you write your documents, and
14202 ultimately be more productive.
14205 \begin_layout Section
14206 The external template configuration file
14209 \begin_layout Standard
14210 It is relatively easy to add custom external template definitions to LyX.
14211 However, be aware that doing this in an careless manner most probably
14215 introduce an easily exploitable security hole.
14216 So before you do this, please read the discussion about security in section
14218 \begin_inset CommandInset ref
14220 reference "sec:Security-discussion"
14227 \begin_layout Standard
14228 Having said that, we encourage you to submit any interesting templates that
14233 \begin_layout Standard
14234 The external templates are defined in the
14235 \begin_inset Flex CharStyle:Code
14238 \begin_layout Plain Layout
14239 LyXDir/lib/external_templates
14245 You can place your own version in
14246 \begin_inset Flex CharStyle:Code
14249 \begin_layout Plain Layout
14250 UserDir/external_templates
14258 \begin_layout Standard
14259 A typical template looks like this:
14262 \begin_layout LyX-Code
14266 \begin_layout LyX-Code
14267 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14270 \begin_layout LyX-Code
14274 \begin_layout LyX-Code
14278 \begin_layout LyX-Code
14282 \begin_layout LyX-Code
14286 \begin_layout LyX-Code
14290 \begin_layout LyX-Code
14291 AutomaticProduction true
14294 \begin_layout LyX-Code
14298 \begin_layout LyX-Code
14302 \begin_layout LyX-Code
14306 \begin_layout LyX-Code
14307 TransformCommand Rotate RotationLatexCommand
14310 \begin_layout LyX-Code
14311 TransformCommand Resize ResizeLatexCommand
14314 \begin_layout LyX-Code
14315 Product "$$RotateFront$$ResizeFront
14318 \begin_layout LyX-Code
14323 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14326 \begin_layout LyX-Code
14327 $$ResizeBack$$RotateBack"
14330 \begin_layout LyX-Code
14334 \begin_layout LyX-Code
14335 UpdateResult "$$AbsPath$$Basename.pstex_t"
14338 \begin_layout LyX-Code
14339 Requirement "graphicx"
14342 \begin_layout LyX-Code
14343 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14346 \begin_layout LyX-Code
14347 ReferencedFile latex "$$AbsPath$$Basename.eps"
14350 \begin_layout LyX-Code
14351 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14354 \begin_layout LyX-Code
14358 \begin_layout LyX-Code
14362 \begin_layout LyX-Code
14363 TransformCommand Rotate RotationLatexCommand
14366 \begin_layout LyX-Code
14367 TransformCommand Resize ResizeLatexCommand
14370 \begin_layout LyX-Code
14371 Product "$$RotateFront$$ResizeFront
14374 \begin_layout LyX-Code
14379 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14382 \begin_layout LyX-Code
14383 $$ResizeBack$$RotateBack"
14386 \begin_layout LyX-Code
14387 UpdateFormat pdftex
14390 \begin_layout LyX-Code
14391 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14394 \begin_layout LyX-Code
14395 Requirement "graphicx"
14398 \begin_layout LyX-Code
14399 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14402 \begin_layout LyX-Code
14403 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14406 \begin_layout LyX-Code
14410 \begin_layout LyX-Code
14414 \begin_layout LyX-Code
14415 Product "$$Contents(
14417 "$$AbsPath$$Basename.asc
14422 \begin_layout LyX-Code
14423 UpdateFormat asciixfig
14426 \begin_layout LyX-Code
14427 UpdateResult "$$AbsPath$$Basename.asc"
14430 \begin_layout LyX-Code
14434 \begin_layout LyX-Code
14438 \begin_layout LyX-Code
14439 Product "<graphic fileref=
14441 "$$AbsOrRelPathMaster$$Basename.eps
14446 \begin_layout LyX-Code
14450 \begin_layout LyX-Code
14454 \begin_layout LyX-Code
14455 UpdateResult "$$AbsPath$$Basename.eps"
14458 \begin_layout LyX-Code
14459 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14462 \begin_layout LyX-Code
14463 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14466 \begin_layout LyX-Code
14470 \begin_layout LyX-Code
14471 Product "[XFig: $$FName]"
14474 \begin_layout LyX-Code
14478 \begin_layout LyX-Code
14482 \begin_layout Standard
14483 As you can see, the template is enclosed in
14484 \begin_inset Flex CharStyle:Code
14487 \begin_layout Plain Layout
14493 \SpecialChar \ldots{}
14495 \begin_inset Flex CharStyle:Code
14498 \begin_layout Plain Layout
14505 It contains a header specifying some general settings and, for each supported
14506 primary document file format, a section
14507 \begin_inset Flex CharStyle:Code
14510 \begin_layout Plain Layout
14516 \SpecialChar \ldots{}
14518 \begin_inset Flex CharStyle:Code
14521 \begin_layout Plain Layout
14530 \begin_layout Subsection
14531 The template header
14534 \begin_layout Description
14535 \begin_inset Flex CharStyle:Code
14538 \begin_layout Plain Layout
14539 AutomaticProduction
14540 \begin_inset space ~
14548 Whether the file represented by the template must be generated by LyX.
14549 This command must occur exactly once.
14552 \begin_layout Description
14553 \begin_inset Flex CharStyle:Code
14556 \begin_layout Plain Layout
14558 \begin_inset space ~
14566 A glob pattern that is used in the file dialog to filter out the desired
14568 If there is more than one possible file extension (e.
14569 \begin_inset space \thinspace{}
14573 \begin_inset space \space{}
14577 \begin_inset Flex CharStyle:Code
14580 \begin_layout Plain Layout
14587 \begin_inset Flex CharStyle:Code
14590 \begin_layout Plain Layout
14596 ), use something like
14597 \begin_inset Flex CharStyle:Code
14600 \begin_layout Plain Layout
14607 This command must occur exactly once.
14610 \begin_layout Description
14611 \begin_inset Flex CharStyle:Code
14614 \begin_layout Plain Layout
14616 \begin_inset space ~
14624 The text that is displayed on the button.
14625 This command must occur exactly once.
14628 \begin_layout Description
14629 \begin_inset Flex CharStyle:Code
14632 \begin_layout Plain Layout
14634 \begin_inset space ~
14638 \begin_inset space ~
14646 The help text that is used in the External dialog.
14647 Provide enough information to explain to the user just what the template
14648 can provide him with.
14649 This command must occur exactly once.
14652 \begin_layout Description
14653 \begin_inset Flex CharStyle:Code
14656 \begin_layout Plain Layout
14658 \begin_inset space ~
14666 The file format of the original file.
14667 This must be the name of a format that is known to LyX (see section
14668 \begin_inset CommandInset ref
14670 reference "sec:Formats"
14676 \begin_inset Quotes eld
14680 \begin_inset Flex CharStyle:Code
14683 \begin_layout Plain Layout
14690 \begin_inset Quotes erd
14693 if the template can handle original files of more than one format.
14694 LyX will attempt to interrogate the file itself in order to deduce its
14695 format in this case.
14696 This command must occur exactly once.
14699 \begin_layout Description
14700 \begin_inset Flex CharStyle:Code
14703 \begin_layout Plain Layout
14705 \begin_inset space ~
14713 A unique name for the template.
14714 It must not contain substitution macros (see below).
14717 \begin_layout Description
14718 \begin_inset Flex CharStyle:Code
14721 \begin_layout Plain Layout
14723 \begin_inset space ~
14726 Rotate|Resize|Clip|Extra
14731 This command specifies which transformations are supported by this template.
14732 It may occur zero or more times.
14733 This command enables the corresponding tabs in the external dialog.
14735 \begin_inset Flex CharStyle:Code
14738 \begin_layout Plain Layout
14744 command must have either a corresponding
14745 \begin_inset Flex CharStyle:Code
14748 \begin_layout Plain Layout
14755 \begin_inset Flex CharStyle:Code
14758 \begin_layout Plain Layout
14765 \begin_inset Flex CharStyle:Code
14768 \begin_layout Plain Layout
14775 Otherwise the transformation will not be supported by that format.
14778 \begin_layout Subsection
14782 \begin_layout Description
14783 \begin_inset Flex CharStyle:Code
14786 \begin_layout Plain Layout
14788 \begin_inset space ~
14791 LaTeX|PDFLaTeX|PlainText|DocBook
14796 The primary document file format that this format definition is for.
14797 Not every template has a sensible representation in all document file formats.
14798 Please define nevertheless a
14799 \begin_inset Flex CharStyle:Code
14802 \begin_layout Plain Layout
14808 section for all formats.
14809 Use a dummy text when no representation is available.
14810 Then you can at least see a reference to the external material in the exported
14814 \begin_layout Description
14815 \begin_inset Flex CharStyle:Code
14818 \begin_layout Plain Layout
14820 \begin_inset space ~
14824 \begin_inset space ~
14832 This command defines an additional macro
14833 \begin_inset Flex CharStyle:Code
14836 \begin_layout Plain Layout
14842 for substitution in
14843 \begin_inset Flex CharStyle:Code
14846 \begin_layout Plain Layout
14854 \begin_inset Flex CharStyle:Code
14857 \begin_layout Plain Layout
14863 itself may contain substitution macros.
14864 The advantage over using
14865 \begin_inset Flex CharStyle:Code
14868 \begin_layout Plain Layout
14875 \begin_inset Flex CharStyle:Code
14878 \begin_layout Plain Layout
14884 is that the substituted value of
14885 \begin_inset Flex CharStyle:Code
14888 \begin_layout Plain Layout
14894 is sanitized so that it is a valid optional argument in the document format.
14895 This command may occur zero or more times.
14898 \begin_layout Description
14899 \begin_inset Flex CharStyle:Code
14902 \begin_layout Plain Layout
14904 \begin_inset space ~
14912 The text that is inserted in the exported document.
14913 This is actually the most important command and can be quite complex.
14914 This command must occur exactly once.
14917 \begin_layout Description
14918 \begin_inset Flex CharStyle:Code
14921 \begin_layout Plain Layout
14923 \begin_inset space ~
14931 This command specifies a preamble snippet that will be included in the
14933 It has to be defined using
14934 \begin_inset Flex CharStyle:Code
14937 \begin_layout Plain Layout
14943 \SpecialChar \ldots{}
14945 \begin_inset Flex CharStyle:Code
14948 \begin_layout Plain Layout
14955 This command may occur zero or more times.
14958 \begin_layout Description
14959 \begin_inset Flex CharStyle:Code
14962 \begin_layout Plain Layout
14964 \begin_inset space ~
14968 \begin_inset space ~
14976 This command denotes files that are created by the conversion process and
14977 are needed for a particular export format.
14978 If the filename is relative, it is interpreted relative to the master document.
14979 This command may be given zero or more times.
14982 \begin_layout Description
14983 \begin_inset Flex CharStyle:Code
14986 \begin_layout Plain Layout
14988 \begin_inset space ~
14996 The name of a required LaTeX package.
14997 The package is included via
14998 \begin_inset Flex CharStyle:Code
15001 \begin_layout Plain Layout
15009 in the LaTeX preamble.
15010 This command may occur zero or more times.
15013 \begin_layout Description
15014 \begin_inset Flex CharStyle:Code
15017 \begin_layout Plain Layout
15019 \begin_inset space ~
15023 \begin_inset space ~
15026 RotationLatexCommand
15031 This command specifies that the built in LaTeX command should be used for
15033 This command may occur once or not at all.
15036 \begin_layout Description
15037 \begin_inset Flex CharStyle:Code
15040 \begin_layout Plain Layout
15042 \begin_inset space ~
15046 \begin_inset space ~
15054 This command specifies that the built in LaTeX command should be used for
15056 This command may occur once or not at all.
15059 \begin_layout Description
15060 \begin_inset Flex CharStyle:Code
15063 \begin_layout Plain Layout
15065 \begin_inset space ~
15069 \begin_inset space ~
15072 RotationLatexOption
15077 This command specifies that rotation is done via an optional argument.
15078 This command may occur once or not at all.
15081 \begin_layout Description
15082 \begin_inset Flex CharStyle:Code
15085 \begin_layout Plain Layout
15087 \begin_inset space ~
15091 \begin_inset space ~
15099 This command specifies that resizing is done via an optional argument.
15100 This command may occur once or not at all.
15103 \begin_layout Description
15104 \begin_inset Flex CharStyle:Code
15107 \begin_layout Plain Layout
15109 \begin_inset space ~
15113 \begin_inset space ~
15121 This command specifies that clipping is done via an optional argument.
15122 This command may occur once or not at all.
15125 \begin_layout Description
15126 \begin_inset Flex CharStyle:Code
15129 \begin_layout Plain Layout
15131 \begin_inset space ~
15135 \begin_inset space ~
15143 This command specifies that an extra optional argument is used.
15144 This command may occur once or not at all.
15147 \begin_layout Description
15148 \begin_inset Flex CharStyle:Code
15151 \begin_layout Plain Layout
15153 \begin_inset space ~
15161 The file format of the converted file.
15162 This must be the name of a format that is known to LyX (see the
15163 \begin_inset Flex CharStyle:MenuItem
15166 \begin_layout Plain Layout
15171 ools\SpecialChar \menuseparator
15176 references:Conversion
15182 This command must occur exactly once.
15185 \begin_layout Description
15186 \begin_inset Flex CharStyle:Code
15189 \begin_layout Plain Layout
15191 \begin_inset space ~
15199 The file name of the converted file.
15200 The file name must be absolute.
15201 This command must occur exactly once.
15204 \begin_layout Subsection
15205 Preamble definitions
15208 \begin_layout Standard
15209 The external template configuration file may contain additional preamble
15210 definitions enclosed by
15211 \begin_inset Flex CharStyle:Code
15214 \begin_layout Plain Layout
15220 \SpecialChar \ldots{}
15222 \begin_inset Flex CharStyle:Code
15225 \begin_layout Plain Layout
15232 They can be used by the templates in the
15233 \begin_inset Flex CharStyle:Code
15236 \begin_layout Plain Layout
15245 \begin_layout Section
15246 The substitution mechanism
15249 \begin_layout Standard
15250 When the external material facility invokes an external program, it is done
15251 on the basis of a command defined in the template configuration file.
15252 These commands can contain various macros that are expanded before execution.
15253 Execution always take place in the directory of the containing document.
15256 \begin_layout Standard
15257 Also, whenever external material is to be displayed, the name will be produced
15258 by the substitution mechanism, and most other commands in the template
15259 definition support substitution as well.
15262 \begin_layout Standard
15263 The available macros are the following:
15266 \begin_layout Description
15267 \begin_inset Flex CharStyle:Code
15270 \begin_layout Plain Layout
15271 $$AbsOrRelPathMaster
15276 The file path, absolute or relative to the master LyX document.
15279 \begin_layout Description
15280 \begin_inset Flex CharStyle:Code
15283 \begin_layout Plain Layout
15284 $$AbsOrRelPathParent
15289 The file path, absolute or relative to the LyX document.
15292 \begin_layout Description
15293 \begin_inset Flex CharStyle:Code
15296 \begin_layout Plain Layout
15302 The absolute file path.
15305 \begin_layout Description
15306 \begin_inset Flex CharStyle:Code
15309 \begin_layout Plain Layout
15315 The filename without path and without the extension.
15318 \begin_layout Description
15319 \begin_inset Flex CharStyle:Code
15322 \begin_layout Plain Layout
15324 \begin_inset Quotes eld
15328 \begin_inset Quotes erd
15336 This macro will expand to the contents of the file with the name
15337 \begin_inset Flex CharStyle:Code
15340 \begin_layout Plain Layout
15349 \begin_layout Description
15350 \begin_inset Flex CharStyle:Code
15353 \begin_layout Plain Layout
15359 The file extension (including the dot).
15362 \begin_layout Description
15363 \begin_inset Flex CharStyle:Code
15366 \begin_layout Plain Layout
15372 The filename of the file specified in the external material dialog.
15373 This is either an absolute name, or it is relative to the LyX document.
15376 \begin_layout Description
15377 \begin_inset Flex CharStyle:Code
15380 \begin_layout Plain Layout
15387 \begin_inset Flex CharStyle:Code
15390 \begin_layout Plain Layout
15396 (absolute name or relative to the LyX document).
15399 \begin_layout Description
15400 \begin_inset Flex CharStyle:Code
15403 \begin_layout Plain Layout
15409 The file path, relative to the master LyX document.
15412 \begin_layout Description
15413 \begin_inset Flex CharStyle:Code
15416 \begin_layout Plain Layout
15422 The file path, relative to the LyX document.
15425 \begin_layout Description
15426 \begin_inset Flex CharStyle:Code
15429 \begin_layout Plain Layout
15435 This macro will expand to the absolute path of the system directory.
15436 This is typically used to point to the various helper scripts that are
15440 \begin_layout Description
15441 \begin_inset Flex CharStyle:Code
15444 \begin_layout Plain Layout
15450 A name and full path to a temporary file which will be automatically deleted
15451 whenever the containing document is closed, or the external material insertion
15455 \begin_layout Standard
15456 All path macros contain a trailing directory separator, so you can construct
15458 \begin_inset space \thinspace{}
15462 \begin_inset space \space{}
15465 the absolute filename with
15466 \begin_inset Flex CharStyle:Code
15469 \begin_layout Plain Layout
15470 $$AbsPath$$Basename$$Extension
15478 \begin_layout Standard
15479 The macros above are substituted in all commands unless otherwise noted.
15481 \begin_inset Flex CharStyle:Code
15484 \begin_layout Plain Layout
15490 supports additionally the following substitutions if they are enabled by
15492 \begin_inset Flex CharStyle:Code
15495 \begin_layout Plain Layout
15502 \begin_inset Flex CharStyle:Code
15505 \begin_layout Plain Layout
15514 \begin_layout Description
15515 \begin_inset Flex CharStyle:Code
15518 \begin_layout Plain Layout
15524 The front part of the resize command.
15527 \begin_layout Description
15528 \begin_inset Flex CharStyle:Code
15531 \begin_layout Plain Layout
15537 The back part of the resize command.
15540 \begin_layout Description
15541 \begin_inset Flex CharStyle:Code
15544 \begin_layout Plain Layout
15550 The front part of the rotation command.
15553 \begin_layout Description
15554 \begin_inset Flex CharStyle:Code
15557 \begin_layout Plain Layout
15563 The back part of the rotation command.
15566 \begin_layout Standard
15567 The value string of the
15568 \begin_inset Flex CharStyle:Code
15571 \begin_layout Plain Layout
15577 command supports additionally the following substitutions if they are enabled
15579 \begin_inset Flex CharStyle:Code
15582 \begin_layout Plain Layout
15589 \begin_inset Flex CharStyle:Code
15592 \begin_layout Plain Layout
15601 \begin_layout Description
15602 \begin_inset Flex CharStyle:Code
15605 \begin_layout Plain Layout
15614 \begin_layout Description
15615 \begin_inset Flex CharStyle:Code
15618 \begin_layout Plain Layout
15627 \begin_layout Description
15628 \begin_inset Flex CharStyle:Code
15631 \begin_layout Plain Layout
15640 \begin_layout Description
15641 \begin_inset Flex CharStyle:Code
15644 \begin_layout Plain Layout
15650 The rotation option.
15653 \begin_layout Standard
15654 You may ask why there are so many path macros.
15655 There are mainly two reasons:
15658 \begin_layout Enumerate
15659 Relative and absolute file names should remain relative or absolute, respectivel
15661 Users may have reasons to prefer either form.
15662 Relative names are useful for portable documents that should work on different
15663 machines, for example.
15664 Absolute names may be required by some programs.
15667 \begin_layout Enumerate
15668 LaTeX treats relative file names differently than LyX and other programs
15669 in nested included files.
15670 For LyX, a relative file name is always relative to the document that contains
15672 For LaTeX, it is always relative to the master document.
15673 These two definitions are identical if you have only one document, but
15674 differ if you have a master document that includes part documents.
15675 That means that relative filenames must be transformed when presented to
15677 Fortunately LyX does this automatically for you if you choose the right
15681 \begin_layout Standard
15682 So which path macro should be used in new template definitions? The rule
15686 \begin_layout Itemize
15688 \begin_inset Flex CharStyle:Code
15691 \begin_layout Plain Layout
15697 if an absolute path is required.
15700 \begin_layout Itemize
15702 \begin_inset Flex CharStyle:Code
15705 \begin_layout Plain Layout
15706 $$AbsOrRelPathMaster
15711 if the substituted string is some kind of LaTeX input.
15714 \begin_layout Itemize
15716 \begin_inset Flex CharStyle:Code
15719 \begin_layout Plain Layout
15720 $$AbsOrRelPathParent
15725 in order to preserve the user's choice.
15728 \begin_layout Standard
15729 There are special cases where this rule does not work and e.
15730 \begin_inset space \thinspace{}
15734 \begin_inset space \space{}
15737 relative names are needed, but normally it will work just fine.
15738 One example for such a case is the command
15739 \begin_inset Flex CharStyle:Code
15742 \begin_layout Plain Layout
15743 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15748 in the XFig template above: We can't use the absolute name because the
15750 \begin_inset Flex CharStyle:Code
15753 \begin_layout Plain Layout
15759 files needs the relative name in order to rewrite the file content.
15762 \begin_layout Section
15763 Security discussion
15764 \begin_inset CommandInset label
15766 name "sec:Security-discussion"
15773 \begin_layout Standard
15774 The external material feature interfaces with a lot of external programs
15775 and does so automatically, so we have to consider the security implications
15777 In particular, since you have the option of including your own filenames
15778 and/or parameter strings and those are expanded into a command, it seems
15779 that it would be possible to create a malicious document which executes
15780 arbitrary commands when a user views or prints the document.
15781 This is something we definitely want to avoid.
15784 \begin_layout Standard
15785 However, since the external program commands are specified in the template
15786 configuration file only, there are no security issues if LyX is properly
15787 configured with safe templates only.
15788 This is so because the external programs are invoked with the
15789 \begin_inset Flex CharStyle:Code
15792 \begin_layout Plain Layout
15798 -system call rather than the
15799 \begin_inset Flex CharStyle:Code
15802 \begin_layout Plain Layout
15808 system-call, so it's not possible to execute arbitrary commands from the
15809 filename or parameter section via the shell.
15812 \begin_layout Standard
15813 This also implies that you are restricted in what command strings you can
15814 use in the external material templates.
15815 In particular, pipes and redirection are not readily available.
15816 This has to be so if LyX should remain safe.
15817 If you want to use some of the shell features, you should write a safe
15818 script to do this in a controlled manner, and then invoke the script from
15819 the command string.
15823 \begin_layout Standard
15824 It is possible to design a template that interacts directly with the shell,
15825 but since this would allow a malicious user to execute arbitrary commands
15826 by writing clever filenames and/or parameters, we generally recommend that
15827 you only use safe scripts that work with the
15828 \begin_inset Flex CharStyle:Code
15831 \begin_layout Plain Layout
15837 system call in a controlled manner.
15838 Of course, for use in a controlled environment, it can be tempting to just
15839 fall back to use ordinary shell scripts.
15840 If you do so, be aware that you
15844 provide an easily exploitable security hole in your system.
15845 Of course it stands to reason that such unsafe templates will never be
15846 included in the standard LyX distribution, although we do encourage people
15847 to submit new templates in the open source tradition.
15848 But LyX as shipped from the official distribution channels will never have
15852 \begin_layout Standard
15853 Including external material provides a lot of power, and you have to be
15854 careful not to introduce security hazards with this power.
15855 A subtle error in a single line in an innocent looking script can open
15856 the door to huge security problems.
15857 So if you do not fully understand the issues, we recommend that you consult
15858 a knowledgeable security professional or the LyX development team if you
15859 have any questions about whether a given template is safe or not.
15860 And do this before you use it in an uncontrolled environment.