1 #LyX 1.6.0svn created this file. For more info see http://www.lyx.org/
7 % DO NOT ALTER THIS PREAMBLE!!!
9 % This preamble is designed to ensure that the User's Guide prints
10 % out as advertised. If you mess with this preamble,
11 % parts of the User's Guide may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
49 InsetLayout CharStyle:MenuItem
58 \newcommand*{\menuitem}[1]{{\sffamily #1}}
66 \font_typewriter default
67 \font_default_family default
77 \pdf_title "LyX Configuration Manual"
78 \pdf_author "LyX Team"
79 \pdf_subject "LyX-documentation Customization"
80 \pdf_keywords "LyX, documentation, customization"
82 \pdf_bookmarksnumbered true
83 \pdf_bookmarksopen true
84 \pdf_bookmarksopenlevel 1
89 \pdf_pagebackref false
90 \pdf_pdfusetitle false
91 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
98 \paperorientation portrait
105 \paragraph_separation indent
107 \quotes_language english
110 \paperpagestyle headings
111 \tracking_changes false
112 \output_changes false
121 Customizing LyX: Features for the Advanced User
129 \begin_layout Plain Layout
131 If you have comments or error corrections, please send them to the LyX Documenta
133 \begin_inset CommandInset href
135 target "lyx-docs@lists.lyx.org"
148 \begin_layout Standard
149 \begin_inset CommandInset toc
150 LatexCommand tableofcontents
157 \begin_layout Chapter
161 \begin_layout Standard
162 This manual covers the customization features present in LyX.
163 In it, we discuss issues like keyboard shortcuts, screen previewing options,
164 printer options, sending commands to LyX via the LyX Server, internationalizati
165 on, installing new LaTeX classes and LyX layouts, etc.
166 We can't possibly hope to touch on everything you can change---our developers
167 add new features faster than we can document them---but we will explain
168 the most common customizations and hopefully point you in the right direction
169 for some of the more obscure ones.
172 \begin_layout Standard
173 \begin_inset Branch OutDated
176 \begin_layout Standard
177 Information from previous versions of this document that now seems to be
178 outdated is contained in the OutDated branch of this document.
179 By default, this information will not appear in the LaTeX output.
187 \begin_layout Chapter
188 LyX configuration files
191 \begin_layout Standard
192 This chapter aims to help you to find your way through the LyX configuration
194 Before continuing to read this chapter, you should find out where your
195 LyX library and user directories are by using
196 \begin_inset Flex CharStyle:MenuItem
199 \begin_layout Plain Layout
204 elp\SpecialChar \menuseparator
217 The library directory is the place where LyX places its system-wide configurati
218 on files; the user directory is where you can place your modified versions.
219 We will call the former
220 \begin_inset Flex CharStyle:Code
223 \begin_layout Plain Layout
230 \begin_inset Flex CharStyle:MenuItem
233 \begin_layout Plain Layout
239 in the remainder of this document.
243 \begin_layout Section
245 \begin_inset Flex CharStyle:Code
248 \begin_layout Plain Layout
257 \begin_layout Standard
258 \begin_inset Flex CharStyle:Code
261 \begin_layout Plain Layout
267 and its sub-directories contain a number of files and that can be used
268 to customise LyX's behaviour.
269 You can change many of these files from within LyX itself through the
270 \begin_inset Flex CharStyle:MenuItem
273 \begin_layout Plain Layout
278 ools\SpecialChar \menuseparator
289 Most customization that you will want to do in LyX is possible through
291 However, many other inner aspects of LyX can be customized by modifying
293 \begin_inset Flex CharStyle:Code
296 \begin_layout Plain Layout
303 These files fall in different categories, described in the following subsection
307 \begin_layout Subsection
308 Automatically generated files
311 \begin_layout Standard
312 The files, which are to be found in
313 \begin_inset Flex CharStyle:MenuItem
316 \begin_layout Plain Layout
322 , are generated when you configure LyX.
323 They contain various default values that are guessed by inspection.
324 In general, it is not a good idea to modify them, since they might be overwritt
328 \begin_layout Labeling
329 \labelwidthstring 00.00.0000
330 \begin_inset Flex CharStyle:Code
333 \begin_layout Plain Layout
339 contains defaults for various commands.
342 \begin_layout Labeling
343 \labelwidthstring 00.00.0000
344 \begin_inset Flex CharStyle:Code
347 \begin_layout Plain Layout
353 contains the list of packages that have been recognized by LyX.
354 It is currently unused by the LyX program itself, but the information extracted
355 , and more, is made available with
356 \begin_inset Flex CharStyle:MenuItem
359 \begin_layout Plain Layout
364 elp\SpecialChar \menuseparator
381 \begin_layout Labeling
382 \labelwidthstring 00.00.0000
383 \begin_inset Flex CharStyle:Code
386 \begin_layout Plain Layout
392 the list of text classes that have been found in your
393 \begin_inset Flex CharStyle:Code
396 \begin_layout Plain Layout
402 directories, along with the associated LaTeX document class and their descripti
406 \begin_layout Labeling
407 \labelwidthstring 00.00.0000
408 \begin_inset Flex CharStyle:Code
411 \begin_layout Plain Layout
417 the list of layout modules found in your
418 \begin_inset Flex CharStyle:Code
421 \begin_layout Plain Layout
430 \begin_layout Labeling
431 \labelwidthstring 00.00.0000
432 \begin_inset Flex CharStyle:Code
435 \begin_layout Plain Layout
441 lists of various sorts of LaTeX-related files found on your system
444 \begin_layout Labeling
445 \labelwidthstring 00.00.0000
446 \begin_inset Flex CharStyle:Code
449 \begin_layout Plain Layout
455 is automatically generated during configuration from the file
456 \begin_inset Flex CharStyle:Code
459 \begin_layout Plain Layout
466 It contains information on your LaTeX configuration.
469 \begin_layout Subsection
473 \begin_layout Standard
474 These directories are duplicated between
475 \begin_inset Flex CharStyle:Code
478 \begin_layout Plain Layout
485 \begin_inset Flex CharStyle:Code
488 \begin_layout Plain Layout
495 If a particular files exists in both places, the one in
496 \begin_inset Flex CharStyle:Code
499 \begin_layout Plain Layout
508 \begin_layout Labeling
509 \labelwidthstring 00.00.0000
510 \begin_inset Flex CharStyle:Code
513 \begin_layout Plain Layout
519 this directory contains files with the extension
520 \begin_inset Flex CharStyle:Code
523 \begin_layout Plain Layout
529 that define the keybindings used in LyX.
530 If there exists an internationalized version of the bind file named
531 \begin_inset Flex CharStyle:Code
534 \begin_layout Plain Layout
540 , that will be used first.
543 \begin_layout Labeling
544 \labelwidthstring 00.00.0000
545 \begin_inset Flex CharStyle:Code
548 \begin_layout Plain Layout
554 contains graphics files that can be included in documents.
558 \begin_layout Labeling
559 \labelwidthstring 00.00.0000
560 \begin_inset Flex CharStyle:Code
563 \begin_layout Plain Layout
569 contains LyX documentation files (including the one you are currently reading).
571 \begin_inset Flex CharStyle:Code
574 \begin_layout Plain Layout
580 deserves special attention, as noted above.
581 If there exists an internationalized version of the help-document with
583 \begin_inset Flex CharStyle:Code
586 \begin_layout Plain Layout
592 prepended to the name, that will be used first.
598 \begin_inset CommandInset ref
600 reference "chap:i18n"
607 \begin_layout Labeling
608 \labelwidthstring 00.00.0000
609 \begin_inset Flex CharStyle:Code
612 \begin_layout Plain Layout
618 contains example files that explain how to use some features.
619 In the file browser, press the
620 \begin_inset Flex CharStyle:MenuItem
623 \begin_layout Plain Layout
632 \begin_layout Labeling
633 \labelwidthstring 00.00.0000
634 \begin_inset Flex CharStyle:Code
637 \begin_layout Plain Layout
643 contains image files that are used by the
644 \begin_inset Flex CharStyle:MenuItem
647 \begin_layout Plain Layout
654 In addition, it also contains the individual icons used in the toolbar
655 and the banners that can be shown when LyX is launched.
658 \begin_layout Labeling
659 \labelwidthstring 00.00.0000
660 \begin_inset Flex CharStyle:Code
663 \begin_layout Plain Layout
669 contains keyboard keymapping files.
675 \begin_inset CommandInset ref
677 reference "sec:keymap"
684 \begin_layout Labeling
685 \labelwidthstring 00.00.0000
686 \begin_inset Flex CharStyle:Code
689 \begin_layout Plain Layout
695 contains the text class and module files described in Chapter
700 \begin_inset CommandInset ref
702 reference "chap:textclass"
709 \begin_layout Labeling
710 \labelwidthstring 00.00.0000
711 \begin_inset Flex CharStyle:Code
714 \begin_layout Plain Layout
721 \begin_inset Flex CharStyle:Code
724 \begin_layout Plain Layout
730 Python scripts used to convert between LyX versions.
731 These can be run from the command line if, say, you want to batch-convert
735 \begin_layout Labeling
736 \labelwidthstring 00.00.0000
737 \begin_inset Flex CharStyle:Code
740 \begin_layout Plain Layout
746 contains some files that demonstrate the capabilities of the
747 \begin_inset Flex CharStyle:MenuItem
750 \begin_layout Plain Layout
761 Also contains some scripts used by LyX itself.
764 \begin_layout Labeling
765 \labelwidthstring 00.00.0000
766 \begin_inset Flex CharStyle:Code
769 \begin_layout Plain Layout
775 contains the standard LyX template files described in Chapter
780 \begin_inset CommandInset ref
782 reference "sec:templates"
789 \begin_layout Labeling
790 \labelwidthstring 00.00.0000
791 \begin_inset Flex CharStyle:Code
794 \begin_layout Plain Layout
800 contains files with the extension
801 \begin_inset Flex CharStyle:Code
804 \begin_layout Plain Layout
810 that define the user interface to LyX.
811 That is, the files define which items appear in which menus and the items
812 appearing on the toolbar.
815 \begin_layout Subsection
816 Files you don't want to modify
819 \begin_layout Standard
820 These files are used internally by LyX and you generally do not need to
821 modify them unless you are a developer.
824 \begin_layout Labeling
825 \labelwidthstring 00.00.0000
826 \begin_inset Flex CharStyle:Code
829 \begin_layout Plain Layout
835 this file contains the list of LyX developers.
836 The contents are displayed with the menu entry
837 \begin_inset Flex CharStyle:MenuItem
840 \begin_layout Plain Layout
845 elp\SpecialChar \menuseparator
858 \begin_layout Labeling
859 \labelwidthstring 00.00.0000
860 \begin_inset Flex CharStyle:Code
863 \begin_layout Plain Layout
869 this is a LaTeX script used during the configuration process.
873 \begin_layout Labeling
874 \labelwidthstring 00.00.0000
875 \begin_inset Flex CharStyle:Code
878 \begin_layout Plain Layout
884 this is the script that is used to re-configure LyX.
885 It creates configuration files in the directory it was run from.
888 \begin_layout Subsection
889 Other files needing a line or two...
892 \begin_layout Labeling
893 \labelwidthstring 00.00.0000
894 \begin_inset Flex CharStyle:Code
897 \begin_layout Plain Layout
903 this contains tables describing how different character encodings can be
907 \begin_layout Labeling
908 \labelwidthstring 00.00.0000
909 \begin_inset Flex CharStyle:Code
912 \begin_layout Plain Layout
918 this file contains the templates available to the new
919 \begin_inset Flex CharStyle:MenuItem
922 \begin_layout Plain Layout
935 \begin_layout Labeling
936 \labelwidthstring 00.00.0000
937 \begin_inset Flex CharStyle:Code
940 \begin_layout Plain Layout
946 this file contains a list of all the languages currently supported by LyX.
949 \begin_layout Section
950 Your local configuration directory
953 \begin_layout Standard
954 Even if you are using LyX as an unprivileged user, you might want to change
955 LyX configuration for your own use.
957 \begin_inset Flex CharStyle:Code
960 \begin_layout Plain Layout
966 directory contains all your personal configuration files.
967 This is the directory described as
968 \begin_inset Quotes eld
972 \begin_inset Quotes erd
976 \begin_inset Flex CharStyle:MenuItem
979 \begin_layout Plain Layout
984 elp\SpecialChar \menuseparator
995 This directory is used as a mirror of
996 \begin_inset Flex CharStyle:Code
999 \begin_layout Plain Layout
1005 , which means that every file in
1006 \begin_inset Flex CharStyle:Code
1009 \begin_layout Plain Layout
1015 is a replacement for the corresponding file in
1016 \begin_inset Flex CharStyle:Code
1019 \begin_layout Plain Layout
1026 Any configuration file described in the above sections can be placed either
1027 in the system-wide directory, in which case it will affect all users, or
1028 in your local directory for your own use.
1031 \begin_layout Standard
1032 To make things clearer, let's provide a few examples:
1035 \begin_layout Itemize
1036 The preferences set in the
1037 \begin_inset Flex CharStyle:MenuItem
1040 \begin_layout Plain Layout
1045 ools\SpecialChar \menuseparator
1055 dialog are saved to a file
1056 \begin_inset Flex CharStyle:Code
1059 \begin_layout Plain Layout
1066 \begin_inset Flex CharStyle:Code
1069 \begin_layout Plain Layout
1078 \begin_layout Itemize
1079 When you reconfigure using
1080 \begin_inset Flex CharStyle:MenuItem
1083 \begin_layout Plain Layout
1088 ools\SpecialChar \menuseparator
1099 \begin_inset Flex CharStyle:Code
1102 \begin_layout Plain Layout
1108 script, and the resulting files are written in your local configuration
1110 This means that any additional text class file that you might have added
1112 \begin_inset Flex CharStyle:Code
1115 \begin_layout Plain Layout
1121 will be added to the list of classes in the
1122 \begin_inset Flex CharStyle:MenuItem
1125 \begin_layout Plain Layout
1130 ocument\SpecialChar \menuseparator
1143 \begin_layout Itemize
1144 If you get some updated documentation from LyX ftp site and cannot install
1145 it because you do not have sysadmin rights on your system, you can just
1147 \begin_inset Flex CharStyle:Code
1150 \begin_layout Plain Layout
1156 and the items in the
1157 \begin_inset Flex CharStyle:MenuItem
1160 \begin_layout Plain Layout
1170 menu will open them!
1173 \begin_layout Section
1174 Running LyX with multiple configurations
1177 \begin_layout Standard
1178 The configuration freedom of the local configuration directory may not suffice
1179 if you want to have more than one configuration at your disposal.
1180 For example, you may want to be use different key bindings or printer settings
1182 You can achieve this by having several such directories.
1183 You then specify which directory to use at run-time.
1186 \begin_layout Standard
1187 Invoking LyX with the command line switch
1188 \begin_inset Flex CharStyle:Code
1191 \begin_layout Plain Layout
1201 instructs the program to read the configuration from that directory, and
1202 not from the default directory.
1203 (You can determine the default directory by running LyX without the
1204 \begin_inset Flex CharStyle:Code
1207 \begin_layout Plain Layout
1213 switch.) If the specified directory does not exist, LyX offers to create
1214 it for you, just like it does for the default directory on the first time
1215 you run the program.
1216 You can modify the configuration options in this additional user directory
1217 exactly as you would for the default directory.
1218 These directories are completely independent (but read on).
1219 Note that setting the environment variable
1220 \begin_inset Flex CharStyle:Code
1223 \begin_layout Plain Layout
1229 to some value has exactly the same effect.
1232 \begin_layout Standard
1233 Having several configurations also requires more maintenance: if you want
1234 to add a new layout to
1235 \begin_inset Flex CharStyle:Code
1238 \begin_layout Plain Layout
1244 which you want available from all your configurations, you must add it
1245 to each directory separately.
1246 You can avoid this with the following trick: after LyX creates the additional
1247 directory, most of the subdirectories (see above) are empty.
1248 If you want the new configuration to mirror an existing one, replace the
1249 empty subdirectory with a symbolic link to the matching subdirectory in
1250 the existing configuration.
1252 \begin_inset Flex CharStyle:Code
1255 \begin_layout Plain Layout
1261 subirectory, however, since it contains a file written by the configuration
1262 script (also accessible through
1263 \begin_inset Flex CharStyle:MenuItem
1266 \begin_layout Plain Layout
1271 ools\SpecialChar \menuseparator
1281 ) which is configuration-specific.
1284 \begin_layout Chapter
1285 The Preferences dialog
1288 \begin_layout Standard
1289 All options of the preferences dialog are described in the Appendix
1291 The Preferences Dialog
1298 For some options you might find here more details.
1301 \begin_layout Section
1302 Using the dialog for the first time
1305 \begin_layout Standard
1307 \begin_inset Flex CharStyle:Code
1310 \begin_layout Plain Layout
1316 file will contain only changes that you have made to the default behavior,
1317 some of which is hard-coded into LyX and some of which is contained in
1319 \begin_inset Flex CharStyle:Code
1322 \begin_layout Plain Layout
1323 LyXDir/lyxrc.defaults
1329 Note that in both files lines beginning with a
1330 \begin_inset Quotes eld
1334 \begin_inset Quotes erd
1337 are just comments and are not interpreted.
1338 However, only system administrators should edit
1339 \begin_inset Flex CharStyle:Code
1342 \begin_layout Plain Layout
1343 LyXDir/lyxrc.defaults
1349 Users should use the
1350 \begin_inset Flex CharStyle:MenuItem
1353 \begin_layout Plain Layout
1354 Tools\SpecialChar \menuseparator
1360 dialog to create and modify their own
1361 \begin_inset Flex CharStyle:Code
1364 \begin_layout Plain Layout
1373 \begin_layout Standard
1375 \begin_inset Flex CharStyle:MenuItem
1378 \begin_layout Plain Layout
1379 Tools\SpecialChar \menuseparator
1385 dialog will be largely self-explanatory.
1386 Most things in the dialog have associated `tool tips': hover your mouse
1387 pointer over something for more information.
1388 Before we highlight a few of the more important commands below, however,
1389 a word of warning: Applying some of your changes (e.g., screen fonts) will
1390 have an instant effect.
1392 changing the bind file) will not.
1393 If nothing appears to have changed, just
1394 \begin_inset Flex CharStyle:MenuItem
1397 \begin_layout Plain Layout
1403 the changes and restart LyX.
1406 \begin_layout Section
1410 \begin_layout Standard
1411 LyX has a powerful mechanism to convert to and from any file format using
1416 \begin_layout Subsection
1417 \begin_inset CommandInset label
1426 \begin_layout Standard
1427 The first step is to define your file formats if they are not already defined.
1429 \begin_inset Flex CharStyle:MenuItem
1432 \begin_layout Plain Layout
1433 Tools\SpecialChar \menuseparator
1434 Preferences\SpecialChar \menuseparator
1435 File Handling\SpecialChar \menuseparator
1443 \begin_inset Flex CharStyle:MenuItem
1446 \begin_layout Plain Layout
1447 New\SpecialChar \ldots{}
1453 button to define your new format.
1455 \begin_inset Flex CharStyle:MenuItem
1458 \begin_layout Plain Layout
1464 field contains the named used to identify the format in the GUI.
1466 \begin_inset Flex CharStyle:MenuItem
1469 \begin_layout Plain Layout
1475 is used to identify the format interally.
1476 You will also need to enter a file extension.
1477 These are all required.
1479 \begin_inset Flex CharStyle:MenuItem
1482 \begin_layout Plain Layout
1488 field is used to provide a keyboard shortcut on the menus.
1489 (For example, pressing
1490 \begin_inset Flex CharStyle:MenuItem
1493 \begin_layout Plain Layout
1500 \begin_inset Flex CharStyle:MenuItem
1503 \begin_layout Plain Layout
1504 View\SpecialChar \menuseparator
1513 \begin_layout Standard
1515 \begin_inset Flex CharStyle:MenuItem
1518 \begin_layout Plain Layout
1525 \begin_inset Flex CharStyle:MenuItem
1528 \begin_layout Plain Layout
1535 For example, you might want to use
1536 \begin_inset Flex CharStyle:MenuItem
1539 \begin_layout Plain Layout
1545 to view PostScript files.
1546 You can enter the command needed to start the program in the corresponding
1548 In defining this command, you can use the four variables listed in the
1550 The viewer is launched when you view an image in LyX or use the
1551 \begin_inset Flex CharStyle:MenuItem
1554 \begin_layout Plain Layout
1561 The editor is for example launched when you press the
1562 \begin_inset Flex CharStyle:MenuItem
1565 \begin_layout Plain Layout
1572 \begin_inset Flex CharStyle:MenuItem
1575 \begin_layout Plain Layout
1582 \begin_inset Flex CharStyle:MenuItem
1585 \begin_layout Plain Layout
1594 \begin_layout Standard
1596 \begin_inset Flex CharStyle:MenuItem
1599 \begin_layout Plain Layout
1605 option tells LyX that a format is suitable for document export.
1606 If this is is set and if a suitable conversion route exists (see
1607 \begin_inset CommandInset ref
1609 reference "sub:Converters"
1613 ), the format will appear in the
1614 \begin_inset Flex CharStyle:MenuItem
1617 \begin_layout Plain Layout
1618 File\SpecialChar \menuseparator
1625 The format will also appear in the
1626 \begin_inset Flex CharStyle:MenuItem
1629 \begin_layout Plain Layout
1635 menu if a viewer is specified for the format.
1636 Pure image formats, such as
1637 \begin_inset Flex CharStyle:Code
1640 \begin_layout Plain Layout
1646 , should not use this option.
1647 Formats that can both represent vector graphics and documents like
1648 \begin_inset Flex CharStyle:Code
1651 \begin_layout Plain Layout
1660 \begin_layout Standard
1662 \begin_inset Flex CharStyle:MenuItem
1665 \begin_layout Plain Layout
1666 Vector graphics format
1671 tells LyX that a format can contain vector graphics.
1672 This information is used to determine the target format of included graphics
1674 \begin_inset Flex CharStyle:MenuItem
1677 \begin_layout Plain Layout
1684 Included graphics may need to be converted to either
1685 \begin_inset Flex CharStyle:MenuItem
1688 \begin_layout Plain Layout
1695 \begin_inset Flex CharStyle:MenuItem
1698 \begin_layout Plain Layout
1705 \begin_inset Flex CharStyle:MenuItem
1708 \begin_layout Plain Layout
1715 \begin_inset Flex CharStyle:MenuItem
1718 \begin_layout Plain Layout
1724 cannot handle other image formats.
1725 If an included graphic is not already in
1726 \begin_inset Flex CharStyle:MenuItem
1729 \begin_layout Plain Layout
1736 \begin_inset Flex CharStyle:MenuItem
1739 \begin_layout Plain Layout
1746 \begin_inset Flex CharStyle:MenuItem
1749 \begin_layout Plain Layout
1755 format, it is converted to
1756 \begin_inset Flex CharStyle:MenuItem
1759 \begin_layout Plain Layout
1765 if the vector format option is set, and otherwise to
1766 \begin_inset Flex CharStyle:MenuItem
1769 \begin_layout Plain Layout
1778 \begin_layout Subsection
1782 \begin_layout Standard
1783 Since all conversions from one format to another take place in LyX's temporary
1784 directory, it is sometimes necessary to modify a file before copying it
1785 to the temporary directory in order that the conversion may be performed.
1789 \begin_layout Plain Layout
1790 For example, the file may refer to other files---images, for example---using
1791 relative file names, and these may become invalid when the file is copied
1792 to the temporary directory.
1797 This is done by a Copier: It copies a file to (or from) the temporary directory
1798 and may modify it in the process.
1801 \begin_layout Standard
1802 The definitions of the copiers may use four variables:
1805 \begin_layout Labeling
1806 \labelwidthstring 00.00.0000
1807 \begin_inset Flex CharStyle:Code
1810 \begin_layout Plain Layout
1816 The LyX system directory (e.
1817 \begin_inset space \thinspace{}
1821 \begin_inset space ~
1825 \begin_inset Flex CharStyle:MenuItem
1828 \begin_layout Plain Layout
1837 \begin_layout Labeling
1838 \labelwidthstring 00.00.0000
1839 \begin_inset Flex CharStyle:Code
1842 \begin_layout Plain Layout
1851 \begin_layout Labeling
1852 \labelwidthstring 00.00.0000
1853 \begin_inset Flex CharStyle:Code
1856 \begin_layout Plain Layout
1865 \begin_layout Labeling
1866 \labelwidthstring 00.00.0000
1867 \begin_inset Flex CharStyle:Code
1870 \begin_layout Plain Layout
1879 \begin_layout Standard
1880 The latter is to be given in a form suitable for inclusion in a LaTeX's
1887 command and is relevant only when exporting files suitable for such inclusion.
1890 \begin_layout Standard
1891 Copiers can be used to do almost anything with output files.
1892 For example, suppose you want generated pdf files to be copied to a special
1894 \begin_inset Flex CharStyle:Code
1897 \begin_layout Plain Layout
1904 Then you could write a shell script such as this one:
1907 \begin_layout Standard
1908 \begin_inset listings
1912 \begin_layout Plain Layout
1917 \begin_layout Plain Layout
1922 \begin_layout Plain Layout
1924 TOFILE=`basename $2`
1927 \begin_layout Plain Layout
1929 cp $FROMFILE /home/you/pdf/$TOFILE
1934 Save that in your local LyX directory---say,
1935 \begin_inset Flex CharStyle:Code
1938 \begin_layout Plain Layout
1939 /home/you/.lyx/scripts/pdfcopier.sh
1944 ---and make it executable, if you need to do so on your platform.
1946 \begin_inset Flex CharStyle:MenuItem
1949 \begin_layout Plain Layout
1950 Tools\SpecialChar \menuseparator
1957 \begin_inset Flex CharStyle:MenuItem
1960 \begin_layout Plain Layout
1966 format---or one of the other pdf formats---and enter
1967 \begin_inset Flex CharStyle:Code
1970 \begin_layout Plain Layout
1971 pdfcopier.sh $$i $$o
1977 \begin_inset Flex CharStyle:MenuItem
1980 \begin_layout Plain Layout
1990 \begin_layout Standard
1991 Copiers are used by LyX in various of its own conversions.
1992 For example, if appropriate programs are found, LyX will automatically
1993 install copiers for the
1994 \begin_inset Flex CharStyle:MenuItem
1997 \begin_layout Plain Layout
2004 \begin_inset Flex CharStyle:MenuItem
2007 \begin_layout Plain Layout
2009 \begin_inset space ~
2018 When these formats are exported, the copier sees that not just the main
2019 HTML file but various associated files (style files, images, etc.) are also
2021 All these files are written to a subdirectory of the directory in which
2022 the original LyX file was found.
2026 \begin_layout Plain Layout
2027 This copier can be customized.
2029 \begin_inset Quotes eld
2033 \begin_inset Quotes erd
2036 argument takes a comma-separated list of extensions to be copied; if it
2037 is omitted, all files will be copied.
2039 \begin_inset Quotes eld
2043 \begin_inset Quotes erd
2046 argument determines the extension added to the generated directory.
2048 \begin_inset Quotes eld
2052 \begin_inset Flex CharStyle:MenuItem
2055 \begin_layout Plain Layout
2062 \begin_inset Quotes erd
2065 , so HTML generated from
2066 \begin_inset Flex CharStyle:MenuItem
2069 \begin_layout Plain Layout
2070 /path/to/filename.lyx
2076 \begin_inset Flex CharStyle:MenuItem
2079 \begin_layout Plain Layout
2080 /path/to/filename.html.LyXconv
2094 \begin_layout Subsection
2095 \begin_inset CommandInset label
2097 name "sub:Converters"
2104 \begin_layout Standard
2105 You can define your own Converters to, uhh, convert files between different
2108 \begin_inset Flex CharStyle:MenuItem
2111 \begin_layout Plain Layout
2112 Tools\SpecialChar \menuseparator
2113 Preferences\SpecialChar \menuseparator
2114 File Handling\SpecialChar \menuseparator
2123 \begin_layout Standard
2124 To define a new converter, select the
2125 \begin_inset Flex CharStyle:MenuItem
2128 \begin_layout Plain Layout
2130 \begin_inset space ~
2139 \begin_inset space \thinspace{}
2143 \begin_inset Flex CharStyle:MenuItem
2146 \begin_layout Plain Layout
2148 \begin_inset space ~
2156 from the drop-down lists, enter the command needed for the conversion,
2158 \begin_inset Flex CharStyle:MenuItem
2161 \begin_layout Plain Layout
2168 Several variables can be used in the definition of converters:
2171 \begin_layout Labeling
2172 \labelwidthstring 00.00.0000
2173 \begin_inset Flex CharStyle:Code
2176 \begin_layout Plain Layout
2182 The LyX system directory
2185 \begin_layout Labeling
2186 \labelwidthstring 00.00.0000
2187 \begin_inset Flex CharStyle:Code
2190 \begin_layout Plain Layout
2199 \begin_layout Labeling
2200 \labelwidthstring 00.00.0000
2201 \begin_inset Flex CharStyle:Code
2204 \begin_layout Plain Layout
2213 \begin_layout Labeling
2214 \labelwidthstring 00.00.0000
2215 \begin_inset Flex CharStyle:Code
2218 \begin_layout Plain Layout
2224 The base filename of the input file (i.e., without the extension)
2227 \begin_layout Labeling
2228 \labelwidthstring 00.00.0000
2229 \begin_inset Flex CharStyle:Code
2232 \begin_layout Plain Layout
2238 The path to the input file
2241 \begin_layout Standard
2243 \begin_inset Flex CharStyle:MenuItem
2246 \begin_layout Plain Layout
2248 \begin_inset space ~
2256 field you can enter the following flags, separated by commas:
2259 \begin_layout Labeling
2260 \labelwidthstring 00.00.0000
2261 \begin_inset Flex CharStyle:Code
2264 \begin_layout Plain Layout
2270 This converter runs some form of LaTeX.
2271 This will make LyX's LaTeX error logs available.
2274 \begin_layout Labeling
2275 \labelwidthstring 00.00.0000
2276 \begin_inset Flex CharStyle:Code
2279 \begin_layout Plain Layout
2286 \begin_inset Flex CharStyle:MenuItem
2289 \begin_layout Plain Layout
2295 file for the conversion.
2298 \begin_layout Labeling
2299 \labelwidthstring 00.00.0000
2300 \begin_inset Flex CharStyle:Code
2303 \begin_layout Plain Layout
2312 \begin_layout Standard
2313 The following three flags are not really flags at all because they take
2315 \begin_inset Flex CharStyle:MenuItem
2318 \begin_layout Plain Layout
2320 \begin_inset space ~
2324 \begin_inset space ~
2335 \begin_layout Labeling
2336 \labelwidthstring 00.00.0000
2337 \begin_inset Flex CharStyle:Code
2340 \begin_layout Plain Layout
2346 If set, the converter's standard error will be redirected to a file
2347 \begin_inset Flex CharStyle:Code
2350 \begin_layout Plain Layout
2356 , and the script given as argument will be run as:
2357 \begin_inset Flex CharStyle:Code
2360 \begin_layout Plain Layout
2361 script <infile.out >infile.log
2367 The argument may contain
2368 \begin_inset Flex CharStyle:Code
2371 \begin_layout Plain Layout
2380 \begin_layout Labeling
2381 \labelwidthstring 00.00.0000
2382 \begin_inset Flex CharStyle:Code
2385 \begin_layout Plain Layout
2391 The name of the directory in which the converter will dump the generated
2393 LyX will not create this directory, and it does not copy anything into
2394 it, though it will copy this directory to the destination.
2395 The argument may contain
2396 \begin_inset Flex CharStyle:Code
2399 \begin_layout Plain Layout
2405 , which will be replaced by the base name of the input and output files,
2406 respectively, when the directory is copied.
2407 \begin_inset Newline newline
2410 Note that resultdir and usetempdir make no sense together.
2411 The latter will be ignored if the former is given.
2414 \begin_layout Labeling
2415 \labelwidthstring 00.00.0000
2416 \begin_inset Flex CharStyle:Code
2419 \begin_layout Plain Layout
2425 Determines the output file name and may, contain
2426 \begin_inset Flex CharStyle:Code
2429 \begin_layout Plain Layout
2436 Sensible only with resultdir and optional even then; if not given, it defaults
2440 \begin_layout Standard
2441 None of these last three are presently used in any of the converters that
2442 are installed with LyX.
2446 \begin_layout Standard
2447 You do not have to define converters between all the formats between which
2448 you want to convert.
2449 For example, you will note that there is no `LyX to PostScript®' converter,
2450 but LyX will export PostScript®.
2451 It does so by first creating a LaTeX file (no converter needs to be defined
2452 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2453 and finally converting the resulting DVI file to PostScript®.
2454 LyX finds such `chains' of converters automatically, and it will always
2455 choose the shortest possible chain.
2456 You can, though, still define multiple conversion methods between file
2458 For example, the standard LyX configuration provides three ways to convert
2459 LaTeX to PDF: Directly, using
2460 \begin_inset Flex CharStyle:MenuItem
2463 \begin_layout Plain Layout
2469 ; via (DVI and) PostScript®, using
2470 \begin_inset Flex CharStyle:MenuItem
2473 \begin_layout Plain Layout
2480 \begin_inset Flex CharStyle:MenuItem
2483 \begin_layout Plain Layout
2490 To define such alternate chains, you must define multiple target `file
2491 formats', as described in section
2492 \begin_inset CommandInset ref
2494 reference "sub:Formats"
2499 For example, in the standard configuration, the formats named
2500 \begin_inset Flex CharStyle:MenuItem
2503 \begin_layout Plain Layout
2510 \begin_inset Flex CharStyle:MenuItem
2513 \begin_layout Plain Layout
2520 \begin_inset Flex CharStyle:MenuItem
2523 \begin_layout Plain Layout
2529 are defined, all of which share the extension
2530 \begin_inset Flex CharStyle:MenuItem
2533 \begin_layout Plain Layout
2539 , and which correspond to the conversion methods just mentioned.
2542 \begin_layout Chapter
2543 Internationalizing LyX
2544 \begin_inset CommandInset label
2553 \begin_layout Standard
2554 LyX supports using a translated interface.
2555 Last time we checked, LyX provided text in thirty languages.
2556 The language of choice is called your
2561 (For further reading on locale settings, see also the documentation for
2562 locale that comes with your operating system.
2563 For Linux, the manual page for
2564 \begin_inset Flex CharStyle:Code
2567 \begin_layout Plain Layout
2573 could be a good place to start).
2576 \begin_layout Standard
2577 Notice that these translations will work, but do contain a few flaws.
2578 In particular, all dialogs have been designed with the English text in
2579 mind, which means that some of the translated text will be too large to
2580 fit within the space allocated.
2581 This is only a display problem and will not cause any harm.
2582 Also, you will find that some of the translations do not define shortcut
2583 keys for everything.
2584 Sometimes, there are simply not enough free letters to do it.
2585 Other times, the translator just hasn't got around to doing it yet.
2586 Our localization team, which you may wish to join,
2590 \begin_layout Plain Layout
2591 If you are a fluent speaker of a language other than English, joining these
2592 teams is a great way to give back to the LyX community!
2597 will of course try to fix these shortcomings in future versions of LyX.
2600 \begin_layout Section
2604 \begin_layout Subsection
2605 Translating the graphical user interface (text messages).
2608 \begin_layout Standard
2610 \begin_inset Flex CharStyle:Code
2613 \begin_layout Plain Layout
2619 library to handle the internationalization of the interface.
2620 To have LyX speak your favorite language in all menus and dialogs, you
2622 \begin_inset Flex CharStyle:Code
2625 \begin_layout Plain Layout
2631 -file for that language.
2632 When this is available, you'll have to generate a
2633 \begin_inset Flex CharStyle:Code
2636 \begin_layout Plain Layout
2642 -file from it and install the
2643 \begin_inset Flex CharStyle:Code
2646 \begin_layout Plain Layout
2653 The process of doing all of this is explained in the documentation for
2655 \begin_inset Flex CharStyle:Code
2658 \begin_layout Plain Layout
2665 It is possible to do this just for yourself, but if you're going to do
2666 it, you might as well share the results of your labors with the rest of
2668 Send a message to the LyX developers' list for more information about how
2672 \begin_layout Standard
2673 In short, this is what you should do (xx denotes the language code):
2676 \begin_layout Itemize
2677 Check out the LyX source code.
2679 \begin_inset CommandInset href
2681 name "information on the web"
2682 target "http://www.lyx.org/devel/cvs.php"
2689 \begin_layout Itemize
2691 \begin_inset Flex CharStyle:Code
2694 \begin_layout Plain Layout
2700 to the folder of the
2701 \begin_inset Flex CharStyle:Code
2704 \begin_layout Plain Layout
2712 \begin_inset Flex CharStyle:Code
2715 \begin_layout Plain Layout
2723 \begin_inset Flex CharStyle:Code
2726 \begin_layout Plain Layout
2732 doesn't exist anywhere, it can be remade with the console command
2733 \begin_inset Flex CharStyle:Code
2736 \begin_layout Plain Layout
2742 in that directory, or you can use an existing po-file for some other language
2746 \begin_layout Itemize
2748 \begin_inset Flex CharStyle:Code
2751 \begin_layout Plain Layout
2761 \begin_layout Plain Layout
2762 This is just a text file, so it can be edited in any text editor.
2763 But there are also specialized programs that support such editing, such
2768 (for all platforms) or
2777 contains a `mode' for editing
2778 \begin_inset Flex CharStyle:Code
2781 \begin_layout Plain Layout
2792 For some menu- and widget-labels, there are also shortcut keys that should
2794 Those keys are marked after a `|', and should be translated according to
2795 the words and phrases of the language.
2796 You should also fill also out the information at the beginning of the new
2798 \begin_inset Flex CharStyle:Code
2801 \begin_layout Plain Layout
2807 -file with your email-address, etc., so people know where to reach you with
2808 suggestions and entertaining flames.
2811 \begin_layout Standard
2812 If you are just doing this on your own, then:
2815 \begin_layout Itemize
2817 \begin_inset Flex CharStyle:Code
2820 \begin_layout Plain Layout
2827 This can be done with
2828 \begin_inset Flex CharStyle:Code
2831 \begin_layout Plain Layout
2832 msgfmt -o xx.mo < xx.po
2840 \begin_layout Itemize
2842 \begin_inset Flex CharStyle:Code
2845 \begin_layout Plain Layout
2851 -file to your locale-tree, at the correct directory for application messages
2856 xx, and under the name
2857 \begin_inset Flex CharStyle:Code
2860 \begin_layout Plain Layout
2868 \begin_inset Flex CharStyle:Code
2871 \begin_layout Plain Layout
2872 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2882 \begin_layout Standard
2883 As said, however, it would be best if the new
2884 \begin_inset Flex CharStyle:Code
2887 \begin_layout Plain Layout
2893 -file could be added to the LyX distribution, so others can use it.
2894 Adding it involves making additional changes to LyX.
2895 So send an email to the developers' mailing list if you're interested in
2899 \begin_layout Subsubsection
2903 \begin_layout Standard
2904 Sometimes it turns out that one English message needs to be translated into
2905 different messages in the target language.
2906 One example is the message
2907 \begin_inset Flex CharStyle:Code
2910 \begin_layout Plain Layout
2916 which has the German translation
2924 , depending upon exactly what the English
2925 \begin_inset Quotes eld
2929 \begin_inset Quotes erd
2934 \begin_inset Flex CharStyle:Code
2937 \begin_layout Plain Layout
2943 does not handle such ambigous translations.
2944 Therefore you have to add some context information to the message: Instead
2946 \begin_inset Flex CharStyle:Code
2949 \begin_layout Plain Layout
2956 \begin_inset Flex CharStyle:Code
2959 \begin_layout Plain Layout
2960 To[[as in 'From format x to format y']]
2966 \begin_inset Flex CharStyle:Code
2969 \begin_layout Plain Layout
2970 To[[as in 'From page x to page y']].
2975 Now the two occurences of
2976 \begin_inset Flex CharStyle:Code
2979 \begin_layout Plain Layout
2986 \begin_inset Flex CharStyle:Code
2989 \begin_layout Plain Layout
2995 and can be translated correctly to
3006 \begin_layout Standard
3007 Of course the context information needs to be stripped off the original
3008 message when no translation is used.
3009 Therefore you have to put it in double square brackets at the end of the
3010 message (see the example above).
3011 The translation mechanism of LyX ensures that everything in double square
3012 brackets at the end of messages is removed before displaying the message.
3015 \begin_layout Subsection
3016 Translating the documentation.
3019 \begin_layout Standard
3020 The online documentation (in the
3021 \begin_inset Flex CharStyle:MenuItem
3024 \begin_layout Plain Layout
3034 -menu) can (and should!) be translated.
3035 If there are translated versions of the documentation available
3039 \begin_layout Plain Layout
3040 As of March 2008, at least some of the documents have been translated into
3041 fourteen languages, with the Tutorial available in a few more.
3046 and the locale is set accordingly, these will be used automagically by
3048 LyX looks for translated versions as
3049 \begin_inset Flex CharStyle:Code
3052 \begin_layout Plain Layout
3053 LyXDir/doc/xx_DocName.lyx
3059 \begin_inset Flex CharStyle:Code
3062 \begin_layout Plain Layout
3068 is the code for the language currently in use.
3069 If there are no translated documents, the default English versions will
3071 Note that the translated versions must have the same filenames (
3072 \begin_inset Flex CharStyle:Code
3075 \begin_layout Plain Layout
3081 above) as the original.
3082 If you feel up to translating the documentation (an excellent way to proof-read
3083 the original documentation by the way!), there are a few things you should
3087 \begin_layout Itemize
3089 \begin_inset Flex CharStyle:Code
3092 \begin_layout Plain Layout
3098 , the guide to writing LyX documentation.
3099 Pay special attention to the translator's section.
3102 \begin_layout Itemize
3103 Check out the documentation translation web page at
3104 \begin_inset CommandInset href
3106 name "http://www.lyx.org/Translation"
3107 target "http://www.lyx.org/Translation"
3112 That way, you can find out which (if any) documents have already been translate
3113 d into your language.
3114 You can also find out who (if anyone) is organizing the effort to translate
3115 the documentation into your language.
3116 If no one is organizing the effort, please let us know that you're interested.
3119 \begin_layout Standard
3120 Once you get to actually translating, here's a few hints for you that may
3124 \begin_layout Itemize
3125 Join the documentation team! There is information on how to do that in
3126 \begin_inset Flex CharStyle:Code
3129 \begin_layout Plain Layout
3136 \begin_inset Flex CharStyle:MenuItem
3139 \begin_layout Plain Layout
3144 elp\SpecialChar \menuseparator
3154 ), which by the way is the first document you should translate.
3157 \begin_layout Itemize
3158 Learn the typographic conventions for the language you are translating to.
3159 Typography is an ancient art and over the centuries, a great variety of
3160 conventions have developed throughout different parts of the world.
3161 Also study the professional terminology amongst typographers in your country.
3162 Inventing your own terminology will only confuse the users.
3165 (Warning! Typography is addictive!)
3168 \begin_layout Itemize
3169 Make a copy of the document.
3170 This will be your working copy.
3171 You can use this as your personal translated help-file by placing it in
3173 \begin_inset Flex CharStyle:Code
3176 \begin_layout Plain Layout
3185 \begin_layout Itemize
3186 Sometimes the original document (from the LyX-team) will be updated.
3187 Use the source viewer at
3188 \begin_inset CommandInset href
3190 name "http://www.lyx.org/trac/timeline"
3191 target "http://www.lyx.org/trac/timeline"
3195 to see what has been changed.
3196 That way you can easily see which parts of the translated document need
3200 \begin_layout Standard
3201 If you ever find an error in the original document, fix it and notify the
3202 rest of the documentation team of the changes! (You didn't forget to join
3203 the documentation team, did you?)
3206 \begin_layout Standard
3207 \begin_inset Branch OutDated
3210 \begin_layout Section
3211 International Keyboard Support
3214 \begin_layout Standard
3217 [Editor's Note: The following section is by
3225 It needs to be fixed to conform to the new Documentation Style sheet and
3226 to make use of the new v1.0 features.
3227 The whole thing also needs to be merged with the section following it.-jw
3228 It may also be badly out of date.-rh (2008)]
3231 \begin_layout Subsection
3232 Defining Own Keymaps: Keymap File Format
3235 \begin_layout Standard
3236 Let's look at a keyboard definition file a little closer.
3237 It is a plain text file defining
3240 \begin_layout Itemize
3241 key-to-key or key-to-string translations
3244 \begin_layout Itemize
3248 \begin_layout Itemize
3249 dead keys exceptions
3252 \begin_layout Standard
3253 To define key-to-key or key-to-string translation, use this command:
3256 \begin_layout Quotation
3257 \begin_inset Flex CharStyle:Code
3260 \begin_layout Plain Layout
3269 \begin_inset Flex CharStyle:Code
3272 \begin_layout Plain Layout
3281 \begin_layout Standard
3283 \begin_inset Flex CharStyle:Code
3286 \begin_layout Plain Layout
3292 is the key to be translated and
3293 \begin_inset Flex CharStyle:Code
3296 \begin_layout Plain Layout
3302 is the string to be inserted into the document.
3303 To define dead keys, use:
3306 \begin_layout Quotation
3307 \begin_inset Flex CharStyle:Code
3310 \begin_layout Plain Layout
3319 \begin_inset Flex CharStyle:Code
3322 \begin_layout Plain Layout
3331 \begin_layout Standard
3333 \begin_inset Flex CharStyle:Code
3336 \begin_layout Plain Layout
3342 is a keyboard key and
3343 \begin_inset Flex CharStyle:Code
3346 \begin_layout Plain Layout
3353 The following dead keys are supported (shortcut name is in parentheses):
3356 \begin_layout Quotation
3360 \begin_inset space \hfill{}
3366 \begin_layout Quotation
3368 \begin_inset space \hfill{}
3374 \begin_layout Quotation
3376 \begin_inset space \hfill{}
3382 \begin_layout Quotation
3384 \begin_inset space \hfill{}
3390 \begin_layout Quotation
3392 \begin_inset space \hfill{}
3398 \begin_layout Quotation
3400 \begin_inset space \hfill{}
3407 \begin_layout Plain Layout
3419 \begin_layout Quotation
3421 \begin_inset space \hfill{}
3427 \begin_layout Quotation
3429 \begin_inset space \hfill{}
3436 \begin_layout Plain Layout
3448 \begin_layout Quotation
3450 \begin_inset space \hfill{}
3456 \begin_layout Quotation
3458 \begin_inset space \hfill{}
3464 \begin_layout Quotation
3466 \begin_inset space \hfill{}
3473 \begin_layout Plain Layout
3485 \begin_layout Quotation
3487 \begin_inset space \hfill{}
3494 \begin_layout Plain Layout
3506 \begin_layout Quotation
3508 \begin_inset space \hfill{}
3514 \begin_layout Quotation
3515 hungarian umlaut (hug)
3516 \begin_inset space \hfill{}
3522 \begin_layout Quotation
3524 \begin_inset space \hfill{}
3530 \begin_layout Quotation
3532 \begin_inset space \hfill{}
3539 \begin_layout Plain Layout
3551 \begin_layout Standard
3552 Since in many international keyboards there are exceptions to what some
3553 dead keys should do, you can define them using
3556 \begin_layout Quotation
3557 \begin_inset Flex CharStyle:Code
3560 \begin_layout Plain Layout
3568 deadkey key outstring
3571 \begin_layout Standard
3572 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3576 \begin_layout Quotation
3577 \begin_inset Flex CharStyle:Code
3580 \begin_layout Plain Layout
3593 \begin_layout Standard
3594 to make it work correctly.
3595 Also, you have to define as exceptions dead keys over i and j, to remove
3596 the dot from them before inserting an accent mark.
3597 I will change this when the time comes, but so far I haven't had time.
3600 \begin_layout Standard
3601 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3604 \begin_inset Flex CharStyle:Code
3607 \begin_layout Plain Layout
3613 have different meaning.
3615 \begin_inset Flex CharStyle:Code
3618 \begin_layout Plain Layout
3624 marks comments, quotes start and end LaTeX-style commands.
3625 To enter quote, you'll need to use
3626 \begin_inset Flex CharStyle:Code
3629 \begin_layout Plain Layout
3638 \begin_inset Flex CharStyle:Code
3641 \begin_layout Plain Layout
3648 \begin_inset Flex CharStyle:Code
3651 \begin_layout Plain Layout
3662 \begin_layout Standard
3663 If you make a keyboard description file that works for your language, please
3664 mail it to me, so I can include it in the next keymap distribution.
3667 \begin_layout Standard
3668 More keywords will be supported in keymap configuration file in future,
3672 \begin_layout Itemize
3673 \begin_inset Flex CharStyle:Code
3676 \begin_layout Plain Layout
3687 \begin_inset space \hfill{}
3691 \begin_inset Flex CharStyle:Code
3694 \begin_layout Plain Layout
3703 \begin_layout Itemize
3704 \begin_inset Flex CharStyle:Code
3707 \begin_layout Plain Layout
3718 \begin_inset space \hfill{}
3722 \begin_inset Flex CharStyle:Code
3725 \begin_layout Plain Layout
3731 an external keymap translation program
3734 \begin_layout Standard
3735 Also, it should look into
3736 \begin_inset Flex CharStyle:Code
3739 \begin_layout Plain Layout
3745 file for defaults, too (for example, a
3746 \begin_inset Flex CharStyle:Code
3749 \begin_layout Plain Layout
3757 option to include default keyboard).
3765 \begin_layout Section
3766 \begin_inset CommandInset label
3772 International Keymap Stuff
3775 \begin_layout Standard
3776 \begin_inset Note Note
3779 \begin_layout Plain Layout
3780 In doing the revisions on this document in March 2008, I did not look over
3781 this stuff, as I do not understand it.
3782 It would be good if someone else could do so.
3790 \begin_layout Standard
3791 The next two sections describe the
3792 \begin_inset Flex CharStyle:Code
3795 \begin_layout Plain Layout
3804 \begin_inset Flex CharStyle:Code
3807 \begin_layout Plain Layout
3815 file syntax in detail.
3816 These sections should help you design your own key map if the ones provided
3817 do not meet your needs.
3820 \begin_layout Subsection
3824 \begin_layout Standard
3828 \begin_inset Flex CharStyle:Code
3831 \begin_layout Plain Layout
3837 file maps keystrokes to characters or strings.
3838 As the name suggests, it sets a keyboard mapping.
3840 \begin_inset Flex CharStyle:Code
3843 \begin_layout Plain Layout
3854 \begin_inset Flex CharStyle:Code
3857 \begin_layout Plain Layout
3872 \begin_inset Flex CharStyle:Code
3875 \begin_layout Plain Layout
3888 \begin_inset Flex CharStyle:Code
3891 \begin_layout Plain Layout
3900 \begin_inset Flex CharStyle:Code
3903 \begin_layout Plain Layout
3911 are described in this section.
3914 \begin_layout Labeling
3915 \labelwidthstring 00.00.0000
3916 \begin_inset Flex CharStyle:Code
3919 \begin_layout Plain Layout
3927 Map a character to a string
3930 \begin_layout LyX-Code
3945 \begin_layout Standard
3978 the double-quote (")
3995 must be escaped with a preceding backslash (
4006 \begin_layout Standard
4008 \begin_inset Flex CharStyle:MenuItem
4011 \begin_layout Plain Layout
4019 statement to cause the symbol
4020 \begin_inset Flex CharStyle:MenuItem
4023 \begin_layout Plain Layout
4031 to be output for the keystroke
4032 \begin_inset Flex CharStyle:MenuItem
4035 \begin_layout Plain Layout
4046 \begin_layout LyX-Code
4052 \begin_layout Labeling
4053 \labelwidthstring 00.00.0000
4054 \begin_inset Flex CharStyle:Code
4057 \begin_layout Plain Layout
4065 Specify an accent character
4068 \begin_layout LyX-Code
4077 \begin_layout Standard
4078 This will make the cha
4116 This is the dead key
4120 \begin_layout Plain Layout
4127 refers to a key that does not produce a character by itself, but when followed
4128 with another key, produces the desired accent character.
4129 For example, a German characte
4131 r with an umlaut like
4141 can be produced in this manner.
4150 \begin_layout Standard
4163 and then another key not in
4180 followed by the other, unallowed key, as output.
4184 \begin_inset Flex CharStyle:MenuItem
4187 \begin_layout Plain Layout
4195 cancels a dead key, so if
4206 \begin_inset Flex CharStyle:MenuItem
4209 \begin_layout Plain Layout
4218 , the cursor will not go one position backwards but will instead cancel
4234 might have had on the next keystroke.
4238 \begin_layout Standard
4239 The following example specifies that the character ' is to be an acute accent,
4240 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4243 \begin_layout LyX-Code
4246 kmod ' acute aeiouAEIOU
4249 \begin_layout Labeling
4250 \labelwidthstring 00.00.0000
4251 \begin_inset Flex CharStyle:Code
4254 \begin_layout Plain Layout
4260 Specify an exception to the accent character
4263 \begin_layout LyX-Code
4272 \begin_layout Standard
4273 This defines an exce
4314 have been assigned a keystroke with a previous
4317 \begin_inset Flex CharStyle:Code
4320 \begin_layout Plain Layout
4344 must not belong in the
4391 If such a declaration does not exist in
4399 \begin_inset Flex CharStyle:Code
4402 \begin_layout Plain Layout
4436 \begin_inset Flex CharStyle:Code
4439 \begin_layout Plain Layout
4453 \begin_layout Standard
4454 The following command produces causes äi to be produced when you enter acute-i
4458 \begin_layout LyX-Code
4472 \begin_layout Labeling
4473 \labelwidthstring 00.00.0000
4474 \begin_inset Flex CharStyle:Code
4477 \begin_layout Plain Layout
4483 Combine two accent characters
4486 \begin_layout LyX-Code
4492 accent1 accent2 allowed
4495 \begin_layout Standard
4496 This one is getting pretty esoteric.
4497 It allows you to combine the effect
4553 \begin_inset Flex CharStyle:Code
4556 \begin_layout Plain Layout
4584 \begin_layout Standard
4585 Consider this example from the
4586 \begin_inset Flex CharStyle:Code
4589 \begin_layout Plain Layout
4600 \begin_layout LyX-Code
4603 kmod ; acute aeioyvhAEIOYVH
4607 kcomb acute umlaut iyIY
4610 \begin_layout Standard
4611 This allows you to press
4612 \begin_inset Flex CharStyle:MenuItem
4615 \begin_layout Plain Layout
4623 and get the effect of
4624 \begin_inset Flex CharStyle:Code
4627 \begin_layout Plain Layout
4646 in this case cancels the last dead key, so if you press
4647 \begin_inset Flex CharStyle:MenuItem
4650 \begin_layout Plain Layout
4659 \begin_inset Flex CharStyle:Code
4662 \begin_layout Plain Layout
4675 \begin_layout Subsection
4679 \begin_layout Standard
4681 \begin_inset Flex CharStyle:Code
4684 \begin_layout Plain Layout
4692 mapping is performed, a
4693 \begin_inset Flex CharStyle:Code
4696 \begin_layout Plain Layout
4706 file maps the strings that the symbols generate to characters in the current
4708 The LyX distribution currently includes at least the
4709 \begin_inset Flex CharStyle:Code
4712 \begin_layout Plain Layout
4721 \begin_inset Flex CharStyle:Code
4724 \begin_layout Plain Layout
4735 \begin_layout Standard
4737 \begin_inset Flex CharStyle:Code
4740 \begin_layout Plain Layout
4748 file is a sequence of declarations of the form
4751 \begin_layout LyX-Code
4764 \begin_layout Standard
4765 For example, in order to map
4766 \begin_inset Flex CharStyle:MenuItem
4769 \begin_layout Plain Layout
4779 to the corresponding character in the iso-8859-1 set (233), the following
4783 \begin_layout LyX-Code
4791 \begin_layout Standard
4793 \begin_inset Flex CharStyle:Code
4796 \begin_layout Plain Layout
4805 \begin_inset Flex CharStyle:Code
4808 \begin_layout Plain Layout
4826 the same character can apply to more than one string.
4828 \begin_inset Flex CharStyle:Code
4831 \begin_layout Plain Layout
4842 \begin_layout LyX-Code
4854 \begin_inset Newline newline
4870 \begin_layout Standard
4871 If LyX cannot find a mapping for the string produced by the keystroke or
4872 a deadkey sequence, it will check if it looks like an accented char and
4873 try to draw an accent over the character on screen.
4876 \begin_layout Subsection
4880 \begin_layout Standard
4881 There is a second way to add support for international characters through
4882 so-called dead-keys.
4883 A dead-key works in combination with a letter to produce an accented character.
4884 Here, we'll explain how to create a really simple dead-key to illustrate
4888 \begin_layout Standard
4889 Suppose you happen to need the circumflex character,
4890 \begin_inset Quotes eld
4894 \begin_inset Quotes erd
4899 \begin_inset Flex CharStyle:MenuItem
4902 \begin_layout Plain Layout
4909 \begin_inset space ~
4913 \begin_inset Flex CharStyle:MenuItem
4916 \begin_layout Plain Layout
4922 ] to the LyX command
4923 \begin_inset Flex CharStyle:Code
4926 \begin_layout Plain Layout
4933 \begin_inset Flex CharStyle:Code
4936 \begin_layout Plain Layout
4943 Now, whenever you type the
4944 \begin_inset Flex CharStyle:MenuItem
4947 \begin_layout Plain Layout
4953 -key followed by a letter, that letter will have a circumflex accent on
4955 For example, the sequence
4956 \begin_inset Quotes eld
4960 \begin_inset Flex CharStyle:MenuItem
4963 \begin_layout Plain Layout
4970 \begin_inset Quotes erd
4973 produces the letter:
4974 \begin_inset Quotes eld
4978 \begin_inset Quotes erd
4982 If you tried to type
4983 \begin_inset Quotes eld
4987 \begin_inset Flex CharStyle:MenuItem
4990 \begin_layout Plain Layout
4997 \begin_inset Quotes erd
5000 , however, LyX will complain with a beep, since a
5001 \begin_inset Quotes eld
5005 \begin_inset Flex CharStyle:MenuItem
5008 \begin_layout Plain Layout
5015 \begin_inset Quotes erd
5018 never takes a circumflex accent.
5020 \begin_inset Flex CharStyle:MenuItem
5023 \begin_layout Plain Layout
5029 after a dead-key produces the bare-accent.
5030 Please note this last point! If you bind a key to a dead-key, you'll need
5031 to rebind the character on that key to yet another key.
5033 \begin_inset Flex CharStyle:MenuItem
5036 \begin_layout Plain Layout
5042 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5045 \begin_layout Standard
5046 One common way to bind dead-keys is to use
5047 \begin_inset Flex CharStyle:MenuItem
5050 \begin_layout Plain Layout
5057 \begin_inset Flex CharStyle:MenuItem
5060 \begin_layout Plain Layout
5067 \begin_inset Flex CharStyle:MenuItem
5070 \begin_layout Plain Layout
5076 in combination with an accent, like
5077 \begin_inset Quotes eld
5081 \begin_inset Flex CharStyle:MenuItem
5084 \begin_layout Plain Layout
5091 \begin_inset Quotes erd
5095 \begin_inset Quotes eld
5099 \begin_inset Flex CharStyle:MenuItem
5102 \begin_layout Plain Layout
5109 \begin_inset Quotes erd
5113 \begin_inset Quotes eld
5117 \begin_inset Flex CharStyle:MenuItem
5120 \begin_layout Plain Layout
5127 \begin_inset Quotes erd
5131 Another way involves using
5132 \begin_inset Flex CharStyle:Code
5135 \begin_layout Plain Layout
5142 \begin_inset Flex CharStyle:Code
5145 \begin_layout Plain Layout
5151 to set up the special
5152 \begin_inset Flex CharStyle:Code
5155 \begin_layout Plain Layout
5163 \begin_inset Flex CharStyle:Code
5166 \begin_layout Plain Layout
5172 acts in some ways just like
5173 \begin_inset Flex CharStyle:MenuItem
5176 \begin_layout Plain Layout
5182 and permits you to bind keys to accented characters.
5183 You can also turn keys into dead-keys by binding them to something like
5185 \begin_inset Flex CharStyle:Code
5188 \begin_layout Plain Layout
5194 and then binding this symbolic key to the corresponding LyX command.
5198 \begin_layout Plain Layout
5203 : This is exactly what I do in my
5204 \begin_inset Flex CharStyle:Code
5207 \begin_layout Plain Layout
5214 \begin_inset Flex CharStyle:Code
5217 \begin_layout Plain Layout
5225 \begin_inset Flex CharStyle:MenuItem
5228 \begin_layout Plain Layout
5230 \begin_inset space ~
5239 \begin_inset Flex CharStyle:Code
5242 \begin_layout Plain Layout
5248 and a bunch of these
5249 \begin_inset Quotes eld
5253 \begin_inset Flex CharStyle:Code
5256 \begin_layout Plain Layout
5263 \begin_inset Quotes erd
5266 symbolic keys bound such things as
5267 \begin_inset Flex CharStyle:MenuItem
5270 \begin_layout Plain Layout
5272 \begin_inset space ~
5281 \begin_inset Flex CharStyle:MenuItem
5284 \begin_layout Plain Layout
5286 \begin_inset space ~
5295 This is how I produce my accented characters.
5300 You can make just about anything into the
5301 \begin_inset Flex CharStyle:Code
5304 \begin_layout Plain Layout
5311 \begin_inset Flex CharStyle:MenuItem
5314 \begin_layout Plain Layout
5320 keys, a spare function key, etc.
5321 As for the LyX commands that produce accents, check the entry for
5322 \begin_inset Flex CharStyle:Code
5325 \begin_layout Plain Layout
5336 You'll find the complete list there.
5339 \begin_layout Subsection
5340 Saving your Language Configuration
5343 \begin_layout Standard
5344 You can edit your preferences so that your desired language environment
5345 is automatically configured when LyX starts up, via the
5346 \begin_inset Flex CharStyle:MenuItem
5349 \begin_layout Plain Layout
5354 dit\SpecialChar \menuseparator
5367 \begin_layout Chapter
5368 Installing New Document Classes, Layouts, and Templates
5369 \begin_inset CommandInset label
5371 name "chap:textclass"
5379 \begin_layout Plain Layout
5380 Installing New Document Classes
5388 \begin_layout Standard
5389 In this chapter, we describe the procedures for creating and installing
5390 new LyX layout and template files, as well as offer a refresher on correctly
5391 installing new LaTeX document classes.
5392 Some definitions: a document class is a LaTeX file (usually ending in
5393 \begin_inset Flex CharStyle:Code
5396 \begin_layout Plain Layout
5403 \begin_inset Flex CharStyle:Code
5406 \begin_layout Plain Layout
5412 ) that describes the format of a document such as an article, report, journal
5413 preprint, etc, and all the commands needed to realize that format.
5414 A layout file is a LyX file that corresponds to a LaTeX document class
5415 and that tells LyX how to
5416 \begin_inset Quotes eld
5420 \begin_inset Quotes erd
5423 things on the screen to make the display look something like the final
5425 More precisely, a layout file describes a
5426 \begin_inset Quotes eld
5430 \begin_inset Quotes erd
5433 which is the internal construct LyX uses to render the screen display.
5435 \begin_inset Quotes eld
5439 \begin_inset Quotes erd
5443 \begin_inset Quotes eld
5447 \begin_inset Quotes erd
5450 can be used somewhat interchangeably, but it is better to refer to the
5451 file as the layout, and the thing living in LyX's memory as the text class.
5452 A template file is simply a LyX document that contains a set of predefined
5453 entries for a given document class---entries that are generally required
5455 Templates are especially useful for things like journal manuscripts that
5456 are to be submitted electronically.
5459 \begin_layout Section
5460 Installing a new LaTeX package
5463 \begin_layout Standard
5464 Some installations may not include a LaTeX package that you would like to
5466 For example, you might need FoilTeX, a package for preparing slides or
5467 viewgraphs for overhead projectors.
5468 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5469 a user interface for that.
5470 For example on MiKTeX you start its program
5471 \begin_inset Quotes eld
5475 \begin_inset Quotes erd
5478 to get a list of available packages.
5479 To install one, right click on it or use the installing toolbar button.
5480 When the package you want to install is not in the list, but you have it
5482 \begin_inset Flex CharStyle:Code
5485 \begin_layout Plain Layout
5492 \begin_inset Flex CharStyle:Code
5495 \begin_layout Plain Layout
5501 -file, then copy these files to a subfolder of your LaTeX distribution,
5502 for example to the folder
5511 Then update the file name database of your LaTeX-distribution.
5512 For example on MiKTeX this is done by pressing the button
5515 \begin_inset space ~
5520 that you find in MiKTeX's
5521 \begin_inset Quotes eld
5525 \begin_inset Quotes erd
5529 In both cases you need afterwards to reconfigure LyX using the menu
5530 \begin_inset Flex CharStyle:MenuItem
5533 \begin_layout Plain Layout
5534 Tools\SpecialChar \menuseparator
5540 and then to restart LyX.
5543 \begin_layout Standard
5544 If your LaTeX distribution doesn't provide a user interface, then you can
5545 follow these steps by using a UNIX/Linux console.
5548 \begin_layout Enumerate
5549 Get the package from
5550 \begin_inset CommandInset href
5553 target "http://www.ctan.org/"
5560 \begin_layout Enumerate
5561 You can install this package in several different places.
5562 If you want it to be available for all users on your system, then you should
5563 install it in your `local' TeX tree; if you want (or need) it to be available
5564 just for you, then you can install it in your own `user' TeX tree.
5565 Where these should be created, if they do not already exist, depends upon
5566 the details of your system.
5567 To find out, look in the file
5568 \begin_inset Flex CharStyle:Code
5571 \begin_layout Plain Layout
5581 \begin_layout Plain Layout
5582 This usually lives in the directory
5583 \begin_inset Flex CharStyle:Code
5586 \begin_layout Plain Layout
5592 , though you can run
5593 \begin_inset Flex CharStyle:Code
5596 \begin_layout Plain Layout
5607 The location of the `local' TeX tree is defined by
5608 \begin_inset Flex CharStyle:Code
5611 \begin_layout Plain Layout
5617 ; this is usually somewhere like
5618 \begin_inset Flex CharStyle:Code
5621 \begin_layout Plain Layout
5622 /usr/local/share/texmf/
5628 The `user' TeX tree is defined by
5629 \begin_inset Flex CharStyle:Code
5632 \begin_layout Plain Layout
5639 \begin_inset Flex CharStyle:Code
5642 \begin_layout Plain Layout
5649 (If these variables are not predefined, you can define them.) You'll probably
5650 need root permissions to create or modify the `local' tree; but your `user'
5651 tree shouldn't have such limitations.
5654 \begin_layout Enumerate
5656 \begin_inset Flex CharStyle:Code
5659 \begin_layout Plain Layout
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 Newline newline
5690 \begin_inset Flex CharStyle:Code
5693 \begin_layout Plain Layout
5694 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5700 \begin_inset Newline newline
5703 But, again, most of this will
5704 \begin_inset Quotes eld
5708 \begin_inset Quotes erd
5714 \begin_layout Enumerate
5719 \begin_layout Plain Layout
5720 We'll assume henceforth that you're defining `local' TeX tree.
5721 If you're defining a user tree, just adjust as necessary.
5727 You must follow the directory structure of your existing
5728 \begin_inset Flex CharStyle:Code
5731 \begin_layout Plain Layout
5737 directory, which will be found at
5738 \begin_inset Flex CharStyle:Code
5741 \begin_layout Plain Layout
5748 For example, latex packages should go under
5749 \begin_inset Flex CharStyle:Code
5752 \begin_layout Plain Layout
5753 $TEXMFLOCAL/tex/latex/
5761 \begin_layout Enumerate
5762 Install the package.
5763 For example, you would unpack the FoilTeX tarball and copy it to
5764 \begin_inset Flex CharStyle:Code
5767 \begin_layout Plain Layout
5768 $TEXMFLOCAL/tex/latex/foiltex
5775 \begin_inset Flex CharStyle:Code
5778 \begin_layout Plain Layout
5784 directory contains various files.
5787 \begin_layout Enumerate
5789 \begin_inset Flex CharStyle:Code
5792 \begin_layout Plain Layout
5800 \begin_inset Flex CharStyle:Code
5803 \begin_layout Plain Layout
5812 \begin_layout Standard
5813 Your package is now installed and available to LaTeX.
5814 To make it available to LyX, you need to create a Layout file, if one is
5815 not already available.
5816 (See the next section.) Once you have a layout file, you need only reconfigure
5818 \begin_inset Flex CharStyle:MenuItem
5821 \begin_layout Plain Layout
5822 Tools\SpecialChar \menuseparator
5828 ) and then restart LyX.
5829 You should then see your new package---for example
5830 \begin_inset Flex CharStyle:MenuItem
5833 \begin_layout Plain Layout
5840 \begin_inset Flex CharStyle:MenuItem
5843 \begin_layout Plain Layout
5844 Document\SpecialChar \menuseparator
5851 \begin_inset Flex CharStyle:MenuItem
5854 \begin_layout Plain Layout
5864 \begin_layout Section
5868 \begin_layout Standard
5869 This section describes how to write and install your own LyX layout files
5870 and walks through the
5871 \begin_inset Flex CharStyle:Code
5874 \begin_layout Plain Layout
5880 text class format as an example.
5882 \begin_inset Flex CharStyle:Code
5885 \begin_layout Plain Layout
5891 files describe what paragraph and character styles are available for a
5892 given document class and how LyX should display them.
5893 We try to provide a thorough description of the process here; however,
5894 there are so many different types of documents supported by LaTeX classes
5895 that we can't hope to cover every different possibility or problem you
5897 (The LyX users' list is frequented by people with lots of experience with
5898 layout design who are willing to share what they've learned.)
5901 \begin_layout Standard
5902 As you prepare to write a new layout, it is extremely helpful to look at
5903 the example layouts distributed with LyX.
5904 If you use a nice LaTeX document class that might be of interest for others,
5905 too, and have a nice corresponding LyX layout, feel free to contribute
5906 the stuff to us, so we may put it into the distribution.
5908 \begin_inset CommandInset href
5910 name "section on the LyX wiki"
5911 target "http://wiki.lyx.org/Layouts/Layouts"
5915 for this kind of material.
5918 \begin_layout Standard
5919 All the tags described in this chapter are case-insensitive; this means
5921 \begin_inset Flex CharStyle:Code
5924 \begin_layout Plain Layout
5931 \begin_inset Flex CharStyle:Code
5934 \begin_layout Plain Layout
5941 \begin_inset Flex CharStyle:Code
5944 \begin_layout Plain Layout
5950 are really the same command.
5951 The possible values are printed in brackets after the feature's name.
5952 The default value if a feature isn't specified inside a text class-description
5954 \begin_inset Flex CharStyle:Code
5957 \begin_layout Plain Layout
5966 If the argument has a datatype like
5967 \begin_inset Quotes eld
5971 \begin_inset Quotes erd
5975 \begin_inset Quotes eld
5979 \begin_inset Quotes erd
5982 , the default is shown like this:
5983 \begin_inset Flex CharStyle:Code
5986 \begin_layout Plain Layout
5997 \begin_layout Subsection
6001 \begin_layout Standard
6002 Similar to layout files, and new with LyX 1.6, are layout
6007 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6008 some modules---such as the Endnotes module---provide support for just such
6010 In a sense, layout modules are similar to included files---files like
6011 \begin_inset Flex CharStyle:Code
6014 \begin_layout Plain Layout
6020 ---in that modules are not specific to a given document layout but may be
6021 used with many different layouts.
6022 The difference is that using a layout module does not require editing the
6024 Rather, modules are selected in the
6025 \begin_inset Flex CharStyle:MenuItem
6028 \begin_layout Plain Layout
6029 Document\SpecialChar \menuseparator
6038 \begin_layout Standard
6039 Building modules is the easiest way to get started with layout editing,
6040 since it can be as simple as adding a single new paragraph or flex inset.
6041 But modules may, in principle, contain anything a layout file can contain.
6044 \begin_layout Standard
6045 A module must begin with a line like the following:
6048 \begin_layout LyX-Code
6051 DeclareLyXModule[endnotes.sty]{Endnotes}
6054 \begin_layout Standard
6055 The argument in square brackets is optional: It declares any LaTeX packages
6056 on which the module depends.
6057 The mandatory argument, in curly brackets, is the name of the module, as
6059 \begin_inset Flex CharStyle:MenuItem
6062 \begin_layout Plain Layout
6063 Document\SpecialChar \menuseparator
6073 \begin_layout Standard
6074 The module declaration should then be followed by lines like the following:
6077 \begin_layout LyX-Code
6081 \begin_layout LyX-Code
6082 #Adds an endnote command, in addition to footnotes.
6086 \begin_layout LyX-Code
6087 #You will need to add
6089 theendnotes in ERT where you
6092 \begin_layout LyX-Code
6093 #want the endnotes to appear.
6097 \begin_layout LyX-Code
6101 \begin_layout LyX-Code
6102 #Requires: somemodule | othermodule
6105 \begin_layout LyX-Code
6106 #Excludes: badmodule
6109 \begin_layout Standard
6110 The description is used in
6111 \begin_inset Flex CharStyle:MenuItem
6114 \begin_layout Plain Layout
6115 Document\SpecialChar \menuseparator
6121 to provide the user with information about what the module does.
6123 \begin_inset Flex CharStyle:Code
6126 \begin_layout Plain Layout
6132 line is used to identify other modules with which this one must be used;
6134 \begin_inset Flex CharStyle:Code
6137 \begin_layout Plain Layout
6143 line is used to identify modules with which this one may not be used.
6144 Both are optional, and, as shown, multiple modules should be separated
6145 with the pipe symbol: |.
6146 Note that the required modules are treated disjunctively:
6150 of the required modules must be used.
6155 excluded module may be used.
6156 Note that modules are identified here by their
6160 without the .module extension.
6162 \begin_inset Flex CharStyle:Code
6165 \begin_layout Plain Layout
6172 \begin_inset Flex CharStyle:Code
6175 \begin_layout Plain Layout
6184 \begin_layout Standard
6185 After creating a new module, you will need to reconfigure and then restart
6186 LyX for the module to appear in the menu.
6187 However, changes you make to the module will be seen immediately, if you
6189 \begin_inset Flex CharStyle:MenuItem
6192 \begin_layout Plain Layout
6193 Document\SpecialChar \menuseparator
6199 , highlight something, and then hit
6200 \begin_inset Quotes eld
6204 \begin_inset Quotes erd
6210 It is strongly recommended that you save your work before doing so
6215 it is strongly recommended that you not attempt to edit modules while simultaneo
6216 usly working on documents
6219 Though of course the developers strive to keep LyX stable in such situations,
6220 syntax errors and the like in your module file could cause strange behavior.
6223 \begin_layout Subsection
6224 Supporting new document classes
6227 \begin_layout Standard
6228 There are two situations you are likely to encounter when wanting to support
6229 a new LaTeX document class, involving LaTeX2e class (
6230 \begin_inset Flex CharStyle:Code
6233 \begin_layout Plain Layout
6240 \begin_inset Flex CharStyle:Code
6243 \begin_layout Plain Layout
6250 Supporting a style file is usually fairly easy.
6251 Supporting a new document class is a bit harder.
6254 \begin_layout Subsection
6256 \begin_inset Flex CharStyle:MenuItem
6259 \begin_layout Plain Layout
6268 \begin_layout Standard
6269 If your new document class is provided as a style file that is used in conjuncti
6270 on with an existing, supported document class---for the sake of the example,
6271 we'll assume that the style file is called
6272 \begin_inset Flex CharStyle:MenuItem
6275 \begin_layout Plain Layout
6281 and it is meant to be used with
6282 \begin_inset Flex CharStyle:MenuItem
6285 \begin_layout Plain Layout
6291 , which is a standard class---start by copying the existing class's layout
6292 file into your local directory:
6295 \begin_layout LyX-Code
6296 cp report.layout ~/.lyx/layouts/myclass.layout
6299 \begin_layout Standard
6301 \begin_inset Flex CharStyle:Code
6304 \begin_layout Plain Layout
6310 and change the line:
6313 \begin_layout LyX-Code
6316 DeclareLaTeXClass{report}
6319 \begin_layout Standard
6323 \begin_layout LyX-Code
6326 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6329 \begin_layout Standard
6333 \begin_layout LyX-Code
6335 \begin_inset Newline newline
6341 \begin_inset Newline newline
6347 \begin_layout Standard
6348 near the top of the file.
6351 \begin_layout Standard
6352 Start LyX and select
6353 \begin_inset Flex CharStyle:MenuItem
6356 \begin_layout Plain Layout
6361 ools\SpecialChar \menuseparator
6372 Then restart LyX and try creating a new document.
6374 \begin_inset Flex CharStyle:MenuItem
6377 \begin_layout Plain Layout
6383 " as a document class option in the
6384 \begin_inset Flex CharStyle:MenuItem
6387 \begin_layout Plain Layout
6392 ocument\SpecialChar \menuseparator
6403 It is likely that some of the sectioning commands and such in your new
6404 class will work differently from how they worked in the base class---
6405 \begin_inset Flex CharStyle:Code
6408 \begin_layout Plain Layout
6414 in this example---so you can fiddle around with the settings for the different
6415 sections if you wish.
6418 \begin_layout Subsection
6420 \begin_inset Flex CharStyle:MenuItem
6423 \begin_layout Plain Layout
6432 \begin_layout Standard
6433 There are two possibilities here.
6434 One is that the class file is itself based upon an existing document class.
6435 For example, many thesis classes are based upon
6436 \begin_inset Flex CharStyle:MenuItem
6439 \begin_layout Plain Layout
6446 To see whether yours is, look for a line like
6449 \begin_layout LyX-Code
6455 \begin_layout Standard
6457 If so, then you may proceed largely as in the previous section, though
6458 the DeclareLaTeXClass line will be different.
6459 If your new class is thesis, and it is based upon book, then the line should
6464 \begin_layout Plain Layout
6465 And it will be easiest if you save the file to
6466 \begin_inset Flex CharStyle:Code
6469 \begin_layout Plain Layout
6475 : LyX assumes that the document class has the same name as the layout file.
6484 \begin_layout LyX-Code
6487 DeclareLaTeXClass[thesis,book]{thesis}
6490 \begin_layout Standard
6491 If, on the other hand, the new class is not based upon an existing class,
6492 you will probably have to
6493 \begin_inset Quotes eld
6497 \begin_inset Quotes erd
6501 We strongly suggest copying an existing layout file which uses a similar
6502 LaTeX class and then modifying it, if you can do so.
6503 At least use an existing file as a starting point so you can find out what
6504 items you need to worry about.
6505 Again, the specifics are covered below.
6508 \begin_layout Section
6509 Declaring a new text class
6512 \begin_layout Standard
6513 When it's finally time to get your hands dirty and create or edit your own
6514 layout file, the following sections describe what you're up against.
6515 Our advice is to go slowly, save and test often, listen to soothing music,
6516 and enjoy one or two of your favorite adult beverages; more if you are
6517 getting particularly stuck.
6518 It's really not that hard, except that the multitude of options can become
6519 overwhelming if you try to do to much in one sitting.
6520 Go have another adult beverage, just for good measure.
6523 \begin_layout Standard
6527 \begin_layout Standard
6528 Lines in a layout file which begin with a
6529 \begin_inset Flex CharStyle:Code
6532 \begin_layout Plain Layout
6539 There is one exception to this rule: all layouts should begin with lines
6543 \begin_layout LyX-Code
6546 #% Do not delete the line below; configure depends on this
6549 \begin_layout LyX-Code
6554 DeclareLaTeXClass{article}
6557 \begin_layout Standard
6558 The second line is used when you configure LyX.
6559 The layout file is read by the LaTeX script
6560 \begin_inset Flex CharStyle:Code
6563 \begin_layout Plain Layout
6569 , in a special mode where
6570 \begin_inset Flex CharStyle:Code
6573 \begin_layout Plain Layout
6580 The first line is just a LaTeX comment, and the second one contains the
6581 declaration of the text class.
6582 If these lines appear in a file named
6583 \begin_inset Flex CharStyle:Code
6586 \begin_layout Plain Layout
6592 , then they define a text class of name
6593 \begin_inset Flex CharStyle:Code
6596 \begin_layout Plain Layout
6602 (the name of the layout file) which uses the LaTeX document class
6603 \begin_inset Flex CharStyle:Code
6606 \begin_layout Plain Layout
6612 (the default is to use the same name as the layout).
6614 \begin_inset Quotes eld
6618 \begin_inset Quotes erd
6621 that appears above is used as a description of the text class in the
6622 \begin_inset Flex CharStyle:MenuItem
6625 \begin_layout Plain Layout
6630 ocument\SpecialChar \menuseparator
6643 \begin_layout Standard
6644 Let's assume that you wrote your own text class that uses the
6645 \begin_inset Flex CharStyle:Code
6648 \begin_layout Plain Layout
6654 document class, but where you changed the appearance of the section headings.
6655 If you put it in a file
6656 \begin_inset Flex CharStyle:Code
6659 \begin_layout Plain Layout
6665 , the header of this file should be:
6668 \begin_layout LyX-Code
6671 #% Do not delete the line below; configure depends on this
6674 \begin_layout LyX-Code
6679 DeclareLaTeXClass[article]{article (with my own headings)}
6682 \begin_layout Standard
6683 This declares a text class
6684 \begin_inset Flex CharStyle:Code
6687 \begin_layout Plain Layout
6693 , associated with the LaTeX document class
6694 \begin_inset Flex CharStyle:Code
6697 \begin_layout Plain Layout
6704 \begin_inset Quotes eld
6707 article (with my own headings)
6708 \begin_inset Quotes erd
6712 If your text class depends on several packages, you can declare it as:
6715 \begin_layout LyX-Code
6718 #% Do not delete the line below; configure depends on this
6721 \begin_layout LyX-Code
6726 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6729 \begin_layout Standard
6730 This indicates that your text class uses the foo.sty package.
6731 Finally, it is also possible to declare classes for DocBook code.
6732 Typical declarations will look like
6735 \begin_layout LyX-Code
6738 #% Do not delete the line below; configure depends on this
6741 \begin_layout LyX-Code
6746 DeclareDocBookClass[article]{SGML (DocBook article)}
6749 \begin_layout Standard
6750 Note that these declarations can also be given an optional parameter declaring
6751 the name of the document class (but not a list).
6754 \begin_layout Standard
6755 So, to be as explicit as possible, the form of the layout declaration is:
6758 \begin_layout LyX-Code
6763 DeclareLaTeXClass[class,package.sty]{layout description}
6766 \begin_layout Standard
6767 The class need only be specified if the name of the LaTeX class file and
6768 the name of the layout file are different; if the name of the classfile
6769 is not specified, then LyX will simply assume that it is the same as the
6770 name of the layout file.
6773 \begin_layout Standard
6774 When the text class has been modified to your taste, all you have to do
6775 is to copy it either to
6776 \begin_inset Flex CharStyle:Code
6779 \begin_layout Plain Layout
6786 \begin_inset Flex CharStyle:Code
6789 \begin_layout Plain Layout
6796 \begin_inset Flex CharStyle:MenuItem
6799 \begin_layout Plain Layout
6804 ools\SpecialChar \menuseparator
6814 , exit LyX and restart it.
6815 Then your new text class should be available along with the others.
6818 \begin_layout Standard
6819 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6820 you made to your layout files.
6821 As a result, editing layout files could be very time consuming.
6822 Beginning with 1.6, however, you can force a reload of the layout currently
6823 in use by using the LyX function
6824 \begin_inset Flex CharStyle:MenuItem
6827 \begin_layout Plain Layout
6834 There is no default binding for this function---though, of course, you
6835 can bind it to a key yourself.
6836 If you want to use this function, then, you should simply enter it in the
6842 : This is very much an `advanced feature'.
6847 recommended that you save your work before using this function.
6852 recommended that you not attempt to edit your layout while simultaneously
6853 working on a document that you care about.
6854 Use a test document.
6855 Syntax errors and the like in your layout file could cause peculiar behavior.
6856 In particular, such errors could cause LyX to regard the current layout
6857 as invalid and to attempt to switch to some other layout.
6858 The LyX team strives to keep LyX stable in such situations, but safe is
6862 \begin_layout Subsection
6866 \begin_layout Standard
6867 The first non-comment line must contain the file format number:
6870 \begin_layout Description
6871 \begin_inset Flex CharStyle:Code
6874 \begin_layout Plain Layout
6881 \begin_inset Flex CharStyle:Code
6884 \begin_layout Plain Layout
6890 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6891 don't have an explicit file format).
6892 The file format that is documented here is format 8.
6895 \begin_layout Subsection
6896 General text class parameters
6899 \begin_layout Standard
6900 These are the general parameters which describe the form of the entire document:
6903 \begin_layout Description
6904 \begin_inset Flex CharStyle:Code
6907 \begin_layout Plain Layout
6913 Adds information to the document preamble.
6915 \begin_inset Quotes eld
6919 \begin_inset Flex CharStyle:Code
6922 \begin_layout Plain Layout
6929 \begin_inset Quotes erd
6935 \begin_layout Description
6936 \begin_inset Flex CharStyle:Code
6939 \begin_layout Plain Layout
6945 Describes various global options supported by the document class.
6947 \begin_inset space ~
6951 \begin_inset CommandInset ref
6953 reference "sec:classoptions"
6959 \begin_inset Quotes eld
6963 \begin_inset Flex CharStyle:Code
6966 \begin_layout Plain Layout
6973 \begin_inset Quotes erd
6979 \begin_layout Description
6980 \begin_inset Flex CharStyle:Code
6983 \begin_layout Plain Layout
6990 \begin_inset Flex CharStyle:Code
6993 \begin_layout Plain Layout
7002 \begin_inset Flex CharStyle:Code
7005 \begin_layout Plain Layout
7011 ] Whether the class should default to having one or two columns.
7012 Can be changed in the
7013 \begin_inset Flex CharStyle:MenuItem
7016 \begin_layout Plain Layout
7021 ocument\SpecialChar \menuseparator
7034 \begin_layout Description
7035 \begin_inset Flex CharStyle:Code
7038 \begin_layout Plain Layout
7044 This sequence defines a new counter.
7046 \begin_inset space ~
7050 \begin_inset CommandInset ref
7052 reference "sec:counter"
7058 \begin_inset Quotes eld
7062 \begin_inset Flex CharStyle:Code
7065 \begin_layout Plain Layout
7072 \begin_inset Quotes erd
7078 \begin_layout Description
7079 \begin_inset Flex CharStyle:Code
7082 \begin_layout Plain Layout
7088 Sets the default font used to display the document.
7090 \begin_inset space ~
7094 \begin_inset CommandInset ref
7096 reference "sec:fonts"
7100 for how to declare fonts.
7102 \begin_inset Quotes eld
7106 \begin_inset Flex CharStyle:Code
7109 \begin_layout Plain Layout
7116 \begin_inset Quotes erd
7122 \begin_layout Description
7123 \begin_inset Flex CharStyle:Code
7126 \begin_layout Plain Layout
7133 \begin_inset Flex CharStyle:Code
7136 \begin_layout Plain Layout
7142 ] This is the style that will be assigned to new paragraphs, usually
7143 \begin_inset Flex CharStyle:MenuItem
7146 \begin_layout Plain Layout
7153 This will default to the first defined style if not given, but you are
7154 highly encouraged to use this directive.
7157 \begin_layout Description
7158 \begin_inset Flex CharStyle:Code
7161 \begin_layout Plain Layout
7167 Defines a new float.
7169 \begin_inset space ~
7173 \begin_inset CommandInset ref
7175 reference "sec:floats"
7181 \begin_inset Quotes eld
7185 \begin_inset Flex CharStyle:Code
7188 \begin_layout Plain Layout
7195 \begin_inset Quotes erd
7201 \begin_layout Description
7202 \begin_inset Flex CharStyle:Code
7205 \begin_layout Plain Layout
7211 As its name implies, this command allows you to include another layout
7212 definition file within yours to avoid duplicating commands.
7213 Common examples are the standard layout files, for example,
7214 \begin_inset Flex CharStyle:Code
7217 \begin_layout Plain Layout
7223 , which contains most of the basic layouts.
7226 \begin_layout Description
7227 \begin_inset Flex CharStyle:Code
7230 \begin_layout Plain Layout
7236 This section (re-)defines the layout of an inset.
7237 It can be applied to an existing inset of to a new, user-defined inset,
7238 e.g., a new character style.
7240 \begin_inset space ~
7244 \begin_inset CommandInset ref
7246 reference "sec:charstyle"
7250 for more information.
7252 \begin_inset Quotes eld
7256 \begin_inset Flex CharStyle:Code
7259 \begin_layout Plain Layout
7266 \begin_inset Quotes erd
7272 \begin_layout Description
7273 \begin_inset Flex CharStyle:Code
7276 \begin_layout Plain Layout
7282 A string that indicates the width of the left margin on the screen, for
7284 \begin_inset Quotes eld
7288 \begin_inset Quotes erd
7294 \begin_layout Description
7295 \begin_inset Flex CharStyle:Code
7298 \begin_layout Plain Layout
7304 This command deletes an existing float.
7305 This is particularly useful when you want to suppress a float that has
7306 be defined in an input file.
7309 \begin_layout Description
7310 \begin_inset Flex CharStyle:Code
7313 \begin_layout Plain Layout
7319 This command deletes an existing style.
7320 This is particularly useful when you want to suppress a style that has
7321 be defined in an input file.
7324 \begin_layout Description
7325 \begin_inset Flex CharStyle:Code
7328 \begin_layout Plain Layout
7334 A string indicating what sort of output documents using this class will
7336 At present, the options are: `docbook', `latex', `linuxdoc', and `literate'.
7339 \begin_layout Description
7340 \begin_inset Flex CharStyle:Code
7343 \begin_layout Plain Layout
7354 \begin_inset Flex CharStyle:Code
7357 \begin_layout Plain Layout
7368 \begin_inset Flex CharStyle:Code
7371 \begin_layout Plain Layout
7378 \begin_inset Flex CharStyle:Code
7381 \begin_layout Plain Layout
7387 ] The class default pagestyle.
7388 Can be changed in the
7389 \begin_inset Flex CharStyle:MenuItem
7392 \begin_layout Plain Layout
7397 ocument\SpecialChar \menuseparator
7410 \begin_layout Description
7411 \begin_inset Flex CharStyle:Code
7414 \begin_layout Plain Layout
7420 Sets the preamble for the LaTeX document.
7421 Note that this will completely override any prior
7422 \begin_inset Flex CharStyle:Code
7425 \begin_layout Plain Layout
7432 \begin_inset Flex CharStyle:Code
7435 \begin_layout Plain Layout
7443 \begin_inset Quotes eld
7447 \begin_inset Flex CharStyle:Code
7450 \begin_layout Plain Layout
7457 \begin_inset Quotes erd
7463 \begin_layout Description
7464 \begin_inset Flex CharStyle:Code
7467 \begin_layout Plain Layout
7474 \begin_inset Flex CharStyle:Code
7477 \begin_layout Plain Layout
7484 \begin_inset Flex CharStyle:Code
7487 \begin_layout Plain Layout
7496 \begin_inset Flex CharStyle:Code
7499 \begin_layout Plain Layout
7505 ] Whether the class already provides the feature
7506 \begin_inset Flex CharStyle:Code
7509 \begin_layout Plain Layout
7516 A feature is in general the name of a package (
7517 \begin_inset Flex CharStyle:Code
7520 \begin_layout Plain Layout
7527 \begin_inset Flex CharStyle:Code
7530 \begin_layout Plain Layout
7536 , \SpecialChar \ldots{}
7538 \begin_inset Flex CharStyle:Code
7541 \begin_layout Plain Layout
7548 \begin_inset Flex CharStyle:Code
7551 \begin_layout Plain Layout
7557 ,\SpecialChar \ldots{}
7558 ); the complete list of supported features is unfortunately not documented
7559 outside the LyX source code---but see
7560 \begin_inset Flex CharStyle:Code
7563 \begin_layout Plain Layout
7569 if you're interested.
7571 \begin_inset Flex CharStyle:MenuItem
7574 \begin_layout Plain Layout
7579 elp\SpecialChar \menuseparator
7589 also gives an overview of the supported packages.
7592 \begin_layout Description
7593 \begin_inset Flex CharStyle:Code
7596 \begin_layout Plain Layout
7603 \begin_inset Flex CharStyle:Code
7606 \begin_layout Plain Layout
7612 ] Whether the class requires the feature
7613 \begin_inset Flex CharStyle:Code
7616 \begin_layout Plain Layout
7623 Multiple features must be separated by commas.
7624 Note that you can only request supported features.
7627 \begin_layout Description
7628 \begin_inset Flex CharStyle:Code
7631 \begin_layout Plain Layout
7637 A string that indicates the width of the right margin on the screen, for
7639 \begin_inset Quotes eld
7643 \begin_inset Quotes erd
7649 \begin_layout Description
7650 \begin_inset Flex CharStyle:Code
7653 \begin_layout Plain Layout
7659 Sets which divisions get numbered.
7661 \begin_inset Flex CharStyle:Code
7664 \begin_layout Plain Layout
7673 \begin_layout Description
7674 \begin_inset Flex CharStyle:Code
7677 \begin_layout Plain Layout
7686 \begin_inset Flex CharStyle:Code
7689 \begin_layout Plain Layout
7700 \begin_inset Flex CharStyle:Code
7703 \begin_layout Plain Layout
7709 ] Whether the class-default should be printing on one or both sides of the
7711 Can be changed in the
7712 \begin_inset Flex CharStyle:MenuItem
7715 \begin_layout Plain Layout
7720 ocument\SpecialChar \menuseparator
7733 \begin_layout Description
7734 \begin_inset Flex CharStyle:Code
7737 \begin_layout Plain Layout
7743 This sequence defines a new paragraph style.
7744 If the style already exists, it will redefine some of its parameters instead.
7746 \begin_inset space ~
7750 \begin_inset CommandInset ref
7752 reference "sec:style"
7758 \begin_inset Quotes eld
7762 \begin_inset Flex CharStyle:Code
7765 \begin_layout Plain Layout
7772 \begin_inset Quotes erd
7778 \begin_layout Description
7779 \begin_inset Flex CharStyle:Code
7782 \begin_layout Plain Layout
7789 \begin_inset Flex CharStyle:Code
7792 \begin_layout Plain Layout
7798 ] The name of the command or environment to be used with
7799 \begin_inset Flex CharStyle:Code
7802 \begin_layout Plain Layout
7811 \begin_layout Description
7812 \begin_inset Flex CharStyle:Code
7815 \begin_layout Plain Layout
7822 \begin_inset Flex CharStyle:Code
7825 \begin_layout Plain Layout
7834 \begin_inset Flex CharStyle:Code
7837 \begin_layout Plain Layout
7843 ] Indicates what kind of markup is used to define the title of a document.
7845 \begin_inset Flex CharStyle:Code
7848 \begin_layout Plain Layout
7854 means that the macro with name
7855 \begin_inset Flex CharStyle:Code
7858 \begin_layout Plain Layout
7864 will be inserted after the last layout which has
7865 \begin_inset Quotes eld
7869 \begin_inset Flex CharStyle:Code
7872 \begin_layout Plain Layout
7879 \begin_inset Quotes erd
7884 \begin_inset Flex CharStyle:Code
7887 \begin_layout Plain Layout
7893 corresponds to the case where the block of paragraphs which have
7894 \begin_inset Quotes eld
7898 \begin_inset Flex CharStyle:Code
7901 \begin_layout Plain Layout
7908 \begin_inset Quotes erd
7911 should be enclosed into the
7912 \begin_inset Flex CharStyle:Code
7915 \begin_layout Plain Layout
7924 \begin_layout Description
7925 \begin_inset Flex CharStyle:Code
7928 \begin_layout Plain Layout
7934 Sets which divisions are included in the table of contents.
7936 \begin_inset Flex CharStyle:Code
7939 \begin_layout Plain Layout
7948 \begin_layout Description
7949 \begin_inset Flex CharStyle:Code
7952 \begin_layout Plain Layout
7959 \begin_inset Flex CharStyle:Code
7962 \begin_layout Plain Layout
7968 Specifies a module to be included by default with this document class.
7969 The user can still remove the module, but it will be active at the outset.
7970 (This applies only when new files are created, or when this class is chosen
7971 for an existing document.)
7974 \begin_layout Subsection
7975 \begin_inset Flex CharStyle:Code
7978 \begin_layout Plain Layout
7987 \begin_layout Standard
7988 \begin_inset CommandInset label
7990 name "sec:classoptions"
7995 \begin_inset Flex CharStyle:Code
7998 \begin_layout Plain Layout
8004 section can contain the following entries:
8007 \begin_layout Description
8008 \begin_inset Flex CharStyle:Code
8011 \begin_layout Plain Layout
8018 \begin_inset Flex CharStyle:Code
8021 \begin_layout Plain Layout
8027 ] The list of available font sizes for the document's main font, separated
8029 \begin_inset Quotes eld
8033 \begin_inset Flex CharStyle:Code
8036 \begin_layout Plain Layout
8043 \begin_inset Quotes erd
8049 \begin_layout Description
8050 \begin_inset Flex CharStyle:Code
8053 \begin_layout Plain Layout
8059 Used to set the DTD line with XML-based output classes.
8061 \begin_inset Quotes eld
8064 -//OASIS//DTD DocBook V4.2//EN
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
8086 string="empty|plain|headings|fancy"
8091 ] The list of available page styles, separated by
8092 \begin_inset Quotes eld
8096 \begin_inset Flex CharStyle:Code
8099 \begin_layout Plain Layout
8106 \begin_inset Quotes erd
8112 \begin_layout Description
8113 \begin_inset Flex CharStyle:Code
8116 \begin_layout Plain Layout
8123 \begin_inset Flex CharStyle:Code
8126 \begin_layout Plain Layout
8132 ] Some document class options, separated by a comma, that will be added
8133 to the optional part of the
8134 \begin_inset Flex CharStyle:Code
8137 \begin_layout Plain Layout
8148 \begin_layout Standard
8150 \begin_inset Flex CharStyle:Code
8153 \begin_layout Plain Layout
8159 section must end with
8160 \begin_inset Quotes eld
8164 \begin_inset Flex CharStyle:Code
8167 \begin_layout Plain Layout
8174 \begin_inset Quotes erd
8180 \begin_layout Subsection
8184 \begin_layout Standard
8185 \begin_inset CommandInset label
8191 A paragraph style description looks like this:
8195 \begin_layout Plain Layout
8196 Note that this will either define a new layout or modify an existing one.
8204 \begin_layout LyX-Code
8211 \begin_layout LyX-Code
8215 \begin_layout LyX-Code
8219 \begin_layout Standard
8220 where the following commands are allowed:
8223 \begin_layout Description
8224 \begin_inset Flex CharStyle:Code
8227 \begin_layout Plain Layout
8234 \begin_inset Flex CharStyle:Code
8237 \begin_layout Plain Layout
8242 , left, right, center
8247 ] Paragraph alignment.
8250 \begin_layout Description
8251 \begin_inset Flex CharStyle:Code
8254 \begin_layout Plain Layout
8261 \begin_inset Flex CharStyle:Code
8264 \begin_layout Plain Layout
8269 , left, right, center
8274 ] A comma separated list of permitted alignments.
8275 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8277 For example a right-aligned or centered enumeration isn't possible.)
8280 \begin_layout Description
8281 \begin_inset Flex CharStyle:Code
8284 \begin_layout Plain Layout
8291 \begin_inset Flex CharStyle:Code
8294 \begin_layout Plain Layout
8304 \begin_layout Plain Layout
8305 Note that a `float' here is a real number, such as: 1.5.
8310 The vertical space with which the last of a chain of paragraphs with this
8311 layout is separated from the following paragraph.
8312 If the next paragraph has another layout, the separations are not simply
8313 added, but the maximum is taken.
8316 \begin_layout Description
8317 \begin_inset Flex CharStyle:Code
8320 \begin_layout Plain Layout
8327 \begin_inset Flex CharStyle:Code
8330 \begin_layout Plain Layout
8336 The category for this style.
8337 This is used to group related styles in the Layout combobox on the toolbar.
8338 Any string can be used, but you may want to use existing categories with
8343 \begin_layout Description
8344 \begin_inset Flex CharStyle:Code
8347 \begin_layout Plain Layout
8353 Depth of XML command.
8354 Used only with XML-type formats.
8357 \begin_layout Description
8358 \begin_inset Flex CharStyle:Code
8361 \begin_layout Plain Layout
8368 \begin_inset CommandInset label
8370 name "des:CopyStyle"
8375 \begin_inset Flex CharStyle:Code
8378 \begin_layout Plain Layout
8384 Copies all the features of an existing style into the current one.
8388 \begin_layout Description
8389 \begin_inset Flex CharStyle:Code
8392 \begin_layout Plain Layout
8398 The name of a style whose preamble should be output
8403 This allows to ensure some ordering of the preamble snippets when macros
8404 definitions depend on one another.
8408 \begin_layout Plain Layout
8409 Note that, besides that functionality, there is no way to ensure any ordering
8411 The ordering that you see in a given version of LyX may change without
8412 warning in later versions.
8420 \begin_layout Description
8421 \begin_inset Flex CharStyle:Code
8424 \begin_layout Plain Layout
8431 \begin_inset Flex CharStyle:Code
8434 \begin_layout Plain Layout
8439 , Box, Filled_Box, Static
8444 ] The type of label that stands at the end of the paragraph (or sequence
8446 \begin_inset Flex CharStyle:Code
8449 \begin_layout Plain Layout
8456 \begin_inset Flex CharStyle:Code
8459 \begin_layout Plain Layout
8466 \begin_inset Flex CharStyle:Code
8469 \begin_layout Plain Layout
8476 \begin_inset Flex CharStyle:Code
8479 \begin_layout Plain Layout
8487 \begin_inset Flex CharStyle:Code
8490 \begin_layout Plain Layout
8497 \begin_inset Quotes eld
8501 \begin_inset Quotes erd
8505 \begin_inset Flex CharStyle:Code
8508 \begin_layout Plain Layout
8515 \begin_inset Flex CharStyle:Code
8518 \begin_layout Plain Layout
8519 \begin_inset space ~
8528 \begin_inset space ~
8531 black) square suitable for end of proof markers,
8532 \begin_inset Flex CharStyle:Code
8535 \begin_layout Plain Layout
8541 is an explicit text string.
8544 \begin_layout Description
8545 \begin_inset Flex CharStyle:Code
8548 \begin_layout Plain Layout
8555 \begin_inset Flex CharStyle:Code
8558 \begin_layout Plain Layout
8564 ] The string used for a label with a
8565 \begin_inset Flex CharStyle:Code
8568 \begin_layout Plain Layout
8575 \begin_inset Flex CharStyle:Code
8578 \begin_layout Plain Layout
8588 \begin_layout Description
8589 \begin_inset Flex CharStyle:Code
8592 \begin_layout Plain Layout
8599 \begin_inset Flex CharStyle:Code
8602 \begin_layout Plain Layout
8613 \begin_inset Flex CharStyle:Code
8616 \begin_layout Plain Layout
8625 \begin_layout Description
8626 \begin_inset Flex CharStyle:Code
8629 \begin_layout Plain Layout
8636 \begin_inset Flex CharStyle:Code
8639 \begin_layout Plain Layout
8649 ] With this parameter the
8650 \begin_inset Flex CharStyle:MenuItem
8653 \begin_layout Plain Layout
8660 \begin_inset Quotes eld
8663 Vertical space above
8664 \begin_inset Quotes erd
8668 \begin_inset Flex CharStyle:MenuItem
8671 \begin_layout Plain Layout
8676 dit\SpecialChar \menuseparator
8682 \begin_inset space ~
8690 dialog can be set when initializing a paragraph with this style.
8694 \begin_layout Plain Layout
8697 Note from Jean-Marc:
8699 I'm not sure that this setting has much use, and it should probably be
8700 removed in later versions.
8708 \begin_layout Description
8709 \begin_inset Flex CharStyle:Code
8712 \begin_layout Plain Layout
8718 The font used for both the text body
8724 \begin_inset space ~
8728 \begin_inset CommandInset ref
8730 reference "sec:fonts"
8735 Note that defining this font automatically defines the
8736 \begin_inset Flex CharStyle:Code
8739 \begin_layout Plain Layout
8746 So you should define this one first if you also want to define
8747 \begin_inset Flex CharStyle:Code
8750 \begin_layout Plain Layout
8759 \begin_layout Description
8760 \begin_inset Flex CharStyle:Code
8763 \begin_layout Plain Layout
8770 \begin_inset CommandInset label
8772 name "des:FreeSpacing"
8779 \begin_inset Flex CharStyle:Code
8782 \begin_layout Plain Layout
8793 \begin_inset Flex CharStyle:Code
8796 \begin_layout Plain Layout
8802 ] Usually LyX doesn't allow you to insert more than one space between words,
8803 since a space is considered as the separation between two words, not a
8804 character or symbol of its own.
8805 This is a very fine thing but sometimes annoying, for example, when typing
8806 program code or plain LaTeX code.
8808 \begin_inset Flex CharStyle:Code
8811 \begin_layout Plain Layout
8818 Note that LyX will create protected blanks for the additional blanks when
8819 in another mode than LaTeX-mode.
8822 \begin_layout Description
8823 \begin_inset Flex CharStyle:Code
8826 \begin_layout Plain Layout
8832 [[FIXME]] (Used only with XML-type formats.)
8835 \begin_layout Description
8836 \begin_inset Flex CharStyle:Code
8839 \begin_layout Plain Layout
8846 \begin_inset Flex CharStyle:Code
8849 \begin_layout Plain Layout
8855 If 1, marks the layout as being part of a title block (see also the
8856 \begin_inset Flex CharStyle:Code
8859 \begin_layout Plain Layout
8866 \begin_inset Flex CharStyle:Code
8869 \begin_layout Plain Layout
8878 \begin_layout Description
8879 \begin_inset Flex CharStyle:Code
8882 \begin_layout Plain Layout
8889 \begin_inset Flex CharStyle:Code
8892 \begin_layout Plain Layout
8898 ] This provides extra space between paragraphs that have the same layout.
8899 If you put other layouts into an environment, each is separated with the
8901 \begin_inset Flex CharStyle:Code
8904 \begin_layout Plain Layout
8911 But the whole items of the environment are additionally separated with
8913 \begin_inset Flex CharStyle:Code
8916 \begin_layout Plain Layout
8928 \begin_layout Description
8929 \begin_inset Flex CharStyle:Code
8932 \begin_layout Plain Layout
8938 [[FIXME]] (Used only with XML-type formats.)
8941 \begin_layout Description
8942 \begin_inset Flex CharStyle:Code
8945 \begin_layout Plain Layout
8952 \begin_inset CommandInset label
8954 name "des:KeepEmpty"
8961 \begin_inset Flex CharStyle:Code
8964 \begin_layout Plain Layout
8975 \begin_inset Flex CharStyle:Code
8978 \begin_layout Plain Layout
8984 ] Usually LyX does not allow you to leave a paragraph empty, since it would
8985 lead to empty LaTeX output.
8986 There are some cases where this could be desirable however: in a letter
8987 template, the required fields can be provided as empty fields, so that
8988 people do not forget them; in some special classes, a layout can be used
8989 as some kind of break, which does not contain actual text.
8992 \begin_layout Description
8993 \begin_inset Flex CharStyle:Code
8996 \begin_layout Plain Layout
9002 [float=0] The vertical space between the label and the text body.
9003 Only used for labels that are above the text body (
9004 \begin_inset Flex CharStyle:Code
9007 \begin_layout Plain Layout
9014 \begin_inset Flex CharStyle:Code
9017 \begin_layout Plain Layout
9018 Centered_Top_Environment
9026 \begin_layout Description
9027 \begin_inset Flex CharStyle:Code
9030 \begin_layout Plain Layout
9037 \begin_inset Flex CharStyle:Code
9040 \begin_layout Plain Layout
9047 \begin_inset Newline newline
9050 The name of the counter for automatic numbering (see Section
9051 \begin_inset CommandInset ref
9053 reference "sec:counter"
9058 This must be given if
9059 \begin_inset Flex CharStyle:Code
9062 \begin_layout Plain Layout
9069 \begin_inset Flex CharStyle:Code
9072 \begin_layout Plain Layout
9081 \begin_layout Description
9082 \begin_inset Flex CharStyle:Code
9085 \begin_layout Plain Layout
9091 The font used for the label.
9093 \begin_inset space ~
9097 \begin_inset CommandInset ref
9099 reference "sec:fonts"
9106 \begin_layout Description
9107 \begin_inset Flex CharStyle:Code
9110 \begin_layout Plain Layout
9116 Text that indicates how far a label should be indented.
9119 \begin_layout Description
9120 \begin_inset Flex CharStyle:Code
9123 \begin_layout Plain Layout
9130 \begin_inset Flex CharStyle:Code
9133 \begin_layout Plain Layout
9139 ] The horizontal space between the label and the text body.
9140 Only used for labels that are not above the text body.
9143 \begin_layout Description
9144 \begin_inset Flex CharStyle:Code
9147 \begin_layout Plain Layout
9154 \begin_inset Flex CharStyle:Code
9157 \begin_layout Plain Layout
9163 ] The string used for a label with a
9164 \begin_inset Flex CharStyle:Code
9167 \begin_layout Plain Layout
9175 \begin_inset Flex CharStyle:Code
9178 \begin_layout Plain Layout
9184 is set, this string can be contain the special formatting commands described
9186 \begin_inset CommandInset ref
9188 reference "sec:counter"
9196 \begin_layout Plain Layout
9197 For the sake of backwards compatibility, the string
9198 \begin_inset Flex CharStyle:Code
9201 \begin_layout Plain Layout
9211 will be replaced by the expanded
9212 \begin_inset Flex CharStyle:Code
9215 \begin_layout Plain Layout
9222 \begin_inset Flex CharStyle:Code
9225 \begin_layout Plain Layout
9234 This feature is now obsolete and should be replaced by the mechanisms of
9236 \begin_inset CommandInset ref
9238 reference "sec:counter"
9250 \begin_layout Description
9251 \begin_inset Flex CharStyle:Code
9254 \begin_layout Plain Layout
9261 \begin_inset Flex CharStyle:Code
9264 \begin_layout Plain Layout
9270 ] This is used inside the appendix instead of
9271 \begin_inset Flex CharStyle:Code
9274 \begin_layout Plain Layout
9282 \begin_inset Flex CharStyle:Code
9285 \begin_layout Plain Layout
9292 \begin_inset Flex CharStyle:Code
9295 \begin_layout Plain Layout
9304 \begin_layout Description
9305 \begin_inset Flex CharStyle:Code
9308 \begin_layout Plain Layout
9314 [FIXME] (Used only with XML-type formats.)
9317 \begin_layout Description
9318 \begin_inset Flex CharStyle:Code
9321 \begin_layout Plain Layout
9328 \begin_inset Flex CharStyle:Code
9331 \begin_layout Plain Layout
9336 , Manual, Static, Top_Environment,
9337 \begin_inset Newline newline
9340 Centered_Top_Environment, Sensitive, Counter
9346 \begin_inset Newline newline
9350 \begin_inset Flex CharStyle:Code
9353 \begin_layout Plain Layout
9359 means the label is the very first word (up to the first real blank).
9363 \begin_layout Plain Layout
9364 Use protected spaces if you want more than one word as the label.
9370 \begin_inset Flex CharStyle:Code
9373 \begin_layout Plain Layout
9379 means it is defined in the layout (see
9380 \begin_inset Flex CharStyle:Code
9383 \begin_layout Plain Layout
9391 \begin_inset Flex CharStyle:Code
9394 \begin_layout Plain Layout
9401 \begin_inset Flex CharStyle:Code
9404 \begin_layout Plain Layout
9405 Centered_Top_Environment
9410 are special cases of
9411 \begin_inset Flex CharStyle:Code
9414 \begin_layout Plain Layout
9421 The label will be printed above the paragraph, but only at the top of an
9422 environment or the top of a chain of paragraphs with this layout.
9423 Usage is for example the
9424 \begin_inset Flex CharStyle:MenuItem
9427 \begin_layout Plain Layout
9434 \begin_inset Flex CharStyle:MenuItem
9437 \begin_layout Plain Layout
9444 This is also the case for
9445 \begin_inset Flex CharStyle:Code
9448 \begin_layout Plain Layout
9454 labels with latex type
9455 \begin_inset Flex CharStyle:Code
9458 \begin_layout Plain Layout
9464 , in order to make layouts for theorems work correctly.
9466 \begin_inset Flex CharStyle:Code
9469 \begin_layout Plain Layout
9475 is a special case for the caption-labels
9476 \begin_inset Quotes eld
9480 \begin_inset Quotes erd
9484 \begin_inset Quotes eld
9488 \begin_inset Quotes erd
9493 \begin_inset Flex CharStyle:Code
9496 \begin_layout Plain Layout
9502 means the (hardcoded) label string depends on the kind of float.
9504 \begin_inset Flex CharStyle:Code
9507 \begin_layout Plain Layout
9513 label type defines automatically numbered labels.
9515 \begin_inset CommandInset ref
9517 reference "sec:counter"
9524 \begin_layout Description
9525 \begin_inset Flex CharStyle:Code
9528 \begin_layout Plain Layout
9534 The name of the corresponding LaTeX stuff.
9535 Either the environment or command name.
9538 \begin_layout Description
9539 \begin_inset Flex CharStyle:Code
9542 \begin_layout Plain Layout
9548 An optional parameter for the corresponding
9549 \begin_inset Flex CharStyle:Code
9552 \begin_layout Plain Layout
9559 This parameter cannot be changed from within LyX.
9562 \begin_layout Description
9563 \begin_inset Flex CharStyle:Code
9566 \begin_layout Plain Layout
9573 \begin_inset CommandInset label
9575 name "des:LatexType"
9580 \begin_inset Flex CharStyle:Code
9583 \begin_layout Plain Layout
9588 , Command, Environment, Item_Environment,
9594 \begin_inset Flex CharStyle:Code
9597 \begin_layout Plain Layout
9603 ] How the layout should be translated into LaTeX.
9605 \begin_inset Flex CharStyle:Code
9608 \begin_layout Plain Layout
9614 means nothing special.
9616 \begin_inset Flex CharStyle:Code
9619 \begin_layout Plain Layout
9626 \begin_inset Flex CharStyle:Code
9629 \begin_layout Plain Layout
9636 {\SpecialChar \ldots{}
9643 \begin_inset Flex CharStyle:Code
9646 \begin_layout Plain Layout
9653 \begin_inset Flex CharStyle:Code
9656 \begin_layout Plain Layout
9663 }\SpecialChar \ldots{}
9677 \begin_inset Flex CharStyle:Code
9680 \begin_layout Plain Layout
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9697 \begin_inset Flex CharStyle:Code
9700 \begin_layout Plain Layout
9708 is generated for each paragraph of this environment.
9710 \begin_inset Flex CharStyle:Code
9713 \begin_layout Plain Layout
9720 \begin_inset Flex CharStyle:Code
9723 \begin_layout Plain Layout
9730 \begin_inset Flex CharStyle:Code
9733 \begin_layout Plain Layout
9739 is passed as an argument to the environment.
9741 \begin_inset Flex CharStyle:Code
9744 \begin_layout Plain Layout
9750 can be defined in the
9751 \begin_inset Flex CharStyle:MenuItem
9754 \begin_layout Plain Layout
9759 ayout\SpecialChar \menuseparator
9771 \begin_inset Flex CharStyle:Code
9774 \begin_layout Plain Layout
9782 is perhaps a bit misleading, since these rules apply to SGML classes, too.
9783 Visit the SGML class files for specific examples.
9786 \begin_layout Standard
9787 Putting the last few things together, the LaTeX output will be either:
9790 \begin_layout LyX-Code
9793 latexname[latexparam]{\SpecialChar \ldots{}
9797 \begin_layout Standard
9801 \begin_layout LyX-Code
9804 begin{latexname}[latexparam] \SpecialChar \ldots{}
9810 \begin_layout Standard
9811 depending upon the LaTex type.
9814 \begin_layout Description
9815 \begin_inset Flex CharStyle:Code
9818 \begin_layout Plain Layout
9825 \begin_inset Flex CharStyle:Code
9828 \begin_layout Plain Layout
9834 ] If you put layouts into environments, the leftmargins are not simply added,
9835 but added with a factor
9836 \begin_inset Formula $\frac{4}{depth+4}$
9840 Note that this parameter is also used when the margin is defined as
9841 \begin_inset Flex CharStyle:Code
9844 \begin_layout Plain Layout
9851 \begin_inset Flex CharStyle:Code
9854 \begin_layout Plain Layout
9861 Then it is added to the manual or dynamic margin.
9863 \begin_inset Newline newline
9866 The argument is passed as a string.
9868 \begin_inset Quotes eld
9872 \begin_inset Flex CharStyle:Code
9875 \begin_layout Plain Layout
9882 \begin_inset Quotes erd
9885 means that the paragraph is indented with the width of
9886 \begin_inset Quotes eld
9890 \begin_inset Flex CharStyle:Code
9893 \begin_layout Plain Layout
9900 \begin_inset Quotes erd
9904 You can get a negative width by prefixing the string with
9905 \begin_inset Quotes eld
9909 \begin_inset Flex CharStyle:Code
9912 \begin_layout Plain Layout
9919 \begin_inset Quotes erd
9923 This way was chosen so that the look is the same with each used screen
9928 \begin_layout Description
9929 \begin_inset Flex CharStyle:Code
9932 \begin_layout Plain Layout
9939 \begin_inset Flex CharStyle:Code
9942 \begin_layout Plain Layout
9947 , Manual, Dynamic, First_Dynamic, Right_Address_Box
9953 \begin_inset Newline newline
9956 The kind of margin that the layout has on the left side.
9958 \begin_inset Flex CharStyle:Code
9961 \begin_layout Plain Layout
9967 just means a fixed margin.
9969 \begin_inset Flex CharStyle:Code
9972 \begin_layout Plain Layout
9978 means that the left margin depends on the string entered in the
9979 \begin_inset Flex CharStyle:MenuItem
9982 \begin_layout Plain Layout
9987 dit\SpecialChar \menuseparator
9993 \begin_inset space ~
10002 This is used to typeset nice lists without tabulators.
10004 \begin_inset Flex CharStyle:Code
10007 \begin_layout Plain Layout
10013 means that the margin depends on the size of the label.
10014 This is used for automatic enumerated headlines.
10015 It is obvious that the headline
10016 \begin_inset Quotes eld
10019 5.4.3.2.1 Very long headline
10020 \begin_inset Quotes erd
10023 must have a wider left margin (as wide as
10024 \begin_inset Quotes eld
10028 \begin_inset Quotes erd
10031 plus the space) than
10032 \begin_inset Quotes eld
10035 3.2 Very long headline
10036 \begin_inset Quotes erd
10040 \begin_inset Quotes eld
10044 \begin_inset Quotes erd
10047 are not able to do this.
10049 \begin_inset Flex CharStyle:Code
10052 \begin_layout Plain Layout
10058 is similar, but only the very first row of the paragraph is dynamic, while
10059 the others are static; this is used, for example, for descriptions.
10061 \begin_inset Flex CharStyle:Code
10064 \begin_layout Plain Layout
10070 means the margin is chosen in a way that the longest row of this paragraph
10071 fits to the right margin.
10072 This is used to typeset an address on the right edge of the page.
10075 \begin_layout Description
10076 \begin_inset Flex CharStyle:Code
10079 \begin_layout Plain Layout
10086 \begin_inset Flex CharStyle:Code
10089 \begin_layout Plain Layout
10098 \begin_inset Flex CharStyle:Code
10101 \begin_layout Plain Layout
10107 ] Whether fragile commands in this layout should be
10108 \begin_inset Flex CharStyle:Code
10111 \begin_layout Plain Layout
10124 whether this command should itself be protected.)
10127 \begin_layout Description
10128 \begin_inset Flex CharStyle:Code
10131 \begin_layout Plain Layout
10138 \begin_inset Flex CharStyle:Code
10141 \begin_layout Plain Layout
10148 \begin_inset Flex CharStyle:Code
10151 \begin_layout Plain Layout
10159 ] Whether newlines are translated into LaTeX newlines (
10160 \begin_inset Flex CharStyle:Code
10163 \begin_layout Plain Layout
10174 The translation can be switched off to allow more comfortable LaTeX editing
10178 \begin_layout Description
10179 \begin_inset Flex CharStyle:Code
10182 \begin_layout Plain Layout
10189 \begin_inset Flex CharStyle:Code
10192 \begin_layout Plain Layout
10199 \begin_inset Flex CharStyle:Code
10202 \begin_layout Plain Layout
10210 ] Whether the following Paragraph is allowed to indent its very first row.
10212 \begin_inset Flex CharStyle:Code
10215 \begin_layout Plain Layout
10221 means that it is not allowed to do so;
10222 \begin_inset Flex CharStyle:Code
10225 \begin_layout Plain Layout
10231 means it could do so if it wants to.
10234 \begin_layout Description
10235 \begin_inset Flex CharStyle:Code
10238 \begin_layout Plain Layout
10244 Name of a layout that has replaced this layout.
10245 This is used to rename a layout, while keeping backward compatibility.
10248 \begin_layout Description
10249 \begin_inset Flex CharStyle:Code
10252 \begin_layout Plain Layout
10259 \begin_inset Flex CharStyle:Code
10262 \begin_layout Plain Layout
10268 ] The number of optional arguments that can be used with this layout.
10269 This is useful for things like section headings, and only makes sense with
10273 \begin_layout Description
10274 \begin_inset Flex CharStyle:Code
10277 \begin_layout Plain Layout
10284 \begin_inset Flex CharStyle:Code
10287 \begin_layout Plain Layout
10293 ] The indent of the very first line of a paragraph.
10295 \begin_inset Flex CharStyle:Code
10298 \begin_layout Plain Layout
10304 will be fixed for a certain layout.
10305 The exception is Standard layout, since the indentation of a Standard layout
10306 paragraph can be prohibited with
10307 \begin_inset Flex CharStyle:Code
10310 \begin_layout Plain Layout
10317 Also, Standard layout paragraphs inside environments use the
10318 \begin_inset Flex CharStyle:Code
10321 \begin_layout Plain Layout
10327 of the environment, not their native one.
10328 For example, Standard paragraphs inside an enumeration are not indented.
10331 \begin_layout Description
10332 \begin_inset Flex CharStyle:Code
10335 \begin_layout Plain Layout
10342 \begin_inset Flex CharStyle:Code
10345 \begin_layout Plain Layout
10351 ] The vertical space between two paragraphs of this layout.
10354 \begin_layout Description
10355 \begin_inset Flex CharStyle:Code
10358 \begin_layout Plain Layout
10365 \begin_inset Flex CharStyle:Code
10368 \begin_layout Plain Layout
10374 ] LyX allows the user to choose either
10375 \begin_inset Quotes eld
10379 \begin_inset Quotes erd
10383 \begin_inset Quotes eld
10387 \begin_inset Quotes erd
10390 to typeset a document.
10392 \begin_inset Quotes eld
10396 \begin_inset Quotes erd
10399 is chosen, this value is completely ignored.
10401 \begin_inset Quotes eld
10405 \begin_inset Quotes erd
10408 is chosen, the parindent of a LaTeXtype
10409 \begin_inset Quotes eld
10413 \begin_inset Quotes erd
10416 layout is ignored and all paragraphs are separated by this parskip argument.
10417 The vertical space is calculated with
10418 \begin_inset Flex CharStyle:Code
10421 \begin_layout Plain Layout
10423 \begin_inset space ~
10432 \begin_inset Flex CharStyle:Code
10435 \begin_layout Plain Layout
10441 is the height of a row with the normal font.
10442 This way, the look stays the same with different screen fonts.
10445 \begin_layout Description
10446 \begin_inset Flex CharStyle:Code
10449 \begin_layout Plain Layout
10456 \begin_inset CommandInset label
10458 name "des:PathThru"
10465 \begin_inset Flex CharStyle:Code
10468 \begin_layout Plain Layout
10479 \begin_inset Flex CharStyle:Code
10482 \begin_layout Plain Layout
10488 ] Whether the contents of this paragraph should be output in raw form, meaning
10489 without special translations that LaTeX would require.
10492 \begin_layout Description
10493 \begin_inset Flex CharStyle:Code
10496 \begin_layout Plain Layout
10503 \begin_inset CommandInset label
10505 name "des:Preamble"
10509 Information to be included in the LaTeX preamable when this style is used.
10510 Used to define macros, load packages, etc., required by this particular
10513 \begin_inset Quotes eld
10517 \begin_inset Flex CharStyle:Code
10520 \begin_layout Plain Layout
10527 \begin_inset Quotes erd
10533 \begin_layout Description
10534 \begin_inset Flex CharStyle:Code
10537 \begin_layout Plain Layout
10544 \begin_inset Flex CharStyle:Code
10547 \begin_layout Plain Layout
10554 \begin_inset CommandInset label
10556 name "des:Requires"
10560 Whether the layout requires the feature
10561 \begin_inset Flex CharStyle:Code
10564 \begin_layout Plain Layout
10571 See the description of
10572 \begin_inset Flex CharStyle:Code
10575 \begin_layout Plain Layout
10582 \begin_inset CommandInset ref
10583 LatexCommand pageref
10584 reference "des:FreeSpacing"
10588 ) for information on `features'.
10592 \begin_layout Description
10593 \begin_inset Flex CharStyle:Code
10596 \begin_layout Plain Layout
10603 \begin_inset Flex CharStyle:Code
10606 \begin_layout Plain Layout
10613 \begin_inset Flex CharStyle:Code
10616 \begin_layout Plain Layout
10625 \begin_layout Description
10626 \begin_inset Flex CharStyle:Code
10629 \begin_layout Plain Layout
10636 \begin_inset Flex CharStyle:Code
10639 \begin_layout Plain Layout
10644 , onehalf, double, other
10653 ] This defines what the default spacing should be in the layout.
10655 \begin_inset Flex CharStyle:Code
10658 \begin_layout Plain Layout
10665 \begin_inset Flex CharStyle:Code
10668 \begin_layout Plain Layout
10675 \begin_inset Flex CharStyle:Code
10678 \begin_layout Plain Layout
10684 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10685 If you specify the argument
10686 \begin_inset Flex CharStyle:Code
10689 \begin_layout Plain Layout
10695 , then you should also provide a numerical argument which will be the actual
10697 Note that, contrary to other parameters,
10698 \begin_inset Flex CharStyle:Code
10701 \begin_layout Plain Layout
10707 implies the generation of specific LaTeX code, using the package
10710 \begin_inset Flex CharStyle:Code
10713 \begin_layout Plain Layout
10722 \begin_layout Description
10723 \begin_inset Flex CharStyle:Code
10726 \begin_layout Plain Layout
10732 The font used for the text body .
10734 \begin_inset CommandInset ref
10736 reference "sec:fonts"
10743 \begin_layout Description
10744 \begin_inset Flex CharStyle:Code
10747 \begin_layout Plain Layout
10755 The level of the style in the table of contents.
10756 This is used for automatic numbering of section headings.
10759 \begin_layout Description
10760 \begin_inset Flex CharStyle:Code
10763 \begin_layout Plain Layout
10770 \begin_inset Flex CharStyle:Code
10773 \begin_layout Plain Layout
10779 ] The vertical space with which the very first of a chain of paragraphs
10780 with this layout is separated from the previous paragraph.
10781 If the previous paragraph has another layout, the separations are not simply
10782 added, but the maximum is taken.
10785 \begin_layout Subsection
10789 \begin_layout Standard
10790 \begin_inset CommandInset label
10796 Since version 1.3.0 of LyX, it is has been both possible and necessary to
10797 define the floats (
10798 \begin_inset Flex CharStyle:MenuItem
10801 \begin_layout Plain Layout
10808 \begin_inset Flex CharStyle:MenuItem
10811 \begin_layout Plain Layout
10817 , \SpecialChar \ldots{}
10818 ) in the text class itself.
10819 Standard floats are included in the file
10820 \begin_inset Flex CharStyle:Code
10823 \begin_layout Plain Layout
10829 , so you may have to do no more than add
10832 \begin_layout LyX-Code
10833 Input stdfloats.inc
10836 \begin_layout Standard
10837 to your layout file.
10838 If you want to implement a text class that proposes some other float types
10839 (like the AGU class bundled with LyX), the information below will hopefully
10843 \begin_layout Description
10844 \begin_inset Flex CharStyle:Code
10847 \begin_layout Plain Layout
10854 \begin_inset Flex CharStyle:Code
10857 \begin_layout Plain Layout
10864 \begin_inset Quotes erd
10868 \begin_inset Quotes erd
10871 ] The file name extension of an auxiliary file for the list of figures (or
10873 LaTeX writes the captions to this file.
10876 \begin_layout Description
10877 \begin_inset Flex CharStyle:Code
10880 \begin_layout Plain Layout
10887 \begin_inset Flex CharStyle:Code
10890 \begin_layout Plain Layout
10897 \begin_inset Quotes erd
10901 \begin_inset Quotes erd
10904 ] The string that will be used in the menus and also for the caption.
10907 \begin_layout Description
10908 \begin_inset Flex CharStyle:Code
10911 \begin_layout Plain Layout
10918 \begin_inset Flex CharStyle:Code
10921 \begin_layout Plain Layout
10930 \begin_inset Flex CharStyle:Code
10933 \begin_layout Plain Layout
10940 \begin_inset Flex CharStyle:Code
10943 \begin_layout Plain Layout
10949 if the float is already defined by the LaTeX document class.
10951 \begin_inset Flex CharStyle:Code
10954 \begin_layout Plain Layout
10960 , the float will be defined using the LaTeX package
10961 \begin_inset Flex CharStyle:Code
10964 \begin_layout Plain Layout
10973 \begin_layout Description
10974 \begin_inset Flex CharStyle:Code
10977 \begin_layout Plain Layout
10984 \begin_inset Flex CharStyle:Code
10987 \begin_layout Plain Layout
10994 \begin_inset Quotes erd
10998 \begin_inset Quotes erd
11001 ] The heading used for the list of floats.
11004 \begin_layout Description
11005 \begin_inset Flex CharStyle:Code
11008 \begin_layout Plain Layout
11015 \begin_inset Flex CharStyle:Code
11018 \begin_layout Plain Layout
11025 \begin_inset Quotes erd
11029 \begin_inset Quotes erd
11032 ] This (optional) argument determines whether floats of this class will
11033 be numbered within some sectional unit of the document.
11034 For example, if within is equal to
11035 \begin_inset Flex CharStyle:Code
11038 \begin_layout Plain Layout
11044 , the floats will be numbered within chapters.
11048 \begin_layout Description
11049 \begin_inset Flex CharStyle:Code
11052 \begin_layout Plain Layout
11059 \begin_inset Flex CharStyle:Code
11062 \begin_layout Plain Layout
11069 \begin_inset Quotes erd
11073 \begin_inset Quotes erd
11076 ] The default placement for the given class of floats.
11077 The string should be as in standard LaTeX:
11078 \begin_inset Flex CharStyle:Code
11081 \begin_layout Plain Layout
11088 \begin_inset Flex CharStyle:Code
11091 \begin_layout Plain Layout
11098 \begin_inset Flex CharStyle:Code
11101 \begin_layout Plain Layout
11108 \begin_inset Flex CharStyle:Code
11111 \begin_layout Plain Layout
11117 for top, bottom, page, and here, respectively.
11121 \begin_layout Plain Layout
11122 Note that the order of these letters in the string is irrelevant, like in
11128 On top of that there is a new type,
11129 \begin_inset Flex CharStyle:Code
11132 \begin_layout Plain Layout
11138 , which does not really correspond to a float, since it means: put it
11139 \begin_inset Quotes eld
11143 \begin_inset Quotes erd
11147 Note however that the
11148 \begin_inset Flex CharStyle:Code
11151 \begin_layout Plain Layout
11157 specifier is special and, because of implementation details, cannot be
11158 used in non-builtin float types.
11159 If you do not understand what this means, just use
11160 \begin_inset Quotes eld
11164 \begin_inset Flex CharStyle:Code
11167 \begin_layout Plain Layout
11174 \begin_inset Quotes erd
11180 \begin_layout Description
11181 \begin_inset Flex CharStyle:Code
11184 \begin_layout Plain Layout
11191 \begin_inset Flex CharStyle:Code
11194 \begin_layout Plain Layout
11201 \begin_inset Quotes erd
11205 \begin_inset Quotes erd
11208 ] The style used when defining the float using
11209 \begin_inset Flex CharStyle:Code
11212 \begin_layout Plain Layout
11223 \begin_layout Description
11224 \begin_inset Flex CharStyle:Code
11227 \begin_layout Plain Layout
11234 \begin_inset Flex CharStyle:Code
11237 \begin_layout Plain Layout
11244 \begin_inset Quotes erd
11248 \begin_inset Quotes erd
11252 \begin_inset Quotes eld
11256 \begin_inset Quotes erd
11259 of the new class of floats, like program or algorithm.
11260 After the appropriate
11261 \begin_inset Flex CharStyle:Code
11264 \begin_layout Plain Layout
11273 \begin_inset Flex CharStyle:Code
11276 \begin_layout Plain Layout
11285 \begin_inset Flex CharStyle:Code
11288 \begin_layout Plain Layout
11299 \begin_layout Standard
11300 Note that defining a float with type
11301 \begin_inset Flex CharStyle:Code
11304 \begin_layout Plain Layout
11312 automatically defines the corresponding counter with name
11313 \begin_inset Flex CharStyle:Code
11316 \begin_layout Plain Layout
11327 \begin_layout Subsection
11328 Inset layouts and Flex insets
11331 \begin_layout Standard
11332 \begin_inset CommandInset label
11334 name "sec:charstyle"
11338 LyX has supported character styles since version 1.4.0; since version 1.6.0
11339 these are called Flex insets.
11343 \begin_layout Standard
11344 Furthermore, it is possible to define the general layout of many different
11346 Currently, InsetLayout can be used to customize the layout parameters for
11347 footnotes, marginal notes, note insets, ERT insets, branches, listings,
11348 indexes, boxes, tables, algorithms, URLs, and optional arguments, as well
11353 \begin_layout Standard
11354 Flex insets come in three different kinds:
11357 \begin_layout Itemize
11359 \begin_inset Flex CharStyle:Code
11362 \begin_layout Plain Layout
11368 ): These define semantic markup corresponding to such LaTeX commands as
11370 \begin_inset Flex CharStyle:Code
11373 \begin_layout Plain Layout
11382 \begin_inset Flex CharStyle:Code
11385 \begin_layout Plain Layout
11396 \begin_layout Itemize
11398 \begin_inset Flex CharStyle:Code
11401 \begin_layout Plain Layout
11407 ): These can be used to define custom collapsable insets, similar to ERT,
11408 footnote, and the like.
11411 \begin_layout Itemize
11413 \begin_inset Flex CharStyle:Code
11416 \begin_layout Plain Layout
11422 ): For use with DocBook classes.
11425 \begin_layout Standard
11427 \begin_inset Flex CharStyle:Code
11430 \begin_layout Plain Layout
11436 definition starting line is of the form
11439 \begin_layout LyX-Code
11440 InsetLayout <Type> <Name>
11443 \begin_layout Standard
11445 \begin_inset Flex CharStyle:Code
11448 \begin_layout Plain Layout
11455 \begin_inset Flex CharStyle:Code
11458 \begin_layout Plain Layout
11465 \begin_inset Flex CharStyle:Code
11468 \begin_layout Plain Layout
11475 \begin_inset Flex CharStyle:Code
11478 \begin_layout Plain Layout
11485 \begin_inset Flex CharStyle:Code
11488 \begin_layout Plain Layout
11495 \begin_inset Flex CharStyle:Code
11498 \begin_layout Plain Layout
11505 \begin_inset Flex CharStyle:Code
11508 \begin_layout Plain Layout
11515 \begin_inset Flex CharStyle:Code
11518 \begin_layout Plain Layout
11525 \begin_inset Flex CharStyle:Code
11528 \begin_layout Plain Layout
11535 \begin_inset Flex CharStyle:Code
11538 \begin_layout Plain Layout
11545 \begin_inset Flex CharStyle:Code
11548 \begin_layout Plain Layout
11555 \begin_inset Flex CharStyle:Code
11558 \begin_layout Plain Layout
11565 \begin_inset Flex CharStyle:Code
11568 \begin_layout Plain Layout
11575 \begin_inset Flex CharStyle:Code
11578 \begin_layout Plain Layout
11585 \begin_inset Flex CharStyle:Code
11588 \begin_layout Plain Layout
11595 \begin_inset Flex CharStyle:Code
11598 \begin_layout Plain Layout
11605 \begin_inset Flex CharStyle:Code
11608 \begin_layout Plain Layout
11616 \begin_inset Flex CharStyle:Code
11619 \begin_layout Plain Layout
11626 \begin_inset Flex CharStyle:Code
11629 \begin_layout Plain Layout
11636 \begin_inset Flex CharStyle:Code
11639 \begin_layout Plain Layout
11645 should have the form
11646 \begin_inset Flex CharStyle:Code
11649 \begin_layout Plain Layout
11656 \begin_inset Flex CharStyle:Code
11659 \begin_layout Plain Layout
11666 \begin_inset Flex CharStyle:Code
11669 \begin_layout Plain Layout
11676 \begin_inset Flex CharStyle:Code
11679 \begin_layout Plain Layout
11686 \begin_inset Flex CharStyle:Code
11689 \begin_layout Plain Layout
11696 \begin_inset Flex CharStyle:Code
11699 \begin_layout Plain Layout
11705 is any valid identifier.
11709 \begin_layout Standard
11711 \begin_inset Flex CharStyle:Code
11714 \begin_layout Plain Layout
11720 section can contain the following entries:
11723 \begin_layout Description
11724 \begin_inset Flex CharStyle:Code
11727 \begin_layout Plain Layout
11733 The color for the inset's background.
11734 These valid colors are defined in
11735 \begin_inset Flex CharStyle:Code
11738 \begin_layout Plain Layout
11747 \begin_layout Description
11748 \begin_inset Flex CharStyle:Code
11751 \begin_layout Plain Layout
11757 As with paragraph styles (see page
11758 \begin_inset CommandInset ref
11760 reference "des:CopyStyle"
11767 \begin_layout Description
11768 \begin_inset Flex CharStyle:Code
11771 \begin_layout Plain Layout
11778 \begin_inset Flex CharStyle:Code
11781 \begin_layout Plain Layout
11790 \begin_inset Flex CharStyle:Code
11793 \begin_layout Plain Layout
11799 ] Indicates whether the user may employ the Paragraph Settings dialog to
11800 customize the paragraph.
11803 \begin_layout Description
11804 \begin_inset Flex CharStyle:Code
11807 \begin_layout Plain Layout
11814 \begin_inset Flex CharStyle:Code
11817 \begin_layout Plain Layout
11824 \begin_inset Flex CharStyle:Code
11827 \begin_layout Plain Layout
11834 \begin_inset Flex CharStyle:Code
11837 \begin_layout Plain Layout
11843 , describing the rendering style used for the inset's frame and buttons.
11844 Footnotes generally use
11845 \begin_inset Flex CharStyle:Code
11848 \begin_layout Plain Layout
11854 ; ERT insets generally use
11855 \begin_inset Flex CharStyle:Code
11858 \begin_layout Plain Layout
11864 ; and character styles use
11865 \begin_inset Flex CharStyle:Code
11868 \begin_layout Plain Layout
11877 \begin_layout Description
11878 \begin_inset Flex CharStyle:Code
11881 \begin_layout Plain Layout
11887 Required at the end of the InsetLayout declarations.
11890 \begin_layout Description
11891 \begin_inset Flex CharStyle:Code
11894 \begin_layout Plain Layout
11900 The font used for both the text body
11906 \begin_inset space ~
11910 \begin_inset CommandInset ref
11912 reference "sec:fonts"
11917 Note that defining this font automatically defines the
11918 \begin_inset Flex CharStyle:Code
11921 \begin_layout Plain Layout
11927 to the same value, so define this first and define
11928 \begin_inset Flex CharStyle:Code
11931 \begin_layout Plain Layout
11937 later if you want them to be different.
11940 \begin_layout Description
11941 \begin_inset Flex CharStyle:Code
11944 \begin_layout Plain Layout
11953 \begin_layout Description
11954 \begin_inset Flex CharStyle:Code
11957 \begin_layout Plain Layout
11964 \begin_inset Flex CharStyle:Code
11967 \begin_layout Plain Layout
11976 \begin_inset Flex CharStyle:Code
11979 \begin_layout Plain Layout
11985 ] Indicates whether the PlainLayout should be used or, instead, the user
11986 can change the paragraph style used in the inset.
11989 \begin_layout Description
11990 \begin_inset Flex CharStyle:Code
11993 \begin_layout Plain Layout
11999 As with paragraph styles (see page
12000 \begin_inset CommandInset ref
12001 LatexCommand pageref
12002 reference "des:FreeSpacing"
12009 \begin_layout Description
12010 \begin_inset Flex CharStyle:Code
12013 \begin_layout Plain Layout
12019 As with paragraph styles (see page
12020 \begin_inset CommandInset ref
12021 LatexCommand pageref
12022 reference "des:KeepEmpty"
12029 \begin_layout Description
12030 \begin_inset Flex CharStyle:Code
12033 \begin_layout Plain Layout
12039 The font used for the label.
12041 \begin_inset space ~
12045 \begin_inset CommandInset ref
12047 reference "sec:fonts"
12052 Note that this definition can never appear before
12053 \begin_inset Flex CharStyle:Code
12056 \begin_layout Plain Layout
12062 , lest it be ineffective.
12065 \begin_layout Description
12066 \begin_inset Flex CharStyle:Code
12069 \begin_layout Plain Layout
12075 What will be displayed on the button or elsewhere as the inset label.
12076 Some inset types (ERT and Branch) modify this label on the fly.
12079 \begin_layout Description
12080 \begin_inset Flex CharStyle:Code
12083 \begin_layout Plain Layout
12089 The name of the corresponding LaTeX stuff.
12090 Either the environment or command name.
12093 \begin_layout Description
12094 \begin_inset Flex CharStyle:Code
12097 \begin_layout Plain Layout
12103 The optional parameter for the corresponding
12104 \begin_inset Flex CharStyle:Code
12107 \begin_layout Plain Layout
12113 stuff, including possible bracket pairs like
12114 \begin_inset Flex CharStyle:Code
12117 \begin_layout Plain Layout
12124 This parameter cannot be changed from within LyX.
12127 \begin_layout Description
12128 \begin_inset Flex CharStyle:Code
12131 \begin_layout Plain Layout
12137 As with paragraph styles (see page
12138 \begin_inset CommandInset ref
12139 LatexCommand pageref
12140 reference "des:LatexType"
12147 \begin_layout Description
12148 \begin_inset Flex CharStyle:Code
12151 \begin_layout Plain Layout
12158 \begin_inset Flex CharStyle:Code
12161 \begin_layout Plain Layout
12168 \begin_inset Flex CharStyle:Code
12171 \begin_layout Plain Layout
12178 \begin_inset Flex CharStyle:Code
12181 \begin_layout Plain Layout
12188 \begin_inset Flex CharStyle:Code
12191 \begin_layout Plain Layout
12197 (indicating a dummy definition ending definitions of charstyles etc.).
12198 This entry is only meaningful for Flex (user definable) insets.
12201 \begin_layout Description
12202 \begin_inset Flex CharStyle:Code
12205 \begin_layout Plain Layout
12212 \begin_inset Flex CharStyle:Code
12215 \begin_layout Plain Layout
12224 \begin_inset Flex CharStyle:Code
12227 \begin_layout Plain Layout
12233 ] Whether multiple paragraphs are permitted in this inset.
12234 This will also set CustomPars to the same value and ForcePlain to the opposite
12236 These can be reset to other values, if they are used
12243 \begin_layout Description
12244 \begin_inset Flex CharStyle:Code
12247 \begin_layout Plain Layout
12254 \begin_inset Flex CharStyle:Code
12257 \begin_layout Plain Layout
12266 \begin_inset Flex CharStyle:Code
12269 \begin_layout Plain Layout
12275 ] Whether fragile commands in this layout should be
12276 \begin_inset Flex CharStyle:Code
12279 \begin_layout Plain Layout
12292 whether this command should itself be protected.)
12295 \begin_layout Description
12296 \begin_inset Flex CharStyle:Code
12299 \begin_layout Plain Layout
12306 \begin_inset Flex CharStyle:Code
12309 \begin_layout Plain Layout
12318 \begin_inset Flex CharStyle:Code
12321 \begin_layout Plain Layout
12327 ] As with paragraph styles (see page
12328 \begin_inset CommandInset ref
12330 reference "des:PathThru"
12337 \begin_layout Description
12338 \begin_inset Flex CharStyle:Code
12341 \begin_layout Plain Layout
12347 As with paragraph styles (see page
12348 \begin_inset CommandInset ref
12349 LatexCommand pageref
12350 reference "des:Preamble"
12357 \begin_layout Description
12358 \begin_inset Flex CharStyle:Code
12361 \begin_layout Plain Layout
12368 \begin_inset Flex CharStyle:Code
12371 \begin_layout Plain Layout
12377 ] As with paragraph styles (see page
12378 \begin_inset CommandInset ref
12379 LatexCommand pageref
12380 reference "des:Requires"
12387 \begin_layout Subsection
12391 \begin_layout Standard
12392 \begin_inset CommandInset label
12398 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12400 \begin_inset Flex CharStyle:MenuItem
12403 \begin_layout Plain Layout
12410 \begin_inset Flex CharStyle:MenuItem
12413 \begin_layout Plain Layout
12419 , \SpecialChar \ldots{}
12420 ) in the text class itself.
12421 The standard counters are defined in the file
12422 \begin_inset Flex CharStyle:Code
12425 \begin_layout Plain Layout
12431 , so you may have to do no more than add
12434 \begin_layout LyX-Code
12435 Input stdcounters.inc
12438 \begin_layout Standard
12439 to your layout file to get them to work.
12440 But if you want to define custom counters, then you can do so.
12441 The counter declaration must begin with:
12444 \begin_layout LyX-Code
12448 \begin_layout Standard
12449 where of course `name' is replaced by the name of the counter.
12450 And it must end with
12451 \begin_inset Quotes eld
12455 \begin_inset Flex CharStyle:Code
12458 \begin_layout Plain Layout
12465 \begin_inset Quotes erd
12469 The following parameters can also be used:
12472 \begin_layout Description
12473 \begin_inset Flex CharStyle:Code
12476 \begin_layout Plain Layout
12477 LabelString [string=""]
12482 when this is defined, this string defines how the counter is displayed.
12483 Setting this value sets
12484 \begin_inset Flex CharStyle:Code
12487 \begin_layout Plain Layout
12488 LabelStringAppendix
12494 The following special constructs can be used in the string:
12498 \begin_layout Itemize
12499 \begin_inset Flex CharStyle:Code
12502 \begin_layout Plain Layout
12510 will be replaced by the expansion of the
12511 \begin_inset Flex CharStyle:Code
12514 \begin_layout Plain Layout
12521 \begin_inset Flex CharStyle:Code
12524 \begin_layout Plain Layout
12525 LabelStringAppendix
12531 \begin_inset Flex CharStyle:Code
12534 \begin_layout Plain Layout
12544 \begin_layout Itemize
12545 counter values can be expressed using LaTeX-like macros
12546 \begin_inset Flex CharStyle:Code
12549 \begin_layout Plain Layout
12566 \begin_inset Flex CharStyle:Code
12569 \begin_layout Plain Layout
12581 \begin_layout Plain Layout
12591 Actually, the situation is a bit more complicated: any
12610 other than those descibed below will produce arabic numerals.
12611 It would not be surprising to see this change in the future.
12617 \begin_inset Flex CharStyle:Code
12620 \begin_layout Plain Layout
12626 : 1, 2, 3,\SpecialChar \ldots{}
12628 \begin_inset Flex CharStyle:Code
12631 \begin_layout Plain Layout
12637 for lower-case letters: a, b, c, \SpecialChar \ldots{}
12639 \begin_inset Flex CharStyle:Code
12642 \begin_layout Plain Layout
12648 for upper-case letters: A, B, C, \SpecialChar \ldots{}
12650 \begin_inset Flex CharStyle:Code
12653 \begin_layout Plain Layout
12659 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12661 \begin_inset Flex CharStyle:Code
12664 \begin_layout Plain Layout
12670 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12672 \begin_inset Flex CharStyle:Code
12675 \begin_layout Plain Layout
12681 for hebrew numerals.
12685 \begin_layout Standard
12686 If LabelString is not defined, a default value is constructed as follows:
12687 if the counter has a master counter
12688 \begin_inset Flex CharStyle:Code
12691 \begin_layout Plain Layout
12698 \begin_inset Flex CharStyle:Code
12701 \begin_layout Plain Layout
12708 \begin_inset Flex CharStyle:Code
12711 \begin_layout Plain Layout
12721 is used; otherwise the string
12722 \begin_inset Flex CharStyle:Code
12725 \begin_layout Plain Layout
12736 \begin_layout Description
12737 \begin_inset Flex CharStyle:Code
12740 \begin_layout Plain Layout
12741 LabelStringAppendix [string=""]
12747 \begin_inset Flex CharStyle:Code
12750 \begin_layout Plain Layout
12756 , but for use in the Appendix.
12759 \begin_layout Description
12760 \begin_inset Flex CharStyle:Code
12763 \begin_layout Plain Layout
12770 \begin_inset Flex CharStyle:Code
12773 \begin_layout Plain Layout
12780 \begin_inset Quotes erd
12784 \begin_inset Quotes erd
12787 ] If this is set to the name of another counter, the present counter will
12788 be reset everytime the other one is increased.
12790 \begin_inset Flex CharStyle:Code
12793 \begin_layout Plain Layout
12800 \begin_inset Flex CharStyle:Code
12803 \begin_layout Plain Layout
12812 \begin_layout Subsection
12816 \begin_layout Standard
12817 \begin_inset CommandInset label
12823 A font description looks like this:
12826 \begin_layout LyX-Code
12836 \begin_layout LyX-Code
12840 \begin_layout LyX-Code
12844 \begin_layout Standard
12845 The following commands are available:
12848 \begin_layout Description
12849 \begin_inset Flex CharStyle:Code
12852 \begin_layout Plain Layout
12859 \begin_inset Flex CharStyle:Code
12862 \begin_layout Plain Layout
12871 \begin_inset Flex CharStyle:Code
12874 \begin_layout Plain Layout
12881 \begin_inset Flex CharStyle:Code
12884 \begin_layout Plain Layout
12891 \begin_inset Flex CharStyle:Code
12894 \begin_layout Plain Layout
12901 \begin_inset Flex CharStyle:Code
12904 \begin_layout Plain Layout
12911 \begin_inset Flex CharStyle:Code
12914 \begin_layout Plain Layout
12921 \begin_inset Flex CharStyle:Code
12924 \begin_layout Plain Layout
12931 \begin_inset Flex CharStyle:Code
12934 \begin_layout Plain Layout
12941 \begin_inset Flex CharStyle:Code
12944 \begin_layout Plain Layout
12953 \begin_layout Description
12954 \begin_inset Flex CharStyle:Code
12957 \begin_layout Plain Layout
12966 \begin_inset Flex CharStyle:Code
12969 \begin_layout Plain Layout
12980 \begin_inset Flex CharStyle:Code
12983 \begin_layout Plain Layout
12990 \begin_inset Flex CharStyle:Code
12993 \begin_layout Plain Layout
13002 \begin_layout Description
13003 \begin_inset Flex CharStyle:Code
13006 \begin_layout Plain Layout
13013 \begin_inset Flex CharStyle:Code
13016 \begin_layout Plain Layout
13022 ] Valid argument sare:
13023 \begin_inset Flex CharStyle:Code
13026 \begin_layout Plain Layout
13033 \begin_inset Flex CharStyle:Code
13036 \begin_layout Plain Layout
13043 \begin_inset Flex CharStyle:Code
13046 \begin_layout Plain Layout
13053 \begin_inset Flex CharStyle:Code
13056 \begin_layout Plain Layout
13063 \begin_inset Flex CharStyle:Code
13066 \begin_layout Plain Layout
13073 \begin_inset Flex CharStyle:Code
13076 \begin_layout Plain Layout
13083 Each of these turns on or off the corresponding attribute.
13086 \begin_layout Description
13087 \begin_inset Flex CharStyle:Code
13090 \begin_layout Plain Layout
13099 \begin_inset Flex CharStyle:Code
13102 \begin_layout Plain Layout
13113 \begin_inset Flex CharStyle:Code
13116 \begin_layout Plain Layout
13125 \begin_layout Description
13126 \begin_inset Flex CharStyle:Code
13129 \begin_layout Plain Layout
13138 \begin_inset Flex CharStyle:Code
13141 \begin_layout Plain Layout
13152 \begin_inset Flex CharStyle:Code
13155 \begin_layout Plain Layout
13162 \begin_inset Flex CharStyle:Code
13165 \begin_layout Plain Layout
13172 \begin_inset Flex CharStyle:Code
13175 \begin_layout Plain Layout
13184 \begin_layout Description
13185 \begin_inset Flex CharStyle:Code
13188 \begin_layout Plain Layout
13195 \begin_inset Flex CharStyle:Code
13198 \begin_layout Plain Layout
13205 \begin_inset Flex CharStyle:Code
13208 \begin_layout Plain Layout
13215 \begin_inset Flex CharStyle:Code
13218 \begin_layout Plain Layout
13227 \begin_inset Flex CharStyle:Code
13230 \begin_layout Plain Layout
13237 \begin_inset Flex CharStyle:Code
13240 \begin_layout Plain Layout
13247 \begin_inset Flex CharStyle:Code
13250 \begin_layout Plain Layout
13257 \begin_inset Flex CharStyle:Code
13260 \begin_layout Plain Layout
13267 \begin_inset Flex CharStyle:Code
13270 \begin_layout Plain Layout
13279 \begin_layout Subsection
13280 Upgrading old layout files
13283 \begin_layout Standard
13284 The file format of layout files changes from time to time, so old layout
13285 files need to be converted.
13286 This process has been automated since LyX 1.4.0: If LyX reads an old format
13287 layout file it will call the conversion tool
13288 \begin_inset Flex CharStyle:Code
13291 \begin_layout Plain Layout
13292 LyXDir/scripts/layout2layout.py
13297 and convert it to a temporary file in current format.
13298 The original file is left untouched.
13299 If you want to convert the layout file permanently, just call the converter
13303 \begin_layout LyX-Code
13304 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13307 \begin_layout Standard
13308 (You need to replace
13309 \begin_inset Flex CharStyle:Code
13312 \begin_layout Plain Layout
13318 with the name of your LyX system directory, unless you happen to have defined
13319 such an environment variable.) Then copy
13320 \begin_inset Flex CharStyle:Code
13323 \begin_layout Plain Layout
13330 \begin_inset Flex CharStyle:Code
13333 \begin_layout Plain Layout
13342 \begin_layout Standard
13343 The automatic conversion only handles syntax changes.
13344 It cannot handle the case where the contents of included files was changed,
13345 so these will have to be converted separately.
13348 \begin_layout Section
13350 \begin_inset CommandInset label
13352 name "sec:templates"
13359 \begin_layout Standard
13360 Templates are created just like usual documents.
13361 The only difference is that usual documents contain all possible settings,
13362 including the font scheme and the paper size.
13363 Usually a user doesn't want a template to overwrite his defaults in these
13365 For that reason, the designer of a template should remove the corresponding
13367 \begin_inset Flex CharStyle:Code
13370 \begin_layout Plain Layout
13379 \begin_inset Flex CharStyle:Code
13382 \begin_layout Plain Layout
13390 from the template LyX file.
13391 This can be done with any simple text-editor, for example
13392 \begin_inset Flex CharStyle:Code
13395 \begin_layout Plain Layout
13402 \begin_inset Flex CharStyle:Code
13405 \begin_layout Plain Layout
13415 \begin_layout Standard
13416 Put the edited template files you create in
13417 \begin_inset Flex CharStyle:Code
13420 \begin_layout Plain Layout
13426 , copy the ones you use from the global template directory in
13427 \begin_inset Flex CharStyle:Code
13430 \begin_layout Plain Layout
13436 to the same place, and redefine the template path in the
13437 \begin_inset Flex CharStyle:MenuItem
13440 \begin_layout Plain Layout
13448 \SpecialChar \menuseparator
13453 references\SpecialChar \menuseparator
13462 \begin_layout Standard
13463 Note that there is a template which has a particular meaning:
13464 \begin_inset Flex CharStyle:Code
13467 \begin_layout Plain Layout
13474 This template is loaded everytime you create a new document with
13475 \begin_inset Flex CharStyle:MenuItem
13478 \begin_layout Plain Layout
13488 \SpecialChar \menuseparator
13490 \begin_inset Flex CharStyle:MenuItem
13493 \begin_layout Plain Layout
13503 in order to provide useful defaults.
13504 To create this template from inside LyX, all you have to do is to open
13505 a document with the correct settings, and use the
13506 \begin_inset Flex CharStyle:MenuItem
13509 \begin_layout Plain Layout
13514 e as Document Defaults
13522 \begin_layout Chapter
13523 Including External Material
13526 \begin_layout Standard
13527 \begin_inset Box Shadowbox
13536 height_special "totalheight"
13539 \begin_layout Plain Layout
13540 WARNING: This portion of the documentation has not been updated for some
13542 We certainly hope that it is still accurate, but there are no guarantees.
13550 \begin_layout Standard
13551 The use of material from sources external to LyX is covered in detail in
13557 This part of the manual covers what needs to happen behind the scenes for
13558 new sorts of material to be included.
13561 \begin_layout Section
13565 \begin_layout Standard
13566 The external material feature is based on the concept of a
13571 A template is a specification of how LyX should interface with a certain
13573 As bundled, LyX comes with predefined templates for Xfig figures, various
13574 raster format images, chess diagrams, and LilyPond music notation.
13575 You can check the actual list by using the menu
13576 \begin_inset Flex CharStyle:MenuItem
13579 \begin_layout Plain Layout
13580 Insert\SpecialChar \menuseparator
13581 File\SpecialChar \menuseparator
13588 Furthermore, it is possible to roll your own template to support a specific
13590 Later we'll describe in more detail what is involved, and hopefully you
13591 will submit all the templates you create so we can include them in a later
13595 \begin_layout Standard
13596 Another basic idea of the external material feature is to distinguish between
13597 the original file that serves as a base for final material and the produced
13598 file that is included in your exported or printed document.
13599 For example, consider the case of a figure produced with
13600 \begin_inset Flex CharStyle:Code
13603 \begin_layout Plain Layout
13610 The Xfig application itself works on an original file with the
13611 \begin_inset Flex CharStyle:Code
13614 \begin_layout Plain Layout
13621 Within XFig, you create and change your figure, and when you are done,
13623 \begin_inset Flex CharStyle:Code
13626 \begin_layout Plain Layout
13633 When you want to include the figure in your document, you invoke
13634 \begin_inset Flex CharStyle:Code
13637 \begin_layout Plain Layout
13643 in order to create a PostScript file that can readily be included in your
13646 \begin_inset Flex CharStyle:Code
13649 \begin_layout Plain Layout
13655 file is the original file, and the PostScript file is the produced file.
13658 \begin_layout Standard
13659 This distinction is important in order to allow updating of the material
13660 while you are in the process of writing the document.
13661 Furthermore, it provides us with the flexibility that is needed to support
13662 multiple export formats.
13663 For instance, in the case of a plain text file, it is not exactly an award-winn
13664 ing idea to include the figure as raw PostScript®.
13665 Instead, you'd either prefer to just include a reference to the figure
13666 or try to invoke some graphics to Ascii converter to make the final result
13667 look similar to the real graphics.
13668 The external material management allows you to do this, because it is parameter
13669 ized on the different export formats that LyX supports.
13672 \begin_layout Standard
13673 Besides supporting the production of different products according to the
13674 exported format, it supports tight integration with editing and viewing
13676 In the case of an XFig figure, you are able to invoke Xfig on the original
13677 file with a single click from within the external material dialog in LyX,
13678 and also preview the produced PostScript file with ghostview with another
13680 No more fiddling around with the command line and/or file browsers to locate
13681 and manipulate the original or produced files.
13682 In this way, you are finally able to take full advantage of the many different
13683 applications that are relevant to use when you write your documents, and
13684 ultimately be more productive.
13687 \begin_layout Section
13688 The external template configuration file
13691 \begin_layout Standard
13692 It is relatively easy to add custom external template definitions to LyX.
13693 However, be aware that doing this in an careless manner most probably
13697 introduce an easily exploitable security hole.
13698 So before you do this, please read the discussion about security in section
13700 \begin_inset CommandInset ref
13702 reference "sec:Security-discussion"
13709 \begin_layout Standard
13710 Having said that, we encourage you to submit any interesting templates that
13715 \begin_layout Standard
13716 The external templates are defined in the
13717 \begin_inset Flex CharStyle:Code
13720 \begin_layout Plain Layout
13721 LyXDir/lib/external_templates
13727 You can place your own version in
13728 \begin_inset Flex CharStyle:Code
13731 \begin_layout Plain Layout
13732 UserDir/external_templates
13740 \begin_layout Standard
13741 A typical template looks like this:
13744 \begin_layout LyX-Code
13748 \begin_layout LyX-Code
13749 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
13752 \begin_layout LyX-Code
13756 \begin_layout LyX-Code
13760 \begin_layout LyX-Code
13764 \begin_layout LyX-Code
13768 \begin_layout LyX-Code
13772 \begin_layout LyX-Code
13773 AutomaticProduction true
13776 \begin_layout LyX-Code
13780 \begin_layout LyX-Code
13784 \begin_layout LyX-Code
13788 \begin_layout LyX-Code
13789 TransformCommand Rotate RotationLatexCommand
13792 \begin_layout LyX-Code
13793 TransformCommand Resize ResizeLatexCommand
13796 \begin_layout LyX-Code
13797 Product "$$RotateFront$$ResizeFront
13800 \begin_layout LyX-Code
13805 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
13808 \begin_layout LyX-Code
13809 $$ResizeBack$$RotateBack"
13812 \begin_layout LyX-Code
13816 \begin_layout LyX-Code
13817 UpdateResult "$$AbsPath$$Basename.pstex_t"
13820 \begin_layout LyX-Code
13821 Requirement "graphicx"
13824 \begin_layout LyX-Code
13825 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
13828 \begin_layout LyX-Code
13829 ReferencedFile latex "$$AbsPath$$Basename.eps"
13832 \begin_layout LyX-Code
13833 ReferencedFile dvi "$$AbsPath$$Basename.eps"
13836 \begin_layout LyX-Code
13840 \begin_layout LyX-Code
13844 \begin_layout LyX-Code
13845 TransformCommand Rotate RotationLatexCommand
13848 \begin_layout LyX-Code
13849 TransformCommand Resize ResizeLatexCommand
13852 \begin_layout LyX-Code
13853 Product "$$RotateFront$$ResizeFront
13856 \begin_layout LyX-Code
13861 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
13864 \begin_layout LyX-Code
13865 $$ResizeBack$$RotateBack"
13868 \begin_layout LyX-Code
13869 UpdateFormat pdftex
13872 \begin_layout LyX-Code
13873 UpdateResult "$$AbsPath$$Basename.pdftex_t"
13876 \begin_layout LyX-Code
13877 Requirement "graphicx"
13880 \begin_layout LyX-Code
13881 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
13884 \begin_layout LyX-Code
13885 ReferencedFile latex "$$AbsPath$$Basename.pdf"
13888 \begin_layout LyX-Code
13892 \begin_layout LyX-Code
13896 \begin_layout LyX-Code
13897 Product "$$Contents(
13899 "$$AbsPath$$Basename.asc
13904 \begin_layout LyX-Code
13905 UpdateFormat asciixfig
13908 \begin_layout LyX-Code
13909 UpdateResult "$$AbsPath$$Basename.asc"
13912 \begin_layout LyX-Code
13916 \begin_layout LyX-Code
13920 \begin_layout LyX-Code
13921 Product "<graphic fileref=
13923 "$$AbsOrRelPathMaster$$Basename.eps
13928 \begin_layout LyX-Code
13932 \begin_layout LyX-Code
13936 \begin_layout LyX-Code
13937 UpdateResult "$$AbsPath$$Basename.eps"
13940 \begin_layout LyX-Code
13941 ReferencedFile docbook "$$AbsPath$$Basename.eps"
13944 \begin_layout LyX-Code
13945 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
13948 \begin_layout LyX-Code
13952 \begin_layout LyX-Code
13953 Product "[XFig: $$FName]"
13956 \begin_layout LyX-Code
13960 \begin_layout LyX-Code
13964 \begin_layout Standard
13965 As you can see, the template is enclosed in
13966 \begin_inset Flex CharStyle:Code
13969 \begin_layout Plain Layout
13975 \SpecialChar \ldots{}
13977 \begin_inset Flex CharStyle:Code
13980 \begin_layout Plain Layout
13987 It contains a header specifying some general settings and, for each supported
13988 primary document file format, a section
13989 \begin_inset Flex CharStyle:Code
13992 \begin_layout Plain Layout
13998 \SpecialChar \ldots{}
14000 \begin_inset Flex CharStyle:Code
14003 \begin_layout Plain Layout
14012 \begin_layout Subsection
14013 The template header
14016 \begin_layout Description
14017 \begin_inset Flex CharStyle:Code
14020 \begin_layout Plain Layout
14021 AutomaticProduction
14022 \begin_inset space ~
14030 Whether the file represented by the template must be generated by LyX.
14031 This command must occur exactly once.
14034 \begin_layout Description
14035 \begin_inset Flex CharStyle:Code
14038 \begin_layout Plain Layout
14040 \begin_inset space ~
14048 A glob pattern that is used in the file dialog to filter out the desired
14050 If there is more than one possible file extension (e.g.
14051 \begin_inset space ~
14055 \begin_inset Flex CharStyle:Code
14058 \begin_layout Plain Layout
14065 \begin_inset Flex CharStyle:Code
14068 \begin_layout Plain Layout
14074 ), use something like
14075 \begin_inset Flex CharStyle:Code
14078 \begin_layout Plain Layout
14085 This command must occur exactly once.
14088 \begin_layout Description
14089 \begin_inset Flex CharStyle:Code
14092 \begin_layout Plain Layout
14094 \begin_inset space ~
14102 The text that is displayed on the button.
14103 This command must occur exactly once.
14106 \begin_layout Description
14107 \begin_inset Flex CharStyle:Code
14110 \begin_layout Plain Layout
14112 \begin_inset space ~
14116 \begin_inset space ~
14124 The help text that is used in the External dialog.
14125 Provide enough information to explain to the user just what the template
14126 can provide him with.
14127 This command must occur exactly once.
14130 \begin_layout Description
14131 \begin_inset Flex CharStyle:Code
14134 \begin_layout Plain Layout
14136 \begin_inset space ~
14144 The file format of the original file.
14145 This must be the name of a format that is known to LyX (see section
14146 \begin_inset CommandInset ref
14148 reference "sub:Formats"
14154 \begin_inset Quotes eld
14158 \begin_inset Flex CharStyle:Code
14161 \begin_layout Plain Layout
14168 \begin_inset Quotes erd
14171 if the template can handle original files of more than one format.
14172 LyX will attempt to interrogate the file itself in order to deduce its
14173 format in this case.
14174 This command must occur exactly once.
14177 \begin_layout Description
14178 \begin_inset Flex CharStyle:Code
14181 \begin_layout Plain Layout
14183 \begin_inset space ~
14191 A unique name for the template.
14192 It must not contain substitution macros (see below).
14195 \begin_layout Description
14196 \begin_inset Flex CharStyle:Code
14199 \begin_layout Plain Layout
14201 \begin_inset space ~
14204 Rotate|Resize|Clip|Extra
14209 This command specifies which transformations are supported by this template.
14210 It may occur zero or more times.
14211 This command enables the corresponding tabs in the external dialog.
14213 \begin_inset Flex CharStyle:Code
14216 \begin_layout Plain Layout
14222 command must have either a corresponding
14223 \begin_inset Flex CharStyle:Code
14226 \begin_layout Plain Layout
14233 \begin_inset Flex CharStyle:Code
14236 \begin_layout Plain Layout
14243 \begin_inset Flex CharStyle:Code
14246 \begin_layout Plain Layout
14253 Otherwise the transformation will not be supported by that format.
14256 \begin_layout Subsection
14260 \begin_layout Description
14261 \begin_inset Flex CharStyle:Code
14264 \begin_layout Plain Layout
14266 \begin_inset space ~
14269 LaTeX|PDFLaTeX|PlainText|DocBook
14274 The primary document file format that this format definition is for.
14275 Not every template has a sensible representation in all document file formats.
14276 Please define nevertheless a
14277 \begin_inset Flex CharStyle:Code
14280 \begin_layout Plain Layout
14286 section for all formats.
14287 Use a dummy text when no representation is available.
14288 Then you can at least see a reference to the external material in the exported
14292 \begin_layout Description
14293 \begin_inset Flex CharStyle:Code
14296 \begin_layout Plain Layout
14298 \begin_inset space ~
14302 \begin_inset space ~
14310 This command defines an additional macro
14311 \begin_inset Flex CharStyle:Code
14314 \begin_layout Plain Layout
14320 for substitution in
14321 \begin_inset Flex CharStyle:Code
14324 \begin_layout Plain Layout
14332 \begin_inset Flex CharStyle:Code
14335 \begin_layout Plain Layout
14341 itself may contain substitution macros.
14342 The advantage over using
14343 \begin_inset Flex CharStyle:Code
14346 \begin_layout Plain Layout
14353 \begin_inset Flex CharStyle:Code
14356 \begin_layout Plain Layout
14362 is that the substituted value of
14363 \begin_inset Flex CharStyle:Code
14366 \begin_layout Plain Layout
14372 is sanitized so that it is a valid optional argument in the document format.
14373 This command may occur zero or more times.
14376 \begin_layout Description
14377 \begin_inset Flex CharStyle:Code
14380 \begin_layout Plain Layout
14382 \begin_inset space ~
14390 The text that is inserted in the exported document.
14391 This is actually the most important command and can be quite complex.
14392 This command must occur exactly once.
14395 \begin_layout Description
14396 \begin_inset Flex CharStyle:Code
14399 \begin_layout Plain Layout
14401 \begin_inset space ~
14409 This command specifies a preamble snippet that will be included in the
14411 It has to be defined using
14412 \begin_inset Flex CharStyle:Code
14415 \begin_layout Plain Layout
14421 \SpecialChar \ldots{}
14423 \begin_inset Flex CharStyle:Code
14426 \begin_layout Plain Layout
14433 This command may occur zero or more times.
14436 \begin_layout Description
14437 \begin_inset Flex CharStyle:Code
14440 \begin_layout Plain Layout
14442 \begin_inset space ~
14446 \begin_inset space ~
14454 This command denotes files that are created by the conversion process and
14455 are needed for a particular export format.
14456 If the filename is relative, it is interpreted relative to the master document.
14457 This command may be given zero or more times.
14460 \begin_layout Description
14461 \begin_inset Flex CharStyle:Code
14464 \begin_layout Plain Layout
14466 \begin_inset space ~
14474 The name of a required LaTeX package.
14475 The package is included via
14476 \begin_inset Flex CharStyle:Code
14479 \begin_layout Plain Layout
14487 in the LaTeX preamble.
14488 This command may occur zero or more times.
14491 \begin_layout Description
14492 \begin_inset Flex CharStyle:Code
14495 \begin_layout Plain Layout
14497 \begin_inset space ~
14501 \begin_inset space ~
14504 RotationLatexCommand
14509 This command specifies that the built in LaTeX command should be used for
14511 This command may occur once or not at all.
14514 \begin_layout Description
14515 \begin_inset Flex CharStyle:Code
14518 \begin_layout Plain Layout
14520 \begin_inset space ~
14524 \begin_inset space ~
14532 This command specifies that the built in LaTeX command should be used for
14534 This command may occur once or not at all.
14537 \begin_layout Description
14538 \begin_inset Flex CharStyle:Code
14541 \begin_layout Plain Layout
14543 \begin_inset space ~
14547 \begin_inset space ~
14550 RotationLatexOption
14555 This command specifies that rotation is done via an optional argument.
14556 This command may occur once or not at all.
14559 \begin_layout Description
14560 \begin_inset Flex CharStyle:Code
14563 \begin_layout Plain Layout
14565 \begin_inset space ~
14569 \begin_inset space ~
14577 This command specifies that resizing is done via an optional argument.
14578 This command may occur once or not at all.
14581 \begin_layout Description
14582 \begin_inset Flex CharStyle:Code
14585 \begin_layout Plain Layout
14587 \begin_inset space ~
14591 \begin_inset space ~
14599 This command specifies that clipping is done via an optional argument.
14600 This command may occur once or not at all.
14603 \begin_layout Description
14604 \begin_inset Flex CharStyle:Code
14607 \begin_layout Plain Layout
14609 \begin_inset space ~
14613 \begin_inset space ~
14621 This command specifies that an extra optional argument is used.
14622 This command may occur once or not at all.
14625 \begin_layout Description
14626 \begin_inset Flex CharStyle:Code
14629 \begin_layout Plain Layout
14631 \begin_inset space ~
14639 The file format of the converted file.
14640 This must be the name of a format that is known to LyX (see the
14641 \begin_inset Flex CharStyle:MenuItem
14644 \begin_layout Plain Layout
14649 ools\SpecialChar \menuseparator
14654 references:Conversion
14660 This command must occur exactly once.
14663 \begin_layout Description
14664 \begin_inset Flex CharStyle:Code
14667 \begin_layout Plain Layout
14669 \begin_inset space ~
14677 The file name of the converted file.
14678 The file name must be absolute.
14679 This command must occur exactly once.
14682 \begin_layout Subsection
14683 Preamble definitions
14686 \begin_layout Standard
14687 The external template configuration file may contain additional preamble
14688 definitions enclosed by
14689 \begin_inset Flex CharStyle:Code
14692 \begin_layout Plain Layout
14698 \SpecialChar \ldots{}
14700 \begin_inset Flex CharStyle:Code
14703 \begin_layout Plain Layout
14710 They can be used by the templates in the
14711 \begin_inset Flex CharStyle:Code
14714 \begin_layout Plain Layout
14723 \begin_layout Section
14724 The substitution mechanism
14727 \begin_layout Standard
14728 When the external material facility invokes an external program, it is done
14729 on the basis of a command defined in the template configuration file.
14730 These commands can contain various macros that are expanded before execution.
14731 Execution always take place in the directory of the containing document.
14734 \begin_layout Standard
14735 Also, whenever external material is to be displayed, the name will be produced
14736 by the substitution mechanism, and most other commands in the template
14737 definition support substitution as well.
14740 \begin_layout Standard
14741 The available macros are the following:
14744 \begin_layout Description
14745 \begin_inset Flex CharStyle:Code
14748 \begin_layout Plain Layout
14749 $$AbsOrRelPathMaster
14754 The file path, absolute or relative to the master LyX document.
14757 \begin_layout Description
14758 \begin_inset Flex CharStyle:Code
14761 \begin_layout Plain Layout
14762 $$AbsOrRelPathParent
14767 The file path, absolute or relative to the LyX document.
14770 \begin_layout Description
14771 \begin_inset Flex CharStyle:Code
14774 \begin_layout Plain Layout
14780 The absolute file path.
14783 \begin_layout Description
14784 \begin_inset Flex CharStyle:Code
14787 \begin_layout Plain Layout
14793 The filename without path and without the extension.
14796 \begin_layout Description
14797 \begin_inset Flex CharStyle:Code
14800 \begin_layout Plain Layout
14802 \begin_inset Quotes eld
14806 \begin_inset Quotes erd
14814 This macro will expand to the contents of the file with the name
14815 \begin_inset Flex CharStyle:Code
14818 \begin_layout Plain Layout
14827 \begin_layout Description
14828 \begin_inset Flex CharStyle:Code
14831 \begin_layout Plain Layout
14837 The file extension (including the dot).
14840 \begin_layout Description
14841 \begin_inset Flex CharStyle:Code
14844 \begin_layout Plain Layout
14850 The filename of the file specified in the external material dialog.
14851 This is either an absolute name, or it is relative to the LyX document.
14854 \begin_layout Description
14855 \begin_inset Flex CharStyle:Code
14858 \begin_layout Plain Layout
14865 \begin_inset Flex CharStyle:Code
14868 \begin_layout Plain Layout
14874 (absolute name or relative to the LyX document).
14877 \begin_layout Description
14878 \begin_inset Flex CharStyle:Code
14881 \begin_layout Plain Layout
14887 The file path, relative to the master LyX document.
14890 \begin_layout Description
14891 \begin_inset Flex CharStyle:Code
14894 \begin_layout Plain Layout
14900 The file path, relative to the LyX document.
14903 \begin_layout Description
14904 \begin_inset Flex CharStyle:Code
14907 \begin_layout Plain Layout
14913 This macro will expand to the absolute path of the system directory.
14914 This is typically used to point to the various helper scripts that are
14918 \begin_layout Description
14919 \begin_inset Flex CharStyle:Code
14922 \begin_layout Plain Layout
14928 A name and full path to a temporary file which will be automatically deleted
14929 whenever the containing document is closed, or the external material insertion
14933 \begin_layout Standard
14934 All path macros contain a trailing directory separator, so you can construct
14936 the absolute filename with
14937 \begin_inset Flex CharStyle:Code
14940 \begin_layout Plain Layout
14941 $$AbsPath$$Basename$$Extension
14949 \begin_layout Standard
14950 The macros above are substituted in all commands unless otherwise noted.
14952 \begin_inset Flex CharStyle:Code
14955 \begin_layout Plain Layout
14961 supports additionally the following substitutions if they are enabled by
14963 \begin_inset Flex CharStyle:Code
14966 \begin_layout Plain Layout
14973 \begin_inset Flex CharStyle:Code
14976 \begin_layout Plain Layout
14985 \begin_layout Description
14986 \begin_inset Flex CharStyle:Code
14989 \begin_layout Plain Layout
14995 The front part of the resize command.
14998 \begin_layout Description
14999 \begin_inset Flex CharStyle:Code
15002 \begin_layout Plain Layout
15008 The back part of the resize command.
15011 \begin_layout Description
15012 \begin_inset Flex CharStyle:Code
15015 \begin_layout Plain Layout
15021 The front part of the rotation command.
15024 \begin_layout Description
15025 \begin_inset Flex CharStyle:Code
15028 \begin_layout Plain Layout
15034 The back part of the rotation command.
15037 \begin_layout Standard
15038 The value string of the
15039 \begin_inset Flex CharStyle:Code
15042 \begin_layout Plain Layout
15048 command supports additionally the following substitutions if they are enabled
15050 \begin_inset Flex CharStyle:Code
15053 \begin_layout Plain Layout
15060 \begin_inset Flex CharStyle:Code
15063 \begin_layout Plain Layout
15072 \begin_layout Description
15073 \begin_inset Flex CharStyle:Code
15076 \begin_layout Plain Layout
15085 \begin_layout Description
15086 \begin_inset Flex CharStyle:Code
15089 \begin_layout Plain Layout
15098 \begin_layout Description
15099 \begin_inset Flex CharStyle:Code
15102 \begin_layout Plain Layout
15111 \begin_layout Description
15112 \begin_inset Flex CharStyle:Code
15115 \begin_layout Plain Layout
15121 The rotation option.
15124 \begin_layout Standard
15125 You may ask why there are so many path macros.
15126 There are mainly two reasons:
15129 \begin_layout Enumerate
15130 Relative and absolute file names should remain relative or absolute, respectivel
15132 Users may have reasons to prefer either form.
15133 Relative names are useful for portable documents that should work on different
15134 machines, for example.
15135 Absolute names may be required by some programs.
15138 \begin_layout Enumerate
15139 LaTeX treats relative file names differently than LyX and other programs
15140 in nested included files.
15141 For LyX, a relative file name is always relative to the document that contains
15143 For LaTeX, it is always relative to the master document.
15144 These two definitions are identical if you have only one document, but
15145 differ if you have a master document that includes part documents.
15146 That means that relative filenames must be transformed when presented to
15148 Fortunately LyX does this automatically for you if you choose the right
15152 \begin_layout Standard
15153 So which path macro should be used in new template definitions? The rule
15157 \begin_layout Itemize
15159 \begin_inset Flex CharStyle:Code
15162 \begin_layout Plain Layout
15168 if an absolute path is required.
15171 \begin_layout Itemize
15173 \begin_inset Flex CharStyle:Code
15176 \begin_layout Plain Layout
15177 $$AbsOrRelPathMaster
15182 if the substituted string is some kind of LaTeX input.
15185 \begin_layout Itemize
15187 \begin_inset Flex CharStyle:Code
15190 \begin_layout Plain Layout
15191 $$AbsOrRelPathParent
15196 in order to preserve the user's choice.
15199 \begin_layout Standard
15200 There are special cases where this rule does not work and e.g.
15201 \begin_inset space ~
15204 relative names are needed, but normally it will work just fine.
15205 One example for such a case is the command
15206 \begin_inset Flex CharStyle:Code
15209 \begin_layout Plain Layout
15210 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15215 in the XFig template above: We can't use the absolute name because the
15217 \begin_inset Flex CharStyle:Code
15220 \begin_layout Plain Layout
15226 files needs the relative name in order to rewrite the file content.
15229 \begin_layout Section
15230 \begin_inset CommandInset label
15232 name "sec:Security-discussion"
15236 Security discussion
15239 \begin_layout Standard
15240 \begin_inset Box Shadowbox
15249 height_special "totalheight"
15252 \begin_layout Plain Layout
15253 WARNING: This section is definitely outdated.
15261 \begin_layout Standard
15262 The external material feature interfaces with a lot of external programs
15263 and does so automatically, so we have to consider the security implications
15265 In particular, since you have the option of including your own filenames
15266 and/or parameter strings and those are expanded into a command, it seems
15267 that it would be possible to create a malicious document which executes
15268 arbitrary commands when a user views or prints the document.
15269 This is something we definately want to avoid.
15272 \begin_layout Standard
15273 However, since the external program commands are specified in the template
15274 configuration file only, there are no security issues if LyX is properly
15275 configured with safe templates only.
15276 This is so because the external programs are invoked with the
15277 \begin_inset Flex CharStyle:Code
15280 \begin_layout Plain Layout
15286 -system call rather than the
15287 \begin_inset Flex CharStyle:Code
15290 \begin_layout Plain Layout
15296 system-call, so it's not possible to execute arbitrary commands from the
15297 filename or parameter section via the shell.
15300 \begin_layout Standard
15301 This also implies that you are restricted in what command strings you can
15302 use in the external material templates.
15303 In particular, pipes and redirection are not readily available.
15304 This has to be so if LyX should remain safe.
15305 If you want to use some of the shell features, you should write a safe
15306 script to do this in a controlled manner, and then invoke the script from
15307 the command string.
15309 \begin_inset Flex CharStyle:Code
15312 \begin_layout Plain Layout
15318 directory of the LyX installation, you can find a safe wrapper script
15319 \begin_inset Flex CharStyle:Code
15322 \begin_layout Plain Layout
15323 general_command_wrapper.py
15328 that supports redirection of input and output.
15329 That can serve as an example for how to write safe template scripts.
15330 For a more advanced example that uses
15331 \begin_inset Flex CharStyle:Code
15334 \begin_layout Plain Layout
15340 and friends, take a look at the
15341 \begin_inset Flex CharStyle:Code
15344 \begin_layout Plain Layout
15353 \begin_layout Standard
15354 It is possible to design a template that interacts directly with the shell,
15355 but since this would allow a malicious user to execute arbitrary commands
15356 by writing clever filenames and/or parameters, we generally recommend that
15357 you only use safe scripts that work with the
15358 \begin_inset Flex CharStyle:Code
15361 \begin_layout Plain Layout
15367 system call in a controlled manner.
15368 Of course, for use in a controlled environment, it can be tempting to just
15369 fall back to use ordinary shell scripts.
15370 If you do so, be aware that you
15374 provide an easily exploitable security hole in your system.
15375 Of course it stands to reason that such unsafe templates will never be
15376 included in the standard LyX distribution, although we do encourage people
15377 to submit new templates in the open source tradition.
15378 But LyX as shipped from the official distribution channels will never have
15382 \begin_layout Standard
15383 Including external material provides a lot of power, and you have to be
15384 careful not to introduce security hazards with this power.
15385 A subtle error in a single line in an innocent looking script can open
15386 the door to huge security problems.
15387 So if you do not fully understand the issues, we recommend that you consult
15388 a knowledgable security professional or the LyX development team if you
15389 have any questions about whether a given template is safe or not.
15390 And do this before you use it in an uncontrolled environment.
15393 \begin_layout Chapter
15397 \begin_layout Section
15401 \begin_layout Standard
15402 The `LyX server' allows other programs to talk to LyX, invoke LyX commands,
15403 and retrieve information about the LyX internal state.
15404 This is only intended for advanced users, but they should find it useful.
15405 It is by writing to the LyX server, for example, that bibliography managers,
15406 such as JabRef, are able to
15407 \begin_inset Quotes eld
15411 \begin_inset Quotes erd
15417 \begin_layout Standard
15418 Please note that, at present,
15420 the server does not work on Windows
15426 \begin_layout Plain Layout
15427 There is no reason it cannot do so.
15428 But none of the developers on Windows® have yet implemented this functionality
15437 \begin_layout Section
15438 Starting the LyX Server
15441 \begin_layout Standard
15442 The LyX server works through the use of a pair of named pipes.
15443 These are usually located in
15444 \begin_inset Flex CharStyle:Code
15447 \begin_layout Plain Layout
15454 \begin_inset Quotes eld
15458 \begin_inset Flex CharStyle:Code
15461 \begin_layout Plain Layout
15468 \begin_inset Quotes erd
15472 \begin_inset Quotes eld
15476 \begin_inset Flex CharStyle:Code
15479 \begin_layout Plain Layout
15486 \begin_inset Quotes erd
15490 External programs write into
15491 \begin_inset Flex CharStyle:Code
15494 \begin_layout Plain Layout
15500 and read back data from
15501 \begin_inset Flex CharStyle:Code
15504 \begin_layout Plain Layout
15511 The stem of the pipe names can be defined in the
15512 \begin_inset Flex CharStyle:MenuItem
15515 \begin_layout Plain Layout
15520 ools\SpecialChar \menuseparator
15530 dialog, for example
15531 \begin_inset Flex CharStyle:Code
15534 \begin_layout Plain Layout
15535 "/home/myhome/lyxpipe"
15545 configure this manually in order for the server to start.
15548 \begin_layout Standard
15550 \begin_inset Flex CharStyle:Code
15553 \begin_layout Plain Layout
15560 \begin_inset Flex CharStyle:Code
15563 \begin_layout Plain Layout
15569 ' to create the pipes.
15570 If one of the pipes already exists, LyX will assume that another LyX process
15571 is already running and will not start the server.
15572 This means that if LyX crashes, or if for some other reason, a
15573 \begin_inset Quotes eld
15577 \begin_inset Quotes erd
15580 pipe is left in existence when LyX closes, then LyX will not start the
15582 (This is bug 641.) You will need to delete the pipes manually and then restart
15586 \begin_layout Standard
15587 To have several LyX processes with servers at the same time, you have to
15588 use different configurations, perhaps by using separate user directories,
15590 \begin_inset Flex CharStyle:Code
15593 \begin_layout Plain Layout
15599 file, for each process.
15602 \begin_layout Standard
15603 If you are developing a client program, you might find it useful to enable
15604 debugging information from the LyX server.
15605 Do this by starting LyX as
15606 \begin_inset Flex CharStyle:Code
15609 \begin_layout Plain Layout
15618 \begin_layout Standard
15619 Other than this, there are a few points to consider:
15622 \begin_layout Itemize
15623 Both server and clients must run on UNIX or OS/2 machines.
15624 Communications between LyX on UNIX and clients on OS/2 or vice versa is
15625 not possible right now.
15628 \begin_layout Itemize
15629 On OS/2, only one client can connect to LyXServer at a time.
15632 \begin_layout Itemize
15633 On OS/2, clients must open the input pipe with
15634 \begin_inset Flex CharStyle:Code
15637 \begin_layout Plain Layout
15646 \begin_layout Standard
15647 You can find a complete example client written in C in the source distribution
15649 \begin_inset Flex CharStyle:Code
15652 \begin_layout Plain Layout
15653 development/lyxserver/server_monitor.c
15661 \begin_layout Section
15662 Normal communication
15665 \begin_layout Standard
15666 To issue a LyX call, the client writes a line of ASCII text into the input
15668 This line has the following format:
15671 \begin_layout Quote
15685 \begin_layout Description
15686 clientname is a name that the client can choose arbitrarily.
15687 Its only use is that LyX will echo it if it sends an answer---so a client
15688 can dispatch results from different requesters.
15691 \begin_layout Description
15692 function is the function you want LyX to perform.
15693 It is the same as the commands you'd use in the minibuffer.
15696 \begin_layout Description
15697 argument is an optional argument which is meaningful only to some functions
15699 \begin_inset Quotes eld
15703 \begin_inset Quotes erd
15706 LFUN will insert the argument as text at the cursor position).
15709 \begin_layout Standard
15710 The answer from LyX will arrive in the output pipe and be of the form
15713 \begin_layout Quote
15727 \begin_layout Standard
15736 are just echoed from the command request, while
15740 is more or less useful information filled according to how the command
15741 execution worked out.
15742 Some commands, such as
15743 \begin_inset Quotes eld
15747 \begin_inset Quotes erd
15750 , will return information about the internal state of LyX, while other will
15751 return an empty data-response.
15752 This means that the command execution went fine.
15755 \begin_layout Standard
15756 In case of errors, the response from LyX will have this form
15759 \begin_layout Quote
15773 \begin_layout Standard
15778 should contain an explanation of why the command failed.
15781 \begin_layout Standard
15785 \begin_layout LyX-Code
15786 echo "LYXCMD:test:beginning-of-buffer:" >~/.lyxpipe.in
15789 \begin_layout LyX-Code
15790 echo "LYXCMD:test:get-xy:" >~/.lyxpipe.in
15791 \begin_inset Newline newline
15794 read a <~/.lyxpipe.out
15795 \begin_inset Newline newline
15801 \begin_layout Section
15805 \begin_layout Standard
15806 LyX can notify clients of events going on asynchronously.
15807 Currently it will only do this if the user binds a key sequence with the
15809 \begin_inset Quotes eld
15813 \begin_inset Quotes erd
15817 The format of the string LyX sends is as follows:
15820 \begin_layout Quote
15821 \begin_inset Flex CharStyle:Code
15824 \begin_layout Plain Layout
15835 \begin_layout Standard
15840 is the printed representation of the key sequence that was actually typed
15844 \begin_layout Standard
15845 This mechanism can be used to extend LyX's command set and implement macros.
15846 Bind some key sequence to
15847 \begin_inset Quotes eld
15851 \begin_inset Quotes erd
15855 Then start a client that listens on the output pipe, dispatches the command
15856 according to the sequence, and starts a function that may use LyX calls
15857 and LyX requests to issue a command or a series of commands to LyX.
15860 \begin_layout Section
15861 The simple LyX Server Protocol
15864 \begin_layout Standard
15865 LyX implements a simple protocol that can be used for session management.
15866 All messages are of the form
15869 \begin_layout Quote
15879 \begin_layout Standard
15885 \begin_inset Quotes eld
15889 \begin_inset Quotes erd
15893 \begin_inset Quotes eld
15897 \begin_inset Quotes erd
15902 \begin_inset Quotes eld
15906 \begin_inset Quotes erd
15909 is received from a client, LyX will report back to inform the client that
15910 it's listening to it's messages, while
15911 \begin_inset Quotes eld
15915 \begin_inset Quotes erd
15918 sent from LyX will inform clients that LyX is closing.