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
120 Customizing LyX: Features for the Advanced User
128 \begin_layout Plain Layout
130 If you have comments or error corrections, please send them to the LyX Documenta
132 \begin_inset CommandInset href
134 target "lyx-docs@lists.lyx.org"
141 \begin_inset Quotes eld
145 \begin_inset Quotes erd
148 in the subject header, and please cc the current maintainer of this file,
149 Richard Heck <rgheck@comcast.net>.
155 \begin_inset Newline newline
159 \begin_inset Newline newline
165 \begin_layout Standard
166 \begin_inset CommandInset toc
167 LatexCommand tableofcontents
174 \begin_layout Standard
175 \begin_inset Note Note
178 \begin_layout Plain Layout
179 Please use change tracking when modifying this document.
180 This makes it easier for our translators to recognize things that have
181 been changed, and it helps the maintainer keep up-to-date with what's been
190 \begin_layout Chapter
194 \begin_layout Standard
195 This manual covers the customization features present in LyX.
196 In it, we discuss issues like keyboard shortcuts, screen previewing options,
197 printer options, sending commands to LyX via the LyX Server, internationalizati
198 on, installing new LaTeX classes and LyX layouts, etc.
199 We can't possibly hope to touch on everything you can change—our developers
200 add new features faster than we can document them—but we will explain the
201 most common customizations and hopefully point you in the right direction
202 for some of the more obscure ones.
205 \begin_layout Standard
206 \begin_inset Branch OutDated
209 \begin_layout Standard
210 Information from previous versions of this document that now seems to be
211 outdated is contained in the OutDated branch of this document.
212 By default, this information will not appear in the LaTeX output.
220 \begin_layout Chapter
221 LyX configuration files
224 \begin_layout Standard
225 This chapter aims to help you to find your way through the LyX configuration
227 Before continuing to read this chapter, you should find out where your
228 LyX library and user directories are by using
229 \begin_inset Flex CharStyle:MenuItem
232 \begin_layout Plain Layout
233 Help\SpecialChar \menuseparator
244 The library directory is the place where LyX places its system-wide configurati
245 on files; the user directory is where you can place your modified versions.
246 We will call the former
247 \begin_inset Flex CharStyle:Code
250 \begin_layout Plain Layout
257 \begin_inset Flex CharStyle:MenuItem
260 \begin_layout Plain Layout
266 in the remainder of this document.
270 \begin_layout Section
272 \begin_inset Flex CharStyle:Code
275 \begin_layout Plain Layout
284 \begin_layout Standard
285 \begin_inset Flex CharStyle:Code
288 \begin_layout Plain Layout
294 and its sub-directories contain a number of files and that can be used
295 to customize LyX's behavior.
296 You can change many of these files from within LyX itself through the
297 \begin_inset Flex CharStyle:MenuItem
300 \begin_layout Plain Layout
301 Tools\SpecialChar \menuseparator
308 Most customization that you will want to do in LyX is possible through
310 However, many other inner aspects of LyX can be customized by modifying
312 \begin_inset Flex CharStyle:Code
315 \begin_layout Plain Layout
322 These files fall in different categories, described in the following subsection
326 \begin_layout Subsection
327 Automatically generated files
330 \begin_layout Standard
331 The files, which are to be found in
332 \begin_inset Flex CharStyle:MenuItem
335 \begin_layout Plain Layout
341 , are generated when you configure LyX.
342 They contain various default values that are guessed by inspection.
343 In general, it is not a good idea to modify them, since they might be overwritt
347 \begin_layout Labeling
348 \labelwidthstring 00.00.0000
349 \begin_inset Flex CharStyle:Code
352 \begin_layout Plain Layout
358 contains defaults for various commands.
361 \begin_layout Labeling
362 \labelwidthstring 00.00.0000
363 \begin_inset Flex CharStyle:Code
366 \begin_layout Plain Layout
372 contains the list of packages that have been recognized by LyX.
373 It is currently unused by the LyX program itself, but the information extracted
374 , and more, is made available with
375 \begin_inset Flex CharStyle:MenuItem
378 \begin_layout Plain Layout
379 Help\SpecialChar \menuseparator
392 \begin_layout Labeling
393 \labelwidthstring 00.00.0000
394 \begin_inset Flex CharStyle:Code
397 \begin_layout Plain Layout
403 the list of text classes that have been found in your
404 \begin_inset Flex CharStyle:Code
407 \begin_layout Plain Layout
413 directories, along with the associated LaTeX document class and their descripti
417 \begin_layout Labeling
418 \labelwidthstring 00.00.0000
419 \begin_inset Flex CharStyle:Code
422 \begin_layout Plain Layout
428 the list of layout modules found in your
429 \begin_inset Flex CharStyle:Code
432 \begin_layout Plain Layout
441 \begin_layout Labeling
442 \labelwidthstring 00.00.0000
443 \begin_inset Flex CharStyle:Code
446 \begin_layout Plain Layout
452 lists of various sorts of LaTeX-related files found on your system
455 \begin_layout Labeling
456 \labelwidthstring 00.00.0000
457 \begin_inset Flex CharStyle:Code
460 \begin_layout Plain Layout
466 is automatically generated during configuration from the file
467 \begin_inset Flex CharStyle:Code
470 \begin_layout Plain Layout
477 It contains information on your LaTeX configuration.
480 \begin_layout Subsection
484 \begin_layout Standard
485 These directories are duplicated between
486 \begin_inset Flex CharStyle:Code
489 \begin_layout Plain Layout
496 \begin_inset Flex CharStyle:Code
499 \begin_layout Plain Layout
506 If a particular files exists in both places, the one in
507 \begin_inset Flex CharStyle:Code
510 \begin_layout Plain Layout
519 \begin_layout Labeling
520 \labelwidthstring 00.00.0000
521 \begin_inset Flex CharStyle:Code
524 \begin_layout Plain Layout
530 this directory contains files with the extension
531 \begin_inset Flex CharStyle:Code
534 \begin_layout Plain Layout
540 that define the keybindings used in LyX.
541 If there exists an internationalized version of the bind file named
542 \begin_inset Flex CharStyle:Code
545 \begin_layout Plain Layout
551 , that will be used first.
554 \begin_layout Labeling
555 \labelwidthstring 00.00.0000
556 \begin_inset Flex CharStyle:Code
559 \begin_layout Plain Layout
565 contains graphics files that can be included in documents.
569 \begin_layout Labeling
570 \labelwidthstring 00.00.0000
571 \begin_inset Flex CharStyle:Code
574 \begin_layout Plain Layout
580 contains LyX documentation files (including the one you are currently reading).
582 \begin_inset Flex CharStyle:Code
585 \begin_layout Plain Layout
591 deserves special attention, as noted above.
592 The internationalized help docs are in subdirectories
593 \begin_inset Flex CharStyle:Code
596 \begin_layout Plain Layout
603 \begin_inset Quotes eld
607 \begin_inset Quotes erd
610 is the ISO language code.
616 \begin_inset CommandInset ref
618 reference "chap:i18n"
625 \begin_layout Labeling
626 \labelwidthstring 00.00.0000
627 \begin_inset Flex CharStyle:Code
630 \begin_layout Plain Layout
636 contains example files that explain how to use some features.
637 In the file browser, press the
638 \begin_inset Flex CharStyle:MenuItem
641 \begin_layout Plain Layout
650 \begin_layout Labeling
651 \labelwidthstring 00.00.0000
652 \begin_inset Flex CharStyle:Code
655 \begin_layout Plain Layout
661 contains image files that are used by the
662 \begin_inset Flex CharStyle:MenuItem
665 \begin_layout Plain Layout
672 In addition, it also contains the individual icons used in the toolbar
673 and the banners that can be shown when LyX is launched.
676 \begin_layout Labeling
677 \labelwidthstring 00.00.0000
678 \begin_inset Flex CharStyle:Code
681 \begin_layout Plain Layout
687 contains keyboard keymapping files.
693 \begin_inset CommandInset ref
695 reference "sec:keymap"
702 \begin_layout Labeling
703 \labelwidthstring 00.00.0000
704 \begin_inset Flex CharStyle:Code
707 \begin_layout Plain Layout
713 contains the text class and module files described in Chapter
718 \begin_inset CommandInset ref
720 reference "chap:textclass"
727 \begin_layout Labeling
728 \labelwidthstring 00.00.0000
729 \begin_inset Flex CharStyle:Code
732 \begin_layout Plain Layout
739 \begin_inset Flex CharStyle:Code
742 \begin_layout Plain Layout
748 Python scripts used to convert between LyX versions.
749 These can be run from the command line if, say, you want to batch-convert
753 \begin_layout Labeling
754 \labelwidthstring 00.00.0000
755 \begin_inset Flex CharStyle:Code
758 \begin_layout Plain Layout
764 contains some files that demonstrate the capabilities of the
765 \begin_inset Flex CharStyle:MenuItem
768 \begin_layout Plain Layout
779 Also contains some scripts used by LyX itself.
782 \begin_layout Labeling
783 \labelwidthstring 00.00.0000
784 \begin_inset Flex CharStyle:Code
787 \begin_layout Plain Layout
793 contains the standard LyX template files described in Chapter
798 \begin_inset CommandInset ref
800 reference "sec:templates"
807 \begin_layout Labeling
808 \labelwidthstring 00.00.0000
809 \begin_inset Flex CharStyle:Code
812 \begin_layout Plain Layout
818 contains files with the extension
819 \begin_inset Flex CharStyle:Code
822 \begin_layout Plain Layout
828 that define the user interface to LyX.
829 That is, the files define which items appear in which menus and the items
830 appearing on the toolbar.
833 \begin_layout Subsection
834 Files you don't want to modify
837 \begin_layout Standard
838 These files are used internally by LyX and you generally do not need to
839 modify them unless you are a developer.
842 \begin_layout Labeling
843 \labelwidthstring 00.00.0000
844 \begin_inset Flex CharStyle:Code
847 \begin_layout Plain Layout
853 this file contains the list of LyX developers.
854 The contents are displayed with the menu entry
855 \begin_inset Flex CharStyle:MenuItem
858 \begin_layout Plain Layout
859 Help\SpecialChar \menuseparator
872 \begin_layout Labeling
873 \labelwidthstring 00.00.0000
874 \begin_inset Flex CharStyle:Code
877 \begin_layout Plain Layout
883 this is a LaTeX script used during the configuration process.
887 \begin_layout Labeling
888 \labelwidthstring 00.00.0000
889 \begin_inset Flex CharStyle:Code
892 \begin_layout Plain Layout
898 this is the script that is used to re-configure LyX.
899 It creates configuration files in the directory it was run from.
902 \begin_layout Subsection
903 Other files needing a line or two...
906 \begin_layout Labeling
907 \labelwidthstring 00.00.0000
908 \begin_inset Flex CharStyle:Code
911 \begin_layout Plain Layout
917 this contains tables describing how different character encodings can be
921 \begin_layout Labeling
922 \labelwidthstring 00.00.0000
923 \begin_inset Flex CharStyle:Code
926 \begin_layout Plain Layout
932 this file contains the templates available to the new
933 \begin_inset Flex CharStyle:MenuItem
936 \begin_layout Plain Layout
949 \begin_layout Labeling
950 \labelwidthstring 00.00.0000
951 \begin_inset Flex CharStyle:Code
954 \begin_layout Plain Layout
960 this file contains a list of all the languages currently supported by LyX.
963 \begin_layout Section
964 Your local configuration directory
967 \begin_layout Standard
968 Even if you are using LyX as an unprivileged user, you might want to change
969 LyX configuration for your own use.
971 \begin_inset Flex CharStyle:Code
974 \begin_layout Plain Layout
980 directory contains all your personal configuration files.
981 This is the directory described as
982 \begin_inset Quotes eld
986 \begin_inset Quotes erd
990 \begin_inset Flex CharStyle:MenuItem
993 \begin_layout Plain Layout
994 Help\SpecialChar \menuseparator
1005 This directory is used as a mirror of
1006 \begin_inset Flex CharStyle:Code
1009 \begin_layout Plain Layout
1015 , which means that every file in
1016 \begin_inset Flex CharStyle:Code
1019 \begin_layout Plain Layout
1025 is a replacement for the corresponding file in
1026 \begin_inset Flex CharStyle:Code
1029 \begin_layout Plain Layout
1036 Any configuration file described in the above sections can be placed either
1037 in the system-wide directory, in which case it will affect all users, or
1038 in your local directory for your own use.
1041 \begin_layout Standard
1042 To make things clearer, let's provide a few examples:
1045 \begin_layout Itemize
1046 The preferences set in the
1047 \begin_inset Flex CharStyle:MenuItem
1050 \begin_layout Plain Layout
1051 Tools\SpecialChar \menuseparator
1057 dialog are saved to a file
1058 \begin_inset Flex CharStyle:Code
1061 \begin_layout Plain Layout
1068 \begin_inset Flex CharStyle:Code
1071 \begin_layout Plain Layout
1080 \begin_layout Itemize
1081 When you reconfigure using
1082 \begin_inset Flex CharStyle:MenuItem
1085 \begin_layout Plain Layout
1086 Tools\SpecialChar \menuseparator
1093 \begin_inset Flex CharStyle:Code
1096 \begin_layout Plain Layout
1102 script, and the resulting files are written in your local configuration
1104 This means that any additional text class file that you might have added
1106 \begin_inset Flex CharStyle:Code
1109 \begin_layout Plain Layout
1115 will be added to the list of classes in the
1116 \begin_inset Flex CharStyle:MenuItem
1119 \begin_layout Plain Layout
1120 Document\SpecialChar \menuseparator
1129 \begin_layout Itemize
1130 If you get some updated documentation from LyX ftp site and cannot install
1131 it because you do not have sysadmin rights on your system, you can just
1133 \begin_inset Flex CharStyle:Code
1136 \begin_layout Plain Layout
1142 and the items in the
1143 \begin_inset Flex CharStyle:MenuItem
1146 \begin_layout Plain Layout
1152 menu will open them!
1155 \begin_layout Section
1156 Running LyX with multiple configurations
1159 \begin_layout Standard
1160 The configuration freedom of the local configuration directory may not suffice
1161 if you want to have more than one configuration at your disposal.
1162 For example, you may want to be use different key bindings or printer settings
1164 You can achieve this by having several such directories.
1165 You then specify which directory to use at run-time.
1168 \begin_layout Standard
1169 Invoking LyX with the command line switch
1170 \begin_inset Flex CharStyle:Code
1173 \begin_layout Plain Layout
1183 instructs the program to read the configuration from that directory, and
1184 not from the default directory.
1185 (You can determine the default directory by running LyX without the
1186 \begin_inset Flex CharStyle:Code
1189 \begin_layout Plain Layout
1195 switch.) If the specified directory does not exist, LyX offers to create
1196 it for you, just like it does for the default directory on the first time
1197 you run the program.
1198 You can modify the configuration options in this additional user directory
1199 exactly as you would for the default directory.
1200 These directories are completely independent (but read on).
1201 Note that setting the environment variable
1202 \begin_inset Flex CharStyle:Code
1205 \begin_layout Plain Layout
1211 to some value has exactly the same effect.
1214 \begin_layout Standard
1215 Having several configurations also requires more maintenance: if you want
1216 to add a new layout to
1217 \begin_inset Flex CharStyle:Code
1220 \begin_layout Plain Layout
1226 which you want available from all your configurations, you must add it
1227 to each directory separately.
1228 You can avoid this with the following trick: after LyX creates the additional
1229 directory, most of the subdirectories (see above) are empty.
1230 If you want the new configuration to mirror an existing one, replace the
1231 empty subdirectory with a symbolic link to the matching subdirectory in
1232 the existing configuration.
1234 \begin_inset Flex CharStyle:Code
1237 \begin_layout Plain Layout
1243 subdirectory, however, since it contains a file written by the configuration
1244 script (also accessible through
1245 \begin_inset Flex CharStyle:MenuItem
1248 \begin_layout Plain Layout
1249 Tools\SpecialChar \menuseparator
1255 ) which is configuration-specific.
1258 \begin_layout Chapter
1259 The Preferences dialog
1262 \begin_layout Standard
1263 All options of the preferences dialog are described in the Appendix
1265 The Preferences Dialog
1272 For some options you might find here more details.
1275 \begin_layout Section
1276 Using the dialog for the first time
1279 \begin_layout Standard
1281 \begin_inset Flex CharStyle:Code
1284 \begin_layout Plain Layout
1290 file will contain only changes that you have made to the default behavior,
1291 some of which is hard-coded into LyX and some of which is contained in
1293 \begin_inset Flex CharStyle:Code
1296 \begin_layout Plain Layout
1297 LyXDir/lyxrc.defaults
1303 Note that in both files lines beginning with a
1304 \begin_inset Quotes eld
1308 \begin_inset Quotes erd
1311 are just comments and are not interpreted.
1312 However, only system administrators should edit
1313 \begin_inset Flex CharStyle:Code
1316 \begin_layout Plain Layout
1317 LyXDir/lyxrc.defaults
1323 Users should use the
1324 \begin_inset Flex CharStyle:MenuItem
1327 \begin_layout Plain Layout
1328 Tools\SpecialChar \menuseparator
1334 dialog to create and modify their own
1335 \begin_inset Flex CharStyle:Code
1338 \begin_layout Plain Layout
1347 \begin_layout Standard
1349 \begin_inset Flex CharStyle:MenuItem
1352 \begin_layout Plain Layout
1353 Tools\SpecialChar \menuseparator
1359 dialog will be largely self-explanatory.
1360 Most things in the dialog have associated `tool tips': hover your mouse
1361 pointer over something for more information.
1362 Before we highlight a few of the more important commands below, however,
1363 a word of warning: Applying some of your changes (e.
1364 \begin_inset space \thinspace{}
1368 \begin_inset space \space{}
1371 screen fonts) will have an instant effect.
1373 \begin_inset space \thinspace{}
1377 \begin_inset space \space{}
1380 changing the bind file) will not.
1381 If nothing appears to have changed, just
1382 \begin_inset Flex CharStyle:MenuItem
1385 \begin_layout Plain Layout
1391 the changes and restart LyX.
1394 \begin_layout Section
1398 \begin_layout Standard
1399 LyX has a powerful mechanism to convert to and from any file format using
1404 \begin_layout Subsection
1405 \begin_inset CommandInset label
1414 \begin_layout Standard
1415 The first step is to define your file formats if they are not already defined.
1417 \begin_inset Flex CharStyle:MenuItem
1420 \begin_layout Plain Layout
1421 Tools\SpecialChar \menuseparator
1429 \begin_inset Flex CharStyle:MenuItem
1432 \begin_layout Plain Layout
1433 File Handling\SpecialChar \menuseparator
1440 \begin_inset Flex CharStyle:MenuItem
1443 \begin_layout Plain Layout
1444 New\SpecialChar \ldots{}
1450 button to define your new format.
1452 \begin_inset Flex CharStyle:MenuItem
1455 \begin_layout Plain Layout
1461 field contains the named used to identify the format in the GUI.
1463 \begin_inset Flex CharStyle:MenuItem
1466 \begin_layout Plain Layout
1472 is used to identify the format internally.
1473 You will also need to enter a file extension.
1474 These are all required.
1476 \begin_inset Flex CharStyle:MenuItem
1479 \begin_layout Plain Layout
1485 field is used to provide a keyboard shortcut on the menus.
1486 (For example, pressing
1487 \begin_inset Flex CharStyle:MenuItem
1490 \begin_layout Plain Layout
1497 \begin_inset Flex CharStyle:MenuItem
1500 \begin_layout Plain Layout
1501 View\SpecialChar \menuseparator
1510 \begin_layout Standard
1512 \begin_inset Flex CharStyle:MenuItem
1515 \begin_layout Plain Layout
1522 \begin_inset Flex CharStyle:MenuItem
1525 \begin_layout Plain Layout
1532 For example, you might want to use
1533 \begin_inset Flex CharStyle:MenuItem
1536 \begin_layout Plain Layout
1542 to view PostScript files.
1543 You can enter the command needed to start the program in the corresponding
1545 In defining this command, you can use the four variables listed in the
1547 The viewer is launched when you view an image in LyX or use the
1548 \begin_inset Flex CharStyle:MenuItem
1551 \begin_layout Plain Layout
1558 The editor is for example launched when you press the
1559 \begin_inset Flex CharStyle:MenuItem
1562 \begin_layout Plain Layout
1569 \begin_inset Flex CharStyle:MenuItem
1572 \begin_layout Plain Layout
1579 \begin_inset Flex CharStyle:MenuItem
1582 \begin_layout Plain Layout
1591 \begin_layout Standard
1593 \begin_inset Flex CharStyle:MenuItem
1596 \begin_layout Plain Layout
1602 option tells LyX that a format is suitable for document export.
1603 If this is is set and if a suitable conversion route exists (see
1604 \begin_inset CommandInset ref
1606 reference "sub:Converters"
1610 ), the format will appear in the
1611 \begin_inset Flex CharStyle:MenuItem
1614 \begin_layout Plain Layout
1615 File\SpecialChar \menuseparator
1622 The format will also appear in the
1623 \begin_inset Flex CharStyle:MenuItem
1626 \begin_layout Plain Layout
1632 menu if a viewer is specified for the format.
1633 Pure image formats, such as
1634 \begin_inset Flex CharStyle:Code
1637 \begin_layout Plain Layout
1643 , should not use this option.
1644 Formats that can both represent vector graphics and documents like
1645 \begin_inset Flex CharStyle:Code
1648 \begin_layout Plain Layout
1657 \begin_layout Standard
1659 \begin_inset Flex CharStyle:MenuItem
1662 \begin_layout Plain Layout
1663 Vector graphics format
1668 tells LyX that a format can contain vector graphics.
1669 This information is used to determine the target format of included graphics
1671 \begin_inset Flex CharStyle:MenuItem
1674 \begin_layout Plain Layout
1681 Included graphics may need to be converted to either
1682 \begin_inset Flex CharStyle:MenuItem
1685 \begin_layout Plain Layout
1692 \begin_inset Flex CharStyle:MenuItem
1695 \begin_layout Plain Layout
1702 \begin_inset Flex CharStyle:MenuItem
1705 \begin_layout Plain Layout
1712 \begin_inset Flex CharStyle:MenuItem
1715 \begin_layout Plain Layout
1721 cannot handle other image formats.
1722 If an included graphic is not already in
1723 \begin_inset Flex CharStyle:MenuItem
1726 \begin_layout Plain Layout
1733 \begin_inset Flex CharStyle:MenuItem
1736 \begin_layout Plain Layout
1743 \begin_inset Flex CharStyle:MenuItem
1746 \begin_layout Plain Layout
1752 format, it is converted to
1753 \begin_inset Flex CharStyle:MenuItem
1756 \begin_layout Plain Layout
1762 if the vector format option is set, and otherwise to
1763 \begin_inset Flex CharStyle:MenuItem
1766 \begin_layout Plain Layout
1775 \begin_layout Subsection
1779 \begin_layout Standard
1780 Since all conversions from one format to another take place in LyX's temporary
1781 directory, it is sometimes necessary to modify a file before copying it
1782 to the temporary directory in order that the conversion may be performed.
1786 \begin_layout Plain Layout
1787 For example, the file may refer to other files—images, for example—using
1788 relative file names, and these may become invalid when the file is copied
1789 to the temporary directory.
1794 This is done by a Copier: It copies a file to (or from) the temporary directory
1795 and may modify it in the process.
1798 \begin_layout Standard
1799 The definitions of the copiers may use four variables:
1802 \begin_layout Labeling
1803 \labelwidthstring 00.00.0000
1804 \begin_inset Flex CharStyle:Code
1807 \begin_layout Plain Layout
1813 The LyX system directory (e.
1814 \begin_inset space \thinspace{}
1818 \begin_inset space \space{}
1822 \begin_inset Flex CharStyle:MenuItem
1825 \begin_layout Plain Layout
1834 \begin_layout Labeling
1835 \labelwidthstring 00.00.0000
1836 \begin_inset Flex CharStyle:Code
1839 \begin_layout Plain Layout
1848 \begin_layout Labeling
1849 \labelwidthstring 00.00.0000
1850 \begin_inset Flex CharStyle:Code
1853 \begin_layout Plain Layout
1862 \begin_layout Labeling
1863 \labelwidthstring 00.00.0000
1864 \begin_inset Flex CharStyle:Code
1867 \begin_layout Plain Layout
1876 \begin_layout Standard
1877 The latter should be the filename as it would be used in a LaTeX's
1884 It is relevant only when exporting files suitable for such inclusion.
1887 \begin_layout Standard
1888 Copiers can be used to do almost anything with output files.
1889 For example, suppose you want generated pdf files to be copied to a special
1891 \begin_inset Flex CharStyle:Code
1894 \begin_layout Plain Layout
1901 Then you could write a shell script such as this one:
1904 \begin_layout Standard
1905 \begin_inset listings
1909 \begin_layout Plain Layout
1914 \begin_layout Plain Layout
1919 \begin_layout Plain Layout
1921 TOFILE=`basename $2`
1924 \begin_layout Plain Layout
1926 cp $FROMFILE /home/you/pdf/$TOFILE
1931 Save that in your local LyX directory—say,
1932 \begin_inset Flex CharStyle:Code
1935 \begin_layout Plain Layout
1936 /home/you/.lyx/scripts/pdfcopier.sh
1941 —and make it executable, if you need to do so on your platform.
1943 \begin_inset Flex CharStyle:MenuItem
1946 \begin_layout Plain Layout
1947 Tools\SpecialChar \menuseparator
1953 dialog, select under
1954 \begin_inset Flex CharStyle:MenuItem
1957 \begin_layout Plain Layout
1958 File Handling\SpecialChar \menuseparator
1965 \begin_inset Flex CharStyle:MenuItem
1968 \begin_layout Plain Layout
1974 format—or one of the other pdf formats—and enter
1975 \begin_inset Flex CharStyle:Code
1978 \begin_layout Plain Layout
1979 pdfcopier.sh $$i $$o
1985 \begin_inset Flex CharStyle:MenuItem
1988 \begin_layout Plain Layout
1998 \begin_layout Standard
1999 Copiers are used by LyX in various of its own conversions.
2000 For example, if appropriate programs are found, LyX will automatically
2001 install copiers for the
2002 \begin_inset Flex CharStyle:MenuItem
2005 \begin_layout Plain Layout
2012 \begin_inset Flex CharStyle:MenuItem
2015 \begin_layout Plain Layout
2017 \begin_inset space ~
2026 When these formats are exported, the copier sees that not just the main
2027 HTML file but various associated files (style files, images, etc.) are also
2029 All these files are written to a subdirectory of the directory in which
2030 the original LyX file was found.
2034 \begin_layout Plain Layout
2035 This copier can be customized.
2037 \begin_inset Quotes eld
2041 \begin_inset Quotes erd
2044 argument takes a comma-separated list of extensions to be copied; if it
2045 is omitted, all files will be copied.
2047 \begin_inset Quotes eld
2051 \begin_inset Quotes erd
2054 argument determines the extension added to the generated directory.
2056 \begin_inset Quotes eld
2060 \begin_inset Flex CharStyle:MenuItem
2063 \begin_layout Plain Layout
2070 \begin_inset Quotes erd
2073 , so HTML generated from
2074 \begin_inset Flex CharStyle:MenuItem
2077 \begin_layout Plain Layout
2078 /path/to/filename.lyx
2084 \begin_inset Flex CharStyle:MenuItem
2087 \begin_layout Plain Layout
2088 /path/to/filename.html.LyXconv
2102 \begin_layout Subsection
2103 \begin_inset CommandInset label
2105 name "sub:Converters"
2112 \begin_layout Standard
2113 You can define your own Converters to convert files between different formats.
2115 \begin_inset Flex CharStyle:MenuItem
2118 \begin_layout Plain Layout
2119 Tools\SpecialChar \menuseparator
2120 Preferences\SpecialChar \menuseparator
2121 File Handling\SpecialChar \menuseparator
2130 \begin_layout Standard
2131 To define a new converter, select the
2132 \begin_inset Flex CharStyle:MenuItem
2135 \begin_layout Plain Layout
2137 \begin_inset space ~
2146 \begin_inset Flex CharStyle:MenuItem
2149 \begin_layout Plain Layout
2151 \begin_inset space ~
2159 from the drop-down lists, enter the command needed for the conversion,
2161 \begin_inset Flex CharStyle:MenuItem
2164 \begin_layout Plain Layout
2171 Several variables can be used in the definition of converters:
2174 \begin_layout Labeling
2175 \labelwidthstring 00.00.0000
2176 \begin_inset Flex CharStyle:Code
2179 \begin_layout Plain Layout
2185 The LyX system directory
2188 \begin_layout Labeling
2189 \labelwidthstring 00.00.0000
2190 \begin_inset Flex CharStyle:Code
2193 \begin_layout Plain Layout
2202 \begin_layout Labeling
2203 \labelwidthstring 00.00.0000
2204 \begin_inset Flex CharStyle:Code
2207 \begin_layout Plain Layout
2216 \begin_layout Labeling
2217 \labelwidthstring 00.00.0000
2218 \begin_inset Flex CharStyle:Code
2221 \begin_layout Plain Layout
2227 The base filename of the input file (i.
2228 \begin_inset space \thinspace{}
2231 g., without the extension)
2234 \begin_layout Labeling
2235 \labelwidthstring 00.00.0000
2236 \begin_inset Flex CharStyle:Code
2239 \begin_layout Plain Layout
2245 The path to the input file
2248 \begin_layout Labeling
2249 \labelwidthstring 00.00.0000
2250 \begin_inset Flex CharStyle:Code
2253 \begin_layout Plain Layout
2259 The path to the original input file (this is different from $$p when chain
2260 of converters is called).
2263 \begin_layout Standard
2265 \begin_inset Flex CharStyle:MenuItem
2268 \begin_layout Plain Layout
2270 \begin_inset space ~
2278 field you can enter the following flags, separated by commas:
2281 \begin_layout Labeling
2282 \labelwidthstring 00.00.0000
2283 \begin_inset Flex CharStyle:Code
2286 \begin_layout Plain Layout
2292 This converter runs some form of LaTeX.
2293 This will make LyX's LaTeX error logs available.
2296 \begin_layout Labeling
2297 \labelwidthstring 00.00.0000
2298 \begin_inset Flex CharStyle:Code
2301 \begin_layout Plain Layout
2308 \begin_inset Flex CharStyle:MenuItem
2311 \begin_layout Plain Layout
2317 file for the conversion.
2320 \begin_layout Labeling
2321 \labelwidthstring 00.00.0000
2322 \begin_inset Flex CharStyle:Code
2325 \begin_layout Plain Layout
2334 \begin_layout Standard
2335 The following three flags are not really flags at all because they take
2337 \begin_inset Flex CharStyle:MenuItem
2340 \begin_layout Plain Layout
2342 \begin_inset space ~
2346 \begin_inset space ~
2357 \begin_layout Labeling
2358 \labelwidthstring 00.00.0000
2359 \begin_inset Flex CharStyle:Code
2362 \begin_layout Plain Layout
2368 If set, the converter's standard error will be redirected to a file
2369 \begin_inset Flex CharStyle:Code
2372 \begin_layout Plain Layout
2378 , and the script given as argument will be run as:
2379 \begin_inset Flex CharStyle:Code
2382 \begin_layout Plain Layout
2383 script <infile.out >infile.log
2389 The argument may contain
2390 \begin_inset Flex CharStyle:Code
2393 \begin_layout Plain Layout
2402 \begin_layout Labeling
2403 \labelwidthstring 00.00.0000
2404 \begin_inset Flex CharStyle:Code
2407 \begin_layout Plain Layout
2413 The name of the directory in which the converter will dump the generated
2415 LyX will not create this directory, and it does not copy anything into
2416 it, though it will copy this directory to the destination.
2417 The argument may contain
2418 \begin_inset Flex CharStyle:Code
2421 \begin_layout Plain Layout
2427 , which will be replaced by the base name of the input and output files,
2428 respectively, when the directory is copied.
2429 \begin_inset Newline newline
2432 Note that resultdir and usetempdir make no sense together.
2433 The latter will be ignored if the former is given.
2436 \begin_layout Labeling
2437 \labelwidthstring 00.00.0000
2438 \begin_inset Flex CharStyle:Code
2441 \begin_layout Plain Layout
2447 Determines the output file name and may, contain
2448 \begin_inset Flex CharStyle:Code
2451 \begin_layout Plain Layout
2458 Sensible only with resultdir and optional even then; if not given, it defaults
2462 \begin_layout Standard
2463 None of these last three are presently used in any of the converters that
2464 are installed with LyX.
2468 \begin_layout Standard
2469 You do not have to define converters between all the formats between which
2470 you want to convert.
2471 For example, you will note that there is no `LyX to PostScript' converter,
2472 but LyX will export PostScript.
2473 It does so by first creating a LaTeX file (no converter needs to be defined
2474 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2475 and finally converting the resulting DVI file to PostScript.
2476 LyX finds such `chains' of converters automatically, and it will always
2477 choose the shortest possible chain.
2478 You can, though, still define multiple conversion methods between file
2480 For example, the standard LyX configuration provides three ways to convert
2481 LaTeX to PDF: Directly, using
2482 \begin_inset Flex CharStyle:MenuItem
2485 \begin_layout Plain Layout
2491 ; via (DVI and) PostScript, using
2492 \begin_inset Flex CharStyle:MenuItem
2495 \begin_layout Plain Layout
2502 \begin_inset Flex CharStyle:MenuItem
2505 \begin_layout Plain Layout
2512 To define such alternate chains, you must define multiple target `file
2513 formats', as described in section
2514 \begin_inset CommandInset ref
2516 reference "sub:Formats"
2521 For example, in the standard configuration, the formats named
2522 \begin_inset Flex CharStyle:MenuItem
2525 \begin_layout Plain Layout
2532 \begin_inset Flex CharStyle:MenuItem
2535 \begin_layout Plain Layout
2542 \begin_inset Flex CharStyle:MenuItem
2545 \begin_layout Plain Layout
2551 are defined, all of which share the extension
2552 \begin_inset Flex CharStyle:MenuItem
2555 \begin_layout Plain Layout
2561 , and which correspond to the conversion methods just mentioned.
2564 \begin_layout Chapter
2565 Internationalizing LyX
2566 \begin_inset CommandInset label
2575 \begin_layout Standard
2576 LyX supports using a translated interface.
2577 Last time we checked, LyX provided text in thirty languages.
2578 The language of choice is called your
2583 (For further reading on locale settings, see also the documentation for
2584 locale that comes with your operating system.
2585 For Linux, the manual page for
2586 \begin_inset Flex CharStyle:Code
2589 \begin_layout Plain Layout
2595 could be a good place to start).
2598 \begin_layout Standard
2599 Notice that these translations will work, but do contain a few flaws.
2600 In particular, all dialogs have been designed with the English text in
2601 mind, which means that some of the translated text will be too large to
2602 fit within the space allocated.
2603 This is only a display problem and will not cause any harm.
2604 Also, you will find that some of the translations do not define shortcut
2605 keys for everything.
2606 Sometimes, there are simply not enough free letters to do it.
2607 Other times, the translator just hasn't got around to doing it yet.
2608 Our localization team, which you may wish to join,
2612 \begin_layout Plain Layout
2613 If you are a fluent speaker of a language other than English, joining these
2614 teams is a great way to give back to the LyX community!
2619 will of course try to fix these shortcomings in future versions of LyX.
2622 \begin_layout Section
2626 \begin_layout Subsection
2627 Translating the graphical user interface (text messages).
2630 \begin_layout Standard
2632 \begin_inset Flex CharStyle:Code
2635 \begin_layout Plain Layout
2641 library to handle the internationalization of the interface.
2642 To have LyX speak your favorite language in all menus and dialogs, you
2644 \begin_inset Flex CharStyle:Code
2647 \begin_layout Plain Layout
2653 -file for that language.
2654 When this is available, you'll have to generate a
2655 \begin_inset Flex CharStyle:Code
2658 \begin_layout Plain Layout
2664 -file from it and install the
2665 \begin_inset Flex CharStyle:Code
2668 \begin_layout Plain Layout
2675 The process of doing all of this is explained in the documentation for
2677 \begin_inset Flex CharStyle:Code
2680 \begin_layout Plain Layout
2687 It is possible to do this just for yourself, but if you're going to do
2688 it, you might as well share the results of your labors with the rest of
2690 Send a message to the LyX developers' list for more information about how
2694 \begin_layout Standard
2695 In short, this is what you should do (xx denotes the language code):
2698 \begin_layout Itemize
2699 Check out the LyX source code.
2701 \begin_inset CommandInset href
2703 name "information on the web"
2704 target "http://www.lyx.org/devel/cvs.php"
2711 \begin_layout Itemize
2713 \begin_inset Flex CharStyle:Code
2716 \begin_layout Plain Layout
2722 to the folder of the
2723 \begin_inset Flex CharStyle:Code
2726 \begin_layout Plain Layout
2734 \begin_inset Flex CharStyle:Code
2737 \begin_layout Plain Layout
2745 \begin_inset Flex CharStyle:Code
2748 \begin_layout Plain Layout
2754 doesn't exist anywhere, it can be remade with the console command
2755 \begin_inset Flex CharStyle:Code
2758 \begin_layout Plain Layout
2764 in that directory, or you can use an existing po-file for some other language
2768 \begin_layout Itemize
2770 \begin_inset Flex CharStyle:Code
2773 \begin_layout Plain Layout
2783 \begin_layout Plain Layout
2784 This is just a text file, so it can be edited in any text editor.
2785 But there are also specialized programs that support such editing, such
2790 (for all platforms) or
2799 contains a `mode' for editing
2800 \begin_inset Flex CharStyle:Code
2803 \begin_layout Plain Layout
2814 For some menu- and widget-labels, there are also shortcut keys that should
2816 Those keys are marked after a `|', and should be translated according to
2817 the words and phrases of the language.
2818 You should also fill also out the information at the beginning of the new
2820 \begin_inset Flex CharStyle:Code
2823 \begin_layout Plain Layout
2829 -file with your email-address, etc., so people know where to reach you with
2830 suggestions and entertaining flames.
2833 \begin_layout Standard
2834 If you are just doing this on your own, then:
2837 \begin_layout Itemize
2839 \begin_inset Flex CharStyle:Code
2842 \begin_layout Plain Layout
2849 This can be done with
2850 \begin_inset Flex CharStyle:Code
2853 \begin_layout Plain Layout
2854 msgfmt -o xx.mo < xx.po
2862 \begin_layout Itemize
2864 \begin_inset Flex CharStyle:Code
2867 \begin_layout Plain Layout
2873 -file to your locale-tree, at the correct directory for application messages
2878 xx, and under the name
2879 \begin_inset Flex CharStyle:Code
2882 \begin_layout Plain Layout
2889 \begin_inset space \thinspace{}
2893 \begin_inset space \space{}
2897 \begin_inset Flex CharStyle:Code
2900 \begin_layout Plain Layout
2901 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2911 \begin_layout Standard
2912 As said, however, it would be best if the new
2913 \begin_inset Flex CharStyle:Code
2916 \begin_layout Plain Layout
2922 -file could be added to the LyX distribution, so others can use it.
2923 Adding it involves making additional changes to LyX.
2924 So send an email to the developers' mailing list if you're interested in
2928 \begin_layout Subsubsection
2932 \begin_layout Standard
2933 Sometimes it turns out that one English message needs to be translated into
2934 different messages in the target language.
2935 One example is the message
2936 \begin_inset Flex CharStyle:Code
2939 \begin_layout Plain Layout
2945 which has the German translation
2953 , depending upon exactly what the English
2954 \begin_inset Quotes eld
2958 \begin_inset Quotes erd
2963 \begin_inset Flex CharStyle:Code
2966 \begin_layout Plain Layout
2972 does not handle such ambiguous translations.
2973 Therefore you have to add some context information to the message: Instead
2975 \begin_inset Flex CharStyle:Code
2978 \begin_layout Plain Layout
2985 \begin_inset Flex CharStyle:Code
2988 \begin_layout Plain Layout
2989 To[[as in 'From format x to format y']]
2995 \begin_inset Flex CharStyle:Code
2998 \begin_layout Plain Layout
2999 To[[as in 'From page x to page y']].
3004 Now the two occurrences of
3005 \begin_inset Flex CharStyle:Code
3008 \begin_layout Plain Layout
3015 \begin_inset Flex CharStyle:Code
3018 \begin_layout Plain Layout
3024 and can be translated correctly to
3035 \begin_layout Standard
3036 Of course the context information needs to be stripped off the original
3037 message when no translation is used.
3038 Therefore you have to put it in double square brackets at the end of the
3039 message (see the example above).
3040 The translation mechanism of LyX ensures that everything in double square
3041 brackets at the end of messages is removed before displaying the message.
3044 \begin_layout Subsection
3045 Translating the documentation.
3048 \begin_layout Standard
3049 The online documentation (in the
3050 \begin_inset Flex CharStyle:MenuItem
3053 \begin_layout Plain Layout
3059 -menu) can (and should!) be translated.
3060 If there are translated versions of the documentation available
3064 \begin_layout Plain Layout
3065 As of March 2008, at least some of the documents have been translated into
3066 fourteen languages, with the Tutorial available in a few more.
3071 and the locale is set accordingly, these will be used automagically by
3073 LyX looks for translated versions as
3074 \begin_inset Flex CharStyle:Code
3077 \begin_layout Plain Layout
3078 LyXDir/doc/xx/DocName.lyx
3084 \begin_inset Flex CharStyle:Code
3087 \begin_layout Plain Layout
3093 is the code for the language currently in use.
3094 If there are no translated documents, the default English versions will
3096 Note that the translated versions must have the same filenames (
3097 \begin_inset Flex CharStyle:Code
3100 \begin_layout Plain Layout
3106 above) as the original.
3107 If you feel up to translating the documentation (an excellent way to proof-read
3108 the original documentation by the way!), there are a few things you should
3112 \begin_layout Itemize
3114 \begin_inset Flex CharStyle:Code
3117 \begin_layout Plain Layout
3123 , the guide to writing LyX documentation.
3124 Pay special attention to the translator's section.
3127 \begin_layout Itemize
3128 Check out the documentation translation web page at
3129 \begin_inset CommandInset href
3131 name "http://www.lyx.org/Translation"
3132 target "http://www.lyx.org/Translation"
3137 That way, you can find out which (if any) documents have already been translate
3138 d into your language.
3139 You can also find out who (if anyone) is organizing the effort to translate
3140 the documentation into your language.
3141 If no one is organizing the effort, please let us know that you're interested.
3144 \begin_layout Standard
3145 Once you get to actually translating, here's a few hints for you that may
3149 \begin_layout Itemize
3150 Join the documentation team! There is information on how to do that in
3151 \begin_inset Flex CharStyle:Code
3154 \begin_layout Plain Layout
3161 \begin_inset Flex CharStyle:MenuItem
3164 \begin_layout Plain Layout
3165 Help\SpecialChar \menuseparator
3175 ), which by the way is the first document you should translate.
3178 \begin_layout Itemize
3179 Learn the typographic conventions for the language you are translating to.
3180 Typography is an ancient art and over the centuries, a great variety of
3181 conventions have developed throughout different parts of the world.
3182 Also study the professional terminology amongst typographers in your country.
3183 Inventing your own terminology will only confuse the users.
3186 (Warning! Typography is addictive!)
3189 \begin_layout Itemize
3190 Make a copy of the document.
3191 This will be your working copy.
3192 You can use this as your personal translated help-file by placing it in
3194 \begin_inset Flex CharStyle:Code
3197 \begin_layout Plain Layout
3206 \begin_layout Itemize
3207 Sometimes the original document (from the LyX-team) will be updated.
3208 Use the source viewer at
3209 \begin_inset CommandInset href
3211 name "http://www.lyx.org/trac/timeline"
3212 target "http://www.lyx.org/trac/timeline"
3216 to see what has been changed.
3217 That way you can easily see which parts of the translated document need
3221 \begin_layout Standard
3222 If you ever find an error in the original document, fix it and notify the
3223 rest of the documentation team of the changes! (You didn't forget to join
3224 the documentation team, did you?)
3227 \begin_layout Standard
3228 \begin_inset Branch OutDated
3231 \begin_layout Section
3232 International Keyboard Support
3235 \begin_layout Standard
3238 [Editor's Note: The following section is by
3246 It needs to be fixed to conform to the new Documentation Style sheet and
3247 to make use of the new v1.0 features.
3248 The whole thing also needs to be merged with the section following it.-jw
3249 It may also be badly out of date.-rh (2008)]
3252 \begin_layout Subsection
3253 Defining Own Keymaps: Keymap File Format
3256 \begin_layout Standard
3257 Let's look at a keyboard definition file a little closer.
3258 It is a plain text file defining
3261 \begin_layout Itemize
3262 key-to-key or key-to-string translations
3265 \begin_layout Itemize
3269 \begin_layout Itemize
3270 dead keys exceptions
3273 \begin_layout Standard
3274 To define key-to-key or key-to-string translation, use this command:
3277 \begin_layout Quotation
3278 \begin_inset Flex CharStyle:Code
3281 \begin_layout Plain Layout
3290 \begin_inset Flex CharStyle:Code
3293 \begin_layout Plain Layout
3302 \begin_layout Standard
3304 \begin_inset Flex CharStyle:Code
3307 \begin_layout Plain Layout
3313 is the key to be translated and
3314 \begin_inset Flex CharStyle:Code
3317 \begin_layout Plain Layout
3323 is the string to be inserted into the document.
3324 To define dead keys, use:
3327 \begin_layout Quotation
3328 \begin_inset Flex CharStyle:Code
3331 \begin_layout Plain Layout
3340 \begin_inset Flex CharStyle:Code
3343 \begin_layout Plain Layout
3352 \begin_layout Standard
3354 \begin_inset Flex CharStyle:Code
3357 \begin_layout Plain Layout
3363 is a keyboard key and
3364 \begin_inset Flex CharStyle:Code
3367 \begin_layout Plain Layout
3374 The following dead keys are supported (shortcut name is in parentheses):
3377 \begin_layout Quotation
3381 \begin_inset space \hfill{}
3387 \begin_layout Quotation
3389 \begin_inset space \hfill{}
3395 \begin_layout Quotation
3397 \begin_inset space \hfill{}
3403 \begin_layout Quotation
3405 \begin_inset space \hfill{}
3411 \begin_layout Quotation
3413 \begin_inset space \hfill{}
3419 \begin_layout Quotation
3421 \begin_inset space \hfill{}
3428 \begin_layout Plain Layout
3440 \begin_layout Quotation
3442 \begin_inset space \hfill{}
3448 \begin_layout Quotation
3450 \begin_inset space \hfill{}
3457 \begin_layout Plain Layout
3469 \begin_layout Quotation
3471 \begin_inset space \hfill{}
3477 \begin_layout Quotation
3479 \begin_inset space \hfill{}
3485 \begin_layout Quotation
3487 \begin_inset space \hfill{}
3494 \begin_layout Plain Layout
3506 \begin_layout Quotation
3508 \begin_inset space \hfill{}
3515 \begin_layout Plain Layout
3527 \begin_layout Quotation
3529 \begin_inset space \hfill{}
3535 \begin_layout Quotation
3536 hungarian umlaut (hug)
3537 \begin_inset space \hfill{}
3543 \begin_layout Quotation
3545 \begin_inset space \hfill{}
3551 \begin_layout Quotation
3553 \begin_inset space \hfill{}
3560 \begin_layout Plain Layout
3572 \begin_layout Standard
3573 Since in many international keyboards there are exceptions to what some
3574 dead keys should do, you can define them using
3577 \begin_layout Quotation
3578 \begin_inset Flex CharStyle:Code
3581 \begin_layout Plain Layout
3589 deadkey key outstring
3592 \begin_layout Standard
3593 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3597 \begin_layout Quotation
3598 \begin_inset Flex CharStyle:Code
3601 \begin_layout Plain Layout
3614 \begin_layout Standard
3615 to make it work correctly.
3616 Also, you have to define as exceptions dead keys over i and j, to remove
3617 the dot from them before inserting an accent mark.
3618 I will change this when the time comes, but so far I haven't had time.
3621 \begin_layout Standard
3622 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3625 \begin_inset Flex CharStyle:Code
3628 \begin_layout Plain Layout
3634 have different meaning.
3636 \begin_inset Flex CharStyle:Code
3639 \begin_layout Plain Layout
3645 marks comments, quotes start and end LaTeX-style commands.
3646 To enter quote, you'll need to use
3647 \begin_inset Flex CharStyle:Code
3650 \begin_layout Plain Layout
3659 \begin_inset Flex CharStyle:Code
3662 \begin_layout Plain Layout
3669 \begin_inset Flex CharStyle:Code
3672 \begin_layout Plain Layout
3683 \begin_layout Standard
3684 If you make a keyboard description file that works for your language, please
3685 mail it to me, so I can include it in the next keymap distribution.
3688 \begin_layout Standard
3689 More keywords will be supported in keymap configuration file in future,
3693 \begin_layout Itemize
3694 \begin_inset Flex CharStyle:Code
3697 \begin_layout Plain Layout
3708 \begin_inset space \hfill{}
3712 \begin_inset Flex CharStyle:Code
3715 \begin_layout Plain Layout
3724 \begin_layout Itemize
3725 \begin_inset Flex CharStyle:Code
3728 \begin_layout Plain Layout
3739 \begin_inset space \hfill{}
3743 \begin_inset Flex CharStyle:Code
3746 \begin_layout Plain Layout
3752 an external keymap translation program
3755 \begin_layout Standard
3756 Also, it should look into
3757 \begin_inset Flex CharStyle:Code
3760 \begin_layout Plain Layout
3766 file for defaults, too (for example, a
3767 \begin_inset Flex CharStyle:Code
3770 \begin_layout Plain Layout
3778 option to include default keyboard).
3786 \begin_layout Section
3787 \begin_inset CommandInset label
3793 International Keymap Stuff
3796 \begin_layout Standard
3797 \begin_inset Note Note
3800 \begin_layout Plain Layout
3801 In doing the revisions on this document in March 2008, I did not look over
3802 this stuff, as I do not understand it.
3803 It would be good if someone else could do so.
3812 \begin_layout Standard
3813 The next two sections describe the
3814 \begin_inset Flex CharStyle:Code
3817 \begin_layout Plain Layout
3826 \begin_inset Flex CharStyle:Code
3829 \begin_layout Plain Layout
3837 file syntax in detail.
3838 These sections should help you design your own key map if the ones provided
3839 do not meet your needs.
3842 \begin_layout Subsection
3846 \begin_layout Standard
3850 \begin_inset Flex CharStyle:Code
3853 \begin_layout Plain Layout
3859 file maps keystrokes to characters or strings.
3860 As the name suggests, it sets a keyboard mapping.
3862 \begin_inset Flex CharStyle:Code
3865 \begin_layout Plain Layout
3876 \begin_inset Flex CharStyle:Code
3879 \begin_layout Plain Layout
3894 \begin_inset Flex CharStyle:Code
3897 \begin_layout Plain Layout
3910 \begin_inset Flex CharStyle:Code
3913 \begin_layout Plain Layout
3922 \begin_inset Flex CharStyle:Code
3925 \begin_layout Plain Layout
3933 are described in this section.
3936 \begin_layout Labeling
3937 \labelwidthstring 00.00.0000
3938 \begin_inset Flex CharStyle:Code
3941 \begin_layout Plain Layout
3949 Map a character to a string
3952 \begin_layout LyX-Code
3967 \begin_layout Standard
4000 the double-quote (")
4017 must be escaped with a preceding backslash (
4028 \begin_layout Standard
4030 \begin_inset Flex CharStyle:MenuItem
4033 \begin_layout Plain Layout
4041 statement to cause the symbol
4042 \begin_inset Flex CharStyle:MenuItem
4045 \begin_layout Plain Layout
4053 to be output for the keystroke
4054 \begin_inset Flex CharStyle:MenuItem
4057 \begin_layout Plain Layout
4068 \begin_layout LyX-Code
4074 \begin_layout Labeling
4075 \labelwidthstring 00.00.0000
4076 \begin_inset Flex CharStyle:Code
4079 \begin_layout Plain Layout
4087 Specify an accent character
4090 \begin_layout LyX-Code
4099 \begin_layout Standard
4100 This will make the cha
4138 This is the dead key
4142 \begin_layout Plain Layout
4149 refers to a key that does not produce a character by itself, but when followed
4150 with another key, produces the desired accent character.
4151 For example, a German characte
4153 r with an umlaut like
4163 can be produced in this manner.
4172 \begin_layout Standard
4185 and then another key not in
4202 followed by the other, not allowed key, as output.
4206 \begin_inset Flex CharStyle:MenuItem
4209 \begin_layout Plain Layout
4217 cancels a dead key, so if
4228 \begin_inset Flex CharStyle:MenuItem
4231 \begin_layout Plain Layout
4240 , the cursor will not go one position backwards but will instead cancel
4256 might have had on the next keystroke.
4260 \begin_layout Standard
4261 The following example specifies that the character ' is to be an acute accent,
4262 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4265 \begin_layout LyX-Code
4268 kmod ' acute aeiouAEIOU
4271 \begin_layout Labeling
4272 \labelwidthstring 00.00.0000
4273 \begin_inset Flex CharStyle:Code
4276 \begin_layout Plain Layout
4282 Specify an exception to the accent character
4285 \begin_layout LyX-Code
4294 \begin_layout Standard
4295 This defines an exce
4336 have been assigned a keystroke with a previous
4339 \begin_inset Flex CharStyle:Code
4342 \begin_layout Plain Layout
4366 must not belong in the
4413 If such a declaration does not exist in
4421 \begin_inset Flex CharStyle:Code
4424 \begin_layout Plain Layout
4458 \begin_inset Flex CharStyle:Code
4461 \begin_layout Plain Layout
4475 \begin_layout Standard
4476 The following command produces causes äi to be produced when you enter acute-i
4480 \begin_layout LyX-Code
4494 \begin_layout Labeling
4495 \labelwidthstring 00.00.0000
4496 \begin_inset Flex CharStyle:Code
4499 \begin_layout Plain Layout
4505 Combine two accent characters
4508 \begin_layout LyX-Code
4514 accent1 accent2 allowed
4517 \begin_layout Standard
4518 This one is getting pretty esoteric.
4519 It allows you to combine the effect
4575 \begin_inset Flex CharStyle:Code
4578 \begin_layout Plain Layout
4606 \begin_layout Standard
4607 Consider this example from the
4608 \begin_inset Flex CharStyle:Code
4611 \begin_layout Plain Layout
4622 \begin_layout LyX-Code
4625 kmod ; acute aeioyvhAEIOYVH
4629 kcomb acute umlaut iyIY
4632 \begin_layout Standard
4633 This allows you to press
4634 \begin_inset Flex CharStyle:MenuItem
4637 \begin_layout Plain Layout
4645 and get the effect of
4646 \begin_inset Flex CharStyle:Code
4649 \begin_layout Plain Layout
4668 in this case cancels the last dead key, so if you press
4669 \begin_inset Flex CharStyle:MenuItem
4672 \begin_layout Plain Layout
4681 \begin_inset Flex CharStyle:Code
4684 \begin_layout Plain Layout
4697 \begin_layout Subsection
4701 \begin_layout Standard
4703 \begin_inset Flex CharStyle:Code
4706 \begin_layout Plain Layout
4714 mapping is performed, a
4715 \begin_inset Flex CharStyle:Code
4718 \begin_layout Plain Layout
4728 file maps the strings that the symbols generate to characters in the current
4730 The LyX distribution currently includes at least the
4731 \begin_inset Flex CharStyle:Code
4734 \begin_layout Plain Layout
4743 \begin_inset Flex CharStyle:Code
4746 \begin_layout Plain Layout
4757 \begin_layout Standard
4759 \begin_inset Flex CharStyle:Code
4762 \begin_layout Plain Layout
4770 file is a sequence of declarations of the form
4773 \begin_layout LyX-Code
4786 \begin_layout Standard
4787 For example, in order to map
4788 \begin_inset Flex CharStyle:MenuItem
4791 \begin_layout Plain Layout
4801 to the corresponding character in the iso-8859-1 set (233), the following
4805 \begin_layout LyX-Code
4813 \begin_layout Standard
4815 \begin_inset Flex CharStyle:Code
4818 \begin_layout Plain Layout
4827 \begin_inset Flex CharStyle:Code
4830 \begin_layout Plain Layout
4848 the same character can apply to more than one string.
4850 \begin_inset Flex CharStyle:Code
4853 \begin_layout Plain Layout
4864 \begin_layout LyX-Code
4876 \begin_inset Newline newline
4892 \begin_layout Standard
4893 If LyX cannot find a mapping for the string produced by the keystroke or
4894 a deadkey sequence, it will check if it looks like an accented char and
4895 try to draw an accent over the character on screen.
4898 \begin_layout Subsection
4902 \begin_layout Standard
4903 There is a second way to add support for international characters through
4904 so-called dead-keys.
4905 A dead-key works in combination with a letter to produce an accented character.
4906 Here, we'll explain how to create a really simple dead-key to illustrate
4910 \begin_layout Standard
4911 Suppose you happen to need the circumflex character,
4912 \begin_inset Quotes eld
4916 \begin_inset Quotes erd
4921 \begin_inset Flex CharStyle:MenuItem
4924 \begin_layout Plain Layout
4931 \begin_inset space ~
4935 \begin_inset Flex CharStyle:MenuItem
4938 \begin_layout Plain Layout
4944 ] to the LyX command
4945 \begin_inset Flex CharStyle:Code
4948 \begin_layout Plain Layout
4955 \begin_inset Flex CharStyle:Code
4958 \begin_layout Plain Layout
4965 Now, whenever you type the
4966 \begin_inset Flex CharStyle:MenuItem
4969 \begin_layout Plain Layout
4975 -key followed by a letter, that letter will have a circumflex accent on
4977 For example, the sequence
4978 \begin_inset Quotes eld
4982 \begin_inset Flex CharStyle:MenuItem
4985 \begin_layout Plain Layout
4992 \begin_inset Quotes erd
4995 produces the letter:
4996 \begin_inset Quotes eld
5000 \begin_inset Quotes erd
5004 If you tried to type
5005 \begin_inset Quotes eld
5009 \begin_inset Flex CharStyle:MenuItem
5012 \begin_layout Plain Layout
5019 \begin_inset Quotes erd
5022 , however, LyX will complain with a beep, since a
5023 \begin_inset Quotes eld
5027 \begin_inset Flex CharStyle:MenuItem
5030 \begin_layout Plain Layout
5037 \begin_inset Quotes erd
5040 never takes a circumflex accent.
5042 \begin_inset Flex CharStyle:MenuItem
5045 \begin_layout Plain Layout
5051 after a dead-key produces the bare-accent.
5052 Please note this last point! If you bind a key to a dead-key, you'll need
5053 to rebind the character on that key to yet another key.
5055 \begin_inset Flex CharStyle:MenuItem
5058 \begin_layout Plain Layout
5064 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5067 \begin_layout Standard
5068 One common way to bind dead-keys is to use
5069 \begin_inset Flex CharStyle:MenuItem
5072 \begin_layout Plain Layout
5079 \begin_inset Flex CharStyle:MenuItem
5082 \begin_layout Plain Layout
5089 \begin_inset Flex CharStyle:MenuItem
5092 \begin_layout Plain Layout
5098 in combination with an accent, like
5099 \begin_inset Quotes eld
5103 \begin_inset Flex CharStyle:MenuItem
5106 \begin_layout Plain Layout
5113 \begin_inset Quotes erd
5117 \begin_inset Quotes eld
5121 \begin_inset Flex CharStyle:MenuItem
5124 \begin_layout Plain Layout
5131 \begin_inset Quotes erd
5135 \begin_inset Quotes eld
5139 \begin_inset Flex CharStyle:MenuItem
5142 \begin_layout Plain Layout
5149 \begin_inset Quotes erd
5153 Another way involves using
5154 \begin_inset Flex CharStyle:Code
5157 \begin_layout Plain Layout
5164 \begin_inset Flex CharStyle:Code
5167 \begin_layout Plain Layout
5173 to set up the special
5174 \begin_inset Flex CharStyle:Code
5177 \begin_layout Plain Layout
5185 \begin_inset Flex CharStyle:Code
5188 \begin_layout Plain Layout
5194 acts in some ways just like
5195 \begin_inset Flex CharStyle:MenuItem
5198 \begin_layout Plain Layout
5204 and permits you to bind keys to accented characters.
5205 You can also turn keys into dead-keys by binding them to something like
5207 \begin_inset Flex CharStyle:Code
5210 \begin_layout Plain Layout
5216 and then binding this symbolic key to the corresponding LyX command.
5220 \begin_layout Plain Layout
5225 : This is exactly what I do in my
5226 \begin_inset Flex CharStyle:Code
5229 \begin_layout Plain Layout
5236 \begin_inset Flex CharStyle:Code
5239 \begin_layout Plain Layout
5247 \begin_inset Flex CharStyle:MenuItem
5250 \begin_layout Plain Layout
5252 \begin_inset space ~
5261 \begin_inset Flex CharStyle:Code
5264 \begin_layout Plain Layout
5270 and a bunch of these
5271 \begin_inset Quotes eld
5275 \begin_inset Flex CharStyle:Code
5278 \begin_layout Plain Layout
5285 \begin_inset Quotes erd
5288 symbolic keys bound such things as
5289 \begin_inset Flex CharStyle:MenuItem
5292 \begin_layout Plain Layout
5294 \begin_inset space ~
5303 \begin_inset Flex CharStyle:MenuItem
5306 \begin_layout Plain Layout
5308 \begin_inset space ~
5317 This is how I produce my accented characters.
5322 You can make just about anything into the
5323 \begin_inset Flex CharStyle:Code
5326 \begin_layout Plain Layout
5333 \begin_inset Flex CharStyle:MenuItem
5336 \begin_layout Plain Layout
5342 keys, a spare function key, etc.
5343 As for the LyX commands that produce accents, check the entry for
5344 \begin_inset Flex CharStyle:Code
5347 \begin_layout Plain Layout
5358 You'll find the complete list there.
5361 \begin_layout Subsection
5362 Saving your Language Configuration
5365 \begin_layout Standard
5366 You can edit your preferences so that your desired language environment
5367 is automatically configured when LyX starts up, via the
5368 \begin_inset Flex CharStyle:MenuItem
5371 \begin_layout Plain Layout
5372 Edit\SpecialChar \menuseparator
5381 \begin_layout Chapter
5382 Installing New Document Classes, Layouts, and Templates
5383 \begin_inset CommandInset label
5385 name "chap:textclass"
5393 \begin_layout Plain Layout
5394 Installing New Document Classes
5402 \begin_layout Standard
5403 In this chapter, we describe the procedures for creating and installing
5404 new LyX layout and template files, as well as offer a refresher on correctly
5405 installing new LaTeX document classes.
5406 Some definitions: a document class is a LaTeX file (usually ending in
5407 \begin_inset Flex CharStyle:Code
5410 \begin_layout Plain Layout
5417 \begin_inset Flex CharStyle:Code
5420 \begin_layout Plain Layout
5426 ) that describes the format of a document such as an article, report, journal
5427 preprint, etc, and all the commands needed to realize that format.
5428 A layout file is a LyX file that corresponds to a LaTeX document class
5429 and that tells LyX how to
5430 \begin_inset Quotes eld
5434 \begin_inset Quotes erd
5437 things on the screen to make the display look something like the final
5439 More precisely, a layout file describes a
5440 \begin_inset Quotes eld
5444 \begin_inset Quotes erd
5447 which is the internal construct LyX uses to render the screen display.
5449 \begin_inset Quotes eld
5453 \begin_inset Quotes erd
5457 \begin_inset Quotes eld
5461 \begin_inset Quotes erd
5464 can be used somewhat interchangeably, but it is better to refer to the
5465 file as the layout, and the thing living in LyX's memory as the text class.
5466 A template file is simply a LyX document that contains a set of predefined
5467 entries for a given document class—entries that are generally required
5469 Templates are especially useful for things like journal manuscripts that
5470 are to be submitted electronically.
5473 \begin_layout Section
5474 Installing a new LaTeX package
5477 \begin_layout Standard
5478 Some installations may not include a LaTeX package that you would like to
5480 For example, you might need FoilTeX, a package for preparing slides or
5481 viewgraphs for overhead projectors.
5482 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5483 a user interface for that.
5484 For example on MiKTeX you start its program
5485 \begin_inset Quotes eld
5489 \begin_inset Quotes erd
5492 to get a list of available packages.
5493 To install one, right click on it or use the installing toolbar button.
5494 When the package you want to install is not in the list, but you have it
5496 \begin_inset Flex CharStyle:Code
5499 \begin_layout Plain Layout
5506 \begin_inset Flex CharStyle:Code
5509 \begin_layout Plain Layout
5515 -file, then copy these files to a subfolder of your LaTeX distribution,
5516 for example to the folder
5525 Then update the file name database of your LaTeX-distribution.
5526 For example on MiKTeX this is done by pressing the button
5529 \begin_inset space ~
5534 that you find in MiKTeX's
5535 \begin_inset Quotes eld
5539 \begin_inset Quotes erd
5543 In both cases you need afterwards to reconfigure LyX using the menu
5544 \begin_inset Flex CharStyle:MenuItem
5547 \begin_layout Plain Layout
5548 Tools\SpecialChar \menuseparator
5554 and then to restart LyX.
5557 \begin_layout Standard
5558 If your LaTeX distribution doesn't provide a user interface, then you can
5559 follow these steps by using a UNIX/Linux console.
5562 \begin_layout Enumerate
5563 Get the package from
5564 \begin_inset CommandInset href
5567 target "http://www.ctan.org/"
5574 \begin_layout Enumerate
5575 You can install this package in several different places.
5576 If you want it to be available for all users on your system, then you should
5577 install it in your `local' TeX tree; if you want (or need) it to be available
5578 just for you, then you can install it in your own `user' TeX tree.
5579 Where these should be created, if they do not already exist, depends upon
5580 the details of your system.
5581 To find out, look in the file
5582 \begin_inset Flex CharStyle:Code
5585 \begin_layout Plain Layout
5595 \begin_layout Plain Layout
5596 This usually lives in the directory
5597 \begin_inset Flex CharStyle:Code
5600 \begin_layout Plain Layout
5606 , though you can run
5607 \begin_inset Flex CharStyle:Code
5610 \begin_layout Plain Layout
5621 The location of the `local' TeX tree is defined by
5622 \begin_inset Flex CharStyle:Code
5625 \begin_layout Plain Layout
5631 ; this is usually somewhere like
5632 \begin_inset Flex CharStyle:Code
5635 \begin_layout Plain Layout
5636 /usr/local/share/texmf/
5642 The `user' TeX tree is defined by
5643 \begin_inset Flex CharStyle:Code
5646 \begin_layout Plain Layout
5653 \begin_inset Flex CharStyle:Code
5656 \begin_layout Plain Layout
5663 (If these variables are not predefined, you can define them.) You'll probably
5664 need root permissions to create or modify the `local' tree; but your `user'
5665 tree shouldn't have such limitations.
5668 \begin_layout Enumerate
5670 \begin_inset Flex CharStyle:Code
5673 \begin_layout Plain Layout
5680 \begin_inset Flex CharStyle:Code
5683 \begin_layout Plain Layout
5690 \begin_inset Flex CharStyle:Code
5693 \begin_layout Plain Layout
5700 \begin_inset space \thinspace{}
5704 \begin_inset Newline newline
5708 \begin_inset Flex CharStyle:Code
5711 \begin_layout Plain Layout
5712 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5718 \begin_inset Newline newline
5721 But, again, most of this will
5722 \begin_inset Quotes eld
5726 \begin_inset Quotes erd
5732 \begin_layout Enumerate
5737 \begin_layout Plain Layout
5738 We'll assume henceforth that you're defining `local' TeX tree.
5739 If you're defining a user tree, just adjust as necessary.
5745 You must follow the directory structure of your existing
5746 \begin_inset Flex CharStyle:Code
5749 \begin_layout Plain Layout
5755 directory, which will be found at
5756 \begin_inset Flex CharStyle:Code
5759 \begin_layout Plain Layout
5766 For example, latex packages should go under
5767 \begin_inset Flex CharStyle:Code
5770 \begin_layout Plain Layout
5771 $TEXMFLOCAL/tex/latex/
5779 \begin_layout Enumerate
5780 Install the package.
5781 For example, you would unpack the FoilTeX tarball and copy it to
5782 \begin_inset Flex CharStyle:Code
5785 \begin_layout Plain Layout
5786 $TEXMFLOCAL/tex/latex/foiltex
5793 \begin_inset Flex CharStyle:Code
5796 \begin_layout Plain Layout
5802 directory contains various files.
5805 \begin_layout Enumerate
5807 \begin_inset Flex CharStyle:Code
5810 \begin_layout Plain Layout
5818 \begin_inset Flex CharStyle:Code
5821 \begin_layout Plain Layout
5830 \begin_layout Standard
5831 Your package is now installed and available to LaTeX.
5832 To make it available to LyX, you need to create a Layout file, if one is
5833 not already available.
5834 (See the next section.) Once you have a layout file, you need only reconfigure
5836 \begin_inset Flex CharStyle:MenuItem
5839 \begin_layout Plain Layout
5840 Tools\SpecialChar \menuseparator
5846 ) and then restart LyX.
5847 You should then see your new package—for example
5848 \begin_inset Flex CharStyle:MenuItem
5851 \begin_layout Plain Layout
5858 \begin_inset Flex CharStyle:MenuItem
5861 \begin_layout Plain Layout
5862 Document\SpecialChar \menuseparator
5869 \begin_inset Flex CharStyle:MenuItem
5872 \begin_layout Plain Layout
5882 \begin_layout Section
5886 \begin_layout Standard
5887 This section describes how to write and install your own LyX layout files
5888 and walks through the
5889 \begin_inset Flex CharStyle:Code
5892 \begin_layout Plain Layout
5898 text class format as an example.
5900 \begin_inset Flex CharStyle:Code
5903 \begin_layout Plain Layout
5909 files describe what paragraph and character styles are available for a
5910 given document class and how LyX should display them.
5911 We try to provide a thorough description of the process here; however,
5912 there are so many different types of documents supported by LaTeX classes
5913 that we can't hope to cover every different possibility or problem you
5915 (The LyX users' list is frequented by people with lots of experience with
5916 layout design who are willing to share what they've learned.)
5919 \begin_layout Standard
5920 As you prepare to write a new layout, it is extremely helpful to look at
5921 the example layouts distributed with LyX.
5922 If you use a nice LaTeX document class that might be of interest for others,
5923 too, and have a nice corresponding LyX layout, feel free to contribute
5924 the stuff to us, so we may put it into the distribution.
5926 \begin_inset CommandInset href
5928 name "section on the LyX wiki"
5929 target "http://wiki.lyx.org/Layouts/Layouts"
5933 for this kind of material.
5936 \begin_layout Standard
5937 All the tags described in this chapter are case-insensitive; this means
5939 \begin_inset Flex CharStyle:Code
5942 \begin_layout Plain Layout
5949 \begin_inset Flex CharStyle:Code
5952 \begin_layout Plain Layout
5959 \begin_inset Flex CharStyle:Code
5962 \begin_layout Plain Layout
5968 are really the same command.
5969 The possible values are printed in brackets after the feature's name.
5970 The default value if a feature isn't specified inside a text class-description
5972 \begin_inset Flex CharStyle:Code
5975 \begin_layout Plain Layout
5984 If the argument has a data type like
5985 \begin_inset Quotes eld
5989 \begin_inset Quotes erd
5993 \begin_inset Quotes eld
5997 \begin_inset Quotes erd
6000 , the default is shown like this:
6001 \begin_inset Flex CharStyle:Code
6004 \begin_layout Plain Layout
6015 \begin_layout Subsection
6016 \begin_inset CommandInset label
6018 name "sub:Layout-modules"
6025 \begin_layout Standard
6026 Similar to layout files, and new with LyX 1.6, are layout
6031 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6032 some modules—such as the endnotes module—provide support for just such
6034 In a sense, layout modules are similar to included files—files like
6035 \begin_inset Flex CharStyle:Code
6038 \begin_layout Plain Layout
6044 —in that modules are not specific to a given document layout but may be
6045 used with many different layouts.
6046 The difference is that using a layout module does not require editing the
6048 Rather, modules are selected in the
6049 \begin_inset Flex CharStyle:MenuItem
6052 \begin_layout Plain Layout
6053 Document\SpecialChar \menuseparator
6062 \begin_layout Standard
6063 Building modules is the easiest way to get started with layout editing,
6064 since it can be as simple as adding a single new paragraph or flex inset.
6065 But modules may, in principle, contain anything a layout file can contain.
6068 \begin_layout Standard
6069 A module must begin with a line like the following:
6072 \begin_layout LyX-Code
6075 DeclareLyXModule[endnotes.sty]{Endnotes}
6078 \begin_layout Standard
6079 The argument in square brackets is optional: It declares any LaTeX packages
6080 on which the module depends.
6081 The mandatory argument, in curly brackets, is the name of the module, as
6083 \begin_inset Flex CharStyle:MenuItem
6086 \begin_layout Plain Layout
6087 Document\SpecialChar \menuseparator
6097 \begin_layout Standard
6098 The module declaration should then be followed by lines like the following:
6101 \begin_layout LyX-Code
6105 \begin_layout LyX-Code
6106 #Adds an endnote command, in addition to footnotes.
6110 \begin_layout LyX-Code
6111 #You will need to add
6113 theendnotes in TeX code where you
6116 \begin_layout LyX-Code
6117 #want the endnotes to appear.
6121 \begin_layout LyX-Code
6125 \begin_layout LyX-Code
6126 #Requires: somemodule | othermodule
6129 \begin_layout LyX-Code
6130 #Excludes: badmodule
6133 \begin_layout Standard
6134 The description is used in
6135 \begin_inset Flex CharStyle:MenuItem
6138 \begin_layout Plain Layout
6139 Document\SpecialChar \menuseparator
6145 to provide the user with information about what the module does.
6147 \begin_inset Flex CharStyle:Code
6150 \begin_layout Plain Layout
6156 line is used to identify other modules with which this one must be used;
6158 \begin_inset Flex CharStyle:Code
6161 \begin_layout Plain Layout
6167 line is used to identify modules with which this one may not be used.
6168 Both are optional, and, as shown, multiple modules should be separated
6169 with the pipe symbol: |.
6170 Note that the required modules are treated disjunctively:
6174 of the required modules must be used.
6179 excluded module may be used.
6180 Note that modules are identified here by their
6184 without the .module extension.
6186 \begin_inset Flex CharStyle:Code
6189 \begin_layout Plain Layout
6196 \begin_inset Flex CharStyle:Code
6199 \begin_layout Plain Layout
6208 \begin_layout Standard
6209 After creating a new module, you will need to reconfigure and then restart
6210 LyX for the module to appear in the menu.
6211 However, changes you make to the module will be seen immediately, if you
6213 \begin_inset Flex CharStyle:MenuItem
6216 \begin_layout Plain Layout
6217 Document\SpecialChar \menuseparator
6223 , highlight something, and then hit
6224 \begin_inset Quotes eld
6228 \begin_inset Quotes erd
6234 It is strongly recommended that you save your work before doing so
6239 it is strongly recommended that you not attempt to edit modules while simultaneo
6240 usly working on documents
6243 Though of course the developers strive to keep LyX stable in such situations,
6244 syntax errors and the like in your module file could cause strange behavior.
6247 \begin_layout Subsection
6248 Supporting new document classes
6251 \begin_layout Standard
6252 There are two situations you are likely to encounter when wanting to support
6253 a new LaTeX document class, involving LaTeX2e class (
6254 \begin_inset Flex CharStyle:Code
6257 \begin_layout Plain Layout
6264 \begin_inset Flex CharStyle:Code
6267 \begin_layout Plain Layout
6274 Supporting a style file is usually fairly easy.
6275 Supporting a new document class is a bit harder.
6278 \begin_layout Subsection
6280 \begin_inset Flex CharStyle:MenuItem
6283 \begin_layout Plain Layout
6292 \begin_layout Standard
6293 If your new document class is provided as a style file that is used in conjuncti
6294 on with an existing, supported document class—for the sake of the example,
6295 we'll assume that the style file is called
6296 \begin_inset Flex CharStyle:MenuItem
6299 \begin_layout Plain Layout
6305 and it is meant to be used with
6306 \begin_inset Flex CharStyle:MenuItem
6309 \begin_layout Plain Layout
6315 , which is a standard class—start by copying the existing class's layout
6316 file into your local directory:
6319 \begin_layout LyX-Code
6320 cp report.layout ~/.lyx/layouts/myclass.layout
6323 \begin_layout Standard
6325 \begin_inset Flex CharStyle:Code
6328 \begin_layout Plain Layout
6334 and change the line:
6337 \begin_layout LyX-Code
6340 DeclareLaTeXClass{report}
6343 \begin_layout Standard
6347 \begin_layout LyX-Code
6350 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6353 \begin_layout Standard
6357 \begin_layout LyX-Code
6359 \begin_inset Newline newline
6365 \begin_inset Newline newline
6371 \begin_layout Standard
6372 near the top of the file.
6375 \begin_layout Standard
6376 Start LyX and select
6377 \begin_inset Flex CharStyle:MenuItem
6380 \begin_layout Plain Layout
6381 Tools\SpecialChar \menuseparator
6388 Then restart LyX and try creating a new document.
6390 \begin_inset Flex CharStyle:MenuItem
6393 \begin_layout Plain Layout
6399 " as a document class option in the
6400 \begin_inset Flex CharStyle:MenuItem
6403 \begin_layout Plain Layout
6404 Document\SpecialChar \menuseparator
6411 It is likely that some of the sectioning commands and such in your new
6412 class will work differently from how they worked in the base class—
6413 \begin_inset Flex CharStyle:Code
6416 \begin_layout Plain Layout
6422 in this example—so you can fiddle around with the settings for the different
6423 sections if you wish.
6426 \begin_layout Subsection
6428 \begin_inset Flex CharStyle:MenuItem
6431 \begin_layout Plain Layout
6440 \begin_layout Standard
6441 There are two possibilities here.
6442 One is that the class file is itself based upon an existing document class.
6443 For example, many thesis classes are based upon
6444 \begin_inset Flex CharStyle:MenuItem
6447 \begin_layout Plain Layout
6454 To see whether yours is, look for a line like
6457 \begin_layout LyX-Code
6463 \begin_layout Standard
6465 If so, then you may proceed largely as in the previous section, though
6466 the DeclareLaTeXClass line will be different.
6467 If your new class is thesis, and it is based upon book, then the line should
6472 \begin_layout Plain Layout
6473 And it will be easiest if you save the file to
6474 \begin_inset Flex CharStyle:Code
6477 \begin_layout Plain Layout
6483 : LyX assumes that the document class has the same name as the layout file.
6492 \begin_layout LyX-Code
6495 DeclareLaTeXClass[thesis,book]{thesis}
6498 \begin_layout Standard
6499 If, on the other hand, the new class is not based upon an existing class,
6500 you will probably have to
6501 \begin_inset Quotes eld
6505 \begin_inset Quotes erd
6509 We strongly suggest copying an existing layout file which uses a similar
6510 LaTeX class and then modifying it, if you can do so.
6511 At least use an existing file as a starting point so you can find out what
6512 items you need to worry about.
6513 Again, the specifics are covered below.
6516 \begin_layout Section
6517 Declaring a new text class
6520 \begin_layout Standard
6521 When it's finally time to get your hands dirty and create or edit your own
6522 layout file, the following sections describe what you're up against.
6523 Our advice is to go slowly, save and test often, listen to soothing music,
6524 and enjoy one or two of your favorite adult beverages; more if you are
6525 getting particularly stuck.
6526 It's really not that hard, except that the multitude of options can become
6527 overwhelming if you try to do to much in one sitting.
6528 Go have another adult beverage, just for good measure.
6531 \begin_layout Standard
6535 \begin_layout Standard
6536 Lines in a layout file which begin with a
6537 \begin_inset Flex CharStyle:Code
6540 \begin_layout Plain Layout
6547 There is one exception to this rule: all layouts should begin with lines
6551 \begin_layout LyX-Code
6554 #% Do not delete the line below; configure depends on this
6557 \begin_layout LyX-Code
6562 DeclareLaTeXClass{article}
6565 \begin_layout Standard
6566 The second line is used when you configure LyX.
6567 The layout file is read by the LaTeX script
6568 \begin_inset Flex CharStyle:Code
6571 \begin_layout Plain Layout
6577 , in a special mode where
6578 \begin_inset Flex CharStyle:Code
6581 \begin_layout Plain Layout
6588 The first line is just a LaTeX comment, and the second one contains the
6589 declaration of the text class.
6590 If these lines appear in a file named
6591 \begin_inset Flex CharStyle:Code
6594 \begin_layout Plain Layout
6600 , then they define a text class of name
6601 \begin_inset Flex CharStyle:Code
6604 \begin_layout Plain Layout
6610 (the name of the layout file) which uses the LaTeX document class
6611 \begin_inset Flex CharStyle:Code
6614 \begin_layout Plain Layout
6620 (the default is to use the same name as the layout).
6622 \begin_inset Quotes eld
6626 \begin_inset Quotes erd
6629 that appears above is used as a description of the text class in the
6630 \begin_inset Flex CharStyle:MenuItem
6633 \begin_layout Plain Layout
6634 Document\SpecialChar \menuseparator
6643 \begin_layout Standard
6644 Let's assume that you wrote your own text class that uses the
6645 \begin_inset Flex CharStyle:Code
6648 \begin_layout Plain Layout
6654 document class, but where you changed the appearance of the section headings.
6655 If you put it in a file
6656 \begin_inset Flex CharStyle:Code
6659 \begin_layout Plain Layout
6665 , the header of this file should be:
6668 \begin_layout LyX-Code
6671 #% Do not delete the line below; configure depends on this
6674 \begin_layout LyX-Code
6679 DeclareLaTeXClass[article]{article (with my own headings)}
6682 \begin_layout Standard
6683 This declares a text class
6684 \begin_inset Flex CharStyle:Code
6687 \begin_layout Plain Layout
6693 , associated with the LaTeX document class
6694 \begin_inset Flex CharStyle:Code
6697 \begin_layout Plain Layout
6704 \begin_inset Quotes eld
6707 article (with my own headings)
6708 \begin_inset Quotes erd
6712 If your text class depends on several packages, you can declare it as:
6715 \begin_layout LyX-Code
6718 #% Do not delete the line below; configure depends on this
6721 \begin_layout LyX-Code
6726 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6729 \begin_layout Standard
6730 This indicates that your text class uses the foo.sty package.
6731 Finally, it is also possible to declare classes for DocBook code.
6732 Typical declarations will look like
6735 \begin_layout LyX-Code
6738 #% Do not delete the line below; configure depends on this
6741 \begin_layout LyX-Code
6746 DeclareDocBookClass[article]{SGML (DocBook article)}
6749 \begin_layout Standard
6750 Note that these declarations can also be given an optional parameter declaring
6751 the name of the document class (but not a list).
6754 \begin_layout Standard
6755 So, to be as explicit as possible, the form of the layout declaration is:
6758 \begin_layout LyX-Code
6763 DeclareLaTeXClass[class,package.sty]{layout description}
6766 \begin_layout Standard
6767 The class need only be specified if the name of the LaTeX class file and
6768 the name of the layout file are different; if the name of the class file
6769 is not specified, then LyX will simply assume that it is the same as the
6770 name of the layout file.
6773 \begin_layout Standard
6774 When the text class has been modified to your taste, all you have to do
6775 is to copy it either to
6776 \begin_inset Flex CharStyle:Code
6779 \begin_layout Plain Layout
6786 \begin_inset Flex CharStyle:Code
6789 \begin_layout Plain Layout
6796 \begin_inset Flex CharStyle:MenuItem
6799 \begin_layout Plain Layout
6800 Tools\SpecialChar \menuseparator
6806 , exit LyX and restart it.
6807 Then your new text class should be available along with the others.
6810 \begin_layout Standard
6811 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6812 you made to your layout files.
6813 As a result, editing layout files could be very time consuming.
6814 Beginning with 1.6, however, you can force a reload of the layout currently
6815 in use by using the LyX function
6816 \begin_inset Flex CharStyle:MenuItem
6819 \begin_layout Plain Layout
6826 There is no default binding for this function—though, of course, you can
6827 bind it to a key yourself.
6828 If you want to use this function, then, you should simply enter it in the
6834 : This is very much an `advanced feature'.
6839 recommended that you save your work before using this function.
6844 recommended that you not attempt to edit your layout while simultaneously
6845 working on a document that you care about.
6846 Use a test document.
6847 Syntax errors and the like in your layout file could cause peculiar behavior.
6848 In particular, such errors could cause LyX to regard the current layout
6849 as invalid and to attempt to switch to some other layout.
6850 The LyX team strives to keep LyX stable in such situations, but safe is
6854 \begin_layout Subsection
6858 \begin_layout Standard
6859 The first non-comment line must contain the file format number:
6862 \begin_layout Description
6863 \begin_inset Flex CharStyle:Code
6866 \begin_layout Plain Layout
6873 \begin_inset Flex CharStyle:Code
6876 \begin_layout Plain Layout
6882 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6883 don't have an explicit file format).
6884 The file format that is documented here is format 12.
6887 \begin_layout Subsection
6888 General text class parameters
6891 \begin_layout Standard
6892 These are the general parameters which describe the form of the entire document:
6895 \begin_layout Description
6896 \begin_inset Flex CharStyle:Code
6899 \begin_layout Plain Layout
6905 Adds information to the document preamble.
6907 \begin_inset Quotes eld
6911 \begin_inset Flex CharStyle:Code
6914 \begin_layout Plain Layout
6921 \begin_inset Quotes erd
6927 \begin_layout Description
6928 \begin_inset Flex CharStyle:Code
6931 \begin_layout Plain Layout
6937 Describes various global options supported by the document class.
6939 \begin_inset space ~
6943 \begin_inset CommandInset ref
6945 reference "sec:classoptions"
6951 \begin_inset Quotes eld
6955 \begin_inset Flex CharStyle:Code
6958 \begin_layout Plain Layout
6965 \begin_inset Quotes erd
6971 \begin_layout Description
6972 \begin_inset Flex CharStyle:Code
6975 \begin_layout Plain Layout
6982 \begin_inset Flex CharStyle:Code
6985 \begin_layout Plain Layout
6994 \begin_inset Flex CharStyle:Code
6997 \begin_layout Plain Layout
7003 ] Whether the class should default to having one or two columns.
7004 Can be changed in the
7005 \begin_inset Flex CharStyle:MenuItem
7008 \begin_layout Plain Layout
7009 Document\SpecialChar \menuseparator
7018 \begin_layout Description
7019 \begin_inset Flex CharStyle:Code
7022 \begin_layout Plain Layout
7028 This sequence defines a new counter.
7030 \begin_inset space ~
7034 \begin_inset CommandInset ref
7036 reference "sec:counter"
7042 \begin_inset Quotes eld
7046 \begin_inset Flex CharStyle:Code
7049 \begin_layout Plain Layout
7056 \begin_inset Quotes erd
7062 \begin_layout Description
7063 \begin_inset Flex CharStyle:Code
7066 \begin_layout Plain Layout
7072 Sets the default font used to display the document.
7074 \begin_inset space ~
7078 \begin_inset CommandInset ref
7080 reference "sec:fonts"
7084 for how to declare fonts.
7086 \begin_inset Quotes eld
7090 \begin_inset Flex CharStyle:Code
7093 \begin_layout Plain Layout
7100 \begin_inset Quotes erd
7106 \begin_layout Description
7107 \begin_inset Flex CharStyle:Code
7110 \begin_layout Plain Layout
7117 \begin_inset Flex CharStyle:Code
7120 \begin_layout Plain Layout
7126 Specifies a module to be included by default with this document class,
7127 which should be specified by filename without the
7128 \begin_inset Flex CharStyle:Code
7131 \begin_layout Plain Layout
7138 The user can still remove the module, but it will be active at the outset.
7139 (This applies only when new files are created, or when this class is chosen
7140 for an existing document.)
7143 \begin_layout Description
7144 \begin_inset Flex CharStyle:Code
7147 \begin_layout Plain Layout
7154 \begin_inset Flex CharStyle:Code
7157 \begin_layout Plain Layout
7163 ] This is the style that will be assigned to new paragraphs, usually
7164 \begin_inset Flex CharStyle:MenuItem
7167 \begin_layout Plain Layout
7174 This will default to the first defined style if not given, but you are
7175 highly encouraged to use this directive.
7178 \begin_layout Description
7179 \begin_inset Flex CharStyle:Code
7182 \begin_layout Plain Layout
7189 \begin_inset Flex CharStyle:Code
7192 \begin_layout Plain Layout
7198 ] Indicates that the module in question—which should be specified by filename
7200 \begin_inset Flex CharStyle:Code
7203 \begin_layout Plain Layout
7209 extension—cannot be used with this document class.
7210 This might be used in a journal-specific layout file to prevent, say, the
7212 \begin_inset Flex CharStyle:Code
7215 \begin_layout Plain Layout
7221 module that numbers theorems by section.
7226 be used in a module.
7227 Modules have their own way of excluding other modules (see
7228 \begin_inset CommandInset ref
7230 reference "sub:Layout-modules"
7237 \begin_layout Description
7238 \begin_inset Flex CharStyle:Code
7241 \begin_layout Plain Layout
7247 Defines a new float.
7249 \begin_inset space ~
7253 \begin_inset CommandInset ref
7255 reference "sec:floats"
7261 \begin_inset Quotes eld
7265 \begin_inset Flex CharStyle:Code
7268 \begin_layout Plain Layout
7275 \begin_inset Quotes erd
7281 \begin_layout Description
7282 \begin_inset Flex CharStyle:Code
7285 \begin_layout Plain Layout
7291 As its name implies, this command allows you to include another layout
7292 definition file within yours to avoid duplicating commands.
7293 Common examples are the standard layout files, for example,
7294 \begin_inset Flex CharStyle:Code
7297 \begin_layout Plain Layout
7303 , which contains most of the basic layouts.
7306 \begin_layout Description
7307 \begin_inset Flex CharStyle:Code
7310 \begin_layout Plain Layout
7316 This section (re-)defines the layout of an inset.
7317 It can be applied to an existing inset of to a new, user-defined inset,
7319 \begin_inset space \thinspace{}
7323 \begin_inset space \space{}
7326 a new character style.
7328 \begin_inset space ~
7332 \begin_inset CommandInset ref
7334 reference "sec:charstyle"
7338 for more information.
7340 \begin_inset Quotes eld
7344 \begin_inset Flex CharStyle:Code
7347 \begin_layout Plain Layout
7354 \begin_inset Quotes erd
7360 \begin_layout Description
7361 \begin_inset Flex CharStyle:Code
7364 \begin_layout Plain Layout
7370 A string that indicates the width of the left margin on the screen, for
7372 \begin_inset Quotes eld
7376 \begin_inset Quotes erd
7382 \begin_layout Description
7383 \begin_inset Flex CharStyle:Code
7386 \begin_layout Plain Layout
7392 This command deletes an existing float.
7393 This is particularly useful when you want to suppress a float that has
7394 be defined in an input file.
7397 \begin_layout Description
7398 \begin_inset Flex CharStyle:Code
7401 \begin_layout Plain Layout
7407 This command deletes an existing style.
7408 This is particularly useful when you want to suppress a style that has
7409 be defined in an input file.
7412 \begin_layout Description
7413 \begin_inset Flex CharStyle:Code
7416 \begin_layout Plain Layout
7422 A string indicating what sort of output documents using this class will
7424 At present, the options are: `docbook', `latex', and `literate'.
7427 \begin_layout Description
7428 \begin_inset Flex CharStyle:Code
7431 \begin_layout Plain Layout
7442 \begin_inset Flex CharStyle:Code
7445 \begin_layout Plain Layout
7456 \begin_inset Flex CharStyle:Code
7459 \begin_layout Plain Layout
7466 \begin_inset Flex CharStyle:Code
7469 \begin_layout Plain Layout
7475 ] The class default pagestyle.
7476 Can be changed in the
7477 \begin_inset Flex CharStyle:MenuItem
7480 \begin_layout Plain Layout
7481 Document\SpecialChar \menuseparator
7490 \begin_layout Description
7491 \begin_inset Flex CharStyle:Code
7494 \begin_layout Plain Layout
7500 Sets the preamble for the LaTeX document.
7501 Note that this will completely override any prior
7502 \begin_inset Flex CharStyle:Code
7505 \begin_layout Plain Layout
7512 \begin_inset Flex CharStyle:Code
7515 \begin_layout Plain Layout
7523 \begin_inset Quotes eld
7527 \begin_inset Flex CharStyle:Code
7530 \begin_layout Plain Layout
7537 \begin_inset Quotes erd
7543 \begin_layout Description
7544 \begin_inset Flex CharStyle:Code
7547 \begin_layout Plain Layout
7554 \begin_inset Flex CharStyle:Code
7557 \begin_layout Plain Layout
7564 \begin_inset Flex CharStyle:Code
7567 \begin_layout Plain Layout
7576 \begin_inset Flex CharStyle:Code
7579 \begin_layout Plain Layout
7585 ] Whether the class already provides the feature
7586 \begin_inset Flex CharStyle:Code
7589 \begin_layout Plain Layout
7596 A feature is in general the name of a package (
7597 \begin_inset Flex CharStyle:Code
7600 \begin_layout Plain Layout
7607 \begin_inset Flex CharStyle:Code
7610 \begin_layout Plain Layout
7616 , \SpecialChar \ldots{}
7618 \begin_inset Flex CharStyle:Code
7621 \begin_layout Plain Layout
7628 \begin_inset Flex CharStyle:Code
7631 \begin_layout Plain Layout
7637 ,\SpecialChar \ldots{}
7638 ); the complete list of supported features is unfortunately not documented
7639 outside the LyX source code—but see
7640 \begin_inset Flex CharStyle:Code
7643 \begin_layout Plain Layout
7649 if you're interested.
7651 \begin_inset Flex CharStyle:MenuItem
7654 \begin_layout Plain Layout
7655 Help\SpecialChar \menuseparator
7661 also gives an overview of the supported packages.
7664 \begin_layout Description
7665 \begin_inset Flex CharStyle:Code
7668 \begin_layout Plain Layout
7675 \begin_inset Flex CharStyle:Code
7678 \begin_layout Plain Layout
7684 ] Indicates that this layout provides the functionality of the module mentioned,
7685 which should be specified by the filename without the
7686 \begin_inset Flex CharStyle:Code
7689 \begin_layout Plain Layout
7696 This will typically be used if the layout includes the module directly,
7697 rather than using the
7698 \begin_inset Flex CharStyle:Code
7701 \begin_layout Plain Layout
7707 tag to indicate that it ought to be used.
7708 It could be used in a module that provided an alternate implementation
7709 of the same functionality.
7712 \begin_layout Description
7713 \begin_inset Flex CharStyle:Code
7716 \begin_layout Plain Layout
7723 \begin_inset Flex CharStyle:Code
7726 \begin_layout Plain Layout
7732 ] Whether the class requires the feature
7733 \begin_inset Flex CharStyle:Code
7736 \begin_layout Plain Layout
7743 Multiple features must be separated by commas.
7744 Note that you can only request supported features.
7747 \begin_layout Description
7748 \begin_inset Flex CharStyle:Code
7751 \begin_layout Plain Layout
7757 A string that indicates the width of the right margin on the screen, for
7759 \begin_inset Quotes eld
7763 \begin_inset Quotes erd
7769 \begin_layout Description
7770 \begin_inset Flex CharStyle:Code
7773 \begin_layout Plain Layout
7779 Sets which divisions get numbered.
7781 \begin_inset Flex CharStyle:Code
7784 \begin_layout Plain Layout
7793 \begin_layout Description
7794 \begin_inset Flex CharStyle:Code
7797 \begin_layout Plain Layout
7806 \begin_inset Flex CharStyle:Code
7809 \begin_layout Plain Layout
7820 \begin_inset Flex CharStyle:Code
7823 \begin_layout Plain Layout
7829 ] Whether the class-default should be printing on one or both sides of the
7831 Can be changed in the
7832 \begin_inset Flex CharStyle:MenuItem
7835 \begin_layout Plain Layout
7836 Document\SpecialChar \menuseparator
7845 \begin_layout Description
7846 \begin_inset Flex CharStyle:Code
7849 \begin_layout Plain Layout
7855 This sequence defines a new paragraph style.
7856 If the style already exists, it will redefine some of its parameters instead.
7858 \begin_inset space ~
7862 \begin_inset CommandInset ref
7864 reference "sec:style"
7870 \begin_inset Quotes eld
7874 \begin_inset Flex CharStyle:Code
7877 \begin_layout Plain Layout
7884 \begin_inset Quotes erd
7890 \begin_layout Description
7891 \begin_inset Flex CharStyle:Code
7894 \begin_layout Plain Layout
7901 \begin_inset Flex CharStyle:Code
7904 \begin_layout Plain Layout
7910 ] The name of the command or environment to be used with
7911 \begin_inset Flex CharStyle:Code
7914 \begin_layout Plain Layout
7923 \begin_layout Description
7924 \begin_inset Flex CharStyle:Code
7927 \begin_layout Plain Layout
7934 \begin_inset Flex CharStyle:Code
7937 \begin_layout Plain Layout
7946 \begin_inset Flex CharStyle:Code
7949 \begin_layout Plain Layout
7955 ] Indicates what kind of markup is used to define the title of a document.
7957 \begin_inset Flex CharStyle:Code
7960 \begin_layout Plain Layout
7966 means that the macro with name
7967 \begin_inset Flex CharStyle:Code
7970 \begin_layout Plain Layout
7976 will be inserted after the last layout which has
7977 \begin_inset Quotes eld
7981 \begin_inset Flex CharStyle:Code
7984 \begin_layout Plain Layout
7991 \begin_inset Quotes erd
7996 \begin_inset Flex CharStyle:Code
7999 \begin_layout Plain Layout
8005 corresponds to the case where the block of paragraphs which have
8006 \begin_inset Quotes eld
8010 \begin_inset Flex CharStyle:Code
8013 \begin_layout Plain Layout
8020 \begin_inset Quotes erd
8023 should be enclosed into the
8024 \begin_inset Flex CharStyle:Code
8027 \begin_layout Plain Layout
8036 \begin_layout Description
8037 \begin_inset Flex CharStyle:Code
8040 \begin_layout Plain Layout
8046 Sets which divisions are included in the table of contents.
8048 \begin_inset Flex CharStyle:Code
8051 \begin_layout Plain Layout
8060 \begin_layout Subsection
8061 \begin_inset Flex CharStyle:Code
8064 \begin_layout Plain Layout
8073 \begin_layout Standard
8074 \begin_inset CommandInset label
8076 name "sec:classoptions"
8081 \begin_inset Flex CharStyle:Code
8084 \begin_layout Plain Layout
8090 section can contain the following entries:
8093 \begin_layout Description
8094 \begin_inset Flex CharStyle:Code
8097 \begin_layout Plain Layout
8104 \begin_inset Flex CharStyle:Code
8107 \begin_layout Plain Layout
8113 ] The list of available font sizes for the document's main font, separated
8115 \begin_inset Quotes eld
8119 \begin_inset Flex CharStyle:Code
8122 \begin_layout Plain Layout
8129 \begin_inset Quotes erd
8135 \begin_layout Description
8136 \begin_inset Flex CharStyle:Code
8139 \begin_layout Plain Layout
8145 Used to set the DTD line with XML-based output classes.
8147 \begin_inset space \thinspace{}
8151 \begin_inset Quotes eld
8154 -//OASIS//DTD DocBook V4.2//EN
8155 \begin_inset Quotes erd
8161 \begin_layout Description
8162 \begin_inset Flex CharStyle:Code
8165 \begin_layout Plain Layout
8172 \begin_inset Flex CharStyle:Code
8175 \begin_layout Plain Layout
8176 string="empty|plain|headings|fancy"
8181 ] The list of available page styles, separated by
8182 \begin_inset Quotes eld
8186 \begin_inset Flex CharStyle:Code
8189 \begin_layout Plain Layout
8196 \begin_inset Quotes erd
8202 \begin_layout Description
8203 \begin_inset Flex CharStyle:Code
8206 \begin_layout Plain Layout
8213 \begin_inset Flex CharStyle:Code
8216 \begin_layout Plain Layout
8222 ] Some document class options, separated by a comma, that will be added
8223 to the optional part of the
8224 \begin_inset Flex CharStyle:Code
8227 \begin_layout Plain Layout
8238 \begin_layout Standard
8240 \begin_inset Flex CharStyle:Code
8243 \begin_layout Plain Layout
8249 section must end with
8250 \begin_inset Quotes eld
8254 \begin_inset Flex CharStyle:Code
8257 \begin_layout Plain Layout
8264 \begin_inset Quotes erd
8270 \begin_layout Subsection
8274 \begin_layout Standard
8275 \begin_inset CommandInset label
8281 A paragraph style description looks like this:
8285 \begin_layout Plain Layout
8286 Note that this will either define a new layout or modify an existing one.
8294 \begin_layout LyX-Code
8301 \begin_layout LyX-Code
8305 \begin_layout LyX-Code
8309 \begin_layout Standard
8310 where the following commands are allowed:
8313 \begin_layout Description
8314 \begin_inset Flex CharStyle:Code
8317 \begin_layout Plain Layout
8324 \begin_inset Flex CharStyle:Code
8327 \begin_layout Plain Layout
8332 , left, right, center
8337 ] Paragraph alignment.
8340 \begin_layout Description
8341 \begin_inset Flex CharStyle:Code
8344 \begin_layout Plain Layout
8351 \begin_inset Flex CharStyle:Code
8354 \begin_layout Plain Layout
8359 , left, right, center
8364 ] A comma separated list of permitted alignments.
8365 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8367 For example a right-aligned or centered enumeration isn't possible.)
8370 \begin_layout Description
8371 \begin_inset Flex CharStyle:Code
8374 \begin_layout Plain Layout
8381 \begin_inset Flex CharStyle:Code
8384 \begin_layout Plain Layout
8394 \begin_layout Plain Layout
8395 Note that a `float' here is a real number, such as: 1.5.
8400 The vertical space with which the last of a chain of paragraphs with this
8401 layout is separated from the following paragraph.
8402 If the next paragraph has another layout, the separations are not simply
8403 added, but the maximum is taken.
8406 \begin_layout Description
8407 \begin_inset Flex CharStyle:Code
8410 \begin_layout Plain Layout
8417 \begin_inset Flex CharStyle:Code
8420 \begin_layout Plain Layout
8426 The category for this style.
8427 This is used to group related styles in the Layout combobox on the toolbar.
8428 Any string can be used, but you may want to use existing categories with
8433 \begin_layout Description
8434 \begin_inset Flex CharStyle:Code
8437 \begin_layout Plain Layout
8443 Depth of XML command.
8444 Used only with XML-type formats.
8447 \begin_layout Description
8448 \begin_inset Flex CharStyle:Code
8451 \begin_layout Plain Layout
8458 \begin_inset CommandInset label
8460 name "des:CopyStyle"
8465 \begin_inset Flex CharStyle:Code
8468 \begin_layout Plain Layout
8474 Copies all the features of an existing style into the current one.
8478 \begin_layout Description
8479 \begin_inset Flex CharStyle:Code
8482 \begin_layout Plain Layout
8488 The name of a style whose preamble should be output
8493 This allows to ensure some ordering of the preamble snippets when macros
8494 definitions depend on one another.
8498 \begin_layout Plain Layout
8499 Note that, besides that functionality, there is no way to ensure any ordering
8501 The ordering that you see in a given version of LyX may change without
8502 warning in later versions.
8510 \begin_layout Description
8511 \begin_inset Flex CharStyle:Code
8514 \begin_layout Plain Layout
8521 \begin_inset Flex CharStyle:Code
8524 \begin_layout Plain Layout
8529 , Box, Filled_Box, Static
8534 ] The type of label that stands at the end of the paragraph (or sequence
8536 \begin_inset Flex CharStyle:Code
8539 \begin_layout Plain Layout
8546 \begin_inset Flex CharStyle:Code
8549 \begin_layout Plain Layout
8556 \begin_inset Flex CharStyle:Code
8559 \begin_layout Plain Layout
8566 \begin_inset Flex CharStyle:Code
8569 \begin_layout Plain Layout
8577 \begin_inset Flex CharStyle:Code
8580 \begin_layout Plain Layout
8587 \begin_inset Quotes eld
8591 \begin_inset Quotes erd
8595 \begin_inset Flex CharStyle:Code
8598 \begin_layout Plain Layout
8605 \begin_inset Flex CharStyle:Code
8608 \begin_layout Plain Layout
8609 \begin_inset space ~
8618 \begin_inset space ~
8621 black) square suitable for end of proof markers,
8622 \begin_inset Flex CharStyle:Code
8625 \begin_layout Plain Layout
8631 is an explicit text string.
8634 \begin_layout Description
8635 \begin_inset Flex CharStyle:Code
8638 \begin_layout Plain Layout
8645 \begin_inset Flex CharStyle:Code
8648 \begin_layout Plain Layout
8654 ] The string used for a label with a
8655 \begin_inset Flex CharStyle:Code
8658 \begin_layout Plain Layout
8665 \begin_inset Flex CharStyle:Code
8668 \begin_layout Plain Layout
8678 \begin_layout Description
8679 \begin_inset Flex CharStyle:Code
8682 \begin_layout Plain Layout
8689 \begin_inset Flex CharStyle:Code
8692 \begin_layout Plain Layout
8703 \begin_inset Flex CharStyle:Code
8706 \begin_layout Plain Layout
8715 \begin_layout Description
8716 \begin_inset Flex CharStyle:Code
8719 \begin_layout Plain Layout
8726 \begin_inset Flex CharStyle:Code
8729 \begin_layout Plain Layout
8739 ] With this parameter the
8740 \begin_inset Flex CharStyle:MenuItem
8743 \begin_layout Plain Layout
8750 \begin_inset Quotes eld
8753 Vertical space above
8754 \begin_inset Quotes erd
8758 \begin_inset Flex CharStyle:MenuItem
8761 \begin_layout Plain Layout
8762 Edit\SpecialChar \menuseparator
8764 \begin_inset space ~
8772 dialog can be set when initializing a paragraph with this style.
8776 \begin_layout Plain Layout
8779 Note from Jean-Marc:
8781 I'm not sure that this setting has much use, and it should probably be
8782 removed in later versions.
8790 \begin_layout Description
8791 \begin_inset Flex CharStyle:Code
8794 \begin_layout Plain Layout
8800 The font used for both the text body
8806 \begin_inset space ~
8810 \begin_inset CommandInset ref
8812 reference "sec:fonts"
8817 Note that defining this font automatically defines the
8818 \begin_inset Flex CharStyle:Code
8821 \begin_layout Plain Layout
8828 So you should define this one first if you also want to define
8829 \begin_inset Flex CharStyle:Code
8832 \begin_layout Plain Layout
8841 \begin_layout Description
8842 \begin_inset Flex CharStyle:Code
8845 \begin_layout Plain Layout
8852 \begin_inset CommandInset label
8854 name "des:FreeSpacing"
8861 \begin_inset Flex CharStyle:Code
8864 \begin_layout Plain Layout
8875 \begin_inset Flex CharStyle:Code
8878 \begin_layout Plain Layout
8884 ] Usually LyX doesn't allow you to insert more than one space between words,
8885 since a space is considered as the separation between two words, not a
8886 character or symbol of its own.
8887 This is a very fine thing but sometimes annoying, for example, when typing
8888 program code or plain LaTeX code.
8890 \begin_inset Flex CharStyle:Code
8893 \begin_layout Plain Layout
8900 Note that LyX will create protected blanks for the additional blanks when
8901 in another mode than LaTeX-mode.
8904 \begin_layout Description
8905 \begin_inset Flex CharStyle:Code
8908 \begin_layout Plain Layout
8914 Language dependent information to be included in the LaTeX preamble when
8916 Note that this will completely override any prior
8917 \begin_inset Flex CharStyle:Code
8920 \begin_layout Plain Layout
8928 \begin_inset Quotes eld
8932 \begin_inset Flex CharStyle:Code
8935 \begin_layout Plain Layout
8942 \begin_inset Quotes erd
8946 The contents of this tag will occur once in the LaTeX preamble for each
8947 language used by the document.
8948 Each time, the following substitutions are made:
8952 \begin_layout Itemize
8953 \begin_inset Flex CharStyle:Code
8956 \begin_layout Plain Layout
8962 is replaced by the language name (as used by the babel package).
8965 \begin_layout Itemize
8967 \begin_inset Quotes eld
8971 \begin_inset Quotes erd
8975 \begin_inset Flex CharStyle:Code
8978 \begin_layout Plain Layout
8984 replaces its argument by the translation of the argument to the current
8988 \begin_layout Standard
8989 If the style defines text that appears in the typeset document, it may use
8991 \begin_inset Flex CharStyle:Code
8994 \begin_layout Plain Layout
9000 to support non-english and even multilanguage documents correctly.
9001 The following excerpt (from the
9002 \begin_inset Flex CharStyle:Code
9005 \begin_layout Plain Layout
9011 file) shows how this works:
9014 \begin_layout LyX-Code
9018 \begin_layout LyX-Code
9026 \begin_layout LyX-Code
9029 theoremstyle{remark}
9032 \begin_layout LyX-Code
9035 newtheorem{claim}[thm]{
9042 \begin_layout LyX-Code
9046 \begin_layout LyX-Code
9050 \begin_layout LyX-Code
9066 \begin_layout LyX-Code
9075 claimname}{_(Claim)}}%
9078 \begin_layout LyX-Code
9084 \begin_layout LyX-Code
9088 \begin_layout Standard
9089 The key to correct translation of the user visible text is the definition
9091 \begin_inset Flex CharStyle:Code
9094 \begin_layout Plain Layout
9102 in the standard preamble.
9103 This command holds the name of the theorem that will appear in the output.
9105 \begin_inset Flex CharStyle:Code
9108 \begin_layout Plain Layout
9114 then uses the commands offered by the babel package to redefine
9115 \begin_inset Flex CharStyle:Code
9118 \begin_layout Plain Layout
9126 for each used language.
9128 \begin_inset Flex CharStyle:Code
9131 \begin_layout Plain Layout
9141 test ensures that no LaTeX error occurs in documents that do not use babel.
9142 Since LyX loads babel after the style-specific preamble, the whole command
9143 is deferred to the actual start of the document with
9144 \begin_inset Flex CharStyle:Code
9147 \begin_layout Plain Layout
9159 \begin_layout Description
9160 \begin_inset Flex CharStyle:Code
9163 \begin_layout Plain Layout
9169 [[FIXME]] (Used only with XML-type formats.)
9172 \begin_layout Description
9173 \begin_inset Flex CharStyle:Code
9176 \begin_layout Plain Layout
9183 \begin_inset Flex CharStyle:Code
9186 \begin_layout Plain Layout
9192 If 1, marks the layout as being part of a title block (see also the
9193 \begin_inset Flex CharStyle:Code
9196 \begin_layout Plain Layout
9203 \begin_inset Flex CharStyle:Code
9206 \begin_layout Plain Layout
9215 \begin_layout Description
9216 \begin_inset Flex CharStyle:Code
9219 \begin_layout Plain Layout
9226 \begin_inset Flex CharStyle:Code
9229 \begin_layout Plain Layout
9235 ] This provides extra space between paragraphs that have the same layout.
9236 If you put other layouts into an environment, each is separated with the
9238 \begin_inset Flex CharStyle:Code
9241 \begin_layout Plain Layout
9248 But the whole items of the environment are additionally separated with
9250 \begin_inset Flex CharStyle:Code
9253 \begin_layout Plain Layout
9265 \begin_layout Description
9266 \begin_inset Flex CharStyle:Code
9269 \begin_layout Plain Layout
9275 [[FIXME]] (Used only with XML-type formats.)
9278 \begin_layout Description
9279 \begin_inset Flex CharStyle:Code
9282 \begin_layout Plain Layout
9289 \begin_inset CommandInset label
9291 name "des:KeepEmpty"
9298 \begin_inset Flex CharStyle:Code
9301 \begin_layout Plain Layout
9312 \begin_inset Flex CharStyle:Code
9315 \begin_layout Plain Layout
9321 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9322 lead to empty LaTeX output.
9323 There are some cases where this could be desirable however: in a letter
9324 template, the required fields can be provided as empty fields, so that
9325 people do not forget them; in some special classes, a layout can be used
9326 as some kind of break, which does not contain actual text.
9329 \begin_layout Description
9330 \begin_inset Flex CharStyle:Code
9333 \begin_layout Plain Layout
9339 [float=0] The vertical space between the label and the text body.
9340 Only used for labels that are above the text body (
9341 \begin_inset Flex CharStyle:Code
9344 \begin_layout Plain Layout
9351 \begin_inset Flex CharStyle:Code
9354 \begin_layout Plain Layout
9355 Centered_Top_Environment
9363 \begin_layout Description
9364 \begin_inset Flex CharStyle:Code
9367 \begin_layout Plain Layout
9374 \begin_inset Flex CharStyle:Code
9377 \begin_layout Plain Layout
9384 \begin_inset Newline newline
9387 The name of the counter for automatic numbering (see Section
9388 \begin_inset CommandInset ref
9390 reference "sec:counter"
9395 This must be given if
9396 \begin_inset Flex CharStyle:Code
9399 \begin_layout Plain Layout
9406 \begin_inset Flex CharStyle:Code
9409 \begin_layout Plain Layout
9418 \begin_layout Description
9419 \begin_inset Flex CharStyle:Code
9422 \begin_layout Plain Layout
9428 The font used for the label.
9430 \begin_inset space ~
9434 \begin_inset CommandInset ref
9436 reference "sec:fonts"
9443 \begin_layout Description
9444 \begin_inset Flex CharStyle:Code
9447 \begin_layout Plain Layout
9453 Text that indicates how far a label should be indented.
9456 \begin_layout Description
9457 \begin_inset Flex CharStyle:Code
9460 \begin_layout Plain Layout
9467 \begin_inset Flex CharStyle:Code
9470 \begin_layout Plain Layout
9476 ] The horizontal space between the label and the text body.
9477 Only used for labels that are not above the text body.
9480 \begin_layout Description
9481 \begin_inset Flex CharStyle:Code
9484 \begin_layout Plain Layout
9491 \begin_inset Flex CharStyle:Code
9494 \begin_layout Plain Layout
9500 ] The string used for a label with a
9501 \begin_inset Flex CharStyle:Code
9504 \begin_layout Plain Layout
9512 \begin_inset Flex CharStyle:Code
9515 \begin_layout Plain Layout
9521 is set, this string can be contain the special formatting commands described
9523 \begin_inset CommandInset ref
9525 reference "sec:counter"
9533 \begin_layout Plain Layout
9534 For the sake of backwards compatibility, the string
9535 \begin_inset Flex CharStyle:Code
9538 \begin_layout Plain Layout
9548 will be replaced by the expanded
9549 \begin_inset Flex CharStyle:Code
9552 \begin_layout Plain Layout
9559 \begin_inset Flex CharStyle:Code
9562 \begin_layout Plain Layout
9571 This feature is now obsolete and should be replaced by the mechanisms of
9573 \begin_inset CommandInset ref
9575 reference "sec:counter"
9587 \begin_layout Description
9588 \begin_inset Flex CharStyle:Code
9591 \begin_layout Plain Layout
9598 \begin_inset Flex CharStyle:Code
9601 \begin_layout Plain Layout
9607 ] This is used inside the appendix instead of
9608 \begin_inset Flex CharStyle:Code
9611 \begin_layout Plain Layout
9619 \begin_inset Flex CharStyle:Code
9622 \begin_layout Plain Layout
9629 \begin_inset Flex CharStyle:Code
9632 \begin_layout Plain Layout
9641 \begin_layout Description
9642 \begin_inset Flex CharStyle:Code
9645 \begin_layout Plain Layout
9651 [FIXME] (Used only with XML-type formats.)
9654 \begin_layout Description
9655 \begin_inset Flex CharStyle:Code
9658 \begin_layout Plain Layout
9665 \begin_inset Flex CharStyle:Code
9668 \begin_layout Plain Layout
9673 , Manual, Static, Top_Environment,
9674 \begin_inset Newline newline
9677 Centered_Top_Environment, Sensitive, Counter
9683 \begin_inset Newline newline
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9696 means the label is the very first word (up to the first real blank).
9700 \begin_layout Plain Layout
9701 Use protected spaces if you want more than one word as the label.
9707 \begin_inset Flex CharStyle:Code
9710 \begin_layout Plain Layout
9716 means it is defined in the layout (see
9717 \begin_inset Flex CharStyle:Code
9720 \begin_layout Plain Layout
9728 \begin_inset Flex CharStyle:Code
9731 \begin_layout Plain Layout
9738 \begin_inset Flex CharStyle:Code
9741 \begin_layout Plain Layout
9742 Centered_Top_Environment
9747 are special cases of
9748 \begin_inset Flex CharStyle:Code
9751 \begin_layout Plain Layout
9758 The label will be printed above the paragraph, but only at the top of an
9759 environment or the top of a chain of paragraphs with this layout.
9760 Usage is for example the
9761 \begin_inset Flex CharStyle:MenuItem
9764 \begin_layout Plain Layout
9771 \begin_inset Flex CharStyle:MenuItem
9774 \begin_layout Plain Layout
9781 This is also the case for
9782 \begin_inset Flex CharStyle:Code
9785 \begin_layout Plain Layout
9791 labels with latex type
9792 \begin_inset Flex CharStyle:Code
9795 \begin_layout Plain Layout
9801 , in order to make layouts for theorems work correctly.
9803 \begin_inset Flex CharStyle:Code
9806 \begin_layout Plain Layout
9812 is a special case for the caption-labels
9813 \begin_inset Quotes eld
9817 \begin_inset Quotes erd
9821 \begin_inset Quotes eld
9825 \begin_inset Quotes erd
9830 \begin_inset Flex CharStyle:Code
9833 \begin_layout Plain Layout
9839 means the (hardcoded) label string depends on the kind of float.
9841 \begin_inset Flex CharStyle:Code
9844 \begin_layout Plain Layout
9850 label type defines automatically numbered labels.
9852 \begin_inset CommandInset ref
9854 reference "sec:counter"
9861 \begin_layout Description
9862 \begin_inset Flex CharStyle:Code
9865 \begin_layout Plain Layout
9871 The name of the corresponding LaTeX stuff.
9872 Either the environment or command name.
9875 \begin_layout Description
9876 \begin_inset Flex CharStyle:Code
9879 \begin_layout Plain Layout
9885 An optional parameter for the corresponding
9886 \begin_inset Flex CharStyle:Code
9889 \begin_layout Plain Layout
9896 This parameter cannot be changed from within LyX.
9899 \begin_layout Description
9900 \begin_inset Flex CharStyle:Code
9903 \begin_layout Plain Layout
9910 \begin_inset CommandInset label
9912 name "des:LatexType"
9917 \begin_inset Flex CharStyle:Code
9920 \begin_layout Plain Layout
9925 , Command, Environment, Item_Environment,
9931 \begin_inset Flex CharStyle:Code
9934 \begin_layout Plain Layout
9940 ] How the layout should be translated into LaTeX.
9942 \begin_inset Flex CharStyle:Code
9945 \begin_layout Plain Layout
9951 means nothing special.
9953 \begin_inset Flex CharStyle:Code
9956 \begin_layout Plain Layout
9963 \begin_inset Flex CharStyle:Code
9966 \begin_layout Plain Layout
9973 {\SpecialChar \ldots{}
9980 \begin_inset Flex CharStyle:Code
9983 \begin_layout Plain Layout
9990 \begin_inset Flex CharStyle:Code
9993 \begin_layout Plain Layout
10000 }\SpecialChar \ldots{}
10014 \begin_inset Flex CharStyle:Code
10017 \begin_layout Plain Layout
10024 \begin_inset Flex CharStyle:Code
10027 \begin_layout Plain Layout
10034 \begin_inset Flex CharStyle:Code
10037 \begin_layout Plain Layout
10045 is generated for each paragraph of this environment.
10047 \begin_inset Flex CharStyle:Code
10050 \begin_layout Plain Layout
10057 \begin_inset Flex CharStyle:Code
10060 \begin_layout Plain Layout
10067 \begin_inset Flex CharStyle:Code
10070 \begin_layout Plain Layout
10076 is passed as an argument to the environment.
10078 \begin_inset Flex CharStyle:Code
10081 \begin_layout Plain Layout
10087 can be defined in the
10088 \begin_inset Flex CharStyle:MenuItem
10091 \begin_layout Plain Layout
10096 ayout\SpecialChar \menuseparator
10108 \begin_inset Flex CharStyle:Code
10111 \begin_layout Plain Layout
10119 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10120 Visit the SGML class files for specific examples.
10123 \begin_layout Standard
10124 Putting the last few things together, the LaTeX output will be either:
10127 \begin_layout LyX-Code
10130 latexname[latexparam]{\SpecialChar \ldots{}
10134 \begin_layout Standard
10138 \begin_layout LyX-Code
10141 begin{latexname}[latexparam] \SpecialChar \ldots{}
10147 \begin_layout Standard
10148 depending upon the LaTeX type.
10151 \begin_layout Description
10152 \begin_inset Flex CharStyle:Code
10155 \begin_layout Plain Layout
10162 \begin_inset Flex CharStyle:Code
10165 \begin_layout Plain Layout
10171 ] If you put layouts into environments, the leftmargins are not simply added,
10172 but added with a factor
10173 \begin_inset Formula $\frac{4}{depth+4}$
10177 Note that this parameter is also used when the margin is defined as
10178 \begin_inset Flex CharStyle:Code
10181 \begin_layout Plain Layout
10188 \begin_inset Flex CharStyle:Code
10191 \begin_layout Plain Layout
10198 Then it is added to the manual or dynamic margin.
10200 \begin_inset Newline newline
10203 The argument is passed as a string.
10205 \begin_inset Quotes eld
10209 \begin_inset Flex CharStyle:Code
10212 \begin_layout Plain Layout
10219 \begin_inset Quotes erd
10222 means that the paragraph is indented with the width of
10223 \begin_inset Quotes eld
10227 \begin_inset Flex CharStyle:Code
10230 \begin_layout Plain Layout
10237 \begin_inset Quotes erd
10240 in the normal font.
10241 You can get a negative width by prefixing the string with
10242 \begin_inset Quotes eld
10246 \begin_inset Flex CharStyle:Code
10249 \begin_layout Plain Layout
10256 \begin_inset Quotes erd
10260 This way was chosen so that the look is the same with each used screen
10265 \begin_layout Description
10266 \begin_inset Flex CharStyle:Code
10269 \begin_layout Plain Layout
10276 \begin_inset Flex CharStyle:Code
10279 \begin_layout Plain Layout
10284 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10290 \begin_inset Newline newline
10293 The kind of margin that the layout has on the left side.
10295 \begin_inset Flex CharStyle:Code
10298 \begin_layout Plain Layout
10304 just means a fixed margin.
10306 \begin_inset Flex CharStyle:Code
10309 \begin_layout Plain Layout
10315 means that the left margin depends on the string entered in the
10316 \begin_inset Flex CharStyle:MenuItem
10319 \begin_layout Plain Layout
10320 Edit\SpecialChar \menuseparator
10322 \begin_inset space ~
10331 This is used to typeset nice lists without tabulators.
10333 \begin_inset Flex CharStyle:Code
10336 \begin_layout Plain Layout
10342 means that the margin depends on the size of the label.
10343 This is used for automatic enumerated headlines.
10344 It is obvious that the headline
10345 \begin_inset Quotes eld
10348 5.4.3.2.1 Very long headline
10349 \begin_inset Quotes erd
10352 must have a wider left margin (as wide as
10353 \begin_inset Quotes eld
10357 \begin_inset Quotes erd
10360 plus the space) than
10361 \begin_inset Quotes eld
10364 3.2 Very long headline
10365 \begin_inset Quotes erd
10369 \begin_inset Quotes eld
10373 \begin_inset Quotes erd
10376 are not able to do this.
10378 \begin_inset Flex CharStyle:Code
10381 \begin_layout Plain Layout
10387 is similar, but only the very first row of the paragraph is dynamic, while
10388 the others are static; this is used, for example, for descriptions.
10390 \begin_inset Flex CharStyle:Code
10393 \begin_layout Plain Layout
10399 means the margin is chosen in a way that the longest row of this paragraph
10400 fits to the right margin.
10401 This is used to typeset an address on the right edge of the page.
10404 \begin_layout Description
10405 \begin_inset Flex CharStyle:Code
10408 \begin_layout Plain Layout
10415 \begin_inset Flex CharStyle:Code
10418 \begin_layout Plain Layout
10427 \begin_inset Flex CharStyle:Code
10430 \begin_layout Plain Layout
10436 ] Whether fragile commands in this layout should be
10437 \begin_inset Flex CharStyle:Code
10440 \begin_layout Plain Layout
10453 whether this command should itself be protected.)
10456 \begin_layout Description
10457 \begin_inset Flex CharStyle:Code
10460 \begin_layout Plain Layout
10467 \begin_inset Flex CharStyle:Code
10470 \begin_layout Plain Layout
10477 \begin_inset Flex CharStyle:Code
10480 \begin_layout Plain Layout
10488 ] Whether newlines are translated into LaTeX newlines (
10489 \begin_inset Flex CharStyle:Code
10492 \begin_layout Plain Layout
10503 The translation can be switched off to allow more comfortable LaTeX editing
10507 \begin_layout Description
10508 \begin_inset Flex CharStyle:Code
10511 \begin_layout Plain Layout
10518 \begin_inset Flex CharStyle:Code
10521 \begin_layout Plain Layout
10528 \begin_inset Flex CharStyle:Code
10531 \begin_layout Plain Layout
10539 ] Whether the following Paragraph is allowed to indent its very first row.
10541 \begin_inset Flex CharStyle:Code
10544 \begin_layout Plain Layout
10550 means that it is not allowed to do so;
10551 \begin_inset Flex CharStyle:Code
10554 \begin_layout Plain Layout
10560 means it could do so if it wants to.
10563 \begin_layout Description
10564 \begin_inset Flex CharStyle:Code
10567 \begin_layout Plain Layout
10573 Name of a layout that has replaced this layout.
10574 This is used to rename a layout, while keeping backward compatibility.
10577 \begin_layout Description
10578 \begin_inset Flex CharStyle:Code
10581 \begin_layout Plain Layout
10588 \begin_inset Flex CharStyle:Code
10591 \begin_layout Plain Layout
10597 ] The number of optional arguments that can be used with this layout.
10598 This is useful for things like section headings, and only makes sense with
10602 \begin_layout Description
10603 \begin_inset Flex CharStyle:Code
10606 \begin_layout Plain Layout
10613 \begin_inset Flex CharStyle:Code
10616 \begin_layout Plain Layout
10622 ] The indent of the very first line of a paragraph.
10624 \begin_inset Flex CharStyle:Code
10627 \begin_layout Plain Layout
10633 will be fixed for a certain layout.
10634 The exception is Standard layout, since the indentation of a Standard layout
10635 paragraph can be prohibited with
10636 \begin_inset Flex CharStyle:Code
10639 \begin_layout Plain Layout
10646 Also, Standard layout paragraphs inside environments use the
10647 \begin_inset Flex CharStyle:Code
10650 \begin_layout Plain Layout
10656 of the environment, not their native one.
10657 For example, Standard paragraphs inside an enumeration are not indented.
10660 \begin_layout Description
10661 \begin_inset Flex CharStyle:Code
10664 \begin_layout Plain Layout
10671 \begin_inset Flex CharStyle:Code
10674 \begin_layout Plain Layout
10680 ] The vertical space between two paragraphs of this layout.
10683 \begin_layout Description
10684 \begin_inset Flex CharStyle:Code
10687 \begin_layout Plain Layout
10694 \begin_inset Flex CharStyle:Code
10697 \begin_layout Plain Layout
10703 ] LyX allows the user to choose either
10704 \begin_inset Quotes eld
10708 \begin_inset Quotes erd
10712 \begin_inset Quotes eld
10716 \begin_inset Quotes erd
10719 to typeset a document.
10721 \begin_inset Quotes eld
10725 \begin_inset Quotes erd
10728 is chosen, this value is completely ignored.
10730 \begin_inset Quotes eld
10734 \begin_inset Quotes erd
10737 is chosen, the parindent of a LaTeXtype
10738 \begin_inset Quotes eld
10742 \begin_inset Quotes erd
10745 layout is ignored and all paragraphs are separated by this parskip argument.
10746 The vertical space is calculated with
10747 \begin_inset Flex CharStyle:Code
10750 \begin_layout Plain Layout
10752 \begin_inset space ~
10761 \begin_inset Flex CharStyle:Code
10764 \begin_layout Plain Layout
10770 is the height of a row with the normal font.
10771 This way, the look stays the same with different screen fonts.
10774 \begin_layout Description
10775 \begin_inset Flex CharStyle:Code
10778 \begin_layout Plain Layout
10785 \begin_inset CommandInset label
10787 name "des:PathThru"
10794 \begin_inset Flex CharStyle:Code
10797 \begin_layout Plain Layout
10808 \begin_inset Flex CharStyle:Code
10811 \begin_layout Plain Layout
10817 ] Whether the contents of this paragraph should be output in raw form, meaning
10818 without special translations that LaTeX would require.
10821 \begin_layout Description
10822 \begin_inset Flex CharStyle:Code
10825 \begin_layout Plain Layout
10832 \begin_inset CommandInset label
10834 name "des:Preamble"
10838 Information to be included in the LaTeX preamble when this style is used.
10839 Used to define macros, load packages, etc., required by this particular
10842 \begin_inset Quotes eld
10846 \begin_inset Flex CharStyle:Code
10849 \begin_layout Plain Layout
10856 \begin_inset Quotes erd
10862 \begin_layout Description
10863 \begin_inset Flex CharStyle:Code
10866 \begin_layout Plain Layout
10873 \begin_inset Flex CharStyle:Code
10876 \begin_layout Plain Layout
10883 \begin_inset CommandInset label
10885 name "des:Requires"
10889 Whether the layout requires the feature
10890 \begin_inset Flex CharStyle:Code
10893 \begin_layout Plain Layout
10900 See the description of
10901 \begin_inset Flex CharStyle:Code
10904 \begin_layout Plain Layout
10911 \begin_inset CommandInset ref
10912 LatexCommand pageref
10913 reference "des:FreeSpacing"
10917 ) for information on `features'.
10921 \begin_layout Description
10922 \begin_inset Flex CharStyle:Code
10925 \begin_layout Plain Layout
10932 \begin_inset Flex CharStyle:Code
10935 \begin_layout Plain Layout
10942 \begin_inset Flex CharStyle:Code
10945 \begin_layout Plain Layout
10954 \begin_layout Description
10955 \begin_inset Flex CharStyle:Code
10958 \begin_layout Plain Layout
10965 \begin_inset Flex CharStyle:Code
10968 \begin_layout Plain Layout
10973 , onehalf, double, other
10982 ] This defines what the default spacing should be in the layout.
10984 \begin_inset Flex CharStyle:Code
10987 \begin_layout Plain Layout
10994 \begin_inset Flex CharStyle:Code
10997 \begin_layout Plain Layout
11004 \begin_inset Flex CharStyle:Code
11007 \begin_layout Plain Layout
11013 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11014 If you specify the argument
11015 \begin_inset Flex CharStyle:Code
11018 \begin_layout Plain Layout
11024 , then you should also provide a numerical argument which will be the actual
11026 Note that, contrary to other parameters,
11027 \begin_inset Flex CharStyle:Code
11030 \begin_layout Plain Layout
11036 implies the generation of specific LaTeX code, using the package
11039 \begin_inset Flex CharStyle:Code
11042 \begin_layout Plain Layout
11051 \begin_layout Description
11052 \begin_inset Flex CharStyle:Code
11055 \begin_layout Plain Layout
11061 The font used for the text body .
11063 \begin_inset CommandInset ref
11065 reference "sec:fonts"
11072 \begin_layout Description
11073 \begin_inset Flex CharStyle:Code
11076 \begin_layout Plain Layout
11084 The level of the style in the table of contents.
11085 This is used for automatic numbering of section headings.
11088 \begin_layout Description
11089 \begin_inset Flex CharStyle:Code
11092 \begin_layout Plain Layout
11099 \begin_inset Flex CharStyle:Code
11102 \begin_layout Plain Layout
11108 ] The vertical space with which the very first of a chain of paragraphs
11109 with this layout is separated from the previous paragraph.
11110 If the previous paragraph has another layout, the separations are not simply
11111 added, but the maximum is taken.
11114 \begin_layout Subsection
11118 \begin_layout Standard
11119 \begin_inset CommandInset label
11125 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11126 define the floats (
11127 \begin_inset Flex CharStyle:MenuItem
11130 \begin_layout Plain Layout
11137 \begin_inset Flex CharStyle:MenuItem
11140 \begin_layout Plain Layout
11146 , \SpecialChar \ldots{}
11147 ) in the text class itself.
11148 Standard floats are included in the file
11149 \begin_inset Flex CharStyle:Code
11152 \begin_layout Plain Layout
11158 , so you may have to do no more than add
11161 \begin_layout LyX-Code
11162 Input stdfloats.inc
11165 \begin_layout Standard
11166 to your layout file.
11167 If you want to implement a text class that proposes some other float types
11168 (like the AGU class bundled with LyX), the information below will hopefully
11172 \begin_layout Description
11173 \begin_inset Flex CharStyle:Code
11176 \begin_layout Plain Layout
11183 \begin_inset Flex CharStyle:Code
11186 \begin_layout Plain Layout
11193 \begin_inset Quotes erd
11197 \begin_inset Quotes erd
11200 ] The file name extension of an auxiliary file for the list of figures (or
11202 LaTeX writes the captions to this file.
11205 \begin_layout Description
11206 \begin_inset Flex CharStyle:Code
11209 \begin_layout Plain Layout
11216 \begin_inset Flex CharStyle:Code
11219 \begin_layout Plain Layout
11226 \begin_inset Quotes erd
11230 \begin_inset Quotes erd
11233 ] The string that will be used in the menus and also for the caption.
11236 \begin_layout Description
11237 \begin_inset Flex CharStyle:Code
11240 \begin_layout Plain Layout
11247 \begin_inset Flex CharStyle:Code
11250 \begin_layout Plain Layout
11259 \begin_inset Flex CharStyle:Code
11262 \begin_layout Plain Layout
11269 \begin_inset Flex CharStyle:Code
11272 \begin_layout Plain Layout
11278 if the float is already defined by the LaTeX document class.
11280 \begin_inset Flex CharStyle:Code
11283 \begin_layout Plain Layout
11289 , the float will be defined using the LaTeX package
11290 \begin_inset Flex CharStyle:Code
11293 \begin_layout Plain Layout
11302 \begin_layout Description
11303 \begin_inset Flex CharStyle:Code
11306 \begin_layout Plain Layout
11313 \begin_inset Flex CharStyle:Code
11316 \begin_layout Plain Layout
11323 \begin_inset Quotes erd
11327 \begin_inset Quotes erd
11330 ] The heading used for the list of floats.
11333 \begin_layout Description
11334 \begin_inset Flex CharStyle:Code
11337 \begin_layout Plain Layout
11344 \begin_inset Flex CharStyle:Code
11347 \begin_layout Plain Layout
11354 \begin_inset Quotes erd
11358 \begin_inset Quotes erd
11361 ] This (optional) argument determines whether floats of this class will
11362 be numbered within some sectional unit of the document.
11363 For example, if within is equal to
11364 \begin_inset Flex CharStyle:Code
11367 \begin_layout Plain Layout
11373 , the floats will be numbered within chapters.
11377 \begin_layout Description
11378 \begin_inset Flex CharStyle:Code
11381 \begin_layout Plain Layout
11388 \begin_inset Flex CharStyle:Code
11391 \begin_layout Plain Layout
11398 \begin_inset Quotes erd
11402 \begin_inset Quotes erd
11405 ] The default placement for the given class of floats.
11406 The string should be as in standard LaTeX:
11407 \begin_inset Flex CharStyle:Code
11410 \begin_layout Plain Layout
11417 \begin_inset Flex CharStyle:Code
11420 \begin_layout Plain Layout
11427 \begin_inset Flex CharStyle:Code
11430 \begin_layout Plain Layout
11437 \begin_inset Flex CharStyle:Code
11440 \begin_layout Plain Layout
11446 for top, bottom, page, and here, respectively.
11450 \begin_layout Plain Layout
11451 Note that the order of these letters in the string is irrelevant, like in
11457 On top of that there is a new type,
11458 \begin_inset Flex CharStyle:Code
11461 \begin_layout Plain Layout
11467 , which does not really correspond to a float, since it means: put it
11468 \begin_inset Quotes eld
11472 \begin_inset Quotes erd
11476 Note however that the
11477 \begin_inset Flex CharStyle:Code
11480 \begin_layout Plain Layout
11486 specifier is special and, because of implementation details, cannot be
11487 used in non-built in float types.
11488 If you do not understand what this means, just use
11489 \begin_inset Quotes eld
11493 \begin_inset Flex CharStyle:Code
11496 \begin_layout Plain Layout
11503 \begin_inset Quotes erd
11509 \begin_layout Description
11510 \begin_inset Flex CharStyle:Code
11513 \begin_layout Plain Layout
11520 \begin_inset Flex CharStyle:Code
11523 \begin_layout Plain Layout
11530 \begin_inset Quotes erd
11534 \begin_inset Quotes erd
11537 ] The style used when defining the float using
11538 \begin_inset Flex CharStyle:Code
11541 \begin_layout Plain Layout
11552 \begin_layout Description
11553 \begin_inset Flex CharStyle:Code
11556 \begin_layout Plain Layout
11563 \begin_inset Flex CharStyle:Code
11566 \begin_layout Plain Layout
11573 \begin_inset Quotes erd
11577 \begin_inset Quotes erd
11581 \begin_inset Quotes eld
11585 \begin_inset Quotes erd
11588 of the new class of floats, like program or algorithm.
11589 After the appropriate
11590 \begin_inset Flex CharStyle:Code
11593 \begin_layout Plain Layout
11602 \begin_inset Flex CharStyle:Code
11605 \begin_layout Plain Layout
11614 \begin_inset Flex CharStyle:Code
11617 \begin_layout Plain Layout
11628 \begin_layout Standard
11629 Note that defining a float with type
11630 \begin_inset Flex CharStyle:Code
11633 \begin_layout Plain Layout
11641 automatically defines the corresponding counter with name
11642 \begin_inset Flex CharStyle:Code
11645 \begin_layout Plain Layout
11656 \begin_layout Subsection
11657 Flex insets and InsetLayout
11660 \begin_layout Standard
11661 \begin_inset CommandInset label
11663 name "sec:charstyle"
11667 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11668 these are called Flex insets.
11672 \begin_layout Standard
11673 Flex insets come in three different kinds:
11676 \begin_layout Itemize
11678 \begin_inset Flex CharStyle:Code
11681 \begin_layout Plain Layout
11687 ): These define semantic markup corresponding to such LaTeX commands as
11689 \begin_inset Flex CharStyle:Code
11692 \begin_layout Plain Layout
11701 \begin_inset Flex CharStyle:Code
11704 \begin_layout Plain Layout
11715 \begin_layout Itemize
11717 \begin_inset Flex CharStyle:Code
11720 \begin_layout Plain Layout
11726 ): These can be used to define custom collapsible insets, similar to TeX
11727 code, footnote, and the like.
11728 An obvious example is an endnote inset, which is defined in the
11729 \begin_inset Flex CharStyle:Code
11732 \begin_layout Plain Layout
11741 \begin_layout Itemize
11743 \begin_inset Flex CharStyle:Code
11746 \begin_layout Plain Layout
11752 ): For use with DocBook classes.
11755 \begin_layout Standard
11756 Flex insets are defined using the
11757 \begin_inset Flex CharStyle:Code
11760 \begin_layout Plain Layout
11766 tag, which shall be explained in a moment.
11769 \begin_layout Standard
11771 \begin_inset Flex CharStyle:Code
11774 \begin_layout Plain Layout
11780 tag also serves another function: It can be used to customize the general
11781 layout of many different types of insets.
11783 \begin_inset Flex CharStyle:Code
11786 \begin_layout Plain Layout
11792 can be used to customize the layout parameters for footnotes, marginal
11793 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11794 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11795 define Flex insets.
11798 \begin_layout Standard
11800 \begin_inset Flex CharStyle:Code
11803 \begin_layout Plain Layout
11809 definition must begin with a line of the form:
11812 \begin_layout LyX-Code
11816 \begin_layout Standard
11818 \begin_inset Flex CharStyle:Code
11821 \begin_layout Plain Layout
11827 indicates the inset whose layout is being defined, and here there are two
11831 \begin_layout Enumerate
11832 The layout for a pre-existing inset is being modified.
11833 In this case, can be
11834 \begin_inset Flex CharStyle:Code
11837 \begin_layout Plain Layout
11843 any one of the following:
11844 \begin_inset Flex CharStyle:Code
11847 \begin_layout Plain Layout
11854 \begin_inset Flex CharStyle:Code
11857 \begin_layout Plain Layout
11864 \begin_inset Flex CharStyle:Code
11867 \begin_layout Plain Layout
11874 \begin_inset Flex CharStyle:Code
11877 \begin_layout Plain Layout
11884 \begin_inset Flex CharStyle:Code
11887 \begin_layout Plain Layout
11894 \begin_inset Flex CharStyle:Code
11897 \begin_layout Plain Layout
11904 \begin_inset Flex CharStyle:Code
11907 \begin_layout Plain Layout
11914 \begin_inset Flex CharStyle:Code
11917 \begin_layout Plain Layout
11924 \begin_inset Flex CharStyle:Code
11927 \begin_layout Plain Layout
11934 \begin_inset Flex CharStyle:Code
11937 \begin_layout Plain Layout
11944 \begin_inset Flex CharStyle:Code
11947 \begin_layout Plain Layout
11954 \begin_inset Flex CharStyle:Code
11957 \begin_layout Plain Layout
11964 \begin_inset Flex CharStyle:Code
11967 \begin_layout Plain Layout
11974 \begin_inset Flex CharStyle:Code
11977 \begin_layout Plain Layout
11984 \begin_inset Flex CharStyle:Code
11987 \begin_layout Plain Layout
11994 \begin_inset Flex CharStyle:Code
11997 \begin_layout Plain Layout
12004 \begin_inset Flex CharStyle:Code
12007 \begin_layout Plain Layout
12014 \begin_inset Flex CharStyle:Code
12017 \begin_layout Plain Layout
12024 \begin_inset Flex CharStyle:Code
12027 \begin_layout Plain Layout
12034 \begin_inset Flex CharStyle:Code
12037 \begin_layout Plain Layout
12047 \begin_layout Enumerate
12048 The layout for a Flex inset is being defined.
12050 \begin_inset Flex CharStyle:Code
12053 \begin_layout Plain Layout
12059 can be any valid identifier not used by a pre-existing inset.
12060 Note that the definition of a flex inset must
12065 \begin_inset Flex CharStyle:Code
12068 \begin_layout Plain Layout
12077 \begin_layout Standard
12079 \begin_inset Flex CharStyle:Code
12082 \begin_layout Plain Layout
12088 definition can contain the following entries:
12091 \begin_layout Description
12092 \begin_inset Flex CharStyle:Code
12095 \begin_layout Plain Layout
12101 The color for the inset's background.
12102 The valid colors are defined in
12103 \begin_inset Flex CharStyle:Code
12106 \begin_layout Plain Layout
12115 \begin_layout Description
12116 \begin_inset Flex CharStyle:Code
12119 \begin_layout Plain Layout
12125 As with paragraph styles (see page
12126 \begin_inset CommandInset ref
12128 reference "des:CopyStyle"
12135 \begin_layout Description
12136 \begin_inset Flex CharStyle:Code
12139 \begin_layout Plain Layout
12146 \begin_inset Flex CharStyle:Code
12149 \begin_layout Plain Layout
12158 \begin_inset Flex CharStyle:Code
12161 \begin_layout Plain Layout
12167 ] Indicates whether the user may employ the Paragraph Settings dialog to
12168 customize the paragraph.
12171 \begin_layout Description
12172 \begin_inset Flex CharStyle:Code
12175 \begin_layout Plain Layout
12182 \begin_inset Flex CharStyle:Code
12185 \begin_layout Plain Layout
12192 \begin_inset Flex CharStyle:Code
12195 \begin_layout Plain Layout
12202 \begin_inset Flex CharStyle:Code
12205 \begin_layout Plain Layout
12211 , describing the rendering style used for the inset's frame and buttons.
12212 Footnotes generally use
12213 \begin_inset Flex CharStyle:Code
12216 \begin_layout Plain Layout
12222 , ERT insets generally
12223 \begin_inset Flex CharStyle:Code
12226 \begin_layout Plain Layout
12232 , and character styles
12233 \begin_inset Flex CharStyle:Code
12236 \begin_layout Plain Layout
12245 \begin_layout Description
12246 \begin_inset Flex CharStyle:Code
12249 \begin_layout Plain Layout
12255 Required at the end of the InsetLayout declarations.
12258 \begin_layout Description
12259 \begin_inset Flex CharStyle:Code
12262 \begin_layout Plain Layout
12268 The font used for both the text body
12274 \begin_inset space ~
12278 \begin_inset CommandInset ref
12280 reference "sec:fonts"
12285 Note that defining this font automatically defines the
12286 \begin_inset Flex CharStyle:Code
12289 \begin_layout Plain Layout
12295 to the same value, so define this first and define
12296 \begin_inset Flex CharStyle:Code
12299 \begin_layout Plain Layout
12305 later if you want them to be different.
12308 \begin_layout Description
12309 \begin_inset Flex CharStyle:Code
12312 \begin_layout Plain Layout
12319 \begin_inset Quotes eld
12323 \begin_inset Quotes erd
12326 language, leading to Left-to-Right (latin) output, e.
12327 \begin_inset space \thinspace{}
12331 \begin_inset space \space{}
12334 in TeX code or URL.
12338 \begin_layout Description
12339 \begin_inset Flex CharStyle:Code
12342 \begin_layout Plain Layout
12349 \begin_inset Flex CharStyle:Code
12352 \begin_layout Plain Layout
12361 \begin_inset Flex CharStyle:Code
12364 \begin_layout Plain Layout
12370 ] Indicates whether the PlainLayout should be used or, instead, the user
12371 can change the paragraph style used in the inset.
12374 \begin_layout Description
12375 \begin_inset Flex CharStyle:Code
12378 \begin_layout Plain Layout
12384 As with paragraph styles (see page
12385 \begin_inset CommandInset ref
12386 LatexCommand pageref
12387 reference "des:FreeSpacing"
12394 \begin_layout Description
12395 \begin_inset Flex CharStyle:Code
12398 \begin_layout Plain Layout
12404 As with paragraph styles (see page
12405 \begin_inset CommandInset ref
12406 LatexCommand pageref
12407 reference "des:KeepEmpty"
12414 \begin_layout Description
12415 \begin_inset Flex CharStyle:Code
12418 \begin_layout Plain Layout
12424 The font used for the label.
12426 \begin_inset space ~
12430 \begin_inset CommandInset ref
12432 reference "sec:fonts"
12437 Note that this definition can never appear before
12438 \begin_inset Flex CharStyle:Code
12441 \begin_layout Plain Layout
12447 , lest it be ineffective.
12450 \begin_layout Description
12451 \begin_inset Flex CharStyle:Code
12454 \begin_layout Plain Layout
12460 What will be displayed on the button or elsewhere as the inset label.
12461 Some inset types (TeX code and Branch) modify this label on the fly.
12464 \begin_layout Description
12465 \begin_inset Flex CharStyle:Code
12468 \begin_layout Plain Layout
12474 The name of the corresponding LaTeX stuff.
12475 Either the environment or command name.
12478 \begin_layout Description
12479 \begin_inset Flex CharStyle:Code
12482 \begin_layout Plain Layout
12488 The optional parameter for the corresponding
12489 \begin_inset Flex CharStyle:Code
12492 \begin_layout Plain Layout
12498 stuff, including possible bracket pairs like
12499 \begin_inset Flex CharStyle:Code
12502 \begin_layout Plain Layout
12509 This parameter cannot be changed from within LyX.
12512 \begin_layout Description
12513 \begin_inset Flex CharStyle:Code
12516 \begin_layout Plain Layout
12522 As with paragraph styles (see page
12523 \begin_inset CommandInset ref
12524 LatexCommand pageref
12525 reference "des:LatexType"
12532 \begin_layout Description
12533 \begin_inset Flex CharStyle:Code
12536 \begin_layout Plain Layout
12543 \begin_inset Flex CharStyle:Code
12546 \begin_layout Plain Layout
12553 \begin_inset Flex CharStyle:Code
12556 \begin_layout Plain Layout
12563 \begin_inset Flex CharStyle:Code
12566 \begin_layout Plain Layout
12573 \begin_inset Flex CharStyle:Code
12576 \begin_layout Plain Layout
12582 (indicating a dummy definition ending definitions of charstyles, etc).
12583 This entry is required in and is only meaningful for Flex insets.
12584 Among other things, it determines on which menu this inset will appear.
12587 \begin_layout Description
12588 \begin_inset Flex CharStyle:Code
12591 \begin_layout Plain Layout
12598 \begin_inset Flex CharStyle:Code
12601 \begin_layout Plain Layout
12610 \begin_inset Flex CharStyle:Code
12613 \begin_layout Plain Layout
12619 ] Whether multiple paragraphs are permitted in this inset.
12620 This will also set CustomPars to the same value and ForcePlain to the opposite
12622 These can be reset to other values, if they are used
12629 \begin_layout Description
12630 \begin_inset Flex CharStyle:Code
12633 \begin_layout Plain Layout
12640 \begin_inset Flex CharStyle:Code
12643 \begin_layout Plain Layout
12652 \begin_inset Flex CharStyle:Code
12655 \begin_layout Plain Layout
12661 ] Whether fragile commands in this layout should be
12662 \begin_inset Flex CharStyle:Code
12665 \begin_layout Plain Layout
12678 whether the command should itself be protected.)
12681 \begin_layout Description
12682 \begin_inset Flex CharStyle:Code
12685 \begin_layout Plain Layout
12692 \begin_inset Flex CharStyle:Code
12695 \begin_layout Plain Layout
12704 \begin_inset Flex CharStyle:Code
12707 \begin_layout Plain Layout
12713 ] As with paragraph styles (see page
12714 \begin_inset CommandInset ref
12716 reference "des:PathThru"
12723 \begin_layout Description
12724 \begin_inset Flex CharStyle:Code
12727 \begin_layout Plain Layout
12733 As with paragraph styles (see page
12734 \begin_inset CommandInset ref
12735 LatexCommand pageref
12736 reference "des:Preamble"
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
12763 ] As with paragraph styles (see page
12764 \begin_inset CommandInset ref
12765 LatexCommand pageref
12766 reference "des:Requires"
12773 \begin_layout Subsection
12777 \begin_layout Standard
12778 \begin_inset CommandInset label
12784 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12786 \begin_inset Flex CharStyle:MenuItem
12789 \begin_layout Plain Layout
12796 \begin_inset Flex CharStyle:MenuItem
12799 \begin_layout Plain Layout
12805 , \SpecialChar \ldots{}
12806 ) in the text class itself.
12807 The standard counters are defined in the file
12808 \begin_inset Flex CharStyle:Code
12811 \begin_layout Plain Layout
12817 , so you may have to do no more than add
12820 \begin_layout LyX-Code
12821 Input stdcounters.inc
12824 \begin_layout Standard
12825 to your layout file to get them to work.
12826 But if you want to define custom counters, then you can do so.
12827 The counter declaration must begin with:
12830 \begin_layout LyX-Code
12834 \begin_layout Standard
12835 where of course `name' is replaced by the name of the counter.
12836 And it must end with
12837 \begin_inset Quotes eld
12841 \begin_inset Flex CharStyle:Code
12844 \begin_layout Plain Layout
12851 \begin_inset Quotes erd
12855 The following parameters can also be used:
12858 \begin_layout Description
12859 \begin_inset Flex CharStyle:Code
12862 \begin_layout Plain Layout
12863 LabelString [string=""]
12868 when this is defined, this string defines how the counter is displayed.
12869 Setting this value sets
12870 \begin_inset Flex CharStyle:Code
12873 \begin_layout Plain Layout
12874 LabelStringAppendix
12880 The following special constructs can be used in the string:
12884 \begin_layout Itemize
12885 \begin_inset Flex CharStyle:Code
12888 \begin_layout Plain Layout
12896 will be replaced by the expansion of the
12897 \begin_inset Flex CharStyle:Code
12900 \begin_layout Plain Layout
12907 \begin_inset Flex CharStyle:Code
12910 \begin_layout Plain Layout
12911 LabelStringAppendix
12917 \begin_inset Flex CharStyle:Code
12920 \begin_layout Plain Layout
12930 \begin_layout Itemize
12931 counter values can be expressed using LaTeX-like macros
12932 \begin_inset Flex CharStyle:Code
12935 \begin_layout Plain Layout
12952 \begin_inset Flex CharStyle:Code
12955 \begin_layout Plain Layout
12967 \begin_layout Plain Layout
12977 Actually, the situation is a bit more complicated: any
12996 other than those described below will produce arabic numerals.
12997 It would not be surprising to see this change in the future.
13003 \begin_inset Flex CharStyle:Code
13006 \begin_layout Plain Layout
13012 : 1, 2, 3,\SpecialChar \ldots{}
13014 \begin_inset Flex CharStyle:Code
13017 \begin_layout Plain Layout
13023 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13025 \begin_inset Flex CharStyle:Code
13028 \begin_layout Plain Layout
13034 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13036 \begin_inset Flex CharStyle:Code
13039 \begin_layout Plain Layout
13045 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13047 \begin_inset Flex CharStyle:Code
13050 \begin_layout Plain Layout
13056 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13058 \begin_inset Flex CharStyle:Code
13061 \begin_layout Plain Layout
13067 for hebrew numerals.
13071 \begin_layout Standard
13072 If LabelString is not defined, a default value is constructed as follows:
13073 if the counter has a master counter
13074 \begin_inset Flex CharStyle:Code
13077 \begin_layout Plain Layout
13084 \begin_inset Flex CharStyle:Code
13087 \begin_layout Plain Layout
13094 \begin_inset Flex CharStyle:Code
13097 \begin_layout Plain Layout
13107 is used; otherwise the string
13108 \begin_inset Flex CharStyle:Code
13111 \begin_layout Plain Layout
13122 \begin_layout Description
13123 \begin_inset Flex CharStyle:Code
13126 \begin_layout Plain Layout
13127 LabelStringAppendix [string=""]
13133 \begin_inset Flex CharStyle:Code
13136 \begin_layout Plain Layout
13142 , but for use in the Appendix.
13145 \begin_layout Description
13146 \begin_inset Flex CharStyle:Code
13149 \begin_layout Plain Layout
13156 \begin_inset Flex CharStyle:Code
13159 \begin_layout Plain Layout
13166 \begin_inset Quotes erd
13170 \begin_inset Quotes erd
13173 ] If this is set to the name of another counter, the present counter will
13174 be reset every time the other one is increased.
13176 \begin_inset Flex CharStyle:Code
13179 \begin_layout Plain Layout
13186 \begin_inset Flex CharStyle:Code
13189 \begin_layout Plain Layout
13198 \begin_layout Subsection
13202 \begin_layout Standard
13203 \begin_inset CommandInset label
13209 A font description looks like this:
13212 \begin_layout LyX-Code
13222 \begin_layout LyX-Code
13226 \begin_layout LyX-Code
13230 \begin_layout Standard
13231 The following commands are available:
13234 \begin_layout Description
13235 \begin_inset Flex CharStyle:Code
13238 \begin_layout Plain Layout
13245 \begin_inset Flex CharStyle:Code
13248 \begin_layout Plain Layout
13257 \begin_inset Flex CharStyle:Code
13260 \begin_layout Plain Layout
13267 \begin_inset Flex CharStyle:Code
13270 \begin_layout Plain Layout
13277 \begin_inset Flex CharStyle:Code
13280 \begin_layout Plain Layout
13287 \begin_inset Flex CharStyle:Code
13290 \begin_layout Plain Layout
13297 \begin_inset Flex CharStyle:Code
13300 \begin_layout Plain Layout
13307 \begin_inset Flex CharStyle:Code
13310 \begin_layout Plain Layout
13317 \begin_inset Flex CharStyle:Code
13320 \begin_layout Plain Layout
13327 \begin_inset Flex CharStyle:Code
13330 \begin_layout Plain Layout
13339 \begin_layout Description
13340 \begin_inset Flex CharStyle:Code
13343 \begin_layout Plain Layout
13352 \begin_inset Flex CharStyle:Code
13355 \begin_layout Plain Layout
13366 \begin_inset Flex CharStyle:Code
13369 \begin_layout Plain Layout
13376 \begin_inset Flex CharStyle:Code
13379 \begin_layout Plain Layout
13388 \begin_layout Description
13389 \begin_inset Flex CharStyle:Code
13392 \begin_layout Plain Layout
13399 \begin_inset Flex CharStyle:Code
13402 \begin_layout Plain Layout
13408 ] Valid argument are:
13409 \begin_inset Flex CharStyle:Code
13412 \begin_layout Plain Layout
13419 \begin_inset Flex CharStyle:Code
13422 \begin_layout Plain Layout
13429 \begin_inset Flex CharStyle:Code
13432 \begin_layout Plain Layout
13439 \begin_inset Flex CharStyle:Code
13442 \begin_layout Plain Layout
13449 \begin_inset Flex CharStyle:Code
13452 \begin_layout Plain Layout
13459 \begin_inset Flex CharStyle:Code
13462 \begin_layout Plain Layout
13469 Each of these turns on or off the corresponding attribute.
13472 \begin_layout Description
13473 \begin_inset Flex CharStyle:Code
13476 \begin_layout Plain Layout
13485 \begin_inset Flex CharStyle:Code
13488 \begin_layout Plain Layout
13499 \begin_inset Flex CharStyle:Code
13502 \begin_layout Plain Layout
13511 \begin_layout Description
13512 \begin_inset Flex CharStyle:Code
13515 \begin_layout Plain Layout
13524 \begin_inset Flex CharStyle:Code
13527 \begin_layout Plain Layout
13538 \begin_inset Flex CharStyle:Code
13541 \begin_layout Plain Layout
13548 \begin_inset Flex CharStyle:Code
13551 \begin_layout Plain Layout
13558 \begin_inset Flex CharStyle:Code
13561 \begin_layout Plain Layout
13570 \begin_layout Description
13571 \begin_inset Flex CharStyle:Code
13574 \begin_layout Plain Layout
13581 \begin_inset Flex CharStyle:Code
13584 \begin_layout Plain Layout
13591 \begin_inset Flex CharStyle:Code
13594 \begin_layout Plain Layout
13601 \begin_inset Flex CharStyle:Code
13604 \begin_layout Plain Layout
13613 \begin_inset Flex CharStyle:Code
13616 \begin_layout Plain Layout
13623 \begin_inset Flex CharStyle:Code
13626 \begin_layout Plain Layout
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
13665 \begin_layout Subsection
13666 Upgrading old layout files
13669 \begin_layout Standard
13670 The file format of layout files changes from time to time, so old layout
13671 files need to be converted.
13672 This process has been automated since LyX 1.4.0: If LyX reads an old format
13673 layout file it will call the conversion tool
13674 \begin_inset Flex CharStyle:Code
13677 \begin_layout Plain Layout
13678 LyXDir/scripts/layout2layout.py
13683 and convert it to a temporary file in current format.
13684 The original file is left untouched.
13685 If you want to convert the layout file permanently, just call the converter
13689 \begin_layout LyX-Code
13690 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13693 \begin_layout Standard
13694 (You need to replace
13695 \begin_inset Flex CharStyle:Code
13698 \begin_layout Plain Layout
13704 with the name of your LyX system directory, unless you happen to have defined
13705 such an environment variable.) Then copy
13706 \begin_inset Flex CharStyle:Code
13709 \begin_layout Plain Layout
13716 \begin_inset Flex CharStyle:Code
13719 \begin_layout Plain Layout
13728 \begin_layout Standard
13729 The automatic conversion only handles syntax changes.
13730 It cannot handle the case where the contents of included files was changed,
13731 so these will have to be converted separately.
13734 \begin_layout Section
13736 \begin_inset CommandInset label
13738 name "sec:templates"
13745 \begin_layout Standard
13746 Templates are created just like usual documents.
13747 The only difference is that usual documents contain all possible settings,
13748 including the font scheme and the paper size.
13749 Usually a user doesn't want a template to overwrite his defaults in these
13751 For that reason, the designer of a template should remove the corresponding
13753 \begin_inset Flex CharStyle:Code
13756 \begin_layout Plain Layout
13765 \begin_inset Flex CharStyle:Code
13768 \begin_layout Plain Layout
13776 from the template LyX file.
13777 This can be done with any simple text-editor, for example
13778 \begin_inset Flex CharStyle:Code
13781 \begin_layout Plain Layout
13788 \begin_inset Flex CharStyle:Code
13791 \begin_layout Plain Layout
13801 \begin_layout Standard
13802 Put the edited template files you create in
13803 \begin_inset Flex CharStyle:Code
13806 \begin_layout Plain Layout
13812 , copy the ones you use from the global template directory in
13813 \begin_inset Flex CharStyle:Code
13816 \begin_layout Plain Layout
13822 to the same place, and redefine the template path in the
13823 \begin_inset Flex CharStyle:MenuItem
13826 \begin_layout Plain Layout
13827 Tools\SpecialChar \menuseparator
13828 Preferences\SpecialChar \menuseparator
13837 \begin_layout Standard
13838 Note that there is a template which has a particular meaning:
13839 \begin_inset Flex CharStyle:Code
13842 \begin_layout Plain Layout
13849 This template is loaded every time you create a new document with
13850 \begin_inset Flex CharStyle:MenuItem
13853 \begin_layout Plain Layout
13854 File\SpecialChar \menuseparator
13860 in order to provide useful defaults.
13861 To create this template from inside LyX, all you have to do is to open
13862 a document with the correct settings, and use the
13863 \begin_inset Flex CharStyle:MenuItem
13866 \begin_layout Plain Layout
13867 Save as Document Defaults
13875 \begin_layout Chapter
13876 Including External Material
13879 \begin_layout Standard
13880 \begin_inset Box Shadowbox
13889 height_special "totalheight"
13892 \begin_layout Plain Layout
13893 WARNING: This portion of the documentation has not been updated for some
13895 We certainly hope that it is still accurate, but there are no guarantees.
13903 \begin_layout Standard
13904 The use of material from sources external to LyX is covered in detail in
13910 This part of the manual covers what needs to happen behind the scenes for
13911 new sorts of material to be included.
13914 \begin_layout Section
13918 \begin_layout Standard
13919 The external material feature is based on the concept of a
13924 A template is a specification of how LyX should interface with a certain
13926 As bundled, LyX comes with predefined templates for Xfig figures, various
13927 raster format images, chess diagrams, and LilyPond music notation.
13928 You can check the actual list by using the menu
13929 \begin_inset Flex CharStyle:MenuItem
13932 \begin_layout Plain Layout
13933 Insert\SpecialChar \menuseparator
13934 File\SpecialChar \menuseparator
13941 Furthermore, it is possible to roll your own template to support a specific
13943 Later we'll describe in more detail what is involved, and hopefully you
13944 will submit all the templates you create so we can include them in a later
13948 \begin_layout Standard
13949 Another basic idea of the external material feature is to distinguish between
13950 the original file that serves as a base for final material and the produced
13951 file that is included in your exported or printed document.
13952 For example, consider the case of a figure produced with
13953 \begin_inset Flex CharStyle:Code
13956 \begin_layout Plain Layout
13963 The Xfig application itself works on an original file with the
13964 \begin_inset Flex CharStyle:Code
13967 \begin_layout Plain Layout
13974 Within Xfig, you create and change your figure, and when you are done,
13976 \begin_inset Flex CharStyle:Code
13979 \begin_layout Plain Layout
13986 When you want to include the figure in your document, you invoke
13987 \begin_inset Flex CharStyle:Code
13990 \begin_layout Plain Layout
13996 in order to create a PostScript file that can readily be included in your
13999 \begin_inset Flex CharStyle:Code
14002 \begin_layout Plain Layout
14008 file is the original file, and the PostScript file is the produced file.
14011 \begin_layout Standard
14012 This distinction is important in order to allow updating of the material
14013 while you are in the process of writing the document.
14014 Furthermore, it provides us with the flexibility that is needed to support
14015 multiple export formats.
14016 For instance, in the case of a plain text file, it is not exactly an award-winn
14017 ing idea to include the figure as raw PostScript.
14018 Instead, you'd either prefer to just include a reference to the figure
14019 or try to invoke some graphics to ASCII converter to make the final result
14020 look similar to the real graphics.
14021 The external material management allows you to do this, because it is parametri
14022 zed on the different export formats that LyX supports.
14025 \begin_layout Standard
14026 Besides supporting the production of different products according to the
14027 exported format, it supports tight integration with editing and viewing
14029 In the case of an Xfig figure, you are able to invoke Xfig on the original
14030 file with a single click from within the external material dialog in LyX,
14031 and also preview the produced PostScript file with Ghostview with another
14033 No more fiddling around with the command line and/or file browsers to locate
14034 and manipulate the original or produced files.
14035 In this way, you are finally able to take full advantage of the many different
14036 applications that are relevant to use when you write your documents, and
14037 ultimately be more productive.
14040 \begin_layout Section
14041 The external template configuration file
14044 \begin_layout Standard
14045 It is relatively easy to add custom external template definitions to LyX.
14046 However, be aware that doing this in an careless manner most probably
14050 introduce an easily exploitable security hole.
14051 So before you do this, please read the discussion about security in section
14053 \begin_inset CommandInset ref
14055 reference "sec:Security-discussion"
14062 \begin_layout Standard
14063 Having said that, we encourage you to submit any interesting templates that
14068 \begin_layout Standard
14069 The external templates are defined in the
14070 \begin_inset Flex CharStyle:Code
14073 \begin_layout Plain Layout
14074 LyXDir/lib/external_templates
14080 You can place your own version in
14081 \begin_inset Flex CharStyle:Code
14084 \begin_layout Plain Layout
14085 UserDir/external_templates
14093 \begin_layout Standard
14094 A typical template looks like this:
14097 \begin_layout LyX-Code
14101 \begin_layout LyX-Code
14102 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14105 \begin_layout LyX-Code
14109 \begin_layout LyX-Code
14113 \begin_layout LyX-Code
14117 \begin_layout LyX-Code
14121 \begin_layout LyX-Code
14125 \begin_layout LyX-Code
14126 AutomaticProduction true
14129 \begin_layout LyX-Code
14133 \begin_layout LyX-Code
14137 \begin_layout LyX-Code
14141 \begin_layout LyX-Code
14142 TransformCommand Rotate RotationLatexCommand
14145 \begin_layout LyX-Code
14146 TransformCommand Resize ResizeLatexCommand
14149 \begin_layout LyX-Code
14150 Product "$$RotateFront$$ResizeFront
14153 \begin_layout LyX-Code
14158 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14161 \begin_layout LyX-Code
14162 $$ResizeBack$$RotateBack"
14165 \begin_layout LyX-Code
14169 \begin_layout LyX-Code
14170 UpdateResult "$$AbsPath$$Basename.pstex_t"
14173 \begin_layout LyX-Code
14174 Requirement "graphicx"
14177 \begin_layout LyX-Code
14178 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14181 \begin_layout LyX-Code
14182 ReferencedFile latex "$$AbsPath$$Basename.eps"
14185 \begin_layout LyX-Code
14186 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14189 \begin_layout LyX-Code
14193 \begin_layout LyX-Code
14197 \begin_layout LyX-Code
14198 TransformCommand Rotate RotationLatexCommand
14201 \begin_layout LyX-Code
14202 TransformCommand Resize ResizeLatexCommand
14205 \begin_layout LyX-Code
14206 Product "$$RotateFront$$ResizeFront
14209 \begin_layout LyX-Code
14214 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14217 \begin_layout LyX-Code
14218 $$ResizeBack$$RotateBack"
14221 \begin_layout LyX-Code
14222 UpdateFormat pdftex
14225 \begin_layout LyX-Code
14226 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14229 \begin_layout LyX-Code
14230 Requirement "graphicx"
14233 \begin_layout LyX-Code
14234 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14237 \begin_layout LyX-Code
14238 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14241 \begin_layout LyX-Code
14245 \begin_layout LyX-Code
14249 \begin_layout LyX-Code
14250 Product "$$Contents(
14252 "$$AbsPath$$Basename.asc
14257 \begin_layout LyX-Code
14258 UpdateFormat asciixfig
14261 \begin_layout LyX-Code
14262 UpdateResult "$$AbsPath$$Basename.asc"
14265 \begin_layout LyX-Code
14269 \begin_layout LyX-Code
14273 \begin_layout LyX-Code
14274 Product "<graphic fileref=
14276 "$$AbsOrRelPathMaster$$Basename.eps
14281 \begin_layout LyX-Code
14285 \begin_layout LyX-Code
14289 \begin_layout LyX-Code
14290 UpdateResult "$$AbsPath$$Basename.eps"
14293 \begin_layout LyX-Code
14294 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14297 \begin_layout LyX-Code
14298 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14301 \begin_layout LyX-Code
14305 \begin_layout LyX-Code
14306 Product "[XFig: $$FName]"
14309 \begin_layout LyX-Code
14313 \begin_layout LyX-Code
14317 \begin_layout Standard
14318 As you can see, the template is enclosed in
14319 \begin_inset Flex CharStyle:Code
14322 \begin_layout Plain Layout
14328 \SpecialChar \ldots{}
14330 \begin_inset Flex CharStyle:Code
14333 \begin_layout Plain Layout
14340 It contains a header specifying some general settings and, for each supported
14341 primary document file format, a section
14342 \begin_inset Flex CharStyle:Code
14345 \begin_layout Plain Layout
14351 \SpecialChar \ldots{}
14353 \begin_inset Flex CharStyle:Code
14356 \begin_layout Plain Layout
14365 \begin_layout Subsection
14366 The template header
14369 \begin_layout Description
14370 \begin_inset Flex CharStyle:Code
14373 \begin_layout Plain Layout
14374 AutomaticProduction
14375 \begin_inset space ~
14383 Whether the file represented by the template must be generated by LyX.
14384 This command must occur exactly once.
14387 \begin_layout Description
14388 \begin_inset Flex CharStyle:Code
14391 \begin_layout Plain Layout
14393 \begin_inset space ~
14401 A glob pattern that is used in the file dialog to filter out the desired
14403 If there is more than one possible file extension (e.
14404 \begin_inset space \thinspace{}
14408 \begin_inset space \space{}
14412 \begin_inset Flex CharStyle:Code
14415 \begin_layout Plain Layout
14422 \begin_inset Flex CharStyle:Code
14425 \begin_layout Plain Layout
14431 ), use something like
14432 \begin_inset Flex CharStyle:Code
14435 \begin_layout Plain Layout
14442 This command must occur exactly once.
14445 \begin_layout Description
14446 \begin_inset Flex CharStyle:Code
14449 \begin_layout Plain Layout
14451 \begin_inset space ~
14459 The text that is displayed on the button.
14460 This command must occur exactly once.
14463 \begin_layout Description
14464 \begin_inset Flex CharStyle:Code
14467 \begin_layout Plain Layout
14469 \begin_inset space ~
14473 \begin_inset space ~
14481 The help text that is used in the External dialog.
14482 Provide enough information to explain to the user just what the template
14483 can provide him with.
14484 This command must occur exactly once.
14487 \begin_layout Description
14488 \begin_inset Flex CharStyle:Code
14491 \begin_layout Plain Layout
14493 \begin_inset space ~
14501 The file format of the original file.
14502 This must be the name of a format that is known to LyX (see section
14503 \begin_inset CommandInset ref
14505 reference "sub:Formats"
14511 \begin_inset Quotes eld
14515 \begin_inset Flex CharStyle:Code
14518 \begin_layout Plain Layout
14525 \begin_inset Quotes erd
14528 if the template can handle original files of more than one format.
14529 LyX will attempt to interrogate the file itself in order to deduce its
14530 format in this case.
14531 This command must occur exactly once.
14534 \begin_layout Description
14535 \begin_inset Flex CharStyle:Code
14538 \begin_layout Plain Layout
14540 \begin_inset space ~
14548 A unique name for the template.
14549 It must not contain substitution macros (see below).
14552 \begin_layout Description
14553 \begin_inset Flex CharStyle:Code
14556 \begin_layout Plain Layout
14558 \begin_inset space ~
14561 Rotate|Resize|Clip|Extra
14566 This command specifies which transformations are supported by this template.
14567 It may occur zero or more times.
14568 This command enables the corresponding tabs in the external dialog.
14570 \begin_inset Flex CharStyle:Code
14573 \begin_layout Plain Layout
14579 command must have either a corresponding
14580 \begin_inset Flex CharStyle:Code
14583 \begin_layout Plain Layout
14590 \begin_inset Flex CharStyle:Code
14593 \begin_layout Plain Layout
14600 \begin_inset Flex CharStyle:Code
14603 \begin_layout Plain Layout
14610 Otherwise the transformation will not be supported by that format.
14613 \begin_layout Subsection
14617 \begin_layout Description
14618 \begin_inset Flex CharStyle:Code
14621 \begin_layout Plain Layout
14623 \begin_inset space ~
14626 LaTeX|PDFLaTeX|PlainText|DocBook
14631 The primary document file format that this format definition is for.
14632 Not every template has a sensible representation in all document file formats.
14633 Please define nevertheless a
14634 \begin_inset Flex CharStyle:Code
14637 \begin_layout Plain Layout
14643 section for all formats.
14644 Use a dummy text when no representation is available.
14645 Then you can at least see a reference to the external material in the exported
14649 \begin_layout Description
14650 \begin_inset Flex CharStyle:Code
14653 \begin_layout Plain Layout
14655 \begin_inset space ~
14659 \begin_inset space ~
14667 This command defines an additional macro
14668 \begin_inset Flex CharStyle:Code
14671 \begin_layout Plain Layout
14677 for substitution in
14678 \begin_inset Flex CharStyle:Code
14681 \begin_layout Plain Layout
14689 \begin_inset Flex CharStyle:Code
14692 \begin_layout Plain Layout
14698 itself may contain substitution macros.
14699 The advantage over using
14700 \begin_inset Flex CharStyle:Code
14703 \begin_layout Plain Layout
14710 \begin_inset Flex CharStyle:Code
14713 \begin_layout Plain Layout
14719 is that the substituted value of
14720 \begin_inset Flex CharStyle:Code
14723 \begin_layout Plain Layout
14729 is sanitized so that it is a valid optional argument in the document format.
14730 This command may occur zero or more times.
14733 \begin_layout Description
14734 \begin_inset Flex CharStyle:Code
14737 \begin_layout Plain Layout
14739 \begin_inset space ~
14747 The text that is inserted in the exported document.
14748 This is actually the most important command and can be quite complex.
14749 This command must occur exactly once.
14752 \begin_layout Description
14753 \begin_inset Flex CharStyle:Code
14756 \begin_layout Plain Layout
14758 \begin_inset space ~
14766 This command specifies a preamble snippet that will be included in the
14768 It has to be defined using
14769 \begin_inset Flex CharStyle:Code
14772 \begin_layout Plain Layout
14778 \SpecialChar \ldots{}
14780 \begin_inset Flex CharStyle:Code
14783 \begin_layout Plain Layout
14790 This command may occur zero or more times.
14793 \begin_layout Description
14794 \begin_inset Flex CharStyle:Code
14797 \begin_layout Plain Layout
14799 \begin_inset space ~
14803 \begin_inset space ~
14811 This command denotes files that are created by the conversion process and
14812 are needed for a particular export format.
14813 If the filename is relative, it is interpreted relative to the master document.
14814 This command may be given zero or more times.
14817 \begin_layout Description
14818 \begin_inset Flex CharStyle:Code
14821 \begin_layout Plain Layout
14823 \begin_inset space ~
14831 The name of a required LaTeX package.
14832 The package is included via
14833 \begin_inset Flex CharStyle:Code
14836 \begin_layout Plain Layout
14844 in the LaTeX preamble.
14845 This command may occur zero or more times.
14848 \begin_layout Description
14849 \begin_inset Flex CharStyle:Code
14852 \begin_layout Plain Layout
14854 \begin_inset space ~
14858 \begin_inset space ~
14861 RotationLatexCommand
14866 This command specifies that the built in LaTeX command should be used for
14868 This command may occur once or not at all.
14871 \begin_layout Description
14872 \begin_inset Flex CharStyle:Code
14875 \begin_layout Plain Layout
14877 \begin_inset space ~
14881 \begin_inset space ~
14889 This command specifies that the built in LaTeX command should be used for
14891 This command may occur once or not at all.
14894 \begin_layout Description
14895 \begin_inset Flex CharStyle:Code
14898 \begin_layout Plain Layout
14900 \begin_inset space ~
14904 \begin_inset space ~
14907 RotationLatexOption
14912 This command specifies that rotation is done via an optional argument.
14913 This command may occur once or not at all.
14916 \begin_layout Description
14917 \begin_inset Flex CharStyle:Code
14920 \begin_layout Plain Layout
14922 \begin_inset space ~
14926 \begin_inset space ~
14934 This command specifies that resizing is done via an optional argument.
14935 This command may occur once or not at all.
14938 \begin_layout Description
14939 \begin_inset Flex CharStyle:Code
14942 \begin_layout Plain Layout
14944 \begin_inset space ~
14948 \begin_inset space ~
14956 This command specifies that clipping is done via an optional argument.
14957 This command may occur once or not at all.
14960 \begin_layout Description
14961 \begin_inset Flex CharStyle:Code
14964 \begin_layout Plain Layout
14966 \begin_inset space ~
14970 \begin_inset space ~
14978 This command specifies that an extra optional argument is used.
14979 This command may occur once or not at all.
14982 \begin_layout Description
14983 \begin_inset Flex CharStyle:Code
14986 \begin_layout Plain Layout
14988 \begin_inset space ~
14996 The file format of the converted file.
14997 This must be the name of a format that is known to LyX (see the
14998 \begin_inset Flex CharStyle:MenuItem
15001 \begin_layout Plain Layout
15006 ools\SpecialChar \menuseparator
15011 references:Conversion
15017 This command must occur exactly once.
15020 \begin_layout Description
15021 \begin_inset Flex CharStyle:Code
15024 \begin_layout Plain Layout
15026 \begin_inset space ~
15034 The file name of the converted file.
15035 The file name must be absolute.
15036 This command must occur exactly once.
15039 \begin_layout Subsection
15040 Preamble definitions
15043 \begin_layout Standard
15044 The external template configuration file may contain additional preamble
15045 definitions enclosed by
15046 \begin_inset Flex CharStyle:Code
15049 \begin_layout Plain Layout
15055 \SpecialChar \ldots{}
15057 \begin_inset Flex CharStyle:Code
15060 \begin_layout Plain Layout
15067 They can be used by the templates in the
15068 \begin_inset Flex CharStyle:Code
15071 \begin_layout Plain Layout
15080 \begin_layout Section
15081 The substitution mechanism
15084 \begin_layout Standard
15085 When the external material facility invokes an external program, it is done
15086 on the basis of a command defined in the template configuration file.
15087 These commands can contain various macros that are expanded before execution.
15088 Execution always take place in the directory of the containing document.
15091 \begin_layout Standard
15092 Also, whenever external material is to be displayed, the name will be produced
15093 by the substitution mechanism, and most other commands in the template
15094 definition support substitution as well.
15097 \begin_layout Standard
15098 The available macros are the following:
15101 \begin_layout Description
15102 \begin_inset Flex CharStyle:Code
15105 \begin_layout Plain Layout
15106 $$AbsOrRelPathMaster
15111 The file path, absolute or relative to the master LyX document.
15114 \begin_layout Description
15115 \begin_inset Flex CharStyle:Code
15118 \begin_layout Plain Layout
15119 $$AbsOrRelPathParent
15124 The file path, absolute or relative to the LyX document.
15127 \begin_layout Description
15128 \begin_inset Flex CharStyle:Code
15131 \begin_layout Plain Layout
15137 The absolute file path.
15140 \begin_layout Description
15141 \begin_inset Flex CharStyle:Code
15144 \begin_layout Plain Layout
15150 The filename without path and without the extension.
15153 \begin_layout Description
15154 \begin_inset Flex CharStyle:Code
15157 \begin_layout Plain Layout
15159 \begin_inset Quotes eld
15163 \begin_inset Quotes erd
15171 This macro will expand to the contents of the file with the name
15172 \begin_inset Flex CharStyle:Code
15175 \begin_layout Plain Layout
15184 \begin_layout Description
15185 \begin_inset Flex CharStyle:Code
15188 \begin_layout Plain Layout
15194 The file extension (including the dot).
15197 \begin_layout Description
15198 \begin_inset Flex CharStyle:Code
15201 \begin_layout Plain Layout
15207 The filename of the file specified in the external material dialog.
15208 This is either an absolute name, or it is relative to the LyX document.
15211 \begin_layout Description
15212 \begin_inset Flex CharStyle:Code
15215 \begin_layout Plain Layout
15222 \begin_inset Flex CharStyle:Code
15225 \begin_layout Plain Layout
15231 (absolute name or relative to the LyX document).
15234 \begin_layout Description
15235 \begin_inset Flex CharStyle:Code
15238 \begin_layout Plain Layout
15244 The file path, relative to the master LyX document.
15247 \begin_layout Description
15248 \begin_inset Flex CharStyle:Code
15251 \begin_layout Plain Layout
15257 The file path, relative to the LyX document.
15260 \begin_layout Description
15261 \begin_inset Flex CharStyle:Code
15264 \begin_layout Plain Layout
15270 This macro will expand to the absolute path of the system directory.
15271 This is typically used to point to the various helper scripts that are
15275 \begin_layout Description
15276 \begin_inset Flex CharStyle:Code
15279 \begin_layout Plain Layout
15285 A name and full path to a temporary file which will be automatically deleted
15286 whenever the containing document is closed, or the external material insertion
15290 \begin_layout Standard
15291 All path macros contain a trailing directory separator, so you can construct
15293 \begin_inset space \thinspace{}
15297 \begin_inset space \space{}
15300 the absolute filename with
15301 \begin_inset Flex CharStyle:Code
15304 \begin_layout Plain Layout
15305 $$AbsPath$$Basename$$Extension
15313 \begin_layout Standard
15314 The macros above are substituted in all commands unless otherwise noted.
15316 \begin_inset Flex CharStyle:Code
15319 \begin_layout Plain Layout
15325 supports additionally the following substitutions if they are enabled by
15327 \begin_inset Flex CharStyle:Code
15330 \begin_layout Plain Layout
15337 \begin_inset Flex CharStyle:Code
15340 \begin_layout Plain Layout
15349 \begin_layout Description
15350 \begin_inset Flex CharStyle:Code
15353 \begin_layout Plain Layout
15359 The front part of the resize command.
15362 \begin_layout Description
15363 \begin_inset Flex CharStyle:Code
15366 \begin_layout Plain Layout
15372 The back part of the resize command.
15375 \begin_layout Description
15376 \begin_inset Flex CharStyle:Code
15379 \begin_layout Plain Layout
15385 The front part of the rotation command.
15388 \begin_layout Description
15389 \begin_inset Flex CharStyle:Code
15392 \begin_layout Plain Layout
15398 The back part of the rotation command.
15401 \begin_layout Standard
15402 The value string of the
15403 \begin_inset Flex CharStyle:Code
15406 \begin_layout Plain Layout
15412 command supports additionally the following substitutions if they are enabled
15414 \begin_inset Flex CharStyle:Code
15417 \begin_layout Plain Layout
15424 \begin_inset Flex CharStyle:Code
15427 \begin_layout Plain Layout
15436 \begin_layout Description
15437 \begin_inset Flex CharStyle:Code
15440 \begin_layout Plain Layout
15449 \begin_layout Description
15450 \begin_inset Flex CharStyle:Code
15453 \begin_layout Plain Layout
15462 \begin_layout Description
15463 \begin_inset Flex CharStyle:Code
15466 \begin_layout Plain Layout
15475 \begin_layout Description
15476 \begin_inset Flex CharStyle:Code
15479 \begin_layout Plain Layout
15485 The rotation option.
15488 \begin_layout Standard
15489 You may ask why there are so many path macros.
15490 There are mainly two reasons:
15493 \begin_layout Enumerate
15494 Relative and absolute file names should remain relative or absolute, respectivel
15496 Users may have reasons to prefer either form.
15497 Relative names are useful for portable documents that should work on different
15498 machines, for example.
15499 Absolute names may be required by some programs.
15502 \begin_layout Enumerate
15503 LaTeX treats relative file names differently than LyX and other programs
15504 in nested included files.
15505 For LyX, a relative file name is always relative to the document that contains
15507 For LaTeX, it is always relative to the master document.
15508 These two definitions are identical if you have only one document, but
15509 differ if you have a master document that includes part documents.
15510 That means that relative filenames must be transformed when presented to
15512 Fortunately LyX does this automatically for you if you choose the right
15516 \begin_layout Standard
15517 So which path macro should be used in new template definitions? The rule
15521 \begin_layout Itemize
15523 \begin_inset Flex CharStyle:Code
15526 \begin_layout Plain Layout
15532 if an absolute path is required.
15535 \begin_layout Itemize
15537 \begin_inset Flex CharStyle:Code
15540 \begin_layout Plain Layout
15541 $$AbsOrRelPathMaster
15546 if the substituted string is some kind of LaTeX input.
15549 \begin_layout Itemize
15551 \begin_inset Flex CharStyle:Code
15554 \begin_layout Plain Layout
15555 $$AbsOrRelPathParent
15560 in order to preserve the user's choice.
15563 \begin_layout Standard
15564 There are special cases where this rule does not work and e.
15565 \begin_inset space \thinspace{}
15569 \begin_inset space \space{}
15572 relative names are needed, but normally it will work just fine.
15573 One example for such a case is the command
15574 \begin_inset Flex CharStyle:Code
15577 \begin_layout Plain Layout
15578 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15583 in the XFig template above: We can't use the absolute name because the
15585 \begin_inset Flex CharStyle:Code
15588 \begin_layout Plain Layout
15594 files needs the relative name in order to rewrite the file content.
15597 \begin_layout Section
15598 \begin_inset CommandInset label
15600 name "sec:Security-discussion"
15604 Security discussion
15607 \begin_layout Standard
15608 \begin_inset Box Shadowbox
15617 height_special "totalheight"
15620 \begin_layout Plain Layout
15621 WARNING: This section is definitely outdated.
15629 \begin_layout Standard
15630 The external material feature interfaces with a lot of external programs
15631 and does so automatically, so we have to consider the security implications
15633 In particular, since you have the option of including your own filenames
15634 and/or parameter strings and those are expanded into a command, it seems
15635 that it would be possible to create a malicious document which executes
15636 arbitrary commands when a user views or prints the document.
15637 This is something we definitely want to avoid.
15640 \begin_layout Standard
15641 However, since the external program commands are specified in the template
15642 configuration file only, there are no security issues if LyX is properly
15643 configured with safe templates only.
15644 This is so because the external programs are invoked with the
15645 \begin_inset Flex CharStyle:Code
15648 \begin_layout Plain Layout
15654 -system call rather than the
15655 \begin_inset Flex CharStyle:Code
15658 \begin_layout Plain Layout
15664 system-call, so it's not possible to execute arbitrary commands from the
15665 filename or parameter section via the shell.
15668 \begin_layout Standard
15669 This also implies that you are restricted in what command strings you can
15670 use in the external material templates.
15671 In particular, pipes and redirection are not readily available.
15672 This has to be so if LyX should remain safe.
15673 If you want to use some of the shell features, you should write a safe
15674 script to do this in a controlled manner, and then invoke the script from
15675 the command string.
15677 \begin_inset Flex CharStyle:Code
15680 \begin_layout Plain Layout
15686 directory of the LyX installation, you can find a safe wrapper script
15687 \begin_inset Flex CharStyle:Code
15690 \begin_layout Plain Layout
15691 general_command_wrapper.py
15696 that supports redirection of input and output.
15697 That can serve as an example for how to write safe template scripts.
15698 For a more advanced example that uses
15699 \begin_inset Flex CharStyle:Code
15702 \begin_layout Plain Layout
15708 and friends, take a look at the
15709 \begin_inset Flex CharStyle:Code
15712 \begin_layout Plain Layout
15721 \begin_layout Standard
15722 It is possible to design a template that interacts directly with the shell,
15723 but since this would allow a malicious user to execute arbitrary commands
15724 by writing clever filenames and/or parameters, we generally recommend that
15725 you only use safe scripts that work with the
15726 \begin_inset Flex CharStyle:Code
15729 \begin_layout Plain Layout
15735 system call in a controlled manner.
15736 Of course, for use in a controlled environment, it can be tempting to just
15737 fall back to use ordinary shell scripts.
15738 If you do so, be aware that you
15742 provide an easily exploitable security hole in your system.
15743 Of course it stands to reason that such unsafe templates will never be
15744 included in the standard LyX distribution, although we do encourage people
15745 to submit new templates in the open source tradition.
15746 But LyX as shipped from the official distribution channels will never have
15750 \begin_layout Standard
15751 Including external material provides a lot of power, and you have to be
15752 careful not to introduce security hazards with this power.
15753 A subtle error in a single line in an innocent looking script can open
15754 the door to huge security problems.
15755 So if you do not fully understand the issues, we recommend that you consult
15756 a knowledgeable security professional or the LyX development team if you
15757 have any questions about whether a given template is safe or not.
15758 And do this before you use it in an uncontrolled environment.