1 #LyX 1.6.0rc3 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 package for preparing slides or
5477 viewgraphs for overhead projectors.
5478 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5479 a user interface for that.
5480 For example on MiKTeX you start its program
5481 \begin_inset Quotes eld
5485 \begin_inset Quotes erd
5488 to get a list of available packages.
5489 To install one, right click on it or use the installing toolbar button.
5490 When the package you want to install is not in the list, but you have it
5492 \begin_inset Flex CharStyle:Code
5495 \begin_layout Plain Layout
5502 \begin_inset Flex CharStyle:Code
5505 \begin_layout Plain Layout
5511 -file, then copy these files to a subfolder of your LaTeX distribution,
5512 for example to the folder
5521 Then update the file name database of your LaTeX-distribution.
5522 For example on MiKTeX this is done by pressing the button
5525 \begin_inset space ~
5530 that you find in MiKTeX's
5531 \begin_inset Quotes eld
5535 \begin_inset Quotes erd
5539 In both cases you need afterwards to reconfigure LyX using the menu
5540 \begin_inset Flex CharStyle:MenuItem
5543 \begin_layout Plain Layout
5544 Tools\SpecialChar \menuseparator
5550 and then to restart LyX.
5553 \begin_layout Standard
5554 If your LaTeX distribution doesn't provide a user interface, then you can
5555 follow these steps by using a UNIX/Linux console.
5558 \begin_layout Enumerate
5559 Get the package from
5560 \begin_inset CommandInset href
5563 target "http://www.ctan.org/"
5570 \begin_layout Enumerate
5571 You can install this package in several different places.
5572 If you want it to be available for all users on your system, then you should
5573 install it in your `local' TeX tree; if you want (or need) it to be available
5574 just for you, then you can install it in your own `user' TeX tree.
5575 Where these should be created, if they do not already exist, depends upon
5576 the details of your system.
5577 To find out, look in the file
5578 \begin_inset Flex CharStyle:Code
5581 \begin_layout Plain Layout
5591 \begin_layout Plain Layout
5592 This usually lives in the directory
5593 \begin_inset Flex CharStyle:Code
5596 \begin_layout Plain Layout
5602 , though you can run
5603 \begin_inset Flex CharStyle:Code
5606 \begin_layout Plain Layout
5617 The location of the `local' TeX tree is defined by
5618 \begin_inset Flex CharStyle:Code
5621 \begin_layout Plain Layout
5627 ; this is usually somewhere like
5628 \begin_inset Flex CharStyle:Code
5631 \begin_layout Plain Layout
5632 /usr/local/share/texmf/
5638 The `user' TeX tree is defined by
5639 \begin_inset Flex CharStyle:Code
5642 \begin_layout Plain Layout
5649 \begin_inset Flex CharStyle:Code
5652 \begin_layout Plain Layout
5659 (If these variables are not predefined, you can define them.) You'll probably
5660 need root permissions to create or modify the `local' tree; but your `user'
5661 tree shouldn't have such limitations.
5664 \begin_layout Enumerate
5666 \begin_inset Flex CharStyle:Code
5669 \begin_layout Plain Layout
5676 \begin_inset Flex CharStyle:Code
5679 \begin_layout Plain Layout
5686 \begin_inset Flex CharStyle:Code
5689 \begin_layout Plain Layout
5696 \begin_inset Newline newline
5700 \begin_inset Flex CharStyle:Code
5703 \begin_layout Plain Layout
5704 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5710 \begin_inset Newline newline
5713 But, again, most of this will
5714 \begin_inset Quotes eld
5718 \begin_inset Quotes erd
5724 \begin_layout Enumerate
5729 \begin_layout Plain Layout
5730 We'll assume henceforth that you're defining `local' TeX tree.
5731 If you're defining a user tree, just adjust as necessary.
5737 You must follow the directory structure of your existing
5738 \begin_inset Flex CharStyle:Code
5741 \begin_layout Plain Layout
5747 directory, which will be found at
5748 \begin_inset Flex CharStyle:Code
5751 \begin_layout Plain Layout
5758 For example, latex packages should go under
5759 \begin_inset Flex CharStyle:Code
5762 \begin_layout Plain Layout
5763 $TEXMFLOCAL/tex/latex/
5771 \begin_layout Enumerate
5772 Install the package.
5773 For example, you would unpack the FoilTeX tarball and copy it to
5774 \begin_inset Flex CharStyle:Code
5777 \begin_layout Plain Layout
5778 $TEXMFLOCAL/tex/latex/foiltex
5785 \begin_inset Flex CharStyle:Code
5788 \begin_layout Plain Layout
5794 directory contains various files.
5797 \begin_layout Enumerate
5799 \begin_inset Flex CharStyle:Code
5802 \begin_layout Plain Layout
5810 \begin_inset Flex CharStyle:Code
5813 \begin_layout Plain Layout
5822 \begin_layout Standard
5823 Your package is now installed and available to LaTeX.
5824 To make it available to LyX, you need to create a Layout file, if one is
5825 not already available.
5826 (See the next section.) Once you have a layout file, you need only reconfigure
5828 \begin_inset Flex CharStyle:MenuItem
5831 \begin_layout Plain Layout
5832 Tools\SpecialChar \menuseparator
5838 ) and then restart LyX.
5839 You should then see your new package---for example
5840 \begin_inset Flex CharStyle:MenuItem
5843 \begin_layout Plain Layout
5850 \begin_inset Flex CharStyle:MenuItem
5853 \begin_layout Plain Layout
5854 Document\SpecialChar \menuseparator
5861 \begin_inset Flex CharStyle:MenuItem
5864 \begin_layout Plain Layout
5874 \begin_layout Section
5878 \begin_layout Standard
5879 This section describes how to write and install your own LyX layout files
5880 and walks through the
5881 \begin_inset Flex CharStyle:Code
5884 \begin_layout Plain Layout
5890 text class format as an example.
5892 \begin_inset Flex CharStyle:Code
5895 \begin_layout Plain Layout
5901 files describe what paragraph and character styles are available for a
5902 given document class and how LyX should display them.
5903 We try to provide a thorough description of the process here; however,
5904 there are so many different types of documents supported by LaTeX classes
5905 that we can't hope to cover every different possibility or problem you
5907 (The LyX users' list is frequented by people with lots of experience with
5908 layout design who are willing to share what they've learned.)
5911 \begin_layout Standard
5912 As you prepare to write a new layout, it is extremely helpful to look at
5913 the example layouts distributed with LyX.
5914 If you use a nice LaTeX document class that might be of interest for others,
5915 too, and have a nice corresponding LyX layout, feel free to contribute
5916 the stuff to us, so we may put it into the distribution.
5918 \begin_inset CommandInset href
5920 name "section on the LyX wiki"
5921 target "http://wiki.lyx.org/Layouts/Layouts"
5925 for this kind of material.
5928 \begin_layout Standard
5929 All the tags described in this chapter are case-insensitive; this means
5931 \begin_inset Flex CharStyle:Code
5934 \begin_layout Plain Layout
5941 \begin_inset Flex CharStyle:Code
5944 \begin_layout Plain Layout
5951 \begin_inset Flex CharStyle:Code
5954 \begin_layout Plain Layout
5960 are really the same command.
5961 The possible values are printed in brackets after the feature's name.
5962 The default value if a feature isn't specified inside a text class-description
5964 \begin_inset Flex CharStyle:Code
5967 \begin_layout Plain Layout
5976 If the argument has a datatype like
5977 \begin_inset Quotes eld
5981 \begin_inset Quotes erd
5985 \begin_inset Quotes eld
5989 \begin_inset Quotes erd
5992 , the default is shown like this:
5993 \begin_inset Flex CharStyle:Code
5996 \begin_layout Plain Layout
6007 \begin_layout Subsection
6011 \begin_layout Standard
6012 Similar to layout files, and new with LyX 1.6, are layout
6017 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6018 some modules---such as the Endnotes module---provide support for just such
6020 In a sense, layout modules are similar to included files---files like
6021 \begin_inset Flex CharStyle:Code
6024 \begin_layout Plain Layout
6030 ---in that modules are not specific to a given document layout but may be
6031 used with many different layouts.
6032 The difference is that using a layout module does not require editing the
6034 Rather, modules are selected in the
6035 \begin_inset Flex CharStyle:MenuItem
6038 \begin_layout Plain Layout
6039 Document\SpecialChar \menuseparator
6048 \begin_layout Standard
6049 Building modules is the easiest way to get started with layout editing,
6050 since it can be as simple as adding a single new paragraph or flex inset.
6051 But modules may, in principle, contain anything a layout file can contain.
6054 \begin_layout Standard
6055 A module must begin with a line like the following:
6058 \begin_layout LyX-Code
6061 DeclareLyXModule[endnotes.sty]{Endnotes}
6064 \begin_layout Standard
6065 The argument in square brackets is optional: It declares any LaTeX packages
6066 on which the module depends.
6067 The mandatory argument, in curly brackets, is the name of the module, as
6069 \begin_inset Flex CharStyle:MenuItem
6072 \begin_layout Plain Layout
6073 Document\SpecialChar \menuseparator
6083 \begin_layout Standard
6084 The module declaration should then be followed by lines like the following:
6087 \begin_layout LyX-Code
6091 \begin_layout LyX-Code
6092 #Adds an endnote command, in addition to footnotes.
6096 \begin_layout LyX-Code
6097 #You will need to add
6099 theendnotes in ERT where you
6102 \begin_layout LyX-Code
6103 #want the endnotes to appear.
6107 \begin_layout LyX-Code
6111 \begin_layout LyX-Code
6112 #Requires: somemodule | othermodule
6115 \begin_layout LyX-Code
6116 #Excludes: badmodule
6119 \begin_layout Standard
6120 The description is used in
6121 \begin_inset Flex CharStyle:MenuItem
6124 \begin_layout Plain Layout
6125 Document\SpecialChar \menuseparator
6131 to provide the user with information about what the module does.
6133 \begin_inset Flex CharStyle:Code
6136 \begin_layout Plain Layout
6142 line is used to identify other modules with which this one must be used;
6144 \begin_inset Flex CharStyle:Code
6147 \begin_layout Plain Layout
6153 line is used to identify modules with which this one may not be used.
6154 Both are optional, and, as shown, multiple modules should be separated
6155 with the pipe symbol: |.
6156 Note that the required modules are treated disjunctively:
6160 of the required modules must be used.
6165 excluded module may be used.
6166 Note that modules are identified here by their
6170 without the .module extension.
6172 \begin_inset Flex CharStyle:Code
6175 \begin_layout Plain Layout
6182 \begin_inset Flex CharStyle:Code
6185 \begin_layout Plain Layout
6194 \begin_layout Standard
6195 After creating a new module, you will need to reconfigure and then restart
6196 LyX for the module to appear in the menu.
6197 However, changes you make to the module will be seen immediately, if you
6199 \begin_inset Flex CharStyle:MenuItem
6202 \begin_layout Plain Layout
6203 Document\SpecialChar \menuseparator
6209 , highlight something, and then hit
6210 \begin_inset Quotes eld
6214 \begin_inset Quotes erd
6220 It is strongly recommended that you save your work before doing so
6225 it is strongly recommended that you not attempt to edit modules while simultaneo
6226 usly working on documents
6229 Though of course the developers strive to keep LyX stable in such situations,
6230 syntax errors and the like in your module file could cause strange behavior.
6233 \begin_layout Subsection
6234 Supporting new document classes
6237 \begin_layout Standard
6238 There are two situations you are likely to encounter when wanting to support
6239 a new LaTeX document class, involving LaTeX2e class (
6240 \begin_inset Flex CharStyle:Code
6243 \begin_layout Plain Layout
6250 \begin_inset Flex CharStyle:Code
6253 \begin_layout Plain Layout
6260 Supporting a style file is usually fairly easy.
6261 Supporting a new document class is a bit harder.
6264 \begin_layout Subsection
6266 \begin_inset Flex CharStyle:MenuItem
6269 \begin_layout Plain Layout
6278 \begin_layout Standard
6279 If your new document class is provided as a style file that is used in conjuncti
6280 on with an existing, supported document class---for the sake of the example,
6281 we'll assume that the style file is called
6282 \begin_inset Flex CharStyle:MenuItem
6285 \begin_layout Plain Layout
6291 and it is meant to be used with
6292 \begin_inset Flex CharStyle:MenuItem
6295 \begin_layout Plain Layout
6301 , which is a standard class---start by copying the existing class's layout
6302 file into your local directory:
6305 \begin_layout LyX-Code
6306 cp report.layout ~/.lyx/layouts/myclass.layout
6309 \begin_layout Standard
6311 \begin_inset Flex CharStyle:Code
6314 \begin_layout Plain Layout
6320 and change the line:
6323 \begin_layout LyX-Code
6326 DeclareLaTeXClass{report}
6329 \begin_layout Standard
6333 \begin_layout LyX-Code
6336 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6339 \begin_layout Standard
6343 \begin_layout LyX-Code
6345 \begin_inset Newline newline
6351 \begin_inset Newline newline
6357 \begin_layout Standard
6358 near the top of the file.
6361 \begin_layout Standard
6362 Start LyX and select
6363 \begin_inset Flex CharStyle:MenuItem
6366 \begin_layout Plain Layout
6371 ools\SpecialChar \menuseparator
6382 Then restart LyX and try creating a new document.
6384 \begin_inset Flex CharStyle:MenuItem
6387 \begin_layout Plain Layout
6393 " as a document class option in the
6394 \begin_inset Flex CharStyle:MenuItem
6397 \begin_layout Plain Layout
6402 ocument\SpecialChar \menuseparator
6413 It is likely that some of the sectioning commands and such in your new
6414 class will work differently from how they worked in the base class---
6415 \begin_inset Flex CharStyle:Code
6418 \begin_layout Plain Layout
6424 in this example---so you can fiddle around with the settings for the different
6425 sections if you wish.
6428 \begin_layout Subsection
6430 \begin_inset Flex CharStyle:MenuItem
6433 \begin_layout Plain Layout
6442 \begin_layout Standard
6443 There are two possibilities here.
6444 One is that the class file is itself based upon an existing document class.
6445 For example, many thesis classes are based upon
6446 \begin_inset Flex CharStyle:MenuItem
6449 \begin_layout Plain Layout
6456 To see whether yours is, look for a line like
6459 \begin_layout LyX-Code
6465 \begin_layout Standard
6467 If so, then you may proceed largely as in the previous section, though
6468 the DeclareLaTeXClass line will be different.
6469 If your new class is thesis, and it is based upon book, then the line should
6474 \begin_layout Plain Layout
6475 And it will be easiest if you save the file to
6476 \begin_inset Flex CharStyle:Code
6479 \begin_layout Plain Layout
6485 : LyX assumes that the document class has the same name as the layout file.
6494 \begin_layout LyX-Code
6497 DeclareLaTeXClass[thesis,book]{thesis}
6500 \begin_layout Standard
6501 If, on the other hand, the new class is not based upon an existing class,
6502 you will probably have to
6503 \begin_inset Quotes eld
6507 \begin_inset Quotes erd
6511 We strongly suggest copying an existing layout file which uses a similar
6512 LaTeX class and then modifying it, if you can do so.
6513 At least use an existing file as a starting point so you can find out what
6514 items you need to worry about.
6515 Again, the specifics are covered below.
6518 \begin_layout Section
6519 Declaring a new text class
6522 \begin_layout Standard
6523 When it's finally time to get your hands dirty and create or edit your own
6524 layout file, the following sections describe what you're up against.
6525 Our advice is to go slowly, save and test often, listen to soothing music,
6526 and enjoy one or two of your favorite adult beverages; more if you are
6527 getting particularly stuck.
6528 It's really not that hard, except that the multitude of options can become
6529 overwhelming if you try to do to much in one sitting.
6530 Go have another adult beverage, just for good measure.
6533 \begin_layout Standard
6537 \begin_layout Standard
6538 Lines in a layout file which begin with a
6539 \begin_inset Flex CharStyle:Code
6542 \begin_layout Plain Layout
6549 There is one exception to this rule: all layouts should begin with lines
6553 \begin_layout LyX-Code
6556 #% Do not delete the line below; configure depends on this
6559 \begin_layout LyX-Code
6564 DeclareLaTeXClass{article}
6567 \begin_layout Standard
6568 The second line is used when you configure LyX.
6569 The layout file is read by the LaTeX script
6570 \begin_inset Flex CharStyle:Code
6573 \begin_layout Plain Layout
6579 , in a special mode where
6580 \begin_inset Flex CharStyle:Code
6583 \begin_layout Plain Layout
6590 The first line is just a LaTeX comment, and the second one contains the
6591 declaration of the text class.
6592 If these lines appear in a file named
6593 \begin_inset Flex CharStyle:Code
6596 \begin_layout Plain Layout
6602 , then they define a text class of name
6603 \begin_inset Flex CharStyle:Code
6606 \begin_layout Plain Layout
6612 (the name of the layout file) which uses the LaTeX document class
6613 \begin_inset Flex CharStyle:Code
6616 \begin_layout Plain Layout
6622 (the default is to use the same name as the layout).
6624 \begin_inset Quotes eld
6628 \begin_inset Quotes erd
6631 that appears above is used as a description of the text class in the
6632 \begin_inset Flex CharStyle:MenuItem
6635 \begin_layout Plain Layout
6640 ocument\SpecialChar \menuseparator
6653 \begin_layout Standard
6654 Let's assume that you wrote your own text class that uses the
6655 \begin_inset Flex CharStyle:Code
6658 \begin_layout Plain Layout
6664 document class, but where you changed the appearance of the section headings.
6665 If you put it in a file
6666 \begin_inset Flex CharStyle:Code
6669 \begin_layout Plain Layout
6675 , the header of this file should be:
6678 \begin_layout LyX-Code
6681 #% Do not delete the line below; configure depends on this
6684 \begin_layout LyX-Code
6689 DeclareLaTeXClass[article]{article (with my own headings)}
6692 \begin_layout Standard
6693 This declares a text class
6694 \begin_inset Flex CharStyle:Code
6697 \begin_layout Plain Layout
6703 , associated with the LaTeX document class
6704 \begin_inset Flex CharStyle:Code
6707 \begin_layout Plain Layout
6714 \begin_inset Quotes eld
6717 article (with my own headings)
6718 \begin_inset Quotes erd
6722 If your text class depends on several packages, you can declare it as:
6725 \begin_layout LyX-Code
6728 #% Do not delete the line below; configure depends on this
6731 \begin_layout LyX-Code
6736 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6739 \begin_layout Standard
6740 This indicates that your text class uses the foo.sty package.
6741 Finally, it is also possible to declare classes for DocBook code.
6742 Typical declarations will look like
6745 \begin_layout LyX-Code
6748 #% Do not delete the line below; configure depends on this
6751 \begin_layout LyX-Code
6756 DeclareDocBookClass[article]{SGML (DocBook article)}
6759 \begin_layout Standard
6760 Note that these declarations can also be given an optional parameter declaring
6761 the name of the document class (but not a list).
6764 \begin_layout Standard
6765 So, to be as explicit as possible, the form of the layout declaration is:
6768 \begin_layout LyX-Code
6773 DeclareLaTeXClass[class,package.sty]{layout description}
6776 \begin_layout Standard
6777 The class need only be specified if the name of the LaTeX class file and
6778 the name of the layout file are different; if the name of the classfile
6779 is not specified, then LyX will simply assume that it is the same as the
6780 name of the layout file.
6783 \begin_layout Standard
6784 When the text class has been modified to your taste, all you have to do
6785 is to copy it either to
6786 \begin_inset Flex CharStyle:Code
6789 \begin_layout Plain Layout
6796 \begin_inset Flex CharStyle:Code
6799 \begin_layout Plain Layout
6806 \begin_inset Flex CharStyle:MenuItem
6809 \begin_layout Plain Layout
6814 ools\SpecialChar \menuseparator
6824 , exit LyX and restart it.
6825 Then your new text class should be available along with the others.
6828 \begin_layout Standard
6829 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6830 you made to your layout files.
6831 As a result, editing layout files could be very time consuming.
6832 Beginning with 1.6, however, you can force a reload of the layout currently
6833 in use by using the LyX function
6834 \begin_inset Flex CharStyle:MenuItem
6837 \begin_layout Plain Layout
6844 There is no default binding for this function---though, of course, you
6845 can bind it to a key yourself.
6846 If you want to use this function, then, you should simply enter it in the
6852 : This is very much an `advanced feature'.
6857 recommended that you save your work before using this function.
6862 recommended that you not attempt to edit your layout while simultaneously
6863 working on a document that you care about.
6864 Use a test document.
6865 Syntax errors and the like in your layout file could cause peculiar behavior.
6866 In particular, such errors could cause LyX to regard the current layout
6867 as invalid and to attempt to switch to some other layout.
6868 The LyX team strives to keep LyX stable in such situations, but safe is
6872 \begin_layout Subsection
6876 \begin_layout Standard
6877 The first non-comment line must contain the file format number:
6880 \begin_layout Description
6881 \begin_inset Flex CharStyle:Code
6884 \begin_layout Plain Layout
6891 \begin_inset Flex CharStyle:Code
6894 \begin_layout Plain Layout
6900 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6901 don't have an explicit file format).
6902 The file format that is documented here is format 8.
6905 \begin_layout Subsection
6906 General text class parameters
6909 \begin_layout Standard
6910 These are the general parameters which describe the form of the entire document:
6913 \begin_layout Description
6914 \begin_inset Flex CharStyle:Code
6917 \begin_layout Plain Layout
6923 Adds information to the document preamble.
6925 \begin_inset Quotes eld
6929 \begin_inset Flex CharStyle:Code
6932 \begin_layout Plain Layout
6939 \begin_inset Quotes erd
6945 \begin_layout Description
6946 \begin_inset Flex CharStyle:Code
6949 \begin_layout Plain Layout
6955 Describes various global options supported by the document class.
6957 \begin_inset space ~
6961 \begin_inset CommandInset ref
6963 reference "sec:classoptions"
6969 \begin_inset Quotes eld
6973 \begin_inset Flex CharStyle:Code
6976 \begin_layout Plain Layout
6983 \begin_inset Quotes erd
6989 \begin_layout Description
6990 \begin_inset Flex CharStyle:Code
6993 \begin_layout Plain Layout
7000 \begin_inset Flex CharStyle:Code
7003 \begin_layout Plain Layout
7012 \begin_inset Flex CharStyle:Code
7015 \begin_layout Plain Layout
7021 ] Whether the class should default to having one or two columns.
7022 Can be changed in the
7023 \begin_inset Flex CharStyle:MenuItem
7026 \begin_layout Plain Layout
7031 ocument\SpecialChar \menuseparator
7044 \begin_layout Description
7045 \begin_inset Flex CharStyle:Code
7048 \begin_layout Plain Layout
7054 This sequence defines a new counter.
7056 \begin_inset space ~
7060 \begin_inset CommandInset ref
7062 reference "sec:counter"
7068 \begin_inset Quotes eld
7072 \begin_inset Flex CharStyle:Code
7075 \begin_layout Plain Layout
7082 \begin_inset Quotes erd
7088 \begin_layout Description
7089 \begin_inset Flex CharStyle:Code
7092 \begin_layout Plain Layout
7098 Sets the default font used to display the document.
7100 \begin_inset space ~
7104 \begin_inset CommandInset ref
7106 reference "sec:fonts"
7110 for how to declare fonts.
7112 \begin_inset Quotes eld
7116 \begin_inset Flex CharStyle:Code
7119 \begin_layout Plain Layout
7126 \begin_inset Quotes erd
7132 \begin_layout Description
7133 \begin_inset Flex CharStyle:Code
7136 \begin_layout Plain Layout
7143 \begin_inset Flex CharStyle:Code
7146 \begin_layout Plain Layout
7152 ] This is the style that will be assigned to new paragraphs, usually
7153 \begin_inset Flex CharStyle:MenuItem
7156 \begin_layout Plain Layout
7163 This will default to the first defined style if not given, but you are
7164 highly encouraged to use this directive.
7167 \begin_layout Description
7168 \begin_inset Flex CharStyle:Code
7171 \begin_layout Plain Layout
7177 Defines a new float.
7179 \begin_inset space ~
7183 \begin_inset CommandInset ref
7185 reference "sec:floats"
7191 \begin_inset Quotes eld
7195 \begin_inset Flex CharStyle:Code
7198 \begin_layout Plain Layout
7205 \begin_inset Quotes erd
7211 \begin_layout Description
7212 \begin_inset Flex CharStyle:Code
7215 \begin_layout Plain Layout
7221 As its name implies, this command allows you to include another layout
7222 definition file within yours to avoid duplicating commands.
7223 Common examples are the standard layout files, for example,
7224 \begin_inset Flex CharStyle:Code
7227 \begin_layout Plain Layout
7233 , which contains most of the basic layouts.
7236 \begin_layout Description
7237 \begin_inset Flex CharStyle:Code
7240 \begin_layout Plain Layout
7246 This section (re-)defines the layout of an inset.
7247 It can be applied to an existing inset of to a new, user-defined inset,
7248 e.g., a new character style.
7250 \begin_inset space ~
7254 \begin_inset CommandInset ref
7256 reference "sec:charstyle"
7260 for more information.
7262 \begin_inset Quotes eld
7266 \begin_inset Flex CharStyle:Code
7269 \begin_layout Plain Layout
7276 \begin_inset Quotes erd
7282 \begin_layout Description
7283 \begin_inset Flex CharStyle:Code
7286 \begin_layout Plain Layout
7295 \begin_layout Description
7296 \begin_inset Flex CharStyle:Code
7299 \begin_layout Plain Layout
7305 This command deletes an existing float.
7306 This is particularly useful when you want to suppress a float that has
7307 be defined in an input file.
7310 \begin_layout Description
7311 \begin_inset Flex CharStyle:Code
7314 \begin_layout Plain Layout
7320 This command deletes an existing style.
7321 This is particularly useful when you want to suppress a style that has
7322 be defined in an input file.
7325 \begin_layout Description
7326 \begin_inset Flex CharStyle:Code
7329 \begin_layout Plain Layout
7338 \begin_layout Description
7339 \begin_inset Flex CharStyle:Code
7342 \begin_layout Plain Layout
7353 \begin_inset Flex CharStyle:Code
7356 \begin_layout Plain Layout
7367 \begin_inset Flex CharStyle:Code
7370 \begin_layout Plain Layout
7377 \begin_inset Flex CharStyle:Code
7380 \begin_layout Plain Layout
7386 ] The class default pagestyle.
7387 Can be changed in the
7388 \begin_inset Flex CharStyle:MenuItem
7391 \begin_layout Plain Layout
7396 ocument\SpecialChar \menuseparator
7409 \begin_layout Description
7410 \begin_inset Flex CharStyle:Code
7413 \begin_layout Plain Layout
7419 Sets the preamble for the LaTeX document.
7420 Note that this will completely override any prior
7421 \begin_inset Flex CharStyle:Code
7424 \begin_layout Plain Layout
7431 \begin_inset Flex CharStyle:Code
7434 \begin_layout Plain Layout
7442 \begin_inset Quotes eld
7446 \begin_inset Flex CharStyle:Code
7449 \begin_layout Plain Layout
7456 \begin_inset Quotes erd
7462 \begin_layout Description
7463 \begin_inset Flex CharStyle:Code
7466 \begin_layout Plain Layout
7473 \begin_inset Flex CharStyle:Code
7476 \begin_layout Plain Layout
7483 \begin_inset Flex CharStyle:Code
7486 \begin_layout Plain Layout
7495 \begin_inset Flex CharStyle:Code
7498 \begin_layout Plain Layout
7504 ] Whether the class already provides the feature
7505 \begin_inset Flex CharStyle:Code
7508 \begin_layout Plain Layout
7515 A feature is in general the name of a package (
7516 \begin_inset Flex CharStyle:Code
7519 \begin_layout Plain Layout
7526 \begin_inset Flex CharStyle:Code
7529 \begin_layout Plain Layout
7535 , \SpecialChar \ldots{}
7537 \begin_inset Flex CharStyle:Code
7540 \begin_layout Plain Layout
7547 \begin_inset Flex CharStyle:Code
7550 \begin_layout Plain Layout
7556 ,\SpecialChar \ldots{}
7557 ); the complete list of supported features is unfortunately not documented
7558 outside the LyX source code---but see
7559 \begin_inset Flex CharStyle:Code
7562 \begin_layout Plain Layout
7568 if you're interested.
7570 \begin_inset Flex CharStyle:MenuItem
7573 \begin_layout Plain Layout
7578 elp\SpecialChar \menuseparator
7588 also gives an overview of the supported packages.
7591 \begin_layout Description
7592 \begin_inset Flex CharStyle:Code
7595 \begin_layout Plain Layout
7602 \begin_inset Flex CharStyle:Code
7605 \begin_layout Plain Layout
7611 ] Whether the class requires the feature
7612 \begin_inset Flex CharStyle:Code
7615 \begin_layout Plain Layout
7622 Multiple features must be separated by commas.
7623 Note that you can only request supported features.
7626 \begin_layout Description
7627 \begin_inset Flex CharStyle:Code
7630 \begin_layout Plain Layout
7639 \begin_layout Description
7640 \begin_inset Flex CharStyle:Code
7643 \begin_layout Plain Layout
7652 \begin_layout Description
7653 \begin_inset Flex CharStyle:Code
7656 \begin_layout Plain Layout
7665 \begin_inset Flex CharStyle:Code
7668 \begin_layout Plain Layout
7679 \begin_inset Flex CharStyle:Code
7682 \begin_layout Plain Layout
7688 ] Whether the class-default should be printing on one or both sides of the
7690 Can be changed in the
7691 \begin_inset Flex CharStyle:MenuItem
7694 \begin_layout Plain Layout
7699 ocument\SpecialChar \menuseparator
7712 \begin_layout Description
7713 \begin_inset Flex CharStyle:Code
7716 \begin_layout Plain Layout
7722 This sequence defines a new paragraph style.
7723 If the style already exists, it will redefine some of its parameters instead.
7725 \begin_inset space ~
7729 \begin_inset CommandInset ref
7731 reference "sec:style"
7737 \begin_inset Quotes eld
7741 \begin_inset Flex CharStyle:Code
7744 \begin_layout Plain Layout
7751 \begin_inset Quotes erd
7757 \begin_layout Description
7758 \begin_inset Flex CharStyle:Code
7761 \begin_layout Plain Layout
7768 \begin_inset Flex CharStyle:Code
7771 \begin_layout Plain Layout
7777 ] The name of the command or environment to be used with
7778 \begin_inset Flex CharStyle:Code
7781 \begin_layout Plain Layout
7790 \begin_layout Description
7791 \begin_inset Flex CharStyle:Code
7794 \begin_layout Plain Layout
7801 \begin_inset Flex CharStyle:Code
7804 \begin_layout Plain Layout
7813 \begin_inset Flex CharStyle:Code
7816 \begin_layout Plain Layout
7822 ] Indicates what kind of markup is used to define the title of a document.
7824 \begin_inset Flex CharStyle:Code
7827 \begin_layout Plain Layout
7833 means that the macro with name
7834 \begin_inset Flex CharStyle:Code
7837 \begin_layout Plain Layout
7843 will be inserted after the last layout which has
7844 \begin_inset Quotes eld
7848 \begin_inset Flex CharStyle:Code
7851 \begin_layout Plain Layout
7858 \begin_inset Quotes erd
7863 \begin_inset Flex CharStyle:Code
7866 \begin_layout Plain Layout
7872 corresponds to the case where the block of paragraphs which have
7873 \begin_inset Quotes eld
7877 \begin_inset Flex CharStyle:Code
7880 \begin_layout Plain Layout
7887 \begin_inset Quotes erd
7890 should be enclosed into the
7891 \begin_inset Flex CharStyle:Code
7894 \begin_layout Plain Layout
7903 \begin_layout Description
7904 \begin_inset Flex CharStyle:Code
7907 \begin_layout Plain Layout
7916 \begin_layout Description
7917 \begin_inset Flex CharStyle:Code
7920 \begin_layout Plain Layout
7927 \begin_inset Flex CharStyle:Code
7930 \begin_layout Plain Layout
7936 Specifies a module to be included by default with this document class.
7937 The user can still remove the module, but it will be active at the outset.
7938 (This applies only when new files are created, or when this class is chosen
7939 for an existing document.)
7942 \begin_layout Subsection
7943 \begin_inset Flex CharStyle:Code
7946 \begin_layout Plain Layout
7955 \begin_layout Standard
7956 \begin_inset CommandInset label
7958 name "sec:classoptions"
7963 \begin_inset Flex CharStyle:Code
7966 \begin_layout Plain Layout
7972 section can contain the following entries:
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
7995 ] The list of available font sizes for the document's main font, separated
7997 \begin_inset Quotes eld
8001 \begin_inset Flex CharStyle:Code
8004 \begin_layout Plain Layout
8011 \begin_inset Quotes erd
8017 \begin_layout Description
8018 \begin_inset Flex CharStyle:Code
8021 \begin_layout Plain Layout
8030 \begin_layout Description
8031 \begin_inset Flex CharStyle:Code
8034 \begin_layout Plain Layout
8041 \begin_inset Flex CharStyle:Code
8044 \begin_layout Plain Layout
8045 string="empty|plain|headings|fancy"
8050 ] The list of available page styles, separated by
8051 \begin_inset Quotes eld
8055 \begin_inset Flex CharStyle:Code
8058 \begin_layout Plain Layout
8065 \begin_inset Quotes erd
8071 \begin_layout Description
8072 \begin_inset Flex CharStyle:Code
8075 \begin_layout Plain Layout
8082 \begin_inset Flex CharStyle:Code
8085 \begin_layout Plain Layout
8091 ] Some document class options, separated by a comma, that will be added
8092 to the optional part of the
8093 \begin_inset Flex CharStyle:Code
8096 \begin_layout Plain Layout
8107 \begin_layout Standard
8109 \begin_inset Flex CharStyle:Code
8112 \begin_layout Plain Layout
8118 section must end with
8119 \begin_inset Quotes eld
8123 \begin_inset Flex CharStyle:Code
8126 \begin_layout Plain Layout
8133 \begin_inset Quotes erd
8139 \begin_layout Subsection
8143 \begin_layout Standard
8144 \begin_inset CommandInset label
8150 A paragraph style description looks like this:
8154 \begin_layout Plain Layout
8155 Note that this will either define a new layout or modify an existing one.
8163 \begin_layout LyX-Code
8170 \begin_layout LyX-Code
8174 \begin_layout LyX-Code
8178 \begin_layout Standard
8179 where the following commands are allowed:
8182 \begin_layout Description
8183 \begin_inset Flex CharStyle:Code
8186 \begin_layout Plain Layout
8193 \begin_inset Flex CharStyle:Code
8196 \begin_layout Plain Layout
8201 , left, right, center
8206 ] Paragraph alignment.
8209 \begin_layout Description
8210 \begin_inset Flex CharStyle:Code
8213 \begin_layout Plain Layout
8220 \begin_inset Flex CharStyle:Code
8223 \begin_layout Plain Layout
8228 , left, right, center
8233 ] A comma separated list of permitted alignments.
8234 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8236 For example a right-aligned or centered enumeration isn't possible.)
8239 \begin_layout Description
8240 \begin_inset Flex CharStyle:Code
8243 \begin_layout Plain Layout
8250 \begin_inset Flex CharStyle:Code
8253 \begin_layout Plain Layout
8263 \begin_layout Plain Layout
8264 Note that a `float' here is a real number, such as: 1.5.
8269 The vertical space with which the last of a chain of paragraphs with this
8270 layout is separated from the following paragraph.
8271 If the next paragraph has another layout, the separations are not simply
8272 added, but the maximum is taken.
8275 \begin_layout Description
8276 \begin_inset Flex CharStyle:Code
8279 \begin_layout Plain Layout
8286 \begin_inset Flex CharStyle:Code
8289 \begin_layout Plain Layout
8295 The category for this style.
8296 This is used to group related styles in the Layout combobox on the toolbar.
8297 Any string can be used, but you may want to use existing categories with
8302 \begin_layout Description
8303 \begin_inset Flex CharStyle:Code
8306 \begin_layout Plain Layout
8315 \begin_layout Description
8316 \begin_inset Flex CharStyle:Code
8319 \begin_layout Plain Layout
8326 \begin_inset CommandInset label
8328 name "des:CopyStyle"
8333 \begin_inset Flex CharStyle:Code
8336 \begin_layout Plain Layout
8342 Copies all the features of an existing style into the current one.
8346 \begin_layout Description
8347 \begin_inset Flex CharStyle:Code
8350 \begin_layout Plain Layout
8356 The name of a style whose preamble should be output
8361 This allows to ensure some ordering of the preamble snippets when macros
8362 definitions depend on one another.
8366 \begin_layout Plain Layout
8367 Note that, besides that functionality, there is no way to ensure any ordering
8369 The ordering that you see in a given version of LyX may change without
8370 warning in later versions.
8378 \begin_layout Description
8379 \begin_inset Flex CharStyle:Code
8382 \begin_layout Plain Layout
8389 \begin_inset Flex CharStyle:Code
8392 \begin_layout Plain Layout
8397 , Box, Filled_Box, Static
8402 ] The type of label that stands at the end of the paragraph (or sequence
8404 \begin_inset Flex CharStyle:Code
8407 \begin_layout Plain Layout
8414 \begin_inset Flex CharStyle:Code
8417 \begin_layout Plain Layout
8424 \begin_inset Flex CharStyle:Code
8427 \begin_layout Plain Layout
8434 \begin_inset Flex CharStyle:Code
8437 \begin_layout Plain Layout
8445 \begin_inset Flex CharStyle:Code
8448 \begin_layout Plain Layout
8455 \begin_inset Quotes eld
8459 \begin_inset Quotes erd
8463 \begin_inset Flex CharStyle:Code
8466 \begin_layout Plain Layout
8473 \begin_inset Flex CharStyle:Code
8476 \begin_layout Plain Layout
8477 \begin_inset space ~
8486 \begin_inset space ~
8489 black) square suitable for end of proof markers,
8490 \begin_inset Flex CharStyle:Code
8493 \begin_layout Plain Layout
8499 is an explicit text string.
8502 \begin_layout Description
8503 \begin_inset Flex CharStyle:Code
8506 \begin_layout Plain Layout
8513 \begin_inset Flex CharStyle:Code
8516 \begin_layout Plain Layout
8522 ] The string used for a label with a
8523 \begin_inset Flex CharStyle:Code
8526 \begin_layout Plain Layout
8533 \begin_inset Flex CharStyle:Code
8536 \begin_layout Plain Layout
8546 \begin_layout Description
8547 \begin_inset Flex CharStyle:Code
8550 \begin_layout Plain Layout
8557 \begin_inset Flex CharStyle:Code
8560 \begin_layout Plain Layout
8571 \begin_inset Flex CharStyle:Code
8574 \begin_layout Plain Layout
8583 \begin_layout Description
8584 \begin_inset Flex CharStyle:Code
8587 \begin_layout Plain Layout
8594 \begin_inset Flex CharStyle:Code
8597 \begin_layout Plain Layout
8607 ] With this parameter the
8608 \begin_inset Flex CharStyle:MenuItem
8611 \begin_layout Plain Layout
8618 \begin_inset Quotes eld
8621 Vertical space above
8622 \begin_inset Quotes erd
8626 \begin_inset Flex CharStyle:MenuItem
8629 \begin_layout Plain Layout
8634 dit\SpecialChar \menuseparator
8640 \begin_inset space ~
8648 dialog can be set when initializing a paragraph with this style.
8652 \begin_layout Plain Layout
8655 Note from Jean-Marc:
8657 I'm not sure that this setting has much use, and it should probably be
8658 removed in later versions.
8666 \begin_layout Description
8667 \begin_inset Flex CharStyle:Code
8670 \begin_layout Plain Layout
8676 The font used for both the text body
8682 \begin_inset space ~
8686 \begin_inset CommandInset ref
8688 reference "sec:fonts"
8693 Note that defining this font automatically defines the
8694 \begin_inset Flex CharStyle:Code
8697 \begin_layout Plain Layout
8704 So you should define this one first if you also want to define
8705 \begin_inset Flex CharStyle:Code
8708 \begin_layout Plain Layout
8717 \begin_layout Description
8718 \begin_inset Flex CharStyle:Code
8721 \begin_layout Plain Layout
8728 \begin_inset CommandInset label
8730 name "des:FreeSpacing"
8737 \begin_inset Flex CharStyle:Code
8740 \begin_layout Plain Layout
8751 \begin_inset Flex CharStyle:Code
8754 \begin_layout Plain Layout
8760 ] Usually LyX doesn't allow you to insert more than one space between words,
8761 since a space is considered as the separation between two words, not a
8762 character or symbol of its own.
8763 This is a very fine thing but sometimes annoying, for example, when typing
8764 program code or plain LaTeX code.
8766 \begin_inset Flex CharStyle:Code
8769 \begin_layout Plain Layout
8776 Note that LyX will create protected blanks for the additional blanks when
8777 in another mode than LaTeX-mode.
8780 \begin_layout Description
8781 \begin_inset Flex CharStyle:Code
8784 \begin_layout Plain Layout
8793 \begin_layout Description
8794 \begin_inset Flex CharStyle:Code
8797 \begin_layout Plain Layout
8804 \begin_inset Flex CharStyle:Code
8807 \begin_layout Plain Layout
8813 If 1, marks the layout as being part of a title block (see also the
8814 \begin_inset Flex CharStyle:Code
8817 \begin_layout Plain Layout
8824 \begin_inset Flex CharStyle:Code
8827 \begin_layout Plain Layout
8836 \begin_layout Description
8837 \begin_inset Flex CharStyle:Code
8840 \begin_layout Plain Layout
8847 \begin_inset Flex CharStyle:Code
8850 \begin_layout Plain Layout
8856 ] This provides extra space between paragraphs that have the same layout.
8857 If you put other layouts into an environment, each is separated with the
8859 \begin_inset Flex CharStyle:Code
8862 \begin_layout Plain Layout
8869 But the whole items of the environment are additionally separated with
8871 \begin_inset Flex CharStyle:Code
8874 \begin_layout Plain Layout
8886 \begin_layout Description
8887 \begin_inset Flex CharStyle:Code
8890 \begin_layout Plain Layout
8899 \begin_layout Description
8900 \begin_inset Flex CharStyle:Code
8903 \begin_layout Plain Layout
8910 \begin_inset CommandInset label
8912 name "des:KeepEmpty"
8919 \begin_inset Flex CharStyle:Code
8922 \begin_layout Plain Layout
8933 \begin_inset Flex CharStyle:Code
8936 \begin_layout Plain Layout
8942 ] Usually LyX does not allow you to leave a paragraph empty, since it would
8943 lead to empty LaTeX output.
8944 There are some cases where this could be desirable however: in a letter
8945 template, the required fields can be provided as empty fields, so that
8946 people do not forget them; in some special classes, a layout can be used
8947 as some kind of break, which does not contain actual text.
8950 \begin_layout Description
8951 \begin_inset Flex CharStyle:Code
8954 \begin_layout Plain Layout
8960 [float=0] The vertical space between the label and the text body.
8961 Only used for labels that are above the text body (
8962 \begin_inset Flex CharStyle:Code
8965 \begin_layout Plain Layout
8972 \begin_inset Flex CharStyle:Code
8975 \begin_layout Plain Layout
8976 Centered_Top_Environment
8984 \begin_layout Description
8985 \begin_inset Flex CharStyle:Code
8988 \begin_layout Plain Layout
8995 \begin_inset Flex CharStyle:Code
8998 \begin_layout Plain Layout
9005 \begin_inset Newline newline
9008 The name of the counter for automatic numbering (see Section
9009 \begin_inset CommandInset ref
9011 reference "sec:counter"
9016 This must be given if
9017 \begin_inset Flex CharStyle:Code
9020 \begin_layout Plain Layout
9027 \begin_inset Flex CharStyle:Code
9030 \begin_layout Plain Layout
9039 \begin_layout Description
9040 \begin_inset Flex CharStyle:Code
9043 \begin_layout Plain Layout
9049 The font used for the label.
9051 \begin_inset space ~
9055 \begin_inset CommandInset ref
9057 reference "sec:fonts"
9064 \begin_layout Description
9065 \begin_inset Flex CharStyle:Code
9068 \begin_layout Plain Layout
9075 \begin_inset Flex CharStyle:Code
9078 \begin_layout Plain Layout
9084 ] The horizontal space between the label and the text body.
9085 Only used for labels that are not above the text body.
9088 \begin_layout Description
9089 \begin_inset Flex CharStyle:Code
9092 \begin_layout Plain Layout
9099 \begin_inset Flex CharStyle:Code
9102 \begin_layout Plain Layout
9108 ] The string used for a label with a
9109 \begin_inset Flex CharStyle:Code
9112 \begin_layout Plain Layout
9120 \begin_inset Flex CharStyle:Code
9123 \begin_layout Plain Layout
9129 is set, this string can be contain the special formatting commands described
9131 \begin_inset CommandInset ref
9133 reference "sec:counter"
9141 \begin_layout Plain Layout
9142 For the sake of backwards compatibility, the string
9143 \begin_inset Flex CharStyle:Code
9146 \begin_layout Plain Layout
9156 will be replaced by the expanded
9157 \begin_inset Flex CharStyle:Code
9160 \begin_layout Plain Layout
9167 \begin_inset Flex CharStyle:Code
9170 \begin_layout Plain Layout
9179 This feature is now obsolete and should be replaced by the mechanisms of
9181 \begin_inset CommandInset ref
9183 reference "sec:counter"
9195 \begin_layout Description
9196 \begin_inset Flex CharStyle:Code
9199 \begin_layout Plain Layout
9206 \begin_inset Flex CharStyle:Code
9209 \begin_layout Plain Layout
9215 ] This is used inside the appendix instead of
9216 \begin_inset Flex CharStyle:Code
9219 \begin_layout Plain Layout
9227 \begin_inset Flex CharStyle:Code
9230 \begin_layout Plain Layout
9237 \begin_inset Flex CharStyle:Code
9240 \begin_layout Plain Layout
9249 \begin_layout Description
9250 \begin_inset Flex CharStyle:Code
9253 \begin_layout Plain Layout
9260 \begin_inset Flex CharStyle:Code
9263 \begin_layout Plain Layout
9268 , Manual, Static, Top_Environment,
9269 \begin_inset Newline newline
9272 Centered_Top_Environment, Sensitive, Counter
9278 \begin_inset Newline newline
9282 \begin_inset Flex CharStyle:Code
9285 \begin_layout Plain Layout
9291 means the label is the very first word (up to the first real blank).
9295 \begin_layout Plain Layout
9296 Use protected spaces if you want more than one word as the label.
9302 \begin_inset Flex CharStyle:Code
9305 \begin_layout Plain Layout
9311 means it is defined in the layout (see
9312 \begin_inset Flex CharStyle:Code
9315 \begin_layout Plain Layout
9323 \begin_inset Flex CharStyle:Code
9326 \begin_layout Plain Layout
9333 \begin_inset Flex CharStyle:Code
9336 \begin_layout Plain Layout
9337 Centered_Top_Environment
9342 are special cases of
9343 \begin_inset Flex CharStyle:Code
9346 \begin_layout Plain Layout
9353 The label will be printed above the paragraph, but only at the top of an
9354 environment or the top of a chain of paragraphs with this layout.
9355 Usage is for example the
9356 \begin_inset Flex CharStyle:MenuItem
9359 \begin_layout Plain Layout
9366 \begin_inset Flex CharStyle:MenuItem
9369 \begin_layout Plain Layout
9376 This is also the case for
9377 \begin_inset Flex CharStyle:Code
9380 \begin_layout Plain Layout
9386 labels with latex type
9387 \begin_inset Flex CharStyle:Code
9390 \begin_layout Plain Layout
9396 , in order to make layouts for theorems work correctly.
9398 \begin_inset Flex CharStyle:Code
9401 \begin_layout Plain Layout
9407 is a special case for the caption-labels
9408 \begin_inset Quotes eld
9412 \begin_inset Quotes erd
9416 \begin_inset Quotes eld
9420 \begin_inset Quotes erd
9425 \begin_inset Flex CharStyle:Code
9428 \begin_layout Plain Layout
9434 means the (hardcoded) label string depends on the kind of float.
9436 \begin_inset Flex CharStyle:Code
9439 \begin_layout Plain Layout
9445 label type defines automatically numbered labels.
9447 \begin_inset CommandInset ref
9449 reference "sec:counter"
9456 \begin_layout Description
9457 \begin_inset Flex CharStyle:Code
9460 \begin_layout Plain Layout
9469 \begin_layout Description
9470 \begin_inset Flex CharStyle:Code
9473 \begin_layout Plain Layout
9482 \begin_layout Description
9483 \begin_inset Flex CharStyle:Code
9486 \begin_layout Plain Layout
9492 The name of the corresponding LaTeX stuff.
9493 Either the environment or command name.
9496 \begin_layout Description
9497 \begin_inset Flex CharStyle:Code
9500 \begin_layout Plain Layout
9509 \begin_layout Description
9510 \begin_inset Flex CharStyle:Code
9513 \begin_layout Plain Layout
9519 An optional parameter for the corresponding
9520 \begin_inset Flex CharStyle:Code
9523 \begin_layout Plain Layout
9530 This parameter cannot be changed from within LyX.
9533 \begin_layout Description
9534 \begin_inset Flex CharStyle:Code
9537 \begin_layout Plain Layout
9544 \begin_inset CommandInset label
9546 name "des:LatexType"
9551 \begin_inset Flex CharStyle:Code
9554 \begin_layout Plain Layout
9559 , Command, Environment, Item_Environment,
9565 \begin_inset Flex CharStyle:Code
9568 \begin_layout Plain Layout
9574 ] How the layout should be translated into LaTeX.
9576 \begin_inset Flex CharStyle:Code
9579 \begin_layout Plain Layout
9585 means nothing special.
9587 \begin_inset Flex CharStyle:Code
9590 \begin_layout Plain Layout
9597 \begin_inset Flex CharStyle:Code
9600 \begin_layout Plain Layout
9607 {\SpecialChar \ldots{}
9614 \begin_inset Flex CharStyle:Code
9617 \begin_layout Plain Layout
9624 \begin_inset Flex CharStyle:Code
9627 \begin_layout Plain Layout
9634 }\SpecialChar \ldots{}
9648 \begin_inset Flex CharStyle:Code
9651 \begin_layout Plain Layout
9658 \begin_inset Flex CharStyle:Code
9661 \begin_layout Plain Layout
9668 \begin_inset Flex CharStyle:Code
9671 \begin_layout Plain Layout
9679 is generated for each paragraph of this environment.
9681 \begin_inset Flex CharStyle:Code
9684 \begin_layout Plain Layout
9691 \begin_inset Flex CharStyle:Code
9694 \begin_layout Plain Layout
9701 \begin_inset Flex CharStyle:Code
9704 \begin_layout Plain Layout
9710 is passed as an argument to the environment.
9712 \begin_inset Flex CharStyle:Code
9715 \begin_layout Plain Layout
9721 can be defined in the
9722 \begin_inset Flex CharStyle:MenuItem
9725 \begin_layout Plain Layout
9730 ayout\SpecialChar \menuseparator
9742 \begin_inset Flex CharStyle:Code
9745 \begin_layout Plain Layout
9753 is perhaps a bit misleading, since these rules apply to SGML classes, too.
9754 Visit the SGML class files for specific examples.
9757 \begin_layout Standard
9758 Putting the last few things together, the LaTeX output will be either:
9761 \begin_layout LyX-Code
9764 latexname[latexparam]{\SpecialChar \ldots{}
9768 \begin_layout Standard
9772 \begin_layout LyX-Code
9775 begin{latexname}[latexparam] \SpecialChar \ldots{}
9781 \begin_layout Standard
9782 depending upon the LaTex type.
9785 \begin_layout Description
9786 \begin_inset Flex CharStyle:Code
9789 \begin_layout Plain Layout
9796 \begin_inset Flex CharStyle:Code
9799 \begin_layout Plain Layout
9805 ] If you put layouts into environments, the leftmargins are not simply added,
9806 but added with a factor
9807 \begin_inset Formula $\frac{4}{depth+4}$
9811 Note that this parameter is also used when the margin is defined as
9812 \begin_inset Flex CharStyle:Code
9815 \begin_layout Plain Layout
9822 \begin_inset Flex CharStyle:Code
9825 \begin_layout Plain Layout
9832 Then it is added to the manual or dynamic margin.
9834 \begin_inset Newline newline
9837 The argument is passed as a string.
9839 \begin_inset Quotes eld
9843 \begin_inset Flex CharStyle:Code
9846 \begin_layout Plain Layout
9853 \begin_inset Quotes erd
9856 means that the paragraph is indented with the width of
9857 \begin_inset Quotes eld
9861 \begin_inset Flex CharStyle:Code
9864 \begin_layout Plain Layout
9871 \begin_inset Quotes erd
9875 You can get a negative width by prefixing the string with
9876 \begin_inset Quotes eld
9880 \begin_inset Flex CharStyle:Code
9883 \begin_layout Plain Layout
9890 \begin_inset Quotes erd
9894 This way was chosen so that the look is the same with each used screen
9899 \begin_layout Description
9900 \begin_inset Flex CharStyle:Code
9903 \begin_layout Plain Layout
9910 \begin_inset Flex CharStyle:Code
9913 \begin_layout Plain Layout
9918 , Manual, Dynamic, First_Dynamic, Right_Address_Box
9924 \begin_inset Newline newline
9927 The kind of margin that the layout has on the left side.
9929 \begin_inset Flex CharStyle:Code
9932 \begin_layout Plain Layout
9938 just means a fixed margin.
9940 \begin_inset Flex CharStyle:Code
9943 \begin_layout Plain Layout
9949 means that the left margin depends on the string entered in the
9950 \begin_inset Flex CharStyle:MenuItem
9953 \begin_layout Plain Layout
9958 dit\SpecialChar \menuseparator
9964 \begin_inset space ~
9973 This is used to typeset nice lists without tabulators.
9975 \begin_inset Flex CharStyle:Code
9978 \begin_layout Plain Layout
9984 means that the margin depends on the size of the label.
9985 This is used for automatic enumerated headlines.
9986 It is obvious that the headline
9987 \begin_inset Quotes eld
9990 5.4.3.2.1 Very long headline
9991 \begin_inset Quotes erd
9994 must have a wider left margin (as wide as
9995 \begin_inset Quotes eld
9999 \begin_inset Quotes erd
10002 plus the space) than
10003 \begin_inset Quotes eld
10006 3.2 Very long headline
10007 \begin_inset Quotes erd
10011 \begin_inset Quotes eld
10015 \begin_inset Quotes erd
10018 are not able to do this.
10020 \begin_inset Flex CharStyle:Code
10023 \begin_layout Plain Layout
10029 is similar, but only the very first row of the paragraph is dynamic, while
10030 the others are static; this is used, for example, for descriptions.
10032 \begin_inset Flex CharStyle:Code
10035 \begin_layout Plain Layout
10041 means the margin is chosen in a way that the longest row of this paragraph
10042 fits to the right margin.
10043 This is used to typeset an address on the right edge of the page.
10046 \begin_layout Description
10047 \begin_inset Flex CharStyle:Code
10050 \begin_layout Plain Layout
10057 \begin_inset Flex CharStyle:Code
10060 \begin_layout Plain Layout
10069 \begin_inset Flex CharStyle:Code
10072 \begin_layout Plain Layout
10078 ] Whether fragile commands in this layout should be
10079 \begin_inset Flex CharStyle:Code
10082 \begin_layout Plain Layout
10095 whether this command should itself be protected.)
10098 \begin_layout Description
10099 \begin_inset Flex CharStyle:Code
10102 \begin_layout Plain Layout
10109 \begin_inset Flex CharStyle:Code
10112 \begin_layout Plain Layout
10119 \begin_inset Flex CharStyle:Code
10122 \begin_layout Plain Layout
10130 ] Whether newlines are translated into LaTeX newlines (
10131 \begin_inset Flex CharStyle:Code
10134 \begin_layout Plain Layout
10145 The translation can be switched off to allow more comfortable LaTeX editing
10149 \begin_layout Description
10150 \begin_inset Flex CharStyle:Code
10153 \begin_layout Plain Layout
10160 \begin_inset Flex CharStyle:Code
10163 \begin_layout Plain Layout
10170 \begin_inset Flex CharStyle:Code
10173 \begin_layout Plain Layout
10181 ] Whether the following Paragraph is allowed to indent its very first row.
10183 \begin_inset Flex CharStyle:Code
10186 \begin_layout Plain Layout
10192 means that it is not allowed to do so;
10193 \begin_inset Flex CharStyle:Code
10196 \begin_layout Plain Layout
10202 means it could do so if it wants to.
10205 \begin_layout Description
10206 \begin_inset Flex CharStyle:Code
10209 \begin_layout Plain Layout
10218 \begin_layout Description
10219 \begin_inset Flex CharStyle:Code
10222 \begin_layout Plain Layout
10229 \begin_inset Flex CharStyle:Code
10232 \begin_layout Plain Layout
10238 ] The number of optional arguments that can be used with this layout.
10239 This is useful for things like section headings, and only makes sense with
10243 \begin_layout Description
10244 \begin_inset Flex CharStyle:Code
10247 \begin_layout Plain Layout
10254 \begin_inset Flex CharStyle:Code
10257 \begin_layout Plain Layout
10263 ] The indent of the very first line of a paragraph.
10265 \begin_inset Flex CharStyle:Code
10268 \begin_layout Plain Layout
10274 will be fixed for a certain layout.
10275 The exception is Standard layout, since the indentation of a Standard layout
10276 paragraph can be prohibited with
10277 \begin_inset Flex CharStyle:Code
10280 \begin_layout Plain Layout
10287 Also, Standard layout paragraphs inside environments use the
10288 \begin_inset Flex CharStyle:Code
10291 \begin_layout Plain Layout
10297 of the environment, not their native one.
10298 For example, Standard paragraphs inside an enumeration are not indented.
10301 \begin_layout Description
10302 \begin_inset Flex CharStyle:Code
10305 \begin_layout Plain Layout
10312 \begin_inset Flex CharStyle:Code
10315 \begin_layout Plain Layout
10321 ] The vertical space between two paragraphs of this layout.
10324 \begin_layout Description
10325 \begin_inset Flex CharStyle:Code
10328 \begin_layout Plain Layout
10335 \begin_inset Flex CharStyle:Code
10338 \begin_layout Plain Layout
10344 ] LyX allows the user to choose either
10345 \begin_inset Quotes eld
10349 \begin_inset Quotes erd
10353 \begin_inset Quotes eld
10357 \begin_inset Quotes erd
10360 to typeset a document.
10362 \begin_inset Quotes eld
10366 \begin_inset Quotes erd
10369 is chosen, this value is completely ignored.
10371 \begin_inset Quotes eld
10375 \begin_inset Quotes erd
10378 is chosen, the parindent of a LaTeXtype
10379 \begin_inset Quotes eld
10383 \begin_inset Quotes erd
10386 layout is ignored and all paragraphs are separated by this parskip argument.
10387 The vertical space is calculated with
10388 \begin_inset Flex CharStyle:Code
10391 \begin_layout Plain Layout
10393 \begin_inset space ~
10402 \begin_inset Flex CharStyle:Code
10405 \begin_layout Plain Layout
10411 is the height of a row with the normal font.
10412 This way, the look stays the same with different screen fonts.
10415 \begin_layout Description
10416 \begin_inset Flex CharStyle:Code
10419 \begin_layout Plain Layout
10428 \begin_inset Flex CharStyle:Code
10431 \begin_layout Plain Layout
10442 \begin_inset Flex CharStyle:Code
10445 \begin_layout Plain Layout
10451 ] Whether the contents of this paragraph should be output in raw form, meaning
10452 without special translations that LaTeX would require.
10455 \begin_layout Description
10456 \begin_inset Flex CharStyle:Code
10459 \begin_layout Plain Layout
10466 \begin_inset CommandInset label
10468 name "des:Preamble"
10472 Information to be included in the LaTeX preamable when this style is used.
10473 Used to define macros, load packages, etc., required by this particular
10476 \begin_inset Quotes eld
10480 \begin_inset Flex CharStyle:Code
10483 \begin_layout Plain Layout
10490 \begin_inset Quotes erd
10496 \begin_layout Description
10497 \begin_inset Flex CharStyle:Code
10500 \begin_layout Plain Layout
10507 \begin_inset Flex CharStyle:Code
10510 \begin_layout Plain Layout
10517 \begin_inset CommandInset label
10519 name "des:Requires"
10523 Whether the layout requires the feature
10524 \begin_inset Flex CharStyle:Code
10527 \begin_layout Plain Layout
10534 See the description of
10535 \begin_inset Flex CharStyle:Code
10538 \begin_layout Plain Layout
10545 \begin_inset CommandInset ref
10546 LatexCommand pageref
10547 reference "des:FreeSpacing"
10551 ) for information on `features'.
10555 \begin_layout Description
10556 \begin_inset Flex CharStyle:Code
10559 \begin_layout Plain Layout
10566 \begin_inset Flex CharStyle:Code
10569 \begin_layout Plain Layout
10576 \begin_inset Flex CharStyle:Code
10579 \begin_layout Plain Layout
10588 \begin_layout Description
10589 \begin_inset Flex CharStyle:Code
10592 \begin_layout Plain Layout
10599 \begin_inset Flex CharStyle:Code
10602 \begin_layout Plain Layout
10607 , onehalf, double, other
10616 ] This defines what the default spacing should be in the layout.
10618 \begin_inset Flex CharStyle:Code
10621 \begin_layout Plain Layout
10628 \begin_inset Flex CharStyle:Code
10631 \begin_layout Plain Layout
10638 \begin_inset Flex CharStyle:Code
10641 \begin_layout Plain Layout
10647 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10648 If you specify the argument
10649 \begin_inset Flex CharStyle:Code
10652 \begin_layout Plain Layout
10658 , then you should also provide a numerical argument which will be the actual
10660 Note that, contrary to other parameters,
10661 \begin_inset Flex CharStyle:Code
10664 \begin_layout Plain Layout
10670 implies the generation of specific LaTeX code, using the package
10673 \begin_inset Flex CharStyle:Code
10676 \begin_layout Plain Layout
10685 \begin_layout Description
10686 \begin_inset Flex CharStyle:Code
10689 \begin_layout Plain Layout
10695 The font used for the text body .
10697 \begin_inset CommandInset ref
10699 reference "sec:fonts"
10706 \begin_layout Description
10708 \begin_inset Flex CharStyle:Code
10711 \begin_layout Plain Layout
10719 The level of the style in the table of contents.
10720 This is used for automatic numbering of section headings.
10723 \begin_layout Description
10724 \begin_inset Flex CharStyle:Code
10727 \begin_layout Plain Layout
10734 \begin_inset Flex CharStyle:Code
10737 \begin_layout Plain Layout
10743 ] The vertical space with which the very first of a chain of paragraphs
10744 with this layout is separated from the previous paragraph.
10745 If the previous paragraph has another layout, the separations are not simply
10746 added, but the maximum is taken.
10749 \begin_layout Subsection
10753 \begin_layout Standard
10754 \begin_inset CommandInset label
10760 Since version 1.3.0 of LyX, it is has been both possible and necessary to
10761 define the floats (
10762 \begin_inset Flex CharStyle:MenuItem
10765 \begin_layout Plain Layout
10772 \begin_inset Flex CharStyle:MenuItem
10775 \begin_layout Plain Layout
10781 , \SpecialChar \ldots{}
10782 ) in the text class itself.
10783 Standard floats are included in the file
10784 \begin_inset Flex CharStyle:Code
10787 \begin_layout Plain Layout
10793 , so you may have to do no more than add
10796 \begin_layout LyX-Code
10797 Input stdfloats.inc
10800 \begin_layout Standard
10801 to your layout file.
10802 If you want to implement a text class that proposes some other float types
10803 (like the AGU class bundled with LyX), the information below will hopefully
10807 \begin_layout Description
10808 \begin_inset Flex CharStyle:Code
10811 \begin_layout Plain Layout
10818 \begin_inset Flex CharStyle:Code
10821 \begin_layout Plain Layout
10828 \begin_inset Quotes erd
10832 \begin_inset Quotes erd
10835 ] The file name extension of an auxiliary file for the list of figures (or
10837 LaTeX writes the captions to this file.
10840 \begin_layout Description
10841 \begin_inset Flex CharStyle:Code
10844 \begin_layout Plain Layout
10851 \begin_inset Flex CharStyle:Code
10854 \begin_layout Plain Layout
10861 \begin_inset Quotes erd
10865 \begin_inset Quotes erd
10868 ] The string that will be used in the menus and also for the caption.
10871 \begin_layout Description
10872 \begin_inset Flex CharStyle:Code
10875 \begin_layout Plain Layout
10882 \begin_inset Flex CharStyle:Code
10885 \begin_layout Plain Layout
10894 \begin_inset Flex CharStyle:Code
10897 \begin_layout Plain Layout
10904 \begin_inset Flex CharStyle:Code
10907 \begin_layout Plain Layout
10913 if the float is already defined by the LaTeX document class.
10915 \begin_inset Flex CharStyle:Code
10918 \begin_layout Plain Layout
10924 , the float will be defined using the LaTeX package
10925 \begin_inset Flex CharStyle:Code
10928 \begin_layout Plain Layout
10937 \begin_layout Description
10938 \begin_inset Flex CharStyle:Code
10941 \begin_layout Plain Layout
10948 \begin_inset Flex CharStyle:Code
10951 \begin_layout Plain Layout
10958 \begin_inset Quotes erd
10962 \begin_inset Quotes erd
10965 ] The heading used for the list of floats.
10968 \begin_layout Description
10969 \begin_inset Flex CharStyle:Code
10972 \begin_layout Plain Layout
10979 \begin_inset Flex CharStyle:Code
10982 \begin_layout Plain Layout
10989 \begin_inset Quotes erd
10993 \begin_inset Quotes erd
10996 ] This (optional) argument determines whether floats of this class will
10997 be numbered within some sectional unit of the document.
10998 For example, if within is equal to
10999 \begin_inset Flex CharStyle:Code
11002 \begin_layout Plain Layout
11008 , the floats will be numbered within chapters.
11012 \begin_layout Description
11013 \begin_inset Flex CharStyle:Code
11016 \begin_layout Plain Layout
11023 \begin_inset Flex CharStyle:Code
11026 \begin_layout Plain Layout
11033 \begin_inset Quotes erd
11037 \begin_inset Quotes erd
11040 ] The default placement for the given class of floats.
11041 The string should be as in standard LaTeX:
11042 \begin_inset Flex CharStyle:Code
11045 \begin_layout Plain Layout
11052 \begin_inset Flex CharStyle:Code
11055 \begin_layout Plain Layout
11062 \begin_inset Flex CharStyle:Code
11065 \begin_layout Plain Layout
11072 \begin_inset Flex CharStyle:Code
11075 \begin_layout Plain Layout
11081 for top, bottom, page, and here, respectively.
11085 \begin_layout Plain Layout
11086 Note that the order of these letters in the string is irrelevant, like in
11092 On top of that there is a new type,
11093 \begin_inset Flex CharStyle:Code
11096 \begin_layout Plain Layout
11102 , which does not really correspond to a float, since it means: put it
11103 \begin_inset Quotes eld
11107 \begin_inset Quotes erd
11111 Note however that the
11112 \begin_inset Flex CharStyle:Code
11115 \begin_layout Plain Layout
11121 specifier is special and, because of implementation details, cannot be
11122 used in non-builtin float types.
11123 If you do not understand what this means, just use
11124 \begin_inset Quotes eld
11128 \begin_inset Flex CharStyle:Code
11131 \begin_layout Plain Layout
11138 \begin_inset Quotes erd
11144 \begin_layout Description
11145 \begin_inset Flex CharStyle:Code
11148 \begin_layout Plain Layout
11155 \begin_inset Flex CharStyle:Code
11158 \begin_layout Plain Layout
11165 \begin_inset Quotes erd
11169 \begin_inset Quotes erd
11172 ] The style used when defining the float using
11173 \begin_inset Flex CharStyle:Code
11176 \begin_layout Plain Layout
11187 \begin_layout Description
11188 \begin_inset Flex CharStyle:Code
11191 \begin_layout Plain Layout
11198 \begin_inset Flex CharStyle:Code
11201 \begin_layout Plain Layout
11208 \begin_inset Quotes erd
11212 \begin_inset Quotes erd
11216 \begin_inset Quotes eld
11220 \begin_inset Quotes erd
11223 of the new class of floats, like program or algorithm.
11224 After the appropriate
11225 \begin_inset Flex CharStyle:Code
11228 \begin_layout Plain Layout
11237 \begin_inset Flex CharStyle:Code
11240 \begin_layout Plain Layout
11249 \begin_inset Flex CharStyle:Code
11252 \begin_layout Plain Layout
11263 \begin_layout Standard
11264 Note that defining a float with type
11265 \begin_inset Flex CharStyle:Code
11268 \begin_layout Plain Layout
11276 automatically defines the corresponding counter with name
11277 \begin_inset Flex CharStyle:Code
11280 \begin_layout Plain Layout
11291 \begin_layout Subsection
11292 Inset layouts and Flex insets
11295 \begin_layout Standard
11296 \begin_inset CommandInset label
11298 name "sec:charstyle"
11302 LyX has supported character styles since version 1.4.0; since version 1.6.0
11303 these are called Flex insets.
11307 \begin_layout Standard
11308 Furthermore, it is possible to define the general layout of many different
11310 Currently, InsetLayout can be used to customize the layout parameters
11311 for footnotes, marginal notes, note insets, ERT insets, branches, listings,
11312 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
11317 \begin_layout Standard
11318 Flex insets come in three different kinds:
11321 \begin_layout Itemize
11323 \begin_inset Flex CharStyle:Code
11326 \begin_layout Plain Layout
11332 ): These define semantic markup corresponding to such LaTeX commands as
11334 \begin_inset Flex CharStyle:Code
11337 \begin_layout Plain Layout
11346 \begin_inset Flex CharStyle:Code
11349 \begin_layout Plain Layout
11360 \begin_layout Itemize
11362 \begin_inset Flex CharStyle:Code
11365 \begin_layout Plain Layout
11371 ): These can be used to define custom collapsable insets, similar to ERT,
11372 footnote, and the like.
11375 \begin_layout Itemize
11377 \begin_inset Flex CharStyle:Code
11380 \begin_layout Plain Layout
11386 ): For use with DocBook classes.
11389 \begin_layout Standard
11391 \begin_inset Flex CharStyle:Code
11394 \begin_layout Plain Layout
11400 definition starting line is of the form
11403 \begin_layout LyX-Code
11404 InsetLayout <Type> <Name>
11407 \begin_layout Standard
11409 \begin_inset Flex CharStyle:Code
11412 \begin_layout Plain Layout
11419 \begin_inset Flex CharStyle:Code
11422 \begin_layout Plain Layout
11429 \begin_inset Flex CharStyle:Code
11432 \begin_layout Plain Layout
11439 \begin_inset Flex CharStyle:Code
11442 \begin_layout Plain Layout
11449 \begin_inset Flex CharStyle:Code
11452 \begin_layout Plain Layout
11459 \begin_inset Flex CharStyle:Code
11462 \begin_layout Plain Layout
11469 \begin_inset Flex CharStyle:Code
11472 \begin_layout Plain Layout
11479 \begin_inset Flex CharStyle:Code
11482 \begin_layout Plain Layout
11489 \begin_inset Flex CharStyle:Code
11492 \begin_layout Plain Layout
11499 \begin_inset Flex CharStyle:Code
11502 \begin_layout Plain Layout
11509 \begin_inset Flex CharStyle:Code
11512 \begin_layout Plain Layout
11519 \begin_inset Flex CharStyle:Code
11522 \begin_layout Plain Layout
11529 \begin_inset Flex CharStyle:Code
11532 \begin_layout Plain Layout
11539 \begin_inset Flex CharStyle:Code
11542 \begin_layout Plain Layout
11549 \begin_inset Flex CharStyle:Code
11552 \begin_layout Plain Layout
11559 \begin_inset Flex CharStyle:Code
11562 \begin_layout Plain Layout
11569 \begin_inset Flex CharStyle:Code
11572 \begin_layout Plain Layout
11580 \begin_inset Flex CharStyle:Code
11583 \begin_layout Plain Layout
11590 \begin_inset Flex CharStyle:Code
11593 \begin_layout Plain Layout
11600 \begin_inset Flex CharStyle:Code
11603 \begin_layout Plain Layout
11609 should have the form
11610 \begin_inset Flex CharStyle:Code
11613 \begin_layout Plain Layout
11620 \begin_inset Flex CharStyle:Code
11623 \begin_layout Plain Layout
11630 \begin_inset Flex CharStyle:Code
11633 \begin_layout Plain Layout
11640 \begin_inset Flex CharStyle:Code
11643 \begin_layout Plain Layout
11650 \begin_inset Flex CharStyle:Code
11653 \begin_layout Plain Layout
11660 \begin_inset Flex CharStyle:Code
11663 \begin_layout Plain Layout
11669 is any valid identifier.
11673 \begin_layout Standard
11675 \begin_inset Flex CharStyle:Code
11678 \begin_layout Plain Layout
11684 section can contain the following entries:
11687 \begin_layout Description
11688 \begin_inset Flex CharStyle:Code
11691 \begin_layout Plain Layout
11697 The color for the inset's background.
11698 These valid colors are defined in
11699 \begin_inset Flex CharStyle:Code
11702 \begin_layout Plain Layout
11711 \begin_layout Description
11712 \begin_inset Flex CharStyle:Code
11715 \begin_layout Plain Layout
11721 As with paragraph styles (see page
11722 \begin_inset CommandInset ref
11724 reference "des:CopyStyle"
11731 \begin_layout Description
11732 \begin_inset Flex CharStyle:Code
11735 \begin_layout Plain Layout
11742 \begin_inset Flex CharStyle:Code
11745 \begin_layout Plain Layout
11752 \begin_inset Flex CharStyle:Code
11755 \begin_layout Plain Layout
11762 \begin_inset Flex CharStyle:Code
11765 \begin_layout Plain Layout
11771 , describing the rendering style used for the inset's frame and buttons.
11772 Footnotes generally use
11773 \begin_inset Flex CharStyle:Code
11776 \begin_layout Plain Layout
11782 ; ERT insets generally use
11783 \begin_inset Flex CharStyle:Code
11786 \begin_layout Plain Layout
11792 ; and character styles use
11793 \begin_inset Flex CharStyle:Code
11796 \begin_layout Plain Layout
11805 \begin_layout Description
11806 \begin_inset Flex CharStyle:Code
11809 \begin_layout Plain Layout
11815 The font used for both the text body
11821 \begin_inset space ~
11825 \begin_inset CommandInset ref
11827 reference "sec:fonts"
11832 Note that defining this font automatically defines the
11833 \begin_inset Flex CharStyle:Code
11836 \begin_layout Plain Layout
11842 to the same value, so define this first and define
11843 \begin_inset Flex CharStyle:Code
11846 \begin_layout Plain Layout
11852 later if you want them to be different.
11855 \begin_layout Description
11856 \begin_inset Flex CharStyle:Code
11859 \begin_layout Plain Layout
11868 \begin_layout Description
11869 \begin_inset Flex CharStyle:Code
11872 \begin_layout Plain Layout
11878 As with paragraph styles (see page
11879 \begin_inset CommandInset ref
11880 LatexCommand pageref
11881 reference "des:FreeSpacing"
11888 \begin_layout Description
11889 \begin_inset Flex CharStyle:Code
11892 \begin_layout Plain Layout
11898 As with paragraph styles (see page
11899 \begin_inset CommandInset ref
11900 LatexCommand pageref
11901 reference "des:KeepEmpty"
11908 \begin_layout Description
11909 \begin_inset Flex CharStyle:Code
11912 \begin_layout Plain Layout
11918 What will be displayed on the button or elsewhere as the inset label.
11919 Some inset types (ERT and Branch) modify this label on the fly.
11922 \begin_layout Description
11923 \begin_inset Flex CharStyle:Code
11926 \begin_layout Plain Layout
11932 The font used for the label.
11934 \begin_inset space ~
11938 \begin_inset CommandInset ref
11940 reference "sec:fonts"
11945 Note that this definition can never appear before
11946 \begin_inset Flex CharStyle:Code
11949 \begin_layout Plain Layout
11955 , lest it be ineffective.
11958 \begin_layout Description
11959 \begin_inset Flex CharStyle:Code
11962 \begin_layout Plain Layout
11968 The name of the corresponding LaTeX stuff.
11969 Either the environment or command name.
11972 \begin_layout Description
11973 \begin_inset Flex CharStyle:Code
11976 \begin_layout Plain Layout
11982 The optional parameter for the corresponding
11983 \begin_inset Flex CharStyle:Code
11986 \begin_layout Plain Layout
11992 stuff, including possible bracket pairs like
11993 \begin_inset Flex CharStyle:Code
11996 \begin_layout Plain Layout
12003 This parameter cannot be changed from within LyX.
12006 \begin_layout Description
12007 \begin_inset Flex CharStyle:Code
12010 \begin_layout Plain Layout
12016 As with paragraph styles (see page
12017 \begin_inset CommandInset ref
12018 LatexCommand pageref
12019 reference "des:LatexType"
12026 \begin_layout Description
12027 \begin_inset Flex CharStyle:Code
12030 \begin_layout Plain Layout
12037 \begin_inset Flex CharStyle:Code
12040 \begin_layout Plain Layout
12047 \begin_inset Flex CharStyle:Code
12050 \begin_layout Plain Layout
12057 \begin_inset Flex CharStyle:Code
12060 \begin_layout Plain Layout
12067 \begin_inset Flex CharStyle:Code
12070 \begin_layout Plain Layout
12076 (indicating a dummy definition ending definitions of charstyles etc.).
12077 This entry is only meaningful for Flex (user definable) insets.
12080 \begin_layout Description
12081 \begin_inset Flex CharStyle:Code
12084 \begin_layout Plain Layout
12091 \begin_inset Flex CharStyle:Code
12094 \begin_layout Plain Layout
12103 \begin_inset Flex CharStyle:Code
12106 \begin_layout Plain Layout
12112 ] Whether fragile commands in this layout should be
12113 \begin_inset Flex CharStyle:Code
12116 \begin_layout Plain Layout
12129 whether this command should itself be protected.)
12132 \begin_layout Description
12133 \begin_inset Flex CharStyle:Code
12136 \begin_layout Plain Layout
12142 As with paragraph styles (see page
12143 \begin_inset CommandInset ref
12144 LatexCommand pageref
12145 reference "des:Preamble"
12152 \begin_layout Description
12153 \begin_inset Flex CharStyle:Code
12156 \begin_layout Plain Layout
12163 \begin_inset Flex CharStyle:Code
12166 \begin_layout Plain Layout
12172 ] As with paragraph styles (see page
12173 \begin_inset CommandInset ref
12174 LatexCommand pageref
12175 reference "des:Requires"
12182 \begin_layout Subsection
12186 \begin_layout Standard
12187 \begin_inset CommandInset label
12193 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12195 \begin_inset Flex CharStyle:MenuItem
12198 \begin_layout Plain Layout
12205 \begin_inset Flex CharStyle:MenuItem
12208 \begin_layout Plain Layout
12214 , \SpecialChar \ldots{}
12215 ) in the text class itself.
12216 The standard counters are defined in the file
12217 \begin_inset Flex CharStyle:Code
12220 \begin_layout Plain Layout
12226 , so you may have to do no more than add
12229 \begin_layout LyX-Code
12230 Input stdcounters.inc
12233 \begin_layout Standard
12234 to your layout file to get them to work.
12235 But if you want to define custom counters, then you can do so, using the
12236 following parameters:
12239 \begin_layout Description
12240 \begin_inset Flex CharStyle:Code
12243 \begin_layout Plain Layout
12244 LabelString [string=""]
12249 when this is defined, this string defines how the counter is displayed.
12250 Setting this value sets
12251 \begin_inset Flex CharStyle:Code
12254 \begin_layout Plain Layout
12255 LabelStringAppendix
12261 The following special constructs can be used in the string:
12265 \begin_layout Itemize
12266 \begin_inset Flex CharStyle:Code
12269 \begin_layout Plain Layout
12277 will be replaced by the expansion of the
12278 \begin_inset Flex CharStyle:Code
12281 \begin_layout Plain Layout
12288 \begin_inset Flex CharStyle:Code
12291 \begin_layout Plain Layout
12292 LabelStringAppendix
12298 \begin_inset Flex CharStyle:Code
12301 \begin_layout Plain Layout
12311 \begin_layout Itemize
12312 counter values can be expressed using LaTeX-like macros
12313 \begin_inset Flex CharStyle:Code
12316 \begin_layout Plain Layout
12333 \begin_inset Flex CharStyle:Code
12336 \begin_layout Plain Layout
12348 \begin_layout Plain Layout
12358 Actually, the situation is a bit more complicated: any
12377 other than those descibed below will produce arabic numerals.
12378 It would not be surprising to see this change in the future.
12384 \begin_inset Flex CharStyle:Code
12387 \begin_layout Plain Layout
12393 : 1, 2, 3,\SpecialChar \ldots{}
12395 \begin_inset Flex CharStyle:Code
12398 \begin_layout Plain Layout
12404 for lower-case letters: a, b, c, \SpecialChar \ldots{}
12406 \begin_inset Flex CharStyle:Code
12409 \begin_layout Plain Layout
12415 for upper-case letters: A, B, C, \SpecialChar \ldots{}
12417 \begin_inset Flex CharStyle:Code
12420 \begin_layout Plain Layout
12426 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12428 \begin_inset Flex CharStyle:Code
12431 \begin_layout Plain Layout
12437 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12439 \begin_inset Flex CharStyle:Code
12442 \begin_layout Plain Layout
12448 for hebrew numerals.
12452 \begin_layout Standard
12453 If LabelString is not defined, a default value is constructed as follows:
12454 if the counter has a master counter
12455 \begin_inset Flex CharStyle:Code
12458 \begin_layout Plain Layout
12465 \begin_inset Flex CharStyle:Code
12468 \begin_layout Plain Layout
12475 \begin_inset Flex CharStyle:Code
12478 \begin_layout Plain Layout
12488 is used; otherwise the string
12489 \begin_inset Flex CharStyle:Code
12492 \begin_layout Plain Layout
12503 \begin_layout Description
12504 \begin_inset Flex CharStyle:Code
12507 \begin_layout Plain Layout
12508 LabelStringAppendix [string=""]
12514 \begin_inset Flex CharStyle:Code
12517 \begin_layout Plain Layout
12526 \begin_layout Description
12527 \begin_inset Flex CharStyle:Code
12530 \begin_layout Plain Layout
12537 \begin_inset Flex CharStyle:Code
12540 \begin_layout Plain Layout
12547 \begin_inset Quotes erd
12551 \begin_inset Quotes erd
12554 ] The name of the counter.
12557 \begin_layout Description
12558 \begin_inset Flex CharStyle:Code
12561 \begin_layout Plain Layout
12568 \begin_inset Flex CharStyle:Code
12571 \begin_layout Plain Layout
12578 \begin_inset Quotes erd
12582 \begin_inset Quotes erd
12585 ] If this is set to the name of another counter, the present counter will
12586 be reset everytime the other one is increased.
12588 \begin_inset Flex CharStyle:Code
12591 \begin_layout Plain Layout
12598 \begin_inset Flex CharStyle:Code
12601 \begin_layout Plain Layout
12610 \begin_layout Subsection
12614 \begin_layout Standard
12615 \begin_inset CommandInset label
12621 A font description looks like this:
12624 \begin_layout LyX-Code
12634 \begin_layout LyX-Code
12638 \begin_layout LyX-Code
12642 \begin_layout Standard
12643 The following commands are available:
12646 \begin_layout Description
12647 \begin_inset Flex CharStyle:Code
12650 \begin_layout Plain Layout
12657 \begin_inset Flex CharStyle:Code
12660 \begin_layout Plain Layout
12669 \begin_inset Flex CharStyle:Code
12672 \begin_layout Plain Layout
12679 \begin_inset Flex CharStyle:Code
12682 \begin_layout Plain Layout
12689 \begin_inset Flex CharStyle:Code
12692 \begin_layout Plain Layout
12699 \begin_inset Flex CharStyle:Code
12702 \begin_layout Plain Layout
12709 \begin_inset Flex CharStyle:Code
12712 \begin_layout Plain Layout
12719 \begin_inset Flex CharStyle:Code
12722 \begin_layout Plain Layout
12729 \begin_inset Flex CharStyle:Code
12732 \begin_layout Plain Layout
12739 \begin_inset Flex CharStyle:Code
12742 \begin_layout Plain Layout
12751 \begin_layout Description
12752 \begin_inset Flex CharStyle:Code
12755 \begin_layout Plain Layout
12764 \begin_inset Flex CharStyle:Code
12767 \begin_layout Plain Layout
12778 \begin_inset Flex CharStyle:Code
12781 \begin_layout Plain Layout
12788 \begin_inset Flex CharStyle:Code
12791 \begin_layout Plain Layout
12800 \begin_layout Description
12801 \begin_inset Flex CharStyle:Code
12804 \begin_layout Plain Layout
12811 \begin_inset Flex CharStyle:Code
12814 \begin_layout Plain Layout
12820 ] Valid argument sare:
12821 \begin_inset Flex CharStyle:Code
12824 \begin_layout Plain Layout
12831 \begin_inset Flex CharStyle:Code
12834 \begin_layout Plain Layout
12841 \begin_inset Flex CharStyle:Code
12844 \begin_layout Plain Layout
12851 \begin_inset Flex CharStyle:Code
12854 \begin_layout Plain Layout
12861 \begin_inset Flex CharStyle:Code
12864 \begin_layout Plain Layout
12871 \begin_inset Flex CharStyle:Code
12874 \begin_layout Plain Layout
12881 Each of these turns on or off the corresponding attribute.
12884 \begin_layout Description
12885 \begin_inset Flex CharStyle:Code
12888 \begin_layout Plain Layout
12897 \begin_inset Flex CharStyle:Code
12900 \begin_layout Plain Layout
12911 \begin_inset Flex CharStyle:Code
12914 \begin_layout Plain Layout
12923 \begin_layout Description
12924 \begin_inset Flex CharStyle:Code
12927 \begin_layout Plain Layout
12936 \begin_inset Flex CharStyle:Code
12939 \begin_layout Plain Layout
12950 \begin_inset Flex CharStyle:Code
12953 \begin_layout Plain Layout
12960 \begin_inset Flex CharStyle:Code
12963 \begin_layout Plain Layout
12970 \begin_inset Flex CharStyle:Code
12973 \begin_layout Plain Layout
12982 \begin_layout Description
12983 \begin_inset Flex CharStyle:Code
12986 \begin_layout Plain Layout
12993 \begin_inset Flex CharStyle:Code
12996 \begin_layout Plain Layout
13003 \begin_inset Flex CharStyle:Code
13006 \begin_layout Plain Layout
13013 \begin_inset Flex CharStyle:Code
13016 \begin_layout Plain Layout
13025 \begin_inset Flex CharStyle:Code
13028 \begin_layout Plain Layout
13035 \begin_inset Flex CharStyle:Code
13038 \begin_layout Plain Layout
13045 \begin_inset Flex CharStyle:Code
13048 \begin_layout Plain Layout
13055 \begin_inset Flex CharStyle:Code
13058 \begin_layout Plain Layout
13065 \begin_inset Flex CharStyle:Code
13068 \begin_layout Plain Layout
13077 \begin_layout Subsection
13078 Upgrading old layout files
13081 \begin_layout Standard
13082 The file format of layout files changes from time to time, so old layout
13083 files need to be converted.
13084 This process has been automated since LyX 1.4.0: If LyX reads an old format
13085 layout file it will call the conversion tool
13086 \begin_inset Flex CharStyle:Code
13089 \begin_layout Plain Layout
13090 LyXDir/scripts/layout2layout.py
13095 and convert it to a temporary file in current format.
13096 The original file is left untouched.
13097 If you want to convert the layout file permanently, just call the converter
13101 \begin_layout LyX-Code
13102 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13105 \begin_layout Standard
13106 (You need to replace
13107 \begin_inset Flex CharStyle:Code
13110 \begin_layout Plain Layout
13116 with the name of your LyX system directory, unless you happen to have defined
13117 such an environment variable.) Then copy
13118 \begin_inset Flex CharStyle:Code
13121 \begin_layout Plain Layout
13128 \begin_inset Flex CharStyle:Code
13131 \begin_layout Plain Layout
13140 \begin_layout Standard
13141 The automatic conversion only handles syntax changes.
13142 It cannot handle the case where the contents of included files was changed,
13143 so these will have to be converted separately.
13146 \begin_layout Section
13148 \begin_inset CommandInset label
13150 name "sec:templates"
13157 \begin_layout Standard
13158 Templates are created just like usual documents.
13159 The only difference is that usual documents contain all possible settings,
13160 including the font scheme and the paper size.
13161 Usually a user doesn't want a template to overwrite his defaults in these
13163 For that reason, the designer of a template should remove the corresponding
13165 \begin_inset Flex CharStyle:Code
13168 \begin_layout Plain Layout
13177 \begin_inset Flex CharStyle:Code
13180 \begin_layout Plain Layout
13188 from the template LyX file.
13189 This can be done with any simple text-editor, for example
13190 \begin_inset Flex CharStyle:Code
13193 \begin_layout Plain Layout
13200 \begin_inset Flex CharStyle:Code
13203 \begin_layout Plain Layout
13213 \begin_layout Standard
13214 Put the edited template files you create in
13215 \begin_inset Flex CharStyle:Code
13218 \begin_layout Plain Layout
13224 , copy the ones you use from the global template directory in
13225 \begin_inset Flex CharStyle:Code
13228 \begin_layout Plain Layout
13234 to the same place, and redefine the template path in the
13235 \begin_inset Flex CharStyle:MenuItem
13238 \begin_layout Plain Layout
13246 \SpecialChar \menuseparator
13251 references\SpecialChar \menuseparator
13260 \begin_layout Standard
13261 Note that there is a template which has a particular meaning:
13262 \begin_inset Flex CharStyle:Code
13265 \begin_layout Plain Layout
13272 This template is loaded everytime you create a new document with
13273 \begin_inset Flex CharStyle:MenuItem
13276 \begin_layout Plain Layout
13286 \SpecialChar \menuseparator
13288 \begin_inset Flex CharStyle:MenuItem
13291 \begin_layout Plain Layout
13301 in order to provide useful defaults.
13302 To create this template from inside LyX, all you have to do is to open
13303 a document with the correct settings, and use the
13304 \begin_inset Flex CharStyle:MenuItem
13307 \begin_layout Plain Layout
13312 e as Document Defaults
13320 \begin_layout Chapter
13321 Including External Material
13324 \begin_layout Standard
13325 The use of material from sources external to LyX is covered in detail in
13331 This part of the manual covers what needs to happen behind the scenes for
13332 new sorts of material to be included.
13335 \begin_layout Section
13339 \begin_layout Standard
13340 The external material feature is based on the concept of a
13345 A template is a specification of how LyX should interface with a certain
13347 As bundled, LyX comes with predefined templates for Xfig figures, various
13348 raster format images, chess diagrams, and LilyPond music notation.
13349 You can check the actual list by using the menu
13350 \begin_inset Flex CharStyle:MenuItem
13353 \begin_layout Plain Layout
13354 Insert\SpecialChar \menuseparator
13355 File\SpecialChar \menuseparator
13362 Furthermore, it is possible to roll your own template to support a specific
13364 Later we'll describe in more detail what is involved, and hopefully you
13365 will submit all the templates you create so we can include them in a later
13369 \begin_layout Standard
13370 Another basic idea of the external material feature is to distinguish between
13371 the original file that serves as a base for final material and the produced
13372 file that is included in your exported or printed document.
13373 For example, consider the case of a figure produced with
13374 \begin_inset Flex CharStyle:Code
13377 \begin_layout Plain Layout
13384 The Xfig application itself works on an original file with the
13385 \begin_inset Flex CharStyle:Code
13388 \begin_layout Plain Layout
13395 Within XFig, you create and change your figure, and when you are done,
13397 \begin_inset Flex CharStyle:Code
13400 \begin_layout Plain Layout
13407 When you want to include the figure in your document, you invoke
13408 \begin_inset Flex CharStyle:Code
13411 \begin_layout Plain Layout
13417 in order to create a PostScript file that can readily be included in your
13420 \begin_inset Flex CharStyle:Code
13423 \begin_layout Plain Layout
13429 file is the original file, and the PostScript file is the produced file.
13432 \begin_layout Standard
13433 This distinction is important in order to allow updating of the material
13434 while you are in the process of writing the document.
13435 Furthermore, it provides us with the flexibility that is needed to support
13436 multiple export formats.
13437 For instance, in the case of a plain text file, it is not exactly an award-winn
13438 ing idea to include the figure as raw PostScript®.
13439 Instead, you'd either prefer to just include a reference to the figure
13440 or try to invoke some graphics to Ascii converter to make the final result
13441 look similar to the real graphics.
13442 The external material management allows you to do this, because it is parameter
13443 ized on the different export formats that LyX supports.
13446 \begin_layout Standard
13447 Besides supporting the production of different products according to the
13448 exported format, it supports tight integration with editing and viewing
13450 In the case of an XFig figure, you are able to invoke Xfig on the original
13451 file with a single click from within the external material dialog in LyX,
13452 and also preview the produced PostScript file with ghostview with another
13454 No more fiddling around with the command line and/or file browsers to locate
13455 and manipulate the original or produced files.
13456 In this way, you are finally able to take full advantage of the many different
13457 applications that are relevant to use when you write your documents, and
13458 ultimately be more productive.
13461 \begin_layout Section
13462 The external template configuration file
13465 \begin_layout Standard
13466 It is relatively easy to add custom external template definitions to LyX.
13467 However, be aware that doing this in an careless manner most probably
13471 introduce an easily exploitable security hole.
13472 So before you do this, please read the discussion about security in section
13474 \begin_inset CommandInset ref
13476 reference "sec:Security-discussion"
13483 \begin_layout Standard
13484 Having said that, we encourage you to submit any interesting templates that
13489 \begin_layout Standard
13490 The external templates are defined in the
13491 \begin_inset Flex CharStyle:Code
13494 \begin_layout Plain Layout
13495 LyXDir/lib/external_templates
13501 You can place your own version in
13502 \begin_inset Flex CharStyle:Code
13505 \begin_layout Plain Layout
13506 UserDir/external_templates
13514 \begin_layout Standard
13515 A typical template looks like this:
13518 \begin_layout LyX-Code
13522 \begin_layout LyX-Code
13523 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
13526 \begin_layout LyX-Code
13530 \begin_layout LyX-Code
13534 \begin_layout LyX-Code
13538 \begin_layout LyX-Code
13542 \begin_layout LyX-Code
13546 \begin_layout LyX-Code
13547 AutomaticProduction true
13550 \begin_layout LyX-Code
13554 \begin_layout LyX-Code
13558 \begin_layout LyX-Code
13562 \begin_layout LyX-Code
13563 TransformCommand Rotate RotationLatexCommand
13566 \begin_layout LyX-Code
13567 TransformCommand Resize ResizeLatexCommand
13570 \begin_layout LyX-Code
13571 Product "$$RotateFront$$ResizeFront
13574 \begin_layout LyX-Code
13579 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
13582 \begin_layout LyX-Code
13583 $$ResizeBack$$RotateBack"
13586 \begin_layout LyX-Code
13590 \begin_layout LyX-Code
13591 UpdateResult "$$AbsPath$$Basename.pstex_t"
13594 \begin_layout LyX-Code
13595 Requirement "graphicx"
13598 \begin_layout LyX-Code
13599 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
13602 \begin_layout LyX-Code
13603 ReferencedFile latex "$$AbsPath$$Basename.eps"
13606 \begin_layout LyX-Code
13607 ReferencedFile dvi "$$AbsPath$$Basename.eps"
13610 \begin_layout LyX-Code
13614 \begin_layout LyX-Code
13618 \begin_layout LyX-Code
13619 TransformCommand Rotate RotationLatexCommand
13622 \begin_layout LyX-Code
13623 TransformCommand Resize ResizeLatexCommand
13626 \begin_layout LyX-Code
13627 Product "$$RotateFront$$ResizeFront
13630 \begin_layout LyX-Code
13635 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
13638 \begin_layout LyX-Code
13639 $$ResizeBack$$RotateBack"
13642 \begin_layout LyX-Code
13643 UpdateFormat pdftex
13646 \begin_layout LyX-Code
13647 UpdateResult "$$AbsPath$$Basename.pdftex_t"
13650 \begin_layout LyX-Code
13651 Requirement "graphicx"
13654 \begin_layout LyX-Code
13655 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
13658 \begin_layout LyX-Code
13659 ReferencedFile latex "$$AbsPath$$Basename.pdf"
13662 \begin_layout LyX-Code
13666 \begin_layout LyX-Code
13670 \begin_layout LyX-Code
13671 Product "$$Contents(
13673 "$$AbsPath$$Basename.asc
13678 \begin_layout LyX-Code
13679 UpdateFormat asciixfig
13682 \begin_layout LyX-Code
13683 UpdateResult "$$AbsPath$$Basename.asc"
13686 \begin_layout LyX-Code
13690 \begin_layout LyX-Code
13694 \begin_layout LyX-Code
13695 Product "<graphic fileref=
13697 "$$AbsOrRelPathMaster$$Basename.eps
13702 \begin_layout LyX-Code
13706 \begin_layout LyX-Code
13710 \begin_layout LyX-Code
13711 UpdateResult "$$AbsPath$$Basename.eps"
13714 \begin_layout LyX-Code
13715 ReferencedFile docbook "$$AbsPath$$Basename.eps"
13718 \begin_layout LyX-Code
13719 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
13722 \begin_layout LyX-Code
13726 \begin_layout LyX-Code
13727 Product "[XFig: $$FName]"
13730 \begin_layout LyX-Code
13734 \begin_layout LyX-Code
13738 \begin_layout Standard
13739 As you can see, the template is enclosed in
13740 \begin_inset Flex CharStyle:Code
13743 \begin_layout Plain Layout
13749 \SpecialChar \ldots{}
13751 \begin_inset Flex CharStyle:Code
13754 \begin_layout Plain Layout
13761 It contains a header specifying some general settings and, for each supported
13762 primary document file format, a section
13763 \begin_inset Flex CharStyle:Code
13766 \begin_layout Plain Layout
13772 \SpecialChar \ldots{}
13774 \begin_inset Flex CharStyle:Code
13777 \begin_layout Plain Layout
13786 \begin_layout Subsection
13787 The template header
13790 \begin_layout Description
13791 \begin_inset Flex CharStyle:Code
13794 \begin_layout Plain Layout
13795 AutomaticProduction
13796 \begin_inset space ~
13804 Whether the file represented by the template must be generated by LyX.
13805 This command must occur exactly once.
13808 \begin_layout Description
13809 \begin_inset Flex CharStyle:Code
13812 \begin_layout Plain Layout
13814 \begin_inset space ~
13822 A glob pattern that is used in the file dialog to filter out the desired
13824 If there is more than one possible file extension (e.g.
13825 \begin_inset space ~
13829 \begin_inset Flex CharStyle:Code
13832 \begin_layout Plain Layout
13839 \begin_inset Flex CharStyle:Code
13842 \begin_layout Plain Layout
13848 ), use something like
13849 \begin_inset Flex CharStyle:Code
13852 \begin_layout Plain Layout
13859 This command must occur exactly once.
13862 \begin_layout Description
13863 \begin_inset Flex CharStyle:Code
13866 \begin_layout Plain Layout
13868 \begin_inset space ~
13876 The text that is displayed on the button.
13877 This command must occur exactly once.
13880 \begin_layout Description
13881 \begin_inset Flex CharStyle:Code
13884 \begin_layout Plain Layout
13886 \begin_inset space ~
13890 \begin_inset space ~
13898 The help text that is used in the External dialog.
13899 Provide enough information to explain to the user just what the template
13900 can provide him with.
13901 This command must occur exactly once.
13904 \begin_layout Description
13905 \begin_inset Flex CharStyle:Code
13908 \begin_layout Plain Layout
13910 \begin_inset space ~
13918 The file format of the original file.
13919 This must be the name of a format that is known to LyX (see section
13920 \begin_inset CommandInset ref
13922 reference "sub:Formats"
13928 \begin_inset Quotes eld
13932 \begin_inset Flex CharStyle:Code
13935 \begin_layout Plain Layout
13942 \begin_inset Quotes erd
13945 if the template can handle original files of more than one format.
13946 LyX will attempt to interrogate the file itself in order to deduce its
13947 format in this case.
13948 This command must occur exactly once.
13951 \begin_layout Description
13952 \begin_inset Flex CharStyle:Code
13955 \begin_layout Plain Layout
13957 \begin_inset space ~
13965 A unique name for the template.
13966 It must not contain substitution macros (see below).
13969 \begin_layout Description
13970 \begin_inset Flex CharStyle:Code
13973 \begin_layout Plain Layout
13975 \begin_inset space ~
13978 Rotate|Resize|Clip|Extra
13983 This command specifies which transformations are supported by this template.
13984 It may occur zero or more times.
13985 This command enables the corresponding tabs in the external dialog.
13987 \begin_inset Flex CharStyle:Code
13990 \begin_layout Plain Layout
13996 command must have either a corresponding
13997 \begin_inset Flex CharStyle:Code
14000 \begin_layout Plain Layout
14007 \begin_inset Flex CharStyle:Code
14010 \begin_layout Plain Layout
14017 \begin_inset Flex CharStyle:Code
14020 \begin_layout Plain Layout
14027 Otherwise the transformation will not be supported by that format.
14030 \begin_layout Subsection
14034 \begin_layout Description
14035 \begin_inset Flex CharStyle:Code
14038 \begin_layout Plain Layout
14040 \begin_inset space ~
14043 LaTeX|PDFLaTeX|PlainText|DocBook
14048 The primary document file format that this format definition is for.
14049 Not every template has a sensible representation in all document file formats.
14050 Please define nevertheless a
14051 \begin_inset Flex CharStyle:Code
14054 \begin_layout Plain Layout
14060 section for all formats.
14061 Use a dummy text when no representation is available.
14062 Then you can at least see a reference to the external material in the exported
14066 \begin_layout Description
14067 \begin_inset Flex CharStyle:Code
14070 \begin_layout Plain Layout
14072 \begin_inset space ~
14076 \begin_inset space ~
14084 This command defines an additional macro
14085 \begin_inset Flex CharStyle:Code
14088 \begin_layout Plain Layout
14094 for substitution in
14095 \begin_inset Flex CharStyle:Code
14098 \begin_layout Plain Layout
14106 \begin_inset Flex CharStyle:Code
14109 \begin_layout Plain Layout
14115 itself may contain substitution macros.
14116 The advantage over using
14117 \begin_inset Flex CharStyle:Code
14120 \begin_layout Plain Layout
14127 \begin_inset Flex CharStyle:Code
14130 \begin_layout Plain Layout
14136 is that the substituted value of
14137 \begin_inset Flex CharStyle:Code
14140 \begin_layout Plain Layout
14146 is sanitized so that it is a valid optional argument in the document format.
14147 This command may occur zero or more times.
14150 \begin_layout Description
14151 \begin_inset Flex CharStyle:Code
14154 \begin_layout Plain Layout
14156 \begin_inset space ~
14164 The text that is inserted in the exported document.
14165 This is actually the most important command and can be quite complex.
14166 This command must occur exactly once.
14169 \begin_layout Description
14170 \begin_inset Flex CharStyle:Code
14173 \begin_layout Plain Layout
14175 \begin_inset space ~
14183 This command specifies a preamble snippet that will be included in the
14185 It has to be defined using
14186 \begin_inset Flex CharStyle:Code
14189 \begin_layout Plain Layout
14195 \SpecialChar \ldots{}
14197 \begin_inset Flex CharStyle:Code
14200 \begin_layout Plain Layout
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 ~
14228 This command denotes files that are created by the conversion process and
14229 are needed for a particular export format.
14230 If the filename is relative, it is interpreted relative to the master document.
14231 This command may be given zero or more times.
14234 \begin_layout Description
14235 \begin_inset Flex CharStyle:Code
14238 \begin_layout Plain Layout
14240 \begin_inset space ~
14248 The name of a required LaTeX package.
14249 The package is included via
14250 \begin_inset Flex CharStyle:Code
14253 \begin_layout Plain Layout
14261 in the LaTeX preamble.
14262 This command may occur zero or more times.
14265 \begin_layout Description
14266 \begin_inset Flex CharStyle:Code
14269 \begin_layout Plain Layout
14271 \begin_inset space ~
14275 \begin_inset space ~
14278 RotationLatexCommand
14283 This command specifies that the built in LaTeX command should be used for
14285 This command may occur once or not at all.
14288 \begin_layout Description
14289 \begin_inset Flex CharStyle:Code
14292 \begin_layout Plain Layout
14294 \begin_inset space ~
14298 \begin_inset space ~
14306 This command specifies that the built in LaTeX command should be used for
14308 This command may occur once or not at all.
14311 \begin_layout Description
14312 \begin_inset Flex CharStyle:Code
14315 \begin_layout Plain Layout
14317 \begin_inset space ~
14321 \begin_inset space ~
14324 RotationLatexOption
14329 This command specifies that rotation is done via an optional argument.
14330 This command may occur once or not at all.
14333 \begin_layout Description
14334 \begin_inset Flex CharStyle:Code
14337 \begin_layout Plain Layout
14339 \begin_inset space ~
14343 \begin_inset space ~
14351 This command specifies that resizing is done via an optional argument.
14352 This command may occur once or not at all.
14355 \begin_layout Description
14356 \begin_inset Flex CharStyle:Code
14359 \begin_layout Plain Layout
14361 \begin_inset space ~
14365 \begin_inset space ~
14373 This command specifies that clipping is done via an optional argument.
14374 This command may occur once or not at all.
14377 \begin_layout Description
14378 \begin_inset Flex CharStyle:Code
14381 \begin_layout Plain Layout
14383 \begin_inset space ~
14387 \begin_inset space ~
14395 This command specifies that an extra optional argument is used.
14396 This command may occur once or not at all.
14399 \begin_layout Description
14400 \begin_inset Flex CharStyle:Code
14403 \begin_layout Plain Layout
14405 \begin_inset space ~
14413 The file format of the converted file.
14414 This must be the name of a format that is known to LyX (see the
14415 \begin_inset Flex CharStyle:MenuItem
14418 \begin_layout Plain Layout
14423 ools\SpecialChar \menuseparator
14428 references:Conversion
14434 This command must occur exactly once.
14437 \begin_layout Description
14438 \begin_inset Flex CharStyle:Code
14441 \begin_layout Plain Layout
14443 \begin_inset space ~
14451 The file name of the converted file.
14452 The file name must be absolute.
14453 This command must occur exactly once.
14456 \begin_layout Subsection
14457 Preamble definitions
14460 \begin_layout Standard
14461 The external template configuration file may contain additional preamble
14462 definitions enclosed by
14463 \begin_inset Flex CharStyle:Code
14466 \begin_layout Plain Layout
14472 \SpecialChar \ldots{}
14474 \begin_inset Flex CharStyle:Code
14477 \begin_layout Plain Layout
14484 They can be used by the templates in the
14485 \begin_inset Flex CharStyle:Code
14488 \begin_layout Plain Layout
14497 \begin_layout Section
14498 The substitution mechanism
14501 \begin_layout Standard
14502 When the external material facility invokes an external program, it is done
14503 on the basis of a command defined in the template configuration file.
14504 These commands can contain various macros that are expanded before execution.
14505 Execution always take place in the directory of the containing document.
14508 \begin_layout Standard
14509 Also, whenever external material is to be displayed, the name will be produced
14510 by the substitution mechanism, and most other commands in the template
14511 definition support substitution as well.
14514 \begin_layout Standard
14515 The available macros are the following:
14518 \begin_layout Description
14519 \begin_inset Flex CharStyle:Code
14522 \begin_layout Plain Layout
14523 $$AbsOrRelPathMaster
14528 The file path, absolute or relative to the master LyX document.
14531 \begin_layout Description
14532 \begin_inset Flex CharStyle:Code
14535 \begin_layout Plain Layout
14536 $$AbsOrRelPathParent
14541 The file path, absolute or relative to the LyX document.
14544 \begin_layout Description
14545 \begin_inset Flex CharStyle:Code
14548 \begin_layout Plain Layout
14554 The absolute file path.
14557 \begin_layout Description
14558 \begin_inset Flex CharStyle:Code
14561 \begin_layout Plain Layout
14567 The filename without path and without the extension.
14570 \begin_layout Description
14571 \begin_inset Flex CharStyle:Code
14574 \begin_layout Plain Layout
14576 \begin_inset Quotes eld
14580 \begin_inset Quotes erd
14588 This macro will expand to the contents of the file with the name
14589 \begin_inset Flex CharStyle:Code
14592 \begin_layout Plain Layout
14601 \begin_layout Description
14602 \begin_inset Flex CharStyle:Code
14605 \begin_layout Plain Layout
14611 The file extension (including the dot).
14614 \begin_layout Description
14615 \begin_inset Flex CharStyle:Code
14618 \begin_layout Plain Layout
14624 The filename of the file specified in the external material dialog.
14625 This is either an absolute name, or it is relative to the LyX document.
14628 \begin_layout Description
14629 \begin_inset Flex CharStyle:Code
14632 \begin_layout Plain Layout
14639 \begin_inset Flex CharStyle:Code
14642 \begin_layout Plain Layout
14648 (absolute name or relative to the LyX document).
14651 \begin_layout Description
14652 \begin_inset Flex CharStyle:Code
14655 \begin_layout Plain Layout
14661 The file path, relative to the master LyX document.
14664 \begin_layout Description
14665 \begin_inset Flex CharStyle:Code
14668 \begin_layout Plain Layout
14674 The file path, relative to the LyX document.
14677 \begin_layout Description
14678 \begin_inset Flex CharStyle:Code
14681 \begin_layout Plain Layout
14687 This macro will expand to the absolute path of the system directory.
14688 This is typically used to point to the various helper scripts that are
14692 \begin_layout Description
14693 \begin_inset Flex CharStyle:Code
14696 \begin_layout Plain Layout
14702 A name and full path to a temporary file which will be automatically deleted
14703 whenever the containing document is closed, or the external material insertion
14707 \begin_layout Standard
14708 All path macros contain a trailing directory separator, so you can construct
14710 the absolute filename with
14711 \begin_inset Flex CharStyle:Code
14714 \begin_layout Plain Layout
14715 $$AbsPath$$Basename$$Extension
14723 \begin_layout Standard
14724 The macros above are substituted in all commands unless otherwise noted.
14726 \begin_inset Flex CharStyle:Code
14729 \begin_layout Plain Layout
14735 supports additionally the following substitutions if they are enabled by
14737 \begin_inset Flex CharStyle:Code
14740 \begin_layout Plain Layout
14747 \begin_inset Flex CharStyle:Code
14750 \begin_layout Plain Layout
14759 \begin_layout Description
14760 \begin_inset Flex CharStyle:Code
14763 \begin_layout Plain Layout
14769 The front part of the resize command.
14772 \begin_layout Description
14773 \begin_inset Flex CharStyle:Code
14776 \begin_layout Plain Layout
14782 The back part of the resize command.
14785 \begin_layout Description
14786 \begin_inset Flex CharStyle:Code
14789 \begin_layout Plain Layout
14795 The front part of the rotation command.
14798 \begin_layout Description
14799 \begin_inset Flex CharStyle:Code
14802 \begin_layout Plain Layout
14808 The back part of the rotation command.
14811 \begin_layout Standard
14812 The value string of the
14813 \begin_inset Flex CharStyle:Code
14816 \begin_layout Plain Layout
14822 command supports additionally the following substitutions if they are enabled
14824 \begin_inset Flex CharStyle:Code
14827 \begin_layout Plain Layout
14834 \begin_inset Flex CharStyle:Code
14837 \begin_layout Plain Layout
14846 \begin_layout Description
14847 \begin_inset Flex CharStyle:Code
14850 \begin_layout Plain Layout
14859 \begin_layout Description
14860 \begin_inset Flex CharStyle:Code
14863 \begin_layout Plain Layout
14872 \begin_layout Description
14873 \begin_inset Flex CharStyle:Code
14876 \begin_layout Plain Layout
14885 \begin_layout Description
14886 \begin_inset Flex CharStyle:Code
14889 \begin_layout Plain Layout
14895 The rotation option.
14898 \begin_layout Standard
14899 You may ask why there are so many path macros.
14900 There are mainly two reasons:
14903 \begin_layout Enumerate
14904 Relative and absolute file names should remain relative or absolute, respectivel
14906 Users may have reasons to prefer either form.
14907 Relative names are useful for portable documents that should work on different
14908 machines, for example.
14909 Absolute names may be required by some programs.
14912 \begin_layout Enumerate
14913 LaTeX treats relative file names differently than LyX and other programs
14914 in nested included files.
14915 For LyX, a relative file name is always relative to the document that contains
14917 For LaTeX, it is always relative to the master document.
14918 These two definitions are identical if you have only one document, but
14919 differ if you have a master document that includes part documents.
14920 That means that relative filenames must be transformed when presented to
14922 Fortunately LyX does this automatically for you if you choose the right
14926 \begin_layout Standard
14927 So which path macro should be used in new template definitions? The rule
14931 \begin_layout Itemize
14933 \begin_inset Flex CharStyle:Code
14936 \begin_layout Plain Layout
14942 if an absolute path is required.
14945 \begin_layout Itemize
14947 \begin_inset Flex CharStyle:Code
14950 \begin_layout Plain Layout
14951 $$AbsOrRelPathMaster
14956 if the substituted string is some kind of LaTeX input.
14959 \begin_layout Itemize
14961 \begin_inset Flex CharStyle:Code
14964 \begin_layout Plain Layout
14965 $$AbsOrRelPathParent
14970 in order to preserve the user's choice.
14973 \begin_layout Standard
14974 There are special cases where this rule does not work and e.g.
14975 \begin_inset space ~
14978 relative names are needed, but normally it will work just fine.
14979 One example for such a case is the command
14980 \begin_inset Flex CharStyle:Code
14983 \begin_layout Plain Layout
14984 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14989 in the XFig template above: We can't use the absolute name because the
14991 \begin_inset Flex CharStyle:Code
14994 \begin_layout Plain Layout
15000 files needs the relative name in order to rewrite the file content.
15003 \begin_layout Section
15004 \begin_inset CommandInset label
15006 name "sec:Security-discussion"
15010 Security discussion
15013 \begin_layout Standard
15014 \begin_inset Note Note
15017 \begin_layout Plain Layout
15018 This section is outdated
15023 The external material feature interfaces with a lot of external programs
15024 and does so automatically, so we have to consider the security implications
15026 In particular, since you have the option of including your own filenames
15027 and/or parameter strings and those are expanded into a command, it seems
15028 that it would be possible to create a malicious document which executes
15029 arbitrary commands when a user views or prints the document.
15030 This is something we definately want to avoid.
15033 \begin_layout Standard
15034 However, since the external program commands are specified in the template
15035 configuration file only, there are no security issues if LyX is properly
15036 configured with safe templates only.
15037 This is so because the external programs are invoked with the
15038 \begin_inset Flex CharStyle:Code
15041 \begin_layout Plain Layout
15047 -system call rather than the
15048 \begin_inset Flex CharStyle:Code
15051 \begin_layout Plain Layout
15057 system-call, so it's not possible to execute arbitrary commands from the
15058 filename or parameter section via the shell.
15061 \begin_layout Standard
15062 This also implies that you are restricted in what command strings you can
15063 use in the external material templates.
15064 In particular, pipes and redirection are not readily available.
15065 This has to be so if LyX should remain safe.
15066 If you want to use some of the shell features, you should write a safe
15067 script to do this in a controlled manner, and then invoke the script from
15068 the command string.
15070 \begin_inset Flex CharStyle:Code
15073 \begin_layout Plain Layout
15079 directory of the LyX installation, you can find a safe wrapper script
15080 \begin_inset Flex CharStyle:Code
15083 \begin_layout Plain Layout
15084 general_command_wrapper.py
15089 that supports redirection of input and output.
15090 That can serve as an example for how to write safe template scripts.
15091 For a more advanced example that uses
15092 \begin_inset Flex CharStyle:Code
15095 \begin_layout Plain Layout
15101 and friends, take a look at the
15102 \begin_inset Flex CharStyle:Code
15105 \begin_layout Plain Layout
15114 \begin_layout Standard
15115 It is possible to design a template that interacts directly with the shell,
15116 but since this would allow a malicious user to execute arbitrary commands
15117 by writing clever filenames and/or parameters, we generally recommend that
15118 you only use safe scripts that work with the
15119 \begin_inset Flex CharStyle:Code
15122 \begin_layout Plain Layout
15128 system call in a controlled manner.
15129 Of course, for use in a controlled environment, it can be tempting to just
15130 fall back to use ordinary shell scripts.
15131 If you do so, be aware that you
15135 provide an easily exploitable security hole in your system.
15136 Of course it stands to reason that such unsafe templates will never be
15137 included in the standard LyX distribution, although we do encourage people
15138 to submit new templates in the open source tradition.
15139 But LyX as shipped from the official distribution channels will never have
15143 \begin_layout Standard
15144 Including external material provides a lot of power, and you have to be
15145 careful not to introduce security hazards with this power.
15146 A subtle error in a single line in an innocent looking script can open
15147 the door to huge security problems.
15148 So if you do not fully understand the issues, we recommend that you consult
15149 a knowledgable security professional or the LyX development team if you
15150 have any questions about whether a given template is safe or not.
15151 And do this before you use it in an uncontrolled environment.
15154 \begin_layout Chapter
15158 \begin_layout Section
15162 \begin_layout Standard
15163 The LyX server is a method implemented in LyX that will enable other programs
15164 to talk to LyX, invoke LyX commands, and retrieve information about the
15165 LyX internal state.
15166 This is only intended for advanced users, but they should find it useful.
15167 Please note that, at present,
15169 the server does not work on Windows
15175 \begin_layout Plain Layout
15176 There is no principled reason it cannot do so.
15177 But none of the developers on Windows® have yet implemented this functionality
15186 \begin_layout Section
15187 Starting the LyX Server
15190 \begin_layout Standard
15191 The LyX server works through the use of a pair of named pipes.
15192 These are usually located in
15193 \begin_inset Flex CharStyle:Code
15196 \begin_layout Plain Layout
15203 \begin_inset Quotes eld
15207 \begin_inset Flex CharStyle:Code
15210 \begin_layout Plain Layout
15217 \begin_inset Quotes erd
15221 \begin_inset Quotes eld
15225 \begin_inset Flex CharStyle:Code
15228 \begin_layout Plain Layout
15235 \begin_inset Quotes erd
15239 External programs write into
15240 \begin_inset Flex CharStyle:Code
15243 \begin_layout Plain Layout
15249 and read back data from
15250 \begin_inset Flex CharStyle:Code
15253 \begin_layout Plain Layout
15260 The stem of the pipe names can be defined in the
15261 \begin_inset Flex CharStyle:MenuItem
15264 \begin_layout Plain Layout
15269 ools\SpecialChar \menuseparator
15279 dialog, for example
15280 \begin_inset Flex CharStyle:Code
15283 \begin_layout Plain Layout
15284 "/home/myhome/.lyxpipe"
15292 \begin_layout Standard
15294 \begin_inset Flex CharStyle:Code
15297 \begin_layout Plain Layout
15304 \begin_inset Flex CharStyle:Code
15307 \begin_layout Plain Layout
15313 ' to create the pipes.
15314 The above setting also has the effect of activating the LyX server.
15315 If one of the pipes already exists, LyX will assume that another LyX process
15316 is already running and will not start the server.
15317 To have several LyX processes with servers at the same time, you have to
15318 change the configuration between the start of the programs.
15321 \begin_layout Standard
15322 If you are developing a client program, you might find it useful to enable
15323 debugging information from the LyX server.
15324 Do this by starting LyX as lyx -dbg lyxserver.
15327 \begin_layout Standard
15328 Warning: if LyX crashes, it may not manage to remove the pipes; in this
15329 case you must remove them manually.
15330 If LyX starts and the pipes exist already, it will not start any server.
15333 \begin_layout Standard
15334 Other than this, there are a few points to consider:
15337 \begin_layout Itemize
15338 Both server and clients must run on UNIX or OS/2 machines.
15339 Communications between LyX on UNIX and clients on OS/2 or vice versa is
15340 not possible right now.
15343 \begin_layout Itemize
15344 On OS/2, only one client can connect to LyXServer at a time.
15347 \begin_layout Itemize
15348 On OS/2, clients must open inpipe with
15349 \begin_inset Flex CharStyle:Code
15352 \begin_layout Plain Layout
15361 \begin_layout Standard
15365 \begin_layout Standard
15366 You can find a complete example client written in C in the source distribution
15368 \begin_inset Flex CharStyle:Code
15371 \begin_layout Plain Layout
15372 development/lyxserver/server_monitor.c
15380 \begin_layout Section
15381 Normal communication
15384 \begin_layout Standard
15385 To issue a LyX call, the client writes a line of ASCII text into the input
15387 This line has the following format:
15390 \begin_layout Quote
15404 \begin_layout Description
15409 is a name that the client can choose arbitrarily.
15410 Its only use is that LyX will echo it if it sends an answer---so a client
15411 can dispatch results from different requesters.
15414 \begin_layout Description
15419 is the function you want LyX to perform.
15420 It is the same as the commands you'd use in the minibuffer.
15423 \begin_layout Description
15428 is an optional argument which is meaningful only to some functions (for
15430 \begin_inset Quotes eld
15434 \begin_inset Quotes erd
15437 which will insert the argument as text at the cursor position.)
15440 \begin_layout Standard
15441 The answer from LyX will arrive in the output pipe and be of the form
15444 \begin_layout Quote
15458 \begin_layout Standard
15467 are just echoed from the command request, while
15471 is more or less useful information filled according to how the command
15472 execution worked out.
15473 Some commands will return information about the internal state of LyX,
15475 \begin_inset Quotes eld
15479 \begin_inset Quotes erd
15482 , while other will return an empty data-response.
15483 This means that the command execution went fine.
15486 \begin_layout Standard
15487 In case of errors, the response from LyX will have this form
15490 \begin_layout Quote
15504 \begin_layout Standard
15509 should contain an explanation of why the command failed.
15512 \begin_layout Standard
15516 \begin_layout LyX-Code
15517 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
15520 \begin_layout LyX-Code
15521 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
15522 \begin_inset Newline newline
15525 read a <~/.lyxpipe.out
15526 \begin_inset Newline newline
15532 \begin_layout Section
15536 \begin_layout Standard
15537 LyX can notify clients of events going on asynchronously.
15538 Currently it will only do this if the user binds a key sequence with the
15540 \begin_inset Quotes eld
15544 \begin_inset Quotes erd
15548 The format of the string LyX sends is as follows:
15551 \begin_layout Quote
15552 \begin_inset Flex CharStyle:Code
15555 \begin_layout Plain Layout
15566 \begin_layout Standard
15571 is the printed representation of the key sequence that was actually typed
15575 \begin_layout Standard
15576 This mechanism can be used to extend LyX's command set and implement macros:
15577 bind some key sequence to
15578 \begin_inset Quotes eld
15582 \begin_inset Quotes erd
15585 , start a client that listens on the out pipe, dispatches the command according
15586 to the sequence and starts a function that may use LyX calls and LyX requests
15587 to issue a command or a series of commands to LyX.
15590 \begin_layout Section
15591 The simple LyX Server Protocol
15594 \begin_layout Standard
15595 LyX implements a simple protocol that can be used for session management.
15596 All messages are of the form
15599 \begin_layout Quote
15609 \begin_layout Standard
15615 \begin_inset Quotes eld
15619 \begin_inset Quotes erd
15623 \begin_inset Quotes eld
15627 \begin_inset Quotes erd
15632 \begin_inset Quotes eld
15636 \begin_inset Quotes erd
15639 is received from a client, LyX will report back to inform the client that
15640 it's listening to it's messages, while
15641 \begin_inset Quotes eld
15645 \begin_inset Quotes erd
15648 sent from LyX will inform clients that LyX is closing.