1 #LyX 1.6.0svn created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that the User's Guide prints
10 % out as advertised. If you mess with this preamble,
11 % parts of the User's Guide may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
49 InsetLayout CharStyle:MenuItem
58 \newcommand*{\menuitem}[1]{{\sffamily #1}}
66 \font_typewriter default
67 \font_default_family default
77 \pdf_title "LyX Configuration Manual"
78 \pdf_author "LyX Team"
79 \pdf_subject "LyX-documentation Customization"
80 \pdf_keywords "LyX, documentation, customization"
82 \pdf_bookmarksnumbered true
83 \pdf_bookmarksopen true
84 \pdf_bookmarksopenlevel 1
89 \pdf_pagebackref false
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 is to be given in a form suitable for inclusion in a LaTeX's
1886 command and 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
6000 \begin_layout Standard
6001 Similar to layout files, and new with LyX 1.6, are layout
6006 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6007 some modules---such as the Endnotes module---provide support for just such
6009 In a sense, layout modules are similar to included files---files like
6010 \begin_inset Flex CharStyle:Code
6013 \begin_layout Plain Layout
6019 ---in that modules are not specific to a given document layout but may be
6020 used with many different layouts.
6021 The difference is that using a layout module does not require editing the
6023 Rather, modules are selected in the
6024 \begin_inset Flex CharStyle:MenuItem
6027 \begin_layout Plain Layout
6028 Document\SpecialChar \menuseparator
6037 \begin_layout Standard
6038 Building modules is the easiest way to get started with layout editing,
6039 since it can be as simple as adding a single new paragraph or flex inset.
6040 But modules may, in principle, contain anything a layout file can contain.
6043 \begin_layout Standard
6044 A module must begin with a line like the following:
6047 \begin_layout LyX-Code
6050 DeclareLyXModule[endnotes.sty]{Endnotes}
6053 \begin_layout Standard
6054 The argument in square brackets is optional: It declares any LaTeX packages
6055 on which the module depends.
6056 The mandatory argument, in curly brackets, is the name of the module, as
6058 \begin_inset Flex CharStyle:MenuItem
6061 \begin_layout Plain Layout
6062 Document\SpecialChar \menuseparator
6072 \begin_layout Standard
6073 The module declaration should then be followed by lines like the following:
6076 \begin_layout LyX-Code
6080 \begin_layout LyX-Code
6081 #Adds an endnote command, in addition to footnotes.
6085 \begin_layout LyX-Code
6086 #You will need to add
6088 theendnotes in ERT where you
6091 \begin_layout LyX-Code
6092 #want the endnotes to appear.
6096 \begin_layout LyX-Code
6100 \begin_layout LyX-Code
6101 #Requires: somemodule | othermodule
6104 \begin_layout LyX-Code
6105 #Excludes: badmodule
6108 \begin_layout Standard
6109 The description is used in
6110 \begin_inset Flex CharStyle:MenuItem
6113 \begin_layout Plain Layout
6114 Document\SpecialChar \menuseparator
6120 to provide the user with information about what the module does.
6122 \begin_inset Flex CharStyle:Code
6125 \begin_layout Plain Layout
6131 line is used to identify other modules with which this one must be used;
6133 \begin_inset Flex CharStyle:Code
6136 \begin_layout Plain Layout
6142 line is used to identify modules with which this one may not be used.
6143 Both are optional, and, as shown, multiple modules should be separated
6144 with the pipe symbol: |.
6145 Note that the required modules are treated disjunctively:
6149 of the required modules must be used.
6154 excluded module may be used.
6155 Note that modules are identified here by their
6159 without the .module extension.
6161 \begin_inset Flex CharStyle:Code
6164 \begin_layout Plain Layout
6171 \begin_inset Flex CharStyle:Code
6174 \begin_layout Plain Layout
6183 \begin_layout Standard
6184 After creating a new module, you will need to reconfigure and then restart
6185 LyX for the module to appear in the menu.
6186 However, changes you make to the module will be seen immediately, if you
6188 \begin_inset Flex CharStyle:MenuItem
6191 \begin_layout Plain Layout
6192 Document\SpecialChar \menuseparator
6198 , highlight something, and then hit
6199 \begin_inset Quotes eld
6203 \begin_inset Quotes erd
6209 It is strongly recommended that you save your work before doing so
6214 it is strongly recommended that you not attempt to edit modules while simultaneo
6215 usly working on documents
6218 Though of course the developers strive to keep LyX stable in such situations,
6219 syntax errors and the like in your module file could cause strange behavior.
6222 \begin_layout Subsection
6223 Supporting new document classes
6226 \begin_layout Standard
6227 There are two situations you are likely to encounter when wanting to support
6228 a new LaTeX document class, involving LaTeX2e class (
6229 \begin_inset Flex CharStyle:Code
6232 \begin_layout Plain Layout
6239 \begin_inset Flex CharStyle:Code
6242 \begin_layout Plain Layout
6249 Supporting a style file is usually fairly easy.
6250 Supporting a new document class is a bit harder.
6253 \begin_layout Subsection
6255 \begin_inset Flex CharStyle:MenuItem
6258 \begin_layout Plain Layout
6267 \begin_layout Standard
6268 If your new document class is provided as a style file that is used in conjuncti
6269 on with an existing, supported document class---for the sake of the example,
6270 we'll assume that the style file is called
6271 \begin_inset Flex CharStyle:MenuItem
6274 \begin_layout Plain Layout
6280 and it is meant to be used with
6281 \begin_inset Flex CharStyle:MenuItem
6284 \begin_layout Plain Layout
6290 , which is a standard class---start by copying the existing class's layout
6291 file into your local directory:
6294 \begin_layout LyX-Code
6295 cp report.layout ~/.lyx/layouts/myclass.layout
6298 \begin_layout Standard
6300 \begin_inset Flex CharStyle:Code
6303 \begin_layout Plain Layout
6309 and change the line:
6312 \begin_layout LyX-Code
6315 DeclareLaTeXClass{report}
6318 \begin_layout Standard
6322 \begin_layout LyX-Code
6325 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6328 \begin_layout Standard
6332 \begin_layout LyX-Code
6334 \begin_inset Newline newline
6340 \begin_inset Newline newline
6346 \begin_layout Standard
6347 near the top of the file.
6350 \begin_layout Standard
6351 Start LyX and select
6352 \begin_inset Flex CharStyle:MenuItem
6355 \begin_layout Plain Layout
6360 ools\SpecialChar \menuseparator
6371 Then restart LyX and try creating a new document.
6373 \begin_inset Flex CharStyle:MenuItem
6376 \begin_layout Plain Layout
6382 " as a document class option in the
6383 \begin_inset Flex CharStyle:MenuItem
6386 \begin_layout Plain Layout
6391 ocument\SpecialChar \menuseparator
6402 It is likely that some of the sectioning commands and such in your new
6403 class will work differently from how they worked in the base class---
6404 \begin_inset Flex CharStyle:Code
6407 \begin_layout Plain Layout
6413 in this example---so you can fiddle around with the settings for the different
6414 sections if you wish.
6417 \begin_layout Subsection
6419 \begin_inset Flex CharStyle:MenuItem
6422 \begin_layout Plain Layout
6431 \begin_layout Standard
6432 There are two possibilities here.
6433 One is that the class file is itself based upon an existing document class.
6434 For example, many thesis classes are based upon
6435 \begin_inset Flex CharStyle:MenuItem
6438 \begin_layout Plain Layout
6445 To see whether yours is, look for a line like
6448 \begin_layout LyX-Code
6454 \begin_layout Standard
6456 If so, then you may proceed largely as in the previous section, though
6457 the DeclareLaTeXClass line will be different.
6458 If your new class is thesis, and it is based upon book, then the line should
6463 \begin_layout Plain Layout
6464 And it will be easiest if you save the file to
6465 \begin_inset Flex CharStyle:Code
6468 \begin_layout Plain Layout
6474 : LyX assumes that the document class has the same name as the layout file.
6483 \begin_layout LyX-Code
6486 DeclareLaTeXClass[thesis,book]{thesis}
6489 \begin_layout Standard
6490 If, on the other hand, the new class is not based upon an existing class,
6491 you will probably have to
6492 \begin_inset Quotes eld
6496 \begin_inset Quotes erd
6500 We strongly suggest copying an existing layout file which uses a similar
6501 LaTeX class and then modifying it, if you can do so.
6502 At least use an existing file as a starting point so you can find out what
6503 items you need to worry about.
6504 Again, the specifics are covered below.
6507 \begin_layout Section
6508 Declaring a new text class
6511 \begin_layout Standard
6512 When it's finally time to get your hands dirty and create or edit your own
6513 layout file, the following sections describe what you're up against.
6514 Our advice is to go slowly, save and test often, listen to soothing music,
6515 and enjoy one or two of your favorite adult beverages; more if you are
6516 getting particularly stuck.
6517 It's really not that hard, except that the multitude of options can become
6518 overwhelming if you try to do to much in one sitting.
6519 Go have another adult beverage, just for good measure.
6522 \begin_layout Standard
6526 \begin_layout Standard
6527 Lines in a layout file which begin with a
6528 \begin_inset Flex CharStyle:Code
6531 \begin_layout Plain Layout
6538 There is one exception to this rule: all layouts should begin with lines
6542 \begin_layout LyX-Code
6545 #% Do not delete the line below; configure depends on this
6548 \begin_layout LyX-Code
6553 DeclareLaTeXClass{article}
6556 \begin_layout Standard
6557 The second line is used when you configure LyX.
6558 The layout file is read by the LaTeX script
6559 \begin_inset Flex CharStyle:Code
6562 \begin_layout Plain Layout
6568 , in a special mode where
6569 \begin_inset Flex CharStyle:Code
6572 \begin_layout Plain Layout
6579 The first line is just a LaTeX comment, and the second one contains the
6580 declaration of the text class.
6581 If these lines appear in a file named
6582 \begin_inset Flex CharStyle:Code
6585 \begin_layout Plain Layout
6591 , then they define a text class of name
6592 \begin_inset Flex CharStyle:Code
6595 \begin_layout Plain Layout
6601 (the name of the layout file) which uses the LaTeX document class
6602 \begin_inset Flex CharStyle:Code
6605 \begin_layout Plain Layout
6611 (the default is to use the same name as the layout).
6613 \begin_inset Quotes eld
6617 \begin_inset Quotes erd
6620 that appears above is used as a description of the text class in the
6621 \begin_inset Flex CharStyle:MenuItem
6624 \begin_layout Plain Layout
6629 ocument\SpecialChar \menuseparator
6642 \begin_layout Standard
6643 Let's assume that you wrote your own text class that uses the
6644 \begin_inset Flex CharStyle:Code
6647 \begin_layout Plain Layout
6653 document class, but where you changed the appearance of the section headings.
6654 If you put it in a file
6655 \begin_inset Flex CharStyle:Code
6658 \begin_layout Plain Layout
6664 , the header of this file should be:
6667 \begin_layout LyX-Code
6670 #% Do not delete the line below; configure depends on this
6673 \begin_layout LyX-Code
6678 DeclareLaTeXClass[article]{article (with my own headings)}
6681 \begin_layout Standard
6682 This declares a text class
6683 \begin_inset Flex CharStyle:Code
6686 \begin_layout Plain Layout
6692 , associated with the LaTeX document class
6693 \begin_inset Flex CharStyle:Code
6696 \begin_layout Plain Layout
6703 \begin_inset Quotes eld
6706 article (with my own headings)
6707 \begin_inset Quotes erd
6711 If your text class depends on several packages, you can declare it as:
6714 \begin_layout LyX-Code
6717 #% Do not delete the line below; configure depends on this
6720 \begin_layout LyX-Code
6725 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6728 \begin_layout Standard
6729 This indicates that your text class uses the foo.sty package.
6730 Finally, it is also possible to declare classes for DocBook code.
6731 Typical declarations will look like
6734 \begin_layout LyX-Code
6737 #% Do not delete the line below; configure depends on this
6740 \begin_layout LyX-Code
6745 DeclareDocBookClass[article]{SGML (DocBook article)}
6748 \begin_layout Standard
6749 Note that these declarations can also be given an optional parameter declaring
6750 the name of the document class (but not a list).
6753 \begin_layout Standard
6754 So, to be as explicit as possible, the form of the layout declaration is:
6757 \begin_layout LyX-Code
6762 DeclareLaTeXClass[class,package.sty]{layout description}
6765 \begin_layout Standard
6766 The class need only be specified if the name of the LaTeX class file and
6767 the name of the layout file are different; if the name of the classfile
6768 is not specified, then LyX will simply assume that it is the same as the
6769 name of the layout file.
6772 \begin_layout Standard
6773 When the text class has been modified to your taste, all you have to do
6774 is to copy it either to
6775 \begin_inset Flex CharStyle:Code
6778 \begin_layout Plain Layout
6785 \begin_inset Flex CharStyle:Code
6788 \begin_layout Plain Layout
6795 \begin_inset Flex CharStyle:MenuItem
6798 \begin_layout Plain Layout
6803 ools\SpecialChar \menuseparator
6813 , exit LyX and restart it.
6814 Then your new text class should be available along with the others.
6817 \begin_layout Standard
6818 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6819 you made to your layout files.
6820 As a result, editing layout files could be very time consuming.
6821 Beginning with 1.6, however, you can force a reload of the layout currently
6822 in use by using the LyX function
6823 \begin_inset Flex CharStyle:MenuItem
6826 \begin_layout Plain Layout
6833 There is no default binding for this function---though, of course, you
6834 can bind it to a key yourself.
6835 If you want to use this function, then, you should simply enter it in the
6841 : This is very much an `advanced feature'.
6846 recommended that you save your work before using this function.
6851 recommended that you not attempt to edit your layout while simultaneously
6852 working on a document that you care about.
6853 Use a test document.
6854 Syntax errors and the like in your layout file could cause peculiar behavior.
6855 In particular, such errors could cause LyX to regard the current layout
6856 as invalid and to attempt to switch to some other layout.
6857 The LyX team strives to keep LyX stable in such situations, but safe is
6861 \begin_layout Subsection
6865 \begin_layout Standard
6866 The first non-comment line must contain the file format number:
6869 \begin_layout Description
6870 \begin_inset Flex CharStyle:Code
6873 \begin_layout Plain Layout
6880 \begin_inset Flex CharStyle:Code
6883 \begin_layout Plain Layout
6889 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6890 don't have an explicit file format).
6891 The file format that is documented here is format 8.
6894 \begin_layout Subsection
6895 General text class parameters
6898 \begin_layout Standard
6899 These are the general parameters which describe the form of the entire document:
6902 \begin_layout Description
6903 \begin_inset Flex CharStyle:Code
6906 \begin_layout Plain Layout
6912 Adds information to the document preamble.
6914 \begin_inset Quotes eld
6918 \begin_inset Flex CharStyle:Code
6921 \begin_layout Plain Layout
6928 \begin_inset Quotes erd
6934 \begin_layout Description
6935 \begin_inset Flex CharStyle:Code
6938 \begin_layout Plain Layout
6944 Describes various global options supported by the document class.
6946 \begin_inset space ~
6950 \begin_inset CommandInset ref
6952 reference "sec:classoptions"
6958 \begin_inset Quotes eld
6962 \begin_inset Flex CharStyle:Code
6965 \begin_layout Plain Layout
6972 \begin_inset Quotes erd
6978 \begin_layout Description
6979 \begin_inset Flex CharStyle:Code
6982 \begin_layout Plain Layout
6989 \begin_inset Flex CharStyle:Code
6992 \begin_layout Plain Layout
7001 \begin_inset Flex CharStyle:Code
7004 \begin_layout Plain Layout
7010 ] Whether the class should default to having one or two columns.
7011 Can be changed in the
7012 \begin_inset Flex CharStyle:MenuItem
7015 \begin_layout Plain Layout
7020 ocument\SpecialChar \menuseparator
7033 \begin_layout Description
7034 \begin_inset Flex CharStyle:Code
7037 \begin_layout Plain Layout
7043 This sequence defines a new counter.
7045 \begin_inset space ~
7049 \begin_inset CommandInset ref
7051 reference "sec:counter"
7057 \begin_inset Quotes eld
7061 \begin_inset Flex CharStyle:Code
7064 \begin_layout Plain Layout
7071 \begin_inset Quotes erd
7077 \begin_layout Description
7078 \begin_inset Flex CharStyle:Code
7081 \begin_layout Plain Layout
7087 Sets the default font used to display the document.
7089 \begin_inset space ~
7093 \begin_inset CommandInset ref
7095 reference "sec:fonts"
7099 for how to declare fonts.
7101 \begin_inset Quotes eld
7105 \begin_inset Flex CharStyle:Code
7108 \begin_layout Plain Layout
7115 \begin_inset Quotes erd
7121 \begin_layout Description
7122 \begin_inset Flex CharStyle:Code
7125 \begin_layout Plain Layout
7132 \begin_inset Flex CharStyle:Code
7135 \begin_layout Plain Layout
7141 ] This is the style that will be assigned to new paragraphs, usually
7142 \begin_inset Flex CharStyle:MenuItem
7145 \begin_layout Plain Layout
7152 This will default to the first defined style if not given, but you are
7153 highly encouraged to use this directive.
7156 \begin_layout Description
7157 \begin_inset Flex CharStyle:Code
7160 \begin_layout Plain Layout
7166 Defines a new float.
7168 \begin_inset space ~
7172 \begin_inset CommandInset ref
7174 reference "sec:floats"
7180 \begin_inset Quotes eld
7184 \begin_inset Flex CharStyle:Code
7187 \begin_layout Plain Layout
7194 \begin_inset Quotes erd
7200 \begin_layout Description
7201 \begin_inset Flex CharStyle:Code
7204 \begin_layout Plain Layout
7210 As its name implies, this command allows you to include another layout
7211 definition file within yours to avoid duplicating commands.
7212 Common examples are the standard layout files, for example,
7213 \begin_inset Flex CharStyle:Code
7216 \begin_layout Plain Layout
7222 , which contains most of the basic layouts.
7225 \begin_layout Description
7226 \begin_inset Flex CharStyle:Code
7229 \begin_layout Plain Layout
7235 This section (re-)defines the layout of an inset.
7236 It can be applied to an existing inset of to a new, user-defined inset,
7237 e.g., a new character style.
7239 \begin_inset space ~
7243 \begin_inset CommandInset ref
7245 reference "sec:charstyle"
7249 for more information.
7251 \begin_inset Quotes eld
7255 \begin_inset Flex CharStyle:Code
7258 \begin_layout Plain Layout
7265 \begin_inset Quotes erd
7271 \begin_layout Description
7272 \begin_inset Flex CharStyle:Code
7275 \begin_layout Plain Layout
7281 A string that indicates the width of the left margin on the screen, for
7283 \begin_inset Quotes eld
7287 \begin_inset Quotes erd
7293 \begin_layout Description
7294 \begin_inset Flex CharStyle:Code
7297 \begin_layout Plain Layout
7303 This command deletes an existing float.
7304 This is particularly useful when you want to suppress a float that has
7305 be defined in an input file.
7308 \begin_layout Description
7309 \begin_inset Flex CharStyle:Code
7312 \begin_layout Plain Layout
7318 This command deletes an existing style.
7319 This is particularly useful when you want to suppress a style that has
7320 be defined in an input file.
7323 \begin_layout Description
7324 \begin_inset Flex CharStyle:Code
7327 \begin_layout Plain Layout
7333 A string indicating what sort of output documents using this class will
7335 At present, the options are: `docbook', `latex', `linuxdoc', and `literate'.
7338 \begin_layout Description
7339 \begin_inset Flex CharStyle:Code
7342 \begin_layout Plain Layout
7353 \begin_inset Flex CharStyle:Code
7356 \begin_layout Plain Layout
7367 \begin_inset Flex CharStyle:Code
7370 \begin_layout Plain Layout
7377 \begin_inset Flex CharStyle:Code
7380 \begin_layout Plain Layout
7386 ] The class default pagestyle.
7387 Can be changed in the
7388 \begin_inset Flex CharStyle:MenuItem
7391 \begin_layout Plain Layout
7396 ocument\SpecialChar \menuseparator
7409 \begin_layout Description
7410 \begin_inset Flex CharStyle:Code
7413 \begin_layout Plain Layout
7419 Sets the preamble for the LaTeX document.
7420 Note that this will completely override any prior
7421 \begin_inset Flex CharStyle:Code
7424 \begin_layout Plain Layout
7431 \begin_inset Flex CharStyle:Code
7434 \begin_layout Plain Layout
7442 \begin_inset Quotes eld
7446 \begin_inset Flex CharStyle:Code
7449 \begin_layout Plain Layout
7456 \begin_inset Quotes erd
7462 \begin_layout Description
7463 \begin_inset Flex CharStyle:Code
7466 \begin_layout Plain Layout
7473 \begin_inset Flex CharStyle:Code
7476 \begin_layout Plain Layout
7483 \begin_inset Flex CharStyle:Code
7486 \begin_layout Plain Layout
7495 \begin_inset Flex CharStyle:Code
7498 \begin_layout Plain Layout
7504 ] Whether the class already provides the feature
7505 \begin_inset Flex CharStyle:Code
7508 \begin_layout Plain Layout
7515 A feature is in general the name of a package (
7516 \begin_inset Flex CharStyle:Code
7519 \begin_layout Plain Layout
7526 \begin_inset Flex CharStyle:Code
7529 \begin_layout Plain Layout
7535 , \SpecialChar \ldots{}
7537 \begin_inset Flex CharStyle:Code
7540 \begin_layout Plain Layout
7547 \begin_inset Flex CharStyle:Code
7550 \begin_layout Plain Layout
7556 ,\SpecialChar \ldots{}
7557 ); the complete list of supported features is unfortunately not documented
7558 outside the LyX source code---but see
7559 \begin_inset Flex CharStyle:Code
7562 \begin_layout Plain Layout
7568 if you're interested.
7570 \begin_inset Flex CharStyle:MenuItem
7573 \begin_layout Plain Layout
7578 elp\SpecialChar \menuseparator
7588 also gives an overview of the supported packages.
7591 \begin_layout Description
7592 \begin_inset Flex CharStyle:Code
7595 \begin_layout Plain Layout
7602 \begin_inset Flex CharStyle:Code
7605 \begin_layout Plain Layout
7611 ] Whether the class requires the feature
7612 \begin_inset Flex CharStyle:Code
7615 \begin_layout Plain Layout
7622 Multiple features must be separated by commas.
7623 Note that you can only request supported features.
7626 \begin_layout Description
7627 \begin_inset Flex CharStyle:Code
7630 \begin_layout Plain Layout
7636 A string that indicates the width of the right margin on the screen, for
7638 \begin_inset Quotes eld
7642 \begin_inset Quotes erd
7648 \begin_layout Description
7649 \begin_inset Flex CharStyle:Code
7652 \begin_layout Plain Layout
7658 Sets which divisions get numbered.
7660 \begin_inset Flex CharStyle:Code
7663 \begin_layout Plain Layout
7672 \begin_layout Description
7673 \begin_inset Flex CharStyle:Code
7676 \begin_layout Plain Layout
7685 \begin_inset Flex CharStyle:Code
7688 \begin_layout Plain Layout
7699 \begin_inset Flex CharStyle:Code
7702 \begin_layout Plain Layout
7708 ] Whether the class-default should be printing on one or both sides of the
7710 Can be changed in the
7711 \begin_inset Flex CharStyle:MenuItem
7714 \begin_layout Plain Layout
7719 ocument\SpecialChar \menuseparator
7732 \begin_layout Description
7733 \begin_inset Flex CharStyle:Code
7736 \begin_layout Plain Layout
7742 This sequence defines a new paragraph style.
7743 If the style already exists, it will redefine some of its parameters instead.
7745 \begin_inset space ~
7749 \begin_inset CommandInset ref
7751 reference "sec:style"
7757 \begin_inset Quotes eld
7761 \begin_inset Flex CharStyle:Code
7764 \begin_layout Plain Layout
7771 \begin_inset Quotes erd
7777 \begin_layout Description
7778 \begin_inset Flex CharStyle:Code
7781 \begin_layout Plain Layout
7788 \begin_inset Flex CharStyle:Code
7791 \begin_layout Plain Layout
7797 ] The name of the command or environment to be used with
7798 \begin_inset Flex CharStyle:Code
7801 \begin_layout Plain Layout
7810 \begin_layout Description
7811 \begin_inset Flex CharStyle:Code
7814 \begin_layout Plain Layout
7821 \begin_inset Flex CharStyle:Code
7824 \begin_layout Plain Layout
7833 \begin_inset Flex CharStyle:Code
7836 \begin_layout Plain Layout
7842 ] Indicates what kind of markup is used to define the title of a document.
7844 \begin_inset Flex CharStyle:Code
7847 \begin_layout Plain Layout
7853 means that the macro with name
7854 \begin_inset Flex CharStyle:Code
7857 \begin_layout Plain Layout
7863 will be inserted after the last layout which has
7864 \begin_inset Quotes eld
7868 \begin_inset Flex CharStyle:Code
7871 \begin_layout Plain Layout
7878 \begin_inset Quotes erd
7883 \begin_inset Flex CharStyle:Code
7886 \begin_layout Plain Layout
7892 corresponds to the case where the block of paragraphs which have
7893 \begin_inset Quotes eld
7897 \begin_inset Flex CharStyle:Code
7900 \begin_layout Plain Layout
7907 \begin_inset Quotes erd
7910 should be enclosed into the
7911 \begin_inset Flex CharStyle:Code
7914 \begin_layout Plain Layout
7923 \begin_layout Description
7924 \begin_inset Flex CharStyle:Code
7927 \begin_layout Plain Layout
7933 Sets which divisions are included in the table of contents.
7935 \begin_inset Flex CharStyle:Code
7938 \begin_layout Plain Layout
7947 \begin_layout Description
7948 \begin_inset Flex CharStyle:Code
7951 \begin_layout Plain Layout
7958 \begin_inset Flex CharStyle:Code
7961 \begin_layout Plain Layout
7967 Specifies a module to be included by default with this document class.
7968 The user can still remove the module, but it will be active at the outset.
7969 (This applies only when new files are created, or when this class is chosen
7970 for an existing document.)
7973 \begin_layout Subsection
7974 \begin_inset Flex CharStyle:Code
7977 \begin_layout Plain Layout
7986 \begin_layout Standard
7987 \begin_inset CommandInset label
7989 name "sec:classoptions"
7994 \begin_inset Flex CharStyle:Code
7997 \begin_layout Plain Layout
8003 section can contain the following entries:
8006 \begin_layout Description
8007 \begin_inset Flex CharStyle:Code
8010 \begin_layout Plain Layout
8017 \begin_inset Flex CharStyle:Code
8020 \begin_layout Plain Layout
8026 ] The list of available font sizes for the document's main font, separated
8028 \begin_inset Quotes eld
8032 \begin_inset Flex CharStyle:Code
8035 \begin_layout Plain Layout
8042 \begin_inset Quotes erd
8048 \begin_layout Description
8049 \begin_inset Flex CharStyle:Code
8052 \begin_layout Plain Layout
8058 Used to set the DTD line with XML-based output classes.
8060 \begin_inset Quotes eld
8063 -//OASIS//DTD DocBook V4.2//EN
8064 \begin_inset Quotes erd
8070 \begin_layout Description
8071 \begin_inset Flex CharStyle:Code
8074 \begin_layout Plain Layout
8081 \begin_inset Flex CharStyle:Code
8084 \begin_layout Plain Layout
8085 string="empty|plain|headings|fancy"
8090 ] The list of available page styles, separated by
8091 \begin_inset Quotes eld
8095 \begin_inset Flex CharStyle:Code
8098 \begin_layout Plain Layout
8105 \begin_inset Quotes erd
8111 \begin_layout Description
8112 \begin_inset Flex CharStyle:Code
8115 \begin_layout Plain Layout
8122 \begin_inset Flex CharStyle:Code
8125 \begin_layout Plain Layout
8131 ] Some document class options, separated by a comma, that will be added
8132 to the optional part of the
8133 \begin_inset Flex CharStyle:Code
8136 \begin_layout Plain Layout
8147 \begin_layout Standard
8149 \begin_inset Flex CharStyle:Code
8152 \begin_layout Plain Layout
8158 section must end with
8159 \begin_inset Quotes eld
8163 \begin_inset Flex CharStyle:Code
8166 \begin_layout Plain Layout
8173 \begin_inset Quotes erd
8179 \begin_layout Subsection
8183 \begin_layout Standard
8184 \begin_inset CommandInset label
8190 A paragraph style description looks like this:
8194 \begin_layout Plain Layout
8195 Note that this will either define a new layout or modify an existing one.
8203 \begin_layout LyX-Code
8210 \begin_layout LyX-Code
8214 \begin_layout LyX-Code
8218 \begin_layout Standard
8219 where the following commands are allowed:
8222 \begin_layout Description
8223 \begin_inset Flex CharStyle:Code
8226 \begin_layout Plain Layout
8233 \begin_inset Flex CharStyle:Code
8236 \begin_layout Plain Layout
8241 , left, right, center
8246 ] Paragraph alignment.
8249 \begin_layout Description
8250 \begin_inset Flex CharStyle:Code
8253 \begin_layout Plain Layout
8260 \begin_inset Flex CharStyle:Code
8263 \begin_layout Plain Layout
8268 , left, right, center
8273 ] A comma separated list of permitted alignments.
8274 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8276 For example a right-aligned or centered enumeration isn't possible.)
8279 \begin_layout Description
8280 \begin_inset Flex CharStyle:Code
8283 \begin_layout Plain Layout
8290 \begin_inset Flex CharStyle:Code
8293 \begin_layout Plain Layout
8303 \begin_layout Plain Layout
8304 Note that a `float' here is a real number, such as: 1.5.
8309 The vertical space with which the last of a chain of paragraphs with this
8310 layout is separated from the following paragraph.
8311 If the next paragraph has another layout, the separations are not simply
8312 added, but the maximum is taken.
8315 \begin_layout Description
8316 \begin_inset Flex CharStyle:Code
8319 \begin_layout Plain Layout
8326 \begin_inset Flex CharStyle:Code
8329 \begin_layout Plain Layout
8335 The category for this style.
8336 This is used to group related styles in the Layout combobox on the toolbar.
8337 Any string can be used, but you may want to use existing categories with
8342 \begin_layout Description
8343 \begin_inset Flex CharStyle:Code
8346 \begin_layout Plain Layout
8352 Depth of XML command.
8353 Used only with XML-type formats.
8356 \begin_layout Description
8357 \begin_inset Flex CharStyle:Code
8360 \begin_layout Plain Layout
8367 \begin_inset CommandInset label
8369 name "des:CopyStyle"
8374 \begin_inset Flex CharStyle:Code
8377 \begin_layout Plain Layout
8383 Copies all the features of an existing style into the current one.
8387 \begin_layout Description
8388 \begin_inset Flex CharStyle:Code
8391 \begin_layout Plain Layout
8397 The name of a style whose preamble should be output
8402 This allows to ensure some ordering of the preamble snippets when macros
8403 definitions depend on one another.
8407 \begin_layout Plain Layout
8408 Note that, besides that functionality, there is no way to ensure any ordering
8410 The ordering that you see in a given version of LyX may change without
8411 warning in later versions.
8419 \begin_layout Description
8420 \begin_inset Flex CharStyle:Code
8423 \begin_layout Plain Layout
8430 \begin_inset Flex CharStyle:Code
8433 \begin_layout Plain Layout
8438 , Box, Filled_Box, Static
8443 ] The type of label that stands at the end of the paragraph (or sequence
8445 \begin_inset Flex CharStyle:Code
8448 \begin_layout Plain Layout
8455 \begin_inset Flex CharStyle:Code
8458 \begin_layout Plain Layout
8465 \begin_inset Flex CharStyle:Code
8468 \begin_layout Plain Layout
8475 \begin_inset Flex CharStyle:Code
8478 \begin_layout Plain Layout
8486 \begin_inset Flex CharStyle:Code
8489 \begin_layout Plain Layout
8496 \begin_inset Quotes eld
8500 \begin_inset Quotes erd
8504 \begin_inset Flex CharStyle:Code
8507 \begin_layout Plain Layout
8514 \begin_inset Flex CharStyle:Code
8517 \begin_layout Plain Layout
8518 \begin_inset space ~
8527 \begin_inset space ~
8530 black) square suitable for end of proof markers,
8531 \begin_inset Flex CharStyle:Code
8534 \begin_layout Plain Layout
8540 is an explicit text string.
8543 \begin_layout Description
8544 \begin_inset Flex CharStyle:Code
8547 \begin_layout Plain Layout
8554 \begin_inset Flex CharStyle:Code
8557 \begin_layout Plain Layout
8563 ] The string used for a label with a
8564 \begin_inset Flex CharStyle:Code
8567 \begin_layout Plain Layout
8574 \begin_inset Flex CharStyle:Code
8577 \begin_layout Plain Layout
8587 \begin_layout Description
8588 \begin_inset Flex CharStyle:Code
8591 \begin_layout Plain Layout
8598 \begin_inset Flex CharStyle:Code
8601 \begin_layout Plain Layout
8612 \begin_inset Flex CharStyle:Code
8615 \begin_layout Plain Layout
8624 \begin_layout Description
8625 \begin_inset Flex CharStyle:Code
8628 \begin_layout Plain Layout
8635 \begin_inset Flex CharStyle:Code
8638 \begin_layout Plain Layout
8648 ] With this parameter the
8649 \begin_inset Flex CharStyle:MenuItem
8652 \begin_layout Plain Layout
8659 \begin_inset Quotes eld
8662 Vertical space above
8663 \begin_inset Quotes erd
8667 \begin_inset Flex CharStyle:MenuItem
8670 \begin_layout Plain Layout
8675 dit\SpecialChar \menuseparator
8681 \begin_inset space ~
8689 dialog can be set when initializing a paragraph with this style.
8693 \begin_layout Plain Layout
8696 Note from Jean-Marc:
8698 I'm not sure that this setting has much use, and it should probably be
8699 removed in later versions.
8707 \begin_layout Description
8708 \begin_inset Flex CharStyle:Code
8711 \begin_layout Plain Layout
8717 The font used for both the text body
8723 \begin_inset space ~
8727 \begin_inset CommandInset ref
8729 reference "sec:fonts"
8734 Note that defining this font automatically defines the
8735 \begin_inset Flex CharStyle:Code
8738 \begin_layout Plain Layout
8745 So you should define this one first if you also want to define
8746 \begin_inset Flex CharStyle:Code
8749 \begin_layout Plain Layout
8758 \begin_layout Description
8759 \begin_inset Flex CharStyle:Code
8762 \begin_layout Plain Layout
8769 \begin_inset CommandInset label
8771 name "des:FreeSpacing"
8778 \begin_inset Flex CharStyle:Code
8781 \begin_layout Plain Layout
8792 \begin_inset Flex CharStyle:Code
8795 \begin_layout Plain Layout
8801 ] Usually LyX doesn't allow you to insert more than one space between words,
8802 since a space is considered as the separation between two words, not a
8803 character or symbol of its own.
8804 This is a very fine thing but sometimes annoying, for example, when typing
8805 program code or plain LaTeX code.
8807 \begin_inset Flex CharStyle:Code
8810 \begin_layout Plain Layout
8817 Note that LyX will create protected blanks for the additional blanks when
8818 in another mode than LaTeX-mode.
8821 \begin_layout Description
8822 \begin_inset Flex CharStyle:Code
8825 \begin_layout Plain Layout
8831 [[FIXME]] (Used only with XML-type formats.)
8834 \begin_layout Description
8835 \begin_inset Flex CharStyle:Code
8838 \begin_layout Plain Layout
8845 \begin_inset Flex CharStyle:Code
8848 \begin_layout Plain Layout
8854 If 1, marks the layout as being part of a title block (see also the
8855 \begin_inset Flex CharStyle:Code
8858 \begin_layout Plain Layout
8865 \begin_inset Flex CharStyle:Code
8868 \begin_layout Plain Layout
8877 \begin_layout Description
8878 \begin_inset Flex CharStyle:Code
8881 \begin_layout Plain Layout
8888 \begin_inset Flex CharStyle:Code
8891 \begin_layout Plain Layout
8897 ] This provides extra space between paragraphs that have the same layout.
8898 If you put other layouts into an environment, each is separated with the
8900 \begin_inset Flex CharStyle:Code
8903 \begin_layout Plain Layout
8910 But the whole items of the environment are additionally separated with
8912 \begin_inset Flex CharStyle:Code
8915 \begin_layout Plain Layout
8927 \begin_layout Description
8928 \begin_inset Flex CharStyle:Code
8931 \begin_layout Plain Layout
8937 [[FIXME]] (Used only with XML-type formats.)
8940 \begin_layout Description
8941 \begin_inset Flex CharStyle:Code
8944 \begin_layout Plain Layout
8951 \begin_inset CommandInset label
8953 name "des:KeepEmpty"
8960 \begin_inset Flex CharStyle:Code
8963 \begin_layout Plain Layout
8974 \begin_inset Flex CharStyle:Code
8977 \begin_layout Plain Layout
8983 ] Usually LyX does not allow you to leave a paragraph empty, since it would
8984 lead to empty LaTeX output.
8985 There are some cases where this could be desirable however: in a letter
8986 template, the required fields can be provided as empty fields, so that
8987 people do not forget them; in some special classes, a layout can be used
8988 as some kind of break, which does not contain actual text.
8991 \begin_layout Description
8992 \begin_inset Flex CharStyle:Code
8995 \begin_layout Plain Layout
9001 [float=0] The vertical space between the label and the text body.
9002 Only used for labels that are above the text body (
9003 \begin_inset Flex CharStyle:Code
9006 \begin_layout Plain Layout
9013 \begin_inset Flex CharStyle:Code
9016 \begin_layout Plain Layout
9017 Centered_Top_Environment
9025 \begin_layout Description
9026 \begin_inset Flex CharStyle:Code
9029 \begin_layout Plain Layout
9036 \begin_inset Flex CharStyle:Code
9039 \begin_layout Plain Layout
9046 \begin_inset Newline newline
9049 The name of the counter for automatic numbering (see Section
9050 \begin_inset CommandInset ref
9052 reference "sec:counter"
9057 This must be given if
9058 \begin_inset Flex CharStyle:Code
9061 \begin_layout Plain Layout
9068 \begin_inset Flex CharStyle:Code
9071 \begin_layout Plain Layout
9080 \begin_layout Description
9081 \begin_inset Flex CharStyle:Code
9084 \begin_layout Plain Layout
9090 The font used for the label.
9092 \begin_inset space ~
9096 \begin_inset CommandInset ref
9098 reference "sec:fonts"
9105 \begin_layout Description
9106 \begin_inset Flex CharStyle:Code
9109 \begin_layout Plain Layout
9115 Text that indicates how far a label should be indented.
9118 \begin_layout Description
9119 \begin_inset Flex CharStyle:Code
9122 \begin_layout Plain Layout
9129 \begin_inset Flex CharStyle:Code
9132 \begin_layout Plain Layout
9138 ] The horizontal space between the label and the text body.
9139 Only used for labels that are not above the text body.
9142 \begin_layout Description
9143 \begin_inset Flex CharStyle:Code
9146 \begin_layout Plain Layout
9153 \begin_inset Flex CharStyle:Code
9156 \begin_layout Plain Layout
9162 ] The string used for a label with a
9163 \begin_inset Flex CharStyle:Code
9166 \begin_layout Plain Layout
9174 \begin_inset Flex CharStyle:Code
9177 \begin_layout Plain Layout
9183 is set, this string can be contain the special formatting commands described
9185 \begin_inset CommandInset ref
9187 reference "sec:counter"
9195 \begin_layout Plain Layout
9196 For the sake of backwards compatibility, the string
9197 \begin_inset Flex CharStyle:Code
9200 \begin_layout Plain Layout
9210 will be replaced by the expanded
9211 \begin_inset Flex CharStyle:Code
9214 \begin_layout Plain Layout
9221 \begin_inset Flex CharStyle:Code
9224 \begin_layout Plain Layout
9233 This feature is now obsolete and should be replaced by the mechanisms of
9235 \begin_inset CommandInset ref
9237 reference "sec:counter"
9249 \begin_layout Description
9250 \begin_inset Flex CharStyle:Code
9253 \begin_layout Plain Layout
9260 \begin_inset Flex CharStyle:Code
9263 \begin_layout Plain Layout
9269 ] This is used inside the appendix instead of
9270 \begin_inset Flex CharStyle:Code
9273 \begin_layout Plain Layout
9281 \begin_inset Flex CharStyle:Code
9284 \begin_layout Plain Layout
9291 \begin_inset Flex CharStyle:Code
9294 \begin_layout Plain Layout
9303 \begin_layout Description
9304 \begin_inset Flex CharStyle:Code
9307 \begin_layout Plain Layout
9313 [FIXME] (Used only with XML-type formats.)
9316 \begin_layout Description
9317 \begin_inset Flex CharStyle:Code
9320 \begin_layout Plain Layout
9327 \begin_inset Flex CharStyle:Code
9330 \begin_layout Plain Layout
9335 , Manual, Static, Top_Environment,
9336 \begin_inset Newline newline
9339 Centered_Top_Environment, Sensitive, Counter
9345 \begin_inset Newline newline
9349 \begin_inset Flex CharStyle:Code
9352 \begin_layout Plain Layout
9358 means the label is the very first word (up to the first real blank).
9362 \begin_layout Plain Layout
9363 Use protected spaces if you want more than one word as the label.
9369 \begin_inset Flex CharStyle:Code
9372 \begin_layout Plain Layout
9378 means it is defined in the layout (see
9379 \begin_inset Flex CharStyle:Code
9382 \begin_layout Plain Layout
9390 \begin_inset Flex CharStyle:Code
9393 \begin_layout Plain Layout
9400 \begin_inset Flex CharStyle:Code
9403 \begin_layout Plain Layout
9404 Centered_Top_Environment
9409 are special cases of
9410 \begin_inset Flex CharStyle:Code
9413 \begin_layout Plain Layout
9420 The label will be printed above the paragraph, but only at the top of an
9421 environment or the top of a chain of paragraphs with this layout.
9422 Usage is for example the
9423 \begin_inset Flex CharStyle:MenuItem
9426 \begin_layout Plain Layout
9433 \begin_inset Flex CharStyle:MenuItem
9436 \begin_layout Plain Layout
9443 This is also the case for
9444 \begin_inset Flex CharStyle:Code
9447 \begin_layout Plain Layout
9453 labels with latex type
9454 \begin_inset Flex CharStyle:Code
9457 \begin_layout Plain Layout
9463 , in order to make layouts for theorems work correctly.
9465 \begin_inset Flex CharStyle:Code
9468 \begin_layout Plain Layout
9474 is a special case for the caption-labels
9475 \begin_inset Quotes eld
9479 \begin_inset Quotes erd
9483 \begin_inset Quotes eld
9487 \begin_inset Quotes erd
9492 \begin_inset Flex CharStyle:Code
9495 \begin_layout Plain Layout
9501 means the (hardcoded) label string depends on the kind of float.
9503 \begin_inset Flex CharStyle:Code
9506 \begin_layout Plain Layout
9512 label type defines automatically numbered labels.
9514 \begin_inset CommandInset ref
9516 reference "sec:counter"
9523 \begin_layout Description
9524 \begin_inset Flex CharStyle:Code
9527 \begin_layout Plain Layout
9533 The name of the corresponding LaTeX stuff.
9534 Either the environment or command name.
9537 \begin_layout Description
9538 \begin_inset Flex CharStyle:Code
9541 \begin_layout Plain Layout
9547 An optional parameter for the corresponding
9548 \begin_inset Flex CharStyle:Code
9551 \begin_layout Plain Layout
9558 This parameter cannot be changed from within LyX.
9561 \begin_layout Description
9562 \begin_inset Flex CharStyle:Code
9565 \begin_layout Plain Layout
9572 \begin_inset CommandInset label
9574 name "des:LatexType"
9579 \begin_inset Flex CharStyle:Code
9582 \begin_layout Plain Layout
9587 , Command, Environment, Item_Environment,
9593 \begin_inset Flex CharStyle:Code
9596 \begin_layout Plain Layout
9602 ] How the layout should be translated into LaTeX.
9604 \begin_inset Flex CharStyle:Code
9607 \begin_layout Plain Layout
9613 means nothing special.
9615 \begin_inset Flex CharStyle:Code
9618 \begin_layout Plain Layout
9625 \begin_inset Flex CharStyle:Code
9628 \begin_layout Plain Layout
9635 {\SpecialChar \ldots{}
9642 \begin_inset Flex CharStyle:Code
9645 \begin_layout Plain Layout
9652 \begin_inset Flex CharStyle:Code
9655 \begin_layout Plain Layout
9662 }\SpecialChar \ldots{}
9676 \begin_inset Flex CharStyle:Code
9679 \begin_layout Plain Layout
9686 \begin_inset Flex CharStyle:Code
9689 \begin_layout Plain Layout
9696 \begin_inset Flex CharStyle:Code
9699 \begin_layout Plain Layout
9707 is generated for each paragraph of this environment.
9709 \begin_inset Flex CharStyle:Code
9712 \begin_layout Plain Layout
9719 \begin_inset Flex CharStyle:Code
9722 \begin_layout Plain Layout
9729 \begin_inset Flex CharStyle:Code
9732 \begin_layout Plain Layout
9738 is passed as an argument to the environment.
9740 \begin_inset Flex CharStyle:Code
9743 \begin_layout Plain Layout
9749 can be defined in the
9750 \begin_inset Flex CharStyle:MenuItem
9753 \begin_layout Plain Layout
9758 ayout\SpecialChar \menuseparator
9770 \begin_inset Flex CharStyle:Code
9773 \begin_layout Plain Layout
9781 is perhaps a bit misleading, since these rules apply to SGML classes, too.
9782 Visit the SGML class files for specific examples.
9785 \begin_layout Standard
9786 Putting the last few things together, the LaTeX output will be either:
9789 \begin_layout LyX-Code
9792 latexname[latexparam]{\SpecialChar \ldots{}
9796 \begin_layout Standard
9800 \begin_layout LyX-Code
9803 begin{latexname}[latexparam] \SpecialChar \ldots{}
9809 \begin_layout Standard
9810 depending upon the LaTex type.
9813 \begin_layout Description
9814 \begin_inset Flex CharStyle:Code
9817 \begin_layout Plain Layout
9824 \begin_inset Flex CharStyle:Code
9827 \begin_layout Plain Layout
9833 ] If you put layouts into environments, the leftmargins are not simply added,
9834 but added with a factor
9835 \begin_inset Formula $\frac{4}{depth+4}$
9839 Note that this parameter is also used when the margin is defined as
9840 \begin_inset Flex CharStyle:Code
9843 \begin_layout Plain Layout
9850 \begin_inset Flex CharStyle:Code
9853 \begin_layout Plain Layout
9860 Then it is added to the manual or dynamic margin.
9862 \begin_inset Newline newline
9865 The argument is passed as a string.
9867 \begin_inset Quotes eld
9871 \begin_inset Flex CharStyle:Code
9874 \begin_layout Plain Layout
9881 \begin_inset Quotes erd
9884 means that the paragraph is indented with the width of
9885 \begin_inset Quotes eld
9889 \begin_inset Flex CharStyle:Code
9892 \begin_layout Plain Layout
9899 \begin_inset Quotes erd
9903 You can get a negative width by prefixing the string with
9904 \begin_inset Quotes eld
9908 \begin_inset Flex CharStyle:Code
9911 \begin_layout Plain Layout
9918 \begin_inset Quotes erd
9922 This way was chosen so that the look is the same with each used screen
9927 \begin_layout Description
9928 \begin_inset Flex CharStyle:Code
9931 \begin_layout Plain Layout
9938 \begin_inset Flex CharStyle:Code
9941 \begin_layout Plain Layout
9946 , Manual, Dynamic, First_Dynamic, Right_Address_Box
9952 \begin_inset Newline newline
9955 The kind of margin that the layout has on the left side.
9957 \begin_inset Flex CharStyle:Code
9960 \begin_layout Plain Layout
9966 just means a fixed margin.
9968 \begin_inset Flex CharStyle:Code
9971 \begin_layout Plain Layout
9977 means that the left margin depends on the string entered in the
9978 \begin_inset Flex CharStyle:MenuItem
9981 \begin_layout Plain Layout
9986 dit\SpecialChar \menuseparator
9992 \begin_inset space ~
10001 This is used to typeset nice lists without tabulators.
10003 \begin_inset Flex CharStyle:Code
10006 \begin_layout Plain Layout
10012 means that the margin depends on the size of the label.
10013 This is used for automatic enumerated headlines.
10014 It is obvious that the headline
10015 \begin_inset Quotes eld
10018 5.4.3.2.1 Very long headline
10019 \begin_inset Quotes erd
10022 must have a wider left margin (as wide as
10023 \begin_inset Quotes eld
10027 \begin_inset Quotes erd
10030 plus the space) than
10031 \begin_inset Quotes eld
10034 3.2 Very long headline
10035 \begin_inset Quotes erd
10039 \begin_inset Quotes eld
10043 \begin_inset Quotes erd
10046 are not able to do this.
10048 \begin_inset Flex CharStyle:Code
10051 \begin_layout Plain Layout
10057 is similar, but only the very first row of the paragraph is dynamic, while
10058 the others are static; this is used, for example, for descriptions.
10060 \begin_inset Flex CharStyle:Code
10063 \begin_layout Plain Layout
10069 means the margin is chosen in a way that the longest row of this paragraph
10070 fits to the right margin.
10071 This is used to typeset an address on the right edge of the page.
10074 \begin_layout Description
10075 \begin_inset Flex CharStyle:Code
10078 \begin_layout Plain Layout
10085 \begin_inset Flex CharStyle:Code
10088 \begin_layout Plain Layout
10097 \begin_inset Flex CharStyle:Code
10100 \begin_layout Plain Layout
10106 ] Whether fragile commands in this layout should be
10107 \begin_inset Flex CharStyle:Code
10110 \begin_layout Plain Layout
10123 whether this command should itself be protected.)
10126 \begin_layout Description
10127 \begin_inset Flex CharStyle:Code
10130 \begin_layout Plain Layout
10137 \begin_inset Flex CharStyle:Code
10140 \begin_layout Plain Layout
10147 \begin_inset Flex CharStyle:Code
10150 \begin_layout Plain Layout
10158 ] Whether newlines are translated into LaTeX newlines (
10159 \begin_inset Flex CharStyle:Code
10162 \begin_layout Plain Layout
10173 The translation can be switched off to allow more comfortable LaTeX editing
10177 \begin_layout Description
10178 \begin_inset Flex CharStyle:Code
10181 \begin_layout Plain Layout
10188 \begin_inset Flex CharStyle:Code
10191 \begin_layout Plain Layout
10198 \begin_inset Flex CharStyle:Code
10201 \begin_layout Plain Layout
10209 ] Whether the following Paragraph is allowed to indent its very first row.
10211 \begin_inset Flex CharStyle:Code
10214 \begin_layout Plain Layout
10220 means that it is not allowed to do so;
10221 \begin_inset Flex CharStyle:Code
10224 \begin_layout Plain Layout
10230 means it could do so if it wants to.
10233 \begin_layout Description
10234 \begin_inset Flex CharStyle:Code
10237 \begin_layout Plain Layout
10243 Name of a layout that has replaced this layout.
10244 This is used to rename a layout, while keeping backward compatibility.
10247 \begin_layout Description
10248 \begin_inset Flex CharStyle:Code
10251 \begin_layout Plain Layout
10258 \begin_inset Flex CharStyle:Code
10261 \begin_layout Plain Layout
10267 ] The number of optional arguments that can be used with this layout.
10268 This is useful for things like section headings, and only makes sense with
10272 \begin_layout Description
10273 \begin_inset Flex CharStyle:Code
10276 \begin_layout Plain Layout
10283 \begin_inset Flex CharStyle:Code
10286 \begin_layout Plain Layout
10292 ] The indent of the very first line of a paragraph.
10294 \begin_inset Flex CharStyle:Code
10297 \begin_layout Plain Layout
10303 will be fixed for a certain layout.
10304 The exception is Standard layout, since the indentation of a Standard layout
10305 paragraph can be prohibited with
10306 \begin_inset Flex CharStyle:Code
10309 \begin_layout Plain Layout
10316 Also, Standard layout paragraphs inside environments use the
10317 \begin_inset Flex CharStyle:Code
10320 \begin_layout Plain Layout
10326 of the environment, not their native one.
10327 For example, Standard paragraphs inside an enumeration are not indented.
10330 \begin_layout Description
10331 \begin_inset Flex CharStyle:Code
10334 \begin_layout Plain Layout
10341 \begin_inset Flex CharStyle:Code
10344 \begin_layout Plain Layout
10350 ] The vertical space between two paragraphs of this layout.
10353 \begin_layout Description
10354 \begin_inset Flex CharStyle:Code
10357 \begin_layout Plain Layout
10364 \begin_inset Flex CharStyle:Code
10367 \begin_layout Plain Layout
10373 ] LyX allows the user to choose either
10374 \begin_inset Quotes eld
10378 \begin_inset Quotes erd
10382 \begin_inset Quotes eld
10386 \begin_inset Quotes erd
10389 to typeset a document.
10391 \begin_inset Quotes eld
10395 \begin_inset Quotes erd
10398 is chosen, this value is completely ignored.
10400 \begin_inset Quotes eld
10404 \begin_inset Quotes erd
10407 is chosen, the parindent of a LaTeXtype
10408 \begin_inset Quotes eld
10412 \begin_inset Quotes erd
10415 layout is ignored and all paragraphs are separated by this parskip argument.
10416 The vertical space is calculated with
10417 \begin_inset Flex CharStyle:Code
10420 \begin_layout Plain Layout
10422 \begin_inset space ~
10431 \begin_inset Flex CharStyle:Code
10434 \begin_layout Plain Layout
10440 is the height of a row with the normal font.
10441 This way, the look stays the same with different screen fonts.
10444 \begin_layout Description
10445 \begin_inset Flex CharStyle:Code
10448 \begin_layout Plain Layout
10455 \begin_inset CommandInset label
10457 name "des:PathThru"
10464 \begin_inset Flex CharStyle:Code
10467 \begin_layout Plain Layout
10478 \begin_inset Flex CharStyle:Code
10481 \begin_layout Plain Layout
10487 ] Whether the contents of this paragraph should be output in raw form, meaning
10488 without special translations that LaTeX would require.
10491 \begin_layout Description
10492 \begin_inset Flex CharStyle:Code
10495 \begin_layout Plain Layout
10502 \begin_inset CommandInset label
10504 name "des:Preamble"
10508 Information to be included in the LaTeX preamable when this style is used.
10509 Used to define macros, load packages, etc., required by this particular
10512 \begin_inset Quotes eld
10516 \begin_inset Flex CharStyle:Code
10519 \begin_layout Plain Layout
10526 \begin_inset Quotes erd
10532 \begin_layout Description
10533 \begin_inset Flex CharStyle:Code
10536 \begin_layout Plain Layout
10543 \begin_inset Flex CharStyle:Code
10546 \begin_layout Plain Layout
10553 \begin_inset CommandInset label
10555 name "des:Requires"
10559 Whether the layout requires the feature
10560 \begin_inset Flex CharStyle:Code
10563 \begin_layout Plain Layout
10570 See the description of
10571 \begin_inset Flex CharStyle:Code
10574 \begin_layout Plain Layout
10581 \begin_inset CommandInset ref
10582 LatexCommand pageref
10583 reference "des:FreeSpacing"
10587 ) for information on `features'.
10591 \begin_layout Description
10592 \begin_inset Flex CharStyle:Code
10595 \begin_layout Plain Layout
10602 \begin_inset Flex CharStyle:Code
10605 \begin_layout Plain Layout
10612 \begin_inset Flex CharStyle:Code
10615 \begin_layout Plain Layout
10624 \begin_layout Description
10625 \begin_inset Flex CharStyle:Code
10628 \begin_layout Plain Layout
10635 \begin_inset Flex CharStyle:Code
10638 \begin_layout Plain Layout
10643 , onehalf, double, other
10652 ] This defines what the default spacing should be in the layout.
10654 \begin_inset Flex CharStyle:Code
10657 \begin_layout Plain Layout
10664 \begin_inset Flex CharStyle:Code
10667 \begin_layout Plain Layout
10674 \begin_inset Flex CharStyle:Code
10677 \begin_layout Plain Layout
10683 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10684 If you specify the argument
10685 \begin_inset Flex CharStyle:Code
10688 \begin_layout Plain Layout
10694 , then you should also provide a numerical argument which will be the actual
10696 Note that, contrary to other parameters,
10697 \begin_inset Flex CharStyle:Code
10700 \begin_layout Plain Layout
10706 implies the generation of specific LaTeX code, using the package
10709 \begin_inset Flex CharStyle:Code
10712 \begin_layout Plain Layout
10721 \begin_layout Description
10722 \begin_inset Flex CharStyle:Code
10725 \begin_layout Plain Layout
10731 The font used for the text body .
10733 \begin_inset CommandInset ref
10735 reference "sec:fonts"
10742 \begin_layout Description
10743 \begin_inset Flex CharStyle:Code
10746 \begin_layout Plain Layout
10754 The level of the style in the table of contents.
10755 This is used for automatic numbering of section headings.
10758 \begin_layout Description
10759 \begin_inset Flex CharStyle:Code
10762 \begin_layout Plain Layout
10769 \begin_inset Flex CharStyle:Code
10772 \begin_layout Plain Layout
10778 ] The vertical space with which the very first of a chain of paragraphs
10779 with this layout is separated from the previous paragraph.
10780 If the previous paragraph has another layout, the separations are not simply
10781 added, but the maximum is taken.
10784 \begin_layout Subsection
10788 \begin_layout Standard
10789 \begin_inset CommandInset label
10795 Since version 1.3.0 of LyX, it is has been both possible and necessary to
10796 define the floats (
10797 \begin_inset Flex CharStyle:MenuItem
10800 \begin_layout Plain Layout
10807 \begin_inset Flex CharStyle:MenuItem
10810 \begin_layout Plain Layout
10816 , \SpecialChar \ldots{}
10817 ) in the text class itself.
10818 Standard floats are included in the file
10819 \begin_inset Flex CharStyle:Code
10822 \begin_layout Plain Layout
10828 , so you may have to do no more than add
10831 \begin_layout LyX-Code
10832 Input stdfloats.inc
10835 \begin_layout Standard
10836 to your layout file.
10837 If you want to implement a text class that proposes some other float types
10838 (like the AGU class bundled with LyX), the information below will hopefully
10842 \begin_layout Description
10843 \begin_inset Flex CharStyle:Code
10846 \begin_layout Plain Layout
10853 \begin_inset Flex CharStyle:Code
10856 \begin_layout Plain Layout
10863 \begin_inset Quotes erd
10867 \begin_inset Quotes erd
10870 ] The file name extension of an auxiliary file for the list of figures (or
10872 LaTeX writes the captions to this file.
10875 \begin_layout Description
10876 \begin_inset Flex CharStyle:Code
10879 \begin_layout Plain Layout
10886 \begin_inset Flex CharStyle:Code
10889 \begin_layout Plain Layout
10896 \begin_inset Quotes erd
10900 \begin_inset Quotes erd
10903 ] The string that will be used in the menus and also for the caption.
10906 \begin_layout Description
10907 \begin_inset Flex CharStyle:Code
10910 \begin_layout Plain Layout
10917 \begin_inset Flex CharStyle:Code
10920 \begin_layout Plain Layout
10929 \begin_inset Flex CharStyle:Code
10932 \begin_layout Plain Layout
10939 \begin_inset Flex CharStyle:Code
10942 \begin_layout Plain Layout
10948 if the float is already defined by the LaTeX document class.
10950 \begin_inset Flex CharStyle:Code
10953 \begin_layout Plain Layout
10959 , the float will be defined using the LaTeX package
10960 \begin_inset Flex CharStyle:Code
10963 \begin_layout Plain Layout
10972 \begin_layout Description
10973 \begin_inset Flex CharStyle:Code
10976 \begin_layout Plain Layout
10983 \begin_inset Flex CharStyle:Code
10986 \begin_layout Plain Layout
10993 \begin_inset Quotes erd
10997 \begin_inset Quotes erd
11000 ] The heading used for the list of floats.
11003 \begin_layout Description
11004 \begin_inset Flex CharStyle:Code
11007 \begin_layout Plain Layout
11014 \begin_inset Flex CharStyle:Code
11017 \begin_layout Plain Layout
11024 \begin_inset Quotes erd
11028 \begin_inset Quotes erd
11031 ] This (optional) argument determines whether floats of this class will
11032 be numbered within some sectional unit of the document.
11033 For example, if within is equal to
11034 \begin_inset Flex CharStyle:Code
11037 \begin_layout Plain Layout
11043 , the floats will be numbered within chapters.
11047 \begin_layout Description
11048 \begin_inset Flex CharStyle:Code
11051 \begin_layout Plain Layout
11058 \begin_inset Flex CharStyle:Code
11061 \begin_layout Plain Layout
11068 \begin_inset Quotes erd
11072 \begin_inset Quotes erd
11075 ] The default placement for the given class of floats.
11076 The string should be as in standard LaTeX:
11077 \begin_inset Flex CharStyle:Code
11080 \begin_layout Plain Layout
11087 \begin_inset Flex CharStyle:Code
11090 \begin_layout Plain Layout
11097 \begin_inset Flex CharStyle:Code
11100 \begin_layout Plain Layout
11107 \begin_inset Flex CharStyle:Code
11110 \begin_layout Plain Layout
11116 for top, bottom, page, and here, respectively.
11120 \begin_layout Plain Layout
11121 Note that the order of these letters in the string is irrelevant, like in
11127 On top of that there is a new type,
11128 \begin_inset Flex CharStyle:Code
11131 \begin_layout Plain Layout
11137 , which does not really correspond to a float, since it means: put it
11138 \begin_inset Quotes eld
11142 \begin_inset Quotes erd
11146 Note however that the
11147 \begin_inset Flex CharStyle:Code
11150 \begin_layout Plain Layout
11156 specifier is special and, because of implementation details, cannot be
11157 used in non-builtin float types.
11158 If you do not understand what this means, just use
11159 \begin_inset Quotes eld
11163 \begin_inset Flex CharStyle:Code
11166 \begin_layout Plain Layout
11173 \begin_inset Quotes erd
11179 \begin_layout Description
11180 \begin_inset Flex CharStyle:Code
11183 \begin_layout Plain Layout
11190 \begin_inset Flex CharStyle:Code
11193 \begin_layout Plain Layout
11200 \begin_inset Quotes erd
11204 \begin_inset Quotes erd
11207 ] The style used when defining the float using
11208 \begin_inset Flex CharStyle:Code
11211 \begin_layout Plain Layout
11222 \begin_layout Description
11223 \begin_inset Flex CharStyle:Code
11226 \begin_layout Plain Layout
11233 \begin_inset Flex CharStyle:Code
11236 \begin_layout Plain Layout
11243 \begin_inset Quotes erd
11247 \begin_inset Quotes erd
11251 \begin_inset Quotes eld
11255 \begin_inset Quotes erd
11258 of the new class of floats, like program or algorithm.
11259 After the appropriate
11260 \begin_inset Flex CharStyle:Code
11263 \begin_layout Plain Layout
11272 \begin_inset Flex CharStyle:Code
11275 \begin_layout Plain Layout
11284 \begin_inset Flex CharStyle:Code
11287 \begin_layout Plain Layout
11298 \begin_layout Standard
11299 Note that defining a float with type
11300 \begin_inset Flex CharStyle:Code
11303 \begin_layout Plain Layout
11311 automatically defines the corresponding counter with name
11312 \begin_inset Flex CharStyle:Code
11315 \begin_layout Plain Layout
11326 \begin_layout Subsection
11327 Inset layouts and Flex insets
11330 \begin_layout Standard
11331 \begin_inset CommandInset label
11333 name "sec:charstyle"
11337 LyX has supported character styles since version 1.4.0; since version 1.6.0
11338 these are called Flex insets.
11342 \begin_layout Standard
11343 Furthermore, it is possible to define the general layout of many different
11345 Currently, InsetLayout can be used to customize the layout parameters for
11346 footnotes, marginal notes, note insets, ERT insets, branches, listings,
11347 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
11352 \begin_layout Standard
11353 Flex insets come in three different kinds:
11356 \begin_layout Itemize
11358 \begin_inset Flex CharStyle:Code
11361 \begin_layout Plain Layout
11367 ): These define semantic markup corresponding to such LaTeX commands as
11369 \begin_inset Flex CharStyle:Code
11372 \begin_layout Plain Layout
11381 \begin_inset Flex CharStyle:Code
11384 \begin_layout Plain Layout
11395 \begin_layout Itemize
11397 \begin_inset Flex CharStyle:Code
11400 \begin_layout Plain Layout
11406 ): These can be used to define custom collapsable insets, similar to ERT,
11407 footnote, and the like.
11410 \begin_layout Itemize
11412 \begin_inset Flex CharStyle:Code
11415 \begin_layout Plain Layout
11421 ): For use with DocBook classes.
11424 \begin_layout Standard
11426 \begin_inset Flex CharStyle:Code
11429 \begin_layout Plain Layout
11435 definition starting line is of the form
11438 \begin_layout LyX-Code
11439 InsetLayout <Type> <Name>
11442 \begin_layout Standard
11444 \begin_inset Flex CharStyle:Code
11447 \begin_layout Plain Layout
11454 \begin_inset Flex CharStyle:Code
11457 \begin_layout Plain Layout
11464 \begin_inset Flex CharStyle:Code
11467 \begin_layout Plain Layout
11474 \begin_inset Flex CharStyle:Code
11477 \begin_layout Plain Layout
11484 \begin_inset Flex CharStyle:Code
11487 \begin_layout Plain Layout
11494 \begin_inset Flex CharStyle:Code
11497 \begin_layout Plain Layout
11504 \begin_inset Flex CharStyle:Code
11507 \begin_layout Plain Layout
11514 \begin_inset Flex CharStyle:Code
11517 \begin_layout Plain Layout
11524 \begin_inset Flex CharStyle:Code
11527 \begin_layout Plain Layout
11534 \begin_inset Flex CharStyle:Code
11537 \begin_layout Plain Layout
11544 \begin_inset Flex CharStyle:Code
11547 \begin_layout Plain Layout
11554 \begin_inset Flex CharStyle:Code
11557 \begin_layout Plain Layout
11564 \begin_inset Flex CharStyle:Code
11567 \begin_layout Plain Layout
11574 \begin_inset Flex CharStyle:Code
11577 \begin_layout Plain Layout
11584 \begin_inset Flex CharStyle:Code
11587 \begin_layout Plain Layout
11594 \begin_inset Flex CharStyle:Code
11597 \begin_layout Plain Layout
11604 \begin_inset Flex CharStyle:Code
11607 \begin_layout Plain Layout
11615 \begin_inset Flex CharStyle:Code
11618 \begin_layout Plain Layout
11625 \begin_inset Flex CharStyle:Code
11628 \begin_layout Plain Layout
11635 \begin_inset Flex CharStyle:Code
11638 \begin_layout Plain Layout
11644 should have the form
11645 \begin_inset Flex CharStyle:Code
11648 \begin_layout Plain Layout
11655 \begin_inset Flex CharStyle:Code
11658 \begin_layout Plain Layout
11665 \begin_inset Flex CharStyle:Code
11668 \begin_layout Plain Layout
11675 \begin_inset Flex CharStyle:Code
11678 \begin_layout Plain Layout
11685 \begin_inset Flex CharStyle:Code
11688 \begin_layout Plain Layout
11695 \begin_inset Flex CharStyle:Code
11698 \begin_layout Plain Layout
11704 is any valid identifier.
11708 \begin_layout Standard
11710 \begin_inset Flex CharStyle:Code
11713 \begin_layout Plain Layout
11719 section can contain the following entries:
11722 \begin_layout Description
11723 \begin_inset Flex CharStyle:Code
11726 \begin_layout Plain Layout
11732 The color for the inset's background.
11733 These valid colors are defined in
11734 \begin_inset Flex CharStyle:Code
11737 \begin_layout Plain Layout
11746 \begin_layout Description
11747 \begin_inset Flex CharStyle:Code
11750 \begin_layout Plain Layout
11756 As with paragraph styles (see page
11757 \begin_inset CommandInset ref
11759 reference "des:CopyStyle"
11766 \begin_layout Description
11767 \begin_inset Flex CharStyle:Code
11770 \begin_layout Plain Layout
11777 \begin_inset Flex CharStyle:Code
11780 \begin_layout Plain Layout
11789 \begin_inset Flex CharStyle:Code
11792 \begin_layout Plain Layout
11798 ] Indicates whether the user may employ the Paragraph Settings dialog to
11799 customize the paragraph.
11802 \begin_layout Description
11803 \begin_inset Flex CharStyle:Code
11806 \begin_layout Plain Layout
11813 \begin_inset Flex CharStyle:Code
11816 \begin_layout Plain Layout
11823 \begin_inset Flex CharStyle:Code
11826 \begin_layout Plain Layout
11833 \begin_inset Flex CharStyle:Code
11836 \begin_layout Plain Layout
11842 , describing the rendering style used for the inset's frame and buttons.
11843 Footnotes generally use
11844 \begin_inset Flex CharStyle:Code
11847 \begin_layout Plain Layout
11853 ; ERT insets generally use
11854 \begin_inset Flex CharStyle:Code
11857 \begin_layout Plain Layout
11863 ; and character styles use
11864 \begin_inset Flex CharStyle:Code
11867 \begin_layout Plain Layout
11876 \begin_layout Description
11877 \begin_inset Flex CharStyle:Code
11880 \begin_layout Plain Layout
11886 Required at the end of the InsetLayout declarations.
11889 \begin_layout Description
11890 \begin_inset Flex CharStyle:Code
11893 \begin_layout Plain Layout
11899 The font used for both the text body
11905 \begin_inset space ~
11909 \begin_inset CommandInset ref
11911 reference "sec:fonts"
11916 Note that defining this font automatically defines the
11917 \begin_inset Flex CharStyle:Code
11920 \begin_layout Plain Layout
11926 to the same value, so define this first and define
11927 \begin_inset Flex CharStyle:Code
11930 \begin_layout Plain Layout
11936 later if you want them to be different.
11939 \begin_layout Description
11940 \begin_inset Flex CharStyle:Code
11943 \begin_layout Plain Layout
11952 \begin_layout Description
11953 \begin_inset Flex CharStyle:Code
11956 \begin_layout Plain Layout
11963 \begin_inset Flex CharStyle:Code
11966 \begin_layout Plain Layout
11975 \begin_inset Flex CharStyle:Code
11978 \begin_layout Plain Layout
11984 ] Indicates whether the PlainLayout should be used or, instead, the user
11985 can change the paragraph style used in the inset.
11988 \begin_layout Description
11989 \begin_inset Flex CharStyle:Code
11992 \begin_layout Plain Layout
11998 As with paragraph styles (see page
11999 \begin_inset CommandInset ref
12000 LatexCommand pageref
12001 reference "des:FreeSpacing"
12008 \begin_layout Description
12009 \begin_inset Flex CharStyle:Code
12012 \begin_layout Plain Layout
12018 As with paragraph styles (see page
12019 \begin_inset CommandInset ref
12020 LatexCommand pageref
12021 reference "des:KeepEmpty"
12028 \begin_layout Description
12029 \begin_inset Flex CharStyle:Code
12032 \begin_layout Plain Layout
12038 The font used for the label.
12040 \begin_inset space ~
12044 \begin_inset CommandInset ref
12046 reference "sec:fonts"
12051 Note that this definition can never appear before
12052 \begin_inset Flex CharStyle:Code
12055 \begin_layout Plain Layout
12061 , lest it be ineffective.
12064 \begin_layout Description
12065 \begin_inset Flex CharStyle:Code
12068 \begin_layout Plain Layout
12074 What will be displayed on the button or elsewhere as the inset label.
12075 Some inset types (ERT and Branch) modify this label on the fly.
12078 \begin_layout Description
12079 \begin_inset Flex CharStyle:Code
12082 \begin_layout Plain Layout
12088 The name of the corresponding LaTeX stuff.
12089 Either the environment or command name.
12092 \begin_layout Description
12093 \begin_inset Flex CharStyle:Code
12096 \begin_layout Plain Layout
12102 The optional parameter for the corresponding
12103 \begin_inset Flex CharStyle:Code
12106 \begin_layout Plain Layout
12112 stuff, including possible bracket pairs like
12113 \begin_inset Flex CharStyle:Code
12116 \begin_layout Plain Layout
12123 This parameter cannot be changed from within LyX.
12126 \begin_layout Description
12127 \begin_inset Flex CharStyle:Code
12130 \begin_layout Plain Layout
12136 As with paragraph styles (see page
12137 \begin_inset CommandInset ref
12138 LatexCommand pageref
12139 reference "des:LatexType"
12146 \begin_layout Description
12147 \begin_inset Flex CharStyle:Code
12150 \begin_layout Plain Layout
12157 \begin_inset Flex CharStyle:Code
12160 \begin_layout Plain Layout
12167 \begin_inset Flex CharStyle:Code
12170 \begin_layout Plain Layout
12177 \begin_inset Flex CharStyle:Code
12180 \begin_layout Plain Layout
12187 \begin_inset Flex CharStyle:Code
12190 \begin_layout Plain Layout
12196 (indicating a dummy definition ending definitions of charstyles etc.).
12197 This entry is only meaningful for Flex (user definable) insets.
12200 \begin_layout Description
12201 \begin_inset Flex CharStyle:Code
12204 \begin_layout Plain Layout
12211 \begin_inset Flex CharStyle:Code
12214 \begin_layout Plain Layout
12223 \begin_inset Flex CharStyle:Code
12226 \begin_layout Plain Layout
12232 ] Whether multiple paragraphs are permitted in this inset.
12233 This will also set CustomPars to the same value and ForcePlain to the opposite
12235 These can be reset to other values, if they are used
12242 \begin_layout Description
12243 \begin_inset Flex CharStyle:Code
12246 \begin_layout Plain Layout
12253 \begin_inset Flex CharStyle:Code
12256 \begin_layout Plain Layout
12265 \begin_inset Flex CharStyle:Code
12268 \begin_layout Plain Layout
12274 ] Whether fragile commands in this layout should be
12275 \begin_inset Flex CharStyle:Code
12278 \begin_layout Plain Layout
12291 whether this command should itself be protected.)
12294 \begin_layout Description
12295 \begin_inset Flex CharStyle:Code
12298 \begin_layout Plain Layout
12305 \begin_inset Flex CharStyle:Code
12308 \begin_layout Plain Layout
12317 \begin_inset Flex CharStyle:Code
12320 \begin_layout Plain Layout
12326 ] As with paragraph styles (see page
12327 \begin_inset CommandInset ref
12329 reference "des:PathThru"
12336 \begin_layout Description
12337 \begin_inset Flex CharStyle:Code
12340 \begin_layout Plain Layout
12346 As with paragraph styles (see page
12347 \begin_inset CommandInset ref
12348 LatexCommand pageref
12349 reference "des:Preamble"
12356 \begin_layout Description
12357 \begin_inset Flex CharStyle:Code
12360 \begin_layout Plain Layout
12367 \begin_inset Flex CharStyle:Code
12370 \begin_layout Plain Layout
12376 ] As with paragraph styles (see page
12377 \begin_inset CommandInset ref
12378 LatexCommand pageref
12379 reference "des:Requires"
12386 \begin_layout Subsection
12390 \begin_layout Standard
12391 \begin_inset CommandInset label
12397 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12399 \begin_inset Flex CharStyle:MenuItem
12402 \begin_layout Plain Layout
12409 \begin_inset Flex CharStyle:MenuItem
12412 \begin_layout Plain Layout
12418 , \SpecialChar \ldots{}
12419 ) in the text class itself.
12420 The standard counters are defined in the file
12421 \begin_inset Flex CharStyle:Code
12424 \begin_layout Plain Layout
12430 , so you may have to do no more than add
12433 \begin_layout LyX-Code
12434 Input stdcounters.inc
12437 \begin_layout Standard
12438 to your layout file to get them to work.
12439 But if you want to define custom counters, then you can do so.
12440 The counter declaration must begin with:
12443 \begin_layout LyX-Code
12447 \begin_layout Standard
12448 where of course `name' is replaced by the name of the counter.
12449 And it must end with
12450 \begin_inset Quotes eld
12454 \begin_inset Flex CharStyle:Code
12457 \begin_layout Plain Layout
12464 \begin_inset Quotes erd
12468 The following parameters can also be used:
12471 \begin_layout Description
12472 \begin_inset Flex CharStyle:Code
12475 \begin_layout Plain Layout
12476 LabelString [string=""]
12481 when this is defined, this string defines how the counter is displayed.
12482 Setting this value sets
12483 \begin_inset Flex CharStyle:Code
12486 \begin_layout Plain Layout
12487 LabelStringAppendix
12493 The following special constructs can be used in the string:
12497 \begin_layout Itemize
12498 \begin_inset Flex CharStyle:Code
12501 \begin_layout Plain Layout
12509 will be replaced by the expansion of the
12510 \begin_inset Flex CharStyle:Code
12513 \begin_layout Plain Layout
12520 \begin_inset Flex CharStyle:Code
12523 \begin_layout Plain Layout
12524 LabelStringAppendix
12530 \begin_inset Flex CharStyle:Code
12533 \begin_layout Plain Layout
12543 \begin_layout Itemize
12544 counter values can be expressed using LaTeX-like macros
12545 \begin_inset Flex CharStyle:Code
12548 \begin_layout Plain Layout
12565 \begin_inset Flex CharStyle:Code
12568 \begin_layout Plain Layout
12580 \begin_layout Plain Layout
12590 Actually, the situation is a bit more complicated: any
12609 other than those descibed below will produce arabic numerals.
12610 It would not be surprising to see this change in the future.
12616 \begin_inset Flex CharStyle:Code
12619 \begin_layout Plain Layout
12625 : 1, 2, 3,\SpecialChar \ldots{}
12627 \begin_inset Flex CharStyle:Code
12630 \begin_layout Plain Layout
12636 for lower-case letters: a, b, c, \SpecialChar \ldots{}
12638 \begin_inset Flex CharStyle:Code
12641 \begin_layout Plain Layout
12647 for upper-case letters: A, B, C, \SpecialChar \ldots{}
12649 \begin_inset Flex CharStyle:Code
12652 \begin_layout Plain Layout
12658 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12660 \begin_inset Flex CharStyle:Code
12663 \begin_layout Plain Layout
12669 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12671 \begin_inset Flex CharStyle:Code
12674 \begin_layout Plain Layout
12680 for hebrew numerals.
12684 \begin_layout Standard
12685 If LabelString is not defined, a default value is constructed as follows:
12686 if the counter has a master counter
12687 \begin_inset Flex CharStyle:Code
12690 \begin_layout Plain Layout
12697 \begin_inset Flex CharStyle:Code
12700 \begin_layout Plain Layout
12707 \begin_inset Flex CharStyle:Code
12710 \begin_layout Plain Layout
12720 is used; otherwise the string
12721 \begin_inset Flex CharStyle:Code
12724 \begin_layout Plain Layout
12735 \begin_layout Description
12736 \begin_inset Flex CharStyle:Code
12739 \begin_layout Plain Layout
12740 LabelStringAppendix [string=""]
12746 \begin_inset Flex CharStyle:Code
12749 \begin_layout Plain Layout
12755 , but for use in the Appendix.
12758 \begin_layout Description
12759 \begin_inset Flex CharStyle:Code
12762 \begin_layout Plain Layout
12769 \begin_inset Flex CharStyle:Code
12772 \begin_layout Plain Layout
12779 \begin_inset Quotes erd
12783 \begin_inset Quotes erd
12786 ] If this is set to the name of another counter, the present counter will
12787 be reset everytime the other one is increased.
12789 \begin_inset Flex CharStyle:Code
12792 \begin_layout Plain Layout
12799 \begin_inset Flex CharStyle:Code
12802 \begin_layout Plain Layout
12811 \begin_layout Subsection
12815 \begin_layout Standard
12816 \begin_inset CommandInset label
12822 A font description looks like this:
12825 \begin_layout LyX-Code
12835 \begin_layout LyX-Code
12839 \begin_layout LyX-Code
12843 \begin_layout Standard
12844 The following commands are available:
12847 \begin_layout Description
12848 \begin_inset Flex CharStyle:Code
12851 \begin_layout Plain Layout
12858 \begin_inset Flex CharStyle:Code
12861 \begin_layout Plain Layout
12870 \begin_inset Flex CharStyle:Code
12873 \begin_layout Plain Layout
12880 \begin_inset Flex CharStyle:Code
12883 \begin_layout Plain Layout
12890 \begin_inset Flex CharStyle:Code
12893 \begin_layout Plain Layout
12900 \begin_inset Flex CharStyle:Code
12903 \begin_layout Plain Layout
12910 \begin_inset Flex CharStyle:Code
12913 \begin_layout Plain Layout
12920 \begin_inset Flex CharStyle:Code
12923 \begin_layout Plain Layout
12930 \begin_inset Flex CharStyle:Code
12933 \begin_layout Plain Layout
12940 \begin_inset Flex CharStyle:Code
12943 \begin_layout Plain Layout
12952 \begin_layout Description
12953 \begin_inset Flex CharStyle:Code
12956 \begin_layout Plain Layout
12965 \begin_inset Flex CharStyle:Code
12968 \begin_layout Plain Layout
12979 \begin_inset Flex CharStyle:Code
12982 \begin_layout Plain Layout
12989 \begin_inset Flex CharStyle:Code
12992 \begin_layout Plain Layout
13001 \begin_layout Description
13002 \begin_inset Flex CharStyle:Code
13005 \begin_layout Plain Layout
13012 \begin_inset Flex CharStyle:Code
13015 \begin_layout Plain Layout
13021 ] Valid argument sare:
13022 \begin_inset Flex CharStyle:Code
13025 \begin_layout Plain Layout
13032 \begin_inset Flex CharStyle:Code
13035 \begin_layout Plain Layout
13042 \begin_inset Flex CharStyle:Code
13045 \begin_layout Plain Layout
13052 \begin_inset Flex CharStyle:Code
13055 \begin_layout Plain Layout
13062 \begin_inset Flex CharStyle:Code
13065 \begin_layout Plain Layout
13072 \begin_inset Flex CharStyle:Code
13075 \begin_layout Plain Layout
13082 Each of these turns on or off the corresponding attribute.
13085 \begin_layout Description
13086 \begin_inset Flex CharStyle:Code
13089 \begin_layout Plain Layout
13098 \begin_inset Flex CharStyle:Code
13101 \begin_layout Plain Layout
13112 \begin_inset Flex CharStyle:Code
13115 \begin_layout Plain Layout
13124 \begin_layout Description
13125 \begin_inset Flex CharStyle:Code
13128 \begin_layout Plain Layout
13137 \begin_inset Flex CharStyle:Code
13140 \begin_layout Plain Layout
13151 \begin_inset Flex CharStyle:Code
13154 \begin_layout Plain Layout
13161 \begin_inset Flex CharStyle:Code
13164 \begin_layout Plain Layout
13171 \begin_inset Flex CharStyle:Code
13174 \begin_layout Plain Layout
13183 \begin_layout Description
13184 \begin_inset Flex CharStyle:Code
13187 \begin_layout Plain Layout
13194 \begin_inset Flex CharStyle:Code
13197 \begin_layout Plain Layout
13204 \begin_inset Flex CharStyle:Code
13207 \begin_layout Plain Layout
13214 \begin_inset Flex CharStyle:Code
13217 \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
13246 \begin_inset Flex CharStyle:Code
13249 \begin_layout Plain Layout
13256 \begin_inset Flex CharStyle:Code
13259 \begin_layout Plain Layout
13266 \begin_inset Flex CharStyle:Code
13269 \begin_layout Plain Layout
13278 \begin_layout Subsection
13279 Upgrading old layout files
13282 \begin_layout Standard
13283 The file format of layout files changes from time to time, so old layout
13284 files need to be converted.
13285 This process has been automated since LyX 1.4.0: If LyX reads an old format
13286 layout file it will call the conversion tool
13287 \begin_inset Flex CharStyle:Code
13290 \begin_layout Plain Layout
13291 LyXDir/scripts/layout2layout.py
13296 and convert it to a temporary file in current format.
13297 The original file is left untouched.
13298 If you want to convert the layout file permanently, just call the converter
13302 \begin_layout LyX-Code
13303 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13306 \begin_layout Standard
13307 (You need to replace
13308 \begin_inset Flex CharStyle:Code
13311 \begin_layout Plain Layout
13317 with the name of your LyX system directory, unless you happen to have defined
13318 such an environment variable.) Then copy
13319 \begin_inset Flex CharStyle:Code
13322 \begin_layout Plain Layout
13329 \begin_inset Flex CharStyle:Code
13332 \begin_layout Plain Layout
13341 \begin_layout Standard
13342 The automatic conversion only handles syntax changes.
13343 It cannot handle the case where the contents of included files was changed,
13344 so these will have to be converted separately.
13347 \begin_layout Section
13349 \begin_inset CommandInset label
13351 name "sec:templates"
13358 \begin_layout Standard
13359 Templates are created just like usual documents.
13360 The only difference is that usual documents contain all possible settings,
13361 including the font scheme and the paper size.
13362 Usually a user doesn't want a template to overwrite his defaults in these
13364 For that reason, the designer of a template should remove the corresponding
13366 \begin_inset Flex CharStyle:Code
13369 \begin_layout Plain Layout
13378 \begin_inset Flex CharStyle:Code
13381 \begin_layout Plain Layout
13389 from the template LyX file.
13390 This can be done with any simple text-editor, for example
13391 \begin_inset Flex CharStyle:Code
13394 \begin_layout Plain Layout
13401 \begin_inset Flex CharStyle:Code
13404 \begin_layout Plain Layout
13414 \begin_layout Standard
13415 Put the edited template files you create in
13416 \begin_inset Flex CharStyle:Code
13419 \begin_layout Plain Layout
13425 , copy the ones you use from the global template directory in
13426 \begin_inset Flex CharStyle:Code
13429 \begin_layout Plain Layout
13435 to the same place, and redefine the template path in the
13436 \begin_inset Flex CharStyle:MenuItem
13439 \begin_layout Plain Layout
13447 \SpecialChar \menuseparator
13452 references\SpecialChar \menuseparator
13461 \begin_layout Standard
13462 Note that there is a template which has a particular meaning:
13463 \begin_inset Flex CharStyle:Code
13466 \begin_layout Plain Layout
13473 This template is loaded everytime you create a new document with
13474 \begin_inset Flex CharStyle:MenuItem
13477 \begin_layout Plain Layout
13487 \SpecialChar \menuseparator
13489 \begin_inset Flex CharStyle:MenuItem
13492 \begin_layout Plain Layout
13502 in order to provide useful defaults.
13503 To create this template from inside LyX, all you have to do is to open
13504 a document with the correct settings, and use the
13505 \begin_inset Flex CharStyle:MenuItem
13508 \begin_layout Plain Layout
13513 e as Document Defaults
13521 \begin_layout Chapter
13522 Including External Material
13525 \begin_layout Standard
13526 \begin_inset Box Shadowbox
13535 height_special "totalheight"
13538 \begin_layout Plain Layout
13539 WARNING: This portion of the documentation has not been updated for some
13541 We certainly hope that it is still accurate, but there are no guarantees.
13549 \begin_layout Standard
13550 The use of material from sources external to LyX is covered in detail in
13556 This part of the manual covers what needs to happen behind the scenes for
13557 new sorts of material to be included.
13560 \begin_layout Section
13564 \begin_layout Standard
13565 The external material feature is based on the concept of a
13570 A template is a specification of how LyX should interface with a certain
13572 As bundled, LyX comes with predefined templates for Xfig figures, various
13573 raster format images, chess diagrams, and LilyPond music notation.
13574 You can check the actual list by using the menu
13575 \begin_inset Flex CharStyle:MenuItem
13578 \begin_layout Plain Layout
13579 Insert\SpecialChar \menuseparator
13580 File\SpecialChar \menuseparator
13587 Furthermore, it is possible to roll your own template to support a specific
13589 Later we'll describe in more detail what is involved, and hopefully you
13590 will submit all the templates you create so we can include them in a later
13594 \begin_layout Standard
13595 Another basic idea of the external material feature is to distinguish between
13596 the original file that serves as a base for final material and the produced
13597 file that is included in your exported or printed document.
13598 For example, consider the case of a figure produced with
13599 \begin_inset Flex CharStyle:Code
13602 \begin_layout Plain Layout
13609 The Xfig application itself works on an original file with the
13610 \begin_inset Flex CharStyle:Code
13613 \begin_layout Plain Layout
13620 Within XFig, you create and change your figure, and when you are done,
13622 \begin_inset Flex CharStyle:Code
13625 \begin_layout Plain Layout
13632 When you want to include the figure in your document, you invoke
13633 \begin_inset Flex CharStyle:Code
13636 \begin_layout Plain Layout
13642 in order to create a PostScript file that can readily be included in your
13645 \begin_inset Flex CharStyle:Code
13648 \begin_layout Plain Layout
13654 file is the original file, and the PostScript file is the produced file.
13657 \begin_layout Standard
13658 This distinction is important in order to allow updating of the material
13659 while you are in the process of writing the document.
13660 Furthermore, it provides us with the flexibility that is needed to support
13661 multiple export formats.
13662 For instance, in the case of a plain text file, it is not exactly an award-winn
13663 ing idea to include the figure as raw PostScript®.
13664 Instead, you'd either prefer to just include a reference to the figure
13665 or try to invoke some graphics to Ascii converter to make the final result
13666 look similar to the real graphics.
13667 The external material management allows you to do this, because it is parameter
13668 ized on the different export formats that LyX supports.
13671 \begin_layout Standard
13672 Besides supporting the production of different products according to the
13673 exported format, it supports tight integration with editing and viewing
13675 In the case of an XFig figure, you are able to invoke Xfig on the original
13676 file with a single click from within the external material dialog in LyX,
13677 and also preview the produced PostScript file with ghostview with another
13679 No more fiddling around with the command line and/or file browsers to locate
13680 and manipulate the original or produced files.
13681 In this way, you are finally able to take full advantage of the many different
13682 applications that are relevant to use when you write your documents, and
13683 ultimately be more productive.
13686 \begin_layout Section
13687 The external template configuration file
13690 \begin_layout Standard
13691 It is relatively easy to add custom external template definitions to LyX.
13692 However, be aware that doing this in an careless manner most probably
13696 introduce an easily exploitable security hole.
13697 So before you do this, please read the discussion about security in section
13699 \begin_inset CommandInset ref
13701 reference "sec:Security-discussion"
13708 \begin_layout Standard
13709 Having said that, we encourage you to submit any interesting templates that
13714 \begin_layout Standard
13715 The external templates are defined in the
13716 \begin_inset Flex CharStyle:Code
13719 \begin_layout Plain Layout
13720 LyXDir/lib/external_templates
13726 You can place your own version in
13727 \begin_inset Flex CharStyle:Code
13730 \begin_layout Plain Layout
13731 UserDir/external_templates
13739 \begin_layout Standard
13740 A typical template looks like this:
13743 \begin_layout LyX-Code
13747 \begin_layout LyX-Code
13748 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
13751 \begin_layout LyX-Code
13755 \begin_layout LyX-Code
13759 \begin_layout LyX-Code
13763 \begin_layout LyX-Code
13767 \begin_layout LyX-Code
13771 \begin_layout LyX-Code
13772 AutomaticProduction true
13775 \begin_layout LyX-Code
13779 \begin_layout LyX-Code
13783 \begin_layout LyX-Code
13787 \begin_layout LyX-Code
13788 TransformCommand Rotate RotationLatexCommand
13791 \begin_layout LyX-Code
13792 TransformCommand Resize ResizeLatexCommand
13795 \begin_layout LyX-Code
13796 Product "$$RotateFront$$ResizeFront
13799 \begin_layout LyX-Code
13804 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
13807 \begin_layout LyX-Code
13808 $$ResizeBack$$RotateBack"
13811 \begin_layout LyX-Code
13815 \begin_layout LyX-Code
13816 UpdateResult "$$AbsPath$$Basename.pstex_t"
13819 \begin_layout LyX-Code
13820 Requirement "graphicx"
13823 \begin_layout LyX-Code
13824 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
13827 \begin_layout LyX-Code
13828 ReferencedFile latex "$$AbsPath$$Basename.eps"
13831 \begin_layout LyX-Code
13832 ReferencedFile dvi "$$AbsPath$$Basename.eps"
13835 \begin_layout LyX-Code
13839 \begin_layout LyX-Code
13843 \begin_layout LyX-Code
13844 TransformCommand Rotate RotationLatexCommand
13847 \begin_layout LyX-Code
13848 TransformCommand Resize ResizeLatexCommand
13851 \begin_layout LyX-Code
13852 Product "$$RotateFront$$ResizeFront
13855 \begin_layout LyX-Code
13860 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
13863 \begin_layout LyX-Code
13864 $$ResizeBack$$RotateBack"
13867 \begin_layout LyX-Code
13868 UpdateFormat pdftex
13871 \begin_layout LyX-Code
13872 UpdateResult "$$AbsPath$$Basename.pdftex_t"
13875 \begin_layout LyX-Code
13876 Requirement "graphicx"
13879 \begin_layout LyX-Code
13880 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
13883 \begin_layout LyX-Code
13884 ReferencedFile latex "$$AbsPath$$Basename.pdf"
13887 \begin_layout LyX-Code
13891 \begin_layout LyX-Code
13895 \begin_layout LyX-Code
13896 Product "$$Contents(
13898 "$$AbsPath$$Basename.asc
13903 \begin_layout LyX-Code
13904 UpdateFormat asciixfig
13907 \begin_layout LyX-Code
13908 UpdateResult "$$AbsPath$$Basename.asc"
13911 \begin_layout LyX-Code
13915 \begin_layout LyX-Code
13919 \begin_layout LyX-Code
13920 Product "<graphic fileref=
13922 "$$AbsOrRelPathMaster$$Basename.eps
13927 \begin_layout LyX-Code
13931 \begin_layout LyX-Code
13935 \begin_layout LyX-Code
13936 UpdateResult "$$AbsPath$$Basename.eps"
13939 \begin_layout LyX-Code
13940 ReferencedFile docbook "$$AbsPath$$Basename.eps"
13943 \begin_layout LyX-Code
13944 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
13947 \begin_layout LyX-Code
13951 \begin_layout LyX-Code
13952 Product "[XFig: $$FName]"
13955 \begin_layout LyX-Code
13959 \begin_layout LyX-Code
13963 \begin_layout Standard
13964 As you can see, the template is enclosed in
13965 \begin_inset Flex CharStyle:Code
13968 \begin_layout Plain Layout
13974 \SpecialChar \ldots{}
13976 \begin_inset Flex CharStyle:Code
13979 \begin_layout Plain Layout
13986 It contains a header specifying some general settings and, for each supported
13987 primary document file format, a section
13988 \begin_inset Flex CharStyle:Code
13991 \begin_layout Plain Layout
13997 \SpecialChar \ldots{}
13999 \begin_inset Flex CharStyle:Code
14002 \begin_layout Plain Layout
14011 \begin_layout Subsection
14012 The template header
14015 \begin_layout Description
14016 \begin_inset Flex CharStyle:Code
14019 \begin_layout Plain Layout
14020 AutomaticProduction
14021 \begin_inset space ~
14029 Whether the file represented by the template must be generated by LyX.
14030 This command must occur exactly once.
14033 \begin_layout Description
14034 \begin_inset Flex CharStyle:Code
14037 \begin_layout Plain Layout
14039 \begin_inset space ~
14047 A glob pattern that is used in the file dialog to filter out the desired
14049 If there is more than one possible file extension (e.g.
14050 \begin_inset space ~
14054 \begin_inset Flex CharStyle:Code
14057 \begin_layout Plain Layout
14064 \begin_inset Flex CharStyle:Code
14067 \begin_layout Plain Layout
14073 ), use something like
14074 \begin_inset Flex CharStyle:Code
14077 \begin_layout Plain Layout
14084 This command must occur exactly once.
14087 \begin_layout Description
14088 \begin_inset Flex CharStyle:Code
14091 \begin_layout Plain Layout
14093 \begin_inset space ~
14101 The text that is displayed on the button.
14102 This command must occur exactly once.
14105 \begin_layout Description
14106 \begin_inset Flex CharStyle:Code
14109 \begin_layout Plain Layout
14111 \begin_inset space ~
14115 \begin_inset space ~
14123 The help text that is used in the External dialog.
14124 Provide enough information to explain to the user just what the template
14125 can provide him with.
14126 This command must occur exactly once.
14129 \begin_layout Description
14130 \begin_inset Flex CharStyle:Code
14133 \begin_layout Plain Layout
14135 \begin_inset space ~
14143 The file format of the original file.
14144 This must be the name of a format that is known to LyX (see section
14145 \begin_inset CommandInset ref
14147 reference "sub:Formats"
14153 \begin_inset Quotes eld
14157 \begin_inset Flex CharStyle:Code
14160 \begin_layout Plain Layout
14167 \begin_inset Quotes erd
14170 if the template can handle original files of more than one format.
14171 LyX will attempt to interrogate the file itself in order to deduce its
14172 format in this case.
14173 This command must occur exactly once.
14176 \begin_layout Description
14177 \begin_inset Flex CharStyle:Code
14180 \begin_layout Plain Layout
14182 \begin_inset space ~
14190 A unique name for the template.
14191 It must not contain substitution macros (see below).
14194 \begin_layout Description
14195 \begin_inset Flex CharStyle:Code
14198 \begin_layout Plain Layout
14200 \begin_inset space ~
14203 Rotate|Resize|Clip|Extra
14208 This command specifies which transformations are supported by this template.
14209 It may occur zero or more times.
14210 This command enables the corresponding tabs in the external dialog.
14212 \begin_inset Flex CharStyle:Code
14215 \begin_layout Plain Layout
14221 command must have either a corresponding
14222 \begin_inset Flex CharStyle:Code
14225 \begin_layout Plain Layout
14232 \begin_inset Flex CharStyle:Code
14235 \begin_layout Plain Layout
14242 \begin_inset Flex CharStyle:Code
14245 \begin_layout Plain Layout
14252 Otherwise the transformation will not be supported by that format.
14255 \begin_layout Subsection
14259 \begin_layout Description
14260 \begin_inset Flex CharStyle:Code
14263 \begin_layout Plain Layout
14265 \begin_inset space ~
14268 LaTeX|PDFLaTeX|PlainText|DocBook
14273 The primary document file format that this format definition is for.
14274 Not every template has a sensible representation in all document file formats.
14275 Please define nevertheless a
14276 \begin_inset Flex CharStyle:Code
14279 \begin_layout Plain Layout
14285 section for all formats.
14286 Use a dummy text when no representation is available.
14287 Then you can at least see a reference to the external material in the exported
14291 \begin_layout Description
14292 \begin_inset Flex CharStyle:Code
14295 \begin_layout Plain Layout
14297 \begin_inset space ~
14301 \begin_inset space ~
14309 This command defines an additional macro
14310 \begin_inset Flex CharStyle:Code
14313 \begin_layout Plain Layout
14319 for substitution in
14320 \begin_inset Flex CharStyle:Code
14323 \begin_layout Plain Layout
14331 \begin_inset Flex CharStyle:Code
14334 \begin_layout Plain Layout
14340 itself may contain substitution macros.
14341 The advantage over using
14342 \begin_inset Flex CharStyle:Code
14345 \begin_layout Plain Layout
14352 \begin_inset Flex CharStyle:Code
14355 \begin_layout Plain Layout
14361 is that the substituted value of
14362 \begin_inset Flex CharStyle:Code
14365 \begin_layout Plain Layout
14371 is sanitized so that it is a valid optional argument in the document format.
14372 This command may occur zero or more times.
14375 \begin_layout Description
14376 \begin_inset Flex CharStyle:Code
14379 \begin_layout Plain Layout
14381 \begin_inset space ~
14389 The text that is inserted in the exported document.
14390 This is actually the most important command and can be quite complex.
14391 This command must occur exactly once.
14394 \begin_layout Description
14395 \begin_inset Flex CharStyle:Code
14398 \begin_layout Plain Layout
14400 \begin_inset space ~
14408 This command specifies a preamble snippet that will be included in the
14410 It has to be defined using
14411 \begin_inset Flex CharStyle:Code
14414 \begin_layout Plain Layout
14420 \SpecialChar \ldots{}
14422 \begin_inset Flex CharStyle:Code
14425 \begin_layout Plain Layout
14432 This command may occur zero or more times.
14435 \begin_layout Description
14436 \begin_inset Flex CharStyle:Code
14439 \begin_layout Plain Layout
14441 \begin_inset space ~
14445 \begin_inset space ~
14453 This command denotes files that are created by the conversion process and
14454 are needed for a particular export format.
14455 If the filename is relative, it is interpreted relative to the master document.
14456 This command may be given zero or more times.
14459 \begin_layout Description
14460 \begin_inset Flex CharStyle:Code
14463 \begin_layout Plain Layout
14465 \begin_inset space ~
14473 The name of a required LaTeX package.
14474 The package is included via
14475 \begin_inset Flex CharStyle:Code
14478 \begin_layout Plain Layout
14486 in the LaTeX preamble.
14487 This command may occur zero or more times.
14490 \begin_layout Description
14491 \begin_inset Flex CharStyle:Code
14494 \begin_layout Plain Layout
14496 \begin_inset space ~
14500 \begin_inset space ~
14503 RotationLatexCommand
14508 This command specifies that the built in LaTeX command should be used for
14510 This command may occur once or not at all.
14513 \begin_layout Description
14514 \begin_inset Flex CharStyle:Code
14517 \begin_layout Plain Layout
14519 \begin_inset space ~
14523 \begin_inset space ~
14531 This command specifies that the built in LaTeX command should be used for
14533 This command may occur once or not at all.
14536 \begin_layout Description
14537 \begin_inset Flex CharStyle:Code
14540 \begin_layout Plain Layout
14542 \begin_inset space ~
14546 \begin_inset space ~
14549 RotationLatexOption
14554 This command specifies that rotation is done via an optional argument.
14555 This command may occur once or not at all.
14558 \begin_layout Description
14559 \begin_inset Flex CharStyle:Code
14562 \begin_layout Plain Layout
14564 \begin_inset space ~
14568 \begin_inset space ~
14576 This command specifies that resizing is done via an optional argument.
14577 This command may occur once or not at all.
14580 \begin_layout Description
14581 \begin_inset Flex CharStyle:Code
14584 \begin_layout Plain Layout
14586 \begin_inset space ~
14590 \begin_inset space ~
14598 This command specifies that clipping is done via an optional argument.
14599 This command may occur once or not at all.
14602 \begin_layout Description
14603 \begin_inset Flex CharStyle:Code
14606 \begin_layout Plain Layout
14608 \begin_inset space ~
14612 \begin_inset space ~
14620 This command specifies that an extra optional argument is used.
14621 This command may occur once or not at all.
14624 \begin_layout Description
14625 \begin_inset Flex CharStyle:Code
14628 \begin_layout Plain Layout
14630 \begin_inset space ~
14638 The file format of the converted file.
14639 This must be the name of a format that is known to LyX (see the
14640 \begin_inset Flex CharStyle:MenuItem
14643 \begin_layout Plain Layout
14648 ools\SpecialChar \menuseparator
14653 references:Conversion
14659 This command must occur exactly once.
14662 \begin_layout Description
14663 \begin_inset Flex CharStyle:Code
14666 \begin_layout Plain Layout
14668 \begin_inset space ~
14676 The file name of the converted file.
14677 The file name must be absolute.
14678 This command must occur exactly once.
14681 \begin_layout Subsection
14682 Preamble definitions
14685 \begin_layout Standard
14686 The external template configuration file may contain additional preamble
14687 definitions enclosed by
14688 \begin_inset Flex CharStyle:Code
14691 \begin_layout Plain Layout
14697 \SpecialChar \ldots{}
14699 \begin_inset Flex CharStyle:Code
14702 \begin_layout Plain Layout
14709 They can be used by the templates in the
14710 \begin_inset Flex CharStyle:Code
14713 \begin_layout Plain Layout
14722 \begin_layout Section
14723 The substitution mechanism
14726 \begin_layout Standard
14727 When the external material facility invokes an external program, it is done
14728 on the basis of a command defined in the template configuration file.
14729 These commands can contain various macros that are expanded before execution.
14730 Execution always take place in the directory of the containing document.
14733 \begin_layout Standard
14734 Also, whenever external material is to be displayed, the name will be produced
14735 by the substitution mechanism, and most other commands in the template
14736 definition support substitution as well.
14739 \begin_layout Standard
14740 The available macros are the following:
14743 \begin_layout Description
14744 \begin_inset Flex CharStyle:Code
14747 \begin_layout Plain Layout
14748 $$AbsOrRelPathMaster
14753 The file path, absolute or relative to the master LyX document.
14756 \begin_layout Description
14757 \begin_inset Flex CharStyle:Code
14760 \begin_layout Plain Layout
14761 $$AbsOrRelPathParent
14766 The file path, absolute or relative to the LyX document.
14769 \begin_layout Description
14770 \begin_inset Flex CharStyle:Code
14773 \begin_layout Plain Layout
14779 The absolute file path.
14782 \begin_layout Description
14783 \begin_inset Flex CharStyle:Code
14786 \begin_layout Plain Layout
14792 The filename without path and without the extension.
14795 \begin_layout Description
14796 \begin_inset Flex CharStyle:Code
14799 \begin_layout Plain Layout
14801 \begin_inset Quotes eld
14805 \begin_inset Quotes erd
14813 This macro will expand to the contents of the file with the name
14814 \begin_inset Flex CharStyle:Code
14817 \begin_layout Plain Layout
14826 \begin_layout Description
14827 \begin_inset Flex CharStyle:Code
14830 \begin_layout Plain Layout
14836 The file extension (including the dot).
14839 \begin_layout Description
14840 \begin_inset Flex CharStyle:Code
14843 \begin_layout Plain Layout
14849 The filename of the file specified in the external material dialog.
14850 This is either an absolute name, or it is relative to the LyX document.
14853 \begin_layout Description
14854 \begin_inset Flex CharStyle:Code
14857 \begin_layout Plain Layout
14864 \begin_inset Flex CharStyle:Code
14867 \begin_layout Plain Layout
14873 (absolute name or relative to the LyX document).
14876 \begin_layout Description
14877 \begin_inset Flex CharStyle:Code
14880 \begin_layout Plain Layout
14886 The file path, relative to the master LyX document.
14889 \begin_layout Description
14890 \begin_inset Flex CharStyle:Code
14893 \begin_layout Plain Layout
14899 The file path, relative to the LyX document.
14902 \begin_layout Description
14903 \begin_inset Flex CharStyle:Code
14906 \begin_layout Plain Layout
14912 This macro will expand to the absolute path of the system directory.
14913 This is typically used to point to the various helper scripts that are
14917 \begin_layout Description
14918 \begin_inset Flex CharStyle:Code
14921 \begin_layout Plain Layout
14927 A name and full path to a temporary file which will be automatically deleted
14928 whenever the containing document is closed, or the external material insertion
14932 \begin_layout Standard
14933 All path macros contain a trailing directory separator, so you can construct
14935 the absolute filename with
14936 \begin_inset Flex CharStyle:Code
14939 \begin_layout Plain Layout
14940 $$AbsPath$$Basename$$Extension
14948 \begin_layout Standard
14949 The macros above are substituted in all commands unless otherwise noted.
14951 \begin_inset Flex CharStyle:Code
14954 \begin_layout Plain Layout
14960 supports additionally the following substitutions if they are enabled by
14962 \begin_inset Flex CharStyle:Code
14965 \begin_layout Plain Layout
14972 \begin_inset Flex CharStyle:Code
14975 \begin_layout Plain Layout
14984 \begin_layout Description
14985 \begin_inset Flex CharStyle:Code
14988 \begin_layout Plain Layout
14994 The front part of the resize command.
14997 \begin_layout Description
14998 \begin_inset Flex CharStyle:Code
15001 \begin_layout Plain Layout
15007 The back part of the resize command.
15010 \begin_layout Description
15011 \begin_inset Flex CharStyle:Code
15014 \begin_layout Plain Layout
15020 The front part of the rotation command.
15023 \begin_layout Description
15024 \begin_inset Flex CharStyle:Code
15027 \begin_layout Plain Layout
15033 The back part of the rotation command.
15036 \begin_layout Standard
15037 The value string of the
15038 \begin_inset Flex CharStyle:Code
15041 \begin_layout Plain Layout
15047 command supports additionally the following substitutions if they are enabled
15049 \begin_inset Flex CharStyle:Code
15052 \begin_layout Plain Layout
15059 \begin_inset Flex CharStyle:Code
15062 \begin_layout Plain Layout
15071 \begin_layout Description
15072 \begin_inset Flex CharStyle:Code
15075 \begin_layout Plain Layout
15084 \begin_layout Description
15085 \begin_inset Flex CharStyle:Code
15088 \begin_layout Plain Layout
15097 \begin_layout Description
15098 \begin_inset Flex CharStyle:Code
15101 \begin_layout Plain Layout
15110 \begin_layout Description
15111 \begin_inset Flex CharStyle:Code
15114 \begin_layout Plain Layout
15120 The rotation option.
15123 \begin_layout Standard
15124 You may ask why there are so many path macros.
15125 There are mainly two reasons:
15128 \begin_layout Enumerate
15129 Relative and absolute file names should remain relative or absolute, respectivel
15131 Users may have reasons to prefer either form.
15132 Relative names are useful for portable documents that should work on different
15133 machines, for example.
15134 Absolute names may be required by some programs.
15137 \begin_layout Enumerate
15138 LaTeX treats relative file names differently than LyX and other programs
15139 in nested included files.
15140 For LyX, a relative file name is always relative to the document that contains
15142 For LaTeX, it is always relative to the master document.
15143 These two definitions are identical if you have only one document, but
15144 differ if you have a master document that includes part documents.
15145 That means that relative filenames must be transformed when presented to
15147 Fortunately LyX does this automatically for you if you choose the right
15151 \begin_layout Standard
15152 So which path macro should be used in new template definitions? The rule
15156 \begin_layout Itemize
15158 \begin_inset Flex CharStyle:Code
15161 \begin_layout Plain Layout
15167 if an absolute path is required.
15170 \begin_layout Itemize
15172 \begin_inset Flex CharStyle:Code
15175 \begin_layout Plain Layout
15176 $$AbsOrRelPathMaster
15181 if the substituted string is some kind of LaTeX input.
15184 \begin_layout Itemize
15186 \begin_inset Flex CharStyle:Code
15189 \begin_layout Plain Layout
15190 $$AbsOrRelPathParent
15195 in order to preserve the user's choice.
15198 \begin_layout Standard
15199 There are special cases where this rule does not work and e.g.
15200 \begin_inset space ~
15203 relative names are needed, but normally it will work just fine.
15204 One example for such a case is the command
15205 \begin_inset Flex CharStyle:Code
15208 \begin_layout Plain Layout
15209 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15214 in the XFig template above: We can't use the absolute name because the
15216 \begin_inset Flex CharStyle:Code
15219 \begin_layout Plain Layout
15225 files needs the relative name in order to rewrite the file content.
15228 \begin_layout Section
15229 \begin_inset CommandInset label
15231 name "sec:Security-discussion"
15235 Security discussion
15238 \begin_layout Standard
15239 \begin_inset Box Shadowbox
15248 height_special "totalheight"
15251 \begin_layout Plain Layout
15252 WARNING: This section is definitely outdated.
15260 \begin_layout Standard
15261 The external material feature interfaces with a lot of external programs
15262 and does so automatically, so we have to consider the security implications
15264 In particular, since you have the option of including your own filenames
15265 and/or parameter strings and those are expanded into a command, it seems
15266 that it would be possible to create a malicious document which executes
15267 arbitrary commands when a user views or prints the document.
15268 This is something we definately want to avoid.
15271 \begin_layout Standard
15272 However, since the external program commands are specified in the template
15273 configuration file only, there are no security issues if LyX is properly
15274 configured with safe templates only.
15275 This is so because the external programs are invoked with the
15276 \begin_inset Flex CharStyle:Code
15279 \begin_layout Plain Layout
15285 -system call rather than the
15286 \begin_inset Flex CharStyle:Code
15289 \begin_layout Plain Layout
15295 system-call, so it's not possible to execute arbitrary commands from the
15296 filename or parameter section via the shell.
15299 \begin_layout Standard
15300 This also implies that you are restricted in what command strings you can
15301 use in the external material templates.
15302 In particular, pipes and redirection are not readily available.
15303 This has to be so if LyX should remain safe.
15304 If you want to use some of the shell features, you should write a safe
15305 script to do this in a controlled manner, and then invoke the script from
15306 the command string.
15308 \begin_inset Flex CharStyle:Code
15311 \begin_layout Plain Layout
15317 directory of the LyX installation, you can find a safe wrapper script
15318 \begin_inset Flex CharStyle:Code
15321 \begin_layout Plain Layout
15322 general_command_wrapper.py
15327 that supports redirection of input and output.
15328 That can serve as an example for how to write safe template scripts.
15329 For a more advanced example that uses
15330 \begin_inset Flex CharStyle:Code
15333 \begin_layout Plain Layout
15339 and friends, take a look at the
15340 \begin_inset Flex CharStyle:Code
15343 \begin_layout Plain Layout
15352 \begin_layout Standard
15353 It is possible to design a template that interacts directly with the shell,
15354 but since this would allow a malicious user to execute arbitrary commands
15355 by writing clever filenames and/or parameters, we generally recommend that
15356 you only use safe scripts that work with the
15357 \begin_inset Flex CharStyle:Code
15360 \begin_layout Plain Layout
15366 system call in a controlled manner.
15367 Of course, for use in a controlled environment, it can be tempting to just
15368 fall back to use ordinary shell scripts.
15369 If you do so, be aware that you
15373 provide an easily exploitable security hole in your system.
15374 Of course it stands to reason that such unsafe templates will never be
15375 included in the standard LyX distribution, although we do encourage people
15376 to submit new templates in the open source tradition.
15377 But LyX as shipped from the official distribution channels will never have
15381 \begin_layout Standard
15382 Including external material provides a lot of power, and you have to be
15383 careful not to introduce security hazards with this power.
15384 A subtle error in a single line in an innocent looking script can open
15385 the door to huge security problems.
15386 So if you do not fully understand the issues, we recommend that you consult
15387 a knowledgable security professional or the LyX development team if you
15388 have any questions about whether a given template is safe or not.
15389 And do this before you use it in an uncontrolled environment.