1 #LyX 1.6.0rc4 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"
147 \begin_layout Standard
148 \begin_inset CommandInset toc
149 LatexCommand tableofcontents
156 \begin_layout Chapter
160 \begin_layout Standard
161 This manual covers the customization features present in LyX.
162 In it, we discuss issues like keyboard shortcuts, screen previewing options,
163 printer options, sending commands to LyX via the LyX Server, internationalizati
164 on, installing new LaTeX classes and LyX layouts, etc.
165 We can't possibly hope to touch on everything you can change---our developers
166 add new features faster than we can document them---but we will explain
167 the most common customizations and hopefully point you in the right direction
168 for some of the more obscure ones.
171 \begin_layout Standard
172 \begin_inset Branch OutDated
175 \begin_layout Standard
176 Information from previous versions of this document that now seems to be
177 outdated is contained in the OutDated branch of this document.
178 By default, this information will not appear in the LaTeX output.
186 \begin_layout Chapter
187 LyX configuration files
190 \begin_layout Standard
191 This chapter aims to help you to find your way through the LyX configuration
193 Before continuing to read this chapter, you should find out where your
194 LyX library and user directories are by using
195 \begin_inset Flex CharStyle:MenuItem
198 \begin_layout Plain Layout
203 elp\SpecialChar \menuseparator
216 The library directory is the place where LyX places its system-wide configurati
217 on files; the user directory is where you can place your modified versions.
218 We will call the former
219 \begin_inset Flex CharStyle:Code
222 \begin_layout Plain Layout
229 \begin_inset Flex CharStyle:MenuItem
232 \begin_layout Plain Layout
238 in the remainder of this document.
242 \begin_layout Section
244 \begin_inset Flex CharStyle:Code
247 \begin_layout Plain Layout
256 \begin_layout Standard
257 \begin_inset Flex CharStyle:Code
260 \begin_layout Plain Layout
266 and its sub-directories contain a number of files and that can be used
267 to customise LyX's behaviour.
268 You can change many of these files from within LyX itself through the
269 \begin_inset Flex CharStyle:MenuItem
272 \begin_layout Plain Layout
277 ools\SpecialChar \menuseparator
288 Most customization that you will want to do in LyX is possible through
290 However, many other inner aspects of LyX can be customized by modifying
292 \begin_inset Flex CharStyle:Code
295 \begin_layout Plain Layout
302 These files fall in different categories, described in the following subsection
306 \begin_layout Subsection
307 Automatically generated files
310 \begin_layout Standard
311 The files, which are to be found in
312 \begin_inset Flex CharStyle:MenuItem
315 \begin_layout Plain Layout
321 , are generated when you configure LyX.
322 They contain various default values that are guessed by inspection.
323 In general, it is not a good idea to modify them, since they might be overwritt
327 \begin_layout Labeling
328 \labelwidthstring 00.00.0000
329 \begin_inset Flex CharStyle:Code
332 \begin_layout Plain Layout
338 contains defaults for various commands.
341 \begin_layout Labeling
342 \labelwidthstring 00.00.0000
343 \begin_inset Flex CharStyle:Code
346 \begin_layout Plain Layout
352 contains the list of packages that have been recognized by LyX.
353 It is currently unused by the LyX program itself, but the information extracted
354 , and more, is made available with
355 \begin_inset Flex CharStyle:MenuItem
358 \begin_layout Plain Layout
363 elp\SpecialChar \menuseparator
380 \begin_layout Labeling
381 \labelwidthstring 00.00.0000
382 \begin_inset Flex CharStyle:Code
385 \begin_layout Plain Layout
391 the list of text classes that have been found in your
392 \begin_inset Flex CharStyle:Code
395 \begin_layout Plain Layout
401 directories, along with the associated LaTeX document class and their descripti
405 \begin_layout Labeling
406 \labelwidthstring 00.00.0000
407 \begin_inset Flex CharStyle:Code
410 \begin_layout Plain Layout
416 the list of layout modules found in your
417 \begin_inset Flex CharStyle:Code
420 \begin_layout Plain Layout
429 \begin_layout Labeling
430 \labelwidthstring 00.00.0000
431 \begin_inset Flex CharStyle:Code
434 \begin_layout Plain Layout
440 lists of various sorts of LaTeX-related files found on your system
443 \begin_layout Labeling
444 \labelwidthstring 00.00.0000
445 \begin_inset Flex CharStyle:Code
448 \begin_layout Plain Layout
454 is automatically generated during configuration from the file
455 \begin_inset Flex CharStyle:Code
458 \begin_layout Plain Layout
465 It contains information on your LaTeX configuration.
468 \begin_layout Subsection
472 \begin_layout Standard
473 These directories are duplicated between
474 \begin_inset Flex CharStyle:Code
477 \begin_layout Plain Layout
484 \begin_inset Flex CharStyle:Code
487 \begin_layout Plain Layout
494 If a particular files exists in both places, the one in
495 \begin_inset Flex CharStyle:Code
498 \begin_layout Plain Layout
507 \begin_layout Labeling
508 \labelwidthstring 00.00.0000
509 \begin_inset Flex CharStyle:Code
512 \begin_layout Plain Layout
518 this directory contains files with the extension
519 \begin_inset Flex CharStyle:Code
522 \begin_layout Plain Layout
528 that define the keybindings used in LyX.
529 If there exists an internationalized version of the bind file named
530 \begin_inset Flex CharStyle:Code
533 \begin_layout Plain Layout
539 , that will be used first.
542 \begin_layout Labeling
543 \labelwidthstring 00.00.0000
544 \begin_inset Flex CharStyle:Code
547 \begin_layout Plain Layout
553 contains graphics files that can be included in documents.
557 \begin_layout Labeling
558 \labelwidthstring 00.00.0000
559 \begin_inset Flex CharStyle:Code
562 \begin_layout Plain Layout
568 contains LyX documentation files (including the one you are currently reading).
570 \begin_inset Flex CharStyle:Code
573 \begin_layout Plain Layout
579 deserves special attention, as noted above.
580 If there exists an internationalized version of the help-document with
582 \begin_inset Flex CharStyle:Code
585 \begin_layout Plain Layout
591 prepended to the name, that will be used first.
597 \begin_inset CommandInset ref
599 reference "chap:i18n"
606 \begin_layout Labeling
607 \labelwidthstring 00.00.0000
608 \begin_inset Flex CharStyle:Code
611 \begin_layout Plain Layout
617 contains example files that explain how to use some features.
618 In the file browser, press the
619 \begin_inset Flex CharStyle:MenuItem
622 \begin_layout Plain Layout
631 \begin_layout Labeling
632 \labelwidthstring 00.00.0000
633 \begin_inset Flex CharStyle:Code
636 \begin_layout Plain Layout
642 contains image files that are used by the
643 \begin_inset Flex CharStyle:MenuItem
646 \begin_layout Plain Layout
653 In addition, it also contains the individual icons used in the toolbar
654 and the banners that can be shown when LyX is launched.
657 \begin_layout Labeling
658 \labelwidthstring 00.00.0000
659 \begin_inset Flex CharStyle:Code
662 \begin_layout Plain Layout
668 contains keyboard keymapping files.
674 \begin_inset CommandInset ref
676 reference "sec:keymap"
683 \begin_layout Labeling
684 \labelwidthstring 00.00.0000
685 \begin_inset Flex CharStyle:Code
688 \begin_layout Plain Layout
694 contains the text class and module files described in Chapter
699 \begin_inset CommandInset ref
701 reference "chap:textclass"
708 \begin_layout Labeling
709 \labelwidthstring 00.00.0000
710 \begin_inset Flex CharStyle:Code
713 \begin_layout Plain Layout
720 \begin_inset Flex CharStyle:Code
723 \begin_layout Plain Layout
729 Python scripts used to convert between LyX versions.
730 These can be run from the command line if, say, you want to batch-convert
734 \begin_layout Labeling
735 \labelwidthstring 00.00.0000
736 \begin_inset Flex CharStyle:Code
739 \begin_layout Plain Layout
745 contains some files that demonstrate the capabilities of the
746 \begin_inset Flex CharStyle:MenuItem
749 \begin_layout Plain Layout
760 Also contains some scripts used by LyX itself.
763 \begin_layout Labeling
764 \labelwidthstring 00.00.0000
765 \begin_inset Flex CharStyle:Code
768 \begin_layout Plain Layout
774 contains the standard LyX template files described in Chapter
779 \begin_inset CommandInset ref
781 reference "sec:templates"
788 \begin_layout Labeling
789 \labelwidthstring 00.00.0000
790 \begin_inset Flex CharStyle:Code
793 \begin_layout Plain Layout
799 contains files with the extension
800 \begin_inset Flex CharStyle:Code
803 \begin_layout Plain Layout
809 that define the user interface to LyX.
810 That is, the files define which items appear in which menus and the items
811 appearing on the toolbar.
814 \begin_layout Subsection
815 Files you don't want to modify
818 \begin_layout Standard
819 These files are used internally by LyX and you generally do not need to
820 modify them unless you are a developer.
823 \begin_layout Labeling
824 \labelwidthstring 00.00.0000
825 \begin_inset Flex CharStyle:Code
828 \begin_layout Plain Layout
834 this file contains the list of LyX developers.
835 The contents are displayed with the menu entry
836 \begin_inset Flex CharStyle:MenuItem
839 \begin_layout Plain Layout
844 elp\SpecialChar \menuseparator
857 \begin_layout Labeling
858 \labelwidthstring 00.00.0000
859 \begin_inset Flex CharStyle:Code
862 \begin_layout Plain Layout
868 this is a LaTeX script used during the configuration process.
872 \begin_layout Labeling
873 \labelwidthstring 00.00.0000
874 \begin_inset Flex CharStyle:Code
877 \begin_layout Plain Layout
883 this is the script that is used to re-configure LyX.
884 It creates configuration files in the directory it was run from.
887 \begin_layout Subsection
888 Other files needing a line or two...
891 \begin_layout Labeling
892 \labelwidthstring 00.00.0000
893 \begin_inset Flex CharStyle:Code
896 \begin_layout Plain Layout
902 this contains tables describing how different character encodings can be
906 \begin_layout Labeling
907 \labelwidthstring 00.00.0000
908 \begin_inset Flex CharStyle:Code
911 \begin_layout Plain Layout
917 this file contains the templates available to the new
918 \begin_inset Flex CharStyle:MenuItem
921 \begin_layout Plain Layout
934 \begin_layout Labeling
935 \labelwidthstring 00.00.0000
936 \begin_inset Flex CharStyle:Code
939 \begin_layout Plain Layout
945 this file contains a list of all the languages currently supported by LyX.
948 \begin_layout Section
949 Your local configuration directory
952 \begin_layout Standard
953 Even if you are using LyX as an unprivileged user, you might want to change
954 LyX configuration for your own use.
956 \begin_inset Flex CharStyle:Code
959 \begin_layout Plain Layout
965 directory contains all your personal configuration files.
966 This is the directory described as
967 \begin_inset Quotes eld
971 \begin_inset Quotes erd
975 \begin_inset Flex CharStyle:MenuItem
978 \begin_layout Plain Layout
983 elp\SpecialChar \menuseparator
994 This directory is used as a mirror of
995 \begin_inset Flex CharStyle:Code
998 \begin_layout Plain Layout
1004 , which means that every file in
1005 \begin_inset Flex CharStyle:Code
1008 \begin_layout Plain Layout
1014 is a replacement for the corresponding file in
1015 \begin_inset Flex CharStyle:Code
1018 \begin_layout Plain Layout
1025 Any configuration file described in the above sections can be placed either
1026 in the system-wide directory, in which case it will affect all users, or
1027 in your local directory for your own use.
1030 \begin_layout Standard
1031 To make things clearer, let's provide a few examples:
1034 \begin_layout Itemize
1035 The preferences set in the
1036 \begin_inset Flex CharStyle:MenuItem
1039 \begin_layout Plain Layout
1044 ools\SpecialChar \menuseparator
1054 dialog are saved to a file
1055 \begin_inset Flex CharStyle:Code
1058 \begin_layout Plain Layout
1065 \begin_inset Flex CharStyle:Code
1068 \begin_layout Plain Layout
1077 \begin_layout Itemize
1078 When you reconfigure using
1079 \begin_inset Flex CharStyle:MenuItem
1082 \begin_layout Plain Layout
1087 ools\SpecialChar \menuseparator
1098 \begin_inset Flex CharStyle:Code
1101 \begin_layout Plain Layout
1107 script, and the resulting files are written in your local configuration
1109 This means that any additional text class file that you might have added
1111 \begin_inset Flex CharStyle:Code
1114 \begin_layout Plain Layout
1120 will be added to the list of classes in the
1121 \begin_inset Flex CharStyle:MenuItem
1124 \begin_layout Plain Layout
1129 ocument\SpecialChar \menuseparator
1142 \begin_layout Itemize
1143 If you get some updated documentation from LyX ftp site and cannot install
1144 it because you do not have sysadmin rights on your system, you can just
1146 \begin_inset Flex CharStyle:Code
1149 \begin_layout Plain Layout
1155 and the items in the
1156 \begin_inset Flex CharStyle:MenuItem
1159 \begin_layout Plain Layout
1169 menu will open them!
1172 \begin_layout Section
1173 Running LyX with multiple configurations
1176 \begin_layout Standard
1177 The configuration freedom of the local configuration directory may not suffice
1178 if you want to have more than one configuration at your disposal.
1179 For example, you may want to be use different key bindings or printer settings
1181 You can achieve this by having several such directories.
1182 You then specify which directory to use at run-time.
1185 \begin_layout Standard
1186 Invoking LyX with the command line switch
1187 \begin_inset Flex CharStyle:Code
1190 \begin_layout Plain Layout
1200 instructs the program to read the configuration from that directory, and
1201 not from the default directory.
1202 (You can determine the default directory by running LyX without the
1203 \begin_inset Flex CharStyle:Code
1206 \begin_layout Plain Layout
1212 switch.) If the specified directory does not exist, LyX offers to create
1213 it for you, just like it does for the default directory on the first time
1214 you run the program.
1215 You can modify the configuration options in this additional user directory
1216 exactly as you would for the default directory.
1217 These directories are completely independent (but read on).
1218 Note that setting the environment variable
1219 \begin_inset Flex CharStyle:Code
1222 \begin_layout Plain Layout
1228 to some value has exactly the same effect.
1231 \begin_layout Standard
1232 Having several configurations also requires more maintenance: if you want
1233 to add a new layout to
1234 \begin_inset Flex CharStyle:Code
1237 \begin_layout Plain Layout
1243 which you want available from all your configurations, you must add it
1244 to each directory separately.
1245 You can avoid this with the following trick: after LyX creates the additional
1246 directory, most of the subdirectories (see above) are empty.
1247 If you want the new configuration to mirror an existing one, replace the
1248 empty subdirectory with a symbolic link to the matching subdirectory in
1249 the existing configuration.
1251 \begin_inset Flex CharStyle:Code
1254 \begin_layout Plain Layout
1260 subirectory, however, since it contains a file written by the configuration
1261 script (also accessible through
1262 \begin_inset Flex CharStyle:MenuItem
1265 \begin_layout Plain Layout
1270 ools\SpecialChar \menuseparator
1280 ) which is configuration-specific.
1283 \begin_layout Chapter
1284 The Preferences dialog
1287 \begin_layout Standard
1288 All options of the preferences dialog are described in the Appendix
1290 The Preferences Dialog
1297 For some options you might find here more details.
1300 \begin_layout Section
1301 Using the dialog for the first time
1304 \begin_layout Standard
1306 \begin_inset Flex CharStyle:Code
1309 \begin_layout Plain Layout
1315 file will contain only changes that you have made to the default behavior,
1316 some of which is hard-coded into LyX and some of which is contained in
1318 \begin_inset Flex CharStyle:Code
1321 \begin_layout Plain Layout
1322 LyXDir/lyxrc.defaults
1328 Note that in both files lines beginning with a
1329 \begin_inset Quotes eld
1333 \begin_inset Quotes erd
1336 are just comments and are not interpreted.
1337 However, only system administrators should edit
1338 \begin_inset Flex CharStyle:Code
1341 \begin_layout Plain Layout
1342 LyXDir/lyxrc.defaults
1348 Users should use the
1349 \begin_inset Flex CharStyle:MenuItem
1352 \begin_layout Plain Layout
1353 Tools\SpecialChar \menuseparator
1359 dialog to create and modify their own
1360 \begin_inset Flex CharStyle:Code
1363 \begin_layout Plain Layout
1372 \begin_layout Standard
1374 \begin_inset Flex CharStyle:MenuItem
1377 \begin_layout Plain Layout
1378 Tools\SpecialChar \menuseparator
1384 dialog will be largely self-explanatory.
1385 Most things in the dialog have associated `tool tips': hover your mouse
1386 pointer over something for more information.
1387 Before we highlight a few of the more important commands below, however,
1388 a word of warning: Applying some of your changes (e.g., screen fonts) will
1389 have an instant effect.
1391 changing the bind file) will not.
1392 If nothing appears to have changed, just
1393 \begin_inset Flex CharStyle:MenuItem
1396 \begin_layout Plain Layout
1402 the changes and restart LyX.
1405 \begin_layout Section
1409 \begin_layout Standard
1410 LyX has a powerful mechanism to convert to and from any file format using
1415 \begin_layout Subsection
1416 \begin_inset CommandInset label
1425 \begin_layout Standard
1426 The first step is to define your file formats if they are not already defined.
1428 \begin_inset Flex CharStyle:MenuItem
1431 \begin_layout Plain Layout
1432 Tools\SpecialChar \menuseparator
1433 Preferences\SpecialChar \menuseparator
1434 File Handling\SpecialChar \menuseparator
1442 \begin_inset Flex CharStyle:MenuItem
1445 \begin_layout Plain Layout
1446 New\SpecialChar \ldots{}
1452 button to define your new format.
1454 \begin_inset Flex CharStyle:MenuItem
1457 \begin_layout Plain Layout
1463 field contains the named used to identify the format in the GUI.
1465 \begin_inset Flex CharStyle:MenuItem
1468 \begin_layout Plain Layout
1474 is used to identify the format interally.
1475 You will also need to enter a file extension.
1476 These are all required.
1478 \begin_inset Flex CharStyle:MenuItem
1481 \begin_layout Plain Layout
1487 field is used to provide a keyboard shortcut on the menus.
1488 (For example, pressing
1489 \begin_inset Flex CharStyle:MenuItem
1492 \begin_layout Plain Layout
1499 \begin_inset Flex CharStyle:MenuItem
1502 \begin_layout Plain Layout
1503 View\SpecialChar \menuseparator
1512 \begin_layout Standard
1514 \begin_inset Flex CharStyle:MenuItem
1517 \begin_layout Plain Layout
1524 \begin_inset Flex CharStyle:MenuItem
1527 \begin_layout Plain Layout
1534 For example, you might want to use
1535 \begin_inset Flex CharStyle:MenuItem
1538 \begin_layout Plain Layout
1544 to view PostScript files.
1545 You can enter the command needed to start the program in the corresponding
1547 In defining this command, you can use the four variables listed in the
1549 The viewer is launched when you view an image in LyX or use the
1550 \begin_inset Flex CharStyle:MenuItem
1553 \begin_layout Plain Layout
1560 The editor is for example launched when you press the
1561 \begin_inset Flex CharStyle:MenuItem
1564 \begin_layout Plain Layout
1571 \begin_inset Flex CharStyle:MenuItem
1574 \begin_layout Plain Layout
1581 \begin_inset Flex CharStyle:MenuItem
1584 \begin_layout Plain Layout
1593 \begin_layout Standard
1595 \begin_inset Flex CharStyle:MenuItem
1598 \begin_layout Plain Layout
1604 option tells LyX that a format is suitable for document export.
1605 If this is is set and if a suitable conversion route exists (see
1606 \begin_inset CommandInset ref
1608 reference "sub:Converters"
1612 ), the format will appear in the
1613 \begin_inset Flex CharStyle:MenuItem
1616 \begin_layout Plain Layout
1617 File\SpecialChar \menuseparator
1624 The format will also appear in the
1625 \begin_inset Flex CharStyle:MenuItem
1628 \begin_layout Plain Layout
1634 menu if a viewer is specified for the format.
1635 Pure image formats, such as
1636 \begin_inset Flex CharStyle:Code
1639 \begin_layout Plain Layout
1645 , should not use this option.
1646 Formats that can both represent vector graphics and documents like
1647 \begin_inset Flex CharStyle:Code
1650 \begin_layout Plain Layout
1659 \begin_layout Standard
1661 \begin_inset Flex CharStyle:MenuItem
1664 \begin_layout Plain Layout
1665 Vector graphics format
1670 tells LyX that a format can contain vector graphics.
1671 This information is used to determine the target format of included graphics
1673 \begin_inset Flex CharStyle:MenuItem
1676 \begin_layout Plain Layout
1683 Included graphics may need to be converted to either
1684 \begin_inset Flex CharStyle:MenuItem
1687 \begin_layout Plain Layout
1694 \begin_inset Flex CharStyle:MenuItem
1697 \begin_layout Plain Layout
1704 \begin_inset Flex CharStyle:MenuItem
1707 \begin_layout Plain Layout
1714 \begin_inset Flex CharStyle:MenuItem
1717 \begin_layout Plain Layout
1723 cannot handle other image formats.
1724 If an included graphic is not already in
1725 \begin_inset Flex CharStyle:MenuItem
1728 \begin_layout Plain Layout
1735 \begin_inset Flex CharStyle:MenuItem
1738 \begin_layout Plain Layout
1745 \begin_inset Flex CharStyle:MenuItem
1748 \begin_layout Plain Layout
1754 format, it is converted to
1755 \begin_inset Flex CharStyle:MenuItem
1758 \begin_layout Plain Layout
1764 if the vector format option is set, and otherwise to
1765 \begin_inset Flex CharStyle:MenuItem
1768 \begin_layout Plain Layout
1777 \begin_layout Subsection
1781 \begin_layout Standard
1782 Since all conversions from one format to another take place in LyX's temporary
1783 directory, it is sometimes necessary to modify a file before copying it
1784 to the temporary directory in order that the conversion may be performed.
1788 \begin_layout Plain Layout
1789 For example, the file may refer to other files---images, for example---using
1790 relative file names, and these may become invalid when the file is copied
1791 to the temporary directory.
1796 This is done by a Copier: It copies a file to (or from) the temporary directory
1797 and may modify it in the process.
1800 \begin_layout Standard
1801 The definitions of the copiers may use four variables:
1804 \begin_layout Labeling
1805 \labelwidthstring 00.00.0000
1806 \begin_inset Flex CharStyle:Code
1809 \begin_layout Plain Layout
1815 The LyX system directory (e.
1816 \begin_inset space \thinspace{}
1820 \begin_inset space ~
1824 \begin_inset Flex CharStyle:MenuItem
1827 \begin_layout Plain Layout
1836 \begin_layout Labeling
1837 \labelwidthstring 00.00.0000
1838 \begin_inset Flex CharStyle:Code
1841 \begin_layout Plain Layout
1850 \begin_layout Labeling
1851 \labelwidthstring 00.00.0000
1852 \begin_inset Flex CharStyle:Code
1855 \begin_layout Plain Layout
1864 \begin_layout Labeling
1865 \labelwidthstring 00.00.0000
1866 \begin_inset Flex CharStyle:Code
1869 \begin_layout Plain Layout
1878 \begin_layout Standard
1879 The latter should be the filename as it would be used in a LaTeX's
1886 It is relevant only when exporting files suitable for such inclusion.
1889 \begin_layout Standard
1890 Copiers can be used to do almost anything with output files.
1891 For example, suppose you want generated pdf files to be copied to a special
1893 \begin_inset Flex CharStyle:Code
1896 \begin_layout Plain Layout
1903 Then you could write a shell script such as this one:
1906 \begin_layout Standard
1907 \begin_inset listings
1911 \begin_layout Plain Layout
1916 \begin_layout Plain Layout
1921 \begin_layout Plain Layout
1923 TOFILE=`basename $2`
1926 \begin_layout Plain Layout
1928 cp $FROMFILE /home/you/pdf/$TOFILE
1933 Save that in your local LyX directory---say,
1934 \begin_inset Flex CharStyle:Code
1937 \begin_layout Plain Layout
1938 /home/you/.lyx/scripts/pdfcopier.sh
1943 ---and make it executable, if you need to do so on your platform.
1945 \begin_inset Flex CharStyle:MenuItem
1948 \begin_layout Plain Layout
1949 Tools\SpecialChar \menuseparator
1956 \begin_inset Flex CharStyle:MenuItem
1959 \begin_layout Plain Layout
1965 format---or one of the other pdf formats---and enter
1966 \begin_inset Flex CharStyle:Code
1969 \begin_layout Plain Layout
1970 pdfcopier.sh $$i $$o
1976 \begin_inset Flex CharStyle:MenuItem
1979 \begin_layout Plain Layout
1989 \begin_layout Standard
1990 Copiers are used by LyX in various of its own conversions.
1991 For example, if appropriate programs are found, LyX will automatically
1992 install copiers for the
1993 \begin_inset Flex CharStyle:MenuItem
1996 \begin_layout Plain Layout
2003 \begin_inset Flex CharStyle:MenuItem
2006 \begin_layout Plain Layout
2008 \begin_inset space ~
2017 When these formats are exported, the copier sees that not just the main
2018 HTML file but various associated files (style files, images, etc.) are also
2020 All these files are written to a subdirectory of the directory in which
2021 the original LyX file was found.
2025 \begin_layout Plain Layout
2026 This copier can be customized.
2028 \begin_inset Quotes eld
2032 \begin_inset Quotes erd
2035 argument takes a comma-separated list of extensions to be copied; if it
2036 is omitted, all files will be copied.
2038 \begin_inset Quotes eld
2042 \begin_inset Quotes erd
2045 argument determines the extension added to the generated directory.
2047 \begin_inset Quotes eld
2051 \begin_inset Flex CharStyle:MenuItem
2054 \begin_layout Plain Layout
2061 \begin_inset Quotes erd
2064 , so HTML generated from
2065 \begin_inset Flex CharStyle:MenuItem
2068 \begin_layout Plain Layout
2069 /path/to/filename.lyx
2075 \begin_inset Flex CharStyle:MenuItem
2078 \begin_layout Plain Layout
2079 /path/to/filename.html.LyXconv
2093 \begin_layout Subsection
2094 \begin_inset CommandInset label
2096 name "sub:Converters"
2103 \begin_layout Standard
2104 You can define your own Converters to, uhh, convert files between different
2107 \begin_inset Flex CharStyle:MenuItem
2110 \begin_layout Plain Layout
2111 Tools\SpecialChar \menuseparator
2112 Preferences\SpecialChar \menuseparator
2113 File Handling\SpecialChar \menuseparator
2122 \begin_layout Standard
2123 To define a new converter, select the
2124 \begin_inset Flex CharStyle:MenuItem
2127 \begin_layout Plain Layout
2129 \begin_inset space ~
2138 \begin_inset space \thinspace{}
2142 \begin_inset Flex CharStyle:MenuItem
2145 \begin_layout Plain Layout
2147 \begin_inset space ~
2155 from the drop-down lists, enter the command needed for the conversion,
2157 \begin_inset Flex CharStyle:MenuItem
2160 \begin_layout Plain Layout
2167 Several variables can be used in the definition of converters:
2170 \begin_layout Labeling
2171 \labelwidthstring 00.00.0000
2172 \begin_inset Flex CharStyle:Code
2175 \begin_layout Plain Layout
2181 The LyX system directory
2184 \begin_layout Labeling
2185 \labelwidthstring 00.00.0000
2186 \begin_inset Flex CharStyle:Code
2189 \begin_layout Plain Layout
2198 \begin_layout Labeling
2199 \labelwidthstring 00.00.0000
2200 \begin_inset Flex CharStyle:Code
2203 \begin_layout Plain Layout
2212 \begin_layout Labeling
2213 \labelwidthstring 00.00.0000
2214 \begin_inset Flex CharStyle:Code
2217 \begin_layout Plain Layout
2223 The base filename of the input file (i.e., without the extension)
2226 \begin_layout Labeling
2227 \labelwidthstring 00.00.0000
2228 \begin_inset Flex CharStyle:Code
2231 \begin_layout Plain Layout
2237 The path to the input file
2240 \begin_layout Standard
2242 \begin_inset Flex CharStyle:MenuItem
2245 \begin_layout Plain Layout
2247 \begin_inset space ~
2255 field you can enter the following flags, separated by commas:
2258 \begin_layout Labeling
2259 \labelwidthstring 00.00.0000
2260 \begin_inset Flex CharStyle:Code
2263 \begin_layout Plain Layout
2269 This converter runs some form of LaTeX.
2270 This will make LyX's LaTeX error logs available.
2273 \begin_layout Labeling
2274 \labelwidthstring 00.00.0000
2275 \begin_inset Flex CharStyle:Code
2278 \begin_layout Plain Layout
2285 \begin_inset Flex CharStyle:MenuItem
2288 \begin_layout Plain Layout
2294 file for the conversion.
2297 \begin_layout Labeling
2298 \labelwidthstring 00.00.0000
2299 \begin_inset Flex CharStyle:Code
2302 \begin_layout Plain Layout
2311 \begin_layout Standard
2312 The following three flags are not really flags at all because they take
2314 \begin_inset Flex CharStyle:MenuItem
2317 \begin_layout Plain Layout
2319 \begin_inset space ~
2323 \begin_inset space ~
2334 \begin_layout Labeling
2335 \labelwidthstring 00.00.0000
2336 \begin_inset Flex CharStyle:Code
2339 \begin_layout Plain Layout
2345 If set, the converter's standard error will be redirected to a file
2346 \begin_inset Flex CharStyle:Code
2349 \begin_layout Plain Layout
2355 , and the script given as argument will be run as:
2356 \begin_inset Flex CharStyle:Code
2359 \begin_layout Plain Layout
2360 script <infile.out >infile.log
2366 The argument may contain
2367 \begin_inset Flex CharStyle:Code
2370 \begin_layout Plain Layout
2379 \begin_layout Labeling
2380 \labelwidthstring 00.00.0000
2381 \begin_inset Flex CharStyle:Code
2384 \begin_layout Plain Layout
2390 The name of the directory in which the converter will dump the generated
2392 LyX will not create this directory, and it does not copy anything into
2393 it, though it will copy this directory to the destination.
2394 The argument may contain
2395 \begin_inset Flex CharStyle:Code
2398 \begin_layout Plain Layout
2404 , which will be replaced by the base name of the input and output files,
2405 respectively, when the directory is copied.
2406 \begin_inset Newline newline
2409 Note that resultdir and usetempdir make no sense together.
2410 The latter will be ignored if the former is given.
2413 \begin_layout Labeling
2414 \labelwidthstring 00.00.0000
2415 \begin_inset Flex CharStyle:Code
2418 \begin_layout Plain Layout
2424 Determines the output file name and may, contain
2425 \begin_inset Flex CharStyle:Code
2428 \begin_layout Plain Layout
2435 Sensible only with resultdir and optional even then; if not given, it defaults
2439 \begin_layout Standard
2440 None of these last three are presently used in any of the converters that
2441 are installed with LyX.
2445 \begin_layout Standard
2446 You do not have to define converters between all the formats between which
2447 you want to convert.
2448 For example, you will note that there is no `LyX to PostScript®' converter,
2449 but LyX will export PostScript®.
2450 It does so by first creating a LaTeX file (no converter needs to be defined
2451 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2452 and finally converting the resulting DVI file to PostScript®.
2453 LyX finds such `chains' of converters automatically, and it will always
2454 choose the shortest possible chain.
2455 You can, though, still define multiple conversion methods between file
2457 For example, the standard LyX configuration provides three ways to convert
2458 LaTeX to PDF: Directly, using
2459 \begin_inset Flex CharStyle:MenuItem
2462 \begin_layout Plain Layout
2468 ; via (DVI and) PostScript®, using
2469 \begin_inset Flex CharStyle:MenuItem
2472 \begin_layout Plain Layout
2479 \begin_inset Flex CharStyle:MenuItem
2482 \begin_layout Plain Layout
2489 To define such alternate chains, you must define multiple target `file
2490 formats', as described in section
2491 \begin_inset CommandInset ref
2493 reference "sub:Formats"
2498 For example, in the standard configuration, the formats named
2499 \begin_inset Flex CharStyle:MenuItem
2502 \begin_layout Plain Layout
2509 \begin_inset Flex CharStyle:MenuItem
2512 \begin_layout Plain Layout
2519 \begin_inset Flex CharStyle:MenuItem
2522 \begin_layout Plain Layout
2528 are defined, all of which share the extension
2529 \begin_inset Flex CharStyle:MenuItem
2532 \begin_layout Plain Layout
2538 , and which correspond to the conversion methods just mentioned.
2541 \begin_layout Chapter
2542 Internationalizing LyX
2543 \begin_inset CommandInset label
2552 \begin_layout Standard
2553 LyX supports using a translated interface.
2554 Last time we checked, LyX provided text in thirty languages.
2555 The language of choice is called your
2560 (For further reading on locale settings, see also the documentation for
2561 locale that comes with your operating system.
2562 For Linux, the manual page for
2563 \begin_inset Flex CharStyle:Code
2566 \begin_layout Plain Layout
2572 could be a good place to start).
2575 \begin_layout Standard
2576 Notice that these translations will work, but do contain a few flaws.
2577 In particular, all dialogs have been designed with the English text in
2578 mind, which means that some of the translated text will be too large to
2579 fit within the space allocated.
2580 This is only a display problem and will not cause any harm.
2581 Also, you will find that some of the translations do not define shortcut
2582 keys for everything.
2583 Sometimes, there are simply not enough free letters to do it.
2584 Other times, the translator just hasn't got around to doing it yet.
2585 Our localization team, which you may wish to join,
2589 \begin_layout Plain Layout
2590 If you are a fluent speaker of a language other than English, joining these
2591 teams is a great way to give back to the LyX community!
2596 will of course try to fix these shortcomings in future versions of LyX.
2599 \begin_layout Section
2603 \begin_layout Subsection
2604 Translating the graphical user interface (text messages).
2607 \begin_layout Standard
2609 \begin_inset Flex CharStyle:Code
2612 \begin_layout Plain Layout
2618 library to handle the internationalization of the interface.
2619 To have LyX speak your favorite language in all menus and dialogs, you
2621 \begin_inset Flex CharStyle:Code
2624 \begin_layout Plain Layout
2630 -file for that language.
2631 When this is available, you'll have to generate a
2632 \begin_inset Flex CharStyle:Code
2635 \begin_layout Plain Layout
2641 -file from it and install the
2642 \begin_inset Flex CharStyle:Code
2645 \begin_layout Plain Layout
2652 The process of doing all of this is explained in the documentation for
2654 \begin_inset Flex CharStyle:Code
2657 \begin_layout Plain Layout
2664 It is possible to do this just for yourself, but if you're going to do
2665 it, you might as well share the results of your labors with the rest of
2667 Send a message to the LyX developers' list for more information about how
2671 \begin_layout Standard
2672 In short, this is what you should do (xx denotes the language code):
2675 \begin_layout Itemize
2676 Check out the LyX source code.
2678 \begin_inset CommandInset href
2680 name "information on the web"
2681 target "http://www.lyx.org/devel/cvs.php"
2688 \begin_layout Itemize
2690 \begin_inset Flex CharStyle:Code
2693 \begin_layout Plain Layout
2699 to the folder of the
2700 \begin_inset Flex CharStyle:Code
2703 \begin_layout Plain Layout
2711 \begin_inset Flex CharStyle:Code
2714 \begin_layout Plain Layout
2722 \begin_inset Flex CharStyle:Code
2725 \begin_layout Plain Layout
2731 doesn't exist anywhere, it can be remade with the console command
2732 \begin_inset Flex CharStyle:Code
2735 \begin_layout Plain Layout
2741 in that directory, or you can use an existing po-file for some other language
2745 \begin_layout Itemize
2747 \begin_inset Flex CharStyle:Code
2750 \begin_layout Plain Layout
2760 \begin_layout Plain Layout
2761 This is just a text file, so it can be edited in any text editor.
2762 But there are also specialized programs that support such editing, such
2767 (for all platforms) or
2776 contains a `mode' for editing
2777 \begin_inset Flex CharStyle:Code
2780 \begin_layout Plain Layout
2791 For some menu- and widget-labels, there are also shortcut keys that should
2793 Those keys are marked after a `|', and should be translated according to
2794 the words and phrases of the language.
2795 You should also fill also out the information at the beginning of the new
2797 \begin_inset Flex CharStyle:Code
2800 \begin_layout Plain Layout
2806 -file with your email-address, etc., so people know where to reach you with
2807 suggestions and entertaining flames.
2810 \begin_layout Standard
2811 If you are just doing this on your own, then:
2814 \begin_layout Itemize
2816 \begin_inset Flex CharStyle:Code
2819 \begin_layout Plain Layout
2826 This can be done with
2827 \begin_inset Flex CharStyle:Code
2830 \begin_layout Plain Layout
2831 msgfmt -o xx.mo < xx.po
2839 \begin_layout Itemize
2841 \begin_inset Flex CharStyle:Code
2844 \begin_layout Plain Layout
2850 -file to your locale-tree, at the correct directory for application messages
2855 xx, and under the name
2856 \begin_inset Flex CharStyle:Code
2859 \begin_layout Plain Layout
2867 \begin_inset Flex CharStyle:Code
2870 \begin_layout Plain Layout
2871 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2881 \begin_layout Standard
2882 As said, however, it would be best if the new
2883 \begin_inset Flex CharStyle:Code
2886 \begin_layout Plain Layout
2892 -file could be added to the LyX distribution, so others can use it.
2893 Adding it involves making additional changes to LyX.
2894 So send an email to the developers' mailing list if you're interested in
2898 \begin_layout Subsubsection
2902 \begin_layout Standard
2903 Sometimes it turns out that one English message needs to be translated into
2904 different messages in the target language.
2905 One example is the message
2906 \begin_inset Flex CharStyle:Code
2909 \begin_layout Plain Layout
2915 which has the German translation
2923 , depending upon exactly what the English
2924 \begin_inset Quotes eld
2928 \begin_inset Quotes erd
2933 \begin_inset Flex CharStyle:Code
2936 \begin_layout Plain Layout
2942 does not handle such ambigous translations.
2943 Therefore you have to add some context information to the message: Instead
2945 \begin_inset Flex CharStyle:Code
2948 \begin_layout Plain Layout
2955 \begin_inset Flex CharStyle:Code
2958 \begin_layout Plain Layout
2959 To[[as in 'From format x to format y']]
2965 \begin_inset Flex CharStyle:Code
2968 \begin_layout Plain Layout
2969 To[[as in 'From page x to page y']].
2974 Now the two occurences of
2975 \begin_inset Flex CharStyle:Code
2978 \begin_layout Plain Layout
2985 \begin_inset Flex CharStyle:Code
2988 \begin_layout Plain Layout
2994 and can be translated correctly to
3005 \begin_layout Standard
3006 Of course the context information needs to be stripped off the original
3007 message when no translation is used.
3008 Therefore you have to put it in double square brackets at the end of the
3009 message (see the example above).
3010 The translation mechanism of LyX ensures that everything in double square
3011 brackets at the end of messages is removed before displaying the message.
3014 \begin_layout Subsection
3015 Translating the documentation.
3018 \begin_layout Standard
3019 The online documentation (in the
3020 \begin_inset Flex CharStyle:MenuItem
3023 \begin_layout Plain Layout
3033 -menu) can (and should!) be translated.
3034 If there are translated versions of the documentation available
3038 \begin_layout Plain Layout
3039 As of March 2008, at least some of the documents have been translated into
3040 fourteen languages, with the Tutorial available in a few more.
3045 and the locale is set accordingly, these will be used automagically by
3047 LyX looks for translated versions as
3048 \begin_inset Flex CharStyle:Code
3051 \begin_layout Plain Layout
3052 LyXDir/doc/xx_DocName.lyx
3058 \begin_inset Flex CharStyle:Code
3061 \begin_layout Plain Layout
3067 is the code for the language currently in use.
3068 If there are no translated documents, the default English versions will
3070 Note that the translated versions must have the same filenames (
3071 \begin_inset Flex CharStyle:Code
3074 \begin_layout Plain Layout
3080 above) as the original.
3081 If you feel up to translating the documentation (an excellent way to proof-read
3082 the original documentation by the way!), there are a few things you should
3086 \begin_layout Itemize
3088 \begin_inset Flex CharStyle:Code
3091 \begin_layout Plain Layout
3097 , the guide to writing LyX documentation.
3098 Pay special attention to the translator's section.
3101 \begin_layout Itemize
3102 Check out the documentation translation web page at
3103 \begin_inset CommandInset href
3105 name "http://www.lyx.org/Translation"
3106 target "http://www.lyx.org/Translation"
3111 That way, you can find out which (if any) documents have already been translate
3112 d into your language.
3113 You can also find out who (if anyone) is organizing the effort to translate
3114 the documentation into your language.
3115 If no one is organizing the effort, please let us know that you're interested.
3118 \begin_layout Standard
3119 Once you get to actually translating, here's a few hints for you that may
3123 \begin_layout Itemize
3124 Join the documentation team! There is information on how to do that in
3125 \begin_inset Flex CharStyle:Code
3128 \begin_layout Plain Layout
3135 \begin_inset Flex CharStyle:MenuItem
3138 \begin_layout Plain Layout
3143 elp\SpecialChar \menuseparator
3153 ), which by the way is the first document you should translate.
3156 \begin_layout Itemize
3157 Learn the typographic conventions for the language you are translating to.
3158 Typography is an ancient art and over the centuries, a great variety of
3159 conventions have developed throughout different parts of the world.
3160 Also study the professional terminology amongst typographers in your country.
3161 Inventing your own terminology will only confuse the users.
3164 (Warning! Typography is addictive!)
3167 \begin_layout Itemize
3168 Make a copy of the document.
3169 This will be your working copy.
3170 You can use this as your personal translated help-file by placing it in
3172 \begin_inset Flex CharStyle:Code
3175 \begin_layout Plain Layout
3184 \begin_layout Itemize
3185 Sometimes the original document (from the LyX-team) will be updated.
3186 Use the source viewer at
3187 \begin_inset CommandInset href
3189 name "http://www.lyx.org/trac/timeline"
3190 target "http://www.lyx.org/trac/timeline"
3194 to see what has been changed.
3195 That way you can easily see which parts of the translated document need
3199 \begin_layout Standard
3200 If you ever find an error in the original document, fix it and notify the
3201 rest of the documentation team of the changes! (You didn't forget to join
3202 the documentation team, did you?)
3205 \begin_layout Standard
3206 \begin_inset Branch OutDated
3209 \begin_layout Section
3210 International Keyboard Support
3213 \begin_layout Standard
3216 [Editor's Note: The following section is by
3224 It needs to be fixed to conform to the new Documentation Style sheet and
3225 to make use of the new v1.0 features.
3226 The whole thing also needs to be merged with the section following it.-jw
3227 It may also be badly out of date.-rh (2008)]
3230 \begin_layout Subsection
3231 Defining Own Keymaps: Keymap File Format
3234 \begin_layout Standard
3235 Let's look at a keyboard definition file a little closer.
3236 It is a plain text file defining
3239 \begin_layout Itemize
3240 key-to-key or key-to-string translations
3243 \begin_layout Itemize
3247 \begin_layout Itemize
3248 dead keys exceptions
3251 \begin_layout Standard
3252 To define key-to-key or key-to-string translation, use this command:
3255 \begin_layout Quotation
3256 \begin_inset Flex CharStyle:Code
3259 \begin_layout Plain Layout
3268 \begin_inset Flex CharStyle:Code
3271 \begin_layout Plain Layout
3280 \begin_layout Standard
3282 \begin_inset Flex CharStyle:Code
3285 \begin_layout Plain Layout
3291 is the key to be translated and
3292 \begin_inset Flex CharStyle:Code
3295 \begin_layout Plain Layout
3301 is the string to be inserted into the document.
3302 To define dead keys, use:
3305 \begin_layout Quotation
3306 \begin_inset Flex CharStyle:Code
3309 \begin_layout Plain Layout
3318 \begin_inset Flex CharStyle:Code
3321 \begin_layout Plain Layout
3330 \begin_layout Standard
3332 \begin_inset Flex CharStyle:Code
3335 \begin_layout Plain Layout
3341 is a keyboard key and
3342 \begin_inset Flex CharStyle:Code
3345 \begin_layout Plain Layout
3352 The following dead keys are supported (shortcut name is in parentheses):
3355 \begin_layout Quotation
3359 \begin_inset space \hfill{}
3365 \begin_layout Quotation
3367 \begin_inset space \hfill{}
3373 \begin_layout Quotation
3375 \begin_inset space \hfill{}
3381 \begin_layout Quotation
3383 \begin_inset space \hfill{}
3389 \begin_layout Quotation
3391 \begin_inset space \hfill{}
3397 \begin_layout Quotation
3399 \begin_inset space \hfill{}
3406 \begin_layout Plain Layout
3418 \begin_layout Quotation
3420 \begin_inset space \hfill{}
3426 \begin_layout Quotation
3428 \begin_inset space \hfill{}
3435 \begin_layout Plain Layout
3447 \begin_layout Quotation
3449 \begin_inset space \hfill{}
3455 \begin_layout Quotation
3457 \begin_inset space \hfill{}
3463 \begin_layout Quotation
3465 \begin_inset space \hfill{}
3472 \begin_layout Plain Layout
3484 \begin_layout Quotation
3486 \begin_inset space \hfill{}
3493 \begin_layout Plain Layout
3505 \begin_layout Quotation
3507 \begin_inset space \hfill{}
3513 \begin_layout Quotation
3514 hungarian umlaut (hug)
3515 \begin_inset space \hfill{}
3521 \begin_layout Quotation
3523 \begin_inset space \hfill{}
3529 \begin_layout Quotation
3531 \begin_inset space \hfill{}
3538 \begin_layout Plain Layout
3550 \begin_layout Standard
3551 Since in many international keyboards there are exceptions to what some
3552 dead keys should do, you can define them using
3555 \begin_layout Quotation
3556 \begin_inset Flex CharStyle:Code
3559 \begin_layout Plain Layout
3567 deadkey key outstring
3570 \begin_layout Standard
3571 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3575 \begin_layout Quotation
3576 \begin_inset Flex CharStyle:Code
3579 \begin_layout Plain Layout
3592 \begin_layout Standard
3593 to make it work correctly.
3594 Also, you have to define as exceptions dead keys over i and j, to remove
3595 the dot from them before inserting an accent mark.
3596 I will change this when the time comes, but so far I haven't had time.
3599 \begin_layout Standard
3600 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3603 \begin_inset Flex CharStyle:Code
3606 \begin_layout Plain Layout
3612 have different meaning.
3614 \begin_inset Flex CharStyle:Code
3617 \begin_layout Plain Layout
3623 marks comments, quotes start and end LaTeX-style commands.
3624 To enter quote, you'll need to use
3625 \begin_inset Flex CharStyle:Code
3628 \begin_layout Plain Layout
3637 \begin_inset Flex CharStyle:Code
3640 \begin_layout Plain Layout
3647 \begin_inset Flex CharStyle:Code
3650 \begin_layout Plain Layout
3661 \begin_layout Standard
3662 If you make a keyboard description file that works for your language, please
3663 mail it to me, so I can include it in the next keymap distribution.
3666 \begin_layout Standard
3667 More keywords will be supported in keymap configuration file in future,
3671 \begin_layout Itemize
3672 \begin_inset Flex CharStyle:Code
3675 \begin_layout Plain Layout
3686 \begin_inset space \hfill{}
3690 \begin_inset Flex CharStyle:Code
3693 \begin_layout Plain Layout
3702 \begin_layout Itemize
3703 \begin_inset Flex CharStyle:Code
3706 \begin_layout Plain Layout
3717 \begin_inset space \hfill{}
3721 \begin_inset Flex CharStyle:Code
3724 \begin_layout Plain Layout
3730 an external keymap translation program
3733 \begin_layout Standard
3734 Also, it should look into
3735 \begin_inset Flex CharStyle:Code
3738 \begin_layout Plain Layout
3744 file for defaults, too (for example, a
3745 \begin_inset Flex CharStyle:Code
3748 \begin_layout Plain Layout
3756 option to include default keyboard).
3764 \begin_layout Section
3765 \begin_inset CommandInset label
3771 International Keymap Stuff
3774 \begin_layout Standard
3775 \begin_inset Note Note
3778 \begin_layout Plain Layout
3779 In doing the revisions on this document in March 2008, I did not look over
3780 this stuff, as I do not understand it.
3781 It would be good if someone else could do so.
3789 \begin_layout Standard
3790 The next two sections describe the
3791 \begin_inset Flex CharStyle:Code
3794 \begin_layout Plain Layout
3803 \begin_inset Flex CharStyle:Code
3806 \begin_layout Plain Layout
3814 file syntax in detail.
3815 These sections should help you design your own key map if the ones provided
3816 do not meet your needs.
3819 \begin_layout Subsection
3823 \begin_layout Standard
3827 \begin_inset Flex CharStyle:Code
3830 \begin_layout Plain Layout
3836 file maps keystrokes to characters or strings.
3837 As the name suggests, it sets a keyboard mapping.
3839 \begin_inset Flex CharStyle:Code
3842 \begin_layout Plain Layout
3853 \begin_inset Flex CharStyle:Code
3856 \begin_layout Plain Layout
3871 \begin_inset Flex CharStyle:Code
3874 \begin_layout Plain Layout
3887 \begin_inset Flex CharStyle:Code
3890 \begin_layout Plain Layout
3899 \begin_inset Flex CharStyle:Code
3902 \begin_layout Plain Layout
3910 are described in this section.
3913 \begin_layout Labeling
3914 \labelwidthstring 00.00.0000
3915 \begin_inset Flex CharStyle:Code
3918 \begin_layout Plain Layout
3926 Map a character to a string
3929 \begin_layout LyX-Code
3944 \begin_layout Standard
3977 the double-quote (")
3994 must be escaped with a preceding backslash (
4005 \begin_layout Standard
4007 \begin_inset Flex CharStyle:MenuItem
4010 \begin_layout Plain Layout
4018 statement to cause the symbol
4019 \begin_inset Flex CharStyle:MenuItem
4022 \begin_layout Plain Layout
4030 to be output for the keystroke
4031 \begin_inset Flex CharStyle:MenuItem
4034 \begin_layout Plain Layout
4045 \begin_layout LyX-Code
4051 \begin_layout Labeling
4052 \labelwidthstring 00.00.0000
4053 \begin_inset Flex CharStyle:Code
4056 \begin_layout Plain Layout
4064 Specify an accent character
4067 \begin_layout LyX-Code
4076 \begin_layout Standard
4077 This will make the cha
4115 This is the dead key
4119 \begin_layout Plain Layout
4126 refers to a key that does not produce a character by itself, but when followed
4127 with another key, produces the desired accent character.
4128 For example, a German characte
4130 r with an umlaut like
4140 can be produced in this manner.
4149 \begin_layout Standard
4162 and then another key not in
4179 followed by the other, unallowed key, as output.
4183 \begin_inset Flex CharStyle:MenuItem
4186 \begin_layout Plain Layout
4194 cancels a dead key, so if
4205 \begin_inset Flex CharStyle:MenuItem
4208 \begin_layout Plain Layout
4217 , the cursor will not go one position backwards but will instead cancel
4233 might have had on the next keystroke.
4237 \begin_layout Standard
4238 The following example specifies that the character ' is to be an acute accent,
4239 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4242 \begin_layout LyX-Code
4245 kmod ' acute aeiouAEIOU
4248 \begin_layout Labeling
4249 \labelwidthstring 00.00.0000
4250 \begin_inset Flex CharStyle:Code
4253 \begin_layout Plain Layout
4259 Specify an exception to the accent character
4262 \begin_layout LyX-Code
4271 \begin_layout Standard
4272 This defines an exce
4313 have been assigned a keystroke with a previous
4316 \begin_inset Flex CharStyle:Code
4319 \begin_layout Plain Layout
4343 must not belong in the
4390 If such a declaration does not exist in
4398 \begin_inset Flex CharStyle:Code
4401 \begin_layout Plain Layout
4435 \begin_inset Flex CharStyle:Code
4438 \begin_layout Plain Layout
4452 \begin_layout Standard
4453 The following command produces causes äi to be produced when you enter acute-i
4457 \begin_layout LyX-Code
4471 \begin_layout Labeling
4472 \labelwidthstring 00.00.0000
4473 \begin_inset Flex CharStyle:Code
4476 \begin_layout Plain Layout
4482 Combine two accent characters
4485 \begin_layout LyX-Code
4491 accent1 accent2 allowed
4494 \begin_layout Standard
4495 This one is getting pretty esoteric.
4496 It allows you to combine the effect
4552 \begin_inset Flex CharStyle:Code
4555 \begin_layout Plain Layout
4583 \begin_layout Standard
4584 Consider this example from the
4585 \begin_inset Flex CharStyle:Code
4588 \begin_layout Plain Layout
4599 \begin_layout LyX-Code
4602 kmod ; acute aeioyvhAEIOYVH
4606 kcomb acute umlaut iyIY
4609 \begin_layout Standard
4610 This allows you to press
4611 \begin_inset Flex CharStyle:MenuItem
4614 \begin_layout Plain Layout
4622 and get the effect of
4623 \begin_inset Flex CharStyle:Code
4626 \begin_layout Plain Layout
4645 in this case cancels the last dead key, so if you press
4646 \begin_inset Flex CharStyle:MenuItem
4649 \begin_layout Plain Layout
4658 \begin_inset Flex CharStyle:Code
4661 \begin_layout Plain Layout
4674 \begin_layout Subsection
4678 \begin_layout Standard
4680 \begin_inset Flex CharStyle:Code
4683 \begin_layout Plain Layout
4691 mapping is performed, a
4692 \begin_inset Flex CharStyle:Code
4695 \begin_layout Plain Layout
4705 file maps the strings that the symbols generate to characters in the current
4707 The LyX distribution currently includes at least the
4708 \begin_inset Flex CharStyle:Code
4711 \begin_layout Plain Layout
4720 \begin_inset Flex CharStyle:Code
4723 \begin_layout Plain Layout
4734 \begin_layout Standard
4736 \begin_inset Flex CharStyle:Code
4739 \begin_layout Plain Layout
4747 file is a sequence of declarations of the form
4750 \begin_layout LyX-Code
4763 \begin_layout Standard
4764 For example, in order to map
4765 \begin_inset Flex CharStyle:MenuItem
4768 \begin_layout Plain Layout
4778 to the corresponding character in the iso-8859-1 set (233), the following
4782 \begin_layout LyX-Code
4790 \begin_layout Standard
4792 \begin_inset Flex CharStyle:Code
4795 \begin_layout Plain Layout
4804 \begin_inset Flex CharStyle:Code
4807 \begin_layout Plain Layout
4825 the same character can apply to more than one string.
4827 \begin_inset Flex CharStyle:Code
4830 \begin_layout Plain Layout
4841 \begin_layout LyX-Code
4853 \begin_inset Newline newline
4869 \begin_layout Standard
4870 If LyX cannot find a mapping for the string produced by the keystroke or
4871 a deadkey sequence, it will check if it looks like an accented char and
4872 try to draw an accent over the character on screen.
4875 \begin_layout Subsection
4879 \begin_layout Standard
4880 There is a second way to add support for international characters through
4881 so-called dead-keys.
4882 A dead-key works in combination with a letter to produce an accented character.
4883 Here, we'll explain how to create a really simple dead-key to illustrate
4887 \begin_layout Standard
4888 Suppose you happen to need the circumflex character,
4889 \begin_inset Quotes eld
4893 \begin_inset Quotes erd
4898 \begin_inset Flex CharStyle:MenuItem
4901 \begin_layout Plain Layout
4908 \begin_inset space ~
4912 \begin_inset Flex CharStyle:MenuItem
4915 \begin_layout Plain Layout
4921 ] to the LyX command
4922 \begin_inset Flex CharStyle:Code
4925 \begin_layout Plain Layout
4932 \begin_inset Flex CharStyle:Code
4935 \begin_layout Plain Layout
4942 Now, whenever you type the
4943 \begin_inset Flex CharStyle:MenuItem
4946 \begin_layout Plain Layout
4952 -key followed by a letter, that letter will have a circumflex accent on
4954 For example, the sequence
4955 \begin_inset Quotes eld
4959 \begin_inset Flex CharStyle:MenuItem
4962 \begin_layout Plain Layout
4969 \begin_inset Quotes erd
4972 produces the letter:
4973 \begin_inset Quotes eld
4977 \begin_inset Quotes erd
4981 If you tried to type
4982 \begin_inset Quotes eld
4986 \begin_inset Flex CharStyle:MenuItem
4989 \begin_layout Plain Layout
4996 \begin_inset Quotes erd
4999 , however, LyX will complain with a beep, since a
5000 \begin_inset Quotes eld
5004 \begin_inset Flex CharStyle:MenuItem
5007 \begin_layout Plain Layout
5014 \begin_inset Quotes erd
5017 never takes a circumflex accent.
5019 \begin_inset Flex CharStyle:MenuItem
5022 \begin_layout Plain Layout
5028 after a dead-key produces the bare-accent.
5029 Please note this last point! If you bind a key to a dead-key, you'll need
5030 to rebind the character on that key to yet another key.
5032 \begin_inset Flex CharStyle:MenuItem
5035 \begin_layout Plain Layout
5041 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5044 \begin_layout Standard
5045 One common way to bind dead-keys is to use
5046 \begin_inset Flex CharStyle:MenuItem
5049 \begin_layout Plain Layout
5056 \begin_inset Flex CharStyle:MenuItem
5059 \begin_layout Plain Layout
5066 \begin_inset Flex CharStyle:MenuItem
5069 \begin_layout Plain Layout
5075 in combination with an accent, like
5076 \begin_inset Quotes eld
5080 \begin_inset Flex CharStyle:MenuItem
5083 \begin_layout Plain Layout
5090 \begin_inset Quotes erd
5094 \begin_inset Quotes eld
5098 \begin_inset Flex CharStyle:MenuItem
5101 \begin_layout Plain Layout
5108 \begin_inset Quotes erd
5112 \begin_inset Quotes eld
5116 \begin_inset Flex CharStyle:MenuItem
5119 \begin_layout Plain Layout
5126 \begin_inset Quotes erd
5130 Another way involves using
5131 \begin_inset Flex CharStyle:Code
5134 \begin_layout Plain Layout
5141 \begin_inset Flex CharStyle:Code
5144 \begin_layout Plain Layout
5150 to set up the special
5151 \begin_inset Flex CharStyle:Code
5154 \begin_layout Plain Layout
5162 \begin_inset Flex CharStyle:Code
5165 \begin_layout Plain Layout
5171 acts in some ways just like
5172 \begin_inset Flex CharStyle:MenuItem
5175 \begin_layout Plain Layout
5181 and permits you to bind keys to accented characters.
5182 You can also turn keys into dead-keys by binding them to something like
5184 \begin_inset Flex CharStyle:Code
5187 \begin_layout Plain Layout
5193 and then binding this symbolic key to the corresponding LyX command.
5197 \begin_layout Plain Layout
5202 : This is exactly what I do in my
5203 \begin_inset Flex CharStyle:Code
5206 \begin_layout Plain Layout
5213 \begin_inset Flex CharStyle:Code
5216 \begin_layout Plain Layout
5224 \begin_inset Flex CharStyle:MenuItem
5227 \begin_layout Plain Layout
5229 \begin_inset space ~
5238 \begin_inset Flex CharStyle:Code
5241 \begin_layout Plain Layout
5247 and a bunch of these
5248 \begin_inset Quotes eld
5252 \begin_inset Flex CharStyle:Code
5255 \begin_layout Plain Layout
5262 \begin_inset Quotes erd
5265 symbolic keys bound such things as
5266 \begin_inset Flex CharStyle:MenuItem
5269 \begin_layout Plain Layout
5271 \begin_inset space ~
5280 \begin_inset Flex CharStyle:MenuItem
5283 \begin_layout Plain Layout
5285 \begin_inset space ~
5294 This is how I produce my accented characters.
5299 You can make just about anything into the
5300 \begin_inset Flex CharStyle:Code
5303 \begin_layout Plain Layout
5310 \begin_inset Flex CharStyle:MenuItem
5313 \begin_layout Plain Layout
5319 keys, a spare function key, etc.
5320 As for the LyX commands that produce accents, check the entry for
5321 \begin_inset Flex CharStyle:Code
5324 \begin_layout Plain Layout
5335 You'll find the complete list there.
5338 \begin_layout Subsection
5339 Saving your Language Configuration
5342 \begin_layout Standard
5343 You can edit your preferences so that your desired language environment
5344 is automatically configured when LyX starts up, via the
5345 \begin_inset Flex CharStyle:MenuItem
5348 \begin_layout Plain Layout
5353 dit\SpecialChar \menuseparator
5366 \begin_layout Chapter
5367 Installing New Document Classes, Layouts, and Templates
5368 \begin_inset CommandInset label
5370 name "chap:textclass"
5378 \begin_layout Plain Layout
5379 Installing New Document Classes
5387 \begin_layout Standard
5388 In this chapter, we describe the procedures for creating and installing
5389 new LyX layout and template files, as well as offer a refresher on correctly
5390 installing new LaTeX document classes.
5391 Some definitions: a document class is a LaTeX file (usually ending in
5392 \begin_inset Flex CharStyle:Code
5395 \begin_layout Plain Layout
5402 \begin_inset Flex CharStyle:Code
5405 \begin_layout Plain Layout
5411 ) that describes the format of a document such as an article, report, journal
5412 preprint, etc, and all the commands needed to realize that format.
5413 A layout file is a LyX file that corresponds to a LaTeX document class
5414 and that tells LyX how to
5415 \begin_inset Quotes eld
5419 \begin_inset Quotes erd
5422 things on the screen to make the display look something like the final
5424 More precisely, a layout file describes a
5425 \begin_inset Quotes eld
5429 \begin_inset Quotes erd
5432 which is the internal construct LyX uses to render the screen display.
5434 \begin_inset Quotes eld
5438 \begin_inset Quotes erd
5442 \begin_inset Quotes eld
5446 \begin_inset Quotes erd
5449 can be used somewhat interchangeably, but it is better to refer to the
5450 file as the layout, and the thing living in LyX's memory as the text class.
5451 A template file is simply a LyX document that contains a set of predefined
5452 entries for a given document class---entries that are generally required
5454 Templates are especially useful for things like journal manuscripts that
5455 are to be submitted electronically.
5458 \begin_layout Section
5459 Installing a new LaTeX package
5462 \begin_layout Standard
5463 Some installations may not include a LaTeX package that you would like to
5465 For example, you might need FoilTeX, a package for preparing slides or
5466 viewgraphs for overhead projectors.
5467 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5468 a user interface for that.
5469 For example on MiKTeX you start its program
5470 \begin_inset Quotes eld
5474 \begin_inset Quotes erd
5477 to get a list of available packages.
5478 To install one, right click on it or use the installing toolbar button.
5479 When the package you want to install is not in the list, but you have it
5481 \begin_inset Flex CharStyle:Code
5484 \begin_layout Plain Layout
5491 \begin_inset Flex CharStyle:Code
5494 \begin_layout Plain Layout
5500 -file, then copy these files to a subfolder of your LaTeX distribution,
5501 for example to the folder
5510 Then update the file name database of your LaTeX-distribution.
5511 For example on MiKTeX this is done by pressing the button
5514 \begin_inset space ~
5519 that you find in MiKTeX's
5520 \begin_inset Quotes eld
5524 \begin_inset Quotes erd
5528 In both cases you need afterwards to reconfigure LyX using the menu
5529 \begin_inset Flex CharStyle:MenuItem
5532 \begin_layout Plain Layout
5533 Tools\SpecialChar \menuseparator
5539 and then to restart LyX.
5542 \begin_layout Standard
5543 If your LaTeX distribution doesn't provide a user interface, then you can
5544 follow these steps by using a UNIX/Linux console.
5547 \begin_layout Enumerate
5548 Get the package from
5549 \begin_inset CommandInset href
5552 target "http://www.ctan.org/"
5559 \begin_layout Enumerate
5560 You can install this package in several different places.
5561 If you want it to be available for all users on your system, then you should
5562 install it in your `local' TeX tree; if you want (or need) it to be available
5563 just for you, then you can install it in your own `user' TeX tree.
5564 Where these should be created, if they do not already exist, depends upon
5565 the details of your system.
5566 To find out, look in the file
5567 \begin_inset Flex CharStyle:Code
5570 \begin_layout Plain Layout
5580 \begin_layout Plain Layout
5581 This usually lives in the directory
5582 \begin_inset Flex CharStyle:Code
5585 \begin_layout Plain Layout
5591 , though you can run
5592 \begin_inset Flex CharStyle:Code
5595 \begin_layout Plain Layout
5606 The location of the `local' TeX tree is defined by
5607 \begin_inset Flex CharStyle:Code
5610 \begin_layout Plain Layout
5616 ; this is usually somewhere like
5617 \begin_inset Flex CharStyle:Code
5620 \begin_layout Plain Layout
5621 /usr/local/share/texmf/
5627 The `user' TeX tree is defined by
5628 \begin_inset Flex CharStyle:Code
5631 \begin_layout Plain Layout
5638 \begin_inset Flex CharStyle:Code
5641 \begin_layout Plain Layout
5648 (If these variables are not predefined, you can define them.) You'll probably
5649 need root permissions to create or modify the `local' tree; but your `user'
5650 tree shouldn't have such limitations.
5653 \begin_layout Enumerate
5655 \begin_inset Flex CharStyle:Code
5658 \begin_layout Plain Layout
5665 \begin_inset Flex CharStyle:Code
5668 \begin_layout Plain Layout
5675 \begin_inset Flex CharStyle:Code
5678 \begin_layout Plain Layout
5685 \begin_inset Newline newline
5689 \begin_inset Flex CharStyle:Code
5692 \begin_layout Plain Layout
5693 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5699 \begin_inset Newline newline
5702 But, again, most of this will
5703 \begin_inset Quotes eld
5707 \begin_inset Quotes erd
5713 \begin_layout Enumerate
5718 \begin_layout Plain Layout
5719 We'll assume henceforth that you're defining `local' TeX tree.
5720 If you're defining a user tree, just adjust as necessary.
5726 You must follow the directory structure of your existing
5727 \begin_inset Flex CharStyle:Code
5730 \begin_layout Plain Layout
5736 directory, which will be found at
5737 \begin_inset Flex CharStyle:Code
5740 \begin_layout Plain Layout
5747 For example, latex packages should go under
5748 \begin_inset Flex CharStyle:Code
5751 \begin_layout Plain Layout
5752 $TEXMFLOCAL/tex/latex/
5760 \begin_layout Enumerate
5761 Install the package.
5762 For example, you would unpack the FoilTeX tarball and copy it to
5763 \begin_inset Flex CharStyle:Code
5766 \begin_layout Plain Layout
5767 $TEXMFLOCAL/tex/latex/foiltex
5774 \begin_inset Flex CharStyle:Code
5777 \begin_layout Plain Layout
5783 directory contains various files.
5786 \begin_layout Enumerate
5788 \begin_inset Flex CharStyle:Code
5791 \begin_layout Plain Layout
5799 \begin_inset Flex CharStyle:Code
5802 \begin_layout Plain Layout
5811 \begin_layout Standard
5812 Your package is now installed and available to LaTeX.
5813 To make it available to LyX, you need to create a Layout file, if one is
5814 not already available.
5815 (See the next section.) Once you have a layout file, you need only reconfigure
5817 \begin_inset Flex CharStyle:MenuItem
5820 \begin_layout Plain Layout
5821 Tools\SpecialChar \menuseparator
5827 ) and then restart LyX.
5828 You should then see your new package---for example
5829 \begin_inset Flex CharStyle:MenuItem
5832 \begin_layout Plain Layout
5839 \begin_inset Flex CharStyle:MenuItem
5842 \begin_layout Plain Layout
5843 Document\SpecialChar \menuseparator
5850 \begin_inset Flex CharStyle:MenuItem
5853 \begin_layout Plain Layout
5863 \begin_layout Section
5867 \begin_layout Standard
5868 This section describes how to write and install your own LyX layout files
5869 and walks through the
5870 \begin_inset Flex CharStyle:Code
5873 \begin_layout Plain Layout
5879 text class format as an example.
5881 \begin_inset Flex CharStyle:Code
5884 \begin_layout Plain Layout
5890 files describe what paragraph and character styles are available for a
5891 given document class and how LyX should display them.
5892 We try to provide a thorough description of the process here; however,
5893 there are so many different types of documents supported by LaTeX classes
5894 that we can't hope to cover every different possibility or problem you
5896 (The LyX users' list is frequented by people with lots of experience with
5897 layout design who are willing to share what they've learned.)
5900 \begin_layout Standard
5901 As you prepare to write a new layout, it is extremely helpful to look at
5902 the example layouts distributed with LyX.
5903 If you use a nice LaTeX document class that might be of interest for others,
5904 too, and have a nice corresponding LyX layout, feel free to contribute
5905 the stuff to us, so we may put it into the distribution.
5907 \begin_inset CommandInset href
5909 name "section on the LyX wiki"
5910 target "http://wiki.lyx.org/Layouts/Layouts"
5914 for this kind of material.
5917 \begin_layout Standard
5918 All the tags described in this chapter are case-insensitive; this means
5920 \begin_inset Flex CharStyle:Code
5923 \begin_layout Plain Layout
5930 \begin_inset Flex CharStyle:Code
5933 \begin_layout Plain Layout
5940 \begin_inset Flex CharStyle:Code
5943 \begin_layout Plain Layout
5949 are really the same command.
5950 The possible values are printed in brackets after the feature's name.
5951 The default value if a feature isn't specified inside a text class-description
5953 \begin_inset Flex CharStyle:Code
5956 \begin_layout Plain Layout
5965 If the argument has a datatype like
5966 \begin_inset Quotes eld
5970 \begin_inset Quotes erd
5974 \begin_inset Quotes eld
5978 \begin_inset Quotes erd
5981 , the default is shown like this:
5982 \begin_inset Flex CharStyle:Code
5985 \begin_layout Plain Layout
5996 \begin_layout Subsection
5997 \begin_inset CommandInset label
5999 name "sub:Layout-modules"
6006 \begin_layout Standard
6007 Similar to layout files, and new with LyX 1.6, are layout
6012 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6013 some modules---such as the Endnotes module---provide support for just such
6015 In a sense, layout modules are similar to included files---files like
6016 \begin_inset Flex CharStyle:Code
6019 \begin_layout Plain Layout
6025 ---in that modules are not specific to a given document layout but may be
6026 used with many different layouts.
6027 The difference is that using a layout module does not require editing the
6029 Rather, modules are selected in the
6030 \begin_inset Flex CharStyle:MenuItem
6033 \begin_layout Plain Layout
6034 Document\SpecialChar \menuseparator
6043 \begin_layout Standard
6044 Building modules is the easiest way to get started with layout editing,
6045 since it can be as simple as adding a single new paragraph or flex inset.
6046 But modules may, in principle, contain anything a layout file can contain.
6049 \begin_layout Standard
6050 A module must begin with a line like the following:
6053 \begin_layout LyX-Code
6056 DeclareLyXModule[endnotes.sty]{Endnotes}
6059 \begin_layout Standard
6060 The argument in square brackets is optional: It declares any LaTeX packages
6061 on which the module depends.
6062 The mandatory argument, in curly brackets, is the name of the module, as
6064 \begin_inset Flex CharStyle:MenuItem
6067 \begin_layout Plain Layout
6068 Document\SpecialChar \menuseparator
6078 \begin_layout Standard
6079 The module declaration should then be followed by lines like the following:
6082 \begin_layout LyX-Code
6086 \begin_layout LyX-Code
6087 #Adds an endnote command, in addition to footnotes.
6091 \begin_layout LyX-Code
6092 #You will need to add
6094 theendnotes in ERT where you
6097 \begin_layout LyX-Code
6098 #want the endnotes to appear.
6102 \begin_layout LyX-Code
6106 \begin_layout LyX-Code
6107 #Requires: somemodule | othermodule
6110 \begin_layout LyX-Code
6111 #Excludes: badmodule
6114 \begin_layout Standard
6115 The description is used in
6116 \begin_inset Flex CharStyle:MenuItem
6119 \begin_layout Plain Layout
6120 Document\SpecialChar \menuseparator
6126 to provide the user with information about what the module does.
6128 \begin_inset Flex CharStyle:Code
6131 \begin_layout Plain Layout
6137 line is used to identify other modules with which this one must be used;
6139 \begin_inset Flex CharStyle:Code
6142 \begin_layout Plain Layout
6148 line is used to identify modules with which this one may not be used.
6149 Both are optional, and, as shown, multiple modules should be separated
6150 with the pipe symbol: |.
6151 Note that the required modules are treated disjunctively:
6155 of the required modules must be used.
6160 excluded module may be used.
6161 Note that modules are identified here by their
6165 without the .module extension.
6167 \begin_inset Flex CharStyle:Code
6170 \begin_layout Plain Layout
6177 \begin_inset Flex CharStyle:Code
6180 \begin_layout Plain Layout
6189 \begin_layout Standard
6190 After creating a new module, you will need to reconfigure and then restart
6191 LyX for the module to appear in the menu.
6192 However, changes you make to the module will be seen immediately, if you
6194 \begin_inset Flex CharStyle:MenuItem
6197 \begin_layout Plain Layout
6198 Document\SpecialChar \menuseparator
6204 , highlight something, and then hit
6205 \begin_inset Quotes eld
6209 \begin_inset Quotes erd
6215 It is strongly recommended that you save your work before doing so
6220 it is strongly recommended that you not attempt to edit modules while simultaneo
6221 usly working on documents
6224 Though of course the developers strive to keep LyX stable in such situations,
6225 syntax errors and the like in your module file could cause strange behavior.
6228 \begin_layout Subsection
6229 Supporting new document classes
6232 \begin_layout Standard
6233 There are two situations you are likely to encounter when wanting to support
6234 a new LaTeX document class, involving LaTeX2e class (
6235 \begin_inset Flex CharStyle:Code
6238 \begin_layout Plain Layout
6245 \begin_inset Flex CharStyle:Code
6248 \begin_layout Plain Layout
6255 Supporting a style file is usually fairly easy.
6256 Supporting a new document class is a bit harder.
6259 \begin_layout Subsection
6261 \begin_inset Flex CharStyle:MenuItem
6264 \begin_layout Plain Layout
6273 \begin_layout Standard
6274 If your new document class is provided as a style file that is used in conjuncti
6275 on with an existing, supported document class---for the sake of the example,
6276 we'll assume that the style file is called
6277 \begin_inset Flex CharStyle:MenuItem
6280 \begin_layout Plain Layout
6286 and it is meant to be used with
6287 \begin_inset Flex CharStyle:MenuItem
6290 \begin_layout Plain Layout
6296 , which is a standard class---start by copying the existing class's layout
6297 file into your local directory:
6300 \begin_layout LyX-Code
6301 cp report.layout ~/.lyx/layouts/myclass.layout
6304 \begin_layout Standard
6306 \begin_inset Flex CharStyle:Code
6309 \begin_layout Plain Layout
6315 and change the line:
6318 \begin_layout LyX-Code
6321 DeclareLaTeXClass{report}
6324 \begin_layout Standard
6328 \begin_layout LyX-Code
6331 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6334 \begin_layout Standard
6338 \begin_layout LyX-Code
6340 \begin_inset Newline newline
6346 \begin_inset Newline newline
6352 \begin_layout Standard
6353 near the top of the file.
6356 \begin_layout Standard
6357 Start LyX and select
6358 \begin_inset Flex CharStyle:MenuItem
6361 \begin_layout Plain Layout
6366 ools\SpecialChar \menuseparator
6377 Then restart LyX and try creating a new document.
6379 \begin_inset Flex CharStyle:MenuItem
6382 \begin_layout Plain Layout
6388 " as a document class option in the
6389 \begin_inset Flex CharStyle:MenuItem
6392 \begin_layout Plain Layout
6397 ocument\SpecialChar \menuseparator
6408 It is likely that some of the sectioning commands and such in your new
6409 class will work differently from how they worked in the base class---
6410 \begin_inset Flex CharStyle:Code
6413 \begin_layout Plain Layout
6419 in this example---so you can fiddle around with the settings for the different
6420 sections if you wish.
6423 \begin_layout Subsection
6425 \begin_inset Flex CharStyle:MenuItem
6428 \begin_layout Plain Layout
6437 \begin_layout Standard
6438 There are two possibilities here.
6439 One is that the class file is itself based upon an existing document class.
6440 For example, many thesis classes are based upon
6441 \begin_inset Flex CharStyle:MenuItem
6444 \begin_layout Plain Layout
6451 To see whether yours is, look for a line like
6454 \begin_layout LyX-Code
6460 \begin_layout Standard
6462 If so, then you may proceed largely as in the previous section, though
6463 the DeclareLaTeXClass line will be different.
6464 If your new class is thesis, and it is based upon book, then the line should
6469 \begin_layout Plain Layout
6470 And it will be easiest if you save the file to
6471 \begin_inset Flex CharStyle:Code
6474 \begin_layout Plain Layout
6480 : LyX assumes that the document class has the same name as the layout file.
6489 \begin_layout LyX-Code
6492 DeclareLaTeXClass[thesis,book]{thesis}
6495 \begin_layout Standard
6496 If, on the other hand, the new class is not based upon an existing class,
6497 you will probably have to
6498 \begin_inset Quotes eld
6502 \begin_inset Quotes erd
6506 We strongly suggest copying an existing layout file which uses a similar
6507 LaTeX class and then modifying it, if you can do so.
6508 At least use an existing file as a starting point so you can find out what
6509 items you need to worry about.
6510 Again, the specifics are covered below.
6513 \begin_layout Section
6514 Declaring a new text class
6517 \begin_layout Standard
6518 When it's finally time to get your hands dirty and create or edit your own
6519 layout file, the following sections describe what you're up against.
6520 Our advice is to go slowly, save and test often, listen to soothing music,
6521 and enjoy one or two of your favorite adult beverages; more if you are
6522 getting particularly stuck.
6523 It's really not that hard, except that the multitude of options can become
6524 overwhelming if you try to do to much in one sitting.
6525 Go have another adult beverage, just for good measure.
6528 \begin_layout Standard
6532 \begin_layout Standard
6533 Lines in a layout file which begin with a
6534 \begin_inset Flex CharStyle:Code
6537 \begin_layout Plain Layout
6544 There is one exception to this rule: all layouts should begin with lines
6548 \begin_layout LyX-Code
6551 #% Do not delete the line below; configure depends on this
6554 \begin_layout LyX-Code
6559 DeclareLaTeXClass{article}
6562 \begin_layout Standard
6563 The second line is used when you configure LyX.
6564 The layout file is read by the LaTeX script
6565 \begin_inset Flex CharStyle:Code
6568 \begin_layout Plain Layout
6574 , in a special mode where
6575 \begin_inset Flex CharStyle:Code
6578 \begin_layout Plain Layout
6585 The first line is just a LaTeX comment, and the second one contains the
6586 declaration of the text class.
6587 If these lines appear in a file named
6588 \begin_inset Flex CharStyle:Code
6591 \begin_layout Plain Layout
6597 , then they define a text class of name
6598 \begin_inset Flex CharStyle:Code
6601 \begin_layout Plain Layout
6607 (the name of the layout file) which uses the LaTeX document class
6608 \begin_inset Flex CharStyle:Code
6611 \begin_layout Plain Layout
6617 (the default is to use the same name as the layout).
6619 \begin_inset Quotes eld
6623 \begin_inset Quotes erd
6626 that appears above is used as a description of the text class in the
6627 \begin_inset Flex CharStyle:MenuItem
6630 \begin_layout Plain Layout
6635 ocument\SpecialChar \menuseparator
6648 \begin_layout Standard
6649 Let's assume that you wrote your own text class that uses the
6650 \begin_inset Flex CharStyle:Code
6653 \begin_layout Plain Layout
6659 document class, but where you changed the appearance of the section headings.
6660 If you put it in a file
6661 \begin_inset Flex CharStyle:Code
6664 \begin_layout Plain Layout
6670 , the header of this file should be:
6673 \begin_layout LyX-Code
6676 #% Do not delete the line below; configure depends on this
6679 \begin_layout LyX-Code
6684 DeclareLaTeXClass[article]{article (with my own headings)}
6687 \begin_layout Standard
6688 This declares a text class
6689 \begin_inset Flex CharStyle:Code
6692 \begin_layout Plain Layout
6698 , associated with the LaTeX document class
6699 \begin_inset Flex CharStyle:Code
6702 \begin_layout Plain Layout
6709 \begin_inset Quotes eld
6712 article (with my own headings)
6713 \begin_inset Quotes erd
6717 If your text class depends on several packages, you can declare it as:
6720 \begin_layout LyX-Code
6723 #% Do not delete the line below; configure depends on this
6726 \begin_layout LyX-Code
6731 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6734 \begin_layout Standard
6735 This indicates that your text class uses the foo.sty package.
6736 Finally, it is also possible to declare classes for DocBook code.
6737 Typical declarations will look like
6740 \begin_layout LyX-Code
6743 #% Do not delete the line below; configure depends on this
6746 \begin_layout LyX-Code
6751 DeclareDocBookClass[article]{SGML (DocBook article)}
6754 \begin_layout Standard
6755 Note that these declarations can also be given an optional parameter declaring
6756 the name of the document class (but not a list).
6759 \begin_layout Standard
6760 So, to be as explicit as possible, the form of the layout declaration is:
6763 \begin_layout LyX-Code
6768 DeclareLaTeXClass[class,package.sty]{layout description}
6771 \begin_layout Standard
6772 The class need only be specified if the name of the LaTeX class file and
6773 the name of the layout file are different; if the name of the classfile
6774 is not specified, then LyX will simply assume that it is the same as the
6775 name of the layout file.
6778 \begin_layout Standard
6779 When the text class has been modified to your taste, all you have to do
6780 is to copy it either to
6781 \begin_inset Flex CharStyle:Code
6784 \begin_layout Plain Layout
6791 \begin_inset Flex CharStyle:Code
6794 \begin_layout Plain Layout
6801 \begin_inset Flex CharStyle:MenuItem
6804 \begin_layout Plain Layout
6809 ools\SpecialChar \menuseparator
6819 , exit LyX and restart it.
6820 Then your new text class should be available along with the others.
6823 \begin_layout Standard
6824 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6825 you made to your layout files.
6826 As a result, editing layout files could be very time consuming.
6827 Beginning with 1.6, however, you can force a reload of the layout currently
6828 in use by using the LyX function
6829 \begin_inset Flex CharStyle:MenuItem
6832 \begin_layout Plain Layout
6839 There is no default binding for this function---though, of course, you
6840 can bind it to a key yourself.
6841 If you want to use this function, then, you should simply enter it in the
6847 : This is very much an `advanced feature'.
6852 recommended that you save your work before using this function.
6857 recommended that you not attempt to edit your layout while simultaneously
6858 working on a document that you care about.
6859 Use a test document.
6860 Syntax errors and the like in your layout file could cause peculiar behavior.
6861 In particular, such errors could cause LyX to regard the current layout
6862 as invalid and to attempt to switch to some other layout.
6863 The LyX team strives to keep LyX stable in such situations, but safe is
6867 \begin_layout Subsection
6871 \begin_layout Standard
6872 The first non-comment line must contain the file format number:
6875 \begin_layout Description
6876 \begin_inset Flex CharStyle:Code
6879 \begin_layout Plain Layout
6886 \begin_inset Flex CharStyle:Code
6889 \begin_layout Plain Layout
6895 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6896 don't have an explicit file format).
6897 The file format that is documented here is format 8.
6900 \begin_layout Subsection
6901 General text class parameters
6904 \begin_layout Standard
6905 These are the general parameters which describe the form of the entire document:
6908 \begin_layout Description
6909 \begin_inset Flex CharStyle:Code
6912 \begin_layout Plain Layout
6918 Adds information to the document preamble.
6920 \begin_inset Quotes eld
6924 \begin_inset Flex CharStyle:Code
6927 \begin_layout Plain Layout
6934 \begin_inset Quotes erd
6940 \begin_layout Description
6941 \begin_inset Flex CharStyle:Code
6944 \begin_layout Plain Layout
6950 Describes various global options supported by the document class.
6952 \begin_inset space ~
6956 \begin_inset CommandInset ref
6958 reference "sec:classoptions"
6964 \begin_inset Quotes eld
6968 \begin_inset Flex CharStyle:Code
6971 \begin_layout Plain Layout
6978 \begin_inset Quotes erd
6984 \begin_layout Description
6985 \begin_inset Flex CharStyle:Code
6988 \begin_layout Plain Layout
6995 \begin_inset Flex CharStyle:Code
6998 \begin_layout Plain Layout
7007 \begin_inset Flex CharStyle:Code
7010 \begin_layout Plain Layout
7016 ] Whether the class should default to having one or two columns.
7017 Can be changed in the
7018 \begin_inset Flex CharStyle:MenuItem
7021 \begin_layout Plain Layout
7026 ocument\SpecialChar \menuseparator
7039 \begin_layout Description
7040 \begin_inset Flex CharStyle:Code
7043 \begin_layout Plain Layout
7049 This sequence defines a new counter.
7051 \begin_inset space ~
7055 \begin_inset CommandInset ref
7057 reference "sec:counter"
7063 \begin_inset Quotes eld
7067 \begin_inset Flex CharStyle:Code
7070 \begin_layout Plain Layout
7077 \begin_inset Quotes erd
7083 \begin_layout Description
7084 \begin_inset Flex CharStyle:Code
7087 \begin_layout Plain Layout
7093 Sets the default font used to display the document.
7095 \begin_inset space ~
7099 \begin_inset CommandInset ref
7101 reference "sec:fonts"
7105 for how to declare fonts.
7107 \begin_inset Quotes eld
7111 \begin_inset Flex CharStyle:Code
7114 \begin_layout Plain Layout
7121 \begin_inset Quotes erd
7127 \begin_layout Description
7128 \begin_inset Flex CharStyle:Code
7131 \begin_layout Plain Layout
7138 \begin_inset Flex CharStyle:Code
7141 \begin_layout Plain Layout
7147 Specifies a module to be included by default with this document class,
7148 which should be specified by filename without the
7149 \begin_inset Flex CharStyle:Code
7152 \begin_layout Plain Layout
7159 The user can still remove the module, but it will be active at the outset.
7160 (This applies only when new files are created, or when this class is chosen
7161 for an existing document.)
7164 \begin_layout Description
7165 \begin_inset Flex CharStyle:Code
7168 \begin_layout Plain Layout
7175 \begin_inset Flex CharStyle:Code
7178 \begin_layout Plain Layout
7184 ] This is the style that will be assigned to new paragraphs, usually
7185 \begin_inset Flex CharStyle:MenuItem
7188 \begin_layout Plain Layout
7195 This will default to the first defined style if not given, but you are
7196 highly encouraged to use this directive.
7199 \begin_layout Description
7200 \begin_inset Flex CharStyle:Code
7203 \begin_layout Plain Layout
7210 \begin_inset Flex CharStyle:Code
7213 \begin_layout Plain Layout
7219 ] Indicates that the module in question---which should be specified by filename
7221 \begin_inset Flex CharStyle:Code
7224 \begin_layout Plain Layout
7230 extension---cannot be used with this document class.
7231 This might be used in a journal-specific layout file to prevent, say, the
7233 \begin_inset Flex CharStyle:Code
7236 \begin_layout Plain Layout
7242 module that numbers theorems by section.
7247 be used in a module.
7248 Modules have their own way of excluding other modules (see
7249 \begin_inset CommandInset ref
7251 reference "sub:Layout-modules"
7258 \begin_layout Description
7259 \begin_inset Flex CharStyle:Code
7262 \begin_layout Plain Layout
7268 Defines a new float.
7270 \begin_inset space ~
7274 \begin_inset CommandInset ref
7276 reference "sec:floats"
7282 \begin_inset Quotes eld
7286 \begin_inset Flex CharStyle:Code
7289 \begin_layout Plain Layout
7296 \begin_inset Quotes erd
7302 \begin_layout Description
7303 \begin_inset Flex CharStyle:Code
7306 \begin_layout Plain Layout
7312 As its name implies, this command allows you to include another layout
7313 definition file within yours to avoid duplicating commands.
7314 Common examples are the standard layout files, for example,
7315 \begin_inset Flex CharStyle:Code
7318 \begin_layout Plain Layout
7324 , which contains most of the basic layouts.
7327 \begin_layout Description
7328 \begin_inset Flex CharStyle:Code
7331 \begin_layout Plain Layout
7337 This section (re-)defines the layout of an inset.
7338 It can be applied to an existing inset of to a new, user-defined inset,
7339 e.g., a new character style.
7341 \begin_inset space ~
7345 \begin_inset CommandInset ref
7347 reference "sec:charstyle"
7351 for more information.
7353 \begin_inset Quotes eld
7357 \begin_inset Flex CharStyle:Code
7360 \begin_layout Plain Layout
7367 \begin_inset Quotes erd
7373 \begin_layout Description
7374 \begin_inset Flex CharStyle:Code
7377 \begin_layout Plain Layout
7383 A string that indicates the width of the left margin on the screen, for
7385 \begin_inset Quotes eld
7389 \begin_inset Quotes erd
7395 \begin_layout Description
7396 \begin_inset Flex CharStyle:Code
7399 \begin_layout Plain Layout
7405 This command deletes an existing float.
7406 This is particularly useful when you want to suppress a float that has
7407 be defined in an input file.
7410 \begin_layout Description
7411 \begin_inset Flex CharStyle:Code
7414 \begin_layout Plain Layout
7420 This command deletes an existing style.
7421 This is particularly useful when you want to suppress a style that has
7422 be defined in an input file.
7425 \begin_layout Description
7426 \begin_inset Flex CharStyle:Code
7429 \begin_layout Plain Layout
7435 A string indicating what sort of output documents using this class will
7437 At present, the options are: `docbook', `latex', and `literate'.
7440 \begin_layout Description
7441 \begin_inset Flex CharStyle:Code
7444 \begin_layout Plain Layout
7455 \begin_inset Flex CharStyle:Code
7458 \begin_layout Plain Layout
7469 \begin_inset Flex CharStyle:Code
7472 \begin_layout Plain Layout
7479 \begin_inset Flex CharStyle:Code
7482 \begin_layout Plain Layout
7488 ] The class default pagestyle.
7489 Can be changed in the
7490 \begin_inset Flex CharStyle:MenuItem
7493 \begin_layout Plain Layout
7498 ocument\SpecialChar \menuseparator
7511 \begin_layout Description
7512 \begin_inset Flex CharStyle:Code
7515 \begin_layout Plain Layout
7521 Sets the preamble for the LaTeX document.
7522 Note that this will completely override any prior
7523 \begin_inset Flex CharStyle:Code
7526 \begin_layout Plain Layout
7533 \begin_inset Flex CharStyle:Code
7536 \begin_layout Plain Layout
7544 \begin_inset Quotes eld
7548 \begin_inset Flex CharStyle:Code
7551 \begin_layout Plain Layout
7558 \begin_inset Quotes erd
7564 \begin_layout Description
7565 \begin_inset Flex CharStyle:Code
7568 \begin_layout Plain Layout
7575 \begin_inset Flex CharStyle:Code
7578 \begin_layout Plain Layout
7585 \begin_inset Flex CharStyle:Code
7588 \begin_layout Plain Layout
7597 \begin_inset Flex CharStyle:Code
7600 \begin_layout Plain Layout
7606 ] Whether the class already provides the feature
7607 \begin_inset Flex CharStyle:Code
7610 \begin_layout Plain Layout
7617 A feature is in general the name of a package (
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{}
7639 \begin_inset Flex CharStyle:Code
7642 \begin_layout Plain Layout
7649 \begin_inset Flex CharStyle:Code
7652 \begin_layout Plain Layout
7658 ,\SpecialChar \ldots{}
7659 ); the complete list of supported features is unfortunately not documented
7660 outside the LyX source code---but see
7661 \begin_inset Flex CharStyle:Code
7664 \begin_layout Plain Layout
7670 if you're interested.
7672 \begin_inset Flex CharStyle:MenuItem
7675 \begin_layout Plain Layout
7680 elp\SpecialChar \menuseparator
7690 also gives an overview of the supported packages.
7693 \begin_layout Description
7694 \begin_inset Flex CharStyle:Code
7697 \begin_layout Plain Layout
7704 \begin_inset Flex CharStyle:Code
7707 \begin_layout Plain Layout
7713 ] Indicates that this layout provides the functionality of the module mentioned,
7714 which should be specified by filename, which should be specified by filename
7716 \begin_inset Flex CharStyle:Code
7719 \begin_layout Plain Layout
7726 This will typically be used if the layout includes the module directly,
7727 rather than using the
7728 \begin_inset Flex CharStyle:Code
7731 \begin_layout Plain Layout
7737 tag to indicate that it ought to be used.
7738 It could be used in a module that that provided an alternate implementation
7739 of the same functionality.
7742 \begin_layout Description
7743 \begin_inset Flex CharStyle:Code
7746 \begin_layout Plain Layout
7753 \begin_inset Flex CharStyle:Code
7756 \begin_layout Plain Layout
7762 ] Whether the class requires the feature
7763 \begin_inset Flex CharStyle:Code
7766 \begin_layout Plain Layout
7773 Multiple features must be separated by commas.
7774 Note that you can only request supported features.
7777 \begin_layout Description
7778 \begin_inset Flex CharStyle:Code
7781 \begin_layout Plain Layout
7787 A string that indicates the width of the right margin on the screen, for
7789 \begin_inset Quotes eld
7793 \begin_inset Quotes erd
7799 \begin_layout Description
7800 \begin_inset Flex CharStyle:Code
7803 \begin_layout Plain Layout
7809 Sets which divisions get numbered.
7811 \begin_inset Flex CharStyle:Code
7814 \begin_layout Plain Layout
7823 \begin_layout Description
7824 \begin_inset Flex CharStyle:Code
7827 \begin_layout Plain Layout
7836 \begin_inset Flex CharStyle:Code
7839 \begin_layout Plain Layout
7850 \begin_inset Flex CharStyle:Code
7853 \begin_layout Plain Layout
7859 ] Whether the class-default should be printing on one or both sides of the
7861 Can be changed in the
7862 \begin_inset Flex CharStyle:MenuItem
7865 \begin_layout Plain Layout
7870 ocument\SpecialChar \menuseparator
7883 \begin_layout Description
7884 \begin_inset Flex CharStyle:Code
7887 \begin_layout Plain Layout
7893 This sequence defines a new paragraph style.
7894 If the style already exists, it will redefine some of its parameters instead.
7896 \begin_inset space ~
7900 \begin_inset CommandInset ref
7902 reference "sec:style"
7908 \begin_inset Quotes eld
7912 \begin_inset Flex CharStyle:Code
7915 \begin_layout Plain Layout
7922 \begin_inset Quotes erd
7928 \begin_layout Description
7929 \begin_inset Flex CharStyle:Code
7932 \begin_layout Plain Layout
7939 \begin_inset Flex CharStyle:Code
7942 \begin_layout Plain Layout
7948 ] The name of the command or environment to be used with
7949 \begin_inset Flex CharStyle:Code
7952 \begin_layout Plain Layout
7961 \begin_layout Description
7962 \begin_inset Flex CharStyle:Code
7965 \begin_layout Plain Layout
7972 \begin_inset Flex CharStyle:Code
7975 \begin_layout Plain Layout
7984 \begin_inset Flex CharStyle:Code
7987 \begin_layout Plain Layout
7993 ] Indicates what kind of markup is used to define the title of a document.
7995 \begin_inset Flex CharStyle:Code
7998 \begin_layout Plain Layout
8004 means that the macro with name
8005 \begin_inset Flex CharStyle:Code
8008 \begin_layout Plain Layout
8014 will be inserted after the last layout which has
8015 \begin_inset Quotes eld
8019 \begin_inset Flex CharStyle:Code
8022 \begin_layout Plain Layout
8029 \begin_inset Quotes erd
8034 \begin_inset Flex CharStyle:Code
8037 \begin_layout Plain Layout
8043 corresponds to the case where the block of paragraphs which have
8044 \begin_inset Quotes eld
8048 \begin_inset Flex CharStyle:Code
8051 \begin_layout Plain Layout
8058 \begin_inset Quotes erd
8061 should be enclosed into the
8062 \begin_inset Flex CharStyle:Code
8065 \begin_layout Plain Layout
8074 \begin_layout Description
8075 \begin_inset Flex CharStyle:Code
8078 \begin_layout Plain Layout
8084 Sets which divisions are included in the table of contents.
8086 \begin_inset Flex CharStyle:Code
8089 \begin_layout Plain Layout
8098 \begin_layout Subsection
8099 \begin_inset Flex CharStyle:Code
8102 \begin_layout Plain Layout
8111 \begin_layout Standard
8112 \begin_inset CommandInset label
8114 name "sec:classoptions"
8119 \begin_inset Flex CharStyle:Code
8122 \begin_layout Plain Layout
8128 section can contain the following entries:
8131 \begin_layout Description
8132 \begin_inset Flex CharStyle:Code
8135 \begin_layout Plain Layout
8142 \begin_inset Flex CharStyle:Code
8145 \begin_layout Plain Layout
8151 ] The list of available font sizes for the document's main font, separated
8153 \begin_inset Quotes eld
8157 \begin_inset Flex CharStyle:Code
8160 \begin_layout Plain Layout
8167 \begin_inset Quotes erd
8173 \begin_layout Description
8174 \begin_inset Flex CharStyle:Code
8177 \begin_layout Plain Layout
8183 Used to set the DTD line with XML-based output classes.
8185 \begin_inset Quotes eld
8188 -//OASIS//DTD DocBook V4.2//EN
8189 \begin_inset Quotes erd
8195 \begin_layout Description
8196 \begin_inset Flex CharStyle:Code
8199 \begin_layout Plain Layout
8206 \begin_inset Flex CharStyle:Code
8209 \begin_layout Plain Layout
8210 string="empty|plain|headings|fancy"
8215 ] The list of available page styles, separated by
8216 \begin_inset Quotes eld
8220 \begin_inset Flex CharStyle:Code
8223 \begin_layout Plain Layout
8230 \begin_inset Quotes erd
8236 \begin_layout Description
8237 \begin_inset Flex CharStyle:Code
8240 \begin_layout Plain Layout
8247 \begin_inset Flex CharStyle:Code
8250 \begin_layout Plain Layout
8256 ] Some document class options, separated by a comma, that will be added
8257 to the optional part of the
8258 \begin_inset Flex CharStyle:Code
8261 \begin_layout Plain Layout
8272 \begin_layout Standard
8274 \begin_inset Flex CharStyle:Code
8277 \begin_layout Plain Layout
8283 section must end with
8284 \begin_inset Quotes eld
8288 \begin_inset Flex CharStyle:Code
8291 \begin_layout Plain Layout
8298 \begin_inset Quotes erd
8304 \begin_layout Subsection
8308 \begin_layout Standard
8309 \begin_inset CommandInset label
8315 A paragraph style description looks like this:
8319 \begin_layout Plain Layout
8320 Note that this will either define a new layout or modify an existing one.
8328 \begin_layout LyX-Code
8335 \begin_layout LyX-Code
8339 \begin_layout LyX-Code
8343 \begin_layout Standard
8344 where the following commands are allowed:
8347 \begin_layout Description
8348 \begin_inset Flex CharStyle:Code
8351 \begin_layout Plain Layout
8358 \begin_inset Flex CharStyle:Code
8361 \begin_layout Plain Layout
8366 , left, right, center
8371 ] Paragraph alignment.
8374 \begin_layout Description
8375 \begin_inset Flex CharStyle:Code
8378 \begin_layout Plain Layout
8385 \begin_inset Flex CharStyle:Code
8388 \begin_layout Plain Layout
8393 , left, right, center
8398 ] A comma separated list of permitted alignments.
8399 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8401 For example a right-aligned or centered enumeration isn't possible.)
8404 \begin_layout Description
8405 \begin_inset Flex CharStyle:Code
8408 \begin_layout Plain Layout
8415 \begin_inset Flex CharStyle:Code
8418 \begin_layout Plain Layout
8428 \begin_layout Plain Layout
8429 Note that a `float' here is a real number, such as: 1.5.
8434 The vertical space with which the last of a chain of paragraphs with this
8435 layout is separated from the following paragraph.
8436 If the next paragraph has another layout, the separations are not simply
8437 added, but the maximum is taken.
8440 \begin_layout Description
8441 \begin_inset Flex CharStyle:Code
8444 \begin_layout Plain Layout
8451 \begin_inset Flex CharStyle:Code
8454 \begin_layout Plain Layout
8460 The category for this style.
8461 This is used to group related styles in the Layout combobox on the toolbar.
8462 Any string can be used, but you may want to use existing categories with
8467 \begin_layout Description
8468 \begin_inset Flex CharStyle:Code
8471 \begin_layout Plain Layout
8477 Depth of XML command.
8478 Used only with XML-type formats.
8481 \begin_layout Description
8482 \begin_inset Flex CharStyle:Code
8485 \begin_layout Plain Layout
8492 \begin_inset CommandInset label
8494 name "des:CopyStyle"
8499 \begin_inset Flex CharStyle:Code
8502 \begin_layout Plain Layout
8508 Copies all the features of an existing style into the current one.
8512 \begin_layout Description
8513 \begin_inset Flex CharStyle:Code
8516 \begin_layout Plain Layout
8522 The name of a style whose preamble should be output
8527 This allows to ensure some ordering of the preamble snippets when macros
8528 definitions depend on one another.
8532 \begin_layout Plain Layout
8533 Note that, besides that functionality, there is no way to ensure any ordering
8535 The ordering that you see in a given version of LyX may change without
8536 warning in later versions.
8544 \begin_layout Description
8545 \begin_inset Flex CharStyle:Code
8548 \begin_layout Plain Layout
8555 \begin_inset Flex CharStyle:Code
8558 \begin_layout Plain Layout
8563 , Box, Filled_Box, Static
8568 ] The type of label that stands at the end of the paragraph (or sequence
8570 \begin_inset Flex CharStyle:Code
8573 \begin_layout Plain Layout
8580 \begin_inset Flex CharStyle:Code
8583 \begin_layout Plain Layout
8590 \begin_inset Flex CharStyle:Code
8593 \begin_layout Plain Layout
8600 \begin_inset Flex CharStyle:Code
8603 \begin_layout Plain Layout
8611 \begin_inset Flex CharStyle:Code
8614 \begin_layout Plain Layout
8621 \begin_inset Quotes eld
8625 \begin_inset Quotes erd
8629 \begin_inset Flex CharStyle:Code
8632 \begin_layout Plain Layout
8639 \begin_inset Flex CharStyle:Code
8642 \begin_layout Plain Layout
8643 \begin_inset space ~
8652 \begin_inset space ~
8655 black) square suitable for end of proof markers,
8656 \begin_inset Flex CharStyle:Code
8659 \begin_layout Plain Layout
8665 is an explicit text string.
8668 \begin_layout Description
8669 \begin_inset Flex CharStyle:Code
8672 \begin_layout Plain Layout
8679 \begin_inset Flex CharStyle:Code
8682 \begin_layout Plain Layout
8688 ] The string used for a label with a
8689 \begin_inset Flex CharStyle:Code
8692 \begin_layout Plain Layout
8699 \begin_inset Flex CharStyle:Code
8702 \begin_layout Plain Layout
8712 \begin_layout Description
8713 \begin_inset Flex CharStyle:Code
8716 \begin_layout Plain Layout
8723 \begin_inset Flex CharStyle:Code
8726 \begin_layout Plain Layout
8737 \begin_inset Flex CharStyle:Code
8740 \begin_layout Plain Layout
8749 \begin_layout Description
8750 \begin_inset Flex CharStyle:Code
8753 \begin_layout Plain Layout
8760 \begin_inset Flex CharStyle:Code
8763 \begin_layout Plain Layout
8773 ] With this parameter the
8774 \begin_inset Flex CharStyle:MenuItem
8777 \begin_layout Plain Layout
8784 \begin_inset Quotes eld
8787 Vertical space above
8788 \begin_inset Quotes erd
8792 \begin_inset Flex CharStyle:MenuItem
8795 \begin_layout Plain Layout
8800 dit\SpecialChar \menuseparator
8806 \begin_inset space ~
8814 dialog can be set when initializing a paragraph with this style.
8818 \begin_layout Plain Layout
8821 Note from Jean-Marc:
8823 I'm not sure that this setting has much use, and it should probably be
8824 removed in later versions.
8832 \begin_layout Description
8833 \begin_inset Flex CharStyle:Code
8836 \begin_layout Plain Layout
8842 The font used for both the text body
8848 \begin_inset space ~
8852 \begin_inset CommandInset ref
8854 reference "sec:fonts"
8859 Note that defining this font automatically defines the
8860 \begin_inset Flex CharStyle:Code
8863 \begin_layout Plain Layout
8870 So you should define this one first if you also want to define
8871 \begin_inset Flex CharStyle:Code
8874 \begin_layout Plain Layout
8883 \begin_layout Description
8884 \begin_inset Flex CharStyle:Code
8887 \begin_layout Plain Layout
8894 \begin_inset CommandInset label
8896 name "des:FreeSpacing"
8903 \begin_inset Flex CharStyle:Code
8906 \begin_layout Plain Layout
8917 \begin_inset Flex CharStyle:Code
8920 \begin_layout Plain Layout
8926 ] Usually LyX doesn't allow you to insert more than one space between words,
8927 since a space is considered as the separation between two words, not a
8928 character or symbol of its own.
8929 This is a very fine thing but sometimes annoying, for example, when typing
8930 program code or plain LaTeX code.
8932 \begin_inset Flex CharStyle:Code
8935 \begin_layout Plain Layout
8942 Note that LyX will create protected blanks for the additional blanks when
8943 in another mode than LaTeX-mode.
8946 \begin_layout Description
8947 \begin_inset Flex CharStyle:Code
8950 \begin_layout Plain Layout
8956 [[FIXME]] (Used only with XML-type formats.)
8959 \begin_layout Description
8960 \begin_inset Flex CharStyle:Code
8963 \begin_layout Plain Layout
8970 \begin_inset Flex CharStyle:Code
8973 \begin_layout Plain Layout
8979 If 1, marks the layout as being part of a title block (see also the
8980 \begin_inset Flex CharStyle:Code
8983 \begin_layout Plain Layout
8990 \begin_inset Flex CharStyle:Code
8993 \begin_layout Plain Layout
9002 \begin_layout Description
9003 \begin_inset Flex CharStyle:Code
9006 \begin_layout Plain Layout
9013 \begin_inset Flex CharStyle:Code
9016 \begin_layout Plain Layout
9022 ] This provides extra space between paragraphs that have the same layout.
9023 If you put other layouts into an environment, each is separated with the
9025 \begin_inset Flex CharStyle:Code
9028 \begin_layout Plain Layout
9035 But the whole items of the environment are additionally separated with
9037 \begin_inset Flex CharStyle:Code
9040 \begin_layout Plain Layout
9052 \begin_layout Description
9053 \begin_inset Flex CharStyle:Code
9056 \begin_layout Plain Layout
9062 [[FIXME]] (Used only with XML-type formats.)
9065 \begin_layout Description
9066 \begin_inset Flex CharStyle:Code
9069 \begin_layout Plain Layout
9076 \begin_inset CommandInset label
9078 name "des:KeepEmpty"
9085 \begin_inset Flex CharStyle:Code
9088 \begin_layout Plain Layout
9099 \begin_inset Flex CharStyle:Code
9102 \begin_layout Plain Layout
9108 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9109 lead to empty LaTeX output.
9110 There are some cases where this could be desirable however: in a letter
9111 template, the required fields can be provided as empty fields, so that
9112 people do not forget them; in some special classes, a layout can be used
9113 as some kind of break, which does not contain actual text.
9116 \begin_layout Description
9117 \begin_inset Flex CharStyle:Code
9120 \begin_layout Plain Layout
9126 [float=0] The vertical space between the label and the text body.
9127 Only used for labels that are above the text body (
9128 \begin_inset Flex CharStyle:Code
9131 \begin_layout Plain Layout
9138 \begin_inset Flex CharStyle:Code
9141 \begin_layout Plain Layout
9142 Centered_Top_Environment
9150 \begin_layout Description
9151 \begin_inset Flex CharStyle:Code
9154 \begin_layout Plain Layout
9161 \begin_inset Flex CharStyle:Code
9164 \begin_layout Plain Layout
9171 \begin_inset Newline newline
9174 The name of the counter for automatic numbering (see Section
9175 \begin_inset CommandInset ref
9177 reference "sec:counter"
9182 This must be given if
9183 \begin_inset Flex CharStyle:Code
9186 \begin_layout Plain Layout
9193 \begin_inset Flex CharStyle:Code
9196 \begin_layout Plain Layout
9205 \begin_layout Description
9206 \begin_inset Flex CharStyle:Code
9209 \begin_layout Plain Layout
9215 The font used for the label.
9217 \begin_inset space ~
9221 \begin_inset CommandInset ref
9223 reference "sec:fonts"
9230 \begin_layout Description
9231 \begin_inset Flex CharStyle:Code
9234 \begin_layout Plain Layout
9240 Text that indicates how far a label should be indented.
9243 \begin_layout Description
9244 \begin_inset Flex CharStyle:Code
9247 \begin_layout Plain Layout
9254 \begin_inset Flex CharStyle:Code
9257 \begin_layout Plain Layout
9263 ] The horizontal space between the label and the text body.
9264 Only used for labels that are not above the text body.
9267 \begin_layout Description
9268 \begin_inset Flex CharStyle:Code
9271 \begin_layout Plain Layout
9278 \begin_inset Flex CharStyle:Code
9281 \begin_layout Plain Layout
9287 ] The string used for a label with a
9288 \begin_inset Flex CharStyle:Code
9291 \begin_layout Plain Layout
9299 \begin_inset Flex CharStyle:Code
9302 \begin_layout Plain Layout
9308 is set, this string can be contain the special formatting commands described
9310 \begin_inset CommandInset ref
9312 reference "sec:counter"
9320 \begin_layout Plain Layout
9321 For the sake of backwards compatibility, the string
9322 \begin_inset Flex CharStyle:Code
9325 \begin_layout Plain Layout
9335 will be replaced by the expanded
9336 \begin_inset Flex CharStyle:Code
9339 \begin_layout Plain Layout
9346 \begin_inset Flex CharStyle:Code
9349 \begin_layout Plain Layout
9358 This feature is now obsolete and should be replaced by the mechanisms of
9360 \begin_inset CommandInset ref
9362 reference "sec:counter"
9374 \begin_layout Description
9375 \begin_inset Flex CharStyle:Code
9378 \begin_layout Plain Layout
9385 \begin_inset Flex CharStyle:Code
9388 \begin_layout Plain Layout
9394 ] This is used inside the appendix instead of
9395 \begin_inset Flex CharStyle:Code
9398 \begin_layout Plain Layout
9406 \begin_inset Flex CharStyle:Code
9409 \begin_layout Plain Layout
9416 \begin_inset Flex CharStyle:Code
9419 \begin_layout Plain Layout
9428 \begin_layout Description
9429 \begin_inset Flex CharStyle:Code
9432 \begin_layout Plain Layout
9438 [FIXME] (Used only with XML-type formats.)
9441 \begin_layout Description
9442 \begin_inset Flex CharStyle:Code
9445 \begin_layout Plain Layout
9452 \begin_inset Flex CharStyle:Code
9455 \begin_layout Plain Layout
9460 , Manual, Static, Top_Environment,
9461 \begin_inset Newline newline
9464 Centered_Top_Environment, Sensitive, Counter
9470 \begin_inset Newline newline
9474 \begin_inset Flex CharStyle:Code
9477 \begin_layout Plain Layout
9483 means the label is the very first word (up to the first real blank).
9487 \begin_layout Plain Layout
9488 Use protected spaces if you want more than one word as the label.
9494 \begin_inset Flex CharStyle:Code
9497 \begin_layout Plain Layout
9503 means it is defined in the layout (see
9504 \begin_inset Flex CharStyle:Code
9507 \begin_layout Plain Layout
9515 \begin_inset Flex CharStyle:Code
9518 \begin_layout Plain Layout
9525 \begin_inset Flex CharStyle:Code
9528 \begin_layout Plain Layout
9529 Centered_Top_Environment
9534 are special cases of
9535 \begin_inset Flex CharStyle:Code
9538 \begin_layout Plain Layout
9545 The label will be printed above the paragraph, but only at the top of an
9546 environment or the top of a chain of paragraphs with this layout.
9547 Usage is for example the
9548 \begin_inset Flex CharStyle:MenuItem
9551 \begin_layout Plain Layout
9558 \begin_inset Flex CharStyle:MenuItem
9561 \begin_layout Plain Layout
9568 This is also the case for
9569 \begin_inset Flex CharStyle:Code
9572 \begin_layout Plain Layout
9578 labels with latex type
9579 \begin_inset Flex CharStyle:Code
9582 \begin_layout Plain Layout
9588 , in order to make layouts for theorems work correctly.
9590 \begin_inset Flex CharStyle:Code
9593 \begin_layout Plain Layout
9599 is a special case for the caption-labels
9600 \begin_inset Quotes eld
9604 \begin_inset Quotes erd
9608 \begin_inset Quotes eld
9612 \begin_inset Quotes erd
9617 \begin_inset Flex CharStyle:Code
9620 \begin_layout Plain Layout
9626 means the (hardcoded) label string depends on the kind of float.
9628 \begin_inset Flex CharStyle:Code
9631 \begin_layout Plain Layout
9637 label type defines automatically numbered labels.
9639 \begin_inset CommandInset ref
9641 reference "sec:counter"
9648 \begin_layout Description
9649 \begin_inset Flex CharStyle:Code
9652 \begin_layout Plain Layout
9658 The name of the corresponding LaTeX stuff.
9659 Either the environment or command name.
9662 \begin_layout Description
9663 \begin_inset Flex CharStyle:Code
9666 \begin_layout Plain Layout
9672 An optional parameter for the corresponding
9673 \begin_inset Flex CharStyle:Code
9676 \begin_layout Plain Layout
9683 This parameter cannot be changed from within LyX.
9686 \begin_layout Description
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9697 \begin_inset CommandInset label
9699 name "des:LatexType"
9704 \begin_inset Flex CharStyle:Code
9707 \begin_layout Plain Layout
9712 , Command, Environment, Item_Environment,
9718 \begin_inset Flex CharStyle:Code
9721 \begin_layout Plain Layout
9727 ] How the layout should be translated into LaTeX.
9729 \begin_inset Flex CharStyle:Code
9732 \begin_layout Plain Layout
9738 means nothing special.
9740 \begin_inset Flex CharStyle:Code
9743 \begin_layout Plain Layout
9750 \begin_inset Flex CharStyle:Code
9753 \begin_layout Plain Layout
9760 {\SpecialChar \ldots{}
9767 \begin_inset Flex CharStyle:Code
9770 \begin_layout Plain Layout
9777 \begin_inset Flex CharStyle:Code
9780 \begin_layout Plain Layout
9787 }\SpecialChar \ldots{}
9801 \begin_inset Flex CharStyle:Code
9804 \begin_layout Plain Layout
9811 \begin_inset Flex CharStyle:Code
9814 \begin_layout Plain Layout
9821 \begin_inset Flex CharStyle:Code
9824 \begin_layout Plain Layout
9832 is generated for each paragraph of this environment.
9834 \begin_inset Flex CharStyle:Code
9837 \begin_layout Plain Layout
9844 \begin_inset Flex CharStyle:Code
9847 \begin_layout Plain Layout
9854 \begin_inset Flex CharStyle:Code
9857 \begin_layout Plain Layout
9863 is passed as an argument to the environment.
9865 \begin_inset Flex CharStyle:Code
9868 \begin_layout Plain Layout
9874 can be defined in the
9875 \begin_inset Flex CharStyle:MenuItem
9878 \begin_layout Plain Layout
9883 ayout\SpecialChar \menuseparator
9895 \begin_inset Flex CharStyle:Code
9898 \begin_layout Plain Layout
9906 is perhaps a bit misleading, since these rules apply to SGML classes, too.
9907 Visit the SGML class files for specific examples.
9910 \begin_layout Standard
9911 Putting the last few things together, the LaTeX output will be either:
9914 \begin_layout LyX-Code
9917 latexname[latexparam]{\SpecialChar \ldots{}
9921 \begin_layout Standard
9925 \begin_layout LyX-Code
9928 begin{latexname}[latexparam] \SpecialChar \ldots{}
9934 \begin_layout Standard
9935 depending upon the LaTex type.
9938 \begin_layout Description
9939 \begin_inset Flex CharStyle:Code
9942 \begin_layout Plain Layout
9949 \begin_inset Flex CharStyle:Code
9952 \begin_layout Plain Layout
9958 ] If you put layouts into environments, the leftmargins are not simply added,
9959 but added with a factor
9960 \begin_inset Formula $\frac{4}{depth+4}$
9964 Note that this parameter is also used when the margin is defined as
9965 \begin_inset Flex CharStyle:Code
9968 \begin_layout Plain Layout
9975 \begin_inset Flex CharStyle:Code
9978 \begin_layout Plain Layout
9985 Then it is added to the manual or dynamic margin.
9987 \begin_inset Newline newline
9990 The argument is passed as a string.
9992 \begin_inset Quotes eld
9996 \begin_inset Flex CharStyle:Code
9999 \begin_layout Plain Layout
10006 \begin_inset Quotes erd
10009 means that the paragraph is indented with the width of
10010 \begin_inset Quotes eld
10014 \begin_inset Flex CharStyle:Code
10017 \begin_layout Plain Layout
10024 \begin_inset Quotes erd
10027 in the normal font.
10028 You can get a negative width by prefixing the string with
10029 \begin_inset Quotes eld
10033 \begin_inset Flex CharStyle:Code
10036 \begin_layout Plain Layout
10043 \begin_inset Quotes erd
10047 This way was chosen so that the look is the same with each used screen
10052 \begin_layout Description
10053 \begin_inset Flex CharStyle:Code
10056 \begin_layout Plain Layout
10063 \begin_inset Flex CharStyle:Code
10066 \begin_layout Plain Layout
10071 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10077 \begin_inset Newline newline
10080 The kind of margin that the layout has on the left side.
10082 \begin_inset Flex CharStyle:Code
10085 \begin_layout Plain Layout
10091 just means a fixed margin.
10093 \begin_inset Flex CharStyle:Code
10096 \begin_layout Plain Layout
10102 means that the left margin depends on the string entered in the
10103 \begin_inset Flex CharStyle:MenuItem
10106 \begin_layout Plain Layout
10111 dit\SpecialChar \menuseparator
10117 \begin_inset space ~
10126 This is used to typeset nice lists without tabulators.
10128 \begin_inset Flex CharStyle:Code
10131 \begin_layout Plain Layout
10137 means that the margin depends on the size of the label.
10138 This is used for automatic enumerated headlines.
10139 It is obvious that the headline
10140 \begin_inset Quotes eld
10143 5.4.3.2.1 Very long headline
10144 \begin_inset Quotes erd
10147 must have a wider left margin (as wide as
10148 \begin_inset Quotes eld
10152 \begin_inset Quotes erd
10155 plus the space) than
10156 \begin_inset Quotes eld
10159 3.2 Very long headline
10160 \begin_inset Quotes erd
10164 \begin_inset Quotes eld
10168 \begin_inset Quotes erd
10171 are not able to do this.
10173 \begin_inset Flex CharStyle:Code
10176 \begin_layout Plain Layout
10182 is similar, but only the very first row of the paragraph is dynamic, while
10183 the others are static; this is used, for example, for descriptions.
10185 \begin_inset Flex CharStyle:Code
10188 \begin_layout Plain Layout
10194 means the margin is chosen in a way that the longest row of this paragraph
10195 fits to the right margin.
10196 This is used to typeset an address on the right edge of the page.
10199 \begin_layout Description
10200 \begin_inset Flex CharStyle:Code
10203 \begin_layout Plain Layout
10210 \begin_inset Flex CharStyle:Code
10213 \begin_layout Plain Layout
10222 \begin_inset Flex CharStyle:Code
10225 \begin_layout Plain Layout
10231 ] Whether fragile commands in this layout should be
10232 \begin_inset Flex CharStyle:Code
10235 \begin_layout Plain Layout
10248 whether this command should itself be protected.)
10251 \begin_layout Description
10252 \begin_inset Flex CharStyle:Code
10255 \begin_layout Plain Layout
10262 \begin_inset Flex CharStyle:Code
10265 \begin_layout Plain Layout
10272 \begin_inset Flex CharStyle:Code
10275 \begin_layout Plain Layout
10283 ] Whether newlines are translated into LaTeX newlines (
10284 \begin_inset Flex CharStyle:Code
10287 \begin_layout Plain Layout
10298 The translation can be switched off to allow more comfortable LaTeX editing
10302 \begin_layout Description
10303 \begin_inset Flex CharStyle:Code
10306 \begin_layout Plain Layout
10313 \begin_inset Flex CharStyle:Code
10316 \begin_layout Plain Layout
10323 \begin_inset Flex CharStyle:Code
10326 \begin_layout Plain Layout
10334 ] Whether the following Paragraph is allowed to indent its very first row.
10336 \begin_inset Flex CharStyle:Code
10339 \begin_layout Plain Layout
10345 means that it is not allowed to do so;
10346 \begin_inset Flex CharStyle:Code
10349 \begin_layout Plain Layout
10355 means it could do so if it wants to.
10358 \begin_layout Description
10359 \begin_inset Flex CharStyle:Code
10362 \begin_layout Plain Layout
10368 Name of a layout that has replaced this layout.
10369 This is used to rename a layout, while keeping backward compatibility.
10372 \begin_layout Description
10373 \begin_inset Flex CharStyle:Code
10376 \begin_layout Plain Layout
10383 \begin_inset Flex CharStyle:Code
10386 \begin_layout Plain Layout
10392 ] The number of optional arguments that can be used with this layout.
10393 This is useful for things like section headings, and only makes sense with
10397 \begin_layout Description
10398 \begin_inset Flex CharStyle:Code
10401 \begin_layout Plain Layout
10408 \begin_inset Flex CharStyle:Code
10411 \begin_layout Plain Layout
10417 ] The indent of the very first line of a paragraph.
10419 \begin_inset Flex CharStyle:Code
10422 \begin_layout Plain Layout
10428 will be fixed for a certain layout.
10429 The exception is Standard layout, since the indentation of a Standard layout
10430 paragraph can be prohibited with
10431 \begin_inset Flex CharStyle:Code
10434 \begin_layout Plain Layout
10441 Also, Standard layout paragraphs inside environments use the
10442 \begin_inset Flex CharStyle:Code
10445 \begin_layout Plain Layout
10451 of the environment, not their native one.
10452 For example, Standard paragraphs inside an enumeration are not indented.
10455 \begin_layout Description
10456 \begin_inset Flex CharStyle:Code
10459 \begin_layout Plain Layout
10466 \begin_inset Flex CharStyle:Code
10469 \begin_layout Plain Layout
10475 ] The vertical space between two paragraphs of this layout.
10478 \begin_layout Description
10479 \begin_inset Flex CharStyle:Code
10482 \begin_layout Plain Layout
10489 \begin_inset Flex CharStyle:Code
10492 \begin_layout Plain Layout
10498 ] LyX allows the user to choose either
10499 \begin_inset Quotes eld
10503 \begin_inset Quotes erd
10507 \begin_inset Quotes eld
10511 \begin_inset Quotes erd
10514 to typeset a document.
10516 \begin_inset Quotes eld
10520 \begin_inset Quotes erd
10523 is chosen, this value is completely ignored.
10525 \begin_inset Quotes eld
10529 \begin_inset Quotes erd
10532 is chosen, the parindent of a LaTeXtype
10533 \begin_inset Quotes eld
10537 \begin_inset Quotes erd
10540 layout is ignored and all paragraphs are separated by this parskip argument.
10541 The vertical space is calculated with
10542 \begin_inset Flex CharStyle:Code
10545 \begin_layout Plain Layout
10547 \begin_inset space ~
10556 \begin_inset Flex CharStyle:Code
10559 \begin_layout Plain Layout
10565 is the height of a row with the normal font.
10566 This way, the look stays the same with different screen fonts.
10569 \begin_layout Description
10570 \begin_inset Flex CharStyle:Code
10573 \begin_layout Plain Layout
10580 \begin_inset CommandInset label
10582 name "des:PathThru"
10589 \begin_inset Flex CharStyle:Code
10592 \begin_layout Plain Layout
10603 \begin_inset Flex CharStyle:Code
10606 \begin_layout Plain Layout
10612 ] Whether the contents of this paragraph should be output in raw form, meaning
10613 without special translations that LaTeX would require.
10616 \begin_layout Description
10617 \begin_inset Flex CharStyle:Code
10620 \begin_layout Plain Layout
10627 \begin_inset CommandInset label
10629 name "des:Preamble"
10633 Information to be included in the LaTeX preamable when this style is used.
10634 Used to define macros, load packages, etc., required by this particular
10637 \begin_inset Quotes eld
10641 \begin_inset Flex CharStyle:Code
10644 \begin_layout Plain Layout
10651 \begin_inset Quotes erd
10657 \begin_layout Description
10658 \begin_inset Flex CharStyle:Code
10661 \begin_layout Plain Layout
10668 \begin_inset Flex CharStyle:Code
10671 \begin_layout Plain Layout
10678 \begin_inset CommandInset label
10680 name "des:Requires"
10684 Whether the layout requires the feature
10685 \begin_inset Flex CharStyle:Code
10688 \begin_layout Plain Layout
10695 See the description of
10696 \begin_inset Flex CharStyle:Code
10699 \begin_layout Plain Layout
10706 \begin_inset CommandInset ref
10707 LatexCommand pageref
10708 reference "des:FreeSpacing"
10712 ) for information on `features'.
10716 \begin_layout Description
10717 \begin_inset Flex CharStyle:Code
10720 \begin_layout Plain Layout
10727 \begin_inset Flex CharStyle:Code
10730 \begin_layout Plain Layout
10737 \begin_inset Flex CharStyle:Code
10740 \begin_layout Plain Layout
10749 \begin_layout Description
10750 \begin_inset Flex CharStyle:Code
10753 \begin_layout Plain Layout
10760 \begin_inset Flex CharStyle:Code
10763 \begin_layout Plain Layout
10768 , onehalf, double, other
10777 ] This defines what the default spacing should be in the layout.
10779 \begin_inset Flex CharStyle:Code
10782 \begin_layout Plain Layout
10789 \begin_inset Flex CharStyle:Code
10792 \begin_layout Plain Layout
10799 \begin_inset Flex CharStyle:Code
10802 \begin_layout Plain Layout
10808 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10809 If you specify the argument
10810 \begin_inset Flex CharStyle:Code
10813 \begin_layout Plain Layout
10819 , then you should also provide a numerical argument which will be the actual
10821 Note that, contrary to other parameters,
10822 \begin_inset Flex CharStyle:Code
10825 \begin_layout Plain Layout
10831 implies the generation of specific LaTeX code, using the package
10834 \begin_inset Flex CharStyle:Code
10837 \begin_layout Plain Layout
10846 \begin_layout Description
10847 \begin_inset Flex CharStyle:Code
10850 \begin_layout Plain Layout
10856 The font used for the text body .
10858 \begin_inset CommandInset ref
10860 reference "sec:fonts"
10867 \begin_layout Description
10868 \begin_inset Flex CharStyle:Code
10871 \begin_layout Plain Layout
10879 The level of the style in the table of contents.
10880 This is used for automatic numbering of section headings.
10883 \begin_layout Description
10884 \begin_inset Flex CharStyle:Code
10887 \begin_layout Plain Layout
10894 \begin_inset Flex CharStyle:Code
10897 \begin_layout Plain Layout
10903 ] The vertical space with which the very first of a chain of paragraphs
10904 with this layout is separated from the previous paragraph.
10905 If the previous paragraph has another layout, the separations are not simply
10906 added, but the maximum is taken.
10909 \begin_layout Subsection
10913 \begin_layout Standard
10914 \begin_inset CommandInset label
10920 Since version 1.3.0 of LyX, it is has been both possible and necessary to
10921 define the floats (
10922 \begin_inset Flex CharStyle:MenuItem
10925 \begin_layout Plain Layout
10932 \begin_inset Flex CharStyle:MenuItem
10935 \begin_layout Plain Layout
10941 , \SpecialChar \ldots{}
10942 ) in the text class itself.
10943 Standard floats are included in the file
10944 \begin_inset Flex CharStyle:Code
10947 \begin_layout Plain Layout
10953 , so you may have to do no more than add
10956 \begin_layout LyX-Code
10957 Input stdfloats.inc
10960 \begin_layout Standard
10961 to your layout file.
10962 If you want to implement a text class that proposes some other float types
10963 (like the AGU class bundled with LyX), the information below will hopefully
10967 \begin_layout Description
10968 \begin_inset Flex CharStyle:Code
10971 \begin_layout Plain Layout
10978 \begin_inset Flex CharStyle:Code
10981 \begin_layout Plain Layout
10988 \begin_inset Quotes erd
10992 \begin_inset Quotes erd
10995 ] The file name extension of an auxiliary file for the list of figures (or
10997 LaTeX writes the captions to this file.
11000 \begin_layout Description
11001 \begin_inset Flex CharStyle:Code
11004 \begin_layout Plain Layout
11011 \begin_inset Flex CharStyle:Code
11014 \begin_layout Plain Layout
11021 \begin_inset Quotes erd
11025 \begin_inset Quotes erd
11028 ] The string that will be used in the menus and also for the caption.
11031 \begin_layout Description
11032 \begin_inset Flex CharStyle:Code
11035 \begin_layout Plain Layout
11042 \begin_inset Flex CharStyle:Code
11045 \begin_layout Plain Layout
11054 \begin_inset Flex CharStyle:Code
11057 \begin_layout Plain Layout
11064 \begin_inset Flex CharStyle:Code
11067 \begin_layout Plain Layout
11073 if the float is already defined by the LaTeX document class.
11075 \begin_inset Flex CharStyle:Code
11078 \begin_layout Plain Layout
11084 , the float will be defined using the LaTeX package
11085 \begin_inset Flex CharStyle:Code
11088 \begin_layout Plain Layout
11097 \begin_layout Description
11098 \begin_inset Flex CharStyle:Code
11101 \begin_layout Plain Layout
11108 \begin_inset Flex CharStyle:Code
11111 \begin_layout Plain Layout
11118 \begin_inset Quotes erd
11122 \begin_inset Quotes erd
11125 ] The heading used for the list of floats.
11128 \begin_layout Description
11129 \begin_inset Flex CharStyle:Code
11132 \begin_layout Plain Layout
11139 \begin_inset Flex CharStyle:Code
11142 \begin_layout Plain Layout
11149 \begin_inset Quotes erd
11153 \begin_inset Quotes erd
11156 ] This (optional) argument determines whether floats of this class will
11157 be numbered within some sectional unit of the document.
11158 For example, if within is equal to
11159 \begin_inset Flex CharStyle:Code
11162 \begin_layout Plain Layout
11168 , the floats will be numbered within chapters.
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 default placement for the given class of floats.
11201 The string should be as in standard LaTeX:
11202 \begin_inset Flex CharStyle:Code
11205 \begin_layout Plain Layout
11212 \begin_inset Flex CharStyle:Code
11215 \begin_layout Plain Layout
11222 \begin_inset Flex CharStyle:Code
11225 \begin_layout Plain Layout
11232 \begin_inset Flex CharStyle:Code
11235 \begin_layout Plain Layout
11241 for top, bottom, page, and here, respectively.
11245 \begin_layout Plain Layout
11246 Note that the order of these letters in the string is irrelevant, like in
11252 On top of that there is a new type,
11253 \begin_inset Flex CharStyle:Code
11256 \begin_layout Plain Layout
11262 , which does not really correspond to a float, since it means: put it
11263 \begin_inset Quotes eld
11267 \begin_inset Quotes erd
11271 Note however that the
11272 \begin_inset Flex CharStyle:Code
11275 \begin_layout Plain Layout
11281 specifier is special and, because of implementation details, cannot be
11282 used in non-builtin float types.
11283 If you do not understand what this means, just use
11284 \begin_inset Quotes eld
11288 \begin_inset Flex CharStyle:Code
11291 \begin_layout Plain Layout
11298 \begin_inset Quotes erd
11304 \begin_layout Description
11305 \begin_inset Flex CharStyle:Code
11308 \begin_layout Plain Layout
11315 \begin_inset Flex CharStyle:Code
11318 \begin_layout Plain Layout
11325 \begin_inset Quotes erd
11329 \begin_inset Quotes erd
11332 ] The style used when defining the float using
11333 \begin_inset Flex CharStyle:Code
11336 \begin_layout Plain Layout
11347 \begin_layout Description
11348 \begin_inset Flex CharStyle:Code
11351 \begin_layout Plain Layout
11358 \begin_inset Flex CharStyle:Code
11361 \begin_layout Plain Layout
11368 \begin_inset Quotes erd
11372 \begin_inset Quotes erd
11376 \begin_inset Quotes eld
11380 \begin_inset Quotes erd
11383 of the new class of floats, like program or algorithm.
11384 After the appropriate
11385 \begin_inset Flex CharStyle:Code
11388 \begin_layout Plain Layout
11397 \begin_inset Flex CharStyle:Code
11400 \begin_layout Plain Layout
11409 \begin_inset Flex CharStyle:Code
11412 \begin_layout Plain Layout
11423 \begin_layout Standard
11424 Note that defining a float with type
11425 \begin_inset Flex CharStyle:Code
11428 \begin_layout Plain Layout
11436 automatically defines the corresponding counter with name
11437 \begin_inset Flex CharStyle:Code
11440 \begin_layout Plain Layout
11451 \begin_layout Subsection
11452 Flex insets and InsetLayout
11455 \begin_layout Standard
11456 \begin_inset CommandInset label
11458 name "sec:charstyle"
11462 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11463 these are called Flex insets.
11467 \begin_layout Standard
11468 Flex insets come in three different kinds:
11471 \begin_layout Itemize
11473 \begin_inset Flex CharStyle:Code
11476 \begin_layout Plain Layout
11482 ): These define semantic markup corresponding to such LaTeX commands as
11484 \begin_inset Flex CharStyle:Code
11487 \begin_layout Plain Layout
11496 \begin_inset Flex CharStyle:Code
11499 \begin_layout Plain Layout
11510 \begin_layout Itemize
11512 \begin_inset Flex CharStyle:Code
11515 \begin_layout Plain Layout
11521 ): These can be used to define custom collapsable insets, similar to ERT,
11522 footnote, and the like.
11523 An obvious example is an endnote inset, which is defined in the
11524 \begin_inset Flex CharStyle:Code
11527 \begin_layout Plain Layout
11536 \begin_layout Itemize
11538 \begin_inset Flex CharStyle:Code
11541 \begin_layout Plain Layout
11547 ): For use with DocBook classes.
11550 \begin_layout Standard
11551 Flex insets are defined using the
11552 \begin_inset Flex CharStyle:Code
11555 \begin_layout Plain Layout
11561 tag, which shall be explained in a moment.
11564 \begin_layout Standard
11566 \begin_inset Flex CharStyle:Code
11569 \begin_layout Plain Layout
11575 tag also serves another function: It can be used to customize the general
11576 layout of many different types of insets.
11578 \begin_inset Flex CharStyle:Code
11581 \begin_layout Plain Layout
11587 can be used to customize the layout parameters for footnotes, marginal
11588 notes, note insets, ERT insets, branches, listings, indexes, boxes, tables,
11589 algorithms, URLs, and optional arguments, as well as to define Flex insets.
11592 \begin_layout Standard
11594 \begin_inset Flex CharStyle:Code
11597 \begin_layout Plain Layout
11603 definition must begin with a line of the form:
11606 \begin_layout LyX-Code
11610 \begin_layout Standard
11612 \begin_inset Flex CharStyle:Code
11615 \begin_layout Plain Layout
11621 indicates the inset whose layout is being defined, and here there are two
11625 \begin_layout Enumerate
11626 The layout for a pre-existing inset is being modified.
11627 In this case, can be
11628 \begin_inset Flex CharStyle:Code
11631 \begin_layout Plain Layout
11637 any one of the following:
11638 \begin_inset Flex CharStyle:Code
11641 \begin_layout Plain Layout
11648 \begin_inset Flex CharStyle:Code
11651 \begin_layout Plain Layout
11658 \begin_inset Flex CharStyle:Code
11661 \begin_layout Plain Layout
11668 \begin_inset Flex CharStyle:Code
11671 \begin_layout Plain Layout
11678 \begin_inset Flex CharStyle:Code
11681 \begin_layout Plain Layout
11688 \begin_inset Flex CharStyle:Code
11691 \begin_layout Plain Layout
11698 \begin_inset Flex CharStyle:Code
11701 \begin_layout Plain Layout
11708 \begin_inset Flex CharStyle:Code
11711 \begin_layout Plain Layout
11718 \begin_inset Flex CharStyle:Code
11721 \begin_layout Plain Layout
11728 \begin_inset Flex CharStyle:Code
11731 \begin_layout Plain Layout
11738 \begin_inset Flex CharStyle:Code
11741 \begin_layout Plain Layout
11748 \begin_inset Flex CharStyle:Code
11751 \begin_layout Plain Layout
11758 \begin_inset Flex CharStyle:Code
11761 \begin_layout Plain Layout
11768 \begin_inset Flex CharStyle:Code
11771 \begin_layout Plain Layout
11778 \begin_inset Flex CharStyle:Code
11781 \begin_layout Plain Layout
11788 \begin_inset Flex CharStyle:Code
11791 \begin_layout Plain Layout
11798 \begin_inset Flex CharStyle:Code
11801 \begin_layout Plain Layout
11808 \begin_inset Flex CharStyle:Code
11811 \begin_layout Plain Layout
11818 \begin_inset Flex CharStyle:Code
11821 \begin_layout Plain Layout
11828 \begin_inset Flex CharStyle:Code
11831 \begin_layout Plain Layout
11841 \begin_layout Enumerate
11842 The layout for a Flex inset is being defined.
11844 \begin_inset Flex CharStyle:Code
11847 \begin_layout Plain Layout
11853 should have the form
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
11913 is any valid identifier.
11915 \begin_inset Flex CharStyle:Code
11918 \begin_layout Plain Layout
11924 indicates on which menu the inset should appear: In the default menu structure,
11926 \begin_inset Flex CharStyle:Code
11929 \begin_layout Plain Layout
11936 \begin_inset Flex CharStyle:Code
11939 \begin_layout Plain Layout
11945 insets appear under
11946 \begin_inset Flex CharStyle:MenuItem
11949 \begin_layout Plain Layout
11950 Edit\SpecialChar \menuseparator
11957 \begin_inset Flex CharStyle:Code
11960 \begin_layout Plain Layout
11966 insets appear under
11967 \begin_inset Flex CharStyle:MenuItem
11970 \begin_layout Plain Layout
11971 Insert\SpecialChar \menuseparator
11978 Note that the definition of a flex inset must
11983 \begin_inset Flex CharStyle:Code
11986 \begin_layout Plain Layout
11995 \begin_layout Standard
11997 \begin_inset Flex CharStyle:Code
12000 \begin_layout Plain Layout
12006 definition can contain the following entries:
12009 \begin_layout Description
12010 \begin_inset Flex CharStyle:Code
12013 \begin_layout Plain Layout
12019 The color for the inset's background.
12020 The valid colors are defined in
12021 \begin_inset Flex CharStyle:Code
12024 \begin_layout Plain Layout
12033 \begin_layout Description
12034 \begin_inset Flex CharStyle:Code
12037 \begin_layout Plain Layout
12043 As with paragraph styles (see page
12044 \begin_inset CommandInset ref
12046 reference "des:CopyStyle"
12053 \begin_layout Description
12054 \begin_inset Flex CharStyle:Code
12057 \begin_layout Plain Layout
12064 \begin_inset Flex CharStyle:Code
12067 \begin_layout Plain Layout
12076 \begin_inset Flex CharStyle:Code
12079 \begin_layout Plain Layout
12085 ] Indicates whether the user may employ the Paragraph Settings dialog to
12086 customize the paragraph.
12089 \begin_layout Description
12090 \begin_inset Flex CharStyle:Code
12093 \begin_layout Plain Layout
12100 \begin_inset Flex CharStyle:Code
12103 \begin_layout Plain Layout
12110 \begin_inset Flex CharStyle:Code
12113 \begin_layout Plain Layout
12120 \begin_inset Flex CharStyle:Code
12123 \begin_layout Plain Layout
12129 , describing the rendering style used for the inset's frame and buttons.
12130 Footnotes generally use
12131 \begin_inset Flex CharStyle:Code
12134 \begin_layout Plain Layout
12140 , ERT insets generally
12141 \begin_inset Flex CharStyle:Code
12144 \begin_layout Plain Layout
12150 , and character styles
12151 \begin_inset Flex CharStyle:Code
12154 \begin_layout Plain Layout
12163 \begin_layout Description
12164 \begin_inset Flex CharStyle:Code
12167 \begin_layout Plain Layout
12173 Required at the end of the InsetLayout declarations.
12176 \begin_layout Description
12177 \begin_inset Flex CharStyle:Code
12180 \begin_layout Plain Layout
12186 The font used for both the text body
12192 \begin_inset space ~
12196 \begin_inset CommandInset ref
12198 reference "sec:fonts"
12203 Note that defining this font automatically defines the
12204 \begin_inset Flex CharStyle:Code
12207 \begin_layout Plain Layout
12213 to the same value, so define this first and define
12214 \begin_inset Flex CharStyle:Code
12217 \begin_layout Plain Layout
12223 later if you want them to be different.
12226 \begin_layout Description
12227 \begin_inset Flex CharStyle:Code
12230 \begin_layout Plain Layout
12237 \begin_inset Quotes eld
12241 \begin_inset Quotes erd
12244 language, leading to Left-to-Right (latin) output, e.g., in ERT or URL.
12248 \begin_layout Description
12249 \begin_inset Flex CharStyle:Code
12252 \begin_layout Plain Layout
12259 \begin_inset Flex CharStyle:Code
12262 \begin_layout Plain Layout
12271 \begin_inset Flex CharStyle:Code
12274 \begin_layout Plain Layout
12280 ] Indicates whether the PlainLayout should be used or, instead, the user
12281 can change the paragraph style used in the inset.
12284 \begin_layout Description
12285 \begin_inset Flex CharStyle:Code
12288 \begin_layout Plain Layout
12294 As with paragraph styles (see page
12295 \begin_inset CommandInset ref
12296 LatexCommand pageref
12297 reference "des:FreeSpacing"
12304 \begin_layout Description
12305 \begin_inset Flex CharStyle:Code
12308 \begin_layout Plain Layout
12314 As with paragraph styles (see page
12315 \begin_inset CommandInset ref
12316 LatexCommand pageref
12317 reference "des:KeepEmpty"
12324 \begin_layout Description
12325 \begin_inset Flex CharStyle:Code
12328 \begin_layout Plain Layout
12334 The font used for the label.
12336 \begin_inset space ~
12340 \begin_inset CommandInset ref
12342 reference "sec:fonts"
12347 Note that this definition can never appear before
12348 \begin_inset Flex CharStyle:Code
12351 \begin_layout Plain Layout
12357 , lest it be ineffective.
12360 \begin_layout Description
12361 \begin_inset Flex CharStyle:Code
12364 \begin_layout Plain Layout
12370 What will be displayed on the button or elsewhere as the inset label.
12371 Some inset types (ERT and Branch) modify this label on the fly.
12374 \begin_layout Description
12375 \begin_inset Flex CharStyle:Code
12378 \begin_layout Plain Layout
12384 The name of the corresponding LaTeX stuff.
12385 Either the environment or command name.
12388 \begin_layout Description
12389 \begin_inset Flex CharStyle:Code
12392 \begin_layout Plain Layout
12398 The optional parameter for the corresponding
12399 \begin_inset Flex CharStyle:Code
12402 \begin_layout Plain Layout
12408 stuff, including possible bracket pairs like
12409 \begin_inset Flex CharStyle:Code
12412 \begin_layout Plain Layout
12419 This parameter cannot be changed from within LyX.
12422 \begin_layout Description
12423 \begin_inset Flex CharStyle:Code
12426 \begin_layout Plain Layout
12432 As with paragraph styles (see page
12433 \begin_inset CommandInset ref
12434 LatexCommand pageref
12435 reference "des:LatexType"
12442 \begin_layout Description
12443 \begin_inset Flex CharStyle:Code
12446 \begin_layout Plain Layout
12453 \begin_inset Flex CharStyle:Code
12456 \begin_layout Plain Layout
12463 \begin_inset Flex CharStyle:Code
12466 \begin_layout Plain Layout
12473 \begin_inset Flex CharStyle:Code
12476 \begin_layout Plain Layout
12483 \begin_inset Flex CharStyle:Code
12486 \begin_layout Plain Layout
12492 (indicating a dummy definition ending definitions of charstyles, etc).
12493 This entry is required in and is only meaningful for Flex insets.
12496 \begin_layout Description
12497 \begin_inset Flex CharStyle:Code
12500 \begin_layout Plain Layout
12507 \begin_inset Flex CharStyle:Code
12510 \begin_layout Plain Layout
12519 \begin_inset Flex CharStyle:Code
12522 \begin_layout Plain Layout
12528 ] Whether multiple paragraphs are permitted in this inset.
12529 This will also set CustomPars to the same value and ForcePlain to the opposite
12531 These can be reset to other values, if they are used
12538 \begin_layout Description
12539 \begin_inset Flex CharStyle:Code
12542 \begin_layout Plain Layout
12549 \begin_inset Flex CharStyle:Code
12552 \begin_layout Plain Layout
12561 \begin_inset Flex CharStyle:Code
12564 \begin_layout Plain Layout
12570 ] Whether fragile commands in this layout should be
12571 \begin_inset Flex CharStyle:Code
12574 \begin_layout Plain Layout
12587 whether the command should itself be protected.)
12590 \begin_layout Description
12591 \begin_inset Flex CharStyle:Code
12594 \begin_layout Plain Layout
12601 \begin_inset Flex CharStyle:Code
12604 \begin_layout Plain Layout
12613 \begin_inset Flex CharStyle:Code
12616 \begin_layout Plain Layout
12622 ] As with paragraph styles (see page
12623 \begin_inset CommandInset ref
12625 reference "des:PathThru"
12632 \begin_layout Description
12633 \begin_inset Flex CharStyle:Code
12636 \begin_layout Plain Layout
12642 As with paragraph styles (see page
12643 \begin_inset CommandInset ref
12644 LatexCommand pageref
12645 reference "des:Preamble"
12652 \begin_layout Description
12653 \begin_inset Flex CharStyle:Code
12656 \begin_layout Plain Layout
12663 \begin_inset Flex CharStyle:Code
12666 \begin_layout Plain Layout
12672 ] As with paragraph styles (see page
12673 \begin_inset CommandInset ref
12674 LatexCommand pageref
12675 reference "des:Requires"
12682 \begin_layout Subsection
12686 \begin_layout Standard
12687 \begin_inset CommandInset label
12693 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12695 \begin_inset Flex CharStyle:MenuItem
12698 \begin_layout Plain Layout
12705 \begin_inset Flex CharStyle:MenuItem
12708 \begin_layout Plain Layout
12714 , \SpecialChar \ldots{}
12715 ) in the text class itself.
12716 The standard counters are defined in the file
12717 \begin_inset Flex CharStyle:Code
12720 \begin_layout Plain Layout
12726 , so you may have to do no more than add
12729 \begin_layout LyX-Code
12730 Input stdcounters.inc
12733 \begin_layout Standard
12734 to your layout file to get them to work.
12735 But if you want to define custom counters, then you can do so.
12736 The counter declaration must begin with:
12739 \begin_layout LyX-Code
12743 \begin_layout Standard
12744 where of course `name' is replaced by the name of the counter.
12745 And it must end with
12746 \begin_inset Quotes eld
12750 \begin_inset Flex CharStyle:Code
12753 \begin_layout Plain Layout
12760 \begin_inset Quotes erd
12764 The following parameters can also be used:
12767 \begin_layout Description
12768 \begin_inset Flex CharStyle:Code
12771 \begin_layout Plain Layout
12772 LabelString [string=""]
12777 when this is defined, this string defines how the counter is displayed.
12778 Setting this value sets
12779 \begin_inset Flex CharStyle:Code
12782 \begin_layout Plain Layout
12783 LabelStringAppendix
12789 The following special constructs can be used in the string:
12793 \begin_layout Itemize
12794 \begin_inset Flex CharStyle:Code
12797 \begin_layout Plain Layout
12805 will be replaced by the expansion of the
12806 \begin_inset Flex CharStyle:Code
12809 \begin_layout Plain Layout
12816 \begin_inset Flex CharStyle:Code
12819 \begin_layout Plain Layout
12820 LabelStringAppendix
12826 \begin_inset Flex CharStyle:Code
12829 \begin_layout Plain Layout
12839 \begin_layout Itemize
12840 counter values can be expressed using LaTeX-like macros
12841 \begin_inset Flex CharStyle:Code
12844 \begin_layout Plain Layout
12861 \begin_inset Flex CharStyle:Code
12864 \begin_layout Plain Layout
12876 \begin_layout Plain Layout
12886 Actually, the situation is a bit more complicated: any
12905 other than those descibed below will produce arabic numerals.
12906 It would not be surprising to see this change in the future.
12912 \begin_inset Flex CharStyle:Code
12915 \begin_layout Plain Layout
12921 : 1, 2, 3,\SpecialChar \ldots{}
12923 \begin_inset Flex CharStyle:Code
12926 \begin_layout Plain Layout
12932 for lower-case letters: a, b, c, \SpecialChar \ldots{}
12934 \begin_inset Flex CharStyle:Code
12937 \begin_layout Plain Layout
12943 for upper-case letters: A, B, C, \SpecialChar \ldots{}
12945 \begin_inset Flex CharStyle:Code
12948 \begin_layout Plain Layout
12954 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12956 \begin_inset Flex CharStyle:Code
12959 \begin_layout Plain Layout
12965 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12967 \begin_inset Flex CharStyle:Code
12970 \begin_layout Plain Layout
12976 for hebrew numerals.
12980 \begin_layout Standard
12981 If LabelString is not defined, a default value is constructed as follows:
12982 if the counter has a master counter
12983 \begin_inset Flex CharStyle:Code
12986 \begin_layout Plain Layout
12993 \begin_inset Flex CharStyle:Code
12996 \begin_layout Plain Layout
13003 \begin_inset Flex CharStyle:Code
13006 \begin_layout Plain Layout
13016 is used; otherwise the string
13017 \begin_inset Flex CharStyle:Code
13020 \begin_layout Plain Layout
13031 \begin_layout Description
13032 \begin_inset Flex CharStyle:Code
13035 \begin_layout Plain Layout
13036 LabelStringAppendix [string=""]
13042 \begin_inset Flex CharStyle:Code
13045 \begin_layout Plain Layout
13051 , but for use in the Appendix.
13054 \begin_layout Description
13055 \begin_inset Flex CharStyle:Code
13058 \begin_layout Plain Layout
13065 \begin_inset Flex CharStyle:Code
13068 \begin_layout Plain Layout
13075 \begin_inset Quotes erd
13079 \begin_inset Quotes erd
13082 ] If this is set to the name of another counter, the present counter will
13083 be reset everytime the other one is increased.
13085 \begin_inset Flex CharStyle:Code
13088 \begin_layout Plain Layout
13095 \begin_inset Flex CharStyle:Code
13098 \begin_layout Plain Layout
13107 \begin_layout Subsection
13111 \begin_layout Standard
13112 \begin_inset CommandInset label
13118 A font description looks like this:
13121 \begin_layout LyX-Code
13131 \begin_layout LyX-Code
13135 \begin_layout LyX-Code
13139 \begin_layout Standard
13140 The following commands are available:
13143 \begin_layout Description
13144 \begin_inset Flex CharStyle:Code
13147 \begin_layout Plain Layout
13154 \begin_inset Flex CharStyle:Code
13157 \begin_layout Plain Layout
13166 \begin_inset Flex CharStyle:Code
13169 \begin_layout Plain Layout
13176 \begin_inset Flex CharStyle:Code
13179 \begin_layout Plain Layout
13186 \begin_inset Flex CharStyle:Code
13189 \begin_layout Plain Layout
13196 \begin_inset Flex CharStyle:Code
13199 \begin_layout Plain Layout
13206 \begin_inset Flex CharStyle:Code
13209 \begin_layout Plain Layout
13216 \begin_inset Flex CharStyle:Code
13219 \begin_layout Plain Layout
13226 \begin_inset Flex CharStyle:Code
13229 \begin_layout Plain Layout
13236 \begin_inset Flex CharStyle:Code
13239 \begin_layout Plain Layout
13248 \begin_layout Description
13249 \begin_inset Flex CharStyle:Code
13252 \begin_layout Plain Layout
13261 \begin_inset Flex CharStyle:Code
13264 \begin_layout Plain Layout
13275 \begin_inset Flex CharStyle:Code
13278 \begin_layout Plain Layout
13285 \begin_inset Flex CharStyle:Code
13288 \begin_layout Plain Layout
13297 \begin_layout Description
13298 \begin_inset Flex CharStyle:Code
13301 \begin_layout Plain Layout
13308 \begin_inset Flex CharStyle:Code
13311 \begin_layout Plain Layout
13317 ] Valid argument sare:
13318 \begin_inset Flex CharStyle:Code
13321 \begin_layout Plain Layout
13328 \begin_inset Flex CharStyle:Code
13331 \begin_layout Plain Layout
13338 \begin_inset Flex CharStyle:Code
13341 \begin_layout Plain Layout
13348 \begin_inset Flex CharStyle:Code
13351 \begin_layout Plain Layout
13358 \begin_inset Flex CharStyle:Code
13361 \begin_layout Plain Layout
13368 \begin_inset Flex CharStyle:Code
13371 \begin_layout Plain Layout
13378 Each of these turns on or off the corresponding attribute.
13381 \begin_layout Description
13382 \begin_inset Flex CharStyle:Code
13385 \begin_layout Plain Layout
13394 \begin_inset Flex CharStyle:Code
13397 \begin_layout Plain Layout
13408 \begin_inset Flex CharStyle:Code
13411 \begin_layout Plain Layout
13420 \begin_layout Description
13421 \begin_inset Flex CharStyle:Code
13424 \begin_layout Plain Layout
13433 \begin_inset Flex CharStyle:Code
13436 \begin_layout Plain Layout
13447 \begin_inset Flex CharStyle:Code
13450 \begin_layout Plain Layout
13457 \begin_inset Flex CharStyle:Code
13460 \begin_layout Plain Layout
13467 \begin_inset Flex CharStyle:Code
13470 \begin_layout Plain Layout
13479 \begin_layout Description
13480 \begin_inset Flex CharStyle:Code
13483 \begin_layout Plain Layout
13490 \begin_inset Flex CharStyle:Code
13493 \begin_layout Plain Layout
13500 \begin_inset Flex CharStyle:Code
13503 \begin_layout Plain Layout
13510 \begin_inset Flex CharStyle:Code
13513 \begin_layout Plain Layout
13522 \begin_inset Flex CharStyle:Code
13525 \begin_layout Plain Layout
13532 \begin_inset Flex CharStyle:Code
13535 \begin_layout Plain Layout
13542 \begin_inset Flex CharStyle:Code
13545 \begin_layout Plain Layout
13552 \begin_inset Flex CharStyle:Code
13555 \begin_layout Plain Layout
13562 \begin_inset Flex CharStyle:Code
13565 \begin_layout Plain Layout
13574 \begin_layout Subsection
13575 Upgrading old layout files
13578 \begin_layout Standard
13579 The file format of layout files changes from time to time, so old layout
13580 files need to be converted.
13581 This process has been automated since LyX 1.4.0: If LyX reads an old format
13582 layout file it will call the conversion tool
13583 \begin_inset Flex CharStyle:Code
13586 \begin_layout Plain Layout
13587 LyXDir/scripts/layout2layout.py
13592 and convert it to a temporary file in current format.
13593 The original file is left untouched.
13594 If you want to convert the layout file permanently, just call the converter
13598 \begin_layout LyX-Code
13599 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13602 \begin_layout Standard
13603 (You need to replace
13604 \begin_inset Flex CharStyle:Code
13607 \begin_layout Plain Layout
13613 with the name of your LyX system directory, unless you happen to have defined
13614 such an environment variable.) Then copy
13615 \begin_inset Flex CharStyle:Code
13618 \begin_layout Plain Layout
13625 \begin_inset Flex CharStyle:Code
13628 \begin_layout Plain Layout
13637 \begin_layout Standard
13638 The automatic conversion only handles syntax changes.
13639 It cannot handle the case where the contents of included files was changed,
13640 so these will have to be converted separately.
13643 \begin_layout Section
13645 \begin_inset CommandInset label
13647 name "sec:templates"
13654 \begin_layout Standard
13655 Templates are created just like usual documents.
13656 The only difference is that usual documents contain all possible settings,
13657 including the font scheme and the paper size.
13658 Usually a user doesn't want a template to overwrite his defaults in these
13660 For that reason, the designer of a template should remove the corresponding
13662 \begin_inset Flex CharStyle:Code
13665 \begin_layout Plain Layout
13674 \begin_inset Flex CharStyle:Code
13677 \begin_layout Plain Layout
13685 from the template LyX file.
13686 This can be done with any simple text-editor, for example
13687 \begin_inset Flex CharStyle:Code
13690 \begin_layout Plain Layout
13697 \begin_inset Flex CharStyle:Code
13700 \begin_layout Plain Layout
13710 \begin_layout Standard
13711 Put the edited template files you create in
13712 \begin_inset Flex CharStyle:Code
13715 \begin_layout Plain Layout
13721 , copy the ones you use from the global template directory in
13722 \begin_inset Flex CharStyle:Code
13725 \begin_layout Plain Layout
13731 to the same place, and redefine the template path in the
13732 \begin_inset Flex CharStyle:MenuItem
13735 \begin_layout Plain Layout
13743 \SpecialChar \menuseparator
13748 references\SpecialChar \menuseparator
13757 \begin_layout Standard
13758 Note that there is a template which has a particular meaning:
13759 \begin_inset Flex CharStyle:Code
13762 \begin_layout Plain Layout
13769 This template is loaded everytime you create a new document with
13770 \begin_inset Flex CharStyle:MenuItem
13773 \begin_layout Plain Layout
13783 \SpecialChar \menuseparator
13785 \begin_inset Flex CharStyle:MenuItem
13788 \begin_layout Plain Layout
13798 in order to provide useful defaults.
13799 To create this template from inside LyX, all you have to do is to open
13800 a document with the correct settings, and use the
13801 \begin_inset Flex CharStyle:MenuItem
13804 \begin_layout Plain Layout
13809 e as Document Defaults
13817 \begin_layout Chapter
13818 Including External Material
13821 \begin_layout Standard
13822 \begin_inset Box Shadowbox
13831 height_special "totalheight"
13834 \begin_layout Plain Layout
13835 WARNING: This portion of the documentation has not been updated for some
13837 We certainly hope that it is still accurate, but there are no guarantees.
13845 \begin_layout Standard
13846 The use of material from sources external to LyX is covered in detail in
13852 This part of the manual covers what needs to happen behind the scenes for
13853 new sorts of material to be included.
13856 \begin_layout Section
13860 \begin_layout Standard
13861 The external material feature is based on the concept of a
13866 A template is a specification of how LyX should interface with a certain
13868 As bundled, LyX comes with predefined templates for Xfig figures, various
13869 raster format images, chess diagrams, and LilyPond music notation.
13870 You can check the actual list by using the menu
13871 \begin_inset Flex CharStyle:MenuItem
13874 \begin_layout Plain Layout
13875 Insert\SpecialChar \menuseparator
13876 File\SpecialChar \menuseparator
13883 Furthermore, it is possible to roll your own template to support a specific
13885 Later we'll describe in more detail what is involved, and hopefully you
13886 will submit all the templates you create so we can include them in a later
13890 \begin_layout Standard
13891 Another basic idea of the external material feature is to distinguish between
13892 the original file that serves as a base for final material and the produced
13893 file that is included in your exported or printed document.
13894 For example, consider the case of a figure produced with
13895 \begin_inset Flex CharStyle:Code
13898 \begin_layout Plain Layout
13905 The Xfig application itself works on an original file with the
13906 \begin_inset Flex CharStyle:Code
13909 \begin_layout Plain Layout
13916 Within XFig, you create and change your figure, and when you are done,
13918 \begin_inset Flex CharStyle:Code
13921 \begin_layout Plain Layout
13928 When you want to include the figure in your document, you invoke
13929 \begin_inset Flex CharStyle:Code
13932 \begin_layout Plain Layout
13938 in order to create a PostScript file that can readily be included in your
13941 \begin_inset Flex CharStyle:Code
13944 \begin_layout Plain Layout
13950 file is the original file, and the PostScript file is the produced file.
13953 \begin_layout Standard
13954 This distinction is important in order to allow updating of the material
13955 while you are in the process of writing the document.
13956 Furthermore, it provides us with the flexibility that is needed to support
13957 multiple export formats.
13958 For instance, in the case of a plain text file, it is not exactly an award-winn
13959 ing idea to include the figure as raw PostScript®.
13960 Instead, you'd either prefer to just include a reference to the figure
13961 or try to invoke some graphics to Ascii converter to make the final result
13962 look similar to the real graphics.
13963 The external material management allows you to do this, because it is parameter
13964 ized on the different export formats that LyX supports.
13967 \begin_layout Standard
13968 Besides supporting the production of different products according to the
13969 exported format, it supports tight integration with editing and viewing
13971 In the case of an XFig figure, you are able to invoke Xfig on the original
13972 file with a single click from within the external material dialog in LyX,
13973 and also preview the produced PostScript file with ghostview with another
13975 No more fiddling around with the command line and/or file browsers to locate
13976 and manipulate the original or produced files.
13977 In this way, you are finally able to take full advantage of the many different
13978 applications that are relevant to use when you write your documents, and
13979 ultimately be more productive.
13982 \begin_layout Section
13983 The external template configuration file
13986 \begin_layout Standard
13987 It is relatively easy to add custom external template definitions to LyX.
13988 However, be aware that doing this in an careless manner most probably
13992 introduce an easily exploitable security hole.
13993 So before you do this, please read the discussion about security in section
13995 \begin_inset CommandInset ref
13997 reference "sec:Security-discussion"
14004 \begin_layout Standard
14005 Having said that, we encourage you to submit any interesting templates that
14010 \begin_layout Standard
14011 The external templates are defined in the
14012 \begin_inset Flex CharStyle:Code
14015 \begin_layout Plain Layout
14016 LyXDir/lib/external_templates
14022 You can place your own version in
14023 \begin_inset Flex CharStyle:Code
14026 \begin_layout Plain Layout
14027 UserDir/external_templates
14035 \begin_layout Standard
14036 A typical template looks like this:
14039 \begin_layout LyX-Code
14043 \begin_layout LyX-Code
14044 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14047 \begin_layout LyX-Code
14051 \begin_layout LyX-Code
14055 \begin_layout LyX-Code
14059 \begin_layout LyX-Code
14063 \begin_layout LyX-Code
14067 \begin_layout LyX-Code
14068 AutomaticProduction true
14071 \begin_layout LyX-Code
14075 \begin_layout LyX-Code
14079 \begin_layout LyX-Code
14083 \begin_layout LyX-Code
14084 TransformCommand Rotate RotationLatexCommand
14087 \begin_layout LyX-Code
14088 TransformCommand Resize ResizeLatexCommand
14091 \begin_layout LyX-Code
14092 Product "$$RotateFront$$ResizeFront
14095 \begin_layout LyX-Code
14100 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14103 \begin_layout LyX-Code
14104 $$ResizeBack$$RotateBack"
14107 \begin_layout LyX-Code
14111 \begin_layout LyX-Code
14112 UpdateResult "$$AbsPath$$Basename.pstex_t"
14115 \begin_layout LyX-Code
14116 Requirement "graphicx"
14119 \begin_layout LyX-Code
14120 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14123 \begin_layout LyX-Code
14124 ReferencedFile latex "$$AbsPath$$Basename.eps"
14127 \begin_layout LyX-Code
14128 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14131 \begin_layout LyX-Code
14135 \begin_layout LyX-Code
14139 \begin_layout LyX-Code
14140 TransformCommand Rotate RotationLatexCommand
14143 \begin_layout LyX-Code
14144 TransformCommand Resize ResizeLatexCommand
14147 \begin_layout LyX-Code
14148 Product "$$RotateFront$$ResizeFront
14151 \begin_layout LyX-Code
14156 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14159 \begin_layout LyX-Code
14160 $$ResizeBack$$RotateBack"
14163 \begin_layout LyX-Code
14164 UpdateFormat pdftex
14167 \begin_layout LyX-Code
14168 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14171 \begin_layout LyX-Code
14172 Requirement "graphicx"
14175 \begin_layout LyX-Code
14176 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14179 \begin_layout LyX-Code
14180 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14183 \begin_layout LyX-Code
14187 \begin_layout LyX-Code
14191 \begin_layout LyX-Code
14192 Product "$$Contents(
14194 "$$AbsPath$$Basename.asc
14199 \begin_layout LyX-Code
14200 UpdateFormat asciixfig
14203 \begin_layout LyX-Code
14204 UpdateResult "$$AbsPath$$Basename.asc"
14207 \begin_layout LyX-Code
14211 \begin_layout LyX-Code
14215 \begin_layout LyX-Code
14216 Product "<graphic fileref=
14218 "$$AbsOrRelPathMaster$$Basename.eps
14223 \begin_layout LyX-Code
14227 \begin_layout LyX-Code
14231 \begin_layout LyX-Code
14232 UpdateResult "$$AbsPath$$Basename.eps"
14235 \begin_layout LyX-Code
14236 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14239 \begin_layout LyX-Code
14240 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14243 \begin_layout LyX-Code
14247 \begin_layout LyX-Code
14248 Product "[XFig: $$FName]"
14251 \begin_layout LyX-Code
14255 \begin_layout LyX-Code
14259 \begin_layout Standard
14260 As you can see, the template is enclosed in
14261 \begin_inset Flex CharStyle:Code
14264 \begin_layout Plain Layout
14270 \SpecialChar \ldots{}
14272 \begin_inset Flex CharStyle:Code
14275 \begin_layout Plain Layout
14282 It contains a header specifying some general settings and, for each supported
14283 primary document file format, a section
14284 \begin_inset Flex CharStyle:Code
14287 \begin_layout Plain Layout
14293 \SpecialChar \ldots{}
14295 \begin_inset Flex CharStyle:Code
14298 \begin_layout Plain Layout
14307 \begin_layout Subsection
14308 The template header
14311 \begin_layout Description
14312 \begin_inset Flex CharStyle:Code
14315 \begin_layout Plain Layout
14316 AutomaticProduction
14317 \begin_inset space ~
14325 Whether the file represented by the template must be generated by LyX.
14326 This command must occur exactly once.
14329 \begin_layout Description
14330 \begin_inset Flex CharStyle:Code
14333 \begin_layout Plain Layout
14335 \begin_inset space ~
14343 A glob pattern that is used in the file dialog to filter out the desired
14345 If there is more than one possible file extension (e.g.
14346 \begin_inset space ~
14350 \begin_inset Flex CharStyle:Code
14353 \begin_layout Plain Layout
14360 \begin_inset Flex CharStyle:Code
14363 \begin_layout Plain Layout
14369 ), use something like
14370 \begin_inset Flex CharStyle:Code
14373 \begin_layout Plain Layout
14380 This command must occur exactly once.
14383 \begin_layout Description
14384 \begin_inset Flex CharStyle:Code
14387 \begin_layout Plain Layout
14389 \begin_inset space ~
14397 The text that is displayed on the button.
14398 This command must occur exactly once.
14401 \begin_layout Description
14402 \begin_inset Flex CharStyle:Code
14405 \begin_layout Plain Layout
14407 \begin_inset space ~
14411 \begin_inset space ~
14419 The help text that is used in the External dialog.
14420 Provide enough information to explain to the user just what the template
14421 can provide him with.
14422 This command must occur exactly once.
14425 \begin_layout Description
14426 \begin_inset Flex CharStyle:Code
14429 \begin_layout Plain Layout
14431 \begin_inset space ~
14439 The file format of the original file.
14440 This must be the name of a format that is known to LyX (see section
14441 \begin_inset CommandInset ref
14443 reference "sub:Formats"
14449 \begin_inset Quotes eld
14453 \begin_inset Flex CharStyle:Code
14456 \begin_layout Plain Layout
14463 \begin_inset Quotes erd
14466 if the template can handle original files of more than one format.
14467 LyX will attempt to interrogate the file itself in order to deduce its
14468 format in this case.
14469 This command must occur exactly once.
14472 \begin_layout Description
14473 \begin_inset Flex CharStyle:Code
14476 \begin_layout Plain Layout
14478 \begin_inset space ~
14486 A unique name for the template.
14487 It must not contain substitution macros (see below).
14490 \begin_layout Description
14491 \begin_inset Flex CharStyle:Code
14494 \begin_layout Plain Layout
14496 \begin_inset space ~
14499 Rotate|Resize|Clip|Extra
14504 This command specifies which transformations are supported by this template.
14505 It may occur zero or more times.
14506 This command enables the corresponding tabs in the external dialog.
14508 \begin_inset Flex CharStyle:Code
14511 \begin_layout Plain Layout
14517 command must have either a corresponding
14518 \begin_inset Flex CharStyle:Code
14521 \begin_layout Plain Layout
14528 \begin_inset Flex CharStyle:Code
14531 \begin_layout Plain Layout
14538 \begin_inset Flex CharStyle:Code
14541 \begin_layout Plain Layout
14548 Otherwise the transformation will not be supported by that format.
14551 \begin_layout Subsection
14555 \begin_layout Description
14556 \begin_inset Flex CharStyle:Code
14559 \begin_layout Plain Layout
14561 \begin_inset space ~
14564 LaTeX|PDFLaTeX|PlainText|DocBook
14569 The primary document file format that this format definition is for.
14570 Not every template has a sensible representation in all document file formats.
14571 Please define nevertheless a
14572 \begin_inset Flex CharStyle:Code
14575 \begin_layout Plain Layout
14581 section for all formats.
14582 Use a dummy text when no representation is available.
14583 Then you can at least see a reference to the external material in the exported
14587 \begin_layout Description
14588 \begin_inset Flex CharStyle:Code
14591 \begin_layout Plain Layout
14593 \begin_inset space ~
14597 \begin_inset space ~
14605 This command defines an additional macro
14606 \begin_inset Flex CharStyle:Code
14609 \begin_layout Plain Layout
14615 for substitution in
14616 \begin_inset Flex CharStyle:Code
14619 \begin_layout Plain Layout
14627 \begin_inset Flex CharStyle:Code
14630 \begin_layout Plain Layout
14636 itself may contain substitution macros.
14637 The advantage over using
14638 \begin_inset Flex CharStyle:Code
14641 \begin_layout Plain Layout
14648 \begin_inset Flex CharStyle:Code
14651 \begin_layout Plain Layout
14657 is that the substituted value of
14658 \begin_inset Flex CharStyle:Code
14661 \begin_layout Plain Layout
14667 is sanitized so that it is a valid optional argument in the document format.
14668 This command may occur zero or more times.
14671 \begin_layout Description
14672 \begin_inset Flex CharStyle:Code
14675 \begin_layout Plain Layout
14677 \begin_inset space ~
14685 The text that is inserted in the exported document.
14686 This is actually the most important command and can be quite complex.
14687 This command must occur exactly once.
14690 \begin_layout Description
14691 \begin_inset Flex CharStyle:Code
14694 \begin_layout Plain Layout
14696 \begin_inset space ~
14704 This command specifies a preamble snippet that will be included in the
14706 It has to be defined using
14707 \begin_inset Flex CharStyle:Code
14710 \begin_layout Plain Layout
14716 \SpecialChar \ldots{}
14718 \begin_inset Flex CharStyle:Code
14721 \begin_layout Plain Layout
14728 This command may occur zero or more times.
14731 \begin_layout Description
14732 \begin_inset Flex CharStyle:Code
14735 \begin_layout Plain Layout
14737 \begin_inset space ~
14741 \begin_inset space ~
14749 This command denotes files that are created by the conversion process and
14750 are needed for a particular export format.
14751 If the filename is relative, it is interpreted relative to the master document.
14752 This command may be given zero or more times.
14755 \begin_layout Description
14756 \begin_inset Flex CharStyle:Code
14759 \begin_layout Plain Layout
14761 \begin_inset space ~
14769 The name of a required LaTeX package.
14770 The package is included via
14771 \begin_inset Flex CharStyle:Code
14774 \begin_layout Plain Layout
14782 in the LaTeX preamble.
14783 This command may occur zero or more times.
14786 \begin_layout Description
14787 \begin_inset Flex CharStyle:Code
14790 \begin_layout Plain Layout
14792 \begin_inset space ~
14796 \begin_inset space ~
14799 RotationLatexCommand
14804 This command specifies that the built in LaTeX command should be used for
14806 This command may occur once or not at all.
14809 \begin_layout Description
14810 \begin_inset Flex CharStyle:Code
14813 \begin_layout Plain Layout
14815 \begin_inset space ~
14819 \begin_inset space ~
14827 This command specifies that the built in LaTeX command should be used for
14829 This command may occur once or not at all.
14832 \begin_layout Description
14833 \begin_inset Flex CharStyle:Code
14836 \begin_layout Plain Layout
14838 \begin_inset space ~
14842 \begin_inset space ~
14845 RotationLatexOption
14850 This command specifies that rotation is done via an optional argument.
14851 This command may occur once or not at all.
14854 \begin_layout Description
14855 \begin_inset Flex CharStyle:Code
14858 \begin_layout Plain Layout
14860 \begin_inset space ~
14864 \begin_inset space ~
14872 This command specifies that resizing is done via an optional argument.
14873 This command may occur once or not at all.
14876 \begin_layout Description
14877 \begin_inset Flex CharStyle:Code
14880 \begin_layout Plain Layout
14882 \begin_inset space ~
14886 \begin_inset space ~
14894 This command specifies that clipping is done via an optional argument.
14895 This command may occur once or not at all.
14898 \begin_layout Description
14899 \begin_inset Flex CharStyle:Code
14902 \begin_layout Plain Layout
14904 \begin_inset space ~
14908 \begin_inset space ~
14916 This command specifies that an extra optional argument is used.
14917 This command may occur once or not at all.
14920 \begin_layout Description
14921 \begin_inset Flex CharStyle:Code
14924 \begin_layout Plain Layout
14926 \begin_inset space ~
14934 The file format of the converted file.
14935 This must be the name of a format that is known to LyX (see the
14936 \begin_inset Flex CharStyle:MenuItem
14939 \begin_layout Plain Layout
14944 ools\SpecialChar \menuseparator
14949 references:Conversion
14955 This command must occur exactly once.
14958 \begin_layout Description
14959 \begin_inset Flex CharStyle:Code
14962 \begin_layout Plain Layout
14964 \begin_inset space ~
14972 The file name of the converted file.
14973 The file name must be absolute.
14974 This command must occur exactly once.
14977 \begin_layout Subsection
14978 Preamble definitions
14981 \begin_layout Standard
14982 The external template configuration file may contain additional preamble
14983 definitions enclosed by
14984 \begin_inset Flex CharStyle:Code
14987 \begin_layout Plain Layout
14993 \SpecialChar \ldots{}
14995 \begin_inset Flex CharStyle:Code
14998 \begin_layout Plain Layout
15005 They can be used by the templates in the
15006 \begin_inset Flex CharStyle:Code
15009 \begin_layout Plain Layout
15018 \begin_layout Section
15019 The substitution mechanism
15022 \begin_layout Standard
15023 When the external material facility invokes an external program, it is done
15024 on the basis of a command defined in the template configuration file.
15025 These commands can contain various macros that are expanded before execution.
15026 Execution always take place in the directory of the containing document.
15029 \begin_layout Standard
15030 Also, whenever external material is to be displayed, the name will be produced
15031 by the substitution mechanism, and most other commands in the template
15032 definition support substitution as well.
15035 \begin_layout Standard
15036 The available macros are the following:
15039 \begin_layout Description
15040 \begin_inset Flex CharStyle:Code
15043 \begin_layout Plain Layout
15044 $$AbsOrRelPathMaster
15049 The file path, absolute or relative to the master LyX document.
15052 \begin_layout Description
15053 \begin_inset Flex CharStyle:Code
15056 \begin_layout Plain Layout
15057 $$AbsOrRelPathParent
15062 The file path, absolute or relative to the LyX document.
15065 \begin_layout Description
15066 \begin_inset Flex CharStyle:Code
15069 \begin_layout Plain Layout
15075 The absolute file path.
15078 \begin_layout Description
15079 \begin_inset Flex CharStyle:Code
15082 \begin_layout Plain Layout
15088 The filename without path and without the extension.
15091 \begin_layout Description
15092 \begin_inset Flex CharStyle:Code
15095 \begin_layout Plain Layout
15097 \begin_inset Quotes eld
15101 \begin_inset Quotes erd
15109 This macro will expand to the contents of the file with the name
15110 \begin_inset Flex CharStyle:Code
15113 \begin_layout Plain Layout
15122 \begin_layout Description
15123 \begin_inset Flex CharStyle:Code
15126 \begin_layout Plain Layout
15132 The file extension (including the dot).
15135 \begin_layout Description
15136 \begin_inset Flex CharStyle:Code
15139 \begin_layout Plain Layout
15145 The filename of the file specified in the external material dialog.
15146 This is either an absolute name, or it is relative to the LyX document.
15149 \begin_layout Description
15150 \begin_inset Flex CharStyle:Code
15153 \begin_layout Plain Layout
15160 \begin_inset Flex CharStyle:Code
15163 \begin_layout Plain Layout
15169 (absolute name or relative to the LyX document).
15172 \begin_layout Description
15173 \begin_inset Flex CharStyle:Code
15176 \begin_layout Plain Layout
15182 The file path, relative to the master LyX document.
15185 \begin_layout Description
15186 \begin_inset Flex CharStyle:Code
15189 \begin_layout Plain Layout
15195 The file path, relative to the LyX document.
15198 \begin_layout Description
15199 \begin_inset Flex CharStyle:Code
15202 \begin_layout Plain Layout
15208 This macro will expand to the absolute path of the system directory.
15209 This is typically used to point to the various helper scripts that are
15213 \begin_layout Description
15214 \begin_inset Flex CharStyle:Code
15217 \begin_layout Plain Layout
15223 A name and full path to a temporary file which will be automatically deleted
15224 whenever the containing document is closed, or the external material insertion
15228 \begin_layout Standard
15229 All path macros contain a trailing directory separator, so you can construct
15231 the absolute filename with
15232 \begin_inset Flex CharStyle:Code
15235 \begin_layout Plain Layout
15236 $$AbsPath$$Basename$$Extension
15244 \begin_layout Standard
15245 The macros above are substituted in all commands unless otherwise noted.
15247 \begin_inset Flex CharStyle:Code
15250 \begin_layout Plain Layout
15256 supports additionally the following substitutions if they are enabled by
15258 \begin_inset Flex CharStyle:Code
15261 \begin_layout Plain Layout
15268 \begin_inset Flex CharStyle:Code
15271 \begin_layout Plain Layout
15280 \begin_layout Description
15281 \begin_inset Flex CharStyle:Code
15284 \begin_layout Plain Layout
15290 The front part of the resize command.
15293 \begin_layout Description
15294 \begin_inset Flex CharStyle:Code
15297 \begin_layout Plain Layout
15303 The back part of the resize command.
15306 \begin_layout Description
15307 \begin_inset Flex CharStyle:Code
15310 \begin_layout Plain Layout
15316 The front part of the rotation command.
15319 \begin_layout Description
15320 \begin_inset Flex CharStyle:Code
15323 \begin_layout Plain Layout
15329 The back part of the rotation command.
15332 \begin_layout Standard
15333 The value string of the
15334 \begin_inset Flex CharStyle:Code
15337 \begin_layout Plain Layout
15343 command supports additionally the following substitutions if they are enabled
15345 \begin_inset Flex CharStyle:Code
15348 \begin_layout Plain Layout
15355 \begin_inset Flex CharStyle:Code
15358 \begin_layout Plain Layout
15367 \begin_layout Description
15368 \begin_inset Flex CharStyle:Code
15371 \begin_layout Plain Layout
15380 \begin_layout Description
15381 \begin_inset Flex CharStyle:Code
15384 \begin_layout Plain Layout
15393 \begin_layout Description
15394 \begin_inset Flex CharStyle:Code
15397 \begin_layout Plain Layout
15406 \begin_layout Description
15407 \begin_inset Flex CharStyle:Code
15410 \begin_layout Plain Layout
15416 The rotation option.
15419 \begin_layout Standard
15420 You may ask why there are so many path macros.
15421 There are mainly two reasons:
15424 \begin_layout Enumerate
15425 Relative and absolute file names should remain relative or absolute, respectivel
15427 Users may have reasons to prefer either form.
15428 Relative names are useful for portable documents that should work on different
15429 machines, for example.
15430 Absolute names may be required by some programs.
15433 \begin_layout Enumerate
15434 LaTeX treats relative file names differently than LyX and other programs
15435 in nested included files.
15436 For LyX, a relative file name is always relative to the document that contains
15438 For LaTeX, it is always relative to the master document.
15439 These two definitions are identical if you have only one document, but
15440 differ if you have a master document that includes part documents.
15441 That means that relative filenames must be transformed when presented to
15443 Fortunately LyX does this automatically for you if you choose the right
15447 \begin_layout Standard
15448 So which path macro should be used in new template definitions? The rule
15452 \begin_layout Itemize
15454 \begin_inset Flex CharStyle:Code
15457 \begin_layout Plain Layout
15463 if an absolute path is required.
15466 \begin_layout Itemize
15468 \begin_inset Flex CharStyle:Code
15471 \begin_layout Plain Layout
15472 $$AbsOrRelPathMaster
15477 if the substituted string is some kind of LaTeX input.
15480 \begin_layout Itemize
15482 \begin_inset Flex CharStyle:Code
15485 \begin_layout Plain Layout
15486 $$AbsOrRelPathParent
15491 in order to preserve the user's choice.
15494 \begin_layout Standard
15495 There are special cases where this rule does not work and e.g.
15496 \begin_inset space ~
15499 relative names are needed, but normally it will work just fine.
15500 One example for such a case is the command
15501 \begin_inset Flex CharStyle:Code
15504 \begin_layout Plain Layout
15505 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15510 in the XFig template above: We can't use the absolute name because the
15512 \begin_inset Flex CharStyle:Code
15515 \begin_layout Plain Layout
15521 files needs the relative name in order to rewrite the file content.
15524 \begin_layout Section
15525 \begin_inset CommandInset label
15527 name "sec:Security-discussion"
15531 Security discussion
15534 \begin_layout Standard
15535 \begin_inset Box Shadowbox
15544 height_special "totalheight"
15547 \begin_layout Plain Layout
15548 WARNING: This section is definitely outdated.
15556 \begin_layout Standard
15557 The external material feature interfaces with a lot of external programs
15558 and does so automatically, so we have to consider the security implications
15560 In particular, since you have the option of including your own filenames
15561 and/or parameter strings and those are expanded into a command, it seems
15562 that it would be possible to create a malicious document which executes
15563 arbitrary commands when a user views or prints the document.
15564 This is something we definately want to avoid.
15567 \begin_layout Standard
15568 However, since the external program commands are specified in the template
15569 configuration file only, there are no security issues if LyX is properly
15570 configured with safe templates only.
15571 This is so because the external programs are invoked with the
15572 \begin_inset Flex CharStyle:Code
15575 \begin_layout Plain Layout
15581 -system call rather than the
15582 \begin_inset Flex CharStyle:Code
15585 \begin_layout Plain Layout
15591 system-call, so it's not possible to execute arbitrary commands from the
15592 filename or parameter section via the shell.
15595 \begin_layout Standard
15596 This also implies that you are restricted in what command strings you can
15597 use in the external material templates.
15598 In particular, pipes and redirection are not readily available.
15599 This has to be so if LyX should remain safe.
15600 If you want to use some of the shell features, you should write a safe
15601 script to do this in a controlled manner, and then invoke the script from
15602 the command string.
15604 \begin_inset Flex CharStyle:Code
15607 \begin_layout Plain Layout
15613 directory of the LyX installation, you can find a safe wrapper script
15614 \begin_inset Flex CharStyle:Code
15617 \begin_layout Plain Layout
15618 general_command_wrapper.py
15623 that supports redirection of input and output.
15624 That can serve as an example for how to write safe template scripts.
15625 For a more advanced example that uses
15626 \begin_inset Flex CharStyle:Code
15629 \begin_layout Plain Layout
15635 and friends, take a look at the
15636 \begin_inset Flex CharStyle:Code
15639 \begin_layout Plain Layout
15648 \begin_layout Standard
15649 It is possible to design a template that interacts directly with the shell,
15650 but since this would allow a malicious user to execute arbitrary commands
15651 by writing clever filenames and/or parameters, we generally recommend that
15652 you only use safe scripts that work with the
15653 \begin_inset Flex CharStyle:Code
15656 \begin_layout Plain Layout
15662 system call in a controlled manner.
15663 Of course, for use in a controlled environment, it can be tempting to just
15664 fall back to use ordinary shell scripts.
15665 If you do so, be aware that you
15669 provide an easily exploitable security hole in your system.
15670 Of course it stands to reason that such unsafe templates will never be
15671 included in the standard LyX distribution, although we do encourage people
15672 to submit new templates in the open source tradition.
15673 But LyX as shipped from the official distribution channels will never have
15677 \begin_layout Standard
15678 Including external material provides a lot of power, and you have to be
15679 careful not to introduce security hazards with this power.
15680 A subtle error in a single line in an innocent looking script can open
15681 the door to huge security problems.
15682 So if you do not fully understand the issues, we recommend that you consult
15683 a knowledgable security professional or the LyX development team if you
15684 have any questions about whether a given template is safe or not.
15685 And do this before you use it in an uncontrolled environment.