1 #LyX 2.0.0svn created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that the User's Guide prints
10 % out as advertised. If you mess with this preamble,
11 % parts of the User's Guide may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
44 \use_default_options false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
67 \font_typewriter default
68 \font_default_family default
78 \pdf_title "LyX Configuration Manual"
79 \pdf_author "LyX Team"
80 \pdf_subject "LyX-documentation Customization"
81 \pdf_keywords "LyX, documentation, customization"
83 \pdf_bookmarksnumbered true
84 \pdf_bookmarksopen true
85 \pdf_bookmarksopenlevel 1
90 \pdf_pdfusetitle false
91 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
98 \paperorientation portrait
105 \paragraph_separation indent
107 \quotes_language english
110 \paperpagestyle headings
111 \tracking_changes false
112 \output_changes false
121 Customizing LyX: Features for the Advanced User
129 \begin_layout Plain Layout
131 If you have comments or error corrections, please send them to the LyX Documenta
133 \begin_inset CommandInset href
135 target "lyx-docs@lists.lyx.org"
142 \begin_inset Quotes eld
146 \begin_inset Quotes erd
149 in the subject header, and please cc the current maintainer of this file,
150 Richard Heck <rgheck@comcast.net>.
156 \begin_inset Newline newline
160 \begin_inset Newline newline
166 \begin_layout Standard
167 \begin_inset CommandInset toc
168 LatexCommand tableofcontents
175 \begin_layout Standard
176 \begin_inset Note Note
179 \begin_layout Plain Layout
180 Please use change tracking when modifying this document.
181 This makes it easier for our translators to recognize things that have
182 been changed, and it helps the maintainer keep up-to-date with what's been
191 \begin_layout Chapter
195 \begin_layout Standard
196 This manual covers the customization features present in LyX.
197 In it, we discuss issues like keyboard shortcuts, screen previewing options,
198 printer options, sending commands to LyX via the LyX Server, internationalizati
199 on, installing new LaTeX classes and LyX layouts, etc.
200 We can't possibly hope to touch on everything you can change—our developers
201 add new features faster than we can document them—but we will explain the
202 most common customizations and hopefully point you in the right direction
203 for some of the more obscure ones.
206 \begin_layout Standard
207 \begin_inset Branch OutDated
210 \begin_layout Standard
211 Information from previous versions of this document that now seems to be
212 outdated is contained in the OutDated branch of this document.
213 By default, this information will not appear in the LaTeX output.
221 \begin_layout Chapter
222 LyX configuration files
225 \begin_layout Standard
226 This chapter aims to help you to find your way through the LyX configuration
228 Before continuing to read this chapter, you should find out where your
229 LyX library and user directories are by using
230 \begin_inset Flex CharStyle:MenuItem
233 \begin_layout Plain Layout
234 Help\SpecialChar \menuseparator
245 The library directory is the place where LyX places its system-wide configurati
246 on files; the user directory is where you can place your modified versions.
247 We will call the former
248 \begin_inset Flex CharStyle:Code
251 \begin_layout Plain Layout
258 \begin_inset Flex CharStyle:MenuItem
261 \begin_layout Plain Layout
267 in the remainder of this document.
271 \begin_layout Section
273 \begin_inset Flex CharStyle:Code
276 \begin_layout Plain Layout
285 \begin_layout Standard
286 \begin_inset Flex CharStyle:Code
289 \begin_layout Plain Layout
295 and its sub-directories contain a number of files and that can be used
296 to customize LyX's behavior.
297 You can change many of these files from within LyX itself through the
298 \begin_inset Flex CharStyle:MenuItem
301 \begin_layout Plain Layout
302 Tools\SpecialChar \menuseparator
309 Most customization that you will want to do in LyX is possible through
311 However, many other inner aspects of LyX can be customized by modifying
313 \begin_inset Flex CharStyle:Code
316 \begin_layout Plain Layout
323 These files fall in different categories, described in the following subsection
327 \begin_layout Subsection
328 Automatically generated files
331 \begin_layout Standard
332 The files, which are to be found in
333 \begin_inset Flex CharStyle:MenuItem
336 \begin_layout Plain Layout
342 , are generated when you configure LyX.
343 They contain various default values that are guessed by inspection.
344 In general, it is not a good idea to modify them, since they might be overwritt
348 \begin_layout Labeling
349 \labelwidthstring 00.00.0000
350 \begin_inset Flex CharStyle:Code
353 \begin_layout Plain Layout
359 contains defaults for various commands.
362 \begin_layout Labeling
363 \labelwidthstring 00.00.0000
364 \begin_inset Flex CharStyle:Code
367 \begin_layout Plain Layout
373 contains the list of packages that have been recognized by LyX.
374 It is currently unused by the LyX program itself, but the information extracted
375 , and more, is made available with
376 \begin_inset Flex CharStyle:MenuItem
379 \begin_layout Plain Layout
380 Help\SpecialChar \menuseparator
393 \begin_layout Labeling
394 \labelwidthstring 00.00.0000
395 \begin_inset Flex CharStyle:Code
398 \begin_layout Plain Layout
404 the list of text classes that have been found in your
405 \begin_inset Flex CharStyle:Code
408 \begin_layout Plain Layout
414 directories, along with the associated LaTeX document class and their descripti
418 \begin_layout Labeling
419 \labelwidthstring 00.00.0000
420 \begin_inset Flex CharStyle:Code
423 \begin_layout Plain Layout
429 the list of layout modules found in your
430 \begin_inset Flex CharStyle:Code
433 \begin_layout Plain Layout
442 \begin_layout Labeling
443 \labelwidthstring 00.00.0000
444 \begin_inset Flex CharStyle:Code
447 \begin_layout Plain Layout
453 lists of various sorts of LaTeX-related files found on your system
456 \begin_layout Labeling
457 \labelwidthstring 00.00.0000
458 \begin_inset Flex CharStyle:Code
461 \begin_layout Plain Layout
467 is automatically generated during configuration from the file
468 \begin_inset Flex CharStyle:Code
471 \begin_layout Plain Layout
478 It contains information on your LaTeX configuration.
481 \begin_layout Subsection
485 \begin_layout Standard
486 These directories are duplicated between
487 \begin_inset Flex CharStyle:Code
490 \begin_layout Plain Layout
497 \begin_inset Flex CharStyle:Code
500 \begin_layout Plain Layout
507 If a particular files exists in both places, the one in
508 \begin_inset Flex CharStyle:Code
511 \begin_layout Plain Layout
520 \begin_layout Labeling
521 \labelwidthstring 00.00.0000
522 \begin_inset Flex CharStyle:Code
525 \begin_layout Plain Layout
531 this directory contains files with the extension
532 \begin_inset Flex CharStyle:Code
535 \begin_layout Plain Layout
541 that define the keybindings used in LyX.
542 If there exists an internationalized version of the bind file named
543 \begin_inset Flex CharStyle:Code
546 \begin_layout Plain Layout
552 , that will be used first.
555 \begin_layout Labeling
556 \labelwidthstring 00.00.0000
557 \begin_inset Flex CharStyle:Code
560 \begin_layout Plain Layout
566 contains graphics files that can be included in documents.
570 \begin_layout Labeling
571 \labelwidthstring 00.00.0000
572 \begin_inset Flex CharStyle:Code
575 \begin_layout Plain Layout
581 contains LyX documentation files (including the one you are currently reading).
583 \begin_inset Flex CharStyle:Code
586 \begin_layout Plain Layout
592 deserves special attention, as noted above.
593 The internationalized help docs are in subdirectories
594 \begin_inset Flex CharStyle:Code
597 \begin_layout Plain Layout
604 \begin_inset Quotes eld
608 \begin_inset Quotes erd
611 is the ISO language code.
617 \begin_inset CommandInset ref
619 reference "chap:i18n"
626 \begin_layout Labeling
627 \labelwidthstring 00.00.0000
628 \begin_inset Flex CharStyle:Code
631 \begin_layout Plain Layout
637 contains example files that explain how to use some features.
638 In the file browser, press the
639 \begin_inset Flex CharStyle:MenuItem
642 \begin_layout Plain Layout
651 \begin_layout Labeling
652 \labelwidthstring 00.00.0000
653 \begin_inset Flex CharStyle:Code
656 \begin_layout Plain Layout
662 contains image files that are used by the
663 \begin_inset Flex CharStyle:MenuItem
666 \begin_layout Plain Layout
673 In addition, it also contains the individual icons used in the toolbar
674 and the banners that can be shown when LyX is launched.
677 \begin_layout Labeling
678 \labelwidthstring 00.00.0000
679 \begin_inset Flex CharStyle:Code
682 \begin_layout Plain Layout
688 contains keyboard keymapping files.
694 \begin_inset CommandInset ref
696 reference "sec:keymap"
703 \begin_layout Labeling
704 \labelwidthstring 00.00.0000
705 \begin_inset Flex CharStyle:Code
708 \begin_layout Plain Layout
714 contains the text class and module files described in Chapter
719 \begin_inset CommandInset ref
721 reference "chap:textclass"
728 \begin_layout Labeling
729 \labelwidthstring 00.00.0000
730 \begin_inset Flex CharStyle:Code
733 \begin_layout Plain Layout
740 \begin_inset Flex CharStyle:Code
743 \begin_layout Plain Layout
749 Python scripts used to convert between LyX versions.
750 These can be run from the command line if, say, you want to batch-convert
754 \begin_layout Labeling
755 \labelwidthstring 00.00.0000
756 \begin_inset Flex CharStyle:Code
759 \begin_layout Plain Layout
765 contains some files that demonstrate the capabilities of the
766 \begin_inset Flex CharStyle:MenuItem
769 \begin_layout Plain Layout
780 Also contains some scripts used by LyX itself.
783 \begin_layout Labeling
784 \labelwidthstring 00.00.0000
785 \begin_inset Flex CharStyle:Code
788 \begin_layout Plain Layout
794 contains the standard LyX template files described in Chapter
799 \begin_inset CommandInset ref
801 reference "sec:templates"
808 \begin_layout Labeling
809 \labelwidthstring 00.00.0000
810 \begin_inset Flex CharStyle:Code
813 \begin_layout Plain Layout
819 contains files with the extension
820 \begin_inset Flex CharStyle:Code
823 \begin_layout Plain Layout
829 that define the user interface to LyX.
830 That is, the files define which items appear in which menus and the items
831 appearing on the toolbar.
834 \begin_layout Subsection
835 Files you don't want to modify
838 \begin_layout Standard
839 These files are used internally by LyX and you generally do not need to
840 modify them unless you are a developer.
843 \begin_layout Labeling
844 \labelwidthstring 00.00.0000
845 \begin_inset Flex CharStyle:Code
848 \begin_layout Plain Layout
854 this file contains the list of LyX developers.
855 The contents are displayed with the menu entry
856 \begin_inset Flex CharStyle:MenuItem
859 \begin_layout Plain Layout
860 Help\SpecialChar \menuseparator
873 \begin_layout Labeling
874 \labelwidthstring 00.00.0000
875 \begin_inset Flex CharStyle:Code
878 \begin_layout Plain Layout
884 this is a LaTeX script used during the configuration process.
888 \begin_layout Labeling
889 \labelwidthstring 00.00.0000
890 \begin_inset Flex CharStyle:Code
893 \begin_layout Plain Layout
899 this is the script that is used to re-configure LyX.
900 It creates configuration files in the directory it was run from.
903 \begin_layout Subsection
904 Other files needing a line or two...
907 \begin_layout Labeling
908 \labelwidthstring 00.00.0000
909 \begin_inset Flex CharStyle:Code
912 \begin_layout Plain Layout
918 this contains tables describing how different character encodings can be
922 \begin_layout Labeling
923 \labelwidthstring 00.00.0000
924 \begin_inset Flex CharStyle:Code
927 \begin_layout Plain Layout
933 this file contains the templates available to the new
934 \begin_inset Flex CharStyle:MenuItem
937 \begin_layout Plain Layout
950 \begin_layout Labeling
951 \labelwidthstring 00.00.0000
952 \begin_inset Flex CharStyle:Code
955 \begin_layout Plain Layout
961 this file contains a list of all the languages currently supported by LyX.
964 \begin_layout Section
965 Your local configuration directory
968 \begin_layout Standard
969 Even if you are using LyX as an unprivileged user, you might want to change
970 LyX configuration for your own use.
972 \begin_inset Flex CharStyle:Code
975 \begin_layout Plain Layout
981 directory contains all your personal configuration files.
982 This is the directory described as
983 \begin_inset Quotes eld
987 \begin_inset Quotes erd
991 \begin_inset Flex CharStyle:MenuItem
994 \begin_layout Plain Layout
995 Help\SpecialChar \menuseparator
1006 This directory is used as a mirror of
1007 \begin_inset Flex CharStyle:Code
1010 \begin_layout Plain Layout
1016 , which means that every file in
1017 \begin_inset Flex CharStyle:Code
1020 \begin_layout Plain Layout
1026 is a replacement for the corresponding file in
1027 \begin_inset Flex CharStyle:Code
1030 \begin_layout Plain Layout
1037 Any configuration file described in the above sections can be placed either
1038 in the system-wide directory, in which case it will affect all users, or
1039 in your local directory for your own use.
1042 \begin_layout Standard
1043 To make things clearer, let's provide a few examples:
1046 \begin_layout Itemize
1047 The preferences set in the
1048 \begin_inset Flex CharStyle:MenuItem
1051 \begin_layout Plain Layout
1052 Tools\SpecialChar \menuseparator
1058 dialog are saved to a file
1059 \begin_inset Flex CharStyle:Code
1062 \begin_layout Plain Layout
1069 \begin_inset Flex CharStyle:Code
1072 \begin_layout Plain Layout
1081 \begin_layout Itemize
1082 When you reconfigure using
1083 \begin_inset Flex CharStyle:MenuItem
1086 \begin_layout Plain Layout
1087 Tools\SpecialChar \menuseparator
1094 \begin_inset Flex CharStyle:Code
1097 \begin_layout Plain Layout
1103 script, and the resulting files are written in your local configuration
1105 This means that any additional text class file that you might have added
1107 \begin_inset Flex CharStyle:Code
1110 \begin_layout Plain Layout
1116 will be added to the list of classes in the
1117 \begin_inset Flex CharStyle:MenuItem
1120 \begin_layout Plain Layout
1121 Document\SpecialChar \menuseparator
1130 \begin_layout Itemize
1131 If you get some updated documentation from LyX ftp site and cannot install
1132 it because you do not have sysadmin rights on your system, you can just
1134 \begin_inset Flex CharStyle:Code
1137 \begin_layout Plain Layout
1143 and the items in the
1144 \begin_inset Flex CharStyle:MenuItem
1147 \begin_layout Plain Layout
1153 menu will open them!
1156 \begin_layout Section
1157 Running LyX with multiple configurations
1160 \begin_layout Standard
1161 The configuration freedom of the local configuration directory may not suffice
1162 if you want to have more than one configuration at your disposal.
1163 For example, you may want to be use different key bindings or printer settings
1165 You can achieve this by having several such directories.
1166 You then specify which directory to use at run-time.
1169 \begin_layout Standard
1170 Invoking LyX with the command line switch
1171 \begin_inset Flex CharStyle:Code
1174 \begin_layout Plain Layout
1184 instructs the program to read the configuration from that directory, and
1185 not from the default directory.
1186 (You can determine the default directory by running LyX without the
1187 \begin_inset Flex CharStyle:Code
1190 \begin_layout Plain Layout
1196 switch.) If the specified directory does not exist, LyX offers to create
1197 it for you, just like it does for the default directory on the first time
1198 you run the program.
1199 You can modify the configuration options in this additional user directory
1200 exactly as you would for the default directory.
1201 These directories are completely independent (but read on).
1202 Note that setting the environment variable
1203 \begin_inset Flex CharStyle:Code
1206 \begin_layout Plain Layout
1212 to some value has exactly the same effect.
1215 \begin_layout Standard
1216 Having several configurations also requires more maintenance: if you want
1217 to add a new layout to
1218 \begin_inset Flex CharStyle:Code
1221 \begin_layout Plain Layout
1227 which you want available from all your configurations, you must add it
1228 to each directory separately.
1229 You can avoid this with the following trick: after LyX creates the additional
1230 directory, most of the subdirectories (see above) are empty.
1231 If you want the new configuration to mirror an existing one, replace the
1232 empty subdirectory with a symbolic link to the matching subdirectory in
1233 the existing configuration.
1235 \begin_inset Flex CharStyle:Code
1238 \begin_layout Plain Layout
1244 subdirectory, however, since it contains a file written by the configuration
1245 script (also accessible through
1246 \begin_inset Flex CharStyle:MenuItem
1249 \begin_layout Plain Layout
1250 Tools\SpecialChar \menuseparator
1256 ) which is configuration-specific.
1259 \begin_layout Chapter
1260 The Preferences dialog
1263 \begin_layout Standard
1264 All options of the preferences dialog are described in the Appendix
1266 The Preferences Dialog
1273 For some options you might find here more details.
1276 \begin_layout Section
1277 Using the dialog for the first time
1280 \begin_layout Standard
1282 \begin_inset Flex CharStyle:Code
1285 \begin_layout Plain Layout
1291 file will contain only changes that you have made to the default behavior,
1292 some of which is hard-coded into LyX and some of which is contained in
1294 \begin_inset Flex CharStyle:Code
1297 \begin_layout Plain Layout
1298 LyXDir/lyxrc.defaults
1304 Note that in both files lines beginning with a
1305 \begin_inset Quotes eld
1309 \begin_inset Quotes erd
1312 are just comments and are not interpreted.
1313 However, only system administrators should edit
1314 \begin_inset Flex CharStyle:Code
1317 \begin_layout Plain Layout
1318 LyXDir/lyxrc.defaults
1324 Users should use the
1325 \begin_inset Flex CharStyle:MenuItem
1328 \begin_layout Plain Layout
1329 Tools\SpecialChar \menuseparator
1335 dialog to create and modify their own
1336 \begin_inset Flex CharStyle:Code
1339 \begin_layout Plain Layout
1348 \begin_layout Standard
1350 \begin_inset Flex CharStyle:MenuItem
1353 \begin_layout Plain Layout
1354 Tools\SpecialChar \menuseparator
1360 dialog will be largely self-explanatory.
1361 Most things in the dialog have associated `tool tips': hover your mouse
1362 pointer over something for more information.
1363 Before we highlight a few of the more important commands below, however,
1364 a word of warning: Applying some of your changes (e.
1365 \begin_inset space \thinspace{}
1369 \begin_inset space \space{}
1372 screen fonts) will have an instant effect.
1374 \begin_inset space \thinspace{}
1378 \begin_inset space \space{}
1381 changing the bind file) will not.
1382 If nothing appears to have changed, just
1383 \begin_inset Flex CharStyle:MenuItem
1386 \begin_layout Plain Layout
1392 the changes and restart LyX.
1395 \begin_layout Section
1399 \begin_layout Standard
1400 LyX has a powerful mechanism to convert to and from any file format using
1405 \begin_layout Subsection
1406 \begin_inset CommandInset label
1415 \begin_layout Standard
1416 The first step is to define your file formats if they are not already defined.
1418 \begin_inset Flex CharStyle:MenuItem
1421 \begin_layout Plain Layout
1422 Tools\SpecialChar \menuseparator
1430 \begin_inset Flex CharStyle:MenuItem
1433 \begin_layout Plain Layout
1434 File Handling\SpecialChar \menuseparator
1441 \begin_inset Flex CharStyle:MenuItem
1444 \begin_layout Plain Layout
1445 New\SpecialChar \ldots{}
1451 button to define your new format.
1453 \begin_inset Flex CharStyle:MenuItem
1456 \begin_layout Plain Layout
1462 field contains the named used to identify the format in the GUI.
1464 \begin_inset Flex CharStyle:MenuItem
1467 \begin_layout Plain Layout
1473 is used to identify the format internally.
1474 You will also need to enter a file extension.
1475 These are all required.
1477 \begin_inset Flex CharStyle:MenuItem
1480 \begin_layout Plain Layout
1486 field is used to provide a keyboard shortcut on the menus.
1487 (For example, pressing
1488 \begin_inset Flex CharStyle:MenuItem
1491 \begin_layout Plain Layout
1498 \begin_inset Flex CharStyle:MenuItem
1501 \begin_layout Plain Layout
1502 View\SpecialChar \menuseparator
1511 \begin_layout Standard
1513 \begin_inset Flex CharStyle:MenuItem
1516 \begin_layout Plain Layout
1523 \begin_inset Flex CharStyle:MenuItem
1526 \begin_layout Plain Layout
1533 For example, you might want to use
1534 \begin_inset Flex CharStyle:MenuItem
1537 \begin_layout Plain Layout
1543 to view PostScript files.
1544 You can enter the command needed to start the program in the corresponding
1546 In defining this command, you can use the four variables listed in the
1548 The viewer is launched when you view an image in LyX or use the
1549 \begin_inset Flex CharStyle:MenuItem
1552 \begin_layout Plain Layout
1559 The editor is for example launched when you press the
1560 \begin_inset Flex CharStyle:MenuItem
1563 \begin_layout Plain Layout
1570 \begin_inset Flex CharStyle:MenuItem
1573 \begin_layout Plain Layout
1580 \begin_inset Flex CharStyle:MenuItem
1583 \begin_layout Plain Layout
1592 \begin_layout Standard
1594 \begin_inset Flex CharStyle:MenuItem
1597 \begin_layout Plain Layout
1603 option tells LyX that a format is suitable for document export.
1604 If this is is set and if a suitable conversion route exists (see
1605 \begin_inset CommandInset ref
1607 reference "sub:Converters"
1611 ), the format will appear in the
1612 \begin_inset Flex CharStyle:MenuItem
1615 \begin_layout Plain Layout
1616 File\SpecialChar \menuseparator
1623 The format will also appear in the
1624 \begin_inset Flex CharStyle:MenuItem
1627 \begin_layout Plain Layout
1633 menu if a viewer is specified for the format.
1634 Pure image formats, such as
1635 \begin_inset Flex CharStyle:Code
1638 \begin_layout Plain Layout
1644 , should not use this option.
1645 Formats that can both represent vector graphics and documents like
1646 \begin_inset Flex CharStyle:Code
1649 \begin_layout Plain Layout
1658 \begin_layout Standard
1660 \begin_inset Flex CharStyle:MenuItem
1663 \begin_layout Plain Layout
1664 Vector graphics format
1669 tells LyX that a format can contain vector graphics.
1670 This information is used to determine the target format of included graphics
1672 \begin_inset Flex CharStyle:MenuItem
1675 \begin_layout Plain Layout
1682 Included graphics may need to be converted to either
1683 \begin_inset Flex CharStyle:MenuItem
1686 \begin_layout Plain Layout
1693 \begin_inset Flex CharStyle:MenuItem
1696 \begin_layout Plain Layout
1703 \begin_inset Flex CharStyle:MenuItem
1706 \begin_layout Plain Layout
1713 \begin_inset Flex CharStyle:MenuItem
1716 \begin_layout Plain Layout
1722 cannot handle other image formats.
1723 If an included graphic is not already in
1724 \begin_inset Flex CharStyle:MenuItem
1727 \begin_layout Plain Layout
1734 \begin_inset Flex CharStyle:MenuItem
1737 \begin_layout Plain Layout
1744 \begin_inset Flex CharStyle:MenuItem
1747 \begin_layout Plain Layout
1753 format, it is converted to
1754 \begin_inset Flex CharStyle:MenuItem
1757 \begin_layout Plain Layout
1763 if the vector format option is set, and otherwise to
1764 \begin_inset Flex CharStyle:MenuItem
1767 \begin_layout Plain Layout
1776 \begin_layout Subsection
1780 \begin_layout Standard
1781 Since all conversions from one format to another take place in LyX's temporary
1782 directory, it is sometimes necessary to modify a file before copying it
1783 to the temporary directory in order that the conversion may be performed.
1787 \begin_layout Plain Layout
1788 For example, the file may refer to other files—images, for example—using
1789 relative file names, and these may become invalid when the file is copied
1790 to the temporary directory.
1795 This is done by a Copier: It copies a file to (or from) the temporary directory
1796 and may modify it in the process.
1799 \begin_layout Standard
1800 The definitions of the copiers may use four variables:
1803 \begin_layout Labeling
1804 \labelwidthstring 00.00.0000
1805 \begin_inset Flex CharStyle:Code
1808 \begin_layout Plain Layout
1814 The LyX system directory (e.
1815 \begin_inset space \thinspace{}
1819 \begin_inset space \space{}
1823 \begin_inset Flex CharStyle:MenuItem
1826 \begin_layout Plain Layout
1835 \begin_layout Labeling
1836 \labelwidthstring 00.00.0000
1837 \begin_inset Flex CharStyle:Code
1840 \begin_layout Plain Layout
1849 \begin_layout Labeling
1850 \labelwidthstring 00.00.0000
1851 \begin_inset Flex CharStyle:Code
1854 \begin_layout Plain Layout
1863 \begin_layout Labeling
1864 \labelwidthstring 00.00.0000
1865 \begin_inset Flex CharStyle:Code
1868 \begin_layout Plain Layout
1877 \begin_layout Standard
1878 The latter should be the filename as it would be used in a LaTeX's
1885 It is relevant only when exporting files suitable for such inclusion.
1888 \begin_layout Standard
1889 Copiers can be used to do almost anything with output files.
1890 For example, suppose you want generated pdf files to be copied to a special
1892 \begin_inset Flex CharStyle:Code
1895 \begin_layout Plain Layout
1902 Then you could write a shell script such as this one:
1905 \begin_layout Standard
1906 \begin_inset listings
1910 \begin_layout Plain Layout
1915 \begin_layout Plain Layout
1920 \begin_layout Plain Layout
1922 TOFILE=`basename $2`
1925 \begin_layout Plain Layout
1927 cp $FROMFILE /home/you/pdf/$TOFILE
1932 Save that in your local LyX directory—say,
1933 \begin_inset Flex CharStyle:Code
1936 \begin_layout Plain Layout
1937 /home/you/.lyx/scripts/pdfcopier.sh
1942 —and make it executable, if you need to do so on your platform.
1944 \begin_inset Flex CharStyle:MenuItem
1947 \begin_layout Plain Layout
1948 Tools\SpecialChar \menuseparator
1954 dialog, select under
1955 \begin_inset Flex CharStyle:MenuItem
1958 \begin_layout Plain Layout
1959 File Handling\SpecialChar \menuseparator
1966 \begin_inset Flex CharStyle:MenuItem
1969 \begin_layout Plain Layout
1975 format—or one of the other pdf formats—and enter
1976 \begin_inset Flex CharStyle:Code
1979 \begin_layout Plain Layout
1980 pdfcopier.sh $$i $$o
1986 \begin_inset Flex CharStyle:MenuItem
1989 \begin_layout Plain Layout
1999 \begin_layout Standard
2000 Copiers are used by LyX in various of its own conversions.
2001 For example, if appropriate programs are found, LyX will automatically
2002 install copiers for the
2003 \begin_inset Flex CharStyle:MenuItem
2006 \begin_layout Plain Layout
2013 \begin_inset Flex CharStyle:MenuItem
2016 \begin_layout Plain Layout
2018 \begin_inset space ~
2027 When these formats are exported, the copier sees that not just the main
2028 HTML file but various associated files (style files, images, etc.) are also
2030 All these files are written to a subdirectory of the directory in which
2031 the original LyX file was found.
2035 \begin_layout Plain Layout
2036 This copier can be customized.
2038 \begin_inset Quotes eld
2042 \begin_inset Quotes erd
2045 argument takes a comma-separated list of extensions to be copied; if it
2046 is omitted, all files will be copied.
2048 \begin_inset Quotes eld
2052 \begin_inset Quotes erd
2055 argument determines the extension added to the generated directory.
2057 \begin_inset Quotes eld
2061 \begin_inset Flex CharStyle:MenuItem
2064 \begin_layout Plain Layout
2071 \begin_inset Quotes erd
2074 , so HTML generated from
2075 \begin_inset Flex CharStyle:MenuItem
2078 \begin_layout Plain Layout
2079 /path/to/filename.lyx
2085 \begin_inset Flex CharStyle:MenuItem
2088 \begin_layout Plain Layout
2089 /path/to/filename.html.LyXconv
2103 \begin_layout Subsection
2104 \begin_inset CommandInset label
2106 name "sub:Converters"
2113 \begin_layout Standard
2114 You can define your own Converters to convert files between different formats.
2116 \begin_inset Flex CharStyle:MenuItem
2119 \begin_layout Plain Layout
2120 Tools\SpecialChar \menuseparator
2121 Preferences\SpecialChar \menuseparator
2122 File Handling\SpecialChar \menuseparator
2131 \begin_layout Standard
2132 To define a new converter, select the
2133 \begin_inset Flex CharStyle:MenuItem
2136 \begin_layout Plain Layout
2138 \begin_inset space ~
2147 \begin_inset Flex CharStyle:MenuItem
2150 \begin_layout Plain Layout
2152 \begin_inset space ~
2160 from the drop-down lists, enter the command needed for the conversion,
2162 \begin_inset Flex CharStyle:MenuItem
2165 \begin_layout Plain Layout
2172 Several variables can be used in the definition of converters:
2175 \begin_layout Labeling
2176 \labelwidthstring 00.00.0000
2177 \begin_inset Flex CharStyle:Code
2180 \begin_layout Plain Layout
2186 The LyX system directory
2189 \begin_layout Labeling
2190 \labelwidthstring 00.00.0000
2191 \begin_inset Flex CharStyle:Code
2194 \begin_layout Plain Layout
2203 \begin_layout Labeling
2204 \labelwidthstring 00.00.0000
2205 \begin_inset Flex CharStyle:Code
2208 \begin_layout Plain Layout
2217 \begin_layout Labeling
2218 \labelwidthstring 00.00.0000
2219 \begin_inset Flex CharStyle:Code
2222 \begin_layout Plain Layout
2228 The base filename of the input file (i.
2229 \begin_inset space \thinspace{}
2232 g., without the extension)
2235 \begin_layout Labeling
2236 \labelwidthstring 00.00.0000
2237 \begin_inset Flex CharStyle:Code
2240 \begin_layout Plain Layout
2246 The path to the input file
2249 \begin_layout Labeling
2250 \labelwidthstring 00.00.0000
2251 \begin_inset Flex CharStyle:Code
2254 \begin_layout Plain Layout
2260 The path to the original input file (this is different from $$p when chain
2261 of converters is called).
2264 \begin_layout Standard
2266 \begin_inset Flex CharStyle:MenuItem
2269 \begin_layout Plain Layout
2271 \begin_inset space ~
2279 field you can enter the following flags, separated by commas:
2282 \begin_layout Labeling
2283 \labelwidthstring 00.00.0000
2284 \begin_inset Flex CharStyle:Code
2287 \begin_layout Plain Layout
2293 This converter runs some form of LaTeX.
2294 This will make LyX's LaTeX error logs available.
2297 \begin_layout Labeling
2298 \labelwidthstring 00.00.0000
2299 \begin_inset Flex CharStyle:Code
2302 \begin_layout Plain Layout
2309 \begin_inset Flex CharStyle:MenuItem
2312 \begin_layout Plain Layout
2318 file for the conversion.
2321 \begin_layout Labeling
2322 \labelwidthstring 00.00.0000
2323 \begin_inset Flex CharStyle:Code
2326 \begin_layout Plain Layout
2335 \begin_layout Standard
2336 The following three flags are not really flags at all because they take
2338 \begin_inset Flex CharStyle:MenuItem
2341 \begin_layout Plain Layout
2343 \begin_inset space ~
2347 \begin_inset space ~
2358 \begin_layout Labeling
2359 \labelwidthstring 00.00.0000
2360 \begin_inset Flex CharStyle:Code
2363 \begin_layout Plain Layout
2369 If set, the converter's standard error will be redirected to a file
2370 \begin_inset Flex CharStyle:Code
2373 \begin_layout Plain Layout
2379 , and the script given as argument will be run as:
2380 \begin_inset Flex CharStyle:Code
2383 \begin_layout Plain Layout
2384 script <infile.out >infile.log
2390 The argument may contain
2391 \begin_inset Flex CharStyle:Code
2394 \begin_layout Plain Layout
2403 \begin_layout Labeling
2404 \labelwidthstring 00.00.0000
2405 \begin_inset Flex CharStyle:Code
2408 \begin_layout Plain Layout
2414 The name of the directory in which the converter will dump the generated
2416 LyX will not create this directory, and it does not copy anything into
2417 it, though it will copy this directory to the destination.
2418 The argument may contain
2419 \begin_inset Flex CharStyle:Code
2422 \begin_layout Plain Layout
2428 , which will be replaced by the base name of the input and output files,
2429 respectively, when the directory is copied.
2430 \begin_inset Newline newline
2433 Note that resultdir and usetempdir make no sense together.
2434 The latter will be ignored if the former is given.
2437 \begin_layout Labeling
2438 \labelwidthstring 00.00.0000
2439 \begin_inset Flex CharStyle:Code
2442 \begin_layout Plain Layout
2448 Determines the output file name and may, contain
2449 \begin_inset Flex CharStyle:Code
2452 \begin_layout Plain Layout
2459 Sensible only with resultdir and optional even then; if not given, it defaults
2463 \begin_layout Standard
2464 None of these last three are presently used in any of the converters that
2465 are installed with LyX.
2469 \begin_layout Standard
2470 You do not have to define converters between all the formats between which
2471 you want to convert.
2472 For example, you will note that there is no `LyX to PostScript' converter,
2473 but LyX will export PostScript.
2474 It does so by first creating a LaTeX file (no converter needs to be defined
2475 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2476 and finally converting the resulting DVI file to PostScript.
2477 LyX finds such `chains' of converters automatically, and it will always
2478 choose the shortest possible chain.
2479 You can, though, still define multiple conversion methods between file
2481 For example, the standard LyX configuration provides three ways to convert
2482 LaTeX to PDF: Directly, using
2483 \begin_inset Flex CharStyle:MenuItem
2486 \begin_layout Plain Layout
2492 ; via (DVI and) PostScript, using
2493 \begin_inset Flex CharStyle:MenuItem
2496 \begin_layout Plain Layout
2503 \begin_inset Flex CharStyle:MenuItem
2506 \begin_layout Plain Layout
2513 To define such alternate chains, you must define multiple target `file
2514 formats', as described in section
2515 \begin_inset CommandInset ref
2517 reference "sub:Formats"
2522 For example, in the standard configuration, the formats named
2523 \begin_inset Flex CharStyle:MenuItem
2526 \begin_layout Plain Layout
2533 \begin_inset Flex CharStyle:MenuItem
2536 \begin_layout Plain Layout
2543 \begin_inset Flex CharStyle:MenuItem
2546 \begin_layout Plain Layout
2552 are defined, all of which share the extension
2553 \begin_inset Flex CharStyle:MenuItem
2556 \begin_layout Plain Layout
2562 , and which correspond to the conversion methods just mentioned.
2565 \begin_layout Chapter
2566 Internationalizing LyX
2567 \begin_inset CommandInset label
2576 \begin_layout Standard
2577 LyX supports using a translated interface.
2578 Last time we checked, LyX provided text in thirty languages.
2579 The language of choice is called your
2584 (For further reading on locale settings, see also the documentation for
2585 locale that comes with your operating system.
2586 For Linux, the manual page for
2587 \begin_inset Flex CharStyle:Code
2590 \begin_layout Plain Layout
2596 could be a good place to start).
2599 \begin_layout Standard
2600 Notice that these translations will work, but do contain a few flaws.
2601 In particular, all dialogs have been designed with the English text in
2602 mind, which means that some of the translated text will be too large to
2603 fit within the space allocated.
2604 This is only a display problem and will not cause any harm.
2605 Also, you will find that some of the translations do not define shortcut
2606 keys for everything.
2607 Sometimes, there are simply not enough free letters to do it.
2608 Other times, the translator just hasn't got around to doing it yet.
2609 Our localization team, which you may wish to join,
2613 \begin_layout Plain Layout
2614 If you are a fluent speaker of a language other than English, joining these
2615 teams is a great way to give back to the LyX community!
2620 will of course try to fix these shortcomings in future versions of LyX.
2623 \begin_layout Section
2627 \begin_layout Subsection
2628 Translating the graphical user interface (text messages).
2631 \begin_layout Standard
2633 \begin_inset Flex CharStyle:Code
2636 \begin_layout Plain Layout
2642 library to handle the internationalization of the interface.
2643 To have LyX speak your favorite language in all menus and dialogs, you
2645 \begin_inset Flex CharStyle:Code
2648 \begin_layout Plain Layout
2654 -file for that language.
2655 When this is available, you'll have to generate a
2656 \begin_inset Flex CharStyle:Code
2659 \begin_layout Plain Layout
2665 -file from it and install the
2666 \begin_inset Flex CharStyle:Code
2669 \begin_layout Plain Layout
2676 The process of doing all of this is explained in the documentation for
2678 \begin_inset Flex CharStyle:Code
2681 \begin_layout Plain Layout
2688 It is possible to do this just for yourself, but if you're going to do
2689 it, you might as well share the results of your labors with the rest of
2691 Send a message to the LyX developers' list for more information about how
2695 \begin_layout Standard
2696 In short, this is what you should do (xx denotes the language code):
2699 \begin_layout Itemize
2700 Check out the LyX source code.
2702 \begin_inset CommandInset href
2704 name "information on the web"
2705 target "http://www.lyx.org/devel/cvs.php"
2712 \begin_layout Itemize
2714 \begin_inset Flex CharStyle:Code
2717 \begin_layout Plain Layout
2723 to the folder of the
2724 \begin_inset Flex CharStyle:Code
2727 \begin_layout Plain Layout
2735 \begin_inset Flex CharStyle:Code
2738 \begin_layout Plain Layout
2746 \begin_inset Flex CharStyle:Code
2749 \begin_layout Plain Layout
2755 doesn't exist anywhere, it can be remade with the console command
2756 \begin_inset Flex CharStyle:Code
2759 \begin_layout Plain Layout
2765 in that directory, or you can use an existing po-file for some other language
2769 \begin_layout Itemize
2771 \begin_inset Flex CharStyle:Code
2774 \begin_layout Plain Layout
2784 \begin_layout Plain Layout
2785 This is just a text file, so it can be edited in any text editor.
2786 But there are also specialized programs that support such editing, such
2791 (for all platforms) or
2800 contains a `mode' for editing
2801 \begin_inset Flex CharStyle:Code
2804 \begin_layout Plain Layout
2815 For some menu- and widget-labels, there are also shortcut keys that should
2817 Those keys are marked after a `|', and should be translated according to
2818 the words and phrases of the language.
2819 You should also fill also out the information at the beginning of the new
2821 \begin_inset Flex CharStyle:Code
2824 \begin_layout Plain Layout
2830 -file with your email-address, etc., so people know where to reach you with
2831 suggestions and entertaining flames.
2834 \begin_layout Standard
2835 If you are just doing this on your own, then:
2838 \begin_layout Itemize
2840 \begin_inset Flex CharStyle:Code
2843 \begin_layout Plain Layout
2850 This can be done with
2851 \begin_inset Flex CharStyle:Code
2854 \begin_layout Plain Layout
2855 msgfmt -o xx.mo < xx.po
2863 \begin_layout Itemize
2865 \begin_inset Flex CharStyle:Code
2868 \begin_layout Plain Layout
2874 -file to your locale-tree, at the correct directory for application messages
2879 xx, and under the name
2880 \begin_inset Flex CharStyle:Code
2883 \begin_layout Plain Layout
2890 \begin_inset space \thinspace{}
2894 \begin_inset space \space{}
2898 \begin_inset Flex CharStyle:Code
2901 \begin_layout Plain Layout
2902 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2912 \begin_layout Standard
2913 As said, however, it would be best if the new
2914 \begin_inset Flex CharStyle:Code
2917 \begin_layout Plain Layout
2923 -file could be added to the LyX distribution, so others can use it.
2924 Adding it involves making additional changes to LyX.
2925 So send an email to the developers' mailing list if you're interested in
2929 \begin_layout Subsubsection
2933 \begin_layout Standard
2934 Sometimes it turns out that one English message needs to be translated into
2935 different messages in the target language.
2936 One example is the message
2937 \begin_inset Flex CharStyle:Code
2940 \begin_layout Plain Layout
2946 which has the German translation
2954 , depending upon exactly what the English
2955 \begin_inset Quotes eld
2959 \begin_inset Quotes erd
2964 \begin_inset Flex CharStyle:Code
2967 \begin_layout Plain Layout
2973 does not handle such ambiguous translations.
2974 Therefore you have to add some context information to the message: Instead
2976 \begin_inset Flex CharStyle:Code
2979 \begin_layout Plain Layout
2986 \begin_inset Flex CharStyle:Code
2989 \begin_layout Plain Layout
2990 To[[as in 'From format x to format y']]
2996 \begin_inset Flex CharStyle:Code
2999 \begin_layout Plain Layout
3000 To[[as in 'From page x to page y']].
3005 Now the two occurrences of
3006 \begin_inset Flex CharStyle:Code
3009 \begin_layout Plain Layout
3016 \begin_inset Flex CharStyle:Code
3019 \begin_layout Plain Layout
3025 and can be translated correctly to
3036 \begin_layout Standard
3037 Of course the context information needs to be stripped off the original
3038 message when no translation is used.
3039 Therefore you have to put it in double square brackets at the end of the
3040 message (see the example above).
3041 The translation mechanism of LyX ensures that everything in double square
3042 brackets at the end of messages is removed before displaying the message.
3045 \begin_layout Subsection
3046 Translating the documentation.
3049 \begin_layout Standard
3050 The online documentation (in the
3051 \begin_inset Flex CharStyle:MenuItem
3054 \begin_layout Plain Layout
3060 -menu) can (and should!) be translated.
3061 If there are translated versions of the documentation available
3065 \begin_layout Plain Layout
3066 As of March 2008, at least some of the documents have been translated into
3067 fourteen languages, with the Tutorial available in a few more.
3072 and the locale is set accordingly, these will be used automagically by
3074 LyX looks for translated versions as
3075 \begin_inset Flex CharStyle:Code
3078 \begin_layout Plain Layout
3079 LyXDir/doc/xx/DocName.lyx
3085 \begin_inset Flex CharStyle:Code
3088 \begin_layout Plain Layout
3094 is the code for the language currently in use.
3095 If there are no translated documents, the default English versions will
3097 Note that the translated versions must have the same filenames (
3098 \begin_inset Flex CharStyle:Code
3101 \begin_layout Plain Layout
3107 above) as the original.
3108 If you feel up to translating the documentation (an excellent way to proof-read
3109 the original documentation by the way!), there are a few things you should
3113 \begin_layout Itemize
3115 \begin_inset Flex CharStyle:Code
3118 \begin_layout Plain Layout
3124 , the guide to writing LyX documentation.
3125 Pay special attention to the translator's section.
3128 \begin_layout Itemize
3129 Check out the documentation translation web page at
3130 \begin_inset CommandInset href
3132 name "http://www.lyx.org/Translation"
3133 target "http://www.lyx.org/Translation"
3138 That way, you can find out which (if any) documents have already been translate
3139 d into your language.
3140 You can also find out who (if anyone) is organizing the effort to translate
3141 the documentation into your language.
3142 If no one is organizing the effort, please let us know that you're interested.
3145 \begin_layout Standard
3146 Once you get to actually translating, here's a few hints for you that may
3150 \begin_layout Itemize
3151 Join the documentation team! There is information on how to do that in
3152 \begin_inset Flex CharStyle:Code
3155 \begin_layout Plain Layout
3162 \begin_inset Flex CharStyle:MenuItem
3165 \begin_layout Plain Layout
3166 Help\SpecialChar \menuseparator
3176 ), which by the way is the first document you should translate.
3179 \begin_layout Itemize
3180 Learn the typographic conventions for the language you are translating to.
3181 Typography is an ancient art and over the centuries, a great variety of
3182 conventions have developed throughout different parts of the world.
3183 Also study the professional terminology amongst typographers in your country.
3184 Inventing your own terminology will only confuse the users.
3187 (Warning! Typography is addictive!)
3190 \begin_layout Itemize
3191 Make a copy of the document.
3192 This will be your working copy.
3193 You can use this as your personal translated help-file by placing it in
3195 \begin_inset Flex CharStyle:Code
3198 \begin_layout Plain Layout
3207 \begin_layout Itemize
3208 Sometimes the original document (from the LyX-team) will be updated.
3209 Use the source viewer at
3210 \begin_inset CommandInset href
3212 name "http://www.lyx.org/trac/timeline"
3213 target "http://www.lyx.org/trac/timeline"
3217 to see what has been changed.
3218 That way you can easily see which parts of the translated document need
3222 \begin_layout Standard
3223 If you ever find an error in the original document, fix it and notify the
3224 rest of the documentation team of the changes! (You didn't forget to join
3225 the documentation team, did you?)
3228 \begin_layout Standard
3229 \begin_inset Branch OutDated
3232 \begin_layout Section
3233 International Keyboard Support
3236 \begin_layout Standard
3239 [Editor's Note: The following section is by
3247 It needs to be fixed to conform to the new Documentation Style sheet and
3248 to make use of the new v1.0 features.
3249 The whole thing also needs to be merged with the section following it.-jw
3250 It may also be badly out of date.-rh (2008)]
3253 \begin_layout Subsection
3254 Defining Own Keymaps: Keymap File Format
3257 \begin_layout Standard
3258 Let's look at a keyboard definition file a little closer.
3259 It is a plain text file defining
3262 \begin_layout Itemize
3263 key-to-key or key-to-string translations
3266 \begin_layout Itemize
3270 \begin_layout Itemize
3271 dead keys exceptions
3274 \begin_layout Standard
3275 To define key-to-key or key-to-string translation, use this command:
3278 \begin_layout Quotation
3279 \begin_inset Flex CharStyle:Code
3282 \begin_layout Plain Layout
3291 \begin_inset Flex CharStyle:Code
3294 \begin_layout Plain Layout
3303 \begin_layout Standard
3305 \begin_inset Flex CharStyle:Code
3308 \begin_layout Plain Layout
3314 is the key to be translated and
3315 \begin_inset Flex CharStyle:Code
3318 \begin_layout Plain Layout
3324 is the string to be inserted into the document.
3325 To define dead keys, use:
3328 \begin_layout Quotation
3329 \begin_inset Flex CharStyle:Code
3332 \begin_layout Plain Layout
3341 \begin_inset Flex CharStyle:Code
3344 \begin_layout Plain Layout
3353 \begin_layout Standard
3355 \begin_inset Flex CharStyle:Code
3358 \begin_layout Plain Layout
3364 is a keyboard key and
3365 \begin_inset Flex CharStyle:Code
3368 \begin_layout Plain Layout
3375 The following dead keys are supported (shortcut name is in parentheses):
3378 \begin_layout Quotation
3382 \begin_inset space \hfill{}
3388 \begin_layout Quotation
3390 \begin_inset space \hfill{}
3396 \begin_layout Quotation
3398 \begin_inset space \hfill{}
3404 \begin_layout Quotation
3406 \begin_inset space \hfill{}
3412 \begin_layout Quotation
3414 \begin_inset space \hfill{}
3420 \begin_layout Quotation
3422 \begin_inset space \hfill{}
3429 \begin_layout Plain Layout
3441 \begin_layout Quotation
3443 \begin_inset space \hfill{}
3449 \begin_layout Quotation
3451 \begin_inset space \hfill{}
3458 \begin_layout Plain Layout
3470 \begin_layout Quotation
3472 \begin_inset space \hfill{}
3478 \begin_layout Quotation
3480 \begin_inset space \hfill{}
3486 \begin_layout Quotation
3488 \begin_inset space \hfill{}
3495 \begin_layout Plain Layout
3507 \begin_layout Quotation
3509 \begin_inset space \hfill{}
3516 \begin_layout Plain Layout
3528 \begin_layout Quotation
3530 \begin_inset space \hfill{}
3536 \begin_layout Quotation
3537 hungarian umlaut (hug)
3538 \begin_inset space \hfill{}
3544 \begin_layout Quotation
3546 \begin_inset space \hfill{}
3552 \begin_layout Quotation
3554 \begin_inset space \hfill{}
3561 \begin_layout Plain Layout
3573 \begin_layout Standard
3574 Since in many international keyboards there are exceptions to what some
3575 dead keys should do, you can define them using
3578 \begin_layout Quotation
3579 \begin_inset Flex CharStyle:Code
3582 \begin_layout Plain Layout
3590 deadkey key outstring
3593 \begin_layout Standard
3594 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3598 \begin_layout Quotation
3599 \begin_inset Flex CharStyle:Code
3602 \begin_layout Plain Layout
3615 \begin_layout Standard
3616 to make it work correctly.
3617 Also, you have to define as exceptions dead keys over i and j, to remove
3618 the dot from them before inserting an accent mark.
3619 I will change this when the time comes, but so far I haven't had time.
3622 \begin_layout Standard
3623 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3626 \begin_inset Flex CharStyle:Code
3629 \begin_layout Plain Layout
3635 have different meaning.
3637 \begin_inset Flex CharStyle:Code
3640 \begin_layout Plain Layout
3646 marks comments, quotes start and end LaTeX-style commands.
3647 To enter quote, you'll need to use
3648 \begin_inset Flex CharStyle:Code
3651 \begin_layout Plain Layout
3660 \begin_inset Flex CharStyle:Code
3663 \begin_layout Plain Layout
3670 \begin_inset Flex CharStyle:Code
3673 \begin_layout Plain Layout
3684 \begin_layout Standard
3685 If you make a keyboard description file that works for your language, please
3686 mail it to me, so I can include it in the next keymap distribution.
3689 \begin_layout Standard
3690 More keywords will be supported in keymap configuration file in future,
3694 \begin_layout Itemize
3695 \begin_inset Flex CharStyle:Code
3698 \begin_layout Plain Layout
3709 \begin_inset space \hfill{}
3713 \begin_inset Flex CharStyle:Code
3716 \begin_layout Plain Layout
3725 \begin_layout Itemize
3726 \begin_inset Flex CharStyle:Code
3729 \begin_layout Plain Layout
3740 \begin_inset space \hfill{}
3744 \begin_inset Flex CharStyle:Code
3747 \begin_layout Plain Layout
3753 an external keymap translation program
3756 \begin_layout Standard
3757 Also, it should look into
3758 \begin_inset Flex CharStyle:Code
3761 \begin_layout Plain Layout
3767 file for defaults, too (for example, a
3768 \begin_inset Flex CharStyle:Code
3771 \begin_layout Plain Layout
3779 option to include default keyboard).
3787 \begin_layout Section
3788 \begin_inset CommandInset label
3794 International Keymap Stuff
3797 \begin_layout Standard
3798 \begin_inset Note Note
3801 \begin_layout Plain Layout
3802 In doing the revisions on this document in March 2008, I did not look over
3803 this stuff, as I do not understand it.
3804 It would be good if someone else could do so.
3813 \begin_layout Standard
3814 The next two sections describe the
3815 \begin_inset Flex CharStyle:Code
3818 \begin_layout Plain Layout
3827 \begin_inset Flex CharStyle:Code
3830 \begin_layout Plain Layout
3838 file syntax in detail.
3839 These sections should help you design your own key map if the ones provided
3840 do not meet your needs.
3843 \begin_layout Subsection
3847 \begin_layout Standard
3851 \begin_inset Flex CharStyle:Code
3854 \begin_layout Plain Layout
3860 file maps keystrokes to characters or strings.
3861 As the name suggests, it sets a keyboard mapping.
3863 \begin_inset Flex CharStyle:Code
3866 \begin_layout Plain Layout
3877 \begin_inset Flex CharStyle:Code
3880 \begin_layout Plain Layout
3895 \begin_inset Flex CharStyle:Code
3898 \begin_layout Plain Layout
3911 \begin_inset Flex CharStyle:Code
3914 \begin_layout Plain Layout
3923 \begin_inset Flex CharStyle:Code
3926 \begin_layout Plain Layout
3934 are described in this section.
3937 \begin_layout Labeling
3938 \labelwidthstring 00.00.0000
3939 \begin_inset Flex CharStyle:Code
3942 \begin_layout Plain Layout
3950 Map a character to a string
3953 \begin_layout LyX-Code
3968 \begin_layout Standard
4001 the double-quote (")
4018 must be escaped with a preceding backslash (
4029 \begin_layout Standard
4031 \begin_inset Flex CharStyle:MenuItem
4034 \begin_layout Plain Layout
4042 statement to cause the symbol
4043 \begin_inset Flex CharStyle:MenuItem
4046 \begin_layout Plain Layout
4054 to be output for the keystroke
4055 \begin_inset Flex CharStyle:MenuItem
4058 \begin_layout Plain Layout
4069 \begin_layout LyX-Code
4075 \begin_layout Labeling
4076 \labelwidthstring 00.00.0000
4077 \begin_inset Flex CharStyle:Code
4080 \begin_layout Plain Layout
4088 Specify an accent character
4091 \begin_layout LyX-Code
4100 \begin_layout Standard
4101 This will make the cha
4139 This is the dead key
4143 \begin_layout Plain Layout
4150 refers to a key that does not produce a character by itself, but when followed
4151 with another key, produces the desired accent character.
4152 For example, a German characte
4154 r with an umlaut like
4164 can be produced in this manner.
4173 \begin_layout Standard
4186 and then another key not in
4203 followed by the other, not allowed key, as output.
4207 \begin_inset Flex CharStyle:MenuItem
4210 \begin_layout Plain Layout
4218 cancels a dead key, so if
4229 \begin_inset Flex CharStyle:MenuItem
4232 \begin_layout Plain Layout
4241 , the cursor will not go one position backwards but will instead cancel
4257 might have had on the next keystroke.
4261 \begin_layout Standard
4262 The following example specifies that the character ' is to be an acute accent,
4263 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4266 \begin_layout LyX-Code
4269 kmod ' acute aeiouAEIOU
4272 \begin_layout Labeling
4273 \labelwidthstring 00.00.0000
4274 \begin_inset Flex CharStyle:Code
4277 \begin_layout Plain Layout
4283 Specify an exception to the accent character
4286 \begin_layout LyX-Code
4295 \begin_layout Standard
4296 This defines an exce
4337 have been assigned a keystroke with a previous
4340 \begin_inset Flex CharStyle:Code
4343 \begin_layout Plain Layout
4367 must not belong in the
4414 If such a declaration does not exist in
4422 \begin_inset Flex CharStyle:Code
4425 \begin_layout Plain Layout
4459 \begin_inset Flex CharStyle:Code
4462 \begin_layout Plain Layout
4476 \begin_layout Standard
4477 The following command produces causes äi to be produced when you enter acute-i
4481 \begin_layout LyX-Code
4495 \begin_layout Labeling
4496 \labelwidthstring 00.00.0000
4497 \begin_inset Flex CharStyle:Code
4500 \begin_layout Plain Layout
4506 Combine two accent characters
4509 \begin_layout LyX-Code
4515 accent1 accent2 allowed
4518 \begin_layout Standard
4519 This one is getting pretty esoteric.
4520 It allows you to combine the effect
4576 \begin_inset Flex CharStyle:Code
4579 \begin_layout Plain Layout
4607 \begin_layout Standard
4608 Consider this example from the
4609 \begin_inset Flex CharStyle:Code
4612 \begin_layout Plain Layout
4623 \begin_layout LyX-Code
4626 kmod ; acute aeioyvhAEIOYVH
4630 kcomb acute umlaut iyIY
4633 \begin_layout Standard
4634 This allows you to press
4635 \begin_inset Flex CharStyle:MenuItem
4638 \begin_layout Plain Layout
4646 and get the effect of
4647 \begin_inset Flex CharStyle:Code
4650 \begin_layout Plain Layout
4669 in this case cancels the last dead key, so if you press
4670 \begin_inset Flex CharStyle:MenuItem
4673 \begin_layout Plain Layout
4682 \begin_inset Flex CharStyle:Code
4685 \begin_layout Plain Layout
4698 \begin_layout Subsection
4702 \begin_layout Standard
4704 \begin_inset Flex CharStyle:Code
4707 \begin_layout Plain Layout
4715 mapping is performed, a
4716 \begin_inset Flex CharStyle:Code
4719 \begin_layout Plain Layout
4729 file maps the strings that the symbols generate to characters in the current
4731 The LyX distribution currently includes at least the
4732 \begin_inset Flex CharStyle:Code
4735 \begin_layout Plain Layout
4744 \begin_inset Flex CharStyle:Code
4747 \begin_layout Plain Layout
4758 \begin_layout Standard
4760 \begin_inset Flex CharStyle:Code
4763 \begin_layout Plain Layout
4771 file is a sequence of declarations of the form
4774 \begin_layout LyX-Code
4787 \begin_layout Standard
4788 For example, in order to map
4789 \begin_inset Flex CharStyle:MenuItem
4792 \begin_layout Plain Layout
4802 to the corresponding character in the iso-8859-1 set (233), the following
4806 \begin_layout LyX-Code
4814 \begin_layout Standard
4816 \begin_inset Flex CharStyle:Code
4819 \begin_layout Plain Layout
4828 \begin_inset Flex CharStyle:Code
4831 \begin_layout Plain Layout
4849 the same character can apply to more than one string.
4851 \begin_inset Flex CharStyle:Code
4854 \begin_layout Plain Layout
4865 \begin_layout LyX-Code
4877 \begin_inset Newline newline
4893 \begin_layout Standard
4894 If LyX cannot find a mapping for the string produced by the keystroke or
4895 a deadkey sequence, it will check if it looks like an accented char and
4896 try to draw an accent over the character on screen.
4899 \begin_layout Subsection
4903 \begin_layout Standard
4904 There is a second way to add support for international characters through
4905 so-called dead-keys.
4906 A dead-key works in combination with a letter to produce an accented character.
4907 Here, we'll explain how to create a really simple dead-key to illustrate
4911 \begin_layout Standard
4912 Suppose you happen to need the circumflex character,
4913 \begin_inset Quotes eld
4917 \begin_inset Quotes erd
4922 \begin_inset Flex CharStyle:MenuItem
4925 \begin_layout Plain Layout
4932 \begin_inset space ~
4936 \begin_inset Flex CharStyle:MenuItem
4939 \begin_layout Plain Layout
4945 ] to the LyX command
4946 \begin_inset Flex CharStyle:Code
4949 \begin_layout Plain Layout
4956 \begin_inset Flex CharStyle:Code
4959 \begin_layout Plain Layout
4966 Now, whenever you type the
4967 \begin_inset Flex CharStyle:MenuItem
4970 \begin_layout Plain Layout
4976 -key followed by a letter, that letter will have a circumflex accent on
4978 For example, the sequence
4979 \begin_inset Quotes eld
4983 \begin_inset Flex CharStyle:MenuItem
4986 \begin_layout Plain Layout
4993 \begin_inset Quotes erd
4996 produces the letter:
4997 \begin_inset Quotes eld
5001 \begin_inset Quotes erd
5005 If you tried to type
5006 \begin_inset Quotes eld
5010 \begin_inset Flex CharStyle:MenuItem
5013 \begin_layout Plain Layout
5020 \begin_inset Quotes erd
5023 , however, LyX will complain with a beep, since a
5024 \begin_inset Quotes eld
5028 \begin_inset Flex CharStyle:MenuItem
5031 \begin_layout Plain Layout
5038 \begin_inset Quotes erd
5041 never takes a circumflex accent.
5043 \begin_inset Flex CharStyle:MenuItem
5046 \begin_layout Plain Layout
5052 after a dead-key produces the bare-accent.
5053 Please note this last point! If you bind a key to a dead-key, you'll need
5054 to rebind the character on that key to yet another key.
5056 \begin_inset Flex CharStyle:MenuItem
5059 \begin_layout Plain Layout
5065 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5068 \begin_layout Standard
5069 One common way to bind dead-keys is to use
5070 \begin_inset Flex CharStyle:MenuItem
5073 \begin_layout Plain Layout
5080 \begin_inset Flex CharStyle:MenuItem
5083 \begin_layout Plain Layout
5090 \begin_inset Flex CharStyle:MenuItem
5093 \begin_layout Plain Layout
5099 in combination with an accent, like
5100 \begin_inset Quotes eld
5104 \begin_inset Flex CharStyle:MenuItem
5107 \begin_layout Plain Layout
5114 \begin_inset Quotes erd
5118 \begin_inset Quotes eld
5122 \begin_inset Flex CharStyle:MenuItem
5125 \begin_layout Plain Layout
5132 \begin_inset Quotes erd
5136 \begin_inset Quotes eld
5140 \begin_inset Flex CharStyle:MenuItem
5143 \begin_layout Plain Layout
5150 \begin_inset Quotes erd
5154 Another way involves using
5155 \begin_inset Flex CharStyle:Code
5158 \begin_layout Plain Layout
5165 \begin_inset Flex CharStyle:Code
5168 \begin_layout Plain Layout
5174 to set up the special
5175 \begin_inset Flex CharStyle:Code
5178 \begin_layout Plain Layout
5186 \begin_inset Flex CharStyle:Code
5189 \begin_layout Plain Layout
5195 acts in some ways just like
5196 \begin_inset Flex CharStyle:MenuItem
5199 \begin_layout Plain Layout
5205 and permits you to bind keys to accented characters.
5206 You can also turn keys into dead-keys by binding them to something like
5208 \begin_inset Flex CharStyle:Code
5211 \begin_layout Plain Layout
5217 and then binding this symbolic key to the corresponding LyX command.
5221 \begin_layout Plain Layout
5226 : This is exactly what I do in my
5227 \begin_inset Flex CharStyle:Code
5230 \begin_layout Plain Layout
5237 \begin_inset Flex CharStyle:Code
5240 \begin_layout Plain Layout
5248 \begin_inset Flex CharStyle:MenuItem
5251 \begin_layout Plain Layout
5253 \begin_inset space ~
5262 \begin_inset Flex CharStyle:Code
5265 \begin_layout Plain Layout
5271 and a bunch of these
5272 \begin_inset Quotes eld
5276 \begin_inset Flex CharStyle:Code
5279 \begin_layout Plain Layout
5286 \begin_inset Quotes erd
5289 symbolic keys bound such things as
5290 \begin_inset Flex CharStyle:MenuItem
5293 \begin_layout Plain Layout
5295 \begin_inset space ~
5304 \begin_inset Flex CharStyle:MenuItem
5307 \begin_layout Plain Layout
5309 \begin_inset space ~
5318 This is how I produce my accented characters.
5323 You can make just about anything into the
5324 \begin_inset Flex CharStyle:Code
5327 \begin_layout Plain Layout
5334 \begin_inset Flex CharStyle:MenuItem
5337 \begin_layout Plain Layout
5343 keys, a spare function key, etc.
5344 As for the LyX commands that produce accents, check the entry for
5345 \begin_inset Flex CharStyle:Code
5348 \begin_layout Plain Layout
5359 You'll find the complete list there.
5362 \begin_layout Subsection
5363 Saving your Language Configuration
5366 \begin_layout Standard
5367 You can edit your preferences so that your desired language environment
5368 is automatically configured when LyX starts up, via the
5369 \begin_inset Flex CharStyle:MenuItem
5372 \begin_layout Plain Layout
5373 Edit\SpecialChar \menuseparator
5382 \begin_layout Chapter
5383 Installing New Document Classes, Layouts, and Templates
5384 \begin_inset CommandInset label
5386 name "chap:textclass"
5394 \begin_layout Plain Layout
5395 Installing New Document Classes
5403 \begin_layout Standard
5404 In this chapter, we describe the procedures for creating and installing
5405 new LyX layout and template files, as well as offer a refresher on correctly
5406 installing new LaTeX document classes.
5407 Some definitions: a document class is a LaTeX file (usually ending in
5408 \begin_inset Flex CharStyle:Code
5411 \begin_layout Plain Layout
5418 \begin_inset Flex CharStyle:Code
5421 \begin_layout Plain Layout
5427 ) that describes the format of a document such as an article, report, journal
5428 preprint, etc, and all the commands needed to realize that format.
5429 A layout file is a LyX file that corresponds to a LaTeX document class
5430 and that tells LyX how to
5431 \begin_inset Quotes eld
5435 \begin_inset Quotes erd
5438 things on the screen to make the display look something like the final
5440 More precisely, a layout file describes a
5441 \begin_inset Quotes eld
5445 \begin_inset Quotes erd
5448 which is the internal construct LyX uses to render the screen display.
5450 \begin_inset Quotes eld
5454 \begin_inset Quotes erd
5458 \begin_inset Quotes eld
5462 \begin_inset Quotes erd
5465 can be used somewhat interchangeably, but it is better to refer to the
5466 file as the layout, and the thing living in LyX's memory as the text class.
5467 A template file is simply a LyX document that contains a set of predefined
5468 entries for a given document class—entries that are generally required
5470 Templates are especially useful for things like journal manuscripts that
5471 are to be submitted electronically.
5474 \begin_layout Section
5475 Installing a new LaTeX package
5478 \begin_layout Standard
5479 Some installations may not include a LaTeX package that you would like to
5481 For example, you might need FoilTeX, a package for preparing slides or
5482 viewgraphs for overhead projectors.
5483 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5484 a user interface for that.
5485 For example on MiKTeX you start its program
5486 \begin_inset Quotes eld
5490 \begin_inset Quotes erd
5493 to get a list of available packages.
5494 To install one, right click on it or use the installing toolbar button.
5495 When the package you want to install is not in the list, but you have it
5497 \begin_inset Flex CharStyle:Code
5500 \begin_layout Plain Layout
5507 \begin_inset Flex CharStyle:Code
5510 \begin_layout Plain Layout
5516 -file, then copy these files to a subfolder of your LaTeX distribution,
5517 for example to the folder
5526 Then update the file name database of your LaTeX-distribution.
5527 For example on MiKTeX this is done by pressing the button
5530 \begin_inset space ~
5535 that you find in MiKTeX's
5536 \begin_inset Quotes eld
5540 \begin_inset Quotes erd
5544 In both cases you need afterwards to reconfigure LyX using the menu
5545 \begin_inset Flex CharStyle:MenuItem
5548 \begin_layout Plain Layout
5549 Tools\SpecialChar \menuseparator
5555 and then to restart LyX.
5558 \begin_layout Standard
5559 If your LaTeX distribution doesn't provide a user interface, then you can
5560 follow these steps by using a UNIX/Linux console.
5563 \begin_layout Enumerate
5564 Get the package from
5565 \begin_inset CommandInset href
5568 target "http://www.ctan.org/"
5575 \begin_layout Enumerate
5576 You can install this package in several different places.
5577 If you want it to be available for all users on your system, then you should
5578 install it in your `local' TeX tree; if you want (or need) it to be available
5579 just for you, then you can install it in your own `user' TeX tree.
5580 Where these should be created, if they do not already exist, depends upon
5581 the details of your system.
5582 To find out, look in the file
5583 \begin_inset Flex CharStyle:Code
5586 \begin_layout Plain Layout
5596 \begin_layout Plain Layout
5597 This usually lives in the directory
5598 \begin_inset Flex CharStyle:Code
5601 \begin_layout Plain Layout
5607 , though you can run
5608 \begin_inset Flex CharStyle:Code
5611 \begin_layout Plain Layout
5622 The location of the `local' TeX tree is defined by
5623 \begin_inset Flex CharStyle:Code
5626 \begin_layout Plain Layout
5632 ; this is usually somewhere like
5633 \begin_inset Flex CharStyle:Code
5636 \begin_layout Plain Layout
5637 /usr/local/share/texmf/
5643 The `user' TeX tree is defined by
5644 \begin_inset Flex CharStyle:Code
5647 \begin_layout Plain Layout
5654 \begin_inset Flex CharStyle:Code
5657 \begin_layout Plain Layout
5664 (If these variables are not predefined, you can define them.) You'll probably
5665 need root permissions to create or modify the `local' tree; but your `user'
5666 tree shouldn't have such limitations.
5669 \begin_layout Enumerate
5671 \begin_inset Flex CharStyle:Code
5674 \begin_layout Plain Layout
5681 \begin_inset Flex CharStyle:Code
5684 \begin_layout Plain Layout
5691 \begin_inset Flex CharStyle:Code
5694 \begin_layout Plain Layout
5701 \begin_inset space \thinspace{}
5705 \begin_inset Newline newline
5709 \begin_inset Flex CharStyle:Code
5712 \begin_layout Plain Layout
5713 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5719 \begin_inset Newline newline
5722 But, again, most of this will
5723 \begin_inset Quotes eld
5727 \begin_inset Quotes erd
5733 \begin_layout Enumerate
5738 \begin_layout Plain Layout
5739 We'll assume henceforth that you're defining `local' TeX tree.
5740 If you're defining a user tree, just adjust as necessary.
5746 You must follow the directory structure of your existing
5747 \begin_inset Flex CharStyle:Code
5750 \begin_layout Plain Layout
5756 directory, which will be found at
5757 \begin_inset Flex CharStyle:Code
5760 \begin_layout Plain Layout
5767 For example, latex packages should go under
5768 \begin_inset Flex CharStyle:Code
5771 \begin_layout Plain Layout
5772 $TEXMFLOCAL/tex/latex/
5780 \begin_layout Enumerate
5781 Install the package.
5782 For example, you would unpack the FoilTeX tarball and copy it to
5783 \begin_inset Flex CharStyle:Code
5786 \begin_layout Plain Layout
5787 $TEXMFLOCAL/tex/latex/foiltex
5794 \begin_inset Flex CharStyle:Code
5797 \begin_layout Plain Layout
5803 directory contains various files.
5806 \begin_layout Enumerate
5808 \begin_inset Flex CharStyle:Code
5811 \begin_layout Plain Layout
5819 \begin_inset Flex CharStyle:Code
5822 \begin_layout Plain Layout
5831 \begin_layout Standard
5832 Your package is now installed and available to LaTeX.
5833 To make it available to LyX, you need to create a Layout file, if one is
5834 not already available.
5835 (See the next section.) Once you have a layout file, you need only reconfigure
5837 \begin_inset Flex CharStyle:MenuItem
5840 \begin_layout Plain Layout
5841 Tools\SpecialChar \menuseparator
5847 ) and then restart LyX.
5848 You should then see your new package—for example
5849 \begin_inset Flex CharStyle:MenuItem
5852 \begin_layout Plain Layout
5859 \begin_inset Flex CharStyle:MenuItem
5862 \begin_layout Plain Layout
5863 Document\SpecialChar \menuseparator
5870 \begin_inset Flex CharStyle:MenuItem
5873 \begin_layout Plain Layout
5883 \begin_layout Section
5887 \begin_layout Standard
5888 This section describes how to write and install your own LyX layout files
5889 and walks through the
5890 \begin_inset Flex CharStyle:Code
5893 \begin_layout Plain Layout
5899 text class format as an example.
5901 \begin_inset Flex CharStyle:Code
5904 \begin_layout Plain Layout
5910 files describe what paragraph and character styles are available for a
5911 given document class and how LyX should display them.
5912 We try to provide a thorough description of the process here; however,
5913 there are so many different types of documents supported by LaTeX classes
5914 that we can't hope to cover every different possibility or problem you
5916 (The LyX users' list is frequented by people with lots of experience with
5917 layout design who are willing to share what they've learned.)
5920 \begin_layout Standard
5921 As you prepare to write a new layout, it is extremely helpful to look at
5922 the example layouts distributed with LyX.
5923 If you use a nice LaTeX document class that might be of interest for others,
5924 too, and have a nice corresponding LyX layout, feel free to contribute
5925 the stuff to us, so we may put it into the distribution.
5927 \begin_inset CommandInset href
5929 name "section on the LyX wiki"
5930 target "http://wiki.lyx.org/Layouts/Layouts"
5934 for this kind of material.
5937 \begin_layout Standard
5938 All the tags described in this chapter are case-insensitive; this means
5940 \begin_inset Flex CharStyle:Code
5943 \begin_layout Plain Layout
5950 \begin_inset Flex CharStyle:Code
5953 \begin_layout Plain Layout
5960 \begin_inset Flex CharStyle:Code
5963 \begin_layout Plain Layout
5969 are really the same command.
5970 The possible values are printed in brackets after the feature's name.
5971 The default value if a feature isn't specified inside a text class-description
5973 \begin_inset Flex CharStyle:Code
5976 \begin_layout Plain Layout
5985 If the argument has a data type like
5986 \begin_inset Quotes eld
5990 \begin_inset Quotes erd
5994 \begin_inset Quotes eld
5998 \begin_inset Quotes erd
6001 , the default is shown like this:
6002 \begin_inset Flex CharStyle:Code
6005 \begin_layout Plain Layout
6016 \begin_layout Subsection
6017 \begin_inset CommandInset label
6019 name "sub:Layout-modules"
6026 \begin_layout Standard
6027 Similar to layout files, and new with LyX 1.6, are layout
6032 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6033 some modules—such as the endnotes module—provide support for just such
6035 In a sense, layout modules are similar to included files—files like
6036 \begin_inset Flex CharStyle:Code
6039 \begin_layout Plain Layout
6045 —in that modules are not specific to a given document layout but may be
6046 used with many different layouts.
6047 The difference is that using a layout module does not require editing the
6049 Rather, modules are selected in the
6050 \begin_inset Flex CharStyle:MenuItem
6053 \begin_layout Plain Layout
6054 Document\SpecialChar \menuseparator
6063 \begin_layout Standard
6064 Building modules is the easiest way to get started with layout editing,
6065 since it can be as simple as adding a single new paragraph or flex inset.
6066 But modules may, in principle, contain anything a layout file can contain.
6069 \begin_layout Standard
6070 A module must begin with a line like the following:
6073 \begin_layout LyX-Code
6076 DeclareLyXModule[endnotes.sty]{Endnotes}
6079 \begin_layout Standard
6080 The argument in square brackets is optional: It declares any LaTeX packages
6081 on which the module depends.
6082 The mandatory argument, in curly brackets, is the name of the module, as
6084 \begin_inset Flex CharStyle:MenuItem
6087 \begin_layout Plain Layout
6088 Document\SpecialChar \menuseparator
6098 \begin_layout Standard
6099 The module declaration should then be followed by lines like the following:
6102 \begin_layout LyX-Code
6106 \begin_layout LyX-Code
6107 #Adds an endnote command, in addition to footnotes.
6111 \begin_layout LyX-Code
6112 #You will need to add
6114 theendnotes in TeX code where you
6117 \begin_layout LyX-Code
6118 #want the endnotes to appear.
6122 \begin_layout LyX-Code
6126 \begin_layout LyX-Code
6127 #Requires: somemodule | othermodule
6130 \begin_layout LyX-Code
6131 #Excludes: badmodule
6134 \begin_layout Standard
6135 The description is used in
6136 \begin_inset Flex CharStyle:MenuItem
6139 \begin_layout Plain Layout
6140 Document\SpecialChar \menuseparator
6146 to provide the user with information about what the module does.
6148 \begin_inset Flex CharStyle:Code
6151 \begin_layout Plain Layout
6157 line is used to identify other modules with which this one must be used;
6159 \begin_inset Flex CharStyle:Code
6162 \begin_layout Plain Layout
6168 line is used to identify modules with which this one may not be used.
6169 Both are optional, and, as shown, multiple modules should be separated
6170 with the pipe symbol: |.
6171 Note that the required modules are treated disjunctively:
6175 of the required modules must be used.
6180 excluded module may be used.
6181 Note that modules are identified here by their
6185 without the .module extension.
6187 \begin_inset Flex CharStyle:Code
6190 \begin_layout Plain Layout
6197 \begin_inset Flex CharStyle:Code
6200 \begin_layout Plain Layout
6209 \begin_layout Standard
6210 After creating a new module, you will need to reconfigure and then restart
6211 LyX for the module to appear in the menu.
6212 However, changes you make to the module will be seen immediately, if you
6214 \begin_inset Flex CharStyle:MenuItem
6217 \begin_layout Plain Layout
6218 Document\SpecialChar \menuseparator
6224 , highlight something, and then hit
6225 \begin_inset Quotes eld
6229 \begin_inset Quotes erd
6235 It is strongly recommended that you save your work before doing so
6240 it is strongly recommended that you not attempt to edit modules while simultaneo
6241 usly working on documents
6244 Though of course the developers strive to keep LyX stable in such situations,
6245 syntax errors and the like in your module file could cause strange behavior.
6248 \begin_layout Subsection
6249 Supporting new document classes
6252 \begin_layout Standard
6253 There are two situations you are likely to encounter when wanting to support
6254 a new LaTeX document class, involving LaTeX2e class (
6255 \begin_inset Flex CharStyle:Code
6258 \begin_layout Plain Layout
6265 \begin_inset Flex CharStyle:Code
6268 \begin_layout Plain Layout
6275 Supporting a style file is usually fairly easy.
6276 Supporting a new document class is a bit harder.
6279 \begin_layout Subsection
6281 \begin_inset Flex CharStyle:MenuItem
6284 \begin_layout Plain Layout
6293 \begin_layout Standard
6294 If your new document class is provided as a style file that is used in conjuncti
6295 on with an existing, supported document class—for the sake of the example,
6296 we'll assume that the style file is called
6297 \begin_inset Flex CharStyle:MenuItem
6300 \begin_layout Plain Layout
6306 and it is meant to be used with
6307 \begin_inset Flex CharStyle:MenuItem
6310 \begin_layout Plain Layout
6316 , which is a standard class—start by copying the existing class's layout
6317 file into your local directory:
6320 \begin_layout LyX-Code
6321 cp report.layout ~/.lyx/layouts/myclass.layout
6324 \begin_layout Standard
6326 \begin_inset Flex CharStyle:Code
6329 \begin_layout Plain Layout
6335 and change the line:
6338 \begin_layout LyX-Code
6341 DeclareLaTeXClass{report}
6344 \begin_layout Standard
6348 \begin_layout LyX-Code
6351 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6354 \begin_layout Standard
6358 \begin_layout LyX-Code
6360 \begin_inset Newline newline
6366 \begin_inset Newline newline
6372 \begin_layout Standard
6373 near the top of the file.
6376 \begin_layout Standard
6377 Start LyX and select
6378 \begin_inset Flex CharStyle:MenuItem
6381 \begin_layout Plain Layout
6382 Tools\SpecialChar \menuseparator
6389 Then restart LyX and try creating a new document.
6391 \begin_inset Flex CharStyle:MenuItem
6394 \begin_layout Plain Layout
6400 " as a document class option in the
6401 \begin_inset Flex CharStyle:MenuItem
6404 \begin_layout Plain Layout
6405 Document\SpecialChar \menuseparator
6412 It is likely that some of the sectioning commands and such in your new
6413 class will work differently from how they worked in the base class—
6414 \begin_inset Flex CharStyle:Code
6417 \begin_layout Plain Layout
6423 in this example—so you can fiddle around with the settings for the different
6424 sections if you wish.
6427 \begin_layout Subsection
6429 \begin_inset Flex CharStyle:MenuItem
6432 \begin_layout Plain Layout
6441 \begin_layout Standard
6442 There are two possibilities here.
6443 One is that the class file is itself based upon an existing document class.
6444 For example, many thesis classes are based upon
6445 \begin_inset Flex CharStyle:MenuItem
6448 \begin_layout Plain Layout
6455 To see whether yours is, look for a line like
6458 \begin_layout LyX-Code
6464 \begin_layout Standard
6466 If so, then you may proceed largely as in the previous section, though
6467 the DeclareLaTeXClass line will be different.
6468 If your new class is thesis, and it is based upon book, then the line should
6473 \begin_layout Plain Layout
6474 And it will be easiest if you save the file to
6475 \begin_inset Flex CharStyle:Code
6478 \begin_layout Plain Layout
6484 : LyX assumes that the document class has the same name as the layout file.
6493 \begin_layout LyX-Code
6496 DeclareLaTeXClass[thesis,book]{thesis}
6499 \begin_layout Standard
6500 If, on the other hand, the new class is not based upon an existing class,
6501 you will probably have to
6502 \begin_inset Quotes eld
6506 \begin_inset Quotes erd
6510 We strongly suggest copying an existing layout file which uses a similar
6511 LaTeX class and then modifying it, if you can do so.
6512 At least use an existing file as a starting point so you can find out what
6513 items you need to worry about.
6514 Again, the specifics are covered below.
6517 \begin_layout Section
6518 Declaring a new text class
6521 \begin_layout Standard
6522 When it's finally time to get your hands dirty and create or edit your own
6523 layout file, the following sections describe what you're up against.
6524 Our advice is to go slowly, save and test often, listen to soothing music,
6525 and enjoy one or two of your favorite adult beverages; more if you are
6526 getting particularly stuck.
6527 It's really not that hard, except that the multitude of options can become
6528 overwhelming if you try to do to much in one sitting.
6529 Go have another adult beverage, just for good measure.
6532 \begin_layout Standard
6536 \begin_layout Standard
6537 Lines in a layout file which begin with a
6538 \begin_inset Flex CharStyle:Code
6541 \begin_layout Plain Layout
6548 There is one exception to this rule: all layouts should begin with lines
6552 \begin_layout LyX-Code
6555 #% Do not delete the line below; configure depends on this
6558 \begin_layout LyX-Code
6563 DeclareLaTeXClass{article}
6566 \begin_layout Standard
6567 The second line is used when you configure LyX.
6568 The layout file is read by the LaTeX script
6569 \begin_inset Flex CharStyle:Code
6572 \begin_layout Plain Layout
6578 , in a special mode where
6579 \begin_inset Flex CharStyle:Code
6582 \begin_layout Plain Layout
6589 The first line is just a LaTeX comment, and the second one contains the
6590 declaration of the text class.
6591 If these lines appear in a file named
6592 \begin_inset Flex CharStyle:Code
6595 \begin_layout Plain Layout
6601 , then they define a text class of name
6602 \begin_inset Flex CharStyle:Code
6605 \begin_layout Plain Layout
6611 (the name of the layout file) which uses the LaTeX document class
6612 \begin_inset Flex CharStyle:Code
6615 \begin_layout Plain Layout
6621 (the default is to use the same name as the layout).
6623 \begin_inset Quotes eld
6627 \begin_inset Quotes erd
6630 that appears above is used as a description of the text class in the
6631 \begin_inset Flex CharStyle:MenuItem
6634 \begin_layout Plain Layout
6635 Document\SpecialChar \menuseparator
6644 \begin_layout Standard
6645 Let's assume that you wrote your own text class that uses the
6646 \begin_inset Flex CharStyle:Code
6649 \begin_layout Plain Layout
6655 document class, but where you changed the appearance of the section headings.
6656 If you put it in a file
6657 \begin_inset Flex CharStyle:Code
6660 \begin_layout Plain Layout
6666 , the header of this file should be:
6669 \begin_layout LyX-Code
6672 #% Do not delete the line below; configure depends on this
6675 \begin_layout LyX-Code
6680 DeclareLaTeXClass[article]{article (with my own headings)}
6683 \begin_layout Standard
6684 This declares a text class
6685 \begin_inset Flex CharStyle:Code
6688 \begin_layout Plain Layout
6694 , associated with the LaTeX document class
6695 \begin_inset Flex CharStyle:Code
6698 \begin_layout Plain Layout
6705 \begin_inset Quotes eld
6708 article (with my own headings)
6709 \begin_inset Quotes erd
6713 If your text class depends on several packages, you can declare it as:
6716 \begin_layout LyX-Code
6719 #% Do not delete the line below; configure depends on this
6722 \begin_layout LyX-Code
6727 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6730 \begin_layout Standard
6731 This indicates that your text class uses the foo.sty package.
6732 Finally, it is also possible to declare classes for DocBook code.
6733 Typical declarations will look like
6736 \begin_layout LyX-Code
6739 #% Do not delete the line below; configure depends on this
6742 \begin_layout LyX-Code
6747 DeclareDocBookClass[article]{SGML (DocBook article)}
6750 \begin_layout Standard
6751 Note that these declarations can also be given an optional parameter declaring
6752 the name of the document class (but not a list).
6755 \begin_layout Standard
6756 So, to be as explicit as possible, the form of the layout declaration is:
6759 \begin_layout LyX-Code
6764 DeclareLaTeXClass[class,package.sty]{layout description}
6767 \begin_layout Standard
6768 The class need only be specified if the name of the LaTeX class file and
6769 the name of the layout file are different; if the name of the class file
6770 is not specified, then LyX will simply assume that it is the same as the
6771 name of the layout file.
6774 \begin_layout Standard
6775 When the text class has been modified to your taste, all you have to do
6776 is to copy it either to
6777 \begin_inset Flex CharStyle:Code
6780 \begin_layout Plain Layout
6787 \begin_inset Flex CharStyle:Code
6790 \begin_layout Plain Layout
6797 \begin_inset Flex CharStyle:MenuItem
6800 \begin_layout Plain Layout
6801 Tools\SpecialChar \menuseparator
6807 , exit LyX and restart it.
6808 Then your new text class should be available along with the others.
6811 \begin_layout Standard
6812 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6813 you made to your layout files.
6814 As a result, editing layout files could be very time consuming.
6815 Beginning with 1.6, however, you can force a reload of the layout currently
6816 in use by using the LyX function
6817 \begin_inset Flex CharStyle:MenuItem
6820 \begin_layout Plain Layout
6827 There is no default binding for this function—though, of course, you can
6828 bind it to a key yourself.
6829 If you want to use this function, then, you should simply enter it in the
6835 : This is very much an `advanced feature'.
6840 recommended that you save your work before using this function.
6845 recommended that you not attempt to edit your layout while simultaneously
6846 working on a document that you care about.
6847 Use a test document.
6848 Syntax errors and the like in your layout file could cause peculiar behavior.
6849 In particular, such errors could cause LyX to regard the current layout
6850 as invalid and to attempt to switch to some other layout.
6851 The LyX team strives to keep LyX stable in such situations, but safe is
6855 \begin_layout Subsection
6859 \begin_layout Standard
6860 The first non-comment line must contain the file format number:
6863 \begin_layout Description
6864 \begin_inset Flex CharStyle:Code
6867 \begin_layout Plain Layout
6874 \begin_inset Flex CharStyle:Code
6877 \begin_layout Plain Layout
6883 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6884 don't have an explicit file format).
6885 The file format that is documented here is format 14.
6888 \begin_layout Subsection
6889 General text class parameters
6892 \begin_layout Standard
6893 These are the general parameters which describe the form of the entire document:
6896 \begin_layout Description
6897 \begin_inset Flex CharStyle:Code
6900 \begin_layout Plain Layout
6906 Adds information to the document preamble.
6908 \begin_inset Quotes eld
6912 \begin_inset Flex CharStyle:Code
6915 \begin_layout Plain Layout
6922 \begin_inset Quotes erd
6928 \begin_layout Description
6929 \begin_inset Flex CharStyle:Code
6932 \begin_layout Plain Layout
6938 Describes various global options supported by the document class.
6940 \begin_inset space ~
6944 \begin_inset CommandInset ref
6946 reference "sec:classoptions"
6952 \begin_inset Quotes eld
6956 \begin_inset Flex CharStyle:Code
6959 \begin_layout Plain Layout
6966 \begin_inset Quotes erd
6972 \begin_layout Description
6973 \begin_inset Flex CharStyle:Code
6976 \begin_layout Plain Layout
6983 \begin_inset Flex CharStyle:Code
6986 \begin_layout Plain Layout
6995 \begin_inset Flex CharStyle:Code
6998 \begin_layout Plain Layout
7004 ] Whether the class should default to having one or two columns.
7005 Can be changed in the
7006 \begin_inset Flex CharStyle:MenuItem
7009 \begin_layout Plain Layout
7010 Document\SpecialChar \menuseparator
7019 \begin_layout Description
7020 \begin_inset Flex CharStyle:Code
7023 \begin_layout Plain Layout
7029 This sequence defines a new counter.
7031 \begin_inset space ~
7035 \begin_inset CommandInset ref
7037 reference "sec:counter"
7043 \begin_inset Quotes eld
7047 \begin_inset Flex CharStyle:Code
7050 \begin_layout Plain Layout
7057 \begin_inset Quotes erd
7063 \begin_layout Description
7064 \begin_inset Flex CharStyle:Code
7067 \begin_layout Plain Layout
7073 Sets the default font used to display the document.
7075 \begin_inset space ~
7079 \begin_inset CommandInset ref
7081 reference "sec:fonts"
7085 for how to declare fonts.
7087 \begin_inset Quotes eld
7091 \begin_inset Flex CharStyle:Code
7094 \begin_layout Plain Layout
7101 \begin_inset Quotes erd
7107 \begin_layout Description
7108 \begin_inset Flex CharStyle:Code
7111 \begin_layout Plain Layout
7118 \begin_inset Flex CharStyle:Code
7121 \begin_layout Plain Layout
7127 Specifies a module to be included by default with this document class,
7128 which should be specified by filename without the
7129 \begin_inset Flex CharStyle:Code
7132 \begin_layout Plain Layout
7139 The user can still remove the module, but it will be active at the outset.
7140 (This applies only when new files are created, or when this class is chosen
7141 for an existing document.)
7144 \begin_layout Description
7145 \begin_inset Flex CharStyle:Code
7148 \begin_layout Plain Layout
7155 \begin_inset Flex CharStyle:Code
7158 \begin_layout Plain Layout
7164 ] This is the style that will be assigned to new paragraphs, usually
7165 \begin_inset Flex CharStyle:MenuItem
7168 \begin_layout Plain Layout
7175 This will default to the first defined style if not given, but you are
7176 highly encouraged to use this directive.
7179 \begin_layout Description
7180 \begin_inset Flex CharStyle:Code
7183 \begin_layout Plain Layout
7190 \begin_inset Flex CharStyle:Code
7193 \begin_layout Plain Layout
7199 ] Indicates that the module in question—which should be specified by filename
7201 \begin_inset Flex CharStyle:Code
7204 \begin_layout Plain Layout
7210 extension—cannot be used with this document class.
7211 This might be used in a journal-specific layout file to prevent, say, the
7213 \begin_inset Flex CharStyle:Code
7216 \begin_layout Plain Layout
7222 module that numbers theorems by section.
7227 be used in a module.
7228 Modules have their own way of excluding other modules (see
7229 \begin_inset CommandInset ref
7231 reference "sub:Layout-modules"
7238 \begin_layout Description
7239 \begin_inset Flex CharStyle:Code
7242 \begin_layout Plain Layout
7248 Defines a new float.
7250 \begin_inset space ~
7254 \begin_inset CommandInset ref
7256 reference "sec:floats"
7262 \begin_inset Quotes eld
7266 \begin_inset Flex CharStyle:Code
7269 \begin_layout Plain Layout
7276 \begin_inset Quotes erd
7282 \begin_layout Description
7283 \begin_inset Flex CharStyle:Code
7286 \begin_layout Plain Layout
7292 As its name implies, this command allows you to include another layout
7293 definition file within yours to avoid duplicating commands.
7294 Common examples are the standard layout files, for example,
7295 \begin_inset Flex CharStyle:Code
7298 \begin_layout Plain Layout
7304 , which contains most of the basic layouts.
7307 \begin_layout Description
7308 \begin_inset Flex CharStyle:Code
7311 \begin_layout Plain Layout
7317 This section (re-)defines the layout of an inset.
7318 It can be applied to an existing inset of to a new, user-defined inset,
7320 \begin_inset space \thinspace{}
7324 \begin_inset space \space{}
7327 a new character style.
7329 \begin_inset space ~
7333 \begin_inset CommandInset ref
7335 reference "sec:charstyle"
7339 for more information.
7341 \begin_inset Quotes eld
7345 \begin_inset Flex CharStyle:Code
7348 \begin_layout Plain Layout
7355 \begin_inset Quotes erd
7361 \begin_layout Description
7362 \begin_inset Flex CharStyle:Code
7365 \begin_layout Plain Layout
7371 A string that indicates the width of the left margin on the screen, for
7373 \begin_inset Quotes eld
7377 \begin_inset Quotes erd
7383 \begin_layout Description
7384 \begin_inset Flex CharStyle:Code
7387 \begin_layout Plain Layout
7393 This command deletes an existing float.
7394 This is particularly useful when you want to suppress a float that has
7395 be defined in an input file.
7398 \begin_layout Description
7399 \begin_inset Flex CharStyle:Code
7402 \begin_layout Plain Layout
7408 This command deletes an existing style.
7409 This is particularly useful when you want to suppress a style that has
7410 be defined in an input file.
7413 \begin_layout Description
7414 \begin_inset Flex CharStyle:Code
7417 \begin_layout Plain Layout
7423 A string indicating what sort of output documents using this class will
7425 At present, the options are: `docbook', `latex', and `literate'.
7428 \begin_layout Description
7429 \begin_inset Flex CharStyle:Code
7432 \begin_layout Plain Layout
7443 \begin_inset Flex CharStyle:Code
7446 \begin_layout Plain Layout
7457 \begin_inset Flex CharStyle:Code
7460 \begin_layout Plain Layout
7467 \begin_inset Flex CharStyle:Code
7470 \begin_layout Plain Layout
7476 ] The class default pagestyle.
7477 Can be changed in the
7478 \begin_inset Flex CharStyle:MenuItem
7481 \begin_layout Plain Layout
7482 Document\SpecialChar \menuseparator
7491 \begin_layout Description
7492 \begin_inset Flex CharStyle:Code
7495 \begin_layout Plain Layout
7501 Sets the preamble for the LaTeX document.
7502 Note that this will completely override any prior
7503 \begin_inset Flex CharStyle:Code
7506 \begin_layout Plain Layout
7513 \begin_inset Flex CharStyle:Code
7516 \begin_layout Plain Layout
7524 \begin_inset Quotes eld
7528 \begin_inset Flex CharStyle:Code
7531 \begin_layout Plain Layout
7538 \begin_inset Quotes erd
7544 \begin_layout Description
7545 \begin_inset Flex CharStyle:Code
7548 \begin_layout Plain Layout
7555 \begin_inset Flex CharStyle:Code
7558 \begin_layout Plain Layout
7565 \begin_inset Flex CharStyle:Code
7568 \begin_layout Plain Layout
7577 \begin_inset Flex CharStyle:Code
7580 \begin_layout Plain Layout
7586 ] Whether the class already provides the feature
7587 \begin_inset Flex CharStyle:Code
7590 \begin_layout Plain Layout
7597 A feature is in general the name of a package (
7598 \begin_inset Flex CharStyle:Code
7601 \begin_layout Plain Layout
7608 \begin_inset Flex CharStyle:Code
7611 \begin_layout Plain Layout
7617 , \SpecialChar \ldots{}
7619 \begin_inset Flex CharStyle:Code
7622 \begin_layout Plain Layout
7629 \begin_inset Flex CharStyle:Code
7632 \begin_layout Plain Layout
7638 ,\SpecialChar \ldots{}
7639 ); the complete list of supported features is unfortunately not documented
7640 outside the LyX source code—but see
7641 \begin_inset Flex CharStyle:Code
7644 \begin_layout Plain Layout
7650 if you're interested.
7652 \begin_inset Flex CharStyle:MenuItem
7655 \begin_layout Plain Layout
7656 Help\SpecialChar \menuseparator
7662 also gives an overview of the supported packages.
7665 \begin_layout Description
7666 \begin_inset Flex CharStyle:Code
7669 \begin_layout Plain Layout
7676 \begin_inset Flex CharStyle:Code
7679 \begin_layout Plain Layout
7685 ] Indicates that this layout provides the functionality of the module mentioned,
7686 which should be specified by the filename without the
7687 \begin_inset Flex CharStyle:Code
7690 \begin_layout Plain Layout
7697 This will typically be used if the layout includes the module directly,
7698 rather than using the
7699 \begin_inset Flex CharStyle:Code
7702 \begin_layout Plain Layout
7708 tag to indicate that it ought to be used.
7709 It could be used in a module that provided an alternate implementation
7710 of the same functionality.
7713 \begin_layout Description
7714 \begin_inset Flex CharStyle:Code
7717 \begin_layout Plain Layout
7724 \begin_inset Flex CharStyle:Code
7727 \begin_layout Plain Layout
7733 ] Whether the class requires the feature
7734 \begin_inset Flex CharStyle:Code
7737 \begin_layout Plain Layout
7744 Multiple features must be separated by commas.
7745 Note that you can only request supported features.
7748 \begin_layout Description
7749 \begin_inset Flex CharStyle:Code
7752 \begin_layout Plain Layout
7758 A string that indicates the width of the right margin on the screen, for
7760 \begin_inset Quotes eld
7764 \begin_inset Quotes erd
7770 \begin_layout Description
7771 \begin_inset Flex CharStyle:Code
7774 \begin_layout Plain Layout
7780 Sets which divisions get numbered.
7782 \begin_inset Flex CharStyle:Code
7785 \begin_layout Plain Layout
7794 \begin_layout Description
7795 \begin_inset Flex CharStyle:Code
7798 \begin_layout Plain Layout
7807 \begin_inset Flex CharStyle:Code
7810 \begin_layout Plain Layout
7821 \begin_inset Flex CharStyle:Code
7824 \begin_layout Plain Layout
7830 ] Whether the class-default should be printing on one or both sides of the
7832 Can be changed in the
7833 \begin_inset Flex CharStyle:MenuItem
7836 \begin_layout Plain Layout
7837 Document\SpecialChar \menuseparator
7846 \begin_layout Description
7847 \begin_inset Flex CharStyle:Code
7850 \begin_layout Plain Layout
7856 This sequence defines a new paragraph style.
7857 If the style already exists, it will redefine some of its parameters instead.
7859 \begin_inset space ~
7863 \begin_inset CommandInset ref
7865 reference "sec:style"
7871 \begin_inset Quotes eld
7875 \begin_inset Flex CharStyle:Code
7878 \begin_layout Plain Layout
7885 \begin_inset Quotes erd
7891 \begin_layout Description
7892 \begin_inset Flex CharStyle:Code
7895 \begin_layout Plain Layout
7902 \begin_inset Flex CharStyle:Code
7905 \begin_layout Plain Layout
7911 ] The name of the command or environment to be used with
7912 \begin_inset Flex CharStyle:Code
7915 \begin_layout Plain Layout
7924 \begin_layout Description
7925 \begin_inset Flex CharStyle:Code
7928 \begin_layout Plain Layout
7935 \begin_inset Flex CharStyle:Code
7938 \begin_layout Plain Layout
7947 \begin_inset Flex CharStyle:Code
7950 \begin_layout Plain Layout
7956 ] Indicates what kind of markup is used to define the title of a document.
7958 \begin_inset Flex CharStyle:Code
7961 \begin_layout Plain Layout
7967 means that the macro with name
7968 \begin_inset Flex CharStyle:Code
7971 \begin_layout Plain Layout
7977 will be inserted after the last layout which has
7978 \begin_inset Quotes eld
7982 \begin_inset Flex CharStyle:Code
7985 \begin_layout Plain Layout
7992 \begin_inset Quotes erd
7997 \begin_inset Flex CharStyle:Code
8000 \begin_layout Plain Layout
8006 corresponds to the case where the block of paragraphs which have
8007 \begin_inset Quotes eld
8011 \begin_inset Flex CharStyle:Code
8014 \begin_layout Plain Layout
8021 \begin_inset Quotes erd
8024 should be enclosed into the
8025 \begin_inset Flex CharStyle:Code
8028 \begin_layout Plain Layout
8037 \begin_layout Description
8038 \begin_inset Flex CharStyle:Code
8041 \begin_layout Plain Layout
8047 Sets which divisions are included in the table of contents.
8049 \begin_inset Flex CharStyle:Code
8052 \begin_layout Plain Layout
8061 \begin_layout Subsection
8062 \begin_inset Flex CharStyle:Code
8065 \begin_layout Plain Layout
8074 \begin_layout Standard
8075 \begin_inset CommandInset label
8077 name "sec:classoptions"
8082 \begin_inset Flex CharStyle:Code
8085 \begin_layout Plain Layout
8091 section can contain the following entries:
8094 \begin_layout Description
8095 \begin_inset Flex CharStyle:Code
8098 \begin_layout Plain Layout
8105 \begin_inset Flex CharStyle:Code
8108 \begin_layout Plain Layout
8114 ] The list of available font sizes for the document's main font, separated
8116 \begin_inset Quotes eld
8120 \begin_inset Flex CharStyle:Code
8123 \begin_layout Plain Layout
8130 \begin_inset Quotes erd
8136 \begin_layout Description
8137 \begin_inset Flex CharStyle:Code
8140 \begin_layout Plain Layout
8146 Used to set the DTD line with XML-based output classes.
8148 \begin_inset space \thinspace{}
8152 \begin_inset Quotes eld
8155 -//OASIS//DTD DocBook V4.2//EN
8156 \begin_inset Quotes erd
8162 \begin_layout Description
8163 \begin_inset Flex CharStyle:Code
8166 \begin_layout Plain Layout
8173 \begin_inset Flex CharStyle:Code
8176 \begin_layout Plain Layout
8177 string="empty|plain|headings|fancy"
8182 ] The list of available page styles, separated by
8183 \begin_inset Quotes eld
8187 \begin_inset Flex CharStyle:Code
8190 \begin_layout Plain Layout
8197 \begin_inset Quotes erd
8203 \begin_layout Description
8204 \begin_inset Flex CharStyle:Code
8207 \begin_layout Plain Layout
8214 \begin_inset Flex CharStyle:Code
8217 \begin_layout Plain Layout
8223 ] Some document class options, separated by a comma, that will be added
8224 to the optional part of the
8225 \begin_inset Flex CharStyle:Code
8228 \begin_layout Plain Layout
8239 \begin_layout Standard
8241 \begin_inset Flex CharStyle:Code
8244 \begin_layout Plain Layout
8250 section must end with
8251 \begin_inset Quotes eld
8255 \begin_inset Flex CharStyle:Code
8258 \begin_layout Plain Layout
8265 \begin_inset Quotes erd
8271 \begin_layout Subsection
8275 \begin_layout Standard
8276 \begin_inset CommandInset label
8282 A paragraph style description looks like this:
8286 \begin_layout Plain Layout
8287 Note that this will either define a new layout or modify an existing one.
8295 \begin_layout LyX-Code
8302 \begin_layout LyX-Code
8306 \begin_layout LyX-Code
8310 \begin_layout Standard
8311 where the following commands are allowed:
8314 \begin_layout Description
8315 \begin_inset Flex CharStyle:Code
8318 \begin_layout Plain Layout
8325 \begin_inset Flex CharStyle:Code
8328 \begin_layout Plain Layout
8333 , left, right, center
8338 ] Paragraph alignment.
8341 \begin_layout Description
8342 \begin_inset Flex CharStyle:Code
8345 \begin_layout Plain Layout
8352 \begin_inset Flex CharStyle:Code
8355 \begin_layout Plain Layout
8360 , left, right, center
8365 ] A comma separated list of permitted alignments.
8366 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8368 For example a right-aligned or centered enumeration isn't possible.)
8371 \begin_layout Description
8372 \begin_inset Flex CharStyle:Code
8375 \begin_layout Plain Layout
8382 \begin_inset Flex CharStyle:Code
8385 \begin_layout Plain Layout
8395 \begin_layout Plain Layout
8396 Note that a `float' here is a real number, such as: 1.5.
8401 The vertical space with which the last of a chain of paragraphs with this
8402 layout is separated from the following paragraph.
8403 If the next paragraph has another layout, the separations are not simply
8404 added, but the maximum is taken.
8407 \begin_layout Description
8408 \begin_inset Flex CharStyle:Code
8411 \begin_layout Plain Layout
8418 \begin_inset Flex CharStyle:Code
8421 \begin_layout Plain Layout
8427 The category for this style.
8428 This is used to group related styles in the Layout combobox on the toolbar.
8429 Any string can be used, but you may want to use existing categories with
8434 \begin_layout Description
8435 \begin_inset Flex CharStyle:Code
8438 \begin_layout Plain Layout
8444 Depth of XML command.
8445 Used only with XML-type formats.
8448 \begin_layout Description
8449 \begin_inset Flex CharStyle:Code
8452 \begin_layout Plain Layout
8459 \begin_inset CommandInset label
8461 name "des:CopyStyle"
8466 \begin_inset Flex CharStyle:Code
8469 \begin_layout Plain Layout
8475 Copies all the features of an existing style into the current one.
8479 \begin_layout Description
8480 \begin_inset Flex CharStyle:Code
8483 \begin_layout Plain Layout
8489 The name of a style whose preamble should be output
8494 This allows to ensure some ordering of the preamble snippets when macros
8495 definitions depend on one another.
8499 \begin_layout Plain Layout
8500 Note that, besides that functionality, there is no way to ensure any ordering
8502 The ordering that you see in a given version of LyX may change without
8503 warning in later versions.
8511 \begin_layout Description
8512 \begin_inset Flex CharStyle:Code
8515 \begin_layout Plain Layout
8522 \begin_inset Flex CharStyle:Code
8525 \begin_layout Plain Layout
8530 , Box, Filled_Box, Static
8535 ] The type of label that stands at the end of the paragraph (or sequence
8537 \begin_inset Flex CharStyle:Code
8540 \begin_layout Plain Layout
8547 \begin_inset Flex CharStyle:Code
8550 \begin_layout Plain Layout
8557 \begin_inset Flex CharStyle:Code
8560 \begin_layout Plain Layout
8567 \begin_inset Flex CharStyle:Code
8570 \begin_layout Plain Layout
8578 \begin_inset Flex CharStyle:Code
8581 \begin_layout Plain Layout
8588 \begin_inset Quotes eld
8592 \begin_inset Quotes erd
8596 \begin_inset Flex CharStyle:Code
8599 \begin_layout Plain Layout
8606 \begin_inset Flex CharStyle:Code
8609 \begin_layout Plain Layout
8610 \begin_inset space ~
8619 \begin_inset space ~
8622 black) square suitable for end of proof markers,
8623 \begin_inset Flex CharStyle:Code
8626 \begin_layout Plain Layout
8632 is an explicit text string.
8635 \begin_layout Description
8636 \begin_inset Flex CharStyle:Code
8639 \begin_layout Plain Layout
8646 \begin_inset Flex CharStyle:Code
8649 \begin_layout Plain Layout
8655 ] The string used for a label with a
8656 \begin_inset Flex CharStyle:Code
8659 \begin_layout Plain Layout
8666 \begin_inset Flex CharStyle:Code
8669 \begin_layout Plain Layout
8679 \begin_layout Description
8680 \begin_inset Flex CharStyle:Code
8683 \begin_layout Plain Layout
8690 \begin_inset Flex CharStyle:Code
8693 \begin_layout Plain Layout
8704 \begin_inset Flex CharStyle:Code
8707 \begin_layout Plain Layout
8716 \begin_layout Description
8717 \begin_inset Flex CharStyle:Code
8720 \begin_layout Plain Layout
8727 \begin_inset Flex CharStyle:Code
8730 \begin_layout Plain Layout
8740 ] With this parameter the
8741 \begin_inset Flex CharStyle:MenuItem
8744 \begin_layout Plain Layout
8751 \begin_inset Quotes eld
8754 Vertical space above
8755 \begin_inset Quotes erd
8759 \begin_inset Flex CharStyle:MenuItem
8762 \begin_layout Plain Layout
8763 Edit\SpecialChar \menuseparator
8765 \begin_inset space ~
8773 dialog can be set when initializing a paragraph with this style.
8777 \begin_layout Plain Layout
8780 Note from Jean-Marc:
8782 I'm not sure that this setting has much use, and it should probably be
8783 removed in later versions.
8791 \begin_layout Description
8792 \begin_inset Flex CharStyle:Code
8795 \begin_layout Plain Layout
8801 The font used for both the text body
8807 \begin_inset space ~
8811 \begin_inset CommandInset ref
8813 reference "sec:fonts"
8818 Note that defining this font automatically defines the
8819 \begin_inset Flex CharStyle:Code
8822 \begin_layout Plain Layout
8829 So you should define this one first if you also want to define
8830 \begin_inset Flex CharStyle:Code
8833 \begin_layout Plain Layout
8842 \begin_layout Description
8843 \begin_inset Flex CharStyle:Code
8846 \begin_layout Plain Layout
8853 \begin_inset CommandInset label
8855 name "des:FreeSpacing"
8862 \begin_inset Flex CharStyle:Code
8865 \begin_layout Plain Layout
8876 \begin_inset Flex CharStyle:Code
8879 \begin_layout Plain Layout
8885 ] Usually LyX doesn't allow you to insert more than one space between words,
8886 since a space is considered as the separation between two words, not a
8887 character or symbol of its own.
8888 This is a very fine thing but sometimes annoying, for example, when typing
8889 program code or plain LaTeX code.
8891 \begin_inset Flex CharStyle:Code
8894 \begin_layout Plain Layout
8901 Note that LyX will create protected blanks for the additional blanks when
8902 in another mode than LaTeX-mode.
8905 \begin_layout Description
8906 \begin_inset Flex CharStyle:Code
8909 \begin_layout Plain Layout
8915 Language dependent information to be included in the LaTeX preamble when
8917 Note that this will completely override any prior
8918 \begin_inset Flex CharStyle:Code
8921 \begin_layout Plain Layout
8929 \begin_inset Quotes eld
8933 \begin_inset Flex CharStyle:Code
8936 \begin_layout Plain Layout
8943 \begin_inset Quotes erd
8947 The contents of this tag will occur once in the LaTeX preamble for each
8948 language used by the document.
8949 Each time, the following substitutions are made:
8953 \begin_layout Itemize
8954 \begin_inset Flex CharStyle:Code
8957 \begin_layout Plain Layout
8963 is replaced by the language name (as used by the babel package).
8966 \begin_layout Itemize
8968 \begin_inset Quotes eld
8972 \begin_inset Quotes erd
8976 \begin_inset Flex CharStyle:Code
8979 \begin_layout Plain Layout
8985 replaces its argument by the translation of the argument to the current
8989 \begin_layout Standard
8990 This preamble snippet will only be used if the document contains more than
8991 one language and the babel package is used.
8995 \begin_layout Description
8996 \begin_inset Flex CharStyle:Code
8999 \begin_layout Plain Layout
9006 \begin_inset Flex CharStyle:Code
9009 \begin_layout Plain Layout
9015 , but this preamble snippet occurs independently from the babel package,
9016 and only for the document language.
9018 \begin_inset Quotes eld
9022 \begin_inset Flex CharStyle:Code
9025 \begin_layout Plain Layout
9032 \begin_inset Quotes erd
9039 \begin_layout Standard
9040 If the style defines text that appears in the typeset document, it may use
9042 \begin_inset Flex CharStyle:Code
9045 \begin_layout Plain Layout
9052 \begin_inset Flex CharStyle:Code
9055 \begin_layout Plain Layout
9061 to support non-english and even multilanguage documents correctly.
9062 The following excerpt (from the
9063 \begin_inset Flex CharStyle:Code
9066 \begin_layout Plain Layout
9072 file) shows how this works:
9075 \begin_layout LyX-Code
9079 \begin_layout LyX-Code
9082 theoremstyle{remark}
9085 \begin_layout LyX-Code
9088 newtheorem{claim}[thm]{
9095 \begin_layout LyX-Code
9099 \begin_layout LyX-Code
9103 \begin_layout LyX-Code
9108 claimname}{_(Claim)}
9111 \begin_layout LyX-Code
9115 \begin_layout LyX-Code
9119 \begin_layout LyX-Code
9123 \begin_layout LyX-Code
9132 claimname}{_(Claim)}}
9135 \begin_layout LyX-Code
9139 \begin_layout Standard
9140 The key to correct translation of the user visible text is the definition
9142 \begin_inset Flex CharStyle:Code
9145 \begin_layout Plain Layout
9153 in the language preamble.
9154 This command holds the name of the theorem that will appear in the output.
9156 \begin_inset Flex CharStyle:Code
9159 \begin_layout Plain Layout
9165 then uses the commands offered by the babel package to redefine
9166 \begin_inset Flex CharStyle:Code
9169 \begin_layout Plain Layout
9177 for each used language in multilanguage documents.
9181 \begin_layout Description
9182 \begin_inset Flex CharStyle:Code
9185 \begin_layout Plain Layout
9191 [[FIXME]] (Used only with XML-type formats.)
9194 \begin_layout Description
9195 \begin_inset Flex CharStyle:Code
9198 \begin_layout Plain Layout
9205 \begin_inset Flex CharStyle:Code
9208 \begin_layout Plain Layout
9214 If 1, marks the layout as being part of a title block (see also the
9215 \begin_inset Flex CharStyle:Code
9218 \begin_layout Plain Layout
9225 \begin_inset Flex CharStyle:Code
9228 \begin_layout Plain Layout
9237 \begin_layout Description
9238 \begin_inset Flex CharStyle:Code
9241 \begin_layout Plain Layout
9248 \begin_inset Flex CharStyle:Code
9251 \begin_layout Plain Layout
9257 ] This provides extra space between paragraphs that have the same layout.
9258 If you put other layouts into an environment, each is separated with the
9260 \begin_inset Flex CharStyle:Code
9263 \begin_layout Plain Layout
9270 But the whole items of the environment are additionally separated with
9272 \begin_inset Flex CharStyle:Code
9275 \begin_layout Plain Layout
9287 \begin_layout Description
9288 \begin_inset Flex CharStyle:Code
9291 \begin_layout Plain Layout
9297 [[FIXME]] (Used only with XML-type formats.)
9300 \begin_layout Description
9301 \begin_inset Flex CharStyle:Code
9304 \begin_layout Plain Layout
9311 \begin_inset CommandInset label
9313 name "des:KeepEmpty"
9320 \begin_inset Flex CharStyle:Code
9323 \begin_layout Plain Layout
9334 \begin_inset Flex CharStyle:Code
9337 \begin_layout Plain Layout
9343 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9344 lead to empty LaTeX output.
9345 There are some cases where this could be desirable however: in a letter
9346 template, the required fields can be provided as empty fields, so that
9347 people do not forget them; in some special classes, a layout can be used
9348 as some kind of break, which does not contain actual text.
9351 \begin_layout Description
9352 \begin_inset Flex CharStyle:Code
9355 \begin_layout Plain Layout
9361 [float=0] The vertical space between the label and the text body.
9362 Only used for labels that are above the text body (
9363 \begin_inset Flex CharStyle:Code
9366 \begin_layout Plain Layout
9373 \begin_inset Flex CharStyle:Code
9376 \begin_layout Plain Layout
9377 Centered_Top_Environment
9385 \begin_layout Description
9386 \begin_inset Flex CharStyle:Code
9389 \begin_layout Plain Layout
9396 \begin_inset Flex CharStyle:Code
9399 \begin_layout Plain Layout
9406 \begin_inset Newline newline
9409 The name of the counter for automatic numbering (see Section
9410 \begin_inset CommandInset ref
9412 reference "sec:counter"
9417 This must be given if
9418 \begin_inset Flex CharStyle:Code
9421 \begin_layout Plain Layout
9428 \begin_inset Flex CharStyle:Code
9431 \begin_layout Plain Layout
9440 \begin_layout Description
9441 \begin_inset Flex CharStyle:Code
9444 \begin_layout Plain Layout
9450 The font used for the label.
9452 \begin_inset space ~
9456 \begin_inset CommandInset ref
9458 reference "sec:fonts"
9465 \begin_layout Description
9466 \begin_inset Flex CharStyle:Code
9469 \begin_layout Plain Layout
9475 Text that indicates how far a label should be indented.
9478 \begin_layout Description
9479 \begin_inset Flex CharStyle:Code
9482 \begin_layout Plain Layout
9489 \begin_inset Flex CharStyle:Code
9492 \begin_layout Plain Layout
9498 ] The horizontal space between the label and the text body.
9499 Only used for labels that are not above the text body.
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
9522 ] The string used for a label with a
9523 \begin_inset Flex CharStyle:Code
9526 \begin_layout Plain Layout
9534 \begin_inset Flex CharStyle:Code
9537 \begin_layout Plain Layout
9543 is set, this string can be contain the special formatting commands described
9545 \begin_inset CommandInset ref
9547 reference "sec:counter"
9555 \begin_layout Plain Layout
9556 For the sake of backwards compatibility, the string
9557 \begin_inset Flex CharStyle:Code
9560 \begin_layout Plain Layout
9570 will be replaced by the expanded
9571 \begin_inset Flex CharStyle:Code
9574 \begin_layout Plain Layout
9581 \begin_inset Flex CharStyle:Code
9584 \begin_layout Plain Layout
9593 This feature is now obsolete and should be replaced by the mechanisms of
9595 \begin_inset CommandInset ref
9597 reference "sec:counter"
9609 \begin_layout Description
9610 \begin_inset Flex CharStyle:Code
9613 \begin_layout Plain Layout
9620 \begin_inset Flex CharStyle:Code
9623 \begin_layout Plain Layout
9629 ] This is used inside the appendix instead of
9630 \begin_inset Flex CharStyle:Code
9633 \begin_layout Plain Layout
9641 \begin_inset Flex CharStyle:Code
9644 \begin_layout Plain Layout
9651 \begin_inset Flex CharStyle:Code
9654 \begin_layout Plain Layout
9663 \begin_layout Description
9664 \begin_inset Flex CharStyle:Code
9667 \begin_layout Plain Layout
9673 [FIXME] (Used only with XML-type formats.)
9676 \begin_layout Description
9677 \begin_inset Flex CharStyle:Code
9680 \begin_layout Plain Layout
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9695 , Manual, Static, Top_Environment,
9696 \begin_inset Newline newline
9699 Centered_Top_Environment, Sensitive, Counter
9705 \begin_inset Newline newline
9709 \begin_inset Flex CharStyle:Code
9712 \begin_layout Plain Layout
9718 means the label is the very first word (up to the first real blank).
9722 \begin_layout Plain Layout
9723 Use protected spaces if you want more than one word as the label.
9729 \begin_inset Flex CharStyle:Code
9732 \begin_layout Plain Layout
9738 means it is defined in the layout (see
9739 \begin_inset Flex CharStyle:Code
9742 \begin_layout Plain Layout
9750 \begin_inset Flex CharStyle:Code
9753 \begin_layout Plain Layout
9760 \begin_inset Flex CharStyle:Code
9763 \begin_layout Plain Layout
9764 Centered_Top_Environment
9769 are special cases of
9770 \begin_inset Flex CharStyle:Code
9773 \begin_layout Plain Layout
9780 The label will be printed above the paragraph, but only at the top of an
9781 environment or the top of a chain of paragraphs with this layout.
9782 Usage is for example the
9783 \begin_inset Flex CharStyle:MenuItem
9786 \begin_layout Plain Layout
9793 \begin_inset Flex CharStyle:MenuItem
9796 \begin_layout Plain Layout
9803 This is also the case for
9804 \begin_inset Flex CharStyle:Code
9807 \begin_layout Plain Layout
9813 labels with latex type
9814 \begin_inset Flex CharStyle:Code
9817 \begin_layout Plain Layout
9823 , in order to make layouts for theorems work correctly.
9825 \begin_inset Flex CharStyle:Code
9828 \begin_layout Plain Layout
9834 is a special case for the caption-labels
9835 \begin_inset Quotes eld
9839 \begin_inset Quotes erd
9843 \begin_inset Quotes eld
9847 \begin_inset Quotes erd
9852 \begin_inset Flex CharStyle:Code
9855 \begin_layout Plain Layout
9861 means the (hardcoded) label string depends on the kind of float.
9863 \begin_inset Flex CharStyle:Code
9866 \begin_layout Plain Layout
9872 label type defines automatically numbered labels.
9874 \begin_inset CommandInset ref
9876 reference "sec:counter"
9883 \begin_layout Description
9884 \begin_inset Flex CharStyle:Code
9887 \begin_layout Plain Layout
9893 The name of the corresponding LaTeX stuff.
9894 Either the environment or command name.
9897 \begin_layout Description
9898 \begin_inset Flex CharStyle:Code
9901 \begin_layout Plain Layout
9907 An optional parameter for the corresponding
9908 \begin_inset Flex CharStyle:Code
9911 \begin_layout Plain Layout
9918 This parameter cannot be changed from within LyX.
9921 \begin_layout Description
9922 \begin_inset Flex CharStyle:Code
9925 \begin_layout Plain Layout
9932 \begin_inset CommandInset label
9934 name "des:LatexType"
9939 \begin_inset Flex CharStyle:Code
9942 \begin_layout Plain Layout
9947 , Command, Environment, Item_Environment,
9953 \begin_inset Flex CharStyle:Code
9956 \begin_layout Plain Layout
9962 ] How the layout should be translated into LaTeX.
9964 \begin_inset Flex CharStyle:Code
9967 \begin_layout Plain Layout
9973 means nothing special.
9975 \begin_inset Flex CharStyle:Code
9978 \begin_layout Plain Layout
9985 \begin_inset Flex CharStyle:Code
9988 \begin_layout Plain Layout
9995 {\SpecialChar \ldots{}
10002 \begin_inset Flex CharStyle:Code
10005 \begin_layout Plain Layout
10012 \begin_inset Flex CharStyle:Code
10015 \begin_layout Plain Layout
10022 }\SpecialChar \ldots{}
10036 \begin_inset Flex CharStyle:Code
10039 \begin_layout Plain Layout
10046 \begin_inset Flex CharStyle:Code
10049 \begin_layout Plain Layout
10056 \begin_inset Flex CharStyle:Code
10059 \begin_layout Plain Layout
10067 is generated for each paragraph of this environment.
10069 \begin_inset Flex CharStyle:Code
10072 \begin_layout Plain Layout
10079 \begin_inset Flex CharStyle:Code
10082 \begin_layout Plain Layout
10089 \begin_inset Flex CharStyle:Code
10092 \begin_layout Plain Layout
10098 is passed as an argument to the environment.
10100 \begin_inset Flex CharStyle:Code
10103 \begin_layout Plain Layout
10109 can be defined in the
10110 \begin_inset Flex CharStyle:MenuItem
10113 \begin_layout Plain Layout
10118 ayout\SpecialChar \menuseparator
10130 \begin_inset Flex CharStyle:Code
10133 \begin_layout Plain Layout
10141 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10142 Visit the SGML class files for specific examples.
10145 \begin_layout Standard
10146 Putting the last few things together, the LaTeX output will be either:
10149 \begin_layout LyX-Code
10152 latexname[latexparam]{\SpecialChar \ldots{}
10156 \begin_layout Standard
10160 \begin_layout LyX-Code
10163 begin{latexname}[latexparam] \SpecialChar \ldots{}
10169 \begin_layout Standard
10170 depending upon the LaTeX type.
10173 \begin_layout Description
10174 \begin_inset Flex CharStyle:Code
10177 \begin_layout Plain Layout
10184 \begin_inset Flex CharStyle:Code
10187 \begin_layout Plain Layout
10193 ] If you put layouts into environments, the leftmargins are not simply added,
10194 but added with a factor
10195 \begin_inset Formula $\frac{4}{depth+4}$
10199 Note that this parameter is also used when the margin is defined as
10200 \begin_inset Flex CharStyle:Code
10203 \begin_layout Plain Layout
10210 \begin_inset Flex CharStyle:Code
10213 \begin_layout Plain Layout
10220 Then it is added to the manual or dynamic margin.
10222 \begin_inset Newline newline
10225 The argument is passed as a string.
10227 \begin_inset Quotes eld
10231 \begin_inset Flex CharStyle:Code
10234 \begin_layout Plain Layout
10241 \begin_inset Quotes erd
10244 means that the paragraph is indented with the width of
10245 \begin_inset Quotes eld
10249 \begin_inset Flex CharStyle:Code
10252 \begin_layout Plain Layout
10259 \begin_inset Quotes erd
10262 in the normal font.
10263 You can get a negative width by prefixing the string with
10264 \begin_inset Quotes eld
10268 \begin_inset Flex CharStyle:Code
10271 \begin_layout Plain Layout
10278 \begin_inset Quotes erd
10282 This way was chosen so that the look is the same with each used screen
10287 \begin_layout Description
10288 \begin_inset Flex CharStyle:Code
10291 \begin_layout Plain Layout
10298 \begin_inset Flex CharStyle:Code
10301 \begin_layout Plain Layout
10306 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10312 \begin_inset Newline newline
10315 The kind of margin that the layout has on the left side.
10317 \begin_inset Flex CharStyle:Code
10320 \begin_layout Plain Layout
10326 just means a fixed margin.
10328 \begin_inset Flex CharStyle:Code
10331 \begin_layout Plain Layout
10337 means that the left margin depends on the string entered in the
10338 \begin_inset Flex CharStyle:MenuItem
10341 \begin_layout Plain Layout
10342 Edit\SpecialChar \menuseparator
10344 \begin_inset space ~
10353 This is used to typeset nice lists without tabulators.
10355 \begin_inset Flex CharStyle:Code
10358 \begin_layout Plain Layout
10364 means that the margin depends on the size of the label.
10365 This is used for automatic enumerated headlines.
10366 It is obvious that the headline
10367 \begin_inset Quotes eld
10370 5.4.3.2.1 Very long headline
10371 \begin_inset Quotes erd
10374 must have a wider left margin (as wide as
10375 \begin_inset Quotes eld
10379 \begin_inset Quotes erd
10382 plus the space) than
10383 \begin_inset Quotes eld
10386 3.2 Very long headline
10387 \begin_inset Quotes erd
10391 \begin_inset Quotes eld
10395 \begin_inset Quotes erd
10398 are not able to do this.
10400 \begin_inset Flex CharStyle:Code
10403 \begin_layout Plain Layout
10409 is similar, but only the very first row of the paragraph is dynamic, while
10410 the others are static; this is used, for example, for descriptions.
10412 \begin_inset Flex CharStyle:Code
10415 \begin_layout Plain Layout
10421 means the margin is chosen in a way that the longest row of this paragraph
10422 fits to the right margin.
10423 This is used to typeset an address on the right edge of the page.
10426 \begin_layout Description
10427 \begin_inset Flex CharStyle:Code
10430 \begin_layout Plain Layout
10437 \begin_inset Flex CharStyle:Code
10440 \begin_layout Plain Layout
10449 \begin_inset Flex CharStyle:Code
10452 \begin_layout Plain Layout
10458 ] Whether fragile commands in this layout should be
10459 \begin_inset Flex CharStyle:Code
10462 \begin_layout Plain Layout
10475 whether this command should itself be protected.)
10478 \begin_layout Description
10479 \begin_inset Flex CharStyle:Code
10482 \begin_layout Plain Layout
10489 \begin_inset Flex CharStyle:Code
10492 \begin_layout Plain Layout
10499 \begin_inset Flex CharStyle:Code
10502 \begin_layout Plain Layout
10510 ] Whether newlines are translated into LaTeX newlines (
10511 \begin_inset Flex CharStyle:Code
10514 \begin_layout Plain Layout
10525 The translation can be switched off to allow more comfortable LaTeX editing
10529 \begin_layout Description
10530 \begin_inset Flex CharStyle:Code
10533 \begin_layout Plain Layout
10540 \begin_inset Flex CharStyle:Code
10543 \begin_layout Plain Layout
10550 \begin_inset Flex CharStyle:Code
10553 \begin_layout Plain Layout
10561 ] Whether the following Paragraph is allowed to indent its very first row.
10563 \begin_inset Flex CharStyle:Code
10566 \begin_layout Plain Layout
10572 means that it is not allowed to do so;
10573 \begin_inset Flex CharStyle:Code
10576 \begin_layout Plain Layout
10582 means it could do so if it wants to.
10585 \begin_layout Description
10586 \begin_inset Flex CharStyle:Code
10589 \begin_layout Plain Layout
10595 Name of a layout that has replaced this layout.
10596 This is used to rename a layout, while keeping backward compatibility.
10599 \begin_layout Description
10600 \begin_inset Flex CharStyle:Code
10603 \begin_layout Plain Layout
10610 \begin_inset Flex CharStyle:Code
10613 \begin_layout Plain Layout
10619 ] The number of optional arguments that can be used with this layout.
10620 This is useful for things like section headings, and only makes sense with
10624 \begin_layout Description
10625 \begin_inset Flex CharStyle:Code
10628 \begin_layout Plain Layout
10635 \begin_inset Flex CharStyle:Code
10638 \begin_layout Plain Layout
10644 ] The indent of the very first line of a paragraph.
10646 \begin_inset Flex CharStyle:Code
10649 \begin_layout Plain Layout
10655 will be fixed for a certain layout.
10656 The exception is Standard layout, since the indentation of a Standard layout
10657 paragraph can be prohibited with
10658 \begin_inset Flex CharStyle:Code
10661 \begin_layout Plain Layout
10668 Also, Standard layout paragraphs inside environments use the
10669 \begin_inset Flex CharStyle:Code
10672 \begin_layout Plain Layout
10678 of the environment, not their native one.
10679 For example, Standard paragraphs inside an enumeration are not indented.
10682 \begin_layout Description
10683 \begin_inset Flex CharStyle:Code
10686 \begin_layout Plain Layout
10693 \begin_inset Flex CharStyle:Code
10696 \begin_layout Plain Layout
10702 ] The vertical space between two paragraphs of this layout.
10705 \begin_layout Description
10706 \begin_inset Flex CharStyle:Code
10709 \begin_layout Plain Layout
10716 \begin_inset Flex CharStyle:Code
10719 \begin_layout Plain Layout
10725 ] LyX allows the user to choose either
10726 \begin_inset Quotes eld
10730 \begin_inset Quotes erd
10734 \begin_inset Quotes eld
10738 \begin_inset Quotes erd
10741 to typeset a document.
10743 \begin_inset Quotes eld
10747 \begin_inset Quotes erd
10750 is chosen, this value is completely ignored.
10752 \begin_inset Quotes eld
10756 \begin_inset Quotes erd
10759 is chosen, the parindent of a LaTeXtype
10760 \begin_inset Quotes eld
10764 \begin_inset Quotes erd
10767 layout is ignored and all paragraphs are separated by this parskip argument.
10768 The vertical space is calculated with
10769 \begin_inset Flex CharStyle:Code
10772 \begin_layout Plain Layout
10774 \begin_inset space ~
10783 \begin_inset Flex CharStyle:Code
10786 \begin_layout Plain Layout
10792 is the height of a row with the normal font.
10793 This way, the look stays the same with different screen fonts.
10796 \begin_layout Description
10797 \begin_inset Flex CharStyle:Code
10800 \begin_layout Plain Layout
10807 \begin_inset CommandInset label
10809 name "des:PathThru"
10816 \begin_inset Flex CharStyle:Code
10819 \begin_layout Plain Layout
10830 \begin_inset Flex CharStyle:Code
10833 \begin_layout Plain Layout
10839 ] Whether the contents of this paragraph should be output in raw form, meaning
10840 without special translations that LaTeX would require.
10843 \begin_layout Description
10844 \begin_inset Flex CharStyle:Code
10847 \begin_layout Plain Layout
10854 \begin_inset CommandInset label
10856 name "des:Preamble"
10860 Information to be included in the LaTeX preamble when this style is used.
10861 Used to define macros, load packages, etc., required by this particular
10864 \begin_inset Quotes eld
10868 \begin_inset Flex CharStyle:Code
10871 \begin_layout Plain Layout
10878 \begin_inset Quotes erd
10884 \begin_layout Description
10885 \begin_inset Flex CharStyle:Code
10888 \begin_layout Plain Layout
10895 \begin_inset Flex CharStyle:Code
10898 \begin_layout Plain Layout
10905 \begin_inset CommandInset label
10907 name "des:Requires"
10911 Whether the layout requires the feature
10912 \begin_inset Flex CharStyle:Code
10915 \begin_layout Plain Layout
10922 See the description of
10923 \begin_inset Flex CharStyle:Code
10926 \begin_layout Plain Layout
10933 \begin_inset CommandInset ref
10934 LatexCommand pageref
10935 reference "des:FreeSpacing"
10939 ) for information on `features'.
10943 \begin_layout Description
10944 \begin_inset Flex CharStyle:Code
10947 \begin_layout Plain Layout
10954 \begin_inset Flex CharStyle:Code
10957 \begin_layout Plain Layout
10964 \begin_inset Flex CharStyle:Code
10967 \begin_layout Plain Layout
10976 \begin_layout Description
10977 \begin_inset Flex CharStyle:Code
10980 \begin_layout Plain Layout
10987 \begin_inset Flex CharStyle:Code
10990 \begin_layout Plain Layout
10995 , onehalf, double, other
11004 ] This defines what the default spacing should be in the layout.
11006 \begin_inset Flex CharStyle:Code
11009 \begin_layout Plain Layout
11016 \begin_inset Flex CharStyle:Code
11019 \begin_layout Plain Layout
11026 \begin_inset Flex CharStyle:Code
11029 \begin_layout Plain Layout
11035 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11036 If you specify the argument
11037 \begin_inset Flex CharStyle:Code
11040 \begin_layout Plain Layout
11046 , then you should also provide a numerical argument which will be the actual
11048 Note that, contrary to other parameters,
11049 \begin_inset Flex CharStyle:Code
11052 \begin_layout Plain Layout
11058 implies the generation of specific LaTeX code, using the package
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
11083 The font used for the text body .
11085 \begin_inset CommandInset ref
11087 reference "sec:fonts"
11094 \begin_layout Description
11095 \begin_inset Flex CharStyle:Code
11098 \begin_layout Plain Layout
11106 The level of the style in the table of contents.
11107 This is used for automatic numbering of section headings.
11110 \begin_layout Description
11111 \begin_inset Flex CharStyle:Code
11114 \begin_layout Plain Layout
11121 \begin_inset Flex CharStyle:Code
11124 \begin_layout Plain Layout
11130 ] The vertical space with which the very first of a chain of paragraphs
11131 with this layout is separated from the previous paragraph.
11132 If the previous paragraph has another layout, the separations are not simply
11133 added, but the maximum is taken.
11136 \begin_layout Subsection
11140 \begin_layout Standard
11141 \begin_inset CommandInset label
11147 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11148 define the floats (
11149 \begin_inset Flex CharStyle:MenuItem
11152 \begin_layout Plain Layout
11159 \begin_inset Flex CharStyle:MenuItem
11162 \begin_layout Plain Layout
11168 , \SpecialChar \ldots{}
11169 ) in the text class itself.
11170 Standard floats are included in the file
11171 \begin_inset Flex CharStyle:Code
11174 \begin_layout Plain Layout
11180 , so you may have to do no more than add
11183 \begin_layout LyX-Code
11184 Input stdfloats.inc
11187 \begin_layout Standard
11188 to your layout file.
11189 If you want to implement a text class that proposes some other float types
11190 (like the AGU class bundled with LyX), the information below will hopefully
11194 \begin_layout Description
11195 \begin_inset Flex CharStyle:Code
11198 \begin_layout Plain Layout
11205 \begin_inset Flex CharStyle:Code
11208 \begin_layout Plain Layout
11215 \begin_inset Quotes erd
11219 \begin_inset Quotes erd
11222 ] The file name extension of an auxiliary file for the list of figures (or
11224 LaTeX writes the captions to this file.
11227 \begin_layout Description
11228 \begin_inset Flex CharStyle:Code
11231 \begin_layout Plain Layout
11238 \begin_inset Flex CharStyle:Code
11241 \begin_layout Plain Layout
11248 \begin_inset Quotes erd
11252 \begin_inset Quotes erd
11255 ] The string that will be used in the menus and also for the caption.
11258 \begin_layout Description
11259 \begin_inset Flex CharStyle:Code
11262 \begin_layout Plain Layout
11269 \begin_inset Flex CharStyle:Code
11272 \begin_layout Plain Layout
11281 \begin_inset Flex CharStyle:Code
11284 \begin_layout Plain Layout
11291 \begin_inset Flex CharStyle:Code
11294 \begin_layout Plain Layout
11300 if the float is already defined by the LaTeX document class.
11302 \begin_inset Flex CharStyle:Code
11305 \begin_layout Plain Layout
11311 , the float will be defined using the LaTeX package
11312 \begin_inset Flex CharStyle:Code
11315 \begin_layout Plain Layout
11324 \begin_layout Description
11325 \begin_inset Flex CharStyle:Code
11328 \begin_layout Plain Layout
11335 \begin_inset Flex CharStyle:Code
11338 \begin_layout Plain Layout
11345 \begin_inset Quotes erd
11349 \begin_inset Quotes erd
11352 ] The heading used for the list of floats.
11355 \begin_layout Description
11356 \begin_inset Flex CharStyle:Code
11359 \begin_layout Plain Layout
11366 \begin_inset Flex CharStyle:Code
11369 \begin_layout Plain Layout
11376 \begin_inset Quotes erd
11380 \begin_inset Quotes erd
11383 ] This (optional) argument determines whether floats of this class will
11384 be numbered within some sectional unit of the document.
11385 For example, if within is equal to
11386 \begin_inset Flex CharStyle:Code
11389 \begin_layout Plain Layout
11395 , the floats will be numbered within chapters.
11399 \begin_layout Description
11400 \begin_inset Flex CharStyle:Code
11403 \begin_layout Plain Layout
11410 \begin_inset Flex CharStyle:Code
11413 \begin_layout Plain Layout
11420 \begin_inset Quotes erd
11424 \begin_inset Quotes erd
11427 ] The default placement for the given class of floats.
11428 The string should be as in standard LaTeX:
11429 \begin_inset Flex CharStyle:Code
11432 \begin_layout Plain Layout
11439 \begin_inset Flex CharStyle:Code
11442 \begin_layout Plain Layout
11449 \begin_inset Flex CharStyle:Code
11452 \begin_layout Plain Layout
11459 \begin_inset Flex CharStyle:Code
11462 \begin_layout Plain Layout
11468 for top, bottom, page, and here, respectively.
11472 \begin_layout Plain Layout
11473 Note that the order of these letters in the string is irrelevant, like in
11479 On top of that there is a new type,
11480 \begin_inset Flex CharStyle:Code
11483 \begin_layout Plain Layout
11489 , which does not really correspond to a float, since it means: put it
11490 \begin_inset Quotes eld
11494 \begin_inset Quotes erd
11498 Note however that the
11499 \begin_inset Flex CharStyle:Code
11502 \begin_layout Plain Layout
11508 specifier is special and, because of implementation details, cannot be
11509 used in non-built in float types.
11510 If you do not understand what this means, just use
11511 \begin_inset Quotes eld
11515 \begin_inset Flex CharStyle:Code
11518 \begin_layout Plain Layout
11525 \begin_inset Quotes erd
11531 \begin_layout Description
11532 \begin_inset Flex CharStyle:Code
11535 \begin_layout Plain Layout
11542 \begin_inset Flex CharStyle:Code
11545 \begin_layout Plain Layout
11552 \begin_inset Quotes erd
11556 \begin_inset Quotes erd
11559 ] The style used when defining the float using
11560 \begin_inset Flex CharStyle:Code
11563 \begin_layout Plain Layout
11574 \begin_layout Description
11575 \begin_inset Flex CharStyle:Code
11578 \begin_layout Plain Layout
11585 \begin_inset Flex CharStyle:Code
11588 \begin_layout Plain Layout
11595 \begin_inset Quotes erd
11599 \begin_inset Quotes erd
11603 \begin_inset Quotes eld
11607 \begin_inset Quotes erd
11610 of the new class of floats, like program or algorithm.
11611 After the appropriate
11612 \begin_inset Flex CharStyle:Code
11615 \begin_layout Plain Layout
11624 \begin_inset Flex CharStyle:Code
11627 \begin_layout Plain Layout
11636 \begin_inset Flex CharStyle:Code
11639 \begin_layout Plain Layout
11650 \begin_layout Standard
11651 Note that defining a float with type
11652 \begin_inset Flex CharStyle:Code
11655 \begin_layout Plain Layout
11663 automatically defines the corresponding counter with name
11664 \begin_inset Flex CharStyle:Code
11667 \begin_layout Plain Layout
11678 \begin_layout Subsection
11679 Flex insets and InsetLayout
11682 \begin_layout Standard
11683 \begin_inset CommandInset label
11685 name "sec:charstyle"
11689 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11690 these are called Flex insets.
11694 \begin_layout Standard
11695 Flex insets come in three different kinds:
11698 \begin_layout Itemize
11700 \begin_inset Flex CharStyle:Code
11703 \begin_layout Plain Layout
11709 ): These define semantic markup corresponding to such LaTeX commands as
11711 \begin_inset Flex CharStyle:Code
11714 \begin_layout Plain Layout
11723 \begin_inset Flex CharStyle:Code
11726 \begin_layout Plain Layout
11737 \begin_layout Itemize
11739 \begin_inset Flex CharStyle:Code
11742 \begin_layout Plain Layout
11748 ): These can be used to define custom collapsible insets, similar to TeX
11749 code, footnote, and the like.
11750 An obvious example is an endnote inset, which is defined in the
11751 \begin_inset Flex CharStyle:Code
11754 \begin_layout Plain Layout
11763 \begin_layout Itemize
11765 \begin_inset Flex CharStyle:Code
11768 \begin_layout Plain Layout
11774 ): For use with DocBook classes.
11777 \begin_layout Standard
11778 Flex insets are defined using the
11779 \begin_inset Flex CharStyle:Code
11782 \begin_layout Plain Layout
11788 tag, which shall be explained in a moment.
11791 \begin_layout Standard
11793 \begin_inset Flex CharStyle:Code
11796 \begin_layout Plain Layout
11802 tag also serves another function: It can be used to customize the general
11803 layout of many different types of insets.
11805 \begin_inset Flex CharStyle:Code
11808 \begin_layout Plain Layout
11814 can be used to customize the layout parameters for footnotes, marginal
11815 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11816 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11817 define Flex insets.
11820 \begin_layout Standard
11822 \begin_inset Flex CharStyle:Code
11825 \begin_layout Plain Layout
11831 definition must begin with a line of the form:
11834 \begin_layout LyX-Code
11838 \begin_layout Standard
11840 \begin_inset Flex CharStyle:Code
11843 \begin_layout Plain Layout
11849 indicates the inset whose layout is being defined, and here there are two
11853 \begin_layout Enumerate
11854 The layout for a pre-existing inset is being modified.
11855 In this case, can be
11856 \begin_inset Flex CharStyle:Code
11859 \begin_layout Plain Layout
11865 any one of the following:
11866 \begin_inset Flex CharStyle:Code
11869 \begin_layout Plain Layout
11876 \begin_inset Flex CharStyle:Code
11879 \begin_layout Plain Layout
11886 \begin_inset Flex CharStyle:Code
11889 \begin_layout Plain Layout
11896 \begin_inset Flex CharStyle:Code
11899 \begin_layout Plain Layout
11906 \begin_inset Flex CharStyle:Code
11909 \begin_layout Plain Layout
11916 \begin_inset Flex CharStyle:Code
11919 \begin_layout Plain Layout
11926 \begin_inset Flex CharStyle:Code
11929 \begin_layout Plain Layout
11936 \begin_inset Flex CharStyle:Code
11939 \begin_layout Plain Layout
11946 \begin_inset Flex CharStyle:Code
11949 \begin_layout Plain Layout
11956 \begin_inset Flex CharStyle:Code
11959 \begin_layout Plain Layout
11966 \begin_inset Flex CharStyle:Code
11969 \begin_layout Plain Layout
11976 \begin_inset Flex CharStyle:Code
11979 \begin_layout Plain Layout
11986 \begin_inset Flex CharStyle:Code
11989 \begin_layout Plain Layout
11996 \begin_inset Flex CharStyle:Code
11999 \begin_layout Plain Layout
12006 \begin_inset Flex CharStyle:Code
12009 \begin_layout Plain Layout
12016 \begin_inset Flex CharStyle:Code
12019 \begin_layout Plain Layout
12026 \begin_inset Flex CharStyle:Code
12029 \begin_layout Plain Layout
12036 \begin_inset Flex CharStyle:Code
12039 \begin_layout Plain Layout
12046 \begin_inset Flex CharStyle:Code
12049 \begin_layout Plain Layout
12056 \begin_inset Flex CharStyle:Code
12059 \begin_layout Plain Layout
12069 \begin_layout Enumerate
12070 The layout for a Flex inset is being defined.
12072 \begin_inset Flex CharStyle:Code
12075 \begin_layout Plain Layout
12081 can be any valid identifier not used by a pre-existing inset.
12082 Note that the definition of a flex inset must
12087 \begin_inset Flex CharStyle:Code
12090 \begin_layout Plain Layout
12099 \begin_layout Standard
12101 \begin_inset Flex CharStyle:Code
12104 \begin_layout Plain Layout
12110 definition can contain the following entries:
12113 \begin_layout Description
12114 \begin_inset Flex CharStyle:Code
12117 \begin_layout Plain Layout
12123 The color for the inset's background.
12124 The valid colors are defined in
12125 \begin_inset Flex CharStyle:Code
12128 \begin_layout Plain Layout
12137 \begin_layout Description
12138 \begin_inset Flex CharStyle:Code
12141 \begin_layout Plain Layout
12147 As with paragraph styles (see page
12148 \begin_inset CommandInset ref
12150 reference "des:CopyStyle"
12157 \begin_layout Description
12158 \begin_inset Flex CharStyle:Code
12161 \begin_layout Plain Layout
12168 \begin_inset Flex CharStyle:Code
12171 \begin_layout Plain Layout
12180 \begin_inset Flex CharStyle:Code
12183 \begin_layout Plain Layout
12189 ] Indicates whether the user may employ the Paragraph Settings dialog to
12190 customize the paragraph.
12193 \begin_layout Description
12194 \begin_inset Flex CharStyle:Code
12197 \begin_layout Plain Layout
12204 \begin_inset Flex CharStyle:Code
12207 \begin_layout Plain Layout
12214 \begin_inset Flex CharStyle:Code
12217 \begin_layout Plain Layout
12224 \begin_inset Flex CharStyle:Code
12227 \begin_layout Plain Layout
12233 , describing the rendering style used for the inset's frame and buttons.
12234 Footnotes generally use
12235 \begin_inset Flex CharStyle:Code
12238 \begin_layout Plain Layout
12244 , ERT insets generally
12245 \begin_inset Flex CharStyle:Code
12248 \begin_layout Plain Layout
12254 , and character styles
12255 \begin_inset Flex CharStyle:Code
12258 \begin_layout Plain Layout
12267 \begin_layout Description
12268 \begin_inset Flex CharStyle:Code
12271 \begin_layout Plain Layout
12277 Required at the end of the InsetLayout declarations.
12280 \begin_layout Description
12281 \begin_inset Flex CharStyle:Code
12284 \begin_layout Plain Layout
12290 The font used for both the text body
12296 \begin_inset space ~
12300 \begin_inset CommandInset ref
12302 reference "sec:fonts"
12307 Note that defining this font automatically defines the
12308 \begin_inset Flex CharStyle:Code
12311 \begin_layout Plain Layout
12317 to the same value, so define this first and define
12318 \begin_inset Flex CharStyle:Code
12321 \begin_layout Plain Layout
12327 later if you want them to be different.
12330 \begin_layout Description
12331 \begin_inset Flex CharStyle:Code
12334 \begin_layout Plain Layout
12341 \begin_inset Quotes eld
12345 \begin_inset Quotes erd
12348 language, leading to Left-to-Right (latin) output, e.
12349 \begin_inset space \thinspace{}
12353 \begin_inset space \space{}
12356 in TeX code or URL.
12360 \begin_layout Description
12361 \begin_inset Flex CharStyle:Code
12364 \begin_layout Plain Layout
12371 \begin_inset Flex CharStyle:Code
12374 \begin_layout Plain Layout
12383 \begin_inset Flex CharStyle:Code
12386 \begin_layout Plain Layout
12392 ] Indicates whether the PlainLayout should be used or, instead, the user
12393 can change the paragraph style used in the inset.
12396 \begin_layout Description
12397 \begin_inset Flex CharStyle:Code
12400 \begin_layout Plain Layout
12406 As with paragraph styles (see page
12407 \begin_inset CommandInset ref
12408 LatexCommand pageref
12409 reference "des:FreeSpacing"
12416 \begin_layout Description
12417 \begin_inset Flex CharStyle:Code
12420 \begin_layout Plain Layout
12427 \begin_inset Flex CharStyle:Code
12430 \begin_layout Plain Layout
12439 \begin_inset Flex CharStyle:Code
12442 \begin_layout Plain Layout
12448 ] Whether to include the contents of this inset in the strings generated
12449 for the `Outline' pane.
12450 One would not, for example, want the content of a footnote in a section
12451 header to be included in the TOC displayed in the outline, but one would
12452 normally want the content of a character style displayed.
12453 Default is false: not to include.
12456 \begin_layout Description
12457 \begin_inset Flex CharStyle:Code
12460 \begin_layout Plain Layout
12466 As with paragraph styles (see page
12467 \begin_inset CommandInset ref
12468 LatexCommand pageref
12469 reference "des:KeepEmpty"
12476 \begin_layout Description
12477 \begin_inset Flex CharStyle:Code
12480 \begin_layout Plain Layout
12486 The font used for the label.
12488 \begin_inset space ~
12492 \begin_inset CommandInset ref
12494 reference "sec:fonts"
12499 Note that this definition can never appear before
12500 \begin_inset Flex CharStyle:Code
12503 \begin_layout Plain Layout
12509 , lest it be ineffective.
12512 \begin_layout Description
12513 \begin_inset Flex CharStyle:Code
12516 \begin_layout Plain Layout
12522 What will be displayed on the button or elsewhere as the inset label.
12523 Some inset types (TeX code and Branch) modify this label on the fly.
12526 \begin_layout Description
12527 \begin_inset Flex CharStyle:Code
12530 \begin_layout Plain Layout
12536 The name of the corresponding LaTeX stuff.
12537 Either the environment or command name.
12540 \begin_layout Description
12541 \begin_inset Flex CharStyle:Code
12544 \begin_layout Plain Layout
12550 The optional parameter for the corresponding
12551 \begin_inset Flex CharStyle:Code
12554 \begin_layout Plain Layout
12560 stuff, including possible bracket pairs like
12561 \begin_inset Flex CharStyle:Code
12564 \begin_layout Plain Layout
12571 This parameter cannot be changed from within LyX.
12574 \begin_layout Description
12575 \begin_inset Flex CharStyle:Code
12578 \begin_layout Plain Layout
12584 As with paragraph styles (see page
12585 \begin_inset CommandInset ref
12586 LatexCommand pageref
12587 reference "des:LatexType"
12594 \begin_layout Description
12595 \begin_inset Flex CharStyle:Code
12598 \begin_layout Plain Layout
12605 \begin_inset Flex CharStyle:Code
12608 \begin_layout Plain Layout
12615 \begin_inset Flex CharStyle:Code
12618 \begin_layout Plain Layout
12625 \begin_inset Flex CharStyle:Code
12628 \begin_layout Plain Layout
12635 \begin_inset Flex CharStyle:Code
12638 \begin_layout Plain Layout
12644 (indicating a dummy definition ending definitions of charstyles, etc).
12645 This entry is required in and is only meaningful for Flex insets.
12646 Among other things, it determines on which menu this inset will appear.
12649 \begin_layout Description
12650 \begin_inset Flex CharStyle:Code
12653 \begin_layout Plain Layout
12660 \begin_inset Flex CharStyle:Code
12663 \begin_layout Plain Layout
12672 \begin_inset Flex CharStyle:Code
12675 \begin_layout Plain Layout
12681 ] Whether multiple paragraphs are permitted in this inset.
12682 This will also set CustomPars to the same value and ForcePlain to the opposite
12684 These can be reset to other values, if they are used
12691 \begin_layout Description
12692 \begin_inset Flex CharStyle:Code
12695 \begin_layout Plain Layout
12702 \begin_inset Flex CharStyle:Code
12705 \begin_layout Plain Layout
12714 \begin_inset Flex CharStyle:Code
12717 \begin_layout Plain Layout
12723 ] Whether fragile commands in this layout should be
12724 \begin_inset Flex CharStyle:Code
12727 \begin_layout Plain Layout
12740 whether the command should itself be protected.)
12743 \begin_layout Description
12744 \begin_inset Flex CharStyle:Code
12747 \begin_layout Plain Layout
12754 \begin_inset Flex CharStyle:Code
12757 \begin_layout Plain Layout
12766 \begin_inset Flex CharStyle:Code
12769 \begin_layout Plain Layout
12775 ] As with paragraph styles (see page
12776 \begin_inset CommandInset ref
12778 reference "des:PathThru"
12785 \begin_layout Description
12786 \begin_inset Flex CharStyle:Code
12789 \begin_layout Plain Layout
12795 As with paragraph styles (see page
12796 \begin_inset CommandInset ref
12797 LatexCommand pageref
12798 reference "des:Preamble"
12805 \begin_layout Description
12806 \begin_inset Flex CharStyle:Code
12809 \begin_layout Plain Layout
12816 \begin_inset Flex CharStyle:Code
12819 \begin_layout Plain Layout
12825 ] As with paragraph styles (see page
12826 \begin_inset CommandInset ref
12827 LatexCommand pageref
12828 reference "des:Requires"
12835 \begin_layout Subsection
12839 \begin_layout Standard
12840 \begin_inset CommandInset label
12846 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12848 \begin_inset Flex CharStyle:MenuItem
12851 \begin_layout Plain Layout
12858 \begin_inset Flex CharStyle:MenuItem
12861 \begin_layout Plain Layout
12867 , \SpecialChar \ldots{}
12868 ) in the text class itself.
12869 The standard counters are defined in the file
12870 \begin_inset Flex CharStyle:Code
12873 \begin_layout Plain Layout
12879 , so you may have to do no more than add
12882 \begin_layout LyX-Code
12883 Input stdcounters.inc
12886 \begin_layout Standard
12887 to your layout file to get them to work.
12888 But if you want to define custom counters, then you can do so.
12889 The counter declaration must begin with:
12892 \begin_layout LyX-Code
12896 \begin_layout Standard
12897 where of course `name' is replaced by the name of the counter.
12898 And it must end with
12899 \begin_inset Quotes eld
12903 \begin_inset Flex CharStyle:Code
12906 \begin_layout Plain Layout
12913 \begin_inset Quotes erd
12917 The following parameters can also be used:
12920 \begin_layout Description
12921 \begin_inset Flex CharStyle:Code
12924 \begin_layout Plain Layout
12925 LabelString [string=""]
12930 when this is defined, this string defines how the counter is displayed.
12931 Setting this value sets
12932 \begin_inset Flex CharStyle:Code
12935 \begin_layout Plain Layout
12936 LabelStringAppendix
12942 The following special constructs can be used in the string:
12946 \begin_layout Itemize
12947 \begin_inset Flex CharStyle:Code
12950 \begin_layout Plain Layout
12958 will be replaced by the expansion of the
12959 \begin_inset Flex CharStyle:Code
12962 \begin_layout Plain Layout
12969 \begin_inset Flex CharStyle:Code
12972 \begin_layout Plain Layout
12973 LabelStringAppendix
12979 \begin_inset Flex CharStyle:Code
12982 \begin_layout Plain Layout
12992 \begin_layout Itemize
12993 counter values can be expressed using LaTeX-like macros
12994 \begin_inset Flex CharStyle:Code
12997 \begin_layout Plain Layout
13014 \begin_inset Flex CharStyle:Code
13017 \begin_layout Plain Layout
13029 \begin_layout Plain Layout
13039 Actually, the situation is a bit more complicated: any
13058 other than those described below will produce arabic numerals.
13059 It would not be surprising to see this change in the future.
13065 \begin_inset Flex CharStyle:Code
13068 \begin_layout Plain Layout
13074 : 1, 2, 3,\SpecialChar \ldots{}
13076 \begin_inset Flex CharStyle:Code
13079 \begin_layout Plain Layout
13085 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13087 \begin_inset Flex CharStyle:Code
13090 \begin_layout Plain Layout
13096 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13098 \begin_inset Flex CharStyle:Code
13101 \begin_layout Plain Layout
13107 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13109 \begin_inset Flex CharStyle:Code
13112 \begin_layout Plain Layout
13118 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13120 \begin_inset Flex CharStyle:Code
13123 \begin_layout Plain Layout
13129 for hebrew numerals.
13133 \begin_layout Standard
13134 If LabelString is not defined, a default value is constructed as follows:
13135 if the counter has a master counter
13136 \begin_inset Flex CharStyle:Code
13139 \begin_layout Plain Layout
13146 \begin_inset Flex CharStyle:Code
13149 \begin_layout Plain Layout
13156 \begin_inset Flex CharStyle:Code
13159 \begin_layout Plain Layout
13169 is used; otherwise the string
13170 \begin_inset Flex CharStyle:Code
13173 \begin_layout Plain Layout
13184 \begin_layout Description
13185 \begin_inset Flex CharStyle:Code
13188 \begin_layout Plain Layout
13189 LabelStringAppendix [string=""]
13195 \begin_inset Flex CharStyle:Code
13198 \begin_layout Plain Layout
13204 , but for use in the Appendix.
13207 \begin_layout Description
13208 \begin_inset Flex CharStyle:Code
13211 \begin_layout Plain Layout
13218 \begin_inset Flex CharStyle:Code
13221 \begin_layout Plain Layout
13228 \begin_inset Quotes erd
13232 \begin_inset Quotes erd
13235 ] If this is set to the name of another counter, the present counter will
13236 be reset every time the other one is increased.
13238 \begin_inset Flex CharStyle:Code
13241 \begin_layout Plain Layout
13248 \begin_inset Flex CharStyle:Code
13251 \begin_layout Plain Layout
13260 \begin_layout Subsection
13264 \begin_layout Standard
13265 \begin_inset CommandInset label
13271 A font description looks like this:
13274 \begin_layout LyX-Code
13284 \begin_layout LyX-Code
13288 \begin_layout LyX-Code
13292 \begin_layout Standard
13293 The following commands are available:
13296 \begin_layout Description
13297 \begin_inset Flex CharStyle:Code
13300 \begin_layout Plain Layout
13307 \begin_inset Flex CharStyle:Code
13310 \begin_layout Plain Layout
13319 \begin_inset Flex CharStyle:Code
13322 \begin_layout Plain Layout
13329 \begin_inset Flex CharStyle:Code
13332 \begin_layout Plain Layout
13339 \begin_inset Flex CharStyle:Code
13342 \begin_layout Plain Layout
13349 \begin_inset Flex CharStyle:Code
13352 \begin_layout Plain Layout
13359 \begin_inset Flex CharStyle:Code
13362 \begin_layout Plain Layout
13369 \begin_inset Flex CharStyle:Code
13372 \begin_layout Plain Layout
13379 \begin_inset Flex CharStyle:Code
13382 \begin_layout Plain Layout
13389 \begin_inset Flex CharStyle:Code
13392 \begin_layout Plain Layout
13401 \begin_layout Description
13402 \begin_inset Flex CharStyle:Code
13405 \begin_layout Plain Layout
13414 \begin_inset Flex CharStyle:Code
13417 \begin_layout Plain Layout
13428 \begin_inset Flex CharStyle:Code
13431 \begin_layout Plain Layout
13438 \begin_inset Flex CharStyle:Code
13441 \begin_layout Plain Layout
13450 \begin_layout Description
13451 \begin_inset Flex CharStyle:Code
13454 \begin_layout Plain Layout
13461 \begin_inset Flex CharStyle:Code
13464 \begin_layout Plain Layout
13470 ] Valid argument are:
13471 \begin_inset Flex CharStyle:Code
13474 \begin_layout Plain Layout
13481 \begin_inset Flex CharStyle:Code
13484 \begin_layout Plain Layout
13491 \begin_inset Flex CharStyle:Code
13494 \begin_layout Plain Layout
13501 \begin_inset Flex CharStyle:Code
13504 \begin_layout Plain Layout
13511 \begin_inset Flex CharStyle:Code
13514 \begin_layout Plain Layout
13521 \begin_inset Flex CharStyle:Code
13524 \begin_layout Plain Layout
13531 Each of these turns on or off the corresponding attribute.
13534 \begin_layout Description
13535 \begin_inset Flex CharStyle:Code
13538 \begin_layout Plain Layout
13547 \begin_inset Flex CharStyle:Code
13550 \begin_layout Plain Layout
13561 \begin_inset Flex CharStyle:Code
13564 \begin_layout Plain Layout
13573 \begin_layout Description
13574 \begin_inset Flex CharStyle:Code
13577 \begin_layout Plain Layout
13586 \begin_inset Flex CharStyle:Code
13589 \begin_layout Plain Layout
13600 \begin_inset Flex CharStyle:Code
13603 \begin_layout Plain Layout
13610 \begin_inset Flex CharStyle:Code
13613 \begin_layout Plain Layout
13620 \begin_inset Flex CharStyle:Code
13623 \begin_layout Plain Layout
13632 \begin_layout Description
13633 \begin_inset Flex CharStyle:Code
13636 \begin_layout Plain Layout
13643 \begin_inset Flex CharStyle:Code
13646 \begin_layout Plain Layout
13653 \begin_inset Flex CharStyle:Code
13656 \begin_layout Plain Layout
13663 \begin_inset Flex CharStyle:Code
13666 \begin_layout Plain Layout
13675 \begin_inset Flex CharStyle:Code
13678 \begin_layout Plain Layout
13685 \begin_inset Flex CharStyle:Code
13688 \begin_layout Plain Layout
13695 \begin_inset Flex CharStyle:Code
13698 \begin_layout Plain Layout
13705 \begin_inset Flex CharStyle:Code
13708 \begin_layout Plain Layout
13715 \begin_inset Flex CharStyle:Code
13718 \begin_layout Plain Layout
13727 \begin_layout Subsection
13728 Upgrading old layout files
13731 \begin_layout Standard
13732 The file format of layout files changes from time to time, so old layout
13733 files need to be converted.
13734 This process has been automated since LyX 1.4.0: If LyX reads an old format
13735 layout file it will call the conversion tool
13736 \begin_inset Flex CharStyle:Code
13739 \begin_layout Plain Layout
13740 LyXDir/scripts/layout2layout.py
13745 and convert it to a temporary file in current format.
13746 The original file is left untouched.
13747 If you want to convert the layout file permanently, just call the converter
13751 \begin_layout LyX-Code
13752 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13755 \begin_layout Standard
13756 (You need to replace
13757 \begin_inset Flex CharStyle:Code
13760 \begin_layout Plain Layout
13766 with the name of your LyX system directory, unless you happen to have defined
13767 such an environment variable.) Then copy
13768 \begin_inset Flex CharStyle:Code
13771 \begin_layout Plain Layout
13778 \begin_inset Flex CharStyle:Code
13781 \begin_layout Plain Layout
13790 \begin_layout Standard
13791 The automatic conversion only handles syntax changes.
13792 It cannot handle the case where the contents of included files was changed,
13793 so these will have to be converted separately.
13796 \begin_layout Section
13798 \begin_inset CommandInset label
13800 name "sec:templates"
13807 \begin_layout Standard
13808 Templates are created just like usual documents.
13809 The only difference is that usual documents contain all possible settings,
13810 including the font scheme and the paper size.
13811 Usually a user doesn't want a template to overwrite his defaults in these
13813 For that reason, the designer of a template should remove the corresponding
13815 \begin_inset Flex CharStyle:Code
13818 \begin_layout Plain Layout
13827 \begin_inset Flex CharStyle:Code
13830 \begin_layout Plain Layout
13838 from the template LyX file.
13839 This can be done with any simple text-editor, for example
13840 \begin_inset Flex CharStyle:Code
13843 \begin_layout Plain Layout
13850 \begin_inset Flex CharStyle:Code
13853 \begin_layout Plain Layout
13863 \begin_layout Standard
13864 Put the edited template files you create in
13865 \begin_inset Flex CharStyle:Code
13868 \begin_layout Plain Layout
13874 , copy the ones you use from the global template directory in
13875 \begin_inset Flex CharStyle:Code
13878 \begin_layout Plain Layout
13884 to the same place, and redefine the template path in the
13885 \begin_inset Flex CharStyle:MenuItem
13888 \begin_layout Plain Layout
13889 Tools\SpecialChar \menuseparator
13890 Preferences\SpecialChar \menuseparator
13899 \begin_layout Standard
13900 Note that there is a template which has a particular meaning:
13901 \begin_inset Flex CharStyle:Code
13904 \begin_layout Plain Layout
13911 This template is loaded every time you create a new document with
13912 \begin_inset Flex CharStyle:MenuItem
13915 \begin_layout Plain Layout
13916 File\SpecialChar \menuseparator
13922 in order to provide useful defaults.
13923 To create this template from inside LyX, all you have to do is to open
13924 a document with the correct settings, and use the
13925 \begin_inset Flex CharStyle:MenuItem
13928 \begin_layout Plain Layout
13929 Save as Document Defaults
13937 \begin_layout Chapter
13938 Including External Material
13941 \begin_layout Standard
13942 \begin_inset Box Shadowbox
13951 height_special "totalheight"
13954 \begin_layout Plain Layout
13955 WARNING: This portion of the documentation has not been updated for some
13957 We certainly hope that it is still accurate, but there are no guarantees.
13965 \begin_layout Standard
13966 The use of material from sources external to LyX is covered in detail in
13972 This part of the manual covers what needs to happen behind the scenes for
13973 new sorts of material to be included.
13976 \begin_layout Section
13980 \begin_layout Standard
13981 The external material feature is based on the concept of a
13986 A template is a specification of how LyX should interface with a certain
13988 As bundled, LyX comes with predefined templates for Xfig figures, various
13989 raster format images, chess diagrams, and LilyPond music notation.
13990 You can check the actual list by using the menu
13991 \begin_inset Flex CharStyle:MenuItem
13994 \begin_layout Plain Layout
13995 Insert\SpecialChar \menuseparator
13996 File\SpecialChar \menuseparator
14003 Furthermore, it is possible to roll your own template to support a specific
14005 Later we'll describe in more detail what is involved, and hopefully you
14006 will submit all the templates you create so we can include them in a later
14010 \begin_layout Standard
14011 Another basic idea of the external material feature is to distinguish between
14012 the original file that serves as a base for final material and the produced
14013 file that is included in your exported or printed document.
14014 For example, consider the case of a figure produced with
14015 \begin_inset Flex CharStyle:Code
14018 \begin_layout Plain Layout
14025 The Xfig application itself works on an original file with the
14026 \begin_inset Flex CharStyle:Code
14029 \begin_layout Plain Layout
14036 Within Xfig, you create and change your figure, and when you are done,
14038 \begin_inset Flex CharStyle:Code
14041 \begin_layout Plain Layout
14048 When you want to include the figure in your document, you invoke
14049 \begin_inset Flex CharStyle:Code
14052 \begin_layout Plain Layout
14058 in order to create a PostScript file that can readily be included in your
14061 \begin_inset Flex CharStyle:Code
14064 \begin_layout Plain Layout
14070 file is the original file, and the PostScript file is the produced file.
14073 \begin_layout Standard
14074 This distinction is important in order to allow updating of the material
14075 while you are in the process of writing the document.
14076 Furthermore, it provides us with the flexibility that is needed to support
14077 multiple export formats.
14078 For instance, in the case of a plain text file, it is not exactly an award-winn
14079 ing idea to include the figure as raw PostScript.
14080 Instead, you'd either prefer to just include a reference to the figure
14081 or try to invoke some graphics to ASCII converter to make the final result
14082 look similar to the real graphics.
14083 The external material management allows you to do this, because it is parametri
14084 zed on the different export formats that LyX supports.
14087 \begin_layout Standard
14088 Besides supporting the production of different products according to the
14089 exported format, it supports tight integration with editing and viewing
14091 In the case of an Xfig figure, you are able to invoke Xfig on the original
14092 file with a single click from within the external material dialog in LyX,
14093 and also preview the produced PostScript file with Ghostview with another
14095 No more fiddling around with the command line and/or file browsers to locate
14096 and manipulate the original or produced files.
14097 In this way, you are finally able to take full advantage of the many different
14098 applications that are relevant to use when you write your documents, and
14099 ultimately be more productive.
14102 \begin_layout Section
14103 The external template configuration file
14106 \begin_layout Standard
14107 It is relatively easy to add custom external template definitions to LyX.
14108 However, be aware that doing this in an careless manner most probably
14112 introduce an easily exploitable security hole.
14113 So before you do this, please read the discussion about security in section
14115 \begin_inset CommandInset ref
14117 reference "sec:Security-discussion"
14124 \begin_layout Standard
14125 Having said that, we encourage you to submit any interesting templates that
14130 \begin_layout Standard
14131 The external templates are defined in the
14132 \begin_inset Flex CharStyle:Code
14135 \begin_layout Plain Layout
14136 LyXDir/lib/external_templates
14142 You can place your own version in
14143 \begin_inset Flex CharStyle:Code
14146 \begin_layout Plain Layout
14147 UserDir/external_templates
14155 \begin_layout Standard
14156 A typical template looks like this:
14159 \begin_layout LyX-Code
14163 \begin_layout LyX-Code
14164 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14167 \begin_layout LyX-Code
14171 \begin_layout LyX-Code
14175 \begin_layout LyX-Code
14179 \begin_layout LyX-Code
14183 \begin_layout LyX-Code
14187 \begin_layout LyX-Code
14188 AutomaticProduction true
14191 \begin_layout LyX-Code
14195 \begin_layout LyX-Code
14199 \begin_layout LyX-Code
14203 \begin_layout LyX-Code
14204 TransformCommand Rotate RotationLatexCommand
14207 \begin_layout LyX-Code
14208 TransformCommand Resize ResizeLatexCommand
14211 \begin_layout LyX-Code
14212 Product "$$RotateFront$$ResizeFront
14215 \begin_layout LyX-Code
14220 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14223 \begin_layout LyX-Code
14224 $$ResizeBack$$RotateBack"
14227 \begin_layout LyX-Code
14231 \begin_layout LyX-Code
14232 UpdateResult "$$AbsPath$$Basename.pstex_t"
14235 \begin_layout LyX-Code
14236 Requirement "graphicx"
14239 \begin_layout LyX-Code
14240 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14243 \begin_layout LyX-Code
14244 ReferencedFile latex "$$AbsPath$$Basename.eps"
14247 \begin_layout LyX-Code
14248 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14251 \begin_layout LyX-Code
14255 \begin_layout LyX-Code
14259 \begin_layout LyX-Code
14260 TransformCommand Rotate RotationLatexCommand
14263 \begin_layout LyX-Code
14264 TransformCommand Resize ResizeLatexCommand
14267 \begin_layout LyX-Code
14268 Product "$$RotateFront$$ResizeFront
14271 \begin_layout LyX-Code
14276 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14279 \begin_layout LyX-Code
14280 $$ResizeBack$$RotateBack"
14283 \begin_layout LyX-Code
14284 UpdateFormat pdftex
14287 \begin_layout LyX-Code
14288 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14291 \begin_layout LyX-Code
14292 Requirement "graphicx"
14295 \begin_layout LyX-Code
14296 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14299 \begin_layout LyX-Code
14300 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14303 \begin_layout LyX-Code
14307 \begin_layout LyX-Code
14311 \begin_layout LyX-Code
14312 Product "$$Contents(
14314 "$$AbsPath$$Basename.asc
14319 \begin_layout LyX-Code
14320 UpdateFormat asciixfig
14323 \begin_layout LyX-Code
14324 UpdateResult "$$AbsPath$$Basename.asc"
14327 \begin_layout LyX-Code
14331 \begin_layout LyX-Code
14335 \begin_layout LyX-Code
14336 Product "<graphic fileref=
14338 "$$AbsOrRelPathMaster$$Basename.eps
14343 \begin_layout LyX-Code
14347 \begin_layout LyX-Code
14351 \begin_layout LyX-Code
14352 UpdateResult "$$AbsPath$$Basename.eps"
14355 \begin_layout LyX-Code
14356 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14359 \begin_layout LyX-Code
14360 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14363 \begin_layout LyX-Code
14367 \begin_layout LyX-Code
14368 Product "[XFig: $$FName]"
14371 \begin_layout LyX-Code
14375 \begin_layout LyX-Code
14379 \begin_layout Standard
14380 As you can see, the template is enclosed in
14381 \begin_inset Flex CharStyle:Code
14384 \begin_layout Plain Layout
14390 \SpecialChar \ldots{}
14392 \begin_inset Flex CharStyle:Code
14395 \begin_layout Plain Layout
14402 It contains a header specifying some general settings and, for each supported
14403 primary document file format, a section
14404 \begin_inset Flex CharStyle:Code
14407 \begin_layout Plain Layout
14413 \SpecialChar \ldots{}
14415 \begin_inset Flex CharStyle:Code
14418 \begin_layout Plain Layout
14427 \begin_layout Subsection
14428 The template header
14431 \begin_layout Description
14432 \begin_inset Flex CharStyle:Code
14435 \begin_layout Plain Layout
14436 AutomaticProduction
14437 \begin_inset space ~
14445 Whether the file represented by the template must be generated by LyX.
14446 This command must occur exactly once.
14449 \begin_layout Description
14450 \begin_inset Flex CharStyle:Code
14453 \begin_layout Plain Layout
14455 \begin_inset space ~
14463 A glob pattern that is used in the file dialog to filter out the desired
14465 If there is more than one possible file extension (e.
14466 \begin_inset space \thinspace{}
14470 \begin_inset space \space{}
14474 \begin_inset Flex CharStyle:Code
14477 \begin_layout Plain Layout
14484 \begin_inset Flex CharStyle:Code
14487 \begin_layout Plain Layout
14493 ), use something like
14494 \begin_inset Flex CharStyle:Code
14497 \begin_layout Plain Layout
14504 This command must occur exactly once.
14507 \begin_layout Description
14508 \begin_inset Flex CharStyle:Code
14511 \begin_layout Plain Layout
14513 \begin_inset space ~
14521 The text that is displayed on the button.
14522 This command must occur exactly once.
14525 \begin_layout Description
14526 \begin_inset Flex CharStyle:Code
14529 \begin_layout Plain Layout
14531 \begin_inset space ~
14535 \begin_inset space ~
14543 The help text that is used in the External dialog.
14544 Provide enough information to explain to the user just what the template
14545 can provide him with.
14546 This command must occur exactly once.
14549 \begin_layout Description
14550 \begin_inset Flex CharStyle:Code
14553 \begin_layout Plain Layout
14555 \begin_inset space ~
14563 The file format of the original file.
14564 This must be the name of a format that is known to LyX (see section
14565 \begin_inset CommandInset ref
14567 reference "sub:Formats"
14573 \begin_inset Quotes eld
14577 \begin_inset Flex CharStyle:Code
14580 \begin_layout Plain Layout
14587 \begin_inset Quotes erd
14590 if the template can handle original files of more than one format.
14591 LyX will attempt to interrogate the file itself in order to deduce its
14592 format in this case.
14593 This command must occur exactly once.
14596 \begin_layout Description
14597 \begin_inset Flex CharStyle:Code
14600 \begin_layout Plain Layout
14602 \begin_inset space ~
14610 A unique name for the template.
14611 It must not contain substitution macros (see below).
14614 \begin_layout Description
14615 \begin_inset Flex CharStyle:Code
14618 \begin_layout Plain Layout
14620 \begin_inset space ~
14623 Rotate|Resize|Clip|Extra
14628 This command specifies which transformations are supported by this template.
14629 It may occur zero or more times.
14630 This command enables the corresponding tabs in the external dialog.
14632 \begin_inset Flex CharStyle:Code
14635 \begin_layout Plain Layout
14641 command must have either a corresponding
14642 \begin_inset Flex CharStyle:Code
14645 \begin_layout Plain Layout
14652 \begin_inset Flex CharStyle:Code
14655 \begin_layout Plain Layout
14662 \begin_inset Flex CharStyle:Code
14665 \begin_layout Plain Layout
14672 Otherwise the transformation will not be supported by that format.
14675 \begin_layout Subsection
14679 \begin_layout Description
14680 \begin_inset Flex CharStyle:Code
14683 \begin_layout Plain Layout
14685 \begin_inset space ~
14688 LaTeX|PDFLaTeX|PlainText|DocBook
14693 The primary document file format that this format definition is for.
14694 Not every template has a sensible representation in all document file formats.
14695 Please define nevertheless a
14696 \begin_inset Flex CharStyle:Code
14699 \begin_layout Plain Layout
14705 section for all formats.
14706 Use a dummy text when no representation is available.
14707 Then you can at least see a reference to the external material in the exported
14711 \begin_layout Description
14712 \begin_inset Flex CharStyle:Code
14715 \begin_layout Plain Layout
14717 \begin_inset space ~
14721 \begin_inset space ~
14729 This command defines an additional macro
14730 \begin_inset Flex CharStyle:Code
14733 \begin_layout Plain Layout
14739 for substitution in
14740 \begin_inset Flex CharStyle:Code
14743 \begin_layout Plain Layout
14751 \begin_inset Flex CharStyle:Code
14754 \begin_layout Plain Layout
14760 itself may contain substitution macros.
14761 The advantage over using
14762 \begin_inset Flex CharStyle:Code
14765 \begin_layout Plain Layout
14772 \begin_inset Flex CharStyle:Code
14775 \begin_layout Plain Layout
14781 is that the substituted value of
14782 \begin_inset Flex CharStyle:Code
14785 \begin_layout Plain Layout
14791 is sanitized so that it is a valid optional argument in the document format.
14792 This command may occur zero or more times.
14795 \begin_layout Description
14796 \begin_inset Flex CharStyle:Code
14799 \begin_layout Plain Layout
14801 \begin_inset space ~
14809 The text that is inserted in the exported document.
14810 This is actually the most important command and can be quite complex.
14811 This command must occur exactly once.
14814 \begin_layout Description
14815 \begin_inset Flex CharStyle:Code
14818 \begin_layout Plain Layout
14820 \begin_inset space ~
14828 This command specifies a preamble snippet that will be included in the
14830 It has to be defined using
14831 \begin_inset Flex CharStyle:Code
14834 \begin_layout Plain Layout
14840 \SpecialChar \ldots{}
14842 \begin_inset Flex CharStyle:Code
14845 \begin_layout Plain Layout
14852 This command may occur zero or more times.
14855 \begin_layout Description
14856 \begin_inset Flex CharStyle:Code
14859 \begin_layout Plain Layout
14861 \begin_inset space ~
14865 \begin_inset space ~
14873 This command denotes files that are created by the conversion process and
14874 are needed for a particular export format.
14875 If the filename is relative, it is interpreted relative to the master document.
14876 This command may be given zero or more times.
14879 \begin_layout Description
14880 \begin_inset Flex CharStyle:Code
14883 \begin_layout Plain Layout
14885 \begin_inset space ~
14893 The name of a required LaTeX package.
14894 The package is included via
14895 \begin_inset Flex CharStyle:Code
14898 \begin_layout Plain Layout
14906 in the LaTeX preamble.
14907 This command may occur zero or more times.
14910 \begin_layout Description
14911 \begin_inset Flex CharStyle:Code
14914 \begin_layout Plain Layout
14916 \begin_inset space ~
14920 \begin_inset space ~
14923 RotationLatexCommand
14928 This command specifies that the built in LaTeX command should be used for
14930 This command may occur once or not at all.
14933 \begin_layout Description
14934 \begin_inset Flex CharStyle:Code
14937 \begin_layout Plain Layout
14939 \begin_inset space ~
14943 \begin_inset space ~
14951 This command specifies that the built in LaTeX command should be used for
14953 This command may occur once or not at all.
14956 \begin_layout Description
14957 \begin_inset Flex CharStyle:Code
14960 \begin_layout Plain Layout
14962 \begin_inset space ~
14966 \begin_inset space ~
14969 RotationLatexOption
14974 This command specifies that rotation is done via an optional argument.
14975 This command may occur once or not at all.
14978 \begin_layout Description
14979 \begin_inset Flex CharStyle:Code
14982 \begin_layout Plain Layout
14984 \begin_inset space ~
14988 \begin_inset space ~
14996 This command specifies that resizing is done via an optional argument.
14997 This command may occur once or not at all.
15000 \begin_layout Description
15001 \begin_inset Flex CharStyle:Code
15004 \begin_layout Plain Layout
15006 \begin_inset space ~
15010 \begin_inset space ~
15018 This command specifies that clipping is done via an optional argument.
15019 This command may occur once or not at all.
15022 \begin_layout Description
15023 \begin_inset Flex CharStyle:Code
15026 \begin_layout Plain Layout
15028 \begin_inset space ~
15032 \begin_inset space ~
15040 This command specifies that an extra optional argument is used.
15041 This command may occur once or not at all.
15044 \begin_layout Description
15045 \begin_inset Flex CharStyle:Code
15048 \begin_layout Plain Layout
15050 \begin_inset space ~
15058 The file format of the converted file.
15059 This must be the name of a format that is known to LyX (see the
15060 \begin_inset Flex CharStyle:MenuItem
15063 \begin_layout Plain Layout
15068 ools\SpecialChar \menuseparator
15073 references:Conversion
15079 This command must occur exactly once.
15082 \begin_layout Description
15083 \begin_inset Flex CharStyle:Code
15086 \begin_layout Plain Layout
15088 \begin_inset space ~
15096 The file name of the converted file.
15097 The file name must be absolute.
15098 This command must occur exactly once.
15101 \begin_layout Subsection
15102 Preamble definitions
15105 \begin_layout Standard
15106 The external template configuration file may contain additional preamble
15107 definitions enclosed by
15108 \begin_inset Flex CharStyle:Code
15111 \begin_layout Plain Layout
15117 \SpecialChar \ldots{}
15119 \begin_inset Flex CharStyle:Code
15122 \begin_layout Plain Layout
15129 They can be used by the templates in the
15130 \begin_inset Flex CharStyle:Code
15133 \begin_layout Plain Layout
15142 \begin_layout Section
15143 The substitution mechanism
15146 \begin_layout Standard
15147 When the external material facility invokes an external program, it is done
15148 on the basis of a command defined in the template configuration file.
15149 These commands can contain various macros that are expanded before execution.
15150 Execution always take place in the directory of the containing document.
15153 \begin_layout Standard
15154 Also, whenever external material is to be displayed, the name will be produced
15155 by the substitution mechanism, and most other commands in the template
15156 definition support substitution as well.
15159 \begin_layout Standard
15160 The available macros are the following:
15163 \begin_layout Description
15164 \begin_inset Flex CharStyle:Code
15167 \begin_layout Plain Layout
15168 $$AbsOrRelPathMaster
15173 The file path, absolute or relative to the master LyX document.
15176 \begin_layout Description
15177 \begin_inset Flex CharStyle:Code
15180 \begin_layout Plain Layout
15181 $$AbsOrRelPathParent
15186 The file path, absolute or relative to the LyX document.
15189 \begin_layout Description
15190 \begin_inset Flex CharStyle:Code
15193 \begin_layout Plain Layout
15199 The absolute file path.
15202 \begin_layout Description
15203 \begin_inset Flex CharStyle:Code
15206 \begin_layout Plain Layout
15212 The filename without path and without the extension.
15215 \begin_layout Description
15216 \begin_inset Flex CharStyle:Code
15219 \begin_layout Plain Layout
15221 \begin_inset Quotes eld
15225 \begin_inset Quotes erd
15233 This macro will expand to the contents of the file with the name
15234 \begin_inset Flex CharStyle:Code
15237 \begin_layout Plain Layout
15246 \begin_layout Description
15247 \begin_inset Flex CharStyle:Code
15250 \begin_layout Plain Layout
15256 The file extension (including the dot).
15259 \begin_layout Description
15260 \begin_inset Flex CharStyle:Code
15263 \begin_layout Plain Layout
15269 The filename of the file specified in the external material dialog.
15270 This is either an absolute name, or it is relative to the LyX document.
15273 \begin_layout Description
15274 \begin_inset Flex CharStyle:Code
15277 \begin_layout Plain Layout
15284 \begin_inset Flex CharStyle:Code
15287 \begin_layout Plain Layout
15293 (absolute name or relative to the LyX document).
15296 \begin_layout Description
15297 \begin_inset Flex CharStyle:Code
15300 \begin_layout Plain Layout
15306 The file path, relative to the master LyX document.
15309 \begin_layout Description
15310 \begin_inset Flex CharStyle:Code
15313 \begin_layout Plain Layout
15319 The file path, relative to the LyX document.
15322 \begin_layout Description
15323 \begin_inset Flex CharStyle:Code
15326 \begin_layout Plain Layout
15332 This macro will expand to the absolute path of the system directory.
15333 This is typically used to point to the various helper scripts that are
15337 \begin_layout Description
15338 \begin_inset Flex CharStyle:Code
15341 \begin_layout Plain Layout
15347 A name and full path to a temporary file which will be automatically deleted
15348 whenever the containing document is closed, or the external material insertion
15352 \begin_layout Standard
15353 All path macros contain a trailing directory separator, so you can construct
15355 \begin_inset space \thinspace{}
15359 \begin_inset space \space{}
15362 the absolute filename with
15363 \begin_inset Flex CharStyle:Code
15366 \begin_layout Plain Layout
15367 $$AbsPath$$Basename$$Extension
15375 \begin_layout Standard
15376 The macros above are substituted in all commands unless otherwise noted.
15378 \begin_inset Flex CharStyle:Code
15381 \begin_layout Plain Layout
15387 supports additionally the following substitutions if they are enabled by
15389 \begin_inset Flex CharStyle:Code
15392 \begin_layout Plain Layout
15399 \begin_inset Flex CharStyle:Code
15402 \begin_layout Plain Layout
15411 \begin_layout Description
15412 \begin_inset Flex CharStyle:Code
15415 \begin_layout Plain Layout
15421 The front part of the resize command.
15424 \begin_layout Description
15425 \begin_inset Flex CharStyle:Code
15428 \begin_layout Plain Layout
15434 The back part of the resize command.
15437 \begin_layout Description
15438 \begin_inset Flex CharStyle:Code
15441 \begin_layout Plain Layout
15447 The front part of the rotation command.
15450 \begin_layout Description
15451 \begin_inset Flex CharStyle:Code
15454 \begin_layout Plain Layout
15460 The back part of the rotation command.
15463 \begin_layout Standard
15464 The value string of the
15465 \begin_inset Flex CharStyle:Code
15468 \begin_layout Plain Layout
15474 command supports additionally the following substitutions if they are enabled
15476 \begin_inset Flex CharStyle:Code
15479 \begin_layout Plain Layout
15486 \begin_inset Flex CharStyle:Code
15489 \begin_layout Plain Layout
15498 \begin_layout Description
15499 \begin_inset Flex CharStyle:Code
15502 \begin_layout Plain Layout
15511 \begin_layout Description
15512 \begin_inset Flex CharStyle:Code
15515 \begin_layout Plain Layout
15524 \begin_layout Description
15525 \begin_inset Flex CharStyle:Code
15528 \begin_layout Plain Layout
15537 \begin_layout Description
15538 \begin_inset Flex CharStyle:Code
15541 \begin_layout Plain Layout
15547 The rotation option.
15550 \begin_layout Standard
15551 You may ask why there are so many path macros.
15552 There are mainly two reasons:
15555 \begin_layout Enumerate
15556 Relative and absolute file names should remain relative or absolute, respectivel
15558 Users may have reasons to prefer either form.
15559 Relative names are useful for portable documents that should work on different
15560 machines, for example.
15561 Absolute names may be required by some programs.
15564 \begin_layout Enumerate
15565 LaTeX treats relative file names differently than LyX and other programs
15566 in nested included files.
15567 For LyX, a relative file name is always relative to the document that contains
15569 For LaTeX, it is always relative to the master document.
15570 These two definitions are identical if you have only one document, but
15571 differ if you have a master document that includes part documents.
15572 That means that relative filenames must be transformed when presented to
15574 Fortunately LyX does this automatically for you if you choose the right
15578 \begin_layout Standard
15579 So which path macro should be used in new template definitions? The rule
15583 \begin_layout Itemize
15585 \begin_inset Flex CharStyle:Code
15588 \begin_layout Plain Layout
15594 if an absolute path is required.
15597 \begin_layout Itemize
15599 \begin_inset Flex CharStyle:Code
15602 \begin_layout Plain Layout
15603 $$AbsOrRelPathMaster
15608 if the substituted string is some kind of LaTeX input.
15611 \begin_layout Itemize
15613 \begin_inset Flex CharStyle:Code
15616 \begin_layout Plain Layout
15617 $$AbsOrRelPathParent
15622 in order to preserve the user's choice.
15625 \begin_layout Standard
15626 There are special cases where this rule does not work and e.
15627 \begin_inset space \thinspace{}
15631 \begin_inset space \space{}
15634 relative names are needed, but normally it will work just fine.
15635 One example for such a case is the command
15636 \begin_inset Flex CharStyle:Code
15639 \begin_layout Plain Layout
15640 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15645 in the XFig template above: We can't use the absolute name because the
15647 \begin_inset Flex CharStyle:Code
15650 \begin_layout Plain Layout
15656 files needs the relative name in order to rewrite the file content.
15659 \begin_layout Section
15660 \begin_inset CommandInset label
15662 name "sec:Security-discussion"
15666 Security discussion
15669 \begin_layout Standard
15670 \begin_inset Box Shadowbox
15679 height_special "totalheight"
15682 \begin_layout Plain Layout
15683 WARNING: This section is definitely outdated.
15691 \begin_layout Standard
15692 The external material feature interfaces with a lot of external programs
15693 and does so automatically, so we have to consider the security implications
15695 In particular, since you have the option of including your own filenames
15696 and/or parameter strings and those are expanded into a command, it seems
15697 that it would be possible to create a malicious document which executes
15698 arbitrary commands when a user views or prints the document.
15699 This is something we definitely want to avoid.
15702 \begin_layout Standard
15703 However, since the external program commands are specified in the template
15704 configuration file only, there are no security issues if LyX is properly
15705 configured with safe templates only.
15706 This is so because the external programs are invoked with the
15707 \begin_inset Flex CharStyle:Code
15710 \begin_layout Plain Layout
15716 -system call rather than the
15717 \begin_inset Flex CharStyle:Code
15720 \begin_layout Plain Layout
15726 system-call, so it's not possible to execute arbitrary commands from the
15727 filename or parameter section via the shell.
15730 \begin_layout Standard
15731 This also implies that you are restricted in what command strings you can
15732 use in the external material templates.
15733 In particular, pipes and redirection are not readily available.
15734 This has to be so if LyX should remain safe.
15735 If you want to use some of the shell features, you should write a safe
15736 script to do this in a controlled manner, and then invoke the script from
15737 the command string.
15739 \begin_inset Flex CharStyle:Code
15742 \begin_layout Plain Layout
15748 directory of the LyX installation, you can find a safe wrapper script
15749 \begin_inset Flex CharStyle:Code
15752 \begin_layout Plain Layout
15753 general_command_wrapper.py
15758 that supports redirection of input and output.
15759 That can serve as an example for how to write safe template scripts.
15760 For a more advanced example that uses
15761 \begin_inset Flex CharStyle:Code
15764 \begin_layout Plain Layout
15770 and friends, take a look at the
15771 \begin_inset Flex CharStyle:Code
15774 \begin_layout Plain Layout
15783 \begin_layout Standard
15784 It is possible to design a template that interacts directly with the shell,
15785 but since this would allow a malicious user to execute arbitrary commands
15786 by writing clever filenames and/or parameters, we generally recommend that
15787 you only use safe scripts that work with the
15788 \begin_inset Flex CharStyle:Code
15791 \begin_layout Plain Layout
15797 system call in a controlled manner.
15798 Of course, for use in a controlled environment, it can be tempting to just
15799 fall back to use ordinary shell scripts.
15800 If you do so, be aware that you
15804 provide an easily exploitable security hole in your system.
15805 Of course it stands to reason that such unsafe templates will never be
15806 included in the standard LyX distribution, although we do encourage people
15807 to submit new templates in the open source tradition.
15808 But LyX as shipped from the official distribution channels will never have
15812 \begin_layout Standard
15813 Including external material provides a lot of power, and you have to be
15814 careful not to introduce security hazards with this power.
15815 A subtle error in a single line in an innocent looking script can open
15816 the door to huge security problems.
15817 So if you do not fully understand the issues, we recommend that you consult
15818 a knowledgeable security professional or the LyX development team if you
15819 have any questions about whether a given template is safe or not.
15820 And do this before you use it in an uncontrolled environment.