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.devel.lyx.org"
3106 target "http://www.devel.lyx.org"
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
4395 If such a declaration does not exist in
4403 \begin_inset Flex CharStyle:Code
4406 \begin_layout Plain Layout
4446 \begin_inset Flex CharStyle:Code
4449 \begin_layout Plain Layout
4463 \begin_layout Standard
4464 The following command produces causes äi to be produced when you enter acute-i
4468 \begin_layout LyX-Code
4482 \begin_layout Labeling
4483 \labelwidthstring 00.00.0000
4484 \begin_inset Flex CharStyle:Code
4487 \begin_layout Plain Layout
4493 Combine two accent characters
4496 \begin_layout LyX-Code
4502 accent1 accent2 allowed
4505 \begin_layout Standard
4506 This one is getting pretty esoteric.
4507 It allows you to combine the effect
4563 \begin_inset Flex CharStyle:Code
4566 \begin_layout Plain Layout
4594 \begin_layout Standard
4595 Consider this example from the
4596 \begin_inset Flex CharStyle:Code
4599 \begin_layout Plain Layout
4610 \begin_layout LyX-Code
4613 kmod ; acute aeioyvhAEIOYVH
4617 kcomb acute umlaut iyIY
4620 \begin_layout Standard
4621 This allows you to press
4622 \begin_inset Flex CharStyle:MenuItem
4625 \begin_layout Plain Layout
4633 and get the effect of
4634 \begin_inset Flex CharStyle:Code
4637 \begin_layout Plain Layout
4656 in this case cancels the last dead key, so if you press
4657 \begin_inset Flex CharStyle:MenuItem
4660 \begin_layout Plain Layout
4669 \begin_inset Flex CharStyle:Code
4672 \begin_layout Plain Layout
4685 \begin_layout Subsection
4689 \begin_layout Standard
4691 \begin_inset Flex CharStyle:Code
4694 \begin_layout Plain Layout
4702 mapping is performed, a
4703 \begin_inset Flex CharStyle:Code
4706 \begin_layout Plain Layout
4716 file maps the strings that the symbols generate to characters in the current
4718 The LyX distribution currently includes at least the
4719 \begin_inset Flex CharStyle:Code
4722 \begin_layout Plain Layout
4731 \begin_inset Flex CharStyle:Code
4734 \begin_layout Plain Layout
4745 \begin_layout Standard
4747 \begin_inset Flex CharStyle:Code
4750 \begin_layout Plain Layout
4758 file is a sequence of declarations of the form
4761 \begin_layout LyX-Code
4774 \begin_layout Standard
4775 For example, in order to map
4776 \begin_inset Flex CharStyle:MenuItem
4779 \begin_layout Plain Layout
4789 to the corresponding character in the iso-8859-1 set (233), the following
4793 \begin_layout LyX-Code
4801 \begin_layout Standard
4803 \begin_inset Flex CharStyle:Code
4806 \begin_layout Plain Layout
4815 \begin_inset Flex CharStyle:Code
4818 \begin_layout Plain Layout
4836 the same character can apply to more than one string.
4838 \begin_inset Flex CharStyle:Code
4841 \begin_layout Plain Layout
4852 \begin_layout LyX-Code
4864 \begin_inset Newline newline
4880 \begin_layout Standard
4881 If LyX cannot find a mapping for the string produced by the keystroke or
4882 a deadkey sequence, it will check if it looks like an accented char and
4883 try to draw an accent over the character on screen.
4886 \begin_layout Subsection
4890 \begin_layout Standard
4891 There is a second way to add support for international characters through
4892 so-called dead-keys.
4893 A dead-key works in combination with a letter to produce an accented character.
4894 Here, we'll explain how to create a really simple dead-key to illustrate
4898 \begin_layout Standard
4899 Suppose you happen to need the circumflex character,
4900 \begin_inset Quotes eld
4904 \begin_inset Quotes erd
4909 \begin_inset Flex CharStyle:MenuItem
4912 \begin_layout Plain Layout
4919 \begin_inset space ~
4923 \begin_inset Flex CharStyle:MenuItem
4926 \begin_layout Plain Layout
4932 ] to the LyX command
4933 \begin_inset Flex CharStyle:Code
4936 \begin_layout Plain Layout
4943 \begin_inset Flex CharStyle:Code
4946 \begin_layout Plain Layout
4953 Now, whenever you type the
4954 \begin_inset Flex CharStyle:MenuItem
4957 \begin_layout Plain Layout
4963 -key followed by a letter, that letter will have a circumflex accent on
4965 For example, the sequence
4966 \begin_inset Quotes eld
4970 \begin_inset Flex CharStyle:MenuItem
4973 \begin_layout Plain Layout
4980 \begin_inset Quotes erd
4983 produces the letter:
4984 \begin_inset Quotes eld
4988 \begin_inset Quotes erd
4992 If you tried to type
4993 \begin_inset Quotes eld
4997 \begin_inset Flex CharStyle:MenuItem
5000 \begin_layout Plain Layout
5007 \begin_inset Quotes erd
5010 , however, LyX will complain with a beep, since a
5011 \begin_inset Quotes eld
5015 \begin_inset Flex CharStyle:MenuItem
5018 \begin_layout Plain Layout
5025 \begin_inset Quotes erd
5028 never takes a circumflex accent.
5030 \begin_inset Flex CharStyle:MenuItem
5033 \begin_layout Plain Layout
5039 after a dead-key produces the bare-accent.
5040 Please note this last point! If you bind a key to a dead-key, you'll need
5041 to rebind the character on that key to yet another key.
5043 \begin_inset Flex CharStyle:MenuItem
5046 \begin_layout Plain Layout
5052 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5055 \begin_layout Standard
5056 One common way to bind dead-keys is to use
5057 \begin_inset Flex CharStyle:MenuItem
5060 \begin_layout Plain Layout
5067 \begin_inset Flex CharStyle:MenuItem
5070 \begin_layout Plain Layout
5077 \begin_inset Flex CharStyle:MenuItem
5080 \begin_layout Plain Layout
5086 in combination with an accent, like
5087 \begin_inset Quotes eld
5091 \begin_inset Flex CharStyle:MenuItem
5094 \begin_layout Plain Layout
5101 \begin_inset Quotes erd
5105 \begin_inset Quotes eld
5109 \begin_inset Flex CharStyle:MenuItem
5112 \begin_layout Plain Layout
5119 \begin_inset Quotes erd
5123 \begin_inset Quotes eld
5127 \begin_inset Flex CharStyle:MenuItem
5130 \begin_layout Plain Layout
5137 \begin_inset Quotes erd
5141 Another way involves using
5142 \begin_inset Flex CharStyle:Code
5145 \begin_layout Plain Layout
5152 \begin_inset Flex CharStyle:Code
5155 \begin_layout Plain Layout
5161 to set up the special
5162 \begin_inset Flex CharStyle:Code
5165 \begin_layout Plain Layout
5173 \begin_inset Flex CharStyle:Code
5176 \begin_layout Plain Layout
5182 acts in some ways just like
5183 \begin_inset Flex CharStyle:MenuItem
5186 \begin_layout Plain Layout
5192 and permits you to bind keys to accented characters.
5193 You can also turn keys into dead-keys by binding them to something like
5195 \begin_inset Flex CharStyle:Code
5198 \begin_layout Plain Layout
5204 and then binding this symbolic key to the corresponding LyX command.
5208 \begin_layout Plain Layout
5213 : This is exactly what I do in my
5214 \begin_inset Flex CharStyle:Code
5217 \begin_layout Plain Layout
5224 \begin_inset Flex CharStyle:Code
5227 \begin_layout Plain Layout
5235 \begin_inset Flex CharStyle:MenuItem
5238 \begin_layout Plain Layout
5240 \begin_inset space ~
5249 \begin_inset Flex CharStyle:Code
5252 \begin_layout Plain Layout
5258 and a bunch of these
5259 \begin_inset Quotes eld
5263 \begin_inset Flex CharStyle:Code
5266 \begin_layout Plain Layout
5273 \begin_inset Quotes erd
5276 symbolic keys bound such things as
5277 \begin_inset Flex CharStyle:MenuItem
5280 \begin_layout Plain Layout
5282 \begin_inset space ~
5291 \begin_inset Flex CharStyle:MenuItem
5294 \begin_layout Plain Layout
5296 \begin_inset space ~
5305 This is how I produce my accented characters.
5310 You can make just about anything into the
5311 \begin_inset Flex CharStyle:Code
5314 \begin_layout Plain Layout
5321 \begin_inset Flex CharStyle:MenuItem
5324 \begin_layout Plain Layout
5330 keys, a spare function key, etc.
5331 As for the LyX commands that produce accents, check the entry for
5332 \begin_inset Flex CharStyle:Code
5335 \begin_layout Plain Layout
5346 You'll find the complete list there.
5349 \begin_layout Subsection
5350 Saving your Language Configuration
5353 \begin_layout Standard
5354 You can edit your preferences so that your desired language environment
5355 is automatically configured when LyX starts up, via the
5356 \begin_inset Flex CharStyle:MenuItem
5359 \begin_layout Plain Layout
5364 dit\SpecialChar \menuseparator
5377 \begin_layout Chapter
5378 Installing New Document Classes, Layouts, and Templates
5379 \begin_inset CommandInset label
5381 name "chap:textclass"
5389 \begin_layout Plain Layout
5390 Installing New Document Classes
5398 \begin_layout Standard
5399 In this chapter, we describe the procedures for creating and installing
5400 new LyX layout and template files, as well as offer a refresher on correctly
5401 installing new LaTeX document classes.
5402 Some definitions: a document class is a LaTeX file (usually ending in
5403 \begin_inset Flex CharStyle:Code
5406 \begin_layout Plain Layout
5413 \begin_inset Flex CharStyle:Code
5416 \begin_layout Plain Layout
5422 ) that describes the format of a document such as an article, report, journal
5423 preprint, etc, and all the commands needed to realize that format.
5424 A layout file is a LyX file that corresponds to a LaTeX document class
5425 and that tells LyX how to
5426 \begin_inset Quotes eld
5430 \begin_inset Quotes erd
5433 things on the screen to make the display look something like the final
5435 More precisely, a layout file describes a
5436 \begin_inset Quotes eld
5440 \begin_inset Quotes erd
5443 which is the internal construct LyX uses to render the screen display.
5445 \begin_inset Quotes eld
5449 \begin_inset Quotes erd
5453 \begin_inset Quotes eld
5457 \begin_inset Quotes erd
5460 can be used somewhat interchangeably, but it is better to refer to the
5461 file as the layout, and the thing living in LyX's memory as the text class.
5462 A template file is simply a LyX document that contains a set of predefined
5463 entries for a given document class---entries that are generally required
5465 Templates are especially useful for things like journal manuscripts that
5466 are to be submitted electronically.
5469 \begin_layout Section
5470 Installing a new LaTeX package
5473 \begin_layout Standard
5474 Some installations may not include a LaTeX package that you would like to
5476 For example, you might need FoilTeX, a common (and very powerful) package
5477 for preparing slides or viewgraphs for overhead projectors.
5478 On some systems, you may have a GUI for installing such packages: MikTeX
5479 on Windows®, for example.
5482 \begin_layout Standard
5483 If you don't have such a GUI, then you can follow these steps.
5486 \begin_layout Enumerate
5487 Get the package from
5488 \begin_inset CommandInset href
5491 target "http://www.ctan.org/"
5498 \begin_layout Enumerate
5499 You can install this package in several different places.
5500 If you want it to be available for all users on your system, then you should
5501 install it in your `local' TeX tree; if you want (or need) it to be available
5502 just for you, then you can install it in your own `user' TeX tree.
5503 Where these should be created, if they do not already exist, depends upon
5504 the details of your system.
5505 To find out, look in the file
5506 \begin_inset Flex CharStyle:Code
5509 \begin_layout Plain Layout
5519 \begin_layout Plain Layout
5520 This usually lives in the directory
5521 \begin_inset Flex CharStyle:Code
5524 \begin_layout Plain Layout
5530 , though you can run
5531 \begin_inset Flex CharStyle:Code
5534 \begin_layout Plain Layout
5545 The location of the `local' TeX tree is defined by
5546 \begin_inset Flex CharStyle:Code
5549 \begin_layout Plain Layout
5555 ; this is usually somewhere like
5556 \begin_inset Flex CharStyle:Code
5559 \begin_layout Plain Layout
5560 /usr/local/share/texmf/
5566 The `user' TeX tree is defined by
5567 \begin_inset Flex CharStyle:Code
5570 \begin_layout Plain Layout
5577 \begin_inset Flex CharStyle:Code
5580 \begin_layout Plain Layout
5587 (If these variables are not predefined, you can define them.) You'll probably
5588 need root permissions to create or modify the `local' tree; but your `user'
5589 tree shouldn't have such limitations.
5592 \begin_layout Enumerate
5594 \begin_inset Flex CharStyle:Code
5597 \begin_layout Plain Layout
5604 \begin_inset Flex CharStyle:Code
5607 \begin_layout Plain Layout
5614 \begin_inset Flex CharStyle:Code
5617 \begin_layout Plain Layout
5625 \begin_inset Newline newline
5629 \begin_inset Flex CharStyle:Code
5632 \begin_layout Plain Layout
5633 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5639 \begin_inset Newline newline
5642 But, again, most of this will
5643 \begin_inset Quotes eld
5647 \begin_inset Quotes erd
5653 \begin_layout Enumerate
5658 \begin_layout Plain Layout
5659 We'll assume henceforth that you're defining `local' TeX tree.
5660 If you're defining a user tree, just adjust as necessary.
5666 You must follow the directory structure of your existing
5667 \begin_inset Flex CharStyle:Code
5670 \begin_layout Plain Layout
5676 directory, which will be found at
5677 \begin_inset Flex CharStyle:Code
5680 \begin_layout Plain Layout
5687 For example, latex packages should go under
5688 \begin_inset Flex CharStyle:Code
5691 \begin_layout Plain Layout
5692 $TEXMFLOCAL/tex/latex/
5700 \begin_layout Enumerate
5701 Install the package.
5702 For example, you would unpack the FoilTeX tarball and copy it to
5703 \begin_inset Flex CharStyle:Code
5706 \begin_layout Plain Layout
5707 $TEXMFLOCAL/tex/latex/foiltex
5714 \begin_inset Flex CharStyle:Code
5717 \begin_layout Plain Layout
5723 directory contains various files.
5726 \begin_layout Enumerate
5728 \begin_inset Flex CharStyle:Code
5731 \begin_layout Plain Layout
5739 \begin_inset Flex CharStyle:Code
5742 \begin_layout Plain Layout
5751 \begin_layout Standard
5752 Your package is now installed and available to LaTeX.
5753 To make it available to LyX, you need to create a Layout file, if one is
5754 not already available.
5755 (See the next section.) Once you have a layout file, you need only reconfigure
5757 \begin_inset Flex CharStyle:MenuItem
5760 \begin_layout Plain Layout
5765 ools\SpecialChar \menuseparator
5775 ) and then restart LyX.
5776 You should then see your new package---for example
5777 \begin_inset Flex CharStyle:MenuItem
5780 \begin_layout Plain Layout
5787 \begin_inset Flex CharStyle:MenuItem
5790 \begin_layout Plain Layout
5795 ocument\SpecialChar \menuseparator
5806 \begin_inset Flex CharStyle:MenuItem
5809 \begin_layout Plain Layout
5819 \begin_layout Section
5823 \begin_layout Standard
5824 This section describes how to write and install your own LyX layout files
5825 and walks through the
5826 \begin_inset Flex CharStyle:Code
5829 \begin_layout Plain Layout
5835 text class format as an example.
5837 \begin_inset Flex CharStyle:Code
5840 \begin_layout Plain Layout
5846 files describe what paragraph and character styles are available for a
5847 given document class and how LyX should display them.
5848 We try to provide a thorough description of the process here; however,
5849 there are so many different types of documents supported by LaTeX classes
5850 that we can't hope to cover every different possibility or problem you
5852 (The LyX users' list is frequented by people with lots of experience with
5853 layout design who are willing to share what they've learned.)
5856 \begin_layout Standard
5857 As you prepare to write a new layout, it is extremely helpful to look at
5858 the example layouts distributed with LyX.
5859 If you use a nice LaTeX document class that might be of interest for others,
5860 too, and have a nice corresponding LyX layout, feel free to contribute
5861 the stuff to us, so we may put it into the distribution.
5863 \begin_inset CommandInset href
5865 name "section on the LyX wiki"
5866 target "http://wiki.lyx.org/Layouts/Layouts"
5870 for this kind of material.
5873 \begin_layout Standard
5874 All the tags described in this chapter are case-insensitive; this means
5876 \begin_inset Flex CharStyle:Code
5879 \begin_layout Plain Layout
5886 \begin_inset Flex CharStyle:Code
5889 \begin_layout Plain Layout
5896 \begin_inset Flex CharStyle:Code
5899 \begin_layout Plain Layout
5905 are really the same command.
5906 The possible values are printed in brackets after the feature's name.
5907 The default value if a feature isn't specified inside a text class-description
5909 \begin_inset Flex CharStyle:Code
5912 \begin_layout Plain Layout
5921 If the argument has a datatype like
5922 \begin_inset Quotes eld
5926 \begin_inset Quotes erd
5930 \begin_inset Quotes eld
5934 \begin_inset Quotes erd
5937 , the default is shown like this:
5938 \begin_inset Flex CharStyle:Code
5941 \begin_layout Plain Layout
5952 \begin_layout Subsection
5956 \begin_layout Standard
5957 Similar to layout files, and new with LyX 1.6, are layout
5962 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
5963 some modules---such as the Endnotes module---provide support for just such
5965 In a sense, layout modules are similar to included files---files like
5966 \begin_inset Flex CharStyle:Code
5969 \begin_layout Plain Layout
5975 ---in that modules are not specific to a given document layout but may be
5976 used with many different layouts.
5977 The difference is that using a layout module does not require editing the
5979 Rather, modules are selected in the
5980 \begin_inset Flex CharStyle:MenuItem
5983 \begin_layout Plain Layout
5984 Document\SpecialChar \menuseparator
5993 \begin_layout Standard
5994 Building modules is the easiest way to get started with layout editing,
5995 since it can be as simple as adding a single new paragraph or flex inset.
5996 But modules may, in principle, contain anything a layout file can contain.
5999 \begin_layout Standard
6000 A module must begin with a line like the following:
6003 \begin_layout LyX-Code
6006 DeclareLyXModule[endnotes.sty]{Endnotes}
6009 \begin_layout Standard
6010 The argument in square brackets is optional: It declares any LaTeX packages
6011 on which the module depends.
6012 The mandatory argument, in curly brackets, is the name of the module, as
6014 \begin_inset Flex CharStyle:MenuItem
6017 \begin_layout Plain Layout
6018 Document\SpecialChar \menuseparator
6028 \begin_layout Standard
6029 The module declaration should then be followed by lines like the following:
6032 \begin_layout LyX-Code
6036 \begin_layout LyX-Code
6037 #Adds an endnote command, in addition to footnotes.
6041 \begin_layout LyX-Code
6042 #You will need to add
6044 theendnotes in ERT where you
6047 \begin_layout LyX-Code
6048 #want the endnotes to appear.
6052 \begin_layout LyX-Code
6056 \begin_layout LyX-Code
6057 #Requires: somemodule | othermodule
6060 \begin_layout LyX-Code
6061 #Excludes: badmodule
6064 \begin_layout Standard
6065 The description is used in
6066 \begin_inset Flex CharStyle:MenuItem
6069 \begin_layout Plain Layout
6070 Document\SpecialChar \menuseparator
6076 to provide the user with information about what the module does.
6078 \begin_inset Flex CharStyle:Code
6081 \begin_layout Plain Layout
6087 line is used to identify other modules with which this one must be used;
6089 \begin_inset Flex CharStyle:Code
6092 \begin_layout Plain Layout
6098 line is used to identify modules with which this one may not be used.
6099 Both are optional, and, as shown, multiple modules should be separated
6100 with the pipe symbol: |.
6101 Note that the required modules are treated disjunctively:
6105 of the required modules must be used.
6110 excluded module may be used.
6111 Note that modules are identified here by their
6115 without the .module extension.
6117 \begin_inset Flex CharStyle:Code
6120 \begin_layout Plain Layout
6127 \begin_inset Flex CharStyle:Code
6130 \begin_layout Plain Layout
6139 \begin_layout Standard
6140 After creating a new module, you will need to reconfigure and then restart
6141 LyX for the module to appear in the menu.
6142 However, changes you make to the module will be seen immediately, if you
6144 \begin_inset Flex CharStyle:MenuItem
6147 \begin_layout Plain Layout
6148 Document\SpecialChar \menuseparator
6154 , highlight something, and then hit
6155 \begin_inset Quotes eld
6159 \begin_inset Quotes erd
6165 It is strongly recommended that you save your work before doing so
6170 it is strongly recommended that you not attempt to edit modules while simultaneo
6171 usly working on documents
6174 Though of course the developers strive to keep LyX stable in such situations,
6175 syntax errors and the like in your module file could cause strange behavior.
6178 \begin_layout Subsection
6179 Supporting new document classes
6182 \begin_layout Standard
6183 There are two situations you are likely to encounter when wanting to support
6184 a new LaTeX document class, involving LaTeX2e class (
6185 \begin_inset Flex CharStyle:Code
6188 \begin_layout Plain Layout
6195 \begin_inset Flex CharStyle:Code
6198 \begin_layout Plain Layout
6205 Supporting a style file is usually fairly easy.
6206 Supporting a new document class is a bit harder.
6209 \begin_layout Subsection
6211 \begin_inset Flex CharStyle:MenuItem
6214 \begin_layout Plain Layout
6223 \begin_layout Standard
6224 If your new document class is provided as a style file that is used in conjuncti
6225 on with an existing, supported document class---for the sake of the example,
6226 we'll assume that the style file is called
6227 \begin_inset Flex CharStyle:MenuItem
6230 \begin_layout Plain Layout
6236 and it is meant to be used with
6237 \begin_inset Flex CharStyle:MenuItem
6240 \begin_layout Plain Layout
6246 , which is a standard class---start by copying the existing class's layout
6247 file into your local directory:
6250 \begin_layout LyX-Code
6251 cp report.layout ~/.lyx/layouts/myclass.layout
6254 \begin_layout Standard
6256 \begin_inset Flex CharStyle:Code
6259 \begin_layout Plain Layout
6265 and change the line:
6268 \begin_layout LyX-Code
6271 DeclareLaTeXClass{report}
6274 \begin_layout Standard
6278 \begin_layout LyX-Code
6281 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6284 \begin_layout Standard
6288 \begin_layout LyX-Code
6290 \begin_inset Newline newline
6296 \begin_inset Newline newline
6302 \begin_layout Standard
6303 near the top of the file.
6306 \begin_layout Standard
6307 Start LyX and select
6308 \begin_inset Flex CharStyle:MenuItem
6311 \begin_layout Plain Layout
6316 ools\SpecialChar \menuseparator
6327 Then restart LyX and try creating a new document.
6329 \begin_inset Flex CharStyle:MenuItem
6332 \begin_layout Plain Layout
6338 " as a document class option in the
6339 \begin_inset Flex CharStyle:MenuItem
6342 \begin_layout Plain Layout
6347 ocument\SpecialChar \menuseparator
6358 It is likely that some of the sectioning commands and such in your new
6359 class will work differently from how they worked in the base class---
6360 \begin_inset Flex CharStyle:Code
6363 \begin_layout Plain Layout
6369 in this example---so you can fiddle around with the settings for the different
6370 sections if you wish.
6373 \begin_layout Subsection
6375 \begin_inset Flex CharStyle:MenuItem
6378 \begin_layout Plain Layout
6387 \begin_layout Standard
6388 There are two possibilities here.
6389 One is that the class file is itself based upon an existing document class.
6390 For example, many thesis classes are based upon
6391 \begin_inset Flex CharStyle:MenuItem
6394 \begin_layout Plain Layout
6401 To see whether yours is, look for a line like
6404 \begin_layout LyX-Code
6410 \begin_layout Standard
6412 If so, then you may proceed largely as in the previous section, though
6413 the DeclareLaTeXClass line will be different.
6414 If your new class is thesis, and it is based upon book, then the line should
6419 \begin_layout Plain Layout
6420 And it will be easiest if you save the file to
6421 \begin_inset Flex CharStyle:Code
6424 \begin_layout Plain Layout
6430 : LyX assumes that the document class has the same name as the layout file.
6439 \begin_layout LyX-Code
6442 DeclareLaTeXClass[thesis,book]{thesis}
6445 \begin_layout Standard
6446 If, on the other hand, the new class is not based upon an existing class,
6447 you will probably have to
6448 \begin_inset Quotes eld
6452 \begin_inset Quotes erd
6456 We strongly suggest copying an existing layout file which uses a similar
6457 LaTeX class and then modifying it, if you can do so.
6458 At least use an existing file as a starting point so you can find out what
6459 items you need to worry about.
6460 Again, the specifics are covered below.
6463 \begin_layout Section
6464 Declaring a new text class
6467 \begin_layout Standard
6468 When it's finally time to get your hands dirty and create or edit your own
6469 layout file, the following sections describe what you're up against.
6470 Our advice is to go slowly, save and test often, listen to soothing music,
6471 and enjoy one or two of your favorite adult beverages; more if you are
6472 getting particularly stuck.
6473 It's really not that hard, except that the multitude of options can become
6474 overwhelming if you try to do to much in one sitting.
6475 Go have another adult beverage, just for good measure.
6478 \begin_layout Standard
6482 \begin_layout Standard
6483 Lines in a layout file which begin with a
6484 \begin_inset Flex CharStyle:Code
6487 \begin_layout Plain Layout
6494 There is one exception to this rule: all layouts should begin with lines
6498 \begin_layout LyX-Code
6501 #% Do not delete the line below; configure depends on this
6504 \begin_layout LyX-Code
6509 DeclareLaTeXClass{article}
6512 \begin_layout Standard
6513 The second line is used when you configure LyX.
6514 The layout file is read by the LaTeX script
6515 \begin_inset Flex CharStyle:Code
6518 \begin_layout Plain Layout
6524 , in a special mode where
6525 \begin_inset Flex CharStyle:Code
6528 \begin_layout Plain Layout
6535 The first line is just a LaTeX comment, and the second one contains the
6536 declaration of the text class.
6537 If these lines appear in a file named
6538 \begin_inset Flex CharStyle:Code
6541 \begin_layout Plain Layout
6547 , then they define a text class of name
6548 \begin_inset Flex CharStyle:Code
6551 \begin_layout Plain Layout
6557 (the name of the layout file) which uses the LaTeX document class
6558 \begin_inset Flex CharStyle:Code
6561 \begin_layout Plain Layout
6567 (the default is to use the same name as the layout).
6569 \begin_inset Quotes eld
6573 \begin_inset Quotes erd
6576 that appears above is used as a description of the text class in the
6577 \begin_inset Flex CharStyle:MenuItem
6580 \begin_layout Plain Layout
6585 ocument\SpecialChar \menuseparator
6598 \begin_layout Standard
6599 Let's assume that you wrote your own text class that uses the
6600 \begin_inset Flex CharStyle:Code
6603 \begin_layout Plain Layout
6609 document class, but where you changed the appearance of the section headings.
6610 If you put it in a file
6611 \begin_inset Flex CharStyle:Code
6614 \begin_layout Plain Layout
6620 , the header of this file should be:
6623 \begin_layout LyX-Code
6626 #% Do not delete the line below; configure depends on this
6629 \begin_layout LyX-Code
6634 DeclareLaTeXClass[article]{article (with my own headings)}
6637 \begin_layout Standard
6638 This declares a text class
6639 \begin_inset Flex CharStyle:Code
6642 \begin_layout Plain Layout
6648 , associated with the LaTeX document class
6649 \begin_inset Flex CharStyle:Code
6652 \begin_layout Plain Layout
6659 \begin_inset Quotes eld
6662 article (with my own headings)
6663 \begin_inset Quotes erd
6667 If your text class depends on several packages, you can declare it as:
6670 \begin_layout LyX-Code
6673 #% Do not delete the line below; configure depends on this
6676 \begin_layout LyX-Code
6681 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6684 \begin_layout Standard
6685 This indicates that your text class uses the foo.sty package.
6686 Finally, it is also possible to declare classes for DocBook code.
6687 Typical declarations will look like
6690 \begin_layout LyX-Code
6693 #% Do not delete the line below; configure depends on this
6696 \begin_layout LyX-Code
6701 DeclareDocBookClass[article]{SGML (DocBook article)}
6704 \begin_layout Standard
6705 Note that these declarations can also be given an optional parameter declaring
6706 the name of the document class (but not a list).
6709 \begin_layout Standard
6710 So, to be as explicit as possible, the form of the layout declaration is:
6713 \begin_layout LyX-Code
6718 DeclareLaTeXClass[class,package.sty]{layout description}
6721 \begin_layout Standard
6722 The class need only be specified if the name of the LaTeX class file and
6723 the name of the layout file are different; if the name of the classfile
6724 is not specified, then LyX will simply assume that it is the same as the
6725 name of the layout file.
6728 \begin_layout Standard
6729 When the text class has been modified to your taste, all you have to do
6730 is to copy it either to
6731 \begin_inset Flex CharStyle:Code
6734 \begin_layout Plain Layout
6741 \begin_inset Flex CharStyle:Code
6744 \begin_layout Plain Layout
6751 \begin_inset Flex CharStyle:MenuItem
6754 \begin_layout Plain Layout
6759 ools\SpecialChar \menuseparator
6769 , exit LyX and restart it.
6770 Then your new text class should be available along with the others.
6773 \begin_layout Standard
6774 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6775 you made to your layout files.
6776 As a result, editing layout files could be very time consuming.
6777 Beginning with 1.6, however, you can force a reload of the layout currently
6778 in use by using the LyX function
6779 \begin_inset Flex CharStyle:MenuItem
6782 \begin_layout Plain Layout
6789 There is no default binding for this function---though, of course, you
6790 can bind it to a key yourself.
6791 If you want to use this function, then, you should simply enter it in the
6797 : This is very much an `advanced feature'.
6802 recommended that you save your work before using this function.
6807 recommended that you not attempt to edit your layout while simultaneously
6808 working on a document that you care about.
6809 Use a test document.
6810 Syntax errors and the like in your layout file could cause peculiar behavior.
6811 In particular, such errors could cause LyX to regard the current layout
6812 as invalid and to attempt to switch to some other layout.
6813 The LyX team strives to keep LyX stable in such situations, but safe is
6817 \begin_layout Subsection
6821 \begin_layout Standard
6822 The first non-comment line must contain the file format number:
6825 \begin_layout Description
6826 \begin_inset Flex CharStyle:Code
6829 \begin_layout Plain Layout
6836 \begin_inset Flex CharStyle:Code
6839 \begin_layout Plain Layout
6845 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6846 don't have an explicit file format).
6847 The file format that is documented here is format 8.
6850 \begin_layout Subsection
6851 General text class parameters
6854 \begin_layout Standard
6855 These are the general parameters which describe the form of the entire document:
6858 \begin_layout Description
6859 \begin_inset Flex CharStyle:Code
6862 \begin_layout Plain Layout
6868 Adds information to the document preamble.
6870 \begin_inset Quotes eld
6874 \begin_inset Flex CharStyle:Code
6877 \begin_layout Plain Layout
6884 \begin_inset Quotes erd
6890 \begin_layout Description
6891 \begin_inset Flex CharStyle:Code
6894 \begin_layout Plain Layout
6900 Describes various global options supported by the document class.
6902 \begin_inset space ~
6906 \begin_inset CommandInset ref
6908 reference "sec:classoptions"
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
6945 \begin_inset Flex CharStyle:Code
6948 \begin_layout Plain Layout
6957 \begin_inset Flex CharStyle:Code
6960 \begin_layout Plain Layout
6966 ] Whether the class should default to having one or two columns.
6967 Can be changed in the
6968 \begin_inset Flex CharStyle:MenuItem
6971 \begin_layout Plain Layout
6976 ocument\SpecialChar \menuseparator
6989 \begin_layout Description
6990 \begin_inset Flex CharStyle:Code
6993 \begin_layout Plain Layout
6999 This sequence defines a new counter.
7001 \begin_inset space ~
7005 \begin_inset CommandInset ref
7007 reference "sec:counter"
7013 \begin_inset Quotes eld
7017 \begin_inset Flex CharStyle:Code
7020 \begin_layout Plain Layout
7027 \begin_inset Quotes erd
7033 \begin_layout Description
7034 \begin_inset Flex CharStyle:Code
7037 \begin_layout Plain Layout
7043 Sets the default font used to display the document.
7045 \begin_inset space ~
7049 \begin_inset CommandInset ref
7051 reference "sec:fonts"
7055 for how to declare fonts.
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
7088 \begin_inset Flex CharStyle:Code
7091 \begin_layout Plain Layout
7097 ] This is the style that will be assigned to new paragraphs, usually
7098 \begin_inset Flex CharStyle:MenuItem
7101 \begin_layout Plain Layout
7108 This will default to the first defined style if not given, but you are
7109 highly encouraged to use this directive.
7112 \begin_layout Description
7113 \begin_inset Flex CharStyle:Code
7116 \begin_layout Plain Layout
7122 Defines a new float.
7124 \begin_inset space ~
7128 \begin_inset CommandInset ref
7130 reference "sec:floats"
7136 \begin_inset Quotes eld
7140 \begin_inset Flex CharStyle:Code
7143 \begin_layout Plain Layout
7150 \begin_inset Quotes erd
7156 \begin_layout Description
7157 \begin_inset Flex CharStyle:Code
7160 \begin_layout Plain Layout
7166 As its name implies, this command allows you to include another layout
7167 definition file within yours to avoid duplicating commands.
7168 Common examples are the standard layout files, for example,
7169 \begin_inset Flex CharStyle:Code
7172 \begin_layout Plain Layout
7178 , which contains most of the basic layouts.
7181 \begin_layout Description
7182 \begin_inset Flex CharStyle:Code
7185 \begin_layout Plain Layout
7191 This section (re-)defines the layout of an inset.
7192 It can be applied to an existing inset of to a new, user-defined inset,
7193 e.g., a new character style.
7195 \begin_inset space ~
7199 \begin_inset CommandInset ref
7201 reference "sec:charstyle"
7205 for more information.
7207 \begin_inset Quotes eld
7211 \begin_inset Flex CharStyle:Code
7214 \begin_layout Plain Layout
7221 \begin_inset Quotes erd
7227 \begin_layout Description
7228 \begin_inset Flex CharStyle:Code
7231 \begin_layout Plain Layout
7240 \begin_layout Description
7241 \begin_inset Flex CharStyle:Code
7244 \begin_layout Plain Layout
7250 This command deletes an existing float.
7251 This is particularly useful when you want to suppress a float that has
7252 be defined in an input file.
7255 \begin_layout Description
7256 \begin_inset Flex CharStyle:Code
7259 \begin_layout Plain Layout
7265 This command deletes an existing style.
7266 This is particularly useful when you want to suppress a style that has
7267 be defined in an input file.
7270 \begin_layout Description
7271 \begin_inset Flex CharStyle:Code
7274 \begin_layout Plain Layout
7283 \begin_layout Description
7284 \begin_inset Flex CharStyle:Code
7287 \begin_layout Plain Layout
7298 \begin_inset Flex CharStyle:Code
7301 \begin_layout Plain Layout
7312 \begin_inset Flex CharStyle:Code
7315 \begin_layout Plain Layout
7322 \begin_inset Flex CharStyle:Code
7325 \begin_layout Plain Layout
7331 ] The class default pagestyle.
7332 Can be changed in the
7333 \begin_inset Flex CharStyle:MenuItem
7336 \begin_layout Plain Layout
7341 ocument\SpecialChar \menuseparator
7354 \begin_layout Description
7355 \begin_inset Flex CharStyle:Code
7358 \begin_layout Plain Layout
7364 Sets the preamble for the LaTeX document.
7365 Note that this will completely override any prior
7366 \begin_inset Flex CharStyle:Code
7369 \begin_layout Plain Layout
7376 \begin_inset Flex CharStyle:Code
7379 \begin_layout Plain Layout
7387 \begin_inset Quotes eld
7391 \begin_inset Flex CharStyle:Code
7394 \begin_layout Plain Layout
7401 \begin_inset Quotes erd
7407 \begin_layout Description
7408 \begin_inset Flex CharStyle:Code
7411 \begin_layout Plain Layout
7418 \begin_inset Flex CharStyle:Code
7421 \begin_layout Plain Layout
7428 \begin_inset Flex CharStyle:Code
7431 \begin_layout Plain Layout
7440 \begin_inset Flex CharStyle:Code
7443 \begin_layout Plain Layout
7449 ] Whether the class already provides the feature
7450 \begin_inset Flex CharStyle:Code
7453 \begin_layout Plain Layout
7460 A feature is in general the name of a package (
7461 \begin_inset Flex CharStyle:Code
7464 \begin_layout Plain Layout
7471 \begin_inset Flex CharStyle:Code
7474 \begin_layout Plain Layout
7480 , \SpecialChar \ldots{}
7482 \begin_inset Flex CharStyle:Code
7485 \begin_layout Plain Layout
7492 \begin_inset Flex CharStyle:Code
7495 \begin_layout Plain Layout
7501 ,\SpecialChar \ldots{}
7502 ); the complete list of supported features is unfortunately not documented
7503 outside the LyX source code---but see
7504 \begin_inset Flex CharStyle:Code
7507 \begin_layout Plain Layout
7513 if you're interested.
7515 \begin_inset Flex CharStyle:MenuItem
7518 \begin_layout Plain Layout
7523 elp\SpecialChar \menuseparator
7533 also gives an overview of the supported packages.
7536 \begin_layout Description
7537 \begin_inset Flex CharStyle:Code
7540 \begin_layout Plain Layout
7547 \begin_inset Flex CharStyle:Code
7550 \begin_layout Plain Layout
7556 ] Whether the class requires the feature
7557 \begin_inset Flex CharStyle:Code
7560 \begin_layout Plain Layout
7567 Multiple features must be separated by commas.
7568 Note that you can only request supported features.
7571 \begin_layout Description
7572 \begin_inset Flex CharStyle:Code
7575 \begin_layout Plain Layout
7584 \begin_layout Description
7585 \begin_inset Flex CharStyle:Code
7588 \begin_layout Plain Layout
7597 \begin_layout Description
7598 \begin_inset Flex CharStyle:Code
7601 \begin_layout Plain Layout
7610 \begin_inset Flex CharStyle:Code
7613 \begin_layout Plain Layout
7624 \begin_inset Flex CharStyle:Code
7627 \begin_layout Plain Layout
7633 ] Whether the class-default should be printing on one or both sides of the
7635 Can be changed in the
7636 \begin_inset Flex CharStyle:MenuItem
7639 \begin_layout Plain Layout
7644 ocument\SpecialChar \menuseparator
7657 \begin_layout Description
7658 \begin_inset Flex CharStyle:Code
7661 \begin_layout Plain Layout
7667 This sequence defines a new paragraph style.
7668 If the style already exists, it will redefine some of its parameters instead.
7670 \begin_inset space ~
7674 \begin_inset CommandInset ref
7676 reference "sec:style"
7682 \begin_inset Quotes eld
7686 \begin_inset Flex CharStyle:Code
7689 \begin_layout Plain Layout
7696 \begin_inset Quotes erd
7702 \begin_layout Description
7703 \begin_inset Flex CharStyle:Code
7706 \begin_layout Plain Layout
7713 \begin_inset Flex CharStyle:Code
7716 \begin_layout Plain Layout
7722 ] The name of the command or environment to be used with
7723 \begin_inset Flex CharStyle:Code
7726 \begin_layout Plain Layout
7735 \begin_layout Description
7736 \begin_inset Flex CharStyle:Code
7739 \begin_layout Plain Layout
7746 \begin_inset Flex CharStyle:Code
7749 \begin_layout Plain Layout
7758 \begin_inset Flex CharStyle:Code
7761 \begin_layout Plain Layout
7767 ] Indicates what kind of markup is used to define the title of a document.
7769 \begin_inset Flex CharStyle:Code
7772 \begin_layout Plain Layout
7778 means that the macro with name
7779 \begin_inset Flex CharStyle:Code
7782 \begin_layout Plain Layout
7788 will be inserted after the last layout which has
7789 \begin_inset Quotes eld
7793 \begin_inset Flex CharStyle:Code
7796 \begin_layout Plain Layout
7803 \begin_inset Quotes erd
7808 \begin_inset Flex CharStyle:Code
7811 \begin_layout Plain Layout
7817 corresponds to the case where the block of paragraphs which have
7818 \begin_inset Quotes eld
7822 \begin_inset Flex CharStyle:Code
7825 \begin_layout Plain Layout
7832 \begin_inset Quotes erd
7835 should be enclosed into the
7836 \begin_inset Flex CharStyle:Code
7839 \begin_layout Plain Layout
7848 \begin_layout Description
7849 \begin_inset Flex CharStyle:Code
7852 \begin_layout Plain Layout
7861 \begin_layout Description
7862 \begin_inset Flex CharStyle:Code
7865 \begin_layout Plain Layout
7872 \begin_inset Flex CharStyle:Code
7875 \begin_layout Plain Layout
7881 Specifies a module to be included by default with this document class.
7882 The user can still remove the module, but it will be active at the outset.
7883 (This applies only when new files are created, or when this class is chosen
7884 for an existing document.)
7887 \begin_layout Subsection
7888 \begin_inset Flex CharStyle:Code
7891 \begin_layout Plain Layout
7900 \begin_layout Standard
7901 \begin_inset CommandInset label
7903 name "sec:classoptions"
7908 \begin_inset Flex CharStyle:Code
7911 \begin_layout Plain Layout
7917 section can contain the following entries:
7920 \begin_layout Description
7921 \begin_inset Flex CharStyle:Code
7924 \begin_layout Plain Layout
7931 \begin_inset Flex CharStyle:Code
7934 \begin_layout Plain Layout
7940 ] The list of available font sizes for the document's main font, separated
7942 \begin_inset Quotes eld
7946 \begin_inset Flex CharStyle:Code
7949 \begin_layout Plain Layout
7956 \begin_inset Quotes erd
7962 \begin_layout Description
7963 \begin_inset Flex CharStyle:Code
7966 \begin_layout Plain Layout
7975 \begin_layout Description
7976 \begin_inset Flex CharStyle:Code
7979 \begin_layout Plain Layout
7986 \begin_inset Flex CharStyle:Code
7989 \begin_layout Plain Layout
7990 string="empty|plain|headings|fancy"
7995 ] The list of available page styles, separated by
7996 \begin_inset Quotes eld
8000 \begin_inset Flex CharStyle:Code
8003 \begin_layout Plain Layout
8010 \begin_inset Quotes erd
8016 \begin_layout Description
8017 \begin_inset Flex CharStyle:Code
8020 \begin_layout Plain Layout
8027 \begin_inset Flex CharStyle:Code
8030 \begin_layout Plain Layout
8036 ] Some document class options, separated by a comma, that will be added
8037 to the optional part of the
8038 \begin_inset Flex CharStyle:Code
8041 \begin_layout Plain Layout
8052 \begin_layout Standard
8054 \begin_inset Flex CharStyle:Code
8057 \begin_layout Plain Layout
8063 section must end with
8064 \begin_inset Quotes eld
8068 \begin_inset Flex CharStyle:Code
8071 \begin_layout Plain Layout
8078 \begin_inset Quotes erd
8084 \begin_layout Subsection
8088 \begin_layout Standard
8089 \begin_inset CommandInset label
8095 A paragraph style description looks like this:
8099 \begin_layout Plain Layout
8100 Note that this will either define a new layout or modify an existing one.
8108 \begin_layout LyX-Code
8115 \begin_layout LyX-Code
8119 \begin_layout LyX-Code
8123 \begin_layout Standard
8124 where the following commands are allowed:
8127 \begin_layout Description
8128 \begin_inset Flex CharStyle:Code
8131 \begin_layout Plain Layout
8138 \begin_inset Flex CharStyle:Code
8141 \begin_layout Plain Layout
8146 , left, right, center
8151 ] Paragraph alignment.
8154 \begin_layout Description
8155 \begin_inset Flex CharStyle:Code
8158 \begin_layout Plain Layout
8165 \begin_inset Flex CharStyle:Code
8168 \begin_layout Plain Layout
8173 , left, right, center
8178 ] A comma separated list of permitted alignments.
8179 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8181 For example a right-aligned or centered enumeration isn't possible.)
8184 \begin_layout Description
8185 \begin_inset Flex CharStyle:Code
8188 \begin_layout Plain Layout
8195 \begin_inset Flex CharStyle:Code
8198 \begin_layout Plain Layout
8208 \begin_layout Plain Layout
8209 Note that a `float' here is a real number, such as: 1.5.
8214 The vertical space with which the last of a chain of paragraphs with this
8215 layout is separated from the following paragraph.
8216 If the next paragraph has another layout, the separations are not simply
8217 added, but the maximum is taken.
8220 \begin_layout Description
8221 \begin_inset Flex CharStyle:Code
8224 \begin_layout Plain Layout
8231 \begin_inset Flex CharStyle:Code
8234 \begin_layout Plain Layout
8240 The category for this style.
8241 This is used to group related styles in the Layout combobox on the toolbar.
8242 Any string can be used, but you may want to use existing categories with
8247 \begin_layout Description
8248 \begin_inset Flex CharStyle:Code
8251 \begin_layout Plain Layout
8260 \begin_layout Description
8261 \begin_inset Flex CharStyle:Code
8264 \begin_layout Plain Layout
8271 \begin_inset CommandInset label
8273 name "des:CopyStyle"
8278 \begin_inset Flex CharStyle:Code
8281 \begin_layout Plain Layout
8287 Copies all the features of an existing style into the current one.
8291 \begin_layout Description
8292 \begin_inset Flex CharStyle:Code
8295 \begin_layout Plain Layout
8301 The name of a style whose preamble should be output
8306 This allows to ensure some ordering of the preamble snippets when macros
8307 definitions depend on one another.
8311 \begin_layout Plain Layout
8312 Note that, besides that functionality, there is no way to ensure any ordering
8314 The ordering that you see in a given version of LyX may change without
8315 warning in later versions.
8323 \begin_layout Description
8324 \begin_inset Flex CharStyle:Code
8327 \begin_layout Plain Layout
8334 \begin_inset Flex CharStyle:Code
8337 \begin_layout Plain Layout
8342 , Box, Filled_Box, Static
8347 ] The type of label that stands at the end of the paragraph (or sequence
8349 \begin_inset Flex CharStyle:Code
8352 \begin_layout Plain Layout
8359 \begin_inset Flex CharStyle:Code
8362 \begin_layout Plain Layout
8369 \begin_inset Flex CharStyle:Code
8372 \begin_layout Plain Layout
8379 \begin_inset Flex CharStyle:Code
8382 \begin_layout Plain Layout
8390 \begin_inset Flex CharStyle:Code
8393 \begin_layout Plain Layout
8400 \begin_inset Quotes eld
8404 \begin_inset Quotes erd
8408 \begin_inset Flex CharStyle:Code
8411 \begin_layout Plain Layout
8418 \begin_inset Flex CharStyle:Code
8421 \begin_layout Plain Layout
8422 \begin_inset space ~
8431 \begin_inset space ~
8434 black) square suitable for end of proof markers,
8435 \begin_inset Flex CharStyle:Code
8438 \begin_layout Plain Layout
8444 is an explicit text string.
8447 \begin_layout Description
8448 \begin_inset Flex CharStyle:Code
8451 \begin_layout Plain Layout
8458 \begin_inset Flex CharStyle:Code
8461 \begin_layout Plain Layout
8467 ] The string used for a label with a
8468 \begin_inset Flex CharStyle:Code
8471 \begin_layout Plain Layout
8478 \begin_inset Flex CharStyle:Code
8481 \begin_layout Plain Layout
8491 \begin_layout Description
8492 \begin_inset Flex CharStyle:Code
8495 \begin_layout Plain Layout
8502 \begin_inset Flex CharStyle:Code
8505 \begin_layout Plain Layout
8516 \begin_inset Flex CharStyle:Code
8519 \begin_layout Plain Layout
8528 \begin_layout Description
8529 \begin_inset Flex CharStyle:Code
8532 \begin_layout Plain Layout
8539 \begin_inset Flex CharStyle:Code
8542 \begin_layout Plain Layout
8552 ] With this parameter the
8553 \begin_inset Flex CharStyle:MenuItem
8556 \begin_layout Plain Layout
8563 \begin_inset Quotes eld
8566 Vertical space above
8567 \begin_inset Quotes erd
8571 \begin_inset Flex CharStyle:MenuItem
8574 \begin_layout Plain Layout
8579 dit\SpecialChar \menuseparator
8585 \begin_inset space ~
8593 dialog can be set when initializing a paragraph with this style.
8597 \begin_layout Plain Layout
8600 Note from Jean-Marc:
8602 I'm not sure that this setting has much use, and it should probably be
8603 removed in later versions.
8611 \begin_layout Description
8612 \begin_inset Flex CharStyle:Code
8615 \begin_layout Plain Layout
8621 The font used for both the text body
8627 \begin_inset space ~
8631 \begin_inset CommandInset ref
8633 reference "sec:fonts"
8638 Note that defining this font automatically defines the
8639 \begin_inset Flex CharStyle:Code
8642 \begin_layout Plain Layout
8649 So you should define this one first if you also want to define
8650 \begin_inset Flex CharStyle:Code
8653 \begin_layout Plain Layout
8662 \begin_layout Description
8663 \begin_inset Flex CharStyle:Code
8666 \begin_layout Plain Layout
8673 \begin_inset CommandInset label
8675 name "des:FreeSpacing"
8682 \begin_inset Flex CharStyle:Code
8685 \begin_layout Plain Layout
8696 \begin_inset Flex CharStyle:Code
8699 \begin_layout Plain Layout
8705 ] Usually LyX doesn't allow you to insert more than one space between words,
8706 since a space is considered as the separation between two words, not a
8707 character or symbol of its own.
8708 This is a very fine thing but sometimes annoying, for example, when typing
8709 program code or plain LaTeX code.
8711 \begin_inset Flex CharStyle:Code
8714 \begin_layout Plain Layout
8721 Note that LyX will create protected blanks for the additional blanks when
8722 in another mode than LaTeX-mode.
8725 \begin_layout Description
8726 \begin_inset Flex CharStyle:Code
8729 \begin_layout Plain Layout
8738 \begin_layout Description
8739 \begin_inset Flex CharStyle:Code
8742 \begin_layout Plain Layout
8749 \begin_inset Flex CharStyle:Code
8752 \begin_layout Plain Layout
8758 If 1, marks the layout as being part of a title block (see also the
8759 \begin_inset Flex CharStyle:Code
8762 \begin_layout Plain Layout
8769 \begin_inset Flex CharStyle:Code
8772 \begin_layout Plain Layout
8781 \begin_layout Description
8782 \begin_inset Flex CharStyle:Code
8785 \begin_layout Plain Layout
8792 \begin_inset Flex CharStyle:Code
8795 \begin_layout Plain Layout
8801 ] This provides extra space between paragraphs that have the same layout.
8802 If you put other layouts into an environment, each is separated with the
8804 \begin_inset Flex CharStyle:Code
8807 \begin_layout Plain Layout
8814 But the whole items of the environment are additionally separated with
8816 \begin_inset Flex CharStyle:Code
8819 \begin_layout Plain Layout
8831 \begin_layout Description
8832 \begin_inset Flex CharStyle:Code
8835 \begin_layout Plain Layout
8844 \begin_layout Description
8845 \begin_inset Flex CharStyle:Code
8848 \begin_layout Plain Layout
8855 \begin_inset CommandInset label
8857 name "des:KeepEmpty"
8864 \begin_inset Flex CharStyle:Code
8867 \begin_layout Plain Layout
8878 \begin_inset Flex CharStyle:Code
8881 \begin_layout Plain Layout
8887 ] Usually LyX does not allow you to leave a paragraph empty, since it would
8888 lead to empty LaTeX output.
8889 There are some cases where this could be desirable however: in a letter
8890 template, the required fields can be provided as empty fields, so that
8891 people do not forget them; in some special classes, a layout can be used
8892 as some kind of break, which does not contain actual text.
8895 \begin_layout Description
8896 \begin_inset Flex CharStyle:Code
8899 \begin_layout Plain Layout
8905 [float=0] The vertical space between the label and the text body.
8906 Only used for labels that are above the text body (
8907 \begin_inset Flex CharStyle:Code
8910 \begin_layout Plain Layout
8917 \begin_inset Flex CharStyle:Code
8920 \begin_layout Plain Layout
8921 Centered_Top_Environment
8929 \begin_layout Description
8930 \begin_inset Flex CharStyle:Code
8933 \begin_layout Plain Layout
8940 \begin_inset Flex CharStyle:Code
8943 \begin_layout Plain Layout
8950 \begin_inset Newline newline
8953 The name of the counter for automatic numbering (see Section
8954 \begin_inset CommandInset ref
8956 reference "sec:counter"
8961 This must be given if
8962 \begin_inset Flex CharStyle:Code
8965 \begin_layout Plain Layout
8972 \begin_inset Flex CharStyle:Code
8975 \begin_layout Plain Layout
8984 \begin_layout Description
8985 \begin_inset Flex CharStyle:Code
8988 \begin_layout Plain Layout
8994 The font used for the label.
8996 \begin_inset space ~
9000 \begin_inset CommandInset ref
9002 reference "sec:fonts"
9009 \begin_layout Description
9010 \begin_inset Flex CharStyle:Code
9013 \begin_layout Plain Layout
9020 \begin_inset Flex CharStyle:Code
9023 \begin_layout Plain Layout
9029 ] The horizontal space between the label and the text body.
9030 Only used for labels that are not above the text body.
9033 \begin_layout Description
9034 \begin_inset Flex CharStyle:Code
9037 \begin_layout Plain Layout
9044 \begin_inset Flex CharStyle:Code
9047 \begin_layout Plain Layout
9053 ] The string used for a label with a
9054 \begin_inset Flex CharStyle:Code
9057 \begin_layout Plain Layout
9065 \begin_inset Flex CharStyle:Code
9068 \begin_layout Plain Layout
9074 is set, this string can be contain the special formatting commands described
9076 \begin_inset CommandInset ref
9078 reference "sec:counter"
9086 \begin_layout Plain Layout
9087 For the sake of backwards compatibility, the string
9088 \begin_inset Flex CharStyle:Code
9091 \begin_layout Plain Layout
9101 will be replaced by the expanded
9102 \begin_inset Flex CharStyle:Code
9105 \begin_layout Plain Layout
9112 \begin_inset Flex CharStyle:Code
9115 \begin_layout Plain Layout
9124 This feature is now obsolete and should be replaced by the mechanisms of
9126 \begin_inset CommandInset ref
9128 reference "sec:counter"
9140 \begin_layout Description
9141 \begin_inset Flex CharStyle:Code
9144 \begin_layout Plain Layout
9151 \begin_inset Flex CharStyle:Code
9154 \begin_layout Plain Layout
9160 ] This is used inside the appendix instead of
9161 \begin_inset Flex CharStyle:Code
9164 \begin_layout Plain Layout
9172 \begin_inset Flex CharStyle:Code
9175 \begin_layout Plain Layout
9182 \begin_inset Flex CharStyle:Code
9185 \begin_layout Plain Layout
9194 \begin_layout Description
9195 \begin_inset Flex CharStyle:Code
9198 \begin_layout Plain Layout
9205 \begin_inset Flex CharStyle:Code
9208 \begin_layout Plain Layout
9213 , Manual, Static, Top_Environment,
9214 \begin_inset Newline newline
9217 Centered_Top_Environment, Sensitive, Counter
9223 \begin_inset Newline newline
9227 \begin_inset Flex CharStyle:Code
9230 \begin_layout Plain Layout
9236 means the label is the very first word (up to the first real blank).
9240 \begin_layout Plain Layout
9241 Use protected spaces if you want more than one word as the label.
9247 \begin_inset Flex CharStyle:Code
9250 \begin_layout Plain Layout
9256 means it is defined in the layout (see
9257 \begin_inset Flex CharStyle:Code
9260 \begin_layout Plain Layout
9268 \begin_inset Flex CharStyle:Code
9271 \begin_layout Plain Layout
9278 \begin_inset Flex CharStyle:Code
9281 \begin_layout Plain Layout
9282 Centered_Top_Environment
9287 are special cases of
9288 \begin_inset Flex CharStyle:Code
9291 \begin_layout Plain Layout
9298 The label will be printed above the paragraph, but only at the top of an
9299 environment or the top of a chain of paragraphs with this layout.
9300 Usage is for example the
9301 \begin_inset Flex CharStyle:MenuItem
9304 \begin_layout Plain Layout
9311 \begin_inset Flex CharStyle:MenuItem
9314 \begin_layout Plain Layout
9321 This is also the case for
9322 \begin_inset Flex CharStyle:Code
9325 \begin_layout Plain Layout
9331 labels with latex type
9332 \begin_inset Flex CharStyle:Code
9335 \begin_layout Plain Layout
9341 , in order to make layouts for theorems work correctly.
9343 \begin_inset Flex CharStyle:Code
9346 \begin_layout Plain Layout
9352 is a special case for the caption-labels
9353 \begin_inset Quotes eld
9357 \begin_inset Quotes erd
9361 \begin_inset Quotes eld
9365 \begin_inset Quotes erd
9370 \begin_inset Flex CharStyle:Code
9373 \begin_layout Plain Layout
9379 means the (hardcoded) label string depends on the kind of float.
9381 \begin_inset Flex CharStyle:Code
9384 \begin_layout Plain Layout
9390 label type defines automatically numbered labels.
9392 \begin_inset CommandInset ref
9394 reference "sec:counter"
9401 \begin_layout Description
9402 \begin_inset Flex CharStyle:Code
9405 \begin_layout Plain Layout
9414 \begin_layout Description
9415 \begin_inset Flex CharStyle:Code
9418 \begin_layout Plain Layout
9427 \begin_layout Description
9428 \begin_inset Flex CharStyle:Code
9431 \begin_layout Plain Layout
9437 The name of the corresponding LaTeX stuff.
9438 Either the environment or command name.
9441 \begin_layout Description
9442 \begin_inset Flex CharStyle:Code
9445 \begin_layout Plain Layout
9454 \begin_layout Description
9455 \begin_inset Flex CharStyle:Code
9458 \begin_layout Plain Layout
9464 An optional parameter for the corresponding
9465 \begin_inset Flex CharStyle:Code
9468 \begin_layout Plain Layout
9475 This parameter cannot be changed from within LyX.
9478 \begin_layout Description
9479 \begin_inset Flex CharStyle:Code
9482 \begin_layout Plain Layout
9489 \begin_inset CommandInset label
9491 name "des:LatexType"
9496 \begin_inset Flex CharStyle:Code
9499 \begin_layout Plain Layout
9504 , Command, Environment, Item_Environment,
9510 \begin_inset Flex CharStyle:Code
9513 \begin_layout Plain Layout
9519 ] How the layout should be translated into LaTeX.
9521 \begin_inset Flex CharStyle:Code
9524 \begin_layout Plain Layout
9530 means nothing special.
9532 \begin_inset Flex CharStyle:Code
9535 \begin_layout Plain Layout
9542 \begin_inset Flex CharStyle:Code
9545 \begin_layout Plain Layout
9552 {\SpecialChar \ldots{}
9559 \begin_inset Flex CharStyle:Code
9562 \begin_layout Plain Layout
9569 \begin_inset Flex CharStyle:Code
9572 \begin_layout Plain Layout
9579 }\SpecialChar \ldots{}
9593 \begin_inset Flex CharStyle:Code
9596 \begin_layout Plain Layout
9603 \begin_inset Flex CharStyle:Code
9606 \begin_layout Plain Layout
9613 \begin_inset Flex CharStyle:Code
9616 \begin_layout Plain Layout
9624 is generated for each paragraph of this environment.
9626 \begin_inset Flex CharStyle:Code
9629 \begin_layout Plain Layout
9636 \begin_inset Flex CharStyle:Code
9639 \begin_layout Plain Layout
9646 \begin_inset Flex CharStyle:Code
9649 \begin_layout Plain Layout
9655 is passed as an argument to the environment.
9657 \begin_inset Flex CharStyle:Code
9660 \begin_layout Plain Layout
9666 can be defined in the
9667 \begin_inset Flex CharStyle:MenuItem
9670 \begin_layout Plain Layout
9675 ayout\SpecialChar \menuseparator
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9698 is perhaps a bit misleading, since these rules apply to SGML classes, too.
9699 Visit the SGML class files for specific examples.
9702 \begin_layout Standard
9703 Putting the last few things together, the LaTeX output will be either:
9706 \begin_layout LyX-Code
9709 latexname[latexparam]{\SpecialChar \ldots{}
9713 \begin_layout Standard
9717 \begin_layout LyX-Code
9720 begin{latexname}[latexparam] \SpecialChar \ldots{}
9726 \begin_layout Standard
9727 depending upon the LaTex type.
9730 \begin_layout Description
9731 \begin_inset Flex CharStyle:Code
9734 \begin_layout Plain Layout
9741 \begin_inset Flex CharStyle:Code
9744 \begin_layout Plain Layout
9750 ] If you put layouts into environments, the leftmargins are not simply added,
9751 but added with a factor
9752 \begin_inset Formula $\frac{4}{depth+4}$
9756 Note that this parameter is also used when the margin is defined as
9757 \begin_inset Flex CharStyle:Code
9760 \begin_layout Plain Layout
9767 \begin_inset Flex CharStyle:Code
9770 \begin_layout Plain Layout
9777 Then it is added to the manual or dynamic margin.
9779 \begin_inset Newline newline
9782 The argument is passed as a string.
9784 \begin_inset Quotes eld
9788 \begin_inset Flex CharStyle:Code
9791 \begin_layout Plain Layout
9798 \begin_inset Quotes erd
9801 means that the paragraph is indented with the width of
9802 \begin_inset Quotes eld
9806 \begin_inset Flex CharStyle:Code
9809 \begin_layout Plain Layout
9816 \begin_inset Quotes erd
9820 You can get a negative width by prefixing the string with
9821 \begin_inset Quotes eld
9825 \begin_inset Flex CharStyle:Code
9828 \begin_layout Plain Layout
9835 \begin_inset Quotes erd
9839 This way was chosen so that the look is the same with each used screen
9844 \begin_layout Description
9845 \begin_inset Flex CharStyle:Code
9848 \begin_layout Plain Layout
9855 \begin_inset Flex CharStyle:Code
9858 \begin_layout Plain Layout
9863 , Manual, Dynamic, First_Dynamic, Right_Address_Box
9869 \begin_inset Newline newline
9872 The kind of margin that the layout has on the left side.
9874 \begin_inset Flex CharStyle:Code
9877 \begin_layout Plain Layout
9883 just means a fixed margin.
9885 \begin_inset Flex CharStyle:Code
9888 \begin_layout Plain Layout
9894 means that the left margin depends on the string entered in the
9895 \begin_inset Flex CharStyle:MenuItem
9898 \begin_layout Plain Layout
9903 dit\SpecialChar \menuseparator
9909 \begin_inset space ~
9918 This is used to typeset nice lists without tabulators.
9920 \begin_inset Flex CharStyle:Code
9923 \begin_layout Plain Layout
9929 means that the margin depends on the size of the label.
9930 This is used for automatic enumerated headlines.
9931 It is obvious that the headline
9932 \begin_inset Quotes eld
9935 5.4.3.2.1 Very long headline
9936 \begin_inset Quotes erd
9939 must have a wider left margin (as wide as
9940 \begin_inset Quotes eld
9944 \begin_inset Quotes erd
9947 plus the space) than
9948 \begin_inset Quotes eld
9951 3.2 Very long headline
9952 \begin_inset Quotes erd
9956 \begin_inset Quotes eld
9960 \begin_inset Quotes erd
9963 are not able to do this.
9965 \begin_inset Flex CharStyle:Code
9968 \begin_layout Plain Layout
9974 is similar, but only the very first row of the paragraph is dynamic, while
9975 the others are static; this is used, for example, for descriptions.
9977 \begin_inset Flex CharStyle:Code
9980 \begin_layout Plain Layout
9986 means the margin is chosen in a way that the longest row of this paragraph
9987 fits to the right margin.
9988 This is used to typeset an address on the right edge of the page.
9991 \begin_layout Description
9992 \begin_inset Flex CharStyle:Code
9995 \begin_layout Plain Layout
10002 \begin_inset Flex CharStyle:Code
10005 \begin_layout Plain Layout
10014 \begin_inset Flex CharStyle:Code
10017 \begin_layout Plain Layout
10023 ] Whether fragile commands in this layout should be
10024 \begin_inset Flex CharStyle:Code
10027 \begin_layout Plain Layout
10040 whether this command should itself be protected.)
10043 \begin_layout Description
10044 \begin_inset Flex CharStyle:Code
10047 \begin_layout Plain Layout
10054 \begin_inset Flex CharStyle:Code
10057 \begin_layout Plain Layout
10064 \begin_inset Flex CharStyle:Code
10067 \begin_layout Plain Layout
10075 ] Whether newlines are translated into LaTeX newlines (
10076 \begin_inset Flex CharStyle:Code
10079 \begin_layout Plain Layout
10090 The translation can be switched off to allow more comfortable LaTeX editing
10094 \begin_layout Description
10095 \begin_inset Flex CharStyle:Code
10098 \begin_layout Plain Layout
10105 \begin_inset Flex CharStyle:Code
10108 \begin_layout Plain Layout
10115 \begin_inset Flex CharStyle:Code
10118 \begin_layout Plain Layout
10126 ] Whether the following Paragraph is allowed to indent its very first row.
10128 \begin_inset Flex CharStyle:Code
10131 \begin_layout Plain Layout
10137 means that it is not allowed to do so;
10138 \begin_inset Flex CharStyle:Code
10141 \begin_layout Plain Layout
10147 means it could do so if it wants to.
10150 \begin_layout Description
10151 \begin_inset Flex CharStyle:Code
10154 \begin_layout Plain Layout
10163 \begin_layout Description
10164 \begin_inset Flex CharStyle:Code
10167 \begin_layout Plain Layout
10174 \begin_inset Flex CharStyle:Code
10177 \begin_layout Plain Layout
10183 ] The number of optional arguments that can be used with this layout.
10184 This is useful for things like section headings, and only makes sense with
10188 \begin_layout Description
10189 \begin_inset Flex CharStyle:Code
10192 \begin_layout Plain Layout
10199 \begin_inset Flex CharStyle:Code
10202 \begin_layout Plain Layout
10208 ] The indent of the very first line of a paragraph.
10210 \begin_inset Flex CharStyle:Code
10213 \begin_layout Plain Layout
10219 will be fixed for a certain layout.
10220 The exception is Standard layout, since the indentation of a Standard layout
10221 paragraph can be prohibited with
10222 \begin_inset Flex CharStyle:Code
10225 \begin_layout Plain Layout
10232 Also, Standard layout paragraphs inside environments use the
10233 \begin_inset Flex CharStyle:Code
10236 \begin_layout Plain Layout
10242 of the environment, not their native one.
10243 For example, Standard paragraphs inside an enumeration are not indented.
10246 \begin_layout Description
10247 \begin_inset Flex CharStyle:Code
10250 \begin_layout Plain Layout
10257 \begin_inset Flex CharStyle:Code
10260 \begin_layout Plain Layout
10266 ] The vertical space between two paragraphs of this layout.
10269 \begin_layout Description
10270 \begin_inset Flex CharStyle:Code
10273 \begin_layout Plain Layout
10280 \begin_inset Flex CharStyle:Code
10283 \begin_layout Plain Layout
10289 ] LyX allows the user to choose either
10290 \begin_inset Quotes eld
10294 \begin_inset Quotes erd
10298 \begin_inset Quotes eld
10302 \begin_inset Quotes erd
10305 to typeset a document.
10307 \begin_inset Quotes eld
10311 \begin_inset Quotes erd
10314 is chosen, this value is completely ignored.
10316 \begin_inset Quotes eld
10320 \begin_inset Quotes erd
10323 is chosen, the parindent of a LaTeXtype
10324 \begin_inset Quotes eld
10328 \begin_inset Quotes erd
10331 layout is ignored and all paragraphs are separated by this parskip argument.
10332 The vertical space is calculated with
10333 \begin_inset Flex CharStyle:Code
10336 \begin_layout Plain Layout
10338 \begin_inset space ~
10347 \begin_inset Flex CharStyle:Code
10350 \begin_layout Plain Layout
10356 is the height of a row with the normal font.
10357 This way, the look stays the same with different screen fonts.
10360 \begin_layout Description
10361 \begin_inset Flex CharStyle:Code
10364 \begin_layout Plain Layout
10373 \begin_inset Flex CharStyle:Code
10376 \begin_layout Plain Layout
10387 \begin_inset Flex CharStyle:Code
10390 \begin_layout Plain Layout
10396 ] Whether the contents of this paragraph should be output in raw form, meaning
10397 without special translations that LaTeX would require.
10400 \begin_layout Description
10401 \begin_inset Flex CharStyle:Code
10404 \begin_layout Plain Layout
10411 \begin_inset CommandInset label
10413 name "des:Preamble"
10417 Information to be included in the LaTeX preamable when this style is used.
10418 Used to define macros, load packages, etc., required by this particular
10421 \begin_inset Quotes eld
10425 \begin_inset Flex CharStyle:Code
10428 \begin_layout Plain Layout
10435 \begin_inset Quotes erd
10441 \begin_layout Description
10442 \begin_inset Flex CharStyle:Code
10445 \begin_layout Plain Layout
10452 \begin_inset Flex CharStyle:Code
10455 \begin_layout Plain Layout
10462 \begin_inset CommandInset label
10464 name "des:Requires"
10468 Whether the layout requires the feature
10469 \begin_inset Flex CharStyle:Code
10472 \begin_layout Plain Layout
10479 See the description of
10480 \begin_inset Flex CharStyle:Code
10483 \begin_layout Plain Layout
10490 \begin_inset CommandInset ref
10491 LatexCommand pageref
10492 reference "des:FreeSpacing"
10496 ) for information on `features'.
10500 \begin_layout Description
10501 \begin_inset Flex CharStyle:Code
10504 \begin_layout Plain Layout
10511 \begin_inset Flex CharStyle:Code
10514 \begin_layout Plain Layout
10521 \begin_inset Flex CharStyle:Code
10524 \begin_layout Plain Layout
10533 \begin_layout Description
10534 \begin_inset Flex CharStyle:Code
10537 \begin_layout Plain Layout
10544 \begin_inset Flex CharStyle:Code
10547 \begin_layout Plain Layout
10552 , onehalf, double, other
10561 ] This defines what the default spacing should be in the layout.
10563 \begin_inset Flex CharStyle:Code
10566 \begin_layout Plain Layout
10573 \begin_inset Flex CharStyle:Code
10576 \begin_layout Plain Layout
10583 \begin_inset Flex CharStyle:Code
10586 \begin_layout Plain Layout
10592 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10593 If you specify the argument
10594 \begin_inset Flex CharStyle:Code
10597 \begin_layout Plain Layout
10603 , then you should also provide a numerical argument which will be the actual
10605 Note that, contrary to other parameters,
10606 \begin_inset Flex CharStyle:Code
10609 \begin_layout Plain Layout
10615 implies the generation of specific LaTeX code, using the package
10618 \begin_inset Flex CharStyle:Code
10621 \begin_layout Plain Layout
10630 \begin_layout Description
10631 \begin_inset Flex CharStyle:Code
10634 \begin_layout Plain Layout
10640 The font used for the text body .
10642 \begin_inset CommandInset ref
10644 reference "sec:fonts"
10651 \begin_layout Description
10653 \begin_inset Flex CharStyle:Code
10656 \begin_layout Plain Layout
10664 The level of the style in the table of contents.
10665 This is used for automatic numbering of section headings.
10668 \begin_layout Description
10669 \begin_inset Flex CharStyle:Code
10672 \begin_layout Plain Layout
10679 \begin_inset Flex CharStyle:Code
10682 \begin_layout Plain Layout
10688 ] The vertical space with which the very first of a chain of paragraphs
10689 with this layout is separated from the previous paragraph.
10690 If the previous paragraph has another layout, the separations are not simply
10691 added, but the maximum is taken.
10694 \begin_layout Subsection
10698 \begin_layout Standard
10699 \begin_inset CommandInset label
10705 Since version 1.3.0 of LyX, it is has been both possible and necessary to
10706 define the floats (
10707 \begin_inset Flex CharStyle:MenuItem
10710 \begin_layout Plain Layout
10717 \begin_inset Flex CharStyle:MenuItem
10720 \begin_layout Plain Layout
10726 , \SpecialChar \ldots{}
10727 ) in the text class itself.
10728 Standard floats are included in the file
10729 \begin_inset Flex CharStyle:Code
10732 \begin_layout Plain Layout
10738 , so you may have to do no more than add
10741 \begin_layout LyX-Code
10742 Input stdfloats.inc
10745 \begin_layout Standard
10746 to your layout file.
10747 If you want to implement a text class that proposes some other float types
10748 (like the AGU class bundled with LyX), the information below will hopefully
10752 \begin_layout Description
10753 \begin_inset Flex CharStyle:Code
10756 \begin_layout Plain Layout
10763 \begin_inset Flex CharStyle:Code
10766 \begin_layout Plain Layout
10773 \begin_inset Quotes erd
10777 \begin_inset Quotes erd
10780 ] The file name extension of an auxiliary file for the list of figures (or
10782 LaTeX writes the captions to this file.
10785 \begin_layout Description
10786 \begin_inset Flex CharStyle:Code
10789 \begin_layout Plain Layout
10796 \begin_inset Flex CharStyle:Code
10799 \begin_layout Plain Layout
10806 \begin_inset Quotes erd
10810 \begin_inset Quotes erd
10813 ] The string that will be used in the menus and also for the caption.
10816 \begin_layout Description
10817 \begin_inset Flex CharStyle:Code
10820 \begin_layout Plain Layout
10827 \begin_inset Flex CharStyle:Code
10830 \begin_layout Plain Layout
10839 \begin_inset Flex CharStyle:Code
10842 \begin_layout Plain Layout
10849 \begin_inset Flex CharStyle:Code
10852 \begin_layout Plain Layout
10858 if the float is already defined by the LaTeX document class.
10860 \begin_inset Flex CharStyle:Code
10863 \begin_layout Plain Layout
10869 , the float will be defined using the LaTeX package
10870 \begin_inset Flex CharStyle:Code
10873 \begin_layout Plain Layout
10882 \begin_layout Description
10883 \begin_inset Flex CharStyle:Code
10886 \begin_layout Plain Layout
10893 \begin_inset Flex CharStyle:Code
10896 \begin_layout Plain Layout
10903 \begin_inset Quotes erd
10907 \begin_inset Quotes erd
10910 ] The heading used for the list of floats.
10913 \begin_layout Description
10914 \begin_inset Flex CharStyle:Code
10917 \begin_layout Plain Layout
10924 \begin_inset Flex CharStyle:Code
10927 \begin_layout Plain Layout
10934 \begin_inset Quotes erd
10938 \begin_inset Quotes erd
10941 ] This (optional) argument determines whether floats of this class will
10942 be numbered within some sectional unit of the document.
10943 For example, if within is equal to
10944 \begin_inset Flex CharStyle:Code
10947 \begin_layout Plain Layout
10953 , the floats will be numbered within chapters.
10957 \begin_layout Description
10958 \begin_inset Flex CharStyle:Code
10961 \begin_layout Plain Layout
10968 \begin_inset Flex CharStyle:Code
10971 \begin_layout Plain Layout
10978 \begin_inset Quotes erd
10982 \begin_inset Quotes erd
10985 ] The default placement for the given class of floats.
10986 The string should be as in standard LaTeX:
10987 \begin_inset Flex CharStyle:Code
10990 \begin_layout Plain Layout
10997 \begin_inset Flex CharStyle:Code
11000 \begin_layout Plain Layout
11007 \begin_inset Flex CharStyle:Code
11010 \begin_layout Plain Layout
11017 \begin_inset Flex CharStyle:Code
11020 \begin_layout Plain Layout
11026 for top, bottom, page, and here, respectively.
11030 \begin_layout Plain Layout
11031 Note that the order of these letters in the string is irrelevant, like in
11037 On top of that there is a new type,
11038 \begin_inset Flex CharStyle:Code
11041 \begin_layout Plain Layout
11047 , which does not really correspond to a float, since it means: put it
11048 \begin_inset Quotes eld
11052 \begin_inset Quotes erd
11056 Note however that the
11057 \begin_inset Flex CharStyle:Code
11060 \begin_layout Plain Layout
11066 specifier is special and, because of implementation details, cannot be
11067 used in non-builtin float types.
11068 If you do not understand what this means, just use
11069 \begin_inset Quotes eld
11073 \begin_inset Flex CharStyle:Code
11076 \begin_layout Plain Layout
11083 \begin_inset Quotes erd
11089 \begin_layout Description
11090 \begin_inset Flex CharStyle:Code
11093 \begin_layout Plain Layout
11100 \begin_inset Flex CharStyle:Code
11103 \begin_layout Plain Layout
11110 \begin_inset Quotes erd
11114 \begin_inset Quotes erd
11117 ] The style used when defining the float using
11118 \begin_inset Flex CharStyle:Code
11121 \begin_layout Plain Layout
11132 \begin_layout Description
11133 \begin_inset Flex CharStyle:Code
11136 \begin_layout Plain Layout
11143 \begin_inset Flex CharStyle:Code
11146 \begin_layout Plain Layout
11153 \begin_inset Quotes erd
11157 \begin_inset Quotes erd
11161 \begin_inset Quotes eld
11165 \begin_inset Quotes erd
11168 of the new class of floats, like program or algorithm.
11169 After the appropriate
11170 \begin_inset Flex CharStyle:Code
11173 \begin_layout Plain Layout
11182 \begin_inset Flex CharStyle:Code
11185 \begin_layout Plain Layout
11194 \begin_inset Flex CharStyle:Code
11197 \begin_layout Plain Layout
11208 \begin_layout Standard
11209 Note that defining a float with type
11210 \begin_inset Flex CharStyle:Code
11213 \begin_layout Plain Layout
11221 automatically defines the corresponding counter with name
11222 \begin_inset Flex CharStyle:Code
11225 \begin_layout Plain Layout
11236 \begin_layout Subsection
11237 Inset layouts and Flex insets
11240 \begin_layout Standard
11241 \begin_inset CommandInset label
11243 name "sec:charstyle"
11247 LyX has supported character styles since version 1.4.0; since version 1.6.0
11248 these are called Flex insets.
11252 \begin_layout Standard
11253 Furthermore, it is possible to define the general layout of many different
11255 Currently, InsetLayout can be used to customize the layout parameters
11256 for footnotes, marginal notes, note insets, ERT insets, branches, listings,
11257 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
11262 \begin_layout Standard
11263 Flex insets come in three different kinds:
11266 \begin_layout Itemize
11268 \begin_inset Flex CharStyle:Code
11271 \begin_layout Plain Layout
11277 ): These define semantic markup corresponding to such LaTeX commands as
11279 \begin_inset Flex CharStyle:Code
11282 \begin_layout Plain Layout
11291 \begin_inset Flex CharStyle:Code
11294 \begin_layout Plain Layout
11305 \begin_layout Itemize
11307 \begin_inset Flex CharStyle:Code
11310 \begin_layout Plain Layout
11316 ): These can be used to define custom collapsable insets, similar to ERT,
11317 footnote, and the like.
11320 \begin_layout Itemize
11322 \begin_inset Flex CharStyle:Code
11325 \begin_layout Plain Layout
11331 ): For use with DocBook classes.
11334 \begin_layout Standard
11336 \begin_inset Flex CharStyle:Code
11339 \begin_layout Plain Layout
11345 definition starting line is of the form
11348 \begin_layout LyX-Code
11349 InsetLayout <Type> <Name>
11352 \begin_layout Standard
11354 \begin_inset Flex CharStyle:Code
11357 \begin_layout Plain Layout
11364 \begin_inset Flex CharStyle:Code
11367 \begin_layout Plain Layout
11374 \begin_inset Flex CharStyle:Code
11377 \begin_layout Plain Layout
11384 \begin_inset Flex CharStyle:Code
11387 \begin_layout Plain Layout
11394 \begin_inset Flex CharStyle:Code
11397 \begin_layout Plain Layout
11404 \begin_inset Flex CharStyle:Code
11407 \begin_layout Plain Layout
11414 \begin_inset Flex CharStyle:Code
11417 \begin_layout Plain Layout
11424 \begin_inset Flex CharStyle:Code
11427 \begin_layout Plain Layout
11434 \begin_inset Flex CharStyle:Code
11437 \begin_layout Plain Layout
11444 \begin_inset 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
11525 \begin_inset Flex CharStyle:Code
11528 \begin_layout Plain Layout
11535 \begin_inset Flex CharStyle:Code
11538 \begin_layout Plain Layout
11545 \begin_inset Flex CharStyle:Code
11548 \begin_layout Plain Layout
11554 should have the form
11555 \begin_inset Flex CharStyle:Code
11558 \begin_layout Plain Layout
11565 \begin_inset Flex CharStyle:Code
11568 \begin_layout Plain Layout
11575 \begin_inset Flex CharStyle:Code
11578 \begin_layout Plain Layout
11585 \begin_inset Flex CharStyle:Code
11588 \begin_layout Plain Layout
11595 \begin_inset Flex CharStyle:Code
11598 \begin_layout Plain Layout
11605 \begin_inset Flex CharStyle:Code
11608 \begin_layout Plain Layout
11614 is any valid identifier.
11618 \begin_layout Standard
11620 \begin_inset Flex CharStyle:Code
11623 \begin_layout Plain Layout
11629 section can contain the following entries:
11632 \begin_layout Description
11633 \begin_inset Flex CharStyle:Code
11636 \begin_layout Plain Layout
11642 The color for the inset's background.
11643 These valid colors are defined in
11644 \begin_inset Flex CharStyle:Code
11647 \begin_layout Plain Layout
11656 \begin_layout Description
11657 \begin_inset Flex CharStyle:Code
11660 \begin_layout Plain Layout
11666 As with paragraph styles (see page
11667 \begin_inset CommandInset ref
11669 reference "des:CopyStyle"
11676 \begin_layout Description
11677 \begin_inset Flex CharStyle:Code
11680 \begin_layout Plain Layout
11687 \begin_inset Flex CharStyle:Code
11690 \begin_layout Plain Layout
11697 \begin_inset Flex CharStyle:Code
11700 \begin_layout Plain Layout
11707 \begin_inset Flex CharStyle:Code
11710 \begin_layout Plain Layout
11716 , describing the rendering style used for the inset's frame and buttons.
11717 Footnotes generally use
11718 \begin_inset Flex CharStyle:Code
11721 \begin_layout Plain Layout
11727 ; ERT insets generally use
11728 \begin_inset Flex CharStyle:Code
11731 \begin_layout Plain Layout
11737 ; and character styles use
11738 \begin_inset Flex CharStyle:Code
11741 \begin_layout Plain Layout
11750 \begin_layout Description
11751 \begin_inset Flex CharStyle:Code
11754 \begin_layout Plain Layout
11760 The font used for both the text body
11766 \begin_inset space ~
11770 \begin_inset CommandInset ref
11772 reference "sec:fonts"
11777 Note that defining this font automatically defines the
11778 \begin_inset Flex CharStyle:Code
11781 \begin_layout Plain Layout
11787 to the same value, so define this first and define
11788 \begin_inset Flex CharStyle:Code
11791 \begin_layout Plain Layout
11797 later if you want them to be different.
11800 \begin_layout Description
11801 \begin_inset Flex CharStyle:Code
11804 \begin_layout Plain Layout
11813 \begin_layout Description
11814 \begin_inset Flex CharStyle:Code
11817 \begin_layout Plain Layout
11823 As with paragraph styles (see page
11824 \begin_inset CommandInset ref
11825 LatexCommand pageref
11826 reference "des:FreeSpacing"
11833 \begin_layout Description
11834 \begin_inset Flex CharStyle:Code
11837 \begin_layout Plain Layout
11843 As with paragraph styles (see page
11844 \begin_inset CommandInset ref
11845 LatexCommand pageref
11846 reference "des:KeepEmpty"
11853 \begin_layout Description
11854 \begin_inset Flex CharStyle:Code
11857 \begin_layout Plain Layout
11863 What will be displayed on the button or elsewhere as the inset label.
11864 Some inset types (ERT and Branch) modify this label on the fly.
11867 \begin_layout Description
11868 \begin_inset Flex CharStyle:Code
11871 \begin_layout Plain Layout
11877 The font used for the label.
11879 \begin_inset space ~
11883 \begin_inset CommandInset ref
11885 reference "sec:fonts"
11890 Note that this definition can never appear before
11891 \begin_inset Flex CharStyle:Code
11894 \begin_layout Plain Layout
11900 , lest it be ineffective.
11903 \begin_layout Description
11904 \begin_inset Flex CharStyle:Code
11907 \begin_layout Plain Layout
11913 The name of the corresponding LaTeX stuff.
11914 Either the environment or command name.
11917 \begin_layout Description
11918 \begin_inset Flex CharStyle:Code
11921 \begin_layout Plain Layout
11927 The optional parameter for the corresponding
11928 \begin_inset Flex CharStyle:Code
11931 \begin_layout Plain Layout
11937 stuff, including possible bracket pairs like
11938 \begin_inset Flex CharStyle:Code
11941 \begin_layout Plain Layout
11948 This parameter cannot be changed from within LyX.
11951 \begin_layout Description
11952 \begin_inset Flex CharStyle:Code
11955 \begin_layout Plain Layout
11961 As with paragraph styles (see page
11962 \begin_inset CommandInset ref
11963 LatexCommand pageref
11964 reference "des:LatexType"
11971 \begin_layout Description
11972 \begin_inset Flex CharStyle:Code
11975 \begin_layout Plain Layout
11982 \begin_inset Flex CharStyle:Code
11985 \begin_layout Plain Layout
11992 \begin_inset Flex CharStyle:Code
11995 \begin_layout Plain Layout
12002 \begin_inset Flex CharStyle:Code
12005 \begin_layout Plain Layout
12012 \begin_inset Flex CharStyle:Code
12015 \begin_layout Plain Layout
12021 (indicating a dummy definition ending definitions of charstyles etc.).
12022 This entry is only meaningful for Flex (user definable) insets.
12025 \begin_layout Description
12026 \begin_inset Flex CharStyle:Code
12029 \begin_layout Plain Layout
12036 \begin_inset Flex CharStyle:Code
12039 \begin_layout Plain Layout
12048 \begin_inset Flex CharStyle:Code
12051 \begin_layout Plain Layout
12057 ] Whether fragile commands in this layout should be
12058 \begin_inset Flex CharStyle:Code
12061 \begin_layout Plain Layout
12074 whether this command should itself be protected.)
12077 \begin_layout Description
12078 \begin_inset Flex CharStyle:Code
12081 \begin_layout Plain Layout
12087 As with paragraph styles (see page
12088 \begin_inset CommandInset ref
12089 LatexCommand pageref
12090 reference "des:Preamble"
12097 \begin_layout Description
12098 \begin_inset Flex CharStyle:Code
12101 \begin_layout Plain Layout
12108 \begin_inset Flex CharStyle:Code
12111 \begin_layout Plain Layout
12117 ] As with paragraph styles (see page
12118 \begin_inset CommandInset ref
12119 LatexCommand pageref
12120 reference "des:Requires"
12127 \begin_layout Subsection
12131 \begin_layout Standard
12132 \begin_inset CommandInset label
12138 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12140 \begin_inset Flex CharStyle:MenuItem
12143 \begin_layout Plain Layout
12150 \begin_inset Flex CharStyle:MenuItem
12153 \begin_layout Plain Layout
12159 , \SpecialChar \ldots{}
12160 ) in the text class itself.
12161 The standard counters are defined in the file
12162 \begin_inset Flex CharStyle:Code
12165 \begin_layout Plain Layout
12171 , so you may have to do no more than add
12174 \begin_layout LyX-Code
12175 Input stdcounters.inc
12178 \begin_layout Standard
12179 to your layout file to get them to work.
12180 But if you want to define custom counters, then you can do so, using the
12181 following parameters:
12184 \begin_layout Description
12185 \begin_inset Flex CharStyle:Code
12188 \begin_layout Plain Layout
12189 LabelString [string=""]
12194 when this is defined, this string defines how the counter is displayed.
12195 Setting this value sets
12196 \begin_inset Flex CharStyle:Code
12199 \begin_layout Plain Layout
12200 LabelStringAppendix
12206 The following special constructs can be used in the string:
12210 \begin_layout Itemize
12211 \begin_inset Flex CharStyle:Code
12214 \begin_layout Plain Layout
12222 will be replaced by the expansion of the
12223 \begin_inset Flex CharStyle:Code
12226 \begin_layout Plain Layout
12233 \begin_inset Flex CharStyle:Code
12236 \begin_layout Plain Layout
12237 LabelStringAppendix
12243 \begin_inset Flex CharStyle:Code
12246 \begin_layout Plain Layout
12256 \begin_layout Itemize
12257 counter values can be expressed using LaTeX-like macros
12258 \begin_inset Flex CharStyle:Code
12261 \begin_layout Plain Layout
12278 \begin_inset Flex CharStyle:Code
12281 \begin_layout Plain Layout
12293 \begin_layout Plain Layout
12303 Actually, the situation is a bit more complicated: any
12322 other than those descibed below will produce arabic numerals.
12323 It would not be surprising to see this change in the future.
12329 \begin_inset Flex CharStyle:Code
12332 \begin_layout Plain Layout
12338 : 1, 2, 3,\SpecialChar \ldots{}
12340 \begin_inset Flex CharStyle:Code
12343 \begin_layout Plain Layout
12349 for lower-case letters: a, b, c, \SpecialChar \ldots{}
12351 \begin_inset Flex CharStyle:Code
12354 \begin_layout Plain Layout
12360 for upper-case letters: A, B, C, \SpecialChar \ldots{}
12362 \begin_inset Flex CharStyle:Code
12365 \begin_layout Plain Layout
12371 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12373 \begin_inset Flex CharStyle:Code
12376 \begin_layout Plain Layout
12382 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12384 \begin_inset Flex CharStyle:Code
12387 \begin_layout Plain Layout
12393 for hebrew numerals.
12397 \begin_layout Standard
12398 If LabelString is not defined, a default value is constructed as follows:
12399 if the counter has a master counter
12400 \begin_inset Flex CharStyle:Code
12403 \begin_layout Plain Layout
12410 \begin_inset Flex CharStyle:Code
12413 \begin_layout Plain Layout
12420 \begin_inset Flex CharStyle:Code
12423 \begin_layout Plain Layout
12433 is used; otherwise the string
12434 \begin_inset Flex CharStyle:Code
12437 \begin_layout Plain Layout
12448 \begin_layout Description
12449 \begin_inset Flex CharStyle:Code
12452 \begin_layout Plain Layout
12453 LabelStringAppendix [string=""]
12459 \begin_inset Flex CharStyle:Code
12462 \begin_layout Plain Layout
12471 \begin_layout Description
12472 \begin_inset Flex CharStyle:Code
12475 \begin_layout Plain Layout
12482 \begin_inset Flex CharStyle:Code
12485 \begin_layout Plain Layout
12492 \begin_inset Quotes erd
12496 \begin_inset Quotes erd
12499 ] The name of the counter.
12502 \begin_layout Description
12503 \begin_inset Flex CharStyle:Code
12506 \begin_layout Plain Layout
12513 \begin_inset Flex CharStyle:Code
12516 \begin_layout Plain Layout
12523 \begin_inset Quotes erd
12527 \begin_inset Quotes erd
12530 ] If this is set to the name of another counter, the present counter will
12531 be reset everytime the other one is increased.
12533 \begin_inset Flex CharStyle:Code
12536 \begin_layout Plain Layout
12543 \begin_inset Flex CharStyle:Code
12546 \begin_layout Plain Layout
12555 \begin_layout Subsection
12559 \begin_layout Standard
12560 \begin_inset CommandInset label
12566 A font description looks like this:
12569 \begin_layout LyX-Code
12579 \begin_layout LyX-Code
12583 \begin_layout LyX-Code
12587 \begin_layout Standard
12588 The following commands are available:
12591 \begin_layout Description
12592 \begin_inset Flex CharStyle:Code
12595 \begin_layout Plain Layout
12602 \begin_inset Flex CharStyle:Code
12605 \begin_layout Plain Layout
12614 \begin_inset Flex CharStyle:Code
12617 \begin_layout Plain Layout
12624 \begin_inset Flex CharStyle:Code
12627 \begin_layout Plain Layout
12634 \begin_inset Flex CharStyle:Code
12637 \begin_layout Plain Layout
12644 \begin_inset Flex CharStyle:Code
12647 \begin_layout Plain Layout
12654 \begin_inset Flex CharStyle:Code
12657 \begin_layout Plain Layout
12664 \begin_inset Flex CharStyle:Code
12667 \begin_layout Plain Layout
12674 \begin_inset Flex CharStyle:Code
12677 \begin_layout Plain Layout
12684 \begin_inset Flex CharStyle:Code
12687 \begin_layout Plain Layout
12696 \begin_layout Description
12697 \begin_inset Flex CharStyle:Code
12700 \begin_layout Plain Layout
12709 \begin_inset Flex CharStyle:Code
12712 \begin_layout Plain Layout
12723 \begin_inset Flex CharStyle:Code
12726 \begin_layout Plain Layout
12733 \begin_inset Flex CharStyle:Code
12736 \begin_layout Plain Layout
12745 \begin_layout Description
12746 \begin_inset Flex CharStyle:Code
12749 \begin_layout Plain Layout
12756 \begin_inset Flex CharStyle:Code
12759 \begin_layout Plain Layout
12765 ] Valid argument sare:
12766 \begin_inset Flex CharStyle:Code
12769 \begin_layout Plain Layout
12776 \begin_inset Flex CharStyle:Code
12779 \begin_layout Plain Layout
12786 \begin_inset Flex CharStyle:Code
12789 \begin_layout Plain Layout
12796 \begin_inset Flex CharStyle:Code
12799 \begin_layout Plain Layout
12806 \begin_inset Flex CharStyle:Code
12809 \begin_layout Plain Layout
12816 \begin_inset Flex CharStyle:Code
12819 \begin_layout Plain Layout
12826 Each of these turns on or off the corresponding attribute.
12829 \begin_layout Description
12830 \begin_inset Flex CharStyle:Code
12833 \begin_layout Plain Layout
12842 \begin_inset Flex CharStyle:Code
12845 \begin_layout Plain Layout
12856 \begin_inset Flex CharStyle:Code
12859 \begin_layout Plain Layout
12868 \begin_layout Description
12869 \begin_inset Flex CharStyle:Code
12872 \begin_layout Plain Layout
12881 \begin_inset Flex CharStyle:Code
12884 \begin_layout Plain Layout
12895 \begin_inset Flex CharStyle:Code
12898 \begin_layout Plain Layout
12905 \begin_inset Flex CharStyle:Code
12908 \begin_layout Plain Layout
12915 \begin_inset Flex CharStyle:Code
12918 \begin_layout Plain Layout
12927 \begin_layout Description
12928 \begin_inset Flex CharStyle:Code
12931 \begin_layout Plain Layout
12938 \begin_inset Flex CharStyle:Code
12941 \begin_layout Plain Layout
12948 \begin_inset Flex CharStyle:Code
12951 \begin_layout Plain Layout
12958 \begin_inset Flex CharStyle:Code
12961 \begin_layout Plain Layout
12970 \begin_inset Flex CharStyle:Code
12973 \begin_layout Plain Layout
12980 \begin_inset Flex CharStyle:Code
12983 \begin_layout Plain Layout
12990 \begin_inset Flex CharStyle:Code
12993 \begin_layout Plain Layout
13000 \begin_inset Flex CharStyle:Code
13003 \begin_layout Plain Layout
13010 \begin_inset Flex CharStyle:Code
13013 \begin_layout Plain Layout
13022 \begin_layout Subsection
13023 Upgrading old layout files
13026 \begin_layout Standard
13027 The file format of layout files changes from time to time, so old layout
13028 files need to be converted.
13029 This process has been automated since LyX 1.4.0: If LyX reads an old format
13030 layout file it will call the conversion tool
13031 \begin_inset Flex CharStyle:Code
13034 \begin_layout Plain Layout
13035 LyXDir/scripts/layout2layout.py
13040 and convert it to a temporary file in current format.
13041 The original file is left untouched.
13042 If you want to convert the layout file permanently, just call the converter
13046 \begin_layout LyX-Code
13047 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13050 \begin_layout Standard
13051 (You need to replace
13052 \begin_inset Flex CharStyle:Code
13055 \begin_layout Plain Layout
13061 with the name of your LyX system directory, unless you happen to have defined
13062 such an environment variable.) Then copy
13063 \begin_inset Flex CharStyle:Code
13066 \begin_layout Plain Layout
13073 \begin_inset Flex CharStyle:Code
13076 \begin_layout Plain Layout
13085 \begin_layout Standard
13086 The automatic conversion only handles syntax changes.
13087 It cannot handle the case where the contents of included files was changed,
13088 so these will have to be converted separately.
13091 \begin_layout Section
13093 \begin_inset CommandInset label
13095 name "sec:templates"
13102 \begin_layout Standard
13103 Templates are created just like usual documents.
13104 The only difference is that usual documents contain all possible settings,
13105 including the font scheme and the paper size.
13106 Usually a user doesn't want a template to overwrite his defaults in these
13108 For that reason, the designer of a template should remove the corresponding
13110 \begin_inset Flex CharStyle:Code
13113 \begin_layout Plain Layout
13122 \begin_inset Flex CharStyle:Code
13125 \begin_layout Plain Layout
13133 from the template LyX file.
13134 This can be done with any simple text-editor, for example
13135 \begin_inset Flex CharStyle:Code
13138 \begin_layout Plain Layout
13145 \begin_inset Flex CharStyle:Code
13148 \begin_layout Plain Layout
13158 \begin_layout Standard
13159 Put the edited template files you create in
13160 \begin_inset Flex CharStyle:Code
13163 \begin_layout Plain Layout
13169 , copy the ones you use from the global template directory in
13170 \begin_inset Flex CharStyle:Code
13173 \begin_layout Plain Layout
13179 to the same place, and redefine the template path in the
13180 \begin_inset Flex CharStyle:MenuItem
13183 \begin_layout Plain Layout
13191 \SpecialChar \menuseparator
13196 references\SpecialChar \menuseparator
13205 \begin_layout Standard
13206 Note that there is a template which has a particular meaning:
13207 \begin_inset Flex CharStyle:Code
13210 \begin_layout Plain Layout
13217 This template is loaded everytime you create a new document with
13218 \begin_inset Flex CharStyle:MenuItem
13221 \begin_layout Plain Layout
13231 \SpecialChar \menuseparator
13233 \begin_inset Flex CharStyle:MenuItem
13236 \begin_layout Plain Layout
13246 in order to provide useful defaults.
13247 To create this template from inside LyX, all you have to do is to open
13248 a document with the correct settings, and use the
13249 \begin_inset Flex CharStyle:MenuItem
13252 \begin_layout Plain Layout
13257 e as Document Defaults
13265 \begin_layout Chapter
13266 Including External Material
13269 \begin_layout Standard
13270 The use of material from sources external to LyX is covered in detail in
13276 This part of the manual covers what needs to happen behind the scenes for
13277 new sorts of material to be included.
13280 \begin_layout Section
13284 \begin_layout Standard
13285 The external material feature is based on the concept of a
13290 A template is a specification of how LyX should interface with a certain
13292 As bundled, LyX comes with predefined templates for Xfig figures, various
13293 raster format images, chess diagrams, and LilyPond music notation.
13294 You can check the actual list by using the menu
13295 \begin_inset Flex CharStyle:MenuItem
13298 \begin_layout Plain Layout
13299 Insert\SpecialChar \menuseparator
13300 File\SpecialChar \menuseparator
13307 Furthermore, it is possible to roll your own template to support a specific
13309 Later we'll describe in more detail what is involved, and hopefully you
13310 will submit all the templates you create so we can include them in a later
13314 \begin_layout Standard
13315 Another basic idea of the external material feature is to distinguish between
13316 the original file that serves as a base for final material and the produced
13317 file that is included in your exported or printed document.
13318 For example, consider the case of a figure produced with
13319 \begin_inset Flex CharStyle:Code
13322 \begin_layout Plain Layout
13329 The Xfig application itself works on an original file with the
13330 \begin_inset Flex CharStyle:Code
13333 \begin_layout Plain Layout
13340 Within XFig, you create and change your figure, and when you are done,
13342 \begin_inset Flex CharStyle:Code
13345 \begin_layout Plain Layout
13352 When you want to include the figure in your document, you invoke
13353 \begin_inset Flex CharStyle:Code
13356 \begin_layout Plain Layout
13362 in order to create a PostScript file that can readily be included in your
13365 \begin_inset Flex CharStyle:Code
13368 \begin_layout Plain Layout
13374 file is the original file, and the PostScript file is the produced file.
13377 \begin_layout Standard
13378 This distinction is important in order to allow updating of the material
13379 while you are in the process of writing the document.
13380 Furthermore, it provides us with the flexibility that is needed to support
13381 multiple export formats.
13382 For instance, in the case of a plain text file, it is not exactly an award-winn
13383 ing idea to include the figure as raw PostScript®.
13384 Instead, you'd either prefer to just include a reference to the figure
13385 or try to invoke some graphics to Ascii converter to make the final result
13386 look similar to the real graphics.
13387 The external material management allows you to do this, because it is parameter
13388 ized on the different export formats that LyX supports.
13391 \begin_layout Standard
13392 Besides supporting the production of different products according to the
13393 exported format, it supports tight integration with editing and viewing
13395 In the case of an XFig figure, you are able to invoke Xfig on the original
13396 file with a single click from within the external material dialog in LyX,
13397 and also preview the produced PostScript file with ghostview with another
13399 No more fiddling around with the command line and/or file browsers to locate
13400 and manipulate the original or produced files.
13401 In this way, you are finally able to take full advantage of the many different
13402 applications that are relevant to use when you write your documents, and
13403 ultimately be more productive.
13406 \begin_layout Section
13407 The external template configuration file
13410 \begin_layout Standard
13411 It is relatively easy to add custom external template definitions to LyX.
13412 However, be aware that doing this in an careless manner most probably
13416 introduce an easily exploitable security hole.
13417 So before you do this, please read the discussion about security in section
13419 \begin_inset CommandInset ref
13421 reference "sec:Security-discussion"
13428 \begin_layout Standard
13429 Having said that, we encourage you to submit any interesting templates that
13434 \begin_layout Standard
13435 The external templates are defined in the
13436 \begin_inset Flex CharStyle:Code
13439 \begin_layout Plain Layout
13440 LyXDir/lib/external_templates
13446 You can place your own version in
13447 \begin_inset Flex CharStyle:Code
13450 \begin_layout Plain Layout
13451 UserDir/external_templates
13459 \begin_layout Standard
13460 A typical template looks like this:
13463 \begin_layout LyX-Code
13467 \begin_layout LyX-Code
13468 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
13471 \begin_layout LyX-Code
13475 \begin_layout LyX-Code
13479 \begin_layout LyX-Code
13483 \begin_layout LyX-Code
13487 \begin_layout LyX-Code
13491 \begin_layout LyX-Code
13492 AutomaticProduction true
13495 \begin_layout LyX-Code
13499 \begin_layout LyX-Code
13503 \begin_layout LyX-Code
13507 \begin_layout LyX-Code
13508 TransformCommand Rotate RotationLatexCommand
13511 \begin_layout LyX-Code
13512 TransformCommand Resize ResizeLatexCommand
13515 \begin_layout LyX-Code
13516 Product "$$RotateFront$$ResizeFront
13519 \begin_layout LyX-Code
13524 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
13527 \begin_layout LyX-Code
13528 $$ResizeBack$$RotateBack"
13531 \begin_layout LyX-Code
13535 \begin_layout LyX-Code
13536 UpdateResult "$$AbsPath$$Basename.pstex_t"
13539 \begin_layout LyX-Code
13540 Requirement "graphicx"
13543 \begin_layout LyX-Code
13544 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
13547 \begin_layout LyX-Code
13548 ReferencedFile latex "$$AbsPath$$Basename.eps"
13551 \begin_layout LyX-Code
13552 ReferencedFile dvi "$$AbsPath$$Basename.eps"
13555 \begin_layout LyX-Code
13559 \begin_layout LyX-Code
13563 \begin_layout LyX-Code
13564 TransformCommand Rotate RotationLatexCommand
13567 \begin_layout LyX-Code
13568 TransformCommand Resize ResizeLatexCommand
13571 \begin_layout LyX-Code
13572 Product "$$RotateFront$$ResizeFront
13575 \begin_layout LyX-Code
13580 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
13583 \begin_layout LyX-Code
13584 $$ResizeBack$$RotateBack"
13587 \begin_layout LyX-Code
13588 UpdateFormat pdftex
13591 \begin_layout LyX-Code
13592 UpdateResult "$$AbsPath$$Basename.pdftex_t"
13595 \begin_layout LyX-Code
13596 Requirement "graphicx"
13599 \begin_layout LyX-Code
13600 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
13603 \begin_layout LyX-Code
13604 ReferencedFile latex "$$AbsPath$$Basename.pdf"
13607 \begin_layout LyX-Code
13611 \begin_layout LyX-Code
13615 \begin_layout LyX-Code
13616 Product "$$Contents(
13618 "$$AbsPath$$Basename.asc
13623 \begin_layout LyX-Code
13624 UpdateFormat asciixfig
13627 \begin_layout LyX-Code
13628 UpdateResult "$$AbsPath$$Basename.asc"
13631 \begin_layout LyX-Code
13635 \begin_layout LyX-Code
13639 \begin_layout LyX-Code
13640 Product "<graphic fileref=
13642 "$$AbsOrRelPathMaster$$Basename.eps
13647 \begin_layout LyX-Code
13651 \begin_layout LyX-Code
13655 \begin_layout LyX-Code
13656 UpdateResult "$$AbsPath$$Basename.eps"
13659 \begin_layout LyX-Code
13660 ReferencedFile docbook "$$AbsPath$$Basename.eps"
13663 \begin_layout LyX-Code
13664 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
13667 \begin_layout LyX-Code
13671 \begin_layout LyX-Code
13672 Product "[XFig: $$FName]"
13675 \begin_layout LyX-Code
13679 \begin_layout LyX-Code
13683 \begin_layout Standard
13684 As you can see, the template is enclosed in
13685 \begin_inset Flex CharStyle:Code
13688 \begin_layout Plain Layout
13694 \SpecialChar \ldots{}
13696 \begin_inset Flex CharStyle:Code
13699 \begin_layout Plain Layout
13706 It contains a header specifying some general settings and, for each supported
13707 primary document file format, a section
13708 \begin_inset Flex CharStyle:Code
13711 \begin_layout Plain Layout
13717 \SpecialChar \ldots{}
13719 \begin_inset Flex CharStyle:Code
13722 \begin_layout Plain Layout
13731 \begin_layout Subsection
13732 The template header
13735 \begin_layout Description
13736 \begin_inset Flex CharStyle:Code
13739 \begin_layout Plain Layout
13740 AutomaticProduction
13741 \begin_inset space ~
13749 Whether the file represented by the template must be generated by LyX.
13750 This command must occur exactly once.
13753 \begin_layout Description
13754 \begin_inset Flex CharStyle:Code
13757 \begin_layout Plain Layout
13759 \begin_inset space ~
13767 A glob pattern that is used in the file dialog to filter out the desired
13769 If there is more than one possible file extension (e.g.
13770 \begin_inset space ~
13774 \begin_inset Flex CharStyle:Code
13777 \begin_layout Plain Layout
13784 \begin_inset Flex CharStyle:Code
13787 \begin_layout Plain Layout
13793 ), use something like
13794 \begin_inset Flex CharStyle:Code
13797 \begin_layout Plain Layout
13804 This command must occur exactly once.
13807 \begin_layout Description
13808 \begin_inset Flex CharStyle:Code
13811 \begin_layout Plain Layout
13813 \begin_inset space ~
13821 The text that is displayed on the button.
13822 This command must occur exactly once.
13825 \begin_layout Description
13826 \begin_inset Flex CharStyle:Code
13829 \begin_layout Plain Layout
13831 \begin_inset space ~
13835 \begin_inset space ~
13843 The help text that is used in the External dialog.
13844 Provide enough information to explain to the user just what the template
13845 can provide him with.
13846 This command must occur exactly once.
13849 \begin_layout Description
13850 \begin_inset Flex CharStyle:Code
13853 \begin_layout Plain Layout
13855 \begin_inset space ~
13863 The file format of the original file.
13864 This must be the name of a format that is known to LyX (see section
13865 \begin_inset CommandInset ref
13867 reference "sub:Formats"
13873 \begin_inset Quotes eld
13877 \begin_inset Flex CharStyle:Code
13880 \begin_layout Plain Layout
13887 \begin_inset Quotes erd
13890 if the template can handle original files of more than one format.
13891 LyX will attempt to interrogate the file itself in order to deduce its
13892 format in this case.
13893 This command must occur exactly once.
13896 \begin_layout Description
13897 \begin_inset Flex CharStyle:Code
13900 \begin_layout Plain Layout
13902 \begin_inset space ~
13910 A unique name for the template.
13911 It must not contain substitution macros (see below).
13914 \begin_layout Description
13915 \begin_inset Flex CharStyle:Code
13918 \begin_layout Plain Layout
13920 \begin_inset space ~
13923 Rotate|Resize|Clip|Extra
13928 This command specifies which transformations are supported by this template.
13929 It may occur zero or more times.
13930 This command enables the corresponding tabs in the external dialog.
13932 \begin_inset Flex CharStyle:Code
13935 \begin_layout Plain Layout
13941 command must have either a corresponding
13942 \begin_inset Flex CharStyle:Code
13945 \begin_layout Plain Layout
13952 \begin_inset Flex CharStyle:Code
13955 \begin_layout Plain Layout
13962 \begin_inset Flex CharStyle:Code
13965 \begin_layout Plain Layout
13972 Otherwise the transformation will not be supported by that format.
13975 \begin_layout Subsection
13979 \begin_layout Description
13980 \begin_inset Flex CharStyle:Code
13983 \begin_layout Plain Layout
13985 \begin_inset space ~
13988 LaTeX|PDFLaTeX|PlainText|DocBook
13993 The primary document file format that this format definition is for.
13994 Not every template has a sensible representation in all document file formats.
13995 Please define nevertheless a
13996 \begin_inset Flex CharStyle:Code
13999 \begin_layout Plain Layout
14005 section for all formats.
14006 Use a dummy text when no representation is available.
14007 Then you can at least see a reference to the external material in the exported
14011 \begin_layout Description
14012 \begin_inset Flex CharStyle:Code
14015 \begin_layout Plain Layout
14017 \begin_inset space ~
14021 \begin_inset space ~
14029 This command defines an additional macro
14030 \begin_inset Flex CharStyle:Code
14033 \begin_layout Plain Layout
14039 for substitution in
14040 \begin_inset Flex CharStyle:Code
14043 \begin_layout Plain Layout
14051 \begin_inset Flex CharStyle:Code
14054 \begin_layout Plain Layout
14060 itself may contain substitution macros.
14061 The advantage over using
14062 \begin_inset Flex CharStyle:Code
14065 \begin_layout Plain Layout
14072 \begin_inset Flex CharStyle:Code
14075 \begin_layout Plain Layout
14081 is that the substituted value of
14082 \begin_inset Flex CharStyle:Code
14085 \begin_layout Plain Layout
14091 is sanitized so that it is a valid optional argument in the document format.
14092 This command may occur zero or more times.
14095 \begin_layout Description
14096 \begin_inset Flex CharStyle:Code
14099 \begin_layout Plain Layout
14101 \begin_inset space ~
14109 The text that is inserted in the exported document.
14110 This is actually the most important command and can be quite complex.
14111 This command must occur exactly once.
14114 \begin_layout Description
14115 \begin_inset Flex CharStyle:Code
14118 \begin_layout Plain Layout
14120 \begin_inset space ~
14128 This command specifies a preamble snippet that will be included in the
14130 It has to be defined using
14131 \begin_inset Flex CharStyle:Code
14134 \begin_layout Plain Layout
14140 \SpecialChar \ldots{}
14142 \begin_inset Flex CharStyle:Code
14145 \begin_layout Plain Layout
14152 This command may occur zero or more times.
14155 \begin_layout Description
14156 \begin_inset Flex CharStyle:Code
14159 \begin_layout Plain Layout
14161 \begin_inset space ~
14165 \begin_inset space ~
14173 This command denotes files that are created by the conversion process and
14174 are needed for a particular export format.
14175 If the filename is relative, it is interpreted relative to the master document.
14176 This command may be given zero or more times.
14179 \begin_layout Description
14180 \begin_inset Flex CharStyle:Code
14183 \begin_layout Plain Layout
14185 \begin_inset space ~
14193 The name of a required LaTeX package.
14194 The package is included via
14195 \begin_inset Flex CharStyle:Code
14198 \begin_layout Plain Layout
14206 in the LaTeX preamble.
14207 This command may occur zero or more times.
14210 \begin_layout Description
14211 \begin_inset Flex CharStyle:Code
14214 \begin_layout Plain Layout
14216 \begin_inset space ~
14220 \begin_inset space ~
14223 RotationLatexCommand
14228 This command specifies that the built in LaTeX command should be used for
14230 This command may occur once or not at all.
14233 \begin_layout Description
14234 \begin_inset Flex CharStyle:Code
14237 \begin_layout Plain Layout
14239 \begin_inset space ~
14243 \begin_inset space ~
14251 This command specifies that the built in LaTeX command should be used for
14253 This command may occur once or not at all.
14256 \begin_layout Description
14257 \begin_inset Flex CharStyle:Code
14260 \begin_layout Plain Layout
14262 \begin_inset space ~
14266 \begin_inset space ~
14269 RotationLatexOption
14274 This command specifies that rotation is done via an optional argument.
14275 This command may occur once or not at all.
14278 \begin_layout Description
14279 \begin_inset Flex CharStyle:Code
14282 \begin_layout Plain Layout
14284 \begin_inset space ~
14288 \begin_inset space ~
14296 This command specifies that resizing is done via an optional argument.
14297 This command may occur once or not at all.
14300 \begin_layout Description
14301 \begin_inset Flex CharStyle:Code
14304 \begin_layout Plain Layout
14306 \begin_inset space ~
14310 \begin_inset space ~
14318 This command specifies that clipping is done via an optional argument.
14319 This command may occur once or not at all.
14322 \begin_layout Description
14323 \begin_inset Flex CharStyle:Code
14326 \begin_layout Plain Layout
14328 \begin_inset space ~
14332 \begin_inset space ~
14340 This command specifies that an extra optional argument is used.
14341 This command may occur once or not at all.
14344 \begin_layout Description
14345 \begin_inset Flex CharStyle:Code
14348 \begin_layout Plain Layout
14350 \begin_inset space ~
14358 The file format of the converted file.
14359 This must be the name of a format that is known to LyX (see the
14360 \begin_inset Flex CharStyle:MenuItem
14363 \begin_layout Plain Layout
14368 ools\SpecialChar \menuseparator
14373 references:Conversion
14379 This command must occur exactly once.
14382 \begin_layout Description
14383 \begin_inset Flex CharStyle:Code
14386 \begin_layout Plain Layout
14388 \begin_inset space ~
14396 The file name of the converted file.
14397 The file name must be absolute.
14398 This command must occur exactly once.
14401 \begin_layout Subsection
14402 Preamble definitions
14405 \begin_layout Standard
14406 The external template configuration file may contain additional preamble
14407 definitions enclosed by
14408 \begin_inset Flex CharStyle:Code
14411 \begin_layout Plain Layout
14417 \SpecialChar \ldots{}
14419 \begin_inset Flex CharStyle:Code
14422 \begin_layout Plain Layout
14429 They can be used by the templates in the
14430 \begin_inset Flex CharStyle:Code
14433 \begin_layout Plain Layout
14442 \begin_layout Section
14443 The substitution mechanism
14446 \begin_layout Standard
14447 When the external material facility invokes an external program, it is done
14448 on the basis of a command defined in the template configuration file.
14449 These commands can contain various macros that are expanded before execution.
14450 Execution always take place in the directory of the containing document.
14453 \begin_layout Standard
14454 Also, whenever external material is to be displayed, the name will be produced
14455 by the substitution mechanism, and most other commands in the template
14456 definition support substitution as well.
14459 \begin_layout Standard
14460 The available macros are the following:
14463 \begin_layout Description
14464 \begin_inset Flex CharStyle:Code
14467 \begin_layout Plain Layout
14468 $$AbsOrRelPathMaster
14473 The file path, absolute or relative to the master LyX document.
14476 \begin_layout Description
14477 \begin_inset Flex CharStyle:Code
14480 \begin_layout Plain Layout
14481 $$AbsOrRelPathParent
14486 The file path, absolute or relative to the LyX document.
14489 \begin_layout Description
14490 \begin_inset Flex CharStyle:Code
14493 \begin_layout Plain Layout
14499 The absolute file path.
14502 \begin_layout Description
14503 \begin_inset Flex CharStyle:Code
14506 \begin_layout Plain Layout
14512 The filename without path and without the extension.
14515 \begin_layout Description
14516 \begin_inset Flex CharStyle:Code
14519 \begin_layout Plain Layout
14521 \begin_inset Quotes eld
14525 \begin_inset Quotes erd
14533 This macro will expand to the contents of the file with the name
14534 \begin_inset Flex CharStyle:Code
14537 \begin_layout Plain Layout
14546 \begin_layout Description
14547 \begin_inset Flex CharStyle:Code
14550 \begin_layout Plain Layout
14556 The file extension (including the dot).
14559 \begin_layout Description
14560 \begin_inset Flex CharStyle:Code
14563 \begin_layout Plain Layout
14569 The filename of the file specified in the external material dialog.
14570 This is either an absolute name, or it is relative to the LyX document.
14573 \begin_layout Description
14574 \begin_inset Flex CharStyle:Code
14577 \begin_layout Plain Layout
14584 \begin_inset Flex CharStyle:Code
14587 \begin_layout Plain Layout
14593 (absolute name or relative to the LyX document).
14596 \begin_layout Description
14597 \begin_inset Flex CharStyle:Code
14600 \begin_layout Plain Layout
14606 The file path, relative to the master LyX document.
14609 \begin_layout Description
14610 \begin_inset Flex CharStyle:Code
14613 \begin_layout Plain Layout
14619 The file path, relative to the LyX document.
14622 \begin_layout Description
14623 \begin_inset Flex CharStyle:Code
14626 \begin_layout Plain Layout
14632 This macro will expand to the absolute path of the system directory.
14633 This is typically used to point to the various helper scripts that are
14637 \begin_layout Description
14638 \begin_inset Flex CharStyle:Code
14641 \begin_layout Plain Layout
14647 A name and full path to a temporary file which will be automatically deleted
14648 whenever the containing document is closed, or the external material insertion
14652 \begin_layout Standard
14653 All path macros contain a trailing directory separator, so you can construct
14655 the absolute filename with
14656 \begin_inset Flex CharStyle:Code
14659 \begin_layout Plain Layout
14660 $$AbsPath$$Basename$$Extension
14668 \begin_layout Standard
14669 The macros above are substituted in all commands unless otherwise noted.
14671 \begin_inset Flex CharStyle:Code
14674 \begin_layout Plain Layout
14680 supports additionally the following substitutions if they are enabled by
14682 \begin_inset Flex CharStyle:Code
14685 \begin_layout Plain Layout
14692 \begin_inset Flex CharStyle:Code
14695 \begin_layout Plain Layout
14704 \begin_layout Description
14705 \begin_inset Flex CharStyle:Code
14708 \begin_layout Plain Layout
14714 The front part of the resize command.
14717 \begin_layout Description
14718 \begin_inset Flex CharStyle:Code
14721 \begin_layout Plain Layout
14727 The back part of the resize command.
14730 \begin_layout Description
14731 \begin_inset Flex CharStyle:Code
14734 \begin_layout Plain Layout
14740 The front part of the rotation command.
14743 \begin_layout Description
14744 \begin_inset Flex CharStyle:Code
14747 \begin_layout Plain Layout
14753 The back part of the rotation command.
14756 \begin_layout Standard
14757 The value string of the
14758 \begin_inset Flex CharStyle:Code
14761 \begin_layout Plain Layout
14767 command supports additionally the following substitutions if they are enabled
14769 \begin_inset Flex CharStyle:Code
14772 \begin_layout Plain Layout
14779 \begin_inset Flex CharStyle:Code
14782 \begin_layout Plain Layout
14791 \begin_layout Description
14792 \begin_inset Flex CharStyle:Code
14795 \begin_layout Plain Layout
14804 \begin_layout Description
14805 \begin_inset Flex CharStyle:Code
14808 \begin_layout Plain Layout
14817 \begin_layout Description
14818 \begin_inset Flex CharStyle:Code
14821 \begin_layout Plain Layout
14830 \begin_layout Description
14831 \begin_inset Flex CharStyle:Code
14834 \begin_layout Plain Layout
14840 The rotation option.
14843 \begin_layout Standard
14844 You may ask why there are so many path macros.
14845 There are mainly two reasons:
14848 \begin_layout Enumerate
14849 Relative and absolute file names should remain relative or absolute, respectivel
14851 Users may have reasons to prefer either form.
14852 Relative names are useful for portable documents that should work on different
14853 machines, for example.
14854 Absolute names may be required by some programs.
14857 \begin_layout Enumerate
14858 LaTeX treats relative file names differently than LyX and other programs
14859 in nested included files.
14860 For LyX, a relative file name is always relative to the document that contains
14862 For LaTeX, it is always relative to the master document.
14863 These two definitions are identical if you have only one document, but
14864 differ if you have a master document that includes part documents.
14865 That means that relative filenames must be transformed when presented to
14867 Fortunately LyX does this automatically for you if you choose the right
14871 \begin_layout Standard
14872 So which path macro should be used in new template definitions? The rule
14876 \begin_layout Itemize
14878 \begin_inset Flex CharStyle:Code
14881 \begin_layout Plain Layout
14887 if an absolute path is required.
14890 \begin_layout Itemize
14892 \begin_inset Flex CharStyle:Code
14895 \begin_layout Plain Layout
14896 $$AbsOrRelPathMaster
14901 if the substituted string is some kind of LaTeX input.
14904 \begin_layout Itemize
14906 \begin_inset Flex CharStyle:Code
14909 \begin_layout Plain Layout
14910 $$AbsOrRelPathParent
14915 in order to preserve the user's choice.
14918 \begin_layout Standard
14919 There are special cases where this rule does not work and e.g.
14920 \begin_inset space ~
14923 relative names are needed, but normally it will work just fine.
14924 One example for such a case is the command
14925 \begin_inset Flex CharStyle:Code
14928 \begin_layout Plain Layout
14929 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14934 in the XFig template above: We can't use the absolute name because the
14936 \begin_inset Flex CharStyle:Code
14939 \begin_layout Plain Layout
14945 files needs the relative name in order to rewrite the file content.
14948 \begin_layout Section
14949 \begin_inset CommandInset label
14951 name "sec:Security-discussion"
14955 Security discussion
14958 \begin_layout Standard
14959 \begin_inset Note Note
14962 \begin_layout Plain Layout
14963 This section is outdated
14968 The external material feature interfaces with a lot of external programs
14969 and does so automatically, so we have to consider the security implications
14971 In particular, since you have the option of including your own filenames
14972 and/or parameter strings and those are expanded into a command, it seems
14973 that it would be possible to create a malicious document which executes
14974 arbitrary commands when a user views or prints the document.
14975 This is something we definately want to avoid.
14978 \begin_layout Standard
14979 However, since the external program commands are specified in the template
14980 configuration file only, there are no security issues if LyX is properly
14981 configured with safe templates only.
14982 This is so because the external programs are invoked with the
14983 \begin_inset Flex CharStyle:Code
14986 \begin_layout Plain Layout
14992 -system call rather than the
14993 \begin_inset Flex CharStyle:Code
14996 \begin_layout Plain Layout
15002 system-call, so it's not possible to execute arbitrary commands from the
15003 filename or parameter section via the shell.
15006 \begin_layout Standard
15007 This also implies that you are restricted in what command strings you can
15008 use in the external material templates.
15009 In particular, pipes and redirection are not readily available.
15010 This has to be so if LyX should remain safe.
15011 If you want to use some of the shell features, you should write a safe
15012 script to do this in a controlled manner, and then invoke the script from
15013 the command string.
15015 \begin_inset Flex CharStyle:Code
15018 \begin_layout Plain Layout
15024 directory of the LyX installation, you can find a safe wrapper script
15025 \begin_inset Flex CharStyle:Code
15028 \begin_layout Plain Layout
15029 general_command_wrapper.py
15034 that supports redirection of input and output.
15035 That can serve as an example for how to write safe template scripts.
15036 For a more advanced example that uses
15037 \begin_inset Flex CharStyle:Code
15040 \begin_layout Plain Layout
15046 and friends, take a look at the
15047 \begin_inset Flex CharStyle:Code
15050 \begin_layout Plain Layout
15059 \begin_layout Standard
15060 It is possible to design a template that interacts directly with the shell,
15061 but since this would allow a malicious user to execute arbitrary commands
15062 by writing clever filenames and/or parameters, we generally recommend that
15063 you only use safe scripts that work with the
15064 \begin_inset Flex CharStyle:Code
15067 \begin_layout Plain Layout
15073 system call in a controlled manner.
15074 Of course, for use in a controlled environment, it can be tempting to just
15075 fall back to use ordinary shell scripts.
15076 If you do so, be aware that you
15080 provide an easily exploitable security hole in your system.
15081 Of course it stands to reason that such unsafe templates will never be
15082 included in the standard LyX distribution, although we do encourage people
15083 to submit new templates in the open source tradition.
15084 But LyX as shipped from the official distribution channels will never have
15088 \begin_layout Standard
15089 Including external material provides a lot of power, and you have to be
15090 careful not to introduce security hazards with this power.
15091 A subtle error in a single line in an innocent looking script can open
15092 the door to huge security problems.
15093 So if you do not fully understand the issues, we recommend that you consult
15094 a knowledgable security professional or the LyX development team if you
15095 have any questions about whether a given template is safe or not.
15096 And do this before you use it in an uncontrolled environment.
15099 \begin_layout Chapter
15103 \begin_layout Section
15107 \begin_layout Standard
15108 The LyX server is a method implemented in LyX that will enable other programs
15109 to talk to LyX, invoke LyX commands, and retrieve information about the
15110 LyX internal state.
15111 This is only intended for advanced users, but they should find it useful.
15112 Please note that, at present,
15114 the server does not work on Windows
15120 \begin_layout Plain Layout
15121 There is no principled reason it cannot do so.
15122 But none of the developers on Windows® have yet implemented this functionality
15131 \begin_layout Section
15132 Starting the LyX Server
15135 \begin_layout Standard
15136 The LyX server works through the use of a pair of named pipes.
15137 These are usually located in
15138 \begin_inset Flex CharStyle:Code
15141 \begin_layout Plain Layout
15148 \begin_inset Quotes eld
15152 \begin_inset Flex CharStyle:Code
15155 \begin_layout Plain Layout
15162 \begin_inset Quotes erd
15166 \begin_inset Quotes eld
15170 \begin_inset Flex CharStyle:Code
15173 \begin_layout Plain Layout
15180 \begin_inset Quotes erd
15184 External programs write into
15185 \begin_inset Flex CharStyle:Code
15188 \begin_layout Plain Layout
15194 and read back data from
15195 \begin_inset Flex CharStyle:Code
15198 \begin_layout Plain Layout
15205 The stem of the pipe names can be defined in the
15206 \begin_inset Flex CharStyle:MenuItem
15209 \begin_layout Plain Layout
15214 ools\SpecialChar \menuseparator
15224 dialog, for example
15225 \begin_inset Flex CharStyle:Code
15228 \begin_layout Plain Layout
15229 "/home/myhome/.lyxpipe"
15237 \begin_layout Standard
15239 \begin_inset Flex CharStyle:Code
15242 \begin_layout Plain Layout
15249 \begin_inset Flex CharStyle:Code
15252 \begin_layout Plain Layout
15258 ' to create the pipes.
15259 The above setting also has the effect of activating the LyX server.
15260 If one of the pipes already exists, LyX will assume that another LyX process
15261 is already running and will not start the server.
15262 To have several LyX processes with servers at the same time, you have to
15263 change the configuration between the start of the programs.
15266 \begin_layout Standard
15267 If you are developing a client program, you might find it useful to enable
15268 debugging information from the LyX server.
15269 Do this by starting LyX as lyx -dbg lyxserver.
15272 \begin_layout Standard
15273 Warning: if LyX crashes, it may not manage to remove the pipes; in this
15274 case you must remove them manually.
15275 If LyX starts and the pipes exist already, it will not start any server.
15278 \begin_layout Standard
15279 Other than this, there are a few points to consider:
15282 \begin_layout Itemize
15283 Both server and clients must run on UNIX or OS/2 machines.
15284 Communications between LyX on UNIX and clients on OS/2 or vice versa is
15285 not possible right now.
15288 \begin_layout Itemize
15289 On OS/2, only one client can connect to LyXServer at a time.
15292 \begin_layout Itemize
15293 On OS/2, clients must open inpipe with
15294 \begin_inset Flex CharStyle:Code
15297 \begin_layout Plain Layout
15306 \begin_layout Standard
15310 \begin_layout Standard
15311 You can find a complete example client written in C in the source distribution
15313 \begin_inset Flex CharStyle:Code
15316 \begin_layout Plain Layout
15317 development/lyxserver/server_monitor.c
15325 \begin_layout Section
15326 Normal communication
15329 \begin_layout Standard
15330 To issue a LyX call, the client writes a line of ASCII text into the input
15332 This line has the following format:
15335 \begin_layout Quote
15349 \begin_layout Description
15354 is a name that the client can choose arbitrarily.
15355 Its only use is that LyX will echo it if it sends an answer---so a client
15356 can dispatch results from different requesters.
15359 \begin_layout Description
15364 is the function you want LyX to perform.
15365 It is the same as the commands you'd use in the minibuffer.
15368 \begin_layout Description
15373 is an optional argument which is meaningful only to some functions (for
15375 \begin_inset Quotes eld
15379 \begin_inset Quotes erd
15382 which will insert the argument as text at the cursor position.)
15385 \begin_layout Standard
15386 The answer from LyX will arrive in the output pipe and be of the form
15389 \begin_layout Quote
15403 \begin_layout Standard
15412 are just echoed from the command request, while
15416 is more or less useful information filled according to how the command
15417 execution worked out.
15418 Some commands will return information about the internal state of LyX,
15420 \begin_inset Quotes eld
15424 \begin_inset Quotes erd
15427 , while other will return an empty data-response.
15428 This means that the command execution went fine.
15431 \begin_layout Standard
15432 In case of errors, the response from LyX will have this form
15435 \begin_layout Quote
15449 \begin_layout Standard
15454 should contain an explanation of why the command failed.
15457 \begin_layout Standard
15461 \begin_layout LyX-Code
15462 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
15465 \begin_layout LyX-Code
15466 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
15467 \begin_inset Newline newline
15470 read a <~/.lyxpipe.out
15471 \begin_inset Newline newline
15477 \begin_layout Section
15481 \begin_layout Standard
15482 LyX can notify clients of events going on asynchronously.
15483 Currently it will only do this if the user binds a key sequence with the
15485 \begin_inset Quotes eld
15489 \begin_inset Quotes erd
15493 The format of the string LyX sends is as follows:
15496 \begin_layout Quote
15497 \begin_inset Flex CharStyle:Code
15500 \begin_layout Plain Layout
15511 \begin_layout Standard
15516 is the printed representation of the key sequence that was actually typed
15520 \begin_layout Standard
15521 This mechanism can be used to extend LyX's command set and implement macros:
15522 bind some key sequence to
15523 \begin_inset Quotes eld
15527 \begin_inset Quotes erd
15530 , start a client that listens on the out pipe, dispatches the command according
15531 to the sequence and starts a function that may use LyX calls and LyX requests
15532 to issue a command or a series of commands to LyX.
15535 \begin_layout Section
15536 The simple LyX Server Protocol
15539 \begin_layout Standard
15540 LyX implements a simple protocol that can be used for session management.
15541 All messages are of the form
15544 \begin_layout Quote
15554 \begin_layout Standard
15560 \begin_inset Quotes eld
15564 \begin_inset Quotes erd
15568 \begin_inset Quotes eld
15572 \begin_inset Quotes erd
15577 \begin_inset Quotes eld
15581 \begin_inset Quotes erd
15584 is received from a client, LyX will report back to inform the client that
15585 it's listening to it's messages, while
15586 \begin_inset Quotes eld
15590 \begin_inset Quotes erd
15593 sent from LyX will inform clients that LyX is closing.