1 #LyX 2.0.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 this document prints
10 % out as advertised. If you mess with this preamble,
11 % parts of this document may not print out as expected. If you
12 % have problems LaTeXing this file, please contact
13 % the documentation team
14 % email: lyx-docs@lists.lyx.org
16 \usepackage{ifpdf} % part of the hyperref bundle
17 \ifpdf % if pdflatex is used
19 % set fonts for nicer pdf view
20 \IfFileExists{lmodern.sty}
21 {\usepackage{lmodern}}{}
23 \fi % end if pdflatex is used
25 % the pages of the TOC is numbered roman
26 % and a pdf-bookmark for the TOC is added
27 \let\myTOC\tableofcontents
28 \renewcommand\tableofcontents{%
30 \pdfbookmark[1]{\contentsname}{}
34 % redefine the \LyX macro for PDF bookmarks
35 \def\LyX{\texorpdfstring{%
36 L\kern-.1667em\lower.25em\hbox{Y}\kern-.125emX\@}
39 % used for multi-column text
43 \options fleqn,liststotoc,bibtotoc,idxtotoc,BCOR7.5mm,titlepage,tablecaptionabove
44 \use_default_options false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
67 \font_typewriter default
68 \font_default_family default
76 \default_output_format default
77 \bibtex_command default
78 \index_command default
82 \pdf_title "LyX Configuration Manual"
83 \pdf_author "LyX Team"
84 \pdf_subject "LyX-documentation Customization"
85 \pdf_keywords "LyX, documentation, customization"
87 \pdf_bookmarksnumbered true
88 \pdf_bookmarksopen true
89 \pdf_bookmarksopenlevel 1
94 \pdf_pdfusetitle false
95 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
103 \paperorientation portrait
111 \paragraph_separation indent
112 \paragraph_indentation default
113 \quotes_language english
116 \paperpagestyle headings
117 \tracking_changes false
118 \output_changes false
124 Customizing LyX: Features for the Advanced User
132 \begin_layout Plain Layout
134 If you have comments or error corrections, please send them to the LyX Documenta
136 \begin_inset CommandInset href
138 target "lyx-docs@lists.lyx.org"
145 \begin_inset Quotes eld
149 \begin_inset Quotes erd
152 in the subject header, and please cc the current maintainer of this file,
153 Richard Heck <rgheck@comcast.net>.
159 \begin_inset Newline newline
163 \begin_inset Newline newline
169 \begin_layout Standard
170 \begin_inset CommandInset toc
171 LatexCommand tableofcontents
178 \begin_layout Standard
179 \begin_inset Note Note
182 \begin_layout Plain Layout
183 Please use change tracking when modifying this document.
184 This makes it easier for our translators to recognize things that have
185 been changed, and it helps the maintainer keep up-to-date with what's been
194 \begin_layout Chapter
198 \begin_layout Standard
199 This manual covers the customization features present in LyX.
200 In it, we discuss issues like keyboard shortcuts, screen previewing options,
201 printer options, sending commands to LyX via the LyX Server, internationalizati
202 on, installing new LaTeX classes and LyX layouts, etc.
203 We can't possibly hope to touch on everything you can change—our developers
204 add new features faster than we can document them—but we will explain the
205 most common customizations and hopefully point you in the right direction
206 for some of the more obscure ones.
209 \begin_layout Standard
210 \begin_inset Branch OutDated
213 \begin_layout Standard
214 Information from previous versions of this document that now seems to be
215 outdated is contained in the OutDated branch of this document.
216 By default, this information will not appear in the LaTeX output.
224 \begin_layout Chapter
225 LyX configuration files
228 \begin_layout Standard
229 This chapter aims to help you to find your way through the LyX configuration
231 Before continuing to read this chapter, you should find out where your
232 LyX library and user directories are by using
233 \begin_inset Flex CharStyle:MenuItem
236 \begin_layout Plain Layout
237 Help\SpecialChar \menuseparator
248 The library directory is the place where LyX places its system-wide configurati
249 on files; the user directory is where you can place your modified versions.
250 We will call the former
251 \begin_inset Flex CharStyle:Code
254 \begin_layout Plain Layout
261 \begin_inset Flex CharStyle:MenuItem
264 \begin_layout Plain Layout
270 in the remainder of this document.
274 \begin_layout Section
276 \begin_inset Flex CharStyle:Code
279 \begin_layout Plain Layout
288 \begin_layout Standard
289 \begin_inset Flex CharStyle:Code
292 \begin_layout Plain Layout
298 and its sub-directories contain a number of files and that can be used
299 to customize LyX's behavior.
300 You can change many of these files from within LyX itself through the
301 \begin_inset Flex CharStyle:MenuItem
304 \begin_layout Plain Layout
305 Tools\SpecialChar \menuseparator
312 Most customization that you will want to do in LyX is possible through
314 However, many other inner aspects of LyX can be customized by modifying
316 \begin_inset Flex CharStyle:Code
319 \begin_layout Plain Layout
326 These files fall in different categories, described in the following subsection
330 \begin_layout Subsection
331 Automatically generated files
334 \begin_layout Standard
335 The files, which are to be found in
336 \begin_inset Flex CharStyle:MenuItem
339 \begin_layout Plain Layout
345 , are generated when you configure LyX.
346 They contain various default values that are guessed by inspection.
347 In general, it is not a good idea to modify them, since they might be overwritt
351 \begin_layout Labeling
352 \labelwidthstring 00.00.0000
353 \begin_inset Flex CharStyle:Code
356 \begin_layout Plain Layout
362 contains defaults for various commands.
365 \begin_layout Labeling
366 \labelwidthstring 00.00.0000
367 \begin_inset Flex CharStyle:Code
370 \begin_layout Plain Layout
376 contains the list of packages that have been recognized by LyX.
377 It is currently unused by the LyX program itself, but the information extracted
378 , and more, is made available with
379 \begin_inset Flex CharStyle:MenuItem
382 \begin_layout Plain Layout
383 Help\SpecialChar \menuseparator
396 \begin_layout Labeling
397 \labelwidthstring 00.00.0000
398 \begin_inset Flex CharStyle:Code
401 \begin_layout Plain Layout
407 the list of text classes that have been found in your
408 \begin_inset Flex CharStyle:Code
411 \begin_layout Plain Layout
417 directories, along with the associated LaTeX document class and their descripti
421 \begin_layout Labeling
422 \labelwidthstring 00.00.0000
423 \begin_inset Flex CharStyle:Code
426 \begin_layout Plain Layout
432 the list of layout modules found in your
433 \begin_inset Flex CharStyle:Code
436 \begin_layout Plain Layout
445 \begin_layout Labeling
446 \labelwidthstring 00.00.0000
447 \begin_inset Flex CharStyle:Code
450 \begin_layout Plain Layout
456 lists of various sorts of LaTeX-related files found on your system
459 \begin_layout Labeling
460 \labelwidthstring 00.00.0000
461 \begin_inset Flex CharStyle:Code
464 \begin_layout Plain Layout
470 is automatically generated during configuration from the file
471 \begin_inset Flex CharStyle:Code
474 \begin_layout Plain Layout
481 It contains information on your LaTeX configuration.
484 \begin_layout Subsection
488 \begin_layout Standard
489 These directories are duplicated between
490 \begin_inset Flex CharStyle:Code
493 \begin_layout Plain Layout
500 \begin_inset Flex CharStyle:Code
503 \begin_layout Plain Layout
510 If a particular files exists in both places, the one in
511 \begin_inset Flex CharStyle:Code
514 \begin_layout Plain Layout
523 \begin_layout Labeling
524 \labelwidthstring 00.00.0000
525 \begin_inset Flex CharStyle:Code
528 \begin_layout Plain Layout
534 this directory contains files with the extension
535 \begin_inset Flex CharStyle:Code
538 \begin_layout Plain Layout
544 that define the keybindings used in LyX.
545 If there exists an internationalized version of the bind file named
546 \begin_inset Flex CharStyle:Code
549 \begin_layout Plain Layout
555 , that will be used first.
558 \begin_layout Labeling
559 \labelwidthstring 00.00.0000
560 \begin_inset Flex CharStyle:Code
563 \begin_layout Plain Layout
569 contains graphics files that can be included in documents.
573 \begin_layout Labeling
574 \labelwidthstring 00.00.0000
575 \begin_inset Flex CharStyle:Code
578 \begin_layout Plain Layout
584 contains LyX documentation files (including the one you are currently reading).
586 \begin_inset Flex CharStyle:Code
589 \begin_layout Plain Layout
595 deserves special attention, as noted above.
596 The internationalized help docs are in subdirectories
597 \begin_inset Flex CharStyle:Code
600 \begin_layout Plain Layout
607 \begin_inset Quotes eld
611 \begin_inset Quotes erd
614 is the ISO language code.
620 \begin_inset CommandInset ref
622 reference "cha:Internationalizing-LyX"
629 \begin_layout Labeling
630 \labelwidthstring 00.00.0000
631 \begin_inset Flex CharStyle:Code
634 \begin_layout Plain Layout
640 contains example files that explain how to use some features.
641 In the file browser, press the
642 \begin_inset Flex CharStyle:MenuItem
645 \begin_layout Plain Layout
654 \begin_layout Labeling
655 \labelwidthstring 00.00.0000
656 \begin_inset Flex CharStyle:Code
659 \begin_layout Plain Layout
665 contains image files that are used by the
666 \begin_inset Flex CharStyle:MenuItem
669 \begin_layout Plain Layout
676 In addition, it also contains the individual icons used in the toolbar
677 and the banners that can be shown when LyX is launched.
680 \begin_layout Labeling
681 \labelwidthstring 00.00.0000
682 \begin_inset Flex CharStyle:Code
685 \begin_layout Plain Layout
691 contains keyboard keymapping files.
697 \begin_inset CommandInset ref
699 reference "sec:International-Keymap-Stuff"
706 \begin_layout Labeling
707 \labelwidthstring 00.00.0000
708 \begin_inset Flex CharStyle:Code
711 \begin_layout Plain Layout
717 contains the text class and module files described in Chapter
722 \begin_inset CommandInset ref
724 reference "cha:Installing-New-Document"
731 \begin_layout Labeling
732 \labelwidthstring 00.00.0000
733 \begin_inset Flex CharStyle:Code
736 \begin_layout Plain Layout
743 \begin_inset Flex CharStyle:Code
746 \begin_layout Plain Layout
752 Python scripts used to convert between LyX versions.
753 These can be run from the command line if, say, you want to batch-convert
757 \begin_layout Labeling
758 \labelwidthstring 00.00.0000
759 \begin_inset Flex CharStyle:Code
762 \begin_layout Plain Layout
768 contains some files that demonstrate the capabilities of the
769 \begin_inset Flex CharStyle:MenuItem
772 \begin_layout Plain Layout
783 Also contains some scripts used by LyX itself.
786 \begin_layout Labeling
787 \labelwidthstring 00.00.0000
788 \begin_inset Flex CharStyle:Code
791 \begin_layout Plain Layout
797 contains the standard LyX template files described in Chapter
802 \begin_inset CommandInset ref
804 reference "sec:Creating-Templates"
811 \begin_layout Labeling
812 \labelwidthstring 00.00.0000
813 \begin_inset Flex CharStyle:Code
816 \begin_layout Plain Layout
822 contains files with the extension
823 \begin_inset Flex CharStyle:Code
826 \begin_layout Plain Layout
832 that define the user interface to LyX.
833 That is, the files define which items appear in which menus and the items
834 appearing on the toolbar.
837 \begin_layout Subsection
838 Files you don't want to modify
841 \begin_layout Standard
842 These files are used internally by LyX and you generally do not need to
843 modify them unless you are a developer.
846 \begin_layout Labeling
847 \labelwidthstring 00.00.0000
848 \begin_inset Flex CharStyle:Code
851 \begin_layout Plain Layout
857 this file contains the list of LyX developers.
858 The contents are displayed with the menu entry
859 \begin_inset Flex CharStyle:MenuItem
862 \begin_layout Plain Layout
863 Help\SpecialChar \menuseparator
876 \begin_layout Labeling
877 \labelwidthstring 00.00.0000
878 \begin_inset Flex CharStyle:Code
881 \begin_layout Plain Layout
887 this is a LaTeX script used during the configuration process.
891 \begin_layout Labeling
892 \labelwidthstring 00.00.0000
893 \begin_inset Flex CharStyle:Code
896 \begin_layout Plain Layout
902 this is the script that is used to re-configure LyX.
903 It creates configuration files in the directory it was run from.
906 \begin_layout Subsection
907 Other files needing a line or two...
910 \begin_layout Labeling
911 \labelwidthstring 00.00.0000
912 \begin_inset Flex CharStyle:Code
915 \begin_layout Plain Layout
921 this contains tables describing how different character encodings can be
925 \begin_layout Labeling
926 \labelwidthstring 00.00.0000
927 \begin_inset Flex CharStyle:Code
930 \begin_layout Plain Layout
936 this file contains the templates available to the new
937 \begin_inset Flex CharStyle:MenuItem
940 \begin_layout Plain Layout
953 \begin_layout Labeling
954 \labelwidthstring 00.00.0000
955 \begin_inset Flex CharStyle:Code
958 \begin_layout Plain Layout
964 this file contains a list of all the languages currently supported by LyX.
967 \begin_layout Section
968 Your local configuration directory
971 \begin_layout Standard
972 Even if you are using LyX as an unprivileged user, you might want to change
973 LyX configuration for your own use.
975 \begin_inset Flex CharStyle:Code
978 \begin_layout Plain Layout
984 directory contains all your personal configuration files.
985 This is the directory described as
986 \begin_inset Quotes eld
990 \begin_inset Quotes erd
994 \begin_inset Flex CharStyle:MenuItem
997 \begin_layout Plain Layout
998 Help\SpecialChar \menuseparator
1000 \begin_inset space ~
1009 This directory is used as a mirror of
1010 \begin_inset Flex CharStyle:Code
1013 \begin_layout Plain Layout
1019 , which means that every file in
1020 \begin_inset Flex CharStyle:Code
1023 \begin_layout Plain Layout
1029 is a replacement for the corresponding file in
1030 \begin_inset Flex CharStyle:Code
1033 \begin_layout Plain Layout
1040 Any configuration file described in the above sections can be placed either
1041 in the system-wide directory, in which case it will affect all users, or
1042 in your local directory for your own use.
1045 \begin_layout Standard
1046 To make things clearer, let's provide a few examples:
1049 \begin_layout Itemize
1050 The preferences set in the
1051 \begin_inset Flex CharStyle:MenuItem
1054 \begin_layout Plain Layout
1055 Tools\SpecialChar \menuseparator
1061 dialog are saved to a file
1062 \begin_inset Flex CharStyle:Code
1065 \begin_layout Plain Layout
1072 \begin_inset Flex CharStyle:Code
1075 \begin_layout Plain Layout
1084 \begin_layout Itemize
1085 When you reconfigure using
1086 \begin_inset Flex CharStyle:MenuItem
1089 \begin_layout Plain Layout
1090 Tools\SpecialChar \menuseparator
1097 \begin_inset Flex CharStyle:Code
1100 \begin_layout Plain Layout
1106 script, and the resulting files are written in your local configuration
1108 This means that any additional text class file that you might have added
1110 \begin_inset Flex CharStyle:Code
1113 \begin_layout Plain Layout
1119 will be added to the list of classes in the
1120 \begin_inset Flex CharStyle:MenuItem
1123 \begin_layout Plain Layout
1124 Document\SpecialChar \menuseparator
1133 \begin_layout Itemize
1134 If you get some updated documentation from LyX ftp site and cannot install
1135 it because you do not have sysadmin rights on your system, you can just
1137 \begin_inset Flex CharStyle:Code
1140 \begin_layout Plain Layout
1146 and the items in the
1147 \begin_inset Flex CharStyle:MenuItem
1150 \begin_layout Plain Layout
1156 menu will open them!
1159 \begin_layout Section
1160 Running LyX with multiple configurations
1163 \begin_layout Standard
1164 The configuration freedom of the local configuration directory may not suffice
1165 if you want to have more than one configuration at your disposal.
1166 For example, you may want to be use different key bindings or printer settings
1168 You can achieve this by having several such directories.
1169 You then specify which directory to use at run-time.
1172 \begin_layout Standard
1173 Invoking LyX with the command line switch
1174 \begin_inset Flex CharStyle:Code
1177 \begin_layout Plain Layout
1187 instructs the program to read the configuration from that directory, and
1188 not from the default directory.
1189 (You can determine the default directory by running LyX without the
1190 \begin_inset Flex CharStyle:Code
1193 \begin_layout Plain Layout
1199 switch.) If the specified directory does not exist, LyX offers to create
1200 it for you, just like it does for the default directory on the first time
1201 you run the program.
1202 You can modify the configuration options in this additional user directory
1203 exactly as you would for the default directory.
1204 These directories are completely independent (but read on).
1205 Note that setting the environment variable
1206 \begin_inset Flex CharStyle:Code
1209 \begin_layout Plain Layout
1215 to some value has exactly the same effect.
1218 \begin_layout Standard
1219 Having several configurations also requires more maintenance: if you want
1220 to add a new layout to
1221 \begin_inset Flex CharStyle:Code
1224 \begin_layout Plain Layout
1230 which you want available from all your configurations, you must add it
1231 to each directory separately.
1232 You can avoid this with the following trick: after LyX creates the additional
1233 directory, most of the subdirectories (see above) are empty.
1234 If you want the new configuration to mirror an existing one, replace the
1235 empty subdirectory with a symbolic link to the matching subdirectory in
1236 the existing configuration.
1238 \begin_inset Flex CharStyle:Code
1241 \begin_layout Plain Layout
1247 subdirectory, however, since it contains a file written by the configuration
1248 script (also accessible through
1249 \begin_inset Flex CharStyle:MenuItem
1252 \begin_layout Plain Layout
1253 Tools\SpecialChar \menuseparator
1259 ) which is configuration-specific.
1262 \begin_layout Chapter
1263 The Preferences dialog
1266 \begin_layout Standard
1267 All options of the preferences dialog are described in the Appendix
1269 The Preferences Dialog
1276 For some options you might find here more details.
1279 \begin_layout Section
1281 \begin_inset CommandInset label
1290 \begin_layout Standard
1291 The first step is to define your file formats if they are not already defined.
1293 \begin_inset Flex CharStyle:MenuItem
1296 \begin_layout Plain Layout
1297 Tools\SpecialChar \menuseparator
1305 \begin_inset Flex CharStyle:MenuItem
1308 \begin_layout Plain Layout
1309 File Handling\SpecialChar \menuseparator
1316 \begin_inset Flex CharStyle:MenuItem
1319 \begin_layout Plain Layout
1320 New\SpecialChar \ldots{}
1326 button to define your new format.
1328 \begin_inset Flex CharStyle:MenuItem
1331 \begin_layout Plain Layout
1337 field contains the name used to identify the format in the GUI.
1339 \begin_inset Flex CharStyle:MenuItem
1342 \begin_layout Plain Layout
1348 is used to identify the format internally.
1349 You will also need to enter a file extension.
1350 These are all required.
1352 \begin_inset Flex CharStyle:MenuItem
1355 \begin_layout Plain Layout
1361 field is used to provide a keyboard shortcut on the menus.
1362 (For example, pressing
1363 \begin_inset Flex CharStyle:MenuItem
1366 \begin_layout Plain Layout
1373 \begin_inset Flex CharStyle:MenuItem
1376 \begin_layout Plain Layout
1377 View\SpecialChar \menuseparator
1386 \begin_layout Standard
1388 \begin_inset Flex CharStyle:MenuItem
1391 \begin_layout Plain Layout
1398 \begin_inset Flex CharStyle:MenuItem
1401 \begin_layout Plain Layout
1408 For example, you might want to use
1409 \begin_inset Flex CharStyle:MenuItem
1412 \begin_layout Plain Layout
1418 to view PostScript files.
1419 You can enter the command needed to start the program in the corresponding
1421 In defining this command, you can use the four variables listed in the
1423 The viewer is launched when you view an image in LyX or use the
1424 \begin_inset Flex CharStyle:MenuItem
1427 \begin_layout Plain Layout
1434 The editor is for example launched when you right-click on an image and
1436 \begin_inset Flex CharStyle:MenuItem
1439 \begin_layout Plain Layout
1445 in the appearing context menu.
1448 \begin_layout Standard
1450 \begin_inset Flex CharStyle:MenuItem
1453 \begin_layout Plain Layout
1459 option tells LyX that a format is suitable for document export.
1460 If this is set and if a suitable conversion route exists (see sec.
1461 \begin_inset space \thinspace{}
1465 \begin_inset CommandInset ref
1467 reference "sec:Converters"
1471 ), the format will appear in the
1472 \begin_inset Flex CharStyle:MenuItem
1475 \begin_layout Plain Layout
1476 File\SpecialChar \menuseparator
1483 The format will also appear in the
1484 \begin_inset Flex CharStyle:MenuItem
1487 \begin_layout Plain Layout
1493 menu if a viewer is specified for the format.
1494 Pure image formats, such as
1495 \begin_inset Flex CharStyle:Code
1498 \begin_layout Plain Layout
1504 , should not use this option.
1505 Formats that can both represent vector graphics and documents like
1506 \begin_inset Flex CharStyle:Code
1509 \begin_layout Plain Layout
1518 \begin_layout Standard
1520 \begin_inset Flex CharStyle:MenuItem
1523 \begin_layout Plain Layout
1524 Vector graphics format
1529 tells LyX that a format can contain vector graphics.
1530 This information is used to determine the target format of included graphics
1532 \begin_inset Flex CharStyle:MenuItem
1535 \begin_layout Plain Layout
1542 Included graphics may need to be converted to either
1543 \begin_inset Flex CharStyle:MenuItem
1546 \begin_layout Plain Layout
1553 \begin_inset Flex CharStyle:MenuItem
1556 \begin_layout Plain Layout
1563 \begin_inset Flex CharStyle:MenuItem
1566 \begin_layout Plain Layout
1573 \begin_inset Flex CharStyle:MenuItem
1576 \begin_layout Plain Layout
1582 cannot handle other image formats.
1583 If an included graphic is not already in
1584 \begin_inset Flex CharStyle:MenuItem
1587 \begin_layout Plain Layout
1594 \begin_inset Flex CharStyle:MenuItem
1597 \begin_layout Plain Layout
1604 \begin_inset Flex CharStyle:MenuItem
1607 \begin_layout Plain Layout
1613 format, it is converted to
1614 \begin_inset Flex CharStyle:MenuItem
1617 \begin_layout Plain Layout
1623 if the vector format option is set, and otherwise to
1624 \begin_inset Flex CharStyle:MenuItem
1627 \begin_layout Plain Layout
1636 \begin_layout Section
1640 \begin_layout Standard
1641 Since all conversions from one format to another take place in LyX's temporary
1642 directory, it is sometimes necessary to modify a file before copying it
1643 to the temporary directory in order that the conversion may be performed.
1647 \begin_layout Plain Layout
1648 For example, the file may refer to other files—images, for example—using
1649 relative file names, and these may become invalid when the file is copied
1650 to the temporary directory.
1655 This is done by a Copier: It copies a file to (or from) the temporary directory
1656 and may modify it in the process.
1659 \begin_layout Standard
1660 The definitions of the copiers may use four variables:
1663 \begin_layout Labeling
1664 \labelwidthstring 00.00.0000
1665 \begin_inset Flex CharStyle:Code
1668 \begin_layout Plain Layout
1674 The LyX system directory (e.
1675 \begin_inset space \thinspace{}
1679 \begin_inset space \space{}
1683 \begin_inset Flex CharStyle:MenuItem
1686 \begin_layout Plain Layout
1695 \begin_layout Labeling
1696 \labelwidthstring 00.00.0000
1697 \begin_inset Flex CharStyle:Code
1700 \begin_layout Plain Layout
1709 \begin_layout Labeling
1710 \labelwidthstring 00.00.0000
1711 \begin_inset Flex CharStyle:Code
1714 \begin_layout Plain Layout
1723 \begin_layout Labeling
1724 \labelwidthstring 00.00.0000
1725 \begin_inset Flex CharStyle:Code
1728 \begin_layout Plain Layout
1737 \begin_layout Standard
1738 The latter should be the filename as it would be used in a LaTeX's
1745 It is relevant only when exporting files suitable for such inclusion.
1748 \begin_layout Standard
1749 Copiers can be used to do almost anything with output files.
1750 For example, suppose you want generated pdf files to be copied to a special
1752 \begin_inset Flex CharStyle:Code
1755 \begin_layout Plain Layout
1762 Then you could write a shell script such as this one:
1765 \begin_layout Standard
1766 \begin_inset listings
1770 \begin_layout Plain Layout
1775 \begin_layout Plain Layout
1780 \begin_layout Plain Layout
1782 TOFILE=`basename $2`
1785 \begin_layout Plain Layout
1787 cp $FROMFILE /home/you/pdf/$TOFILE
1792 Save it in your local LyX directory—say,
1793 \begin_inset Flex CharStyle:Code
1796 \begin_layout Plain Layout
1797 /home/you/.lyx/scripts/pdfcopier.sh
1802 —and make it executable, if you need to do so on your platform.
1804 \begin_inset Flex CharStyle:MenuItem
1807 \begin_layout Plain Layout
1808 Tools\SpecialChar \menuseparator
1814 dialog, select under
1815 \begin_inset Flex CharStyle:MenuItem
1818 \begin_layout Plain Layout
1819 File Handling\SpecialChar \menuseparator
1826 \begin_inset Flex CharStyle:MenuItem
1829 \begin_layout Plain Layout
1835 format—or one of the other pdf formats—and enter
1836 \begin_inset Flex CharStyle:Code
1839 \begin_layout Plain Layout
1840 pdfcopier.sh $$i $$o
1846 \begin_inset Flex CharStyle:MenuItem
1849 \begin_layout Plain Layout
1859 \begin_layout Standard
1860 Copiers are used by LyX in various of its own conversions.
1861 For example, if appropriate programs are found, LyX will automatically
1862 install copiers for the
1863 \begin_inset Flex CharStyle:MenuItem
1866 \begin_layout Plain Layout
1873 \begin_inset Flex CharStyle:MenuItem
1876 \begin_layout Plain Layout
1878 \begin_inset space ~
1887 When these formats are exported, the copier sees that not just the main
1888 HTML file but various associated files (style files, images, etc.) are also
1890 All these files are written to a subdirectory of the directory in which
1891 the original LyX file was found.
1895 \begin_layout Plain Layout
1896 This copier can be customized.
1898 \begin_inset Quotes eld
1902 \begin_inset Quotes erd
1905 argument takes a comma-separated list of extensions to be copied; if it
1906 is omitted, all files will be copied.
1908 \begin_inset Quotes eld
1912 \begin_inset Quotes erd
1915 argument determines the extension added to the generated directory.
1917 \begin_inset Quotes eld
1921 \begin_inset Flex CharStyle:MenuItem
1924 \begin_layout Plain Layout
1931 \begin_inset Quotes erd
1934 , so HTML generated from
1935 \begin_inset Flex CharStyle:MenuItem
1938 \begin_layout Plain Layout
1939 /path/to/filename.lyx
1945 \begin_inset Flex CharStyle:MenuItem
1948 \begin_layout Plain Layout
1949 /path/to/filename.html.LyXconv
1963 \begin_layout Section
1965 \begin_inset CommandInset label
1967 name "sec:Converters"
1974 \begin_layout Standard
1975 You can define your own Converters to convert files between different formats.
1977 \begin_inset Flex CharStyle:MenuItem
1980 \begin_layout Plain Layout
1981 Tools\SpecialChar \menuseparator
1982 Preferences\SpecialChar \menuseparator
1983 File Handling\SpecialChar \menuseparator
1992 \begin_layout Standard
1993 To define a new converter, select the
1994 \begin_inset Flex CharStyle:MenuItem
1997 \begin_layout Plain Layout
1999 \begin_inset space ~
2008 \begin_inset Flex CharStyle:MenuItem
2011 \begin_layout Plain Layout
2013 \begin_inset space ~
2021 from the drop-down lists, enter the command needed for the conversion,
2023 \begin_inset Flex CharStyle:MenuItem
2026 \begin_layout Plain Layout
2033 Several variables can be used in the definition of converters:
2036 \begin_layout Labeling
2037 \labelwidthstring 00.00.0000
2038 \begin_inset Flex CharStyle:Code
2041 \begin_layout Plain Layout
2047 The LyX system directory
2050 \begin_layout Labeling
2051 \labelwidthstring 00.00.0000
2052 \begin_inset Flex CharStyle:Code
2055 \begin_layout Plain Layout
2064 \begin_layout Labeling
2065 \labelwidthstring 00.00.0000
2066 \begin_inset Flex CharStyle:Code
2069 \begin_layout Plain Layout
2078 \begin_layout Labeling
2079 \labelwidthstring 00.00.0000
2080 \begin_inset Flex CharStyle:Code
2083 \begin_layout Plain Layout
2089 The base filename of the input file (i.
2090 \begin_inset space \thinspace{}
2093 g., without the extension)
2096 \begin_layout Labeling
2097 \labelwidthstring 00.00.0000
2098 \begin_inset Flex CharStyle:Code
2101 \begin_layout Plain Layout
2107 The path to the input file
2110 \begin_layout Labeling
2111 \labelwidthstring 00.00.0000
2112 \begin_inset Flex CharStyle:Code
2115 \begin_layout Plain Layout
2121 The path to the original input file (this is different from $$p when a
2122 chain of converters is called).
2125 \begin_layout Standard
2127 \begin_inset Flex CharStyle:MenuItem
2130 \begin_layout Plain Layout
2132 \begin_inset space ~
2140 field you can enter the following flags, separated by commas:
2143 \begin_layout Labeling
2144 \labelwidthstring 00.00.0000
2145 \begin_inset Flex CharStyle:Code
2148 \begin_layout Plain Layout
2154 This converter runs some form of LaTeX.
2155 This will make LyX's LaTeX error logs available.
2158 \begin_layout Labeling
2159 \labelwidthstring 00.00.0000
2160 \begin_inset Flex CharStyle:Code
2163 \begin_layout Plain Layout
2170 \begin_inset Flex CharStyle:MenuItem
2173 \begin_layout Plain Layout
2179 file for the conversion.
2182 \begin_layout Labeling
2183 \labelwidthstring 00.00.0000
2184 \begin_inset Flex CharStyle:Code
2187 \begin_layout Plain Layout
2196 \begin_layout Standard
2197 The following three flags are not really flags at all because they take
2199 \begin_inset Flex CharStyle:MenuItem
2202 \begin_layout Plain Layout
2204 \begin_inset space ~
2208 \begin_inset space ~
2219 \begin_layout Labeling
2220 \labelwidthstring 00.00.0000
2221 \begin_inset Flex CharStyle:Code
2224 \begin_layout Plain Layout
2230 If set, the converter's standard error will be redirected to a file
2231 \begin_inset Flex CharStyle:Code
2234 \begin_layout Plain Layout
2240 , and the script given as argument will be run as:
2241 \begin_inset Flex CharStyle:Code
2244 \begin_layout Plain Layout
2245 script < infile.out > infile.log
2251 The argument may contain
2252 \begin_inset Flex CharStyle:Code
2255 \begin_layout Plain Layout
2264 \begin_layout Labeling
2265 \labelwidthstring 00.00.0000
2266 \begin_inset Flex CharStyle:Code
2269 \begin_layout Plain Layout
2275 The name of the directory in which the converter will dump the generated
2277 LyX will not create this directory, and it does not copy anything into
2278 it, though it will copy this directory to the destination.
2279 The argument may contain
2280 \begin_inset Flex CharStyle:Code
2283 \begin_layout Plain Layout
2289 , which will be replaced by the base name of the input and output files,
2290 respectively, when the directory is copied.
2291 \begin_inset Newline newline
2294 Note that resultdir and usetempdir make no sense together.
2295 The latter will be ignored if the former is given.
2298 \begin_layout Labeling
2299 \labelwidthstring 00.00.0000
2300 \begin_inset Flex CharStyle:Code
2303 \begin_layout Plain Layout
2309 Determines the output file name and may, contain
2310 \begin_inset Flex CharStyle:Code
2313 \begin_layout Plain Layout
2320 Sensible only with resultdir and optional even then; if not given, it defaults
2324 \begin_layout Standard
2325 None of these last three are presently used in any of the converters that
2326 are installed with LyX.
2330 \begin_layout Standard
2331 You do not have to define converters for all formats between which you want
2333 For example, you will note that there is no `LyX to PostScript' converter,
2334 but LyX will export PostScript.
2335 It does so by first creating a LaTeX file (no converter needs to be defined
2336 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2337 and finally converting the resulting DVI file to PostScript.
2338 LyX finds such `chains' of converters automatically, and it will always
2339 choose the shortest possible chain.
2340 You can, though, still define multiple conversion methods between file
2342 For example, the standard LyX configuration provides three ways to convert
2343 LaTeX to PDF: Directly, using
2344 \begin_inset Flex CharStyle:MenuItem
2347 \begin_layout Plain Layout
2353 ; via (DVI and) PostScript, using
2354 \begin_inset Flex CharStyle:MenuItem
2357 \begin_layout Plain Layout
2364 \begin_inset Flex CharStyle:MenuItem
2367 \begin_layout Plain Layout
2374 To define such alternate chains, you must define multiple target `file
2375 formats', as described in section
2376 \begin_inset CommandInset ref
2378 reference "sec:Formats"
2383 For example, in the standard configuration, the formats named
2384 \begin_inset Flex CharStyle:MenuItem
2387 \begin_layout Plain Layout
2394 \begin_inset Flex CharStyle:MenuItem
2397 \begin_layout Plain Layout
2404 \begin_inset Flex CharStyle:MenuItem
2407 \begin_layout Plain Layout
2413 are defined, all of which share the extension
2414 \begin_inset Flex CharStyle:MenuItem
2417 \begin_layout Plain Layout
2423 , and which correspond to the conversion methods just mentioned.
2426 \begin_layout Chapter
2427 Internationalizing LyX
2428 \begin_inset CommandInset label
2430 name "cha:Internationalizing-LyX"
2437 \begin_layout Standard
2438 LyX supports using a translated interface.
2439 Last time we checked, LyX provided text in thirty languages.
2440 The language of choice is called your
2445 (For further reading on locale settings, see also the documentation for
2446 locale that comes with your operating system.
2447 For Linux, the manual page for
2448 \begin_inset Flex CharStyle:Code
2451 \begin_layout Plain Layout
2457 could be a good place to start).
2460 \begin_layout Standard
2461 Notice that these translations will work, but do contain a few flaws.
2462 In particular, all dialogs have been designed with the English text in
2463 mind, which means that some of the translated text will be too large to
2464 fit within the space allocated.
2465 This is only a display problem and will not cause any harm.
2466 Also, you will find that some of the translations do not define shortcut
2467 keys for everything.
2468 Sometimes, there are simply not enough free letters to do it.
2469 Other times, the translator just hasn't got around to doing it yet.
2470 Our localization team, which you may wish to join,
2474 \begin_layout Plain Layout
2475 If you are a fluent speaker of a language other than English, joining these
2476 teams is a great way to give back to the LyX community!
2481 will of course try to fix these shortcomings in future versions of LyX.
2484 \begin_layout Section
2488 \begin_layout Subsection
2489 Translating the graphical user interface (text messages).
2492 \begin_layout Standard
2494 \begin_inset Flex CharStyle:Code
2497 \begin_layout Plain Layout
2503 library to handle the internationalization of the interface.
2504 To have LyX speak your favorite language in all menus and dialogs, you
2506 \begin_inset Flex CharStyle:Code
2509 \begin_layout Plain Layout
2515 -file for that language.
2516 When this is available, you'll have to generate a
2517 \begin_inset Flex CharStyle:Code
2520 \begin_layout Plain Layout
2526 -file from it and install the
2527 \begin_inset Flex CharStyle:Code
2530 \begin_layout Plain Layout
2537 The process of doing all of this is explained in the documentation for
2539 \begin_inset Flex CharStyle:Code
2542 \begin_layout Plain Layout
2549 It is possible to do this just for yourself, but if you're going to do
2550 it, you might as well share the results of your labors with the rest of
2552 Send a message to the LyX developers' list for more information about how
2556 \begin_layout Standard
2557 In short, this is what you should do (xx denotes the language code):
2560 \begin_layout Itemize
2561 Check out the LyX source code.
2563 \begin_inset CommandInset href
2565 name "information on the web"
2566 target "http://www.lyx.org/devel/cvs.php"
2573 \begin_layout Itemize
2575 \begin_inset Flex CharStyle:Code
2578 \begin_layout Plain Layout
2584 to the folder of the
2585 \begin_inset Flex CharStyle:Code
2588 \begin_layout Plain Layout
2596 \begin_inset Flex CharStyle:Code
2599 \begin_layout Plain Layout
2607 \begin_inset Flex CharStyle:Code
2610 \begin_layout Plain Layout
2616 doesn't exist anywhere, it can be remade with the console command
2617 \begin_inset Flex CharStyle:Code
2620 \begin_layout Plain Layout
2626 in that directory, or you can use an existing po-file for some other language
2630 \begin_layout Itemize
2632 \begin_inset Flex CharStyle:Code
2635 \begin_layout Plain Layout
2645 \begin_layout Plain Layout
2646 This is just a text file, so it can be edited in any text editor.
2647 But there are also specialized programs that support such editing, such
2652 (for all platforms) or
2661 contains a `mode' for editing
2662 \begin_inset Flex CharStyle:Code
2665 \begin_layout Plain Layout
2676 For some menu- and widget-labels, there are also shortcut keys that should
2678 Those keys are marked after a `|', and should be translated according to
2679 the words and phrases of the language.
2680 You should also fill also out the information at the beginning of the new
2682 \begin_inset Flex CharStyle:Code
2685 \begin_layout Plain Layout
2691 -file with your email-address, etc., so people know where to reach you with
2692 suggestions and entertaining flames.
2695 \begin_layout Standard
2696 If you are just doing this on your own, then:
2699 \begin_layout Itemize
2701 \begin_inset Flex CharStyle:Code
2704 \begin_layout Plain Layout
2711 This can be done with
2712 \begin_inset Flex CharStyle:Code
2715 \begin_layout Plain Layout
2716 msgfmt -o xx.mo < xx.po
2724 \begin_layout Itemize
2726 \begin_inset Flex CharStyle:Code
2729 \begin_layout Plain Layout
2735 -file to your locale-tree, at the correct directory for application messages
2740 xx, and under the name
2741 \begin_inset Flex CharStyle:Code
2744 \begin_layout Plain Layout
2751 \begin_inset space \thinspace{}
2755 \begin_inset space \space{}
2759 \begin_inset Flex CharStyle:Code
2762 \begin_layout Plain Layout
2763 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2773 \begin_layout Standard
2774 As said, however, it would be best if the new
2775 \begin_inset Flex CharStyle:Code
2778 \begin_layout Plain Layout
2784 -file could be added to the LyX distribution, so others can use it.
2785 Adding it involves making additional changes to LyX.
2786 So send an email to the developers' mailing list if you're interested in
2790 \begin_layout Subsubsection
2794 \begin_layout Standard
2795 Sometimes it turns out that one English message needs to be translated into
2796 different messages in the target language.
2797 One example is the message
2798 \begin_inset Flex CharStyle:Code
2801 \begin_layout Plain Layout
2807 which has the German translation
2815 , depending upon exactly what the English
2816 \begin_inset Quotes eld
2820 \begin_inset Quotes erd
2825 \begin_inset Flex CharStyle:Code
2828 \begin_layout Plain Layout
2834 does not handle such ambiguous translations.
2835 Therefore you have to add some context information to the message: Instead
2837 \begin_inset Flex CharStyle:Code
2840 \begin_layout Plain Layout
2847 \begin_inset Flex CharStyle:Code
2850 \begin_layout Plain Layout
2851 To[[as in 'From format x to format y']]
2857 \begin_inset Flex CharStyle:Code
2860 \begin_layout Plain Layout
2861 To[[as in 'From page x to page y']].
2866 Now the two occurrences of
2867 \begin_inset Flex CharStyle:Code
2870 \begin_layout Plain Layout
2877 \begin_inset Flex CharStyle:Code
2880 \begin_layout Plain Layout
2886 and can be translated correctly to
2897 \begin_layout Standard
2898 Of course the context information needs to be stripped off the original
2899 message when no translation is used.
2900 Therefore you have to put it in double square brackets at the end of the
2901 message (see the example above).
2902 The translation mechanism of LyX ensures that everything in double square
2903 brackets at the end of messages is removed before displaying the message.
2906 \begin_layout Subsection
2907 Translating the documentation.
2910 \begin_layout Standard
2911 The online documentation (in the
2912 \begin_inset Flex CharStyle:MenuItem
2915 \begin_layout Plain Layout
2921 -menu) can (and should!) be translated.
2922 If there are translated versions of the documentation available
2926 \begin_layout Plain Layout
2927 As of March 2008, at least some of the documents have been translated into
2928 fourteen languages, with the Tutorial available in a few more.
2933 and the locale is set accordingly, these will be used automagically by
2935 LyX looks for translated versions as
2936 \begin_inset Flex CharStyle:Code
2939 \begin_layout Plain Layout
2940 LyXDir/doc/xx/DocName.lyx
2946 \begin_inset Flex CharStyle:Code
2949 \begin_layout Plain Layout
2955 is the code for the language currently in use.
2956 If there are no translated documents, the default English versions will
2958 Note that the translated versions must have the same filenames (
2959 \begin_inset Flex CharStyle:Code
2962 \begin_layout Plain Layout
2968 above) as the original.
2969 If you feel up to translating the documentation (an excellent way to proof-read
2970 the original documentation by the way!), there are a few things you should
2974 \begin_layout Itemize
2975 Check out the documentation translation web page at
2976 \begin_inset CommandInset href
2978 name "http://www.lyx.org/Translation"
2979 target "http://www.lyx.org/Translation"
2984 That way, you can find out which (if any) documents have already been translate
2985 d into your language.
2986 You can also find out who (if anyone) is organizing the effort to translate
2987 the documentation into your language.
2988 If no one is organizing the effort, please let us know that you're interested.
2991 \begin_layout Standard
2992 Once you get to actually translating, here's a few hints for you that may
2996 \begin_layout Itemize
2997 Join the documentation team! There is information on how to do that in
2998 \begin_inset Flex CharStyle:Code
3001 \begin_layout Plain Layout
3008 \begin_inset Flex CharStyle:MenuItem
3011 \begin_layout Plain Layout
3012 Help\SpecialChar \menuseparator
3018 ), which by the way is the first document you should translate.
3021 \begin_layout Itemize
3022 Learn the typographic conventions for the language you are translating to.
3023 Typography is an ancient art and over the centuries, a great variety of
3024 conventions have developed throughout different parts of the world.
3025 Also study the professional terminology amongst typographers in your country.
3026 Inventing your own terminology will only confuse the users.
3029 (Warning! Typography is addictive!)
3032 \begin_layout Itemize
3033 Make a copy of the document.
3034 This will be your working copy.
3035 You can use this as your personal translated help-file by placing it in
3037 \begin_inset Flex CharStyle:Code
3040 \begin_layout Plain Layout
3049 \begin_layout Itemize
3050 Sometimes the original document (from the LyX-team) will be updated.
3051 Use the source viewer at
3052 \begin_inset CommandInset href
3054 name "http://www.lyx.org/trac/timeline"
3055 target "http://www.lyx.org/trac/timeline"
3059 to see what has been changed.
3060 That way you can easily see which parts of the translated document need
3064 \begin_layout Standard
3065 If you ever find an error in the original document, fix it and notify the
3066 rest of the documentation team of the changes! (You didn't forget to join
3067 the documentation team, did you?)
3070 \begin_layout Standard
3071 \begin_inset Branch OutDated
3074 \begin_layout Section
3075 International Keyboard Support
3078 \begin_layout Standard
3081 [Editor's Note: The following section is by
3089 It needs to be fixed to conform to the new Documentation Style sheet and
3090 to make use of the new v1.0 features.
3091 The whole thing also needs to be merged with the section following it.-jw
3092 It may also be badly out of date.-rh (2008)]
3095 \begin_layout Subsection
3096 Defining Own Keymaps: Keymap File Format
3099 \begin_layout Standard
3100 Let's look at a keyboard definition file a little closer.
3101 It is a plain text file defining
3104 \begin_layout Itemize
3105 key-to-key or key-to-string translations
3108 \begin_layout Itemize
3112 \begin_layout Itemize
3113 dead keys exceptions
3116 \begin_layout Standard
3117 To define key-to-key or key-to-string translation, use this command:
3120 \begin_layout Quotation
3121 \begin_inset Flex CharStyle:Code
3124 \begin_layout Plain Layout
3133 \begin_inset Flex CharStyle:Code
3136 \begin_layout Plain Layout
3145 \begin_layout Standard
3147 \begin_inset Flex CharStyle:Code
3150 \begin_layout Plain Layout
3156 is the key to be translated and
3157 \begin_inset Flex CharStyle:Code
3160 \begin_layout Plain Layout
3166 is the string to be inserted into the document.
3167 To define dead keys, use:
3170 \begin_layout Quotation
3171 \begin_inset Flex CharStyle:Code
3174 \begin_layout Plain Layout
3183 \begin_inset Flex CharStyle:Code
3186 \begin_layout Plain Layout
3195 \begin_layout Standard
3197 \begin_inset Flex CharStyle:Code
3200 \begin_layout Plain Layout
3206 is a keyboard key and
3207 \begin_inset Flex CharStyle:Code
3210 \begin_layout Plain Layout
3217 The following dead keys are supported (shortcut name is in parentheses):
3220 \begin_layout Quotation
3224 \begin_inset space \hfill{}
3230 \begin_layout Quotation
3232 \begin_inset space \hfill{}
3238 \begin_layout Quotation
3240 \begin_inset space \hfill{}
3246 \begin_layout Quotation
3248 \begin_inset space \hfill{}
3254 \begin_layout Quotation
3256 \begin_inset space \hfill{}
3262 \begin_layout Quotation
3264 \begin_inset space \hfill{}
3271 \begin_layout Plain Layout
3283 \begin_layout Quotation
3285 \begin_inset space \hfill{}
3291 \begin_layout Quotation
3293 \begin_inset space \hfill{}
3300 \begin_layout Plain Layout
3312 \begin_layout Quotation
3314 \begin_inset space \hfill{}
3320 \begin_layout Quotation
3322 \begin_inset space \hfill{}
3328 \begin_layout Quotation
3330 \begin_inset space \hfill{}
3337 \begin_layout Plain Layout
3349 \begin_layout Quotation
3351 \begin_inset space \hfill{}
3358 \begin_layout Plain Layout
3370 \begin_layout Quotation
3372 \begin_inset space \hfill{}
3378 \begin_layout Quotation
3379 hungarian umlaut (hug)
3380 \begin_inset space \hfill{}
3386 \begin_layout Quotation
3388 \begin_inset space \hfill{}
3394 \begin_layout Quotation
3396 \begin_inset space \hfill{}
3403 \begin_layout Plain Layout
3415 \begin_layout Standard
3416 Since in many international keyboards there are exceptions to what some
3417 dead keys should do, you can define them using
3420 \begin_layout Quotation
3421 \begin_inset Flex CharStyle:Code
3424 \begin_layout Plain Layout
3432 deadkey key outstring
3435 \begin_layout Standard
3436 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3440 \begin_layout Quotation
3441 \begin_inset Flex CharStyle:Code
3444 \begin_layout Plain Layout
3457 \begin_layout Standard
3458 to make it work correctly.
3459 Also, you have to define as exceptions dead keys over i and j, to remove
3460 the dot from them before inserting an accent mark.
3461 I will change this when the time comes, but so far I haven't had time.
3464 \begin_layout Standard
3465 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3468 \begin_inset Flex CharStyle:Code
3471 \begin_layout Plain Layout
3477 have different meaning.
3479 \begin_inset Flex CharStyle:Code
3482 \begin_layout Plain Layout
3488 marks comments, quotes start and end LaTeX-style commands.
3489 To enter quote, you'll need to use
3490 \begin_inset Flex CharStyle:Code
3493 \begin_layout Plain Layout
3502 \begin_inset Flex CharStyle:Code
3505 \begin_layout Plain Layout
3512 \begin_inset Flex CharStyle:Code
3515 \begin_layout Plain Layout
3526 \begin_layout Standard
3527 If you make a keyboard description file that works for your language, please
3528 mail it to me, so I can include it in the next keymap distribution.
3531 \begin_layout Standard
3532 More keywords will be supported in keymap configuration file in future,
3536 \begin_layout Itemize
3537 \begin_inset Flex CharStyle:Code
3540 \begin_layout Plain Layout
3551 \begin_inset space \hfill{}
3555 \begin_inset Flex CharStyle:Code
3558 \begin_layout Plain Layout
3567 \begin_layout Itemize
3568 \begin_inset Flex CharStyle:Code
3571 \begin_layout Plain Layout
3582 \begin_inset space \hfill{}
3586 \begin_inset Flex CharStyle:Code
3589 \begin_layout Plain Layout
3595 an external keymap translation program
3598 \begin_layout Standard
3599 Also, it should look into
3600 \begin_inset Flex CharStyle:Code
3603 \begin_layout Plain Layout
3609 file for defaults, too (for example, a
3610 \begin_inset Flex CharStyle:Code
3613 \begin_layout Plain Layout
3621 option to include default keyboard).
3629 \begin_layout Section
3630 International Keymap Stuff
3631 \begin_inset CommandInset label
3633 name "sec:International-Keymap-Stuff"
3640 \begin_layout Standard
3641 \begin_inset Note Note
3644 \begin_layout Plain Layout
3645 In doing the revisions on this document in March 2008, I did not look over
3646 this stuff, as I do not understand it.
3647 It would be good if someone else could do so.
3656 \begin_layout Standard
3657 The next two sections describe the
3658 \begin_inset Flex CharStyle:Code
3661 \begin_layout Plain Layout
3670 \begin_inset Flex CharStyle:Code
3673 \begin_layout Plain Layout
3681 file syntax in detail.
3682 These sections should help you design your own key map if the ones provided
3683 do not meet your needs.
3686 \begin_layout Subsection
3690 \begin_layout Standard
3694 \begin_inset Flex CharStyle:Code
3697 \begin_layout Plain Layout
3703 file maps keystrokes to characters or strings.
3704 As the name suggests, it sets a keyboard mapping.
3706 \begin_inset Flex CharStyle:Code
3709 \begin_layout Plain Layout
3720 \begin_inset Flex CharStyle:Code
3723 \begin_layout Plain Layout
3738 \begin_inset Flex CharStyle:Code
3741 \begin_layout Plain Layout
3754 \begin_inset Flex CharStyle:Code
3757 \begin_layout Plain Layout
3766 \begin_inset Flex CharStyle:Code
3769 \begin_layout Plain Layout
3777 are described in this section.
3780 \begin_layout Labeling
3781 \labelwidthstring 00.00.0000
3782 \begin_inset Flex CharStyle:Code
3785 \begin_layout Plain Layout
3793 Map a character to a string
3796 \begin_layout LyX-Code
3811 \begin_layout Standard
3844 the double-quote (")
3861 must be escaped with a preceding backslash (
3872 \begin_layout Standard
3874 \begin_inset Flex CharStyle:MenuItem
3877 \begin_layout Plain Layout
3885 statement to cause the symbol
3886 \begin_inset Flex CharStyle:MenuItem
3889 \begin_layout Plain Layout
3897 to be output for the keystroke
3898 \begin_inset Flex CharStyle:MenuItem
3901 \begin_layout Plain Layout
3912 \begin_layout LyX-Code
3918 \begin_layout Labeling
3919 \labelwidthstring 00.00.0000
3920 \begin_inset Flex CharStyle:Code
3923 \begin_layout Plain Layout
3931 Specify an accent character
3934 \begin_layout LyX-Code
3943 \begin_layout Standard
3944 This will make the cha
3982 This is the dead key
3986 \begin_layout Plain Layout
3993 refers to a key that does not produce a character by itself, but when followed
3994 with another key, produces the desired accent character.
3995 For example, a German characte
3997 r with an umlaut like
4007 can be produced in this manner.
4016 \begin_layout Standard
4029 and then another key not in
4046 followed by the other, not allowed key, as output.
4050 \begin_inset Flex CharStyle:MenuItem
4053 \begin_layout Plain Layout
4061 cancels a dead key, so if
4072 \begin_inset Flex CharStyle:MenuItem
4075 \begin_layout Plain Layout
4084 , the cursor will not go one position backwards but will instead cancel
4100 might have had on the next keystroke.
4104 \begin_layout Standard
4105 The following example specifies that the character ' is to be an acute accent,
4106 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4109 \begin_layout LyX-Code
4112 kmod ' acute aeiouAEIOU
4115 \begin_layout Labeling
4116 \labelwidthstring 00.00.0000
4117 \begin_inset Flex CharStyle:Code
4120 \begin_layout Plain Layout
4126 Specify an exception to the accent character
4129 \begin_layout LyX-Code
4138 \begin_layout Standard
4139 This defines an exce
4180 have been assigned a keystroke with a previous
4183 \begin_inset Flex CharStyle:Code
4186 \begin_layout Plain Layout
4210 must not belong in the
4257 If such a declaration does not exist in
4265 \begin_inset Flex CharStyle:Code
4268 \begin_layout Plain Layout
4302 \begin_inset Flex CharStyle:Code
4305 \begin_layout Plain Layout
4319 \begin_layout Standard
4320 The following command produces causes äi to be produced when you enter acute-i
4324 \begin_layout LyX-Code
4338 \begin_layout Labeling
4339 \labelwidthstring 00.00.0000
4340 \begin_inset Flex CharStyle:Code
4343 \begin_layout Plain Layout
4349 Combine two accent characters
4352 \begin_layout LyX-Code
4358 accent1 accent2 allowed
4361 \begin_layout Standard
4362 This one is getting pretty esoteric.
4363 It allows you to combine the effect
4419 \begin_inset Flex CharStyle:Code
4422 \begin_layout Plain Layout
4450 \begin_layout Standard
4451 Consider this example from the
4452 \begin_inset Flex CharStyle:Code
4455 \begin_layout Plain Layout
4466 \begin_layout LyX-Code
4469 kmod ; acute aeioyvhAEIOYVH
4473 kcomb acute umlaut iyIY
4476 \begin_layout Standard
4477 This allows you to press
4478 \begin_inset Flex CharStyle:MenuItem
4481 \begin_layout Plain Layout
4489 and get the effect of
4490 \begin_inset Flex CharStyle:Code
4493 \begin_layout Plain Layout
4512 in this case cancels the last dead key, so if you press
4513 \begin_inset Flex CharStyle:MenuItem
4516 \begin_layout Plain Layout
4525 \begin_inset Flex CharStyle:Code
4528 \begin_layout Plain Layout
4541 \begin_layout Subsection
4545 \begin_layout Standard
4547 \begin_inset Flex CharStyle:Code
4550 \begin_layout Plain Layout
4558 mapping is performed, a
4559 \begin_inset Flex CharStyle:Code
4562 \begin_layout Plain Layout
4572 file maps the strings that the symbols generate to characters in the current
4574 The LyX distribution currently includes at least the
4575 \begin_inset Flex CharStyle:Code
4578 \begin_layout Plain Layout
4587 \begin_inset Flex CharStyle:Code
4590 \begin_layout Plain Layout
4601 \begin_layout Standard
4603 \begin_inset Flex CharStyle:Code
4606 \begin_layout Plain Layout
4614 file is a sequence of declarations of the form
4617 \begin_layout LyX-Code
4630 \begin_layout Standard
4631 For example, in order to map
4632 \begin_inset Flex CharStyle:MenuItem
4635 \begin_layout Plain Layout
4645 to the corresponding character in the iso-8859-1 set (233), the following
4649 \begin_layout LyX-Code
4657 \begin_layout Standard
4659 \begin_inset Flex CharStyle:Code
4662 \begin_layout Plain Layout
4671 \begin_inset Flex CharStyle:Code
4674 \begin_layout Plain Layout
4692 the same character can apply to more than one string.
4694 \begin_inset Flex CharStyle:Code
4697 \begin_layout Plain Layout
4708 \begin_layout LyX-Code
4720 \begin_inset Newline newline
4736 \begin_layout Standard
4737 If LyX cannot find a mapping for the string produced by the keystroke or
4738 a deadkey sequence, it will check if it looks like an accented char and
4739 try to draw an accent over the character on screen.
4742 \begin_layout Subsection
4746 \begin_layout Standard
4747 There is a second way to add support for international characters through
4748 so-called dead-keys.
4749 A dead-key works in combination with a letter to produce an accented character.
4750 Here, we'll explain how to create a really simple dead-key to illustrate
4754 \begin_layout Standard
4755 Suppose you happen to need the circumflex character,
4756 \begin_inset Quotes eld
4760 \begin_inset Quotes erd
4765 \begin_inset Flex CharStyle:MenuItem
4768 \begin_layout Plain Layout
4775 \begin_inset space ~
4779 \begin_inset Flex CharStyle:MenuItem
4782 \begin_layout Plain Layout
4788 ] to the LyX command
4789 \begin_inset Flex CharStyle:Code
4792 \begin_layout Plain Layout
4799 \begin_inset Flex CharStyle:Code
4802 \begin_layout Plain Layout
4809 Now, whenever you type the
4810 \begin_inset Flex CharStyle:MenuItem
4813 \begin_layout Plain Layout
4819 -key followed by a letter, that letter will have a circumflex accent on
4821 For example, the sequence
4822 \begin_inset Quotes eld
4826 \begin_inset Flex CharStyle:MenuItem
4829 \begin_layout Plain Layout
4836 \begin_inset Quotes erd
4839 produces the letter:
4840 \begin_inset Quotes eld
4844 \begin_inset Quotes erd
4848 If you tried to type
4849 \begin_inset Quotes eld
4853 \begin_inset Flex CharStyle:MenuItem
4856 \begin_layout Plain Layout
4863 \begin_inset Quotes erd
4866 , however, LyX will complain with a beep, since a
4867 \begin_inset Quotes eld
4871 \begin_inset Flex CharStyle:MenuItem
4874 \begin_layout Plain Layout
4881 \begin_inset Quotes erd
4884 never takes a circumflex accent.
4886 \begin_inset Flex CharStyle:MenuItem
4889 \begin_layout Plain Layout
4895 after a dead-key produces the bare-accent.
4896 Please note this last point! If you bind a key to a dead-key, you'll need
4897 to rebind the character on that key to yet another key.
4899 \begin_inset Flex CharStyle:MenuItem
4902 \begin_layout Plain Layout
4908 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4911 \begin_layout Standard
4912 One common way to bind dead-keys is to use
4913 \begin_inset Flex CharStyle:MenuItem
4916 \begin_layout Plain Layout
4923 \begin_inset Flex CharStyle:MenuItem
4926 \begin_layout Plain Layout
4933 \begin_inset Flex CharStyle:MenuItem
4936 \begin_layout Plain Layout
4942 in combination with an accent, like
4943 \begin_inset Quotes eld
4947 \begin_inset Flex CharStyle:MenuItem
4950 \begin_layout Plain Layout
4957 \begin_inset Quotes erd
4961 \begin_inset Quotes eld
4965 \begin_inset Flex CharStyle:MenuItem
4968 \begin_layout Plain Layout
4975 \begin_inset Quotes erd
4979 \begin_inset Quotes eld
4983 \begin_inset Flex CharStyle:MenuItem
4986 \begin_layout Plain Layout
4993 \begin_inset Quotes erd
4997 Another way involves using
4998 \begin_inset Flex CharStyle:Code
5001 \begin_layout Plain Layout
5008 \begin_inset Flex CharStyle:Code
5011 \begin_layout Plain Layout
5017 to set up the special
5018 \begin_inset Flex CharStyle:Code
5021 \begin_layout Plain Layout
5029 \begin_inset Flex CharStyle:Code
5032 \begin_layout Plain Layout
5038 acts in some ways just like
5039 \begin_inset Flex CharStyle:MenuItem
5042 \begin_layout Plain Layout
5048 and permits you to bind keys to accented characters.
5049 You can also turn keys into dead-keys by binding them to something like
5051 \begin_inset Flex CharStyle:Code
5054 \begin_layout Plain Layout
5060 and then binding this symbolic key to the corresponding LyX command.
5064 \begin_layout Plain Layout
5069 : This is exactly what I do in my
5070 \begin_inset Flex CharStyle:Code
5073 \begin_layout Plain Layout
5080 \begin_inset Flex CharStyle:Code
5083 \begin_layout Plain Layout
5091 \begin_inset Flex CharStyle:MenuItem
5094 \begin_layout Plain Layout
5096 \begin_inset space ~
5105 \begin_inset Flex CharStyle:Code
5108 \begin_layout Plain Layout
5114 and a bunch of these
5115 \begin_inset Quotes eld
5119 \begin_inset Flex CharStyle:Code
5122 \begin_layout Plain Layout
5129 \begin_inset Quotes erd
5132 symbolic keys bound such things as
5133 \begin_inset Flex CharStyle:MenuItem
5136 \begin_layout Plain Layout
5138 \begin_inset space ~
5147 \begin_inset Flex CharStyle:MenuItem
5150 \begin_layout Plain Layout
5152 \begin_inset space ~
5161 This is how I produce my accented characters.
5166 You can make just about anything into the
5167 \begin_inset Flex CharStyle:Code
5170 \begin_layout Plain Layout
5177 \begin_inset Flex CharStyle:MenuItem
5180 \begin_layout Plain Layout
5186 keys, a spare function key, etc.
5187 As for the LyX commands that produce accents, check the entry for
5188 \begin_inset Flex CharStyle:Code
5191 \begin_layout Plain Layout
5202 You'll find the complete list there.
5205 \begin_layout Subsection
5206 Saving your Language Configuration
5209 \begin_layout Standard
5210 You can edit your preferences so that your desired language environment
5211 is automatically configured when LyX starts up, via the
5212 \begin_inset Flex CharStyle:MenuItem
5215 \begin_layout Plain Layout
5216 Edit\SpecialChar \menuseparator
5225 \begin_layout Chapter
5226 Installing New Document Classes, Layouts, and Templates
5227 \begin_inset CommandInset label
5229 name "cha:Installing-New-Document"
5237 \begin_layout Plain Layout
5238 Installing New Document Classes
5246 \begin_layout Standard
5247 In this chapter, we describe the procedures for creating and installing
5248 new LyX layout and template files, as well as offer a refresher on correctly
5249 installing new LaTeX document classes.
5250 Some definitions: a document class is a LaTeX file (usually ending in
5251 \begin_inset Flex CharStyle:Code
5254 \begin_layout Plain Layout
5261 \begin_inset Flex CharStyle:Code
5264 \begin_layout Plain Layout
5270 ) that describes the format of a document such as an article, report, journal
5271 preprint, etc, and all the commands needed to realize that format.
5272 A layout file is a LyX file that corresponds to a LaTeX document class
5273 and that tells LyX how to
5274 \begin_inset Quotes eld
5278 \begin_inset Quotes erd
5281 things on the screen to make the display look something like the final
5283 More precisely, a layout file describes a
5284 \begin_inset Quotes eld
5288 \begin_inset Quotes erd
5291 which is the internal construct LyX uses to render the screen display.
5293 \begin_inset Quotes eld
5297 \begin_inset Quotes erd
5301 \begin_inset Quotes eld
5305 \begin_inset Quotes erd
5308 can be used somewhat interchangeably, but it is better to refer to the
5309 file as the layout, and the thing living in LyX's memory as the text class.
5310 A template file is simply a LyX document that contains a set of predefined
5311 entries for a given document class—entries that are generally required
5313 Templates are especially useful for things like journal manuscripts that
5314 are to be submitted electronically.
5317 \begin_layout Section
5318 Installing a new LaTeX package
5321 \begin_layout Standard
5322 Some installations may not include a LaTeX package that you would like to
5324 For example, you might need FoilTeX, a package for preparing slides or
5325 viewgraphs for overhead projectors.
5326 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5327 a user interface for that.
5328 For example on MiKTeX you start its program
5329 \begin_inset Quotes eld
5333 \begin_inset Quotes erd
5336 to get a list of available packages.
5337 To install one, right click on it or use the installing toolbar button.
5338 When the package you want to install is not in the list, but you have it
5340 \begin_inset Flex CharStyle:Code
5343 \begin_layout Plain Layout
5350 \begin_inset Flex CharStyle:Code
5353 \begin_layout Plain Layout
5359 -file, then copy these files to a subfolder of your LaTeX distribution,
5360 for example to the folder
5369 Then update the file name database of your LaTeX-distribution.
5370 For example on MiKTeX this is done by pressing the button
5373 \begin_inset space ~
5378 that you find in MiKTeX's
5379 \begin_inset Quotes eld
5383 \begin_inset Quotes erd
5387 In both cases you need afterwards to reconfigure LyX using the menu
5388 \begin_inset Flex CharStyle:MenuItem
5391 \begin_layout Plain Layout
5392 Tools\SpecialChar \menuseparator
5398 and then to restart LyX.
5401 \begin_layout Standard
5402 If your LaTeX distribution doesn't provide a user interface, then you can
5403 follow these steps by using a UNIX/Linux console.
5406 \begin_layout Enumerate
5407 Get the package from
5408 \begin_inset CommandInset href
5411 target "http://www.ctan.org/"
5418 \begin_layout Enumerate
5419 You can install this package in several different places.
5420 If you want it to be available for all users on your system, then you should
5421 install it in your `local' TeX tree; if you want (or need) it to be available
5422 just for you, then you can install it in your own `user' TeX tree.
5423 Where these should be created, if they do not already exist, depends upon
5424 the details of your system.
5425 To find out, look in the file
5426 \begin_inset Flex CharStyle:Code
5429 \begin_layout Plain Layout
5439 \begin_layout Plain Layout
5440 This usually lives in the directory
5441 \begin_inset Flex CharStyle:Code
5444 \begin_layout Plain Layout
5450 , though you can run
5451 \begin_inset Flex CharStyle:Code
5454 \begin_layout Plain Layout
5465 The location of the `local' TeX tree is defined by
5466 \begin_inset Flex CharStyle:Code
5469 \begin_layout Plain Layout
5475 ; this is usually somewhere like
5476 \begin_inset Flex CharStyle:Code
5479 \begin_layout Plain Layout
5480 /usr/local/share/texmf/
5486 The `user' TeX tree is defined by
5487 \begin_inset Flex CharStyle:Code
5490 \begin_layout Plain Layout
5497 \begin_inset Flex CharStyle:Code
5500 \begin_layout Plain Layout
5507 (If these variables are not predefined, you can define them.) You'll probably
5508 need root permissions to create or modify the `local' tree; but your `user'
5509 tree shouldn't have such limitations.
5512 \begin_layout Enumerate
5514 \begin_inset Flex CharStyle:Code
5517 \begin_layout Plain Layout
5524 \begin_inset Flex CharStyle:Code
5527 \begin_layout Plain Layout
5534 \begin_inset Flex CharStyle:Code
5537 \begin_layout Plain Layout
5544 \begin_inset space \thinspace{}
5548 \begin_inset Newline newline
5552 \begin_inset Flex CharStyle:Code
5555 \begin_layout Plain Layout
5556 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5562 \begin_inset Newline newline
5565 But, again, most of this will
5566 \begin_inset Quotes eld
5570 \begin_inset Quotes erd
5576 \begin_layout Enumerate
5581 \begin_layout Plain Layout
5582 We'll assume henceforth that you're defining `local' TeX tree.
5583 If you're defining a user tree, just adjust as necessary.
5589 You must follow the directory structure of your existing
5590 \begin_inset Flex CharStyle:Code
5593 \begin_layout Plain Layout
5599 directory, which will be found at
5600 \begin_inset Flex CharStyle:Code
5603 \begin_layout Plain Layout
5610 For example, latex packages should go under
5611 \begin_inset Flex CharStyle:Code
5614 \begin_layout Plain Layout
5615 $TEXMFLOCAL/tex/latex/
5623 \begin_layout Enumerate
5624 Install the package.
5625 For example, you would unpack the FoilTeX tarball and copy it to
5626 \begin_inset Flex CharStyle:Code
5629 \begin_layout Plain Layout
5630 $TEXMFLOCAL/tex/latex/foiltex
5637 \begin_inset Flex CharStyle:Code
5640 \begin_layout Plain Layout
5646 directory contains various files.
5649 \begin_layout Enumerate
5651 \begin_inset Flex CharStyle:Code
5654 \begin_layout Plain Layout
5662 \begin_inset Flex CharStyle:Code
5665 \begin_layout Plain Layout
5674 \begin_layout Standard
5675 Your package is now installed and available to LaTeX.
5676 To make it available to LyX, you need to create a Layout file, if one is
5677 not already available.
5678 (See the next section.) Once you have a layout file, you need only reconfigure
5680 \begin_inset Flex CharStyle:MenuItem
5683 \begin_layout Plain Layout
5684 Tools\SpecialChar \menuseparator
5690 ) and then restart LyX.
5691 You should then see your new package—for example
5692 \begin_inset Flex CharStyle:MenuItem
5695 \begin_layout Plain Layout
5702 \begin_inset Flex CharStyle:MenuItem
5705 \begin_layout Plain Layout
5706 Document\SpecialChar \menuseparator
5713 \begin_inset Flex CharStyle:MenuItem
5716 \begin_layout Plain Layout
5726 \begin_layout Section
5730 \begin_layout Standard
5731 This section describes how to write and install your own LyX layout files
5732 and walks through the
5733 \begin_inset Flex CharStyle:Code
5736 \begin_layout Plain Layout
5742 text class format as an example.
5744 \begin_inset Flex CharStyle:Code
5747 \begin_layout Plain Layout
5753 files describe what paragraph and character styles are available for a
5754 given document class and how LyX should display them.
5755 We try to provide a thorough description of the process here; however,
5756 there are so many different types of documents supported by LaTeX classes
5757 that we can't hope to cover every different possibility or problem you
5759 (The LyX users' list is frequented by people with lots of experience with
5760 layout design who are willing to share what they've learned.)
5763 \begin_layout Standard
5764 As you prepare to write a new layout, it is extremely helpful to look at
5765 the example layouts distributed with LyX.
5766 If you use a nice LaTeX document class that might be of interest for others,
5767 too, and have a nice corresponding LyX layout, feel free to contribute
5768 the stuff to us, so we may put it into the distribution.
5770 \begin_inset CommandInset href
5772 name "section on the LyX wiki"
5773 target "http://wiki.lyx.org/Layouts/Layouts"
5777 for this kind of material.
5780 \begin_layout Standard
5781 All the tags described in this chapter are case-insensitive; this means
5783 \begin_inset Flex CharStyle:Code
5786 \begin_layout Plain Layout
5793 \begin_inset Flex CharStyle:Code
5796 \begin_layout Plain Layout
5803 \begin_inset Flex CharStyle:Code
5806 \begin_layout Plain Layout
5812 are really the same command.
5813 The possible values are printed in brackets after the feature's name.
5814 The default value if a feature isn't specified inside a text class-description
5816 \begin_inset Flex CharStyle:Code
5819 \begin_layout Plain Layout
5828 If the argument has a data type like
5829 \begin_inset Quotes eld
5833 \begin_inset Quotes erd
5837 \begin_inset Quotes eld
5841 \begin_inset Quotes erd
5844 , the default is shown like this:
5845 \begin_inset Flex CharStyle:Code
5848 \begin_layout Plain Layout
5859 \begin_layout Subsection
5861 \begin_inset CommandInset label
5863 name "sub:Layout-modules"
5870 \begin_layout Standard
5871 Similar to layout files, and new with LyX 1.6, are layout
5876 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
5877 some modules—such as the endnotes module—provide support for just such
5879 In a sense, layout modules are similar to included files—files like
5880 \begin_inset Flex CharStyle:Code
5883 \begin_layout Plain Layout
5889 —in that modules are not specific to a given document layout but may be
5890 used with many different layouts.
5891 The difference is that using a layout module does not require editing the
5893 Rather, modules are selected in the
5894 \begin_inset Flex CharStyle:MenuItem
5897 \begin_layout Plain Layout
5898 Document\SpecialChar \menuseparator
5907 \begin_layout Standard
5908 Building modules is the easiest way to get started with layout editing,
5909 since it can be as simple as adding a single new paragraph or flex inset.
5910 But modules may, in principle, contain anything a layout file can contain.
5913 \begin_layout Standard
5914 A module must begin with a line like the following:
5917 \begin_layout LyX-Code
5920 DeclareLyXModule[endnotes.sty]{Endnotes}
5923 \begin_layout Standard
5924 The mandatory argument, in curly brackets, is the name of the module, as
5926 \begin_inset Flex CharStyle:MenuItem
5929 \begin_layout Plain Layout
5930 Document\SpecialChar \menuseparator
5937 The argument in square brackets is optional: It declares any LaTeX packages
5938 on which the module depends.
5939 Please note that only packages about which LyX knows should be listed in
5940 the square brackets.
5944 \begin_layout Plain Layout
5945 The list of such packages is documented only in the source code.
5950 LyX will not check for arbitrary packages.
5951 It is also possible to use the form
5952 \begin_inset Flex CharStyle:MenuItem
5955 \begin_layout Plain Layout
5961 , which declares that the module can only be used when there exists a conversion
5962 chain between formats `from' and `to'.
5965 \begin_layout Standard
5966 The module declaration should then be followed by lines like the following:
5969 \begin_layout LyX-Code
5973 \begin_layout LyX-Code
5974 #Adds an endnote command, in addition to footnotes.
5978 \begin_layout LyX-Code
5979 #You will need to add
5981 theendnotes in TeX code where you
5984 \begin_layout LyX-Code
5985 #want the endnotes to appear.
5989 \begin_layout LyX-Code
5993 \begin_layout LyX-Code
5994 #Requires: somemodule | othermodule
5997 \begin_layout LyX-Code
5998 #Excludes: badmodule
6001 \begin_layout Standard
6002 The description is used in
6003 \begin_inset Flex CharStyle:MenuItem
6006 \begin_layout Plain Layout
6007 Document\SpecialChar \menuseparator
6013 to provide the user with information about what the module does.
6015 \begin_inset Flex CharStyle:Code
6018 \begin_layout Plain Layout
6024 line is used to identify other modules with which this one must be used;
6026 \begin_inset Flex CharStyle:Code
6029 \begin_layout Plain Layout
6035 line is used to identify modules with which this one may not be used.
6036 Both are optional, and, as shown, multiple modules should be separated
6037 with the pipe symbol: |.
6038 Note that the required modules are treated disjunctively:
6042 of the required modules must be used.
6047 excluded module may be used.
6048 Note that modules are identified here by their
6052 without the .module extension.
6054 \begin_inset Flex CharStyle:Code
6057 \begin_layout Plain Layout
6064 \begin_inset Flex CharStyle:Code
6067 \begin_layout Plain Layout
6076 \begin_layout Standard
6077 After creating a new module, you will need to reconfigure and then restart
6078 LyX for the module to appear in the menu.
6079 However, changes you make to the module will be seen immediately, if you
6081 \begin_inset Flex CharStyle:MenuItem
6084 \begin_layout Plain Layout
6085 Document\SpecialChar \menuseparator
6091 , highlight something, and then hit
6092 \begin_inset Quotes eld
6096 \begin_inset Quotes erd
6102 It is strongly recommended that you save your work before doing so
6107 it is strongly recommended that you not attempt to edit modules while simultaneo
6108 usly working on documents
6111 Though of course the developers strive to keep LyX stable in such situations,
6112 syntax errors and the like in your module file could cause strange behavior.
6115 \begin_layout Subsection
6116 Supporting new document classes
6119 \begin_layout Standard
6120 There are two situations you are likely to encounter when wanting to support
6121 a new LaTeX document class, involving LaTeX2e class (
6122 \begin_inset Flex CharStyle:Code
6125 \begin_layout Plain Layout
6132 \begin_inset Flex CharStyle:Code
6135 \begin_layout Plain Layout
6142 Supporting a style file is usually fairly easy.
6143 Supporting a new document class is a bit harder.
6146 \begin_layout Subsection
6148 \begin_inset Flex CharStyle:MenuItem
6151 \begin_layout Plain Layout
6160 \begin_layout Standard
6161 If your new document class is provided as a style file that is used in conjuncti
6162 on with an existing, supported document class—for the sake of the example,
6163 we'll assume that the style file is called
6164 \begin_inset Flex CharStyle:MenuItem
6167 \begin_layout Plain Layout
6173 and it is meant to be used with
6174 \begin_inset Flex CharStyle:MenuItem
6177 \begin_layout Plain Layout
6183 , which is a standard class—start by copying the existing class's layout
6184 file into your local directory:
6187 \begin_layout LyX-Code
6188 cp report.layout ~/.lyx/layouts/myclass.layout
6191 \begin_layout Standard
6193 \begin_inset Flex CharStyle:Code
6196 \begin_layout Plain Layout
6202 and change the line:
6205 \begin_layout LyX-Code
6208 DeclareLaTeXClass{report}
6211 \begin_layout Standard
6215 \begin_layout LyX-Code
6218 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6221 \begin_layout Standard
6225 \begin_layout LyX-Code
6227 \begin_inset Newline newline
6233 \begin_inset Newline newline
6239 \begin_layout Standard
6240 near the top of the file.
6243 \begin_layout Standard
6244 Start LyX and select
6245 \begin_inset Flex CharStyle:MenuItem
6248 \begin_layout Plain Layout
6249 Tools\SpecialChar \menuseparator
6256 Then restart LyX and try creating a new document.
6258 \begin_inset Flex CharStyle:MenuItem
6261 \begin_layout Plain Layout
6267 " as a document class option in the
6268 \begin_inset Flex CharStyle:MenuItem
6271 \begin_layout Plain Layout
6272 Document\SpecialChar \menuseparator
6279 It is likely that some of the sectioning commands and such in your new
6280 class will work differently from how they worked in the base class—
6281 \begin_inset Flex CharStyle:Code
6284 \begin_layout Plain Layout
6290 in this example—so you can fiddle around with the settings for the different
6291 sections if you wish.
6294 \begin_layout Subsection
6296 \begin_inset Flex CharStyle:MenuItem
6299 \begin_layout Plain Layout
6308 \begin_layout Standard
6309 There are two possibilities here.
6310 One is that the class file is itself based upon an existing document class.
6311 For example, many thesis classes are based upon
6312 \begin_inset Flex CharStyle:MenuItem
6315 \begin_layout Plain Layout
6322 To see whether yours is, look for a line like
6325 \begin_layout LyX-Code
6331 \begin_layout Standard
6333 If so, then you may proceed largely as in the previous section, though
6334 the DeclareLaTeXClass line will be different.
6335 If your new class is thesis, and it is based upon book, then the line should
6340 \begin_layout Plain Layout
6341 And it will be easiest if you save the file to
6342 \begin_inset Flex CharStyle:Code
6345 \begin_layout Plain Layout
6351 : LyX assumes that the document class has the same name as the layout file.
6360 \begin_layout LyX-Code
6363 DeclareLaTeXClass[thesis,book]{thesis}
6366 \begin_layout Standard
6367 If, on the other hand, the new class is not based upon an existing class,
6368 you will probably have to
6369 \begin_inset Quotes eld
6373 \begin_inset Quotes erd
6377 We strongly suggest copying an existing layout file which uses a similar
6378 LaTeX class and then modifying it, if you can do so.
6379 At least use an existing file as a starting point so you can find out what
6380 items you need to worry about.
6381 Again, the specifics are covered below.
6384 \begin_layout Section
6385 Declaring a new text class
6388 \begin_layout Standard
6389 When it's finally time to get your hands dirty and create or edit your own
6390 layout file, the following sections describe what you're up against.
6391 Our advice is to go slowly, save and test often, listen to soothing music,
6392 and enjoy one or two of your favorite adult beverages; more if you are
6393 getting particularly stuck.
6394 It's really not that hard, except that the multitude of options can become
6395 overwhelming if you try to do to much in one sitting.
6396 Go have another adult beverage, just for good measure.
6399 \begin_layout Standard
6403 \begin_layout Standard
6404 Lines in a layout file which begin with a
6405 \begin_inset Flex CharStyle:Code
6408 \begin_layout Plain Layout
6415 There is one exception to this rule: all layouts should begin with lines
6419 \begin_layout LyX-Code
6422 #% Do not delete the line below; configure depends on this
6425 \begin_layout LyX-Code
6430 DeclareLaTeXClass{article}
6433 \begin_layout Standard
6434 The second line is used when you configure LyX.
6435 The layout file is read by the LaTeX script
6436 \begin_inset Flex CharStyle:Code
6439 \begin_layout Plain Layout
6445 , in a special mode where
6446 \begin_inset Flex CharStyle:Code
6449 \begin_layout Plain Layout
6456 The first line is just a LaTeX comment, and the second one contains the
6457 declaration of the text class.
6458 If these lines appear in a file named
6459 \begin_inset Flex CharStyle:Code
6462 \begin_layout Plain Layout
6468 , then they define a text class of name
6469 \begin_inset Flex CharStyle:Code
6472 \begin_layout Plain Layout
6478 (the name of the layout file) which uses the LaTeX document class
6479 \begin_inset Flex CharStyle:Code
6482 \begin_layout Plain Layout
6488 (the default is to use the same name as the layout).
6490 \begin_inset Quotes eld
6494 \begin_inset Quotes erd
6497 that appears above is used as a description of the text class in the
6498 \begin_inset Flex CharStyle:MenuItem
6501 \begin_layout Plain Layout
6502 Document\SpecialChar \menuseparator
6511 \begin_layout Standard
6512 Let's assume that you wrote your own text class that uses the
6513 \begin_inset Flex CharStyle:Code
6516 \begin_layout Plain Layout
6522 document class, but where you changed the appearance of the section headings.
6523 If you put it in a file
6524 \begin_inset Flex CharStyle:Code
6527 \begin_layout Plain Layout
6533 , the header of this file should be:
6536 \begin_layout LyX-Code
6539 #% Do not delete the line below; configure depends on this
6542 \begin_layout LyX-Code
6547 DeclareLaTeXClass[article]{article (with my own headings)}
6550 \begin_layout Standard
6551 This declares a text class
6552 \begin_inset Flex CharStyle:Code
6555 \begin_layout Plain Layout
6561 , associated with the LaTeX document class
6562 \begin_inset Flex CharStyle:Code
6565 \begin_layout Plain Layout
6572 \begin_inset Quotes eld
6575 article (with my own headings)
6576 \begin_inset Quotes erd
6580 If your text class depends on several packages, you can declare it as:
6583 \begin_layout LyX-Code
6586 #% Do not delete the line below; configure depends on this
6589 \begin_layout LyX-Code
6594 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6597 \begin_layout Standard
6598 This indicates that your text class uses the foo.sty package.
6599 Finally, it is also possible to declare classes for DocBook code.
6600 Typical declarations will look like
6603 \begin_layout LyX-Code
6606 #% Do not delete the line below; configure depends on this
6609 \begin_layout LyX-Code
6614 DeclareDocBookClass[article]{SGML (DocBook article)}
6617 \begin_layout Standard
6618 Note that these declarations can also be given an optional parameter declaring
6619 the name of the document class (but not a list).
6622 \begin_layout Standard
6623 So, to be as explicit as possible, the form of the layout declaration is:
6626 \begin_layout LyX-Code
6631 DeclareLaTeXClass[class,package.sty]{layout description}
6634 \begin_layout Standard
6635 The class need only be specified if the name of the LaTeX class file and
6636 the name of the layout file are different; if the name of the class file
6637 is not specified, then LyX will simply assume that it is the same as the
6638 name of the layout file.
6641 \begin_layout Standard
6642 When the text class has been modified to your taste, all you have to do
6643 is to copy it either to
6644 \begin_inset Flex CharStyle:Code
6647 \begin_layout Plain Layout
6654 \begin_inset Flex CharStyle:Code
6657 \begin_layout Plain Layout
6664 \begin_inset Flex CharStyle:MenuItem
6667 \begin_layout Plain Layout
6668 Tools\SpecialChar \menuseparator
6674 , exit LyX and restart it.
6675 Then your new text class should be available along with the others.
6678 \begin_layout Standard
6679 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6680 you made to your layout files.
6681 As a result, editing layout files could be very time consuming.
6682 Beginning with 1.6, however, you can force a reload of the layout currently
6683 in use by using the LyX function
6684 \begin_inset Flex CharStyle:MenuItem
6687 \begin_layout Plain Layout
6694 There is no default binding for this function—though, of course, you can
6695 bind it to a key yourself.
6696 If you want to use this function, then, you should simply enter it in the
6702 : This is very much an `advanced feature'.
6707 recommended that you save your work before using this function.
6712 recommended that you not attempt to edit your layout while simultaneously
6713 working on a document that you care about.
6714 Use a test document.
6715 Syntax errors and the like in your layout file could cause peculiar behavior.
6716 In particular, such errors could cause LyX to regard the current layout
6717 as invalid and to attempt to switch to some other layout.
6718 The LyX team strives to keep LyX stable in such situations, but safe is
6722 \begin_layout Subsection
6726 \begin_layout Standard
6727 The first non-comment line must contain the file format number:
6730 \begin_layout Description
6731 \begin_inset Flex CharStyle:Code
6734 \begin_layout Plain Layout
6741 \begin_inset Flex CharStyle:Code
6744 \begin_layout Plain Layout
6750 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6751 don't have an explicit file format).
6752 The file format that is documented here is format 14.
6755 \begin_layout Subsection
6756 General text class parameters
6759 \begin_layout Standard
6760 These are the general parameters which describe the form of the entire document:
6763 \begin_layout Description
6764 \begin_inset Flex CharStyle:Code
6767 \begin_layout Plain Layout
6773 Adds information to the document preamble.
6775 \begin_inset Quotes eld
6779 \begin_inset Flex CharStyle:Code
6782 \begin_layout Plain Layout
6789 \begin_inset Quotes erd
6795 \begin_layout Description
6796 \begin_inset Flex CharStyle:Code
6799 \begin_layout Plain Layout
6805 Describes various global options supported by the document class.
6807 \begin_inset space ~
6811 \begin_inset CommandInset ref
6813 reference "sub:ClassOptions"
6819 \begin_inset Quotes eld
6823 \begin_inset Flex CharStyle:Code
6826 \begin_layout Plain Layout
6833 \begin_inset Quotes erd
6839 \begin_layout Description
6840 \begin_inset Flex CharStyle:Code
6843 \begin_layout Plain Layout
6850 \begin_inset Flex CharStyle:Code
6853 \begin_layout Plain Layout
6862 \begin_inset Flex CharStyle:Code
6865 \begin_layout Plain Layout
6871 ] Whether the class should default to having one or two columns.
6872 Can be changed in the
6873 \begin_inset Flex CharStyle:MenuItem
6876 \begin_layout Plain Layout
6877 Document\SpecialChar \menuseparator
6886 \begin_layout Description
6887 \begin_inset Flex CharStyle:Code
6890 \begin_layout Plain Layout
6896 This sequence defines a new counter.
6898 \begin_inset space ~
6902 \begin_inset CommandInset ref
6904 reference "sub:Counters"
6910 \begin_inset Quotes eld
6914 \begin_inset Flex CharStyle:Code
6917 \begin_layout Plain Layout
6924 \begin_inset Quotes erd
6930 \begin_layout Description
6931 \begin_inset Flex CharStyle:Code
6934 \begin_layout Plain Layout
6940 Sets the default font used to display the document.
6942 \begin_inset space ~
6946 \begin_inset CommandInset ref
6948 reference "sub:Font-description"
6952 for how to declare fonts.
6954 \begin_inset Quotes eld
6958 \begin_inset Flex CharStyle:Code
6961 \begin_layout Plain Layout
6968 \begin_inset Quotes erd
6974 \begin_layout Description
6975 \begin_inset Flex CharStyle:Code
6978 \begin_layout Plain Layout
6985 \begin_inset Flex CharStyle:Code
6988 \begin_layout Plain Layout
6994 Specifies a module to be included by default with this document class,
6995 which should be specified by filename without the
6996 \begin_inset Flex CharStyle:Code
6999 \begin_layout Plain Layout
7006 The user can still remove the module, but it will be active at the outset.
7007 (This applies only when new files are created, or when this class is chosen
7008 for an existing document.)
7011 \begin_layout Description
7012 \begin_inset Flex CharStyle:Code
7015 \begin_layout Plain Layout
7022 \begin_inset Flex CharStyle:Code
7025 \begin_layout Plain Layout
7031 ] This is the style that will be assigned to new paragraphs, usually
7032 \begin_inset Flex CharStyle:MenuItem
7035 \begin_layout Plain Layout
7042 This will default to the first defined style if not given, but you are
7043 highly encouraged to use this directive.
7046 \begin_layout Description
7047 \begin_inset Flex CharStyle:Code
7050 \begin_layout Plain Layout
7057 \begin_inset Flex CharStyle:Code
7060 \begin_layout Plain Layout
7066 ] Indicates that the module in question—which should be specified by filename
7068 \begin_inset Flex CharStyle:Code
7071 \begin_layout Plain Layout
7077 extension—cannot be used with this document class.
7078 This might be used in a journal-specific layout file to prevent, say, the
7080 \begin_inset Flex CharStyle:Code
7083 \begin_layout Plain Layout
7089 module that numbers theorems by section.
7094 be used in a module.
7095 Modules have their own way of excluding other modules (see
7096 \begin_inset CommandInset ref
7098 reference "sub:Layout-modules"
7105 \begin_layout Description
7106 \begin_inset Flex CharStyle:Code
7109 \begin_layout Plain Layout
7115 Defines a new float.
7117 \begin_inset space ~
7121 \begin_inset CommandInset ref
7123 reference "sub:Floats"
7129 \begin_inset Quotes eld
7133 \begin_inset Flex CharStyle:Code
7136 \begin_layout Plain Layout
7143 \begin_inset Quotes erd
7149 \begin_layout Description
7150 \begin_inset Flex CharStyle:Code
7153 \begin_layout Plain Layout
7159 As its name implies, this command allows you to include another layout
7160 definition file within yours to avoid duplicating commands.
7161 Common examples are the standard layout files, for example,
7162 \begin_inset Flex CharStyle:Code
7165 \begin_layout Plain Layout
7171 , which contains most of the basic layouts.
7174 \begin_layout Description
7175 \begin_inset Flex CharStyle:Code
7178 \begin_layout Plain Layout
7184 This section (re-)defines the layout of an inset.
7185 It can be applied to an existing inset of to a new, user-defined inset,
7187 \begin_inset space \thinspace{}
7191 \begin_inset space \space{}
7194 a new character style.
7196 \begin_inset space ~
7200 \begin_inset CommandInset ref
7202 reference "sub:Flex-insets-and"
7206 for more information.
7208 \begin_inset Quotes eld
7212 \begin_inset Flex CharStyle:Code
7215 \begin_layout Plain Layout
7222 \begin_inset Quotes erd
7228 \begin_layout Description
7229 \begin_inset Flex CharStyle:Code
7232 \begin_layout Plain Layout
7238 A string that indicates the width of the left margin on the screen, for
7240 \begin_inset Quotes eld
7244 \begin_inset Quotes erd
7250 \begin_layout Description
7251 \begin_inset Flex CharStyle:Code
7254 \begin_layout Plain Layout
7260 This command deletes an existing float.
7261 This is particularly useful when you want to suppress a float that has
7262 be defined in an input file.
7265 \begin_layout Description
7266 \begin_inset Flex CharStyle:Code
7269 \begin_layout Plain Layout
7275 This command deletes an existing style.
7276 This is particularly useful when you want to suppress a style that has
7277 be defined in an input file.
7280 \begin_layout Description
7281 \begin_inset Flex CharStyle:Code
7284 \begin_layout Plain Layout
7290 A string indicating the file format (as defined in the Preferences dialog)
7291 produced by this class.
7292 It is mainly useful when
7293 \begin_inset Flex CharStyle:Code
7296 \begin_layout Plain Layout
7302 is `literate' and one wants to define a new type of literate document.
7303 This string is reset to `docbook', `latex', or `literate' when the correspondin
7305 \begin_inset Flex CharStyle:Code
7308 \begin_layout Plain Layout
7314 parameter is encountered.
7317 \begin_layout Description
7318 \begin_inset Flex CharStyle:Code
7321 \begin_layout Plain Layout
7327 A string indicating what sort of output documents using this class will
7329 At present, the options are: `docbook', `latex', and `literate'.
7332 \begin_layout Description
7333 \begin_inset Flex CharStyle:Code
7336 \begin_layout Plain Layout
7347 \begin_inset Flex CharStyle:Code
7350 \begin_layout Plain Layout
7361 \begin_inset Flex CharStyle:Code
7364 \begin_layout Plain Layout
7371 \begin_inset Flex CharStyle:Code
7374 \begin_layout Plain Layout
7380 ] The class default pagestyle.
7381 Can be changed in the
7382 \begin_inset Flex CharStyle:MenuItem
7385 \begin_layout Plain Layout
7386 Document\SpecialChar \menuseparator
7395 \begin_layout Description
7396 \begin_inset Flex CharStyle:Code
7399 \begin_layout Plain Layout
7405 Sets the preamble for the LaTeX document.
7406 Note that this will completely override any prior
7407 \begin_inset Flex CharStyle:Code
7410 \begin_layout Plain Layout
7417 \begin_inset Flex CharStyle:Code
7420 \begin_layout Plain Layout
7428 \begin_inset Quotes eld
7432 \begin_inset Flex CharStyle:Code
7435 \begin_layout Plain Layout
7442 \begin_inset Quotes erd
7448 \begin_layout Description
7449 \begin_inset Flex CharStyle:Code
7452 \begin_layout Plain Layout
7459 \begin_inset Flex CharStyle:Code
7462 \begin_layout Plain Layout
7469 \begin_inset Flex CharStyle:Code
7472 \begin_layout Plain Layout
7481 \begin_inset Flex CharStyle:Code
7484 \begin_layout Plain Layout
7490 ] Whether the class already provides the feature
7491 \begin_inset Flex CharStyle:Code
7494 \begin_layout Plain Layout
7501 A feature is in general the name of a package (
7502 \begin_inset Flex CharStyle:Code
7505 \begin_layout Plain Layout
7512 \begin_inset Flex CharStyle:Code
7515 \begin_layout Plain Layout
7521 , \SpecialChar \ldots{}
7523 \begin_inset Flex CharStyle:Code
7526 \begin_layout Plain Layout
7533 \begin_inset Flex CharStyle:Code
7536 \begin_layout Plain Layout
7542 ,\SpecialChar \ldots{}
7543 ); the complete list of supported features is unfortunately not documented
7544 outside the LyX source code—but see
7545 \begin_inset Flex CharStyle:Code
7548 \begin_layout Plain Layout
7554 if you're interested.
7556 \begin_inset Flex CharStyle:MenuItem
7559 \begin_layout Plain Layout
7560 Help\SpecialChar \menuseparator
7566 also gives an overview of the supported packages.
7569 \begin_layout Description
7570 \begin_inset Flex CharStyle:Code
7573 \begin_layout Plain Layout
7580 \begin_inset Flex CharStyle:Code
7583 \begin_layout Plain Layout
7589 ] Indicates that this layout provides the functionality of the module mentioned,
7590 which should be specified by the filename without the
7591 \begin_inset Flex CharStyle:Code
7594 \begin_layout Plain Layout
7601 This will typically be used if the layout includes the module directly,
7602 rather than using the
7603 \begin_inset Flex CharStyle:Code
7606 \begin_layout Plain Layout
7612 tag to indicate that it ought to be used.
7613 It could be used in a module that provided an alternate implementation
7614 of the same functionality.
7617 \begin_layout Description
7618 \begin_inset Flex CharStyle:Code
7621 \begin_layout Plain Layout
7628 \begin_inset Flex CharStyle:Code
7631 \begin_layout Plain Layout
7637 ] Whether the class requires the feature
7638 \begin_inset Flex CharStyle:Code
7641 \begin_layout Plain Layout
7648 Multiple features must be separated by commas.
7649 Note that you can only request supported features.
7652 \begin_layout Description
7653 \begin_inset Flex CharStyle:Code
7656 \begin_layout Plain Layout
7662 A string that indicates the width of the right margin on the screen, for
7664 \begin_inset Quotes eld
7668 \begin_inset Quotes erd
7674 \begin_layout Description
7675 \begin_inset Flex CharStyle:Code
7678 \begin_layout Plain Layout
7684 Sets which divisions get numbered.
7686 \begin_inset Flex CharStyle:Code
7689 \begin_layout Plain Layout
7698 \begin_layout Description
7699 \begin_inset Flex CharStyle:Code
7702 \begin_layout Plain Layout
7711 \begin_inset Flex CharStyle:Code
7714 \begin_layout Plain Layout
7725 \begin_inset Flex CharStyle:Code
7728 \begin_layout Plain Layout
7734 ] Whether the class-default should be printing on one or both sides of the
7736 Can be changed in the
7737 \begin_inset Flex CharStyle:MenuItem
7740 \begin_layout Plain Layout
7741 Document\SpecialChar \menuseparator
7750 \begin_layout Description
7751 \begin_inset Flex CharStyle:Code
7754 \begin_layout Plain Layout
7760 This sequence defines a new paragraph style.
7761 If the style already exists, it will redefine some of its parameters instead.
7763 \begin_inset space ~
7767 \begin_inset CommandInset ref
7769 reference "sub:Paragraph-Styles"
7775 \begin_inset Quotes eld
7779 \begin_inset Flex CharStyle:Code
7782 \begin_layout Plain Layout
7789 \begin_inset Quotes erd
7795 \begin_layout Description
7796 \begin_inset Flex CharStyle:Code
7799 \begin_layout Plain Layout
7806 \begin_inset Flex CharStyle:Code
7809 \begin_layout Plain Layout
7815 ] The name of the command or environment to be used with
7816 \begin_inset Flex CharStyle:Code
7819 \begin_layout Plain Layout
7828 \begin_layout Description
7829 \begin_inset Flex CharStyle:Code
7832 \begin_layout Plain Layout
7839 \begin_inset Flex CharStyle:Code
7842 \begin_layout Plain Layout
7851 \begin_inset Flex CharStyle:Code
7854 \begin_layout Plain Layout
7860 ] Indicates what kind of markup is used to define the title of a document.
7862 \begin_inset Flex CharStyle:Code
7865 \begin_layout Plain Layout
7871 means that the macro with name
7872 \begin_inset Flex CharStyle:Code
7875 \begin_layout Plain Layout
7881 will be inserted after the last layout which has
7882 \begin_inset Quotes eld
7886 \begin_inset Flex CharStyle:Code
7889 \begin_layout Plain Layout
7896 \begin_inset Quotes erd
7901 \begin_inset Flex CharStyle:Code
7904 \begin_layout Plain Layout
7910 corresponds to the case where the block of paragraphs which have
7911 \begin_inset Quotes eld
7915 \begin_inset Flex CharStyle:Code
7918 \begin_layout Plain Layout
7925 \begin_inset Quotes erd
7928 should be enclosed into the
7929 \begin_inset Flex CharStyle:Code
7932 \begin_layout Plain Layout
7941 \begin_layout Description
7942 \begin_inset Flex CharStyle:Code
7945 \begin_layout Plain Layout
7951 Sets which divisions are included in the table of contents.
7953 \begin_inset Flex CharStyle:Code
7956 \begin_layout Plain Layout
7965 \begin_layout Subsection
7966 \begin_inset Flex CharStyle:Code
7969 \begin_layout Plain Layout
7976 \begin_inset CommandInset label
7978 name "sub:ClassOptions"
7985 \begin_layout Standard
7987 \begin_inset Flex CharStyle:Code
7990 \begin_layout Plain Layout
7996 section can contain the following entries:
7999 \begin_layout Description
8000 \begin_inset Flex CharStyle:Code
8003 \begin_layout Plain Layout
8010 \begin_inset Flex CharStyle:Code
8013 \begin_layout Plain Layout
8019 ] The list of available font sizes for the document's main font, separated
8021 \begin_inset Quotes eld
8025 \begin_inset Flex CharStyle:Code
8028 \begin_layout Plain Layout
8035 \begin_inset Quotes erd
8041 \begin_layout Description
8042 \begin_inset Flex CharStyle:Code
8045 \begin_layout Plain Layout
8051 Used to set the DTD line with XML-based output classes.
8053 \begin_inset space \thinspace{}
8057 \begin_inset Quotes eld
8060 -//OASIS//DTD DocBook V4.2//EN
8061 \begin_inset Quotes erd
8067 \begin_layout Description
8068 \begin_inset Flex CharStyle:Code
8071 \begin_layout Plain Layout
8078 \begin_inset Flex CharStyle:Code
8081 \begin_layout Plain Layout
8082 string="empty|plain|headings|fancy"
8087 ] The list of available page styles, separated by
8088 \begin_inset Quotes eld
8092 \begin_inset Flex CharStyle:Code
8095 \begin_layout Plain Layout
8102 \begin_inset Quotes erd
8108 \begin_layout Description
8109 \begin_inset Flex CharStyle:Code
8112 \begin_layout Plain Layout
8119 \begin_inset Flex CharStyle:Code
8122 \begin_layout Plain Layout
8128 ] Some document class options, separated by a comma, that will be added
8129 to the optional part of the
8130 \begin_inset Flex CharStyle:Code
8133 \begin_layout Plain Layout
8144 \begin_layout Standard
8146 \begin_inset Flex CharStyle:Code
8149 \begin_layout Plain Layout
8155 section must end with
8156 \begin_inset Quotes eld
8160 \begin_inset Flex CharStyle:Code
8163 \begin_layout Plain Layout
8170 \begin_inset Quotes erd
8176 \begin_layout Subsection
8178 \begin_inset CommandInset label
8180 name "sub:Paragraph-Styles"
8187 \begin_layout Standard
8188 A paragraph style description looks like this:
8192 \begin_layout Plain Layout
8193 Note that this will either define a new layout or modify an existing one.
8201 \begin_layout LyX-Code
8208 \begin_layout LyX-Code
8212 \begin_layout LyX-Code
8216 \begin_layout Standard
8217 where the following commands are allowed:
8220 \begin_layout Description
8221 \begin_inset Flex CharStyle:Code
8224 \begin_layout Plain Layout
8231 \begin_inset Flex CharStyle:Code
8234 \begin_layout Plain Layout
8239 , left, right, center
8244 ] Paragraph alignment.
8247 \begin_layout Description
8248 \begin_inset Flex CharStyle:Code
8251 \begin_layout Plain Layout
8258 \begin_inset Flex CharStyle:Code
8261 \begin_layout Plain Layout
8266 , left, right, center
8271 ] A comma separated list of permitted alignments.
8272 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8274 For example a right-aligned or centered enumeration isn't possible.)
8277 \begin_layout Description
8278 \begin_inset Flex CharStyle:Code
8281 \begin_layout Plain Layout
8287 Language dependent information to be included in the LaTeX preamble when
8289 Note that this will completely override any prior
8290 \begin_inset Flex CharStyle:Code
8293 \begin_layout Plain Layout
8301 \begin_inset Quotes eld
8305 \begin_inset Flex CharStyle:Code
8308 \begin_layout Plain Layout
8315 \begin_inset Quotes erd
8319 The contents of this tag will occur once in the LaTeX preamble for each
8320 language used by the document.
8321 Each time, the following substitutions are made:
8325 \begin_layout Itemize
8326 \begin_inset Flex CharStyle:Code
8329 \begin_layout Plain Layout
8335 is replaced by the language name (as used by the babel package).
8338 \begin_layout Itemize
8340 \begin_inset Quotes eld
8344 \begin_inset Quotes erd
8348 \begin_inset Flex CharStyle:Code
8351 \begin_layout Plain Layout
8357 replaces its argument by the translation of the argument to the current
8361 \begin_layout Standard
8362 This preamble snippet will only be used if the document contains more than
8363 one language and the babel package is used.
8367 \begin_layout Description
8368 \begin_inset Flex CharStyle:Code
8371 \begin_layout Plain Layout
8378 \begin_inset Flex CharStyle:Code
8381 \begin_layout Plain Layout
8391 \begin_layout Plain Layout
8392 Note that a `float' here is a real number, such as: 1.5.
8397 The vertical space with which the last of a chain of paragraphs with this
8398 layout is separated from the following paragraph.
8399 If the next paragraph has another layout, the separations are not simply
8400 added, but the maximum is taken.
8403 \begin_layout Description
8404 \begin_inset Flex CharStyle:Code
8407 \begin_layout Plain Layout
8414 \begin_inset Flex CharStyle:Code
8417 \begin_layout Plain Layout
8423 The category for this style.
8424 This is used to group related styles in the Layout combobox on the toolbar.
8425 Any string can be used, but you may want to use existing categories with
8430 \begin_layout Description
8431 \begin_inset Flex CharStyle:Code
8434 \begin_layout Plain Layout
8440 Depth of XML command.
8441 Used only with XML-type formats.
8444 \begin_layout Description
8445 \begin_inset Flex CharStyle:Code
8448 \begin_layout Plain Layout
8455 \begin_inset CommandInset label
8457 name "des:CopyStyle"
8462 \begin_inset Flex CharStyle:Code
8465 \begin_layout Plain Layout
8471 Copies all the features of an existing style into the current one.
8475 \begin_layout Description
8476 \begin_inset Flex CharStyle:Code
8479 \begin_layout Plain Layout
8485 The name of a style whose preamble should be output
8490 This allows to ensure some ordering of the preamble snippets when macros
8491 definitions depend on one another.
8495 \begin_layout Plain Layout
8496 Note that, besides that functionality, there is no way to ensure any ordering
8498 The ordering that you see in a given version of LyX may change without
8499 warning in later versions.
8507 \begin_layout Description
8508 \begin_inset Flex CharStyle:Code
8511 \begin_layout Plain Layout
8518 \begin_inset Flex CharStyle:Code
8521 \begin_layout Plain Layout
8526 , Box, Filled_Box, Static
8531 ] The type of label that stands at the end of the paragraph (or sequence
8533 \begin_inset Flex CharStyle:Code
8536 \begin_layout Plain Layout
8543 \begin_inset Flex CharStyle:Code
8546 \begin_layout Plain Layout
8553 \begin_inset Flex CharStyle:Code
8556 \begin_layout Plain Layout
8563 \begin_inset Flex CharStyle:Code
8566 \begin_layout Plain Layout
8574 \begin_inset Flex CharStyle:Code
8577 \begin_layout Plain Layout
8584 \begin_inset Quotes eld
8588 \begin_inset Quotes erd
8592 \begin_inset Flex CharStyle:Code
8595 \begin_layout Plain Layout
8602 \begin_inset Flex CharStyle:Code
8605 \begin_layout Plain Layout
8606 \begin_inset space ~
8615 \begin_inset space ~
8618 black) square suitable for end of proof markers,
8619 \begin_inset Flex CharStyle:Code
8622 \begin_layout Plain Layout
8628 is an explicit text string.
8631 \begin_layout Description
8632 \begin_inset Flex CharStyle:Code
8635 \begin_layout Plain Layout
8642 \begin_inset Flex CharStyle:Code
8645 \begin_layout Plain Layout
8651 ] The string used for a label with a
8652 \begin_inset Flex CharStyle:Code
8655 \begin_layout Plain Layout
8662 \begin_inset Flex CharStyle:Code
8665 \begin_layout Plain Layout
8675 \begin_layout Description
8676 \begin_inset Flex CharStyle:Code
8679 \begin_layout Plain Layout
8686 \begin_inset Flex CharStyle:Code
8689 \begin_layout Plain Layout
8700 \begin_inset Flex CharStyle:Code
8703 \begin_layout Plain Layout
8712 \begin_layout Description
8713 \begin_inset Flex CharStyle:Code
8716 \begin_layout Plain Layout
8723 \begin_inset Flex CharStyle:Code
8726 \begin_layout Plain Layout
8736 ] With this parameter the
8737 \begin_inset Flex CharStyle:MenuItem
8740 \begin_layout Plain Layout
8747 \begin_inset Quotes eld
8750 Vertical space above
8751 \begin_inset Quotes erd
8755 \begin_inset Flex CharStyle:MenuItem
8758 \begin_layout Plain Layout
8759 Edit\SpecialChar \menuseparator
8761 \begin_inset space ~
8769 dialog can be set when initializing a paragraph with this style.
8773 \begin_layout Plain Layout
8776 Note from Jean-Marc:
8778 I'm not sure that this setting has much use, and it should probably be
8779 removed in later versions.
8787 \begin_layout Description
8788 \begin_inset Flex CharStyle:Code
8791 \begin_layout Plain Layout
8797 The font used for both the text body
8803 \begin_inset space ~
8807 \begin_inset CommandInset ref
8809 reference "sub:Font-description"
8814 Note that defining this font automatically defines the
8815 \begin_inset Flex CharStyle:Code
8818 \begin_layout Plain Layout
8825 So you should define this one first if you also want to define
8826 \begin_inset Flex CharStyle:Code
8829 \begin_layout Plain Layout
8838 \begin_layout Description
8839 \begin_inset Flex CharStyle:Code
8842 \begin_layout Plain Layout
8849 \begin_inset CommandInset label
8851 name "des:FreeSpacing"
8858 \begin_inset Flex CharStyle:Code
8861 \begin_layout Plain Layout
8872 \begin_inset Flex CharStyle:Code
8875 \begin_layout Plain Layout
8881 ] Usually LyX doesn't allow you to insert more than one space between words,
8882 since a space is considered as the separation between two words, not a
8883 character or symbol of its own.
8884 This is a very fine thing but sometimes annoying, for example, when typing
8885 program code or plain LaTeX code.
8887 \begin_inset Flex CharStyle:Code
8890 \begin_layout Plain Layout
8897 Note that LyX will create protected blanks for the additional blanks when
8898 in another mode than LaTeX-mode.
8901 \begin_layout Description
8902 \begin_inset Flex CharStyle:Code
8905 \begin_layout Plain Layout
8911 [[FIXME]] (Used only with XML-type formats.)
8914 \begin_layout Description
8915 \begin_inset Flex CharStyle:Code
8918 \begin_layout Plain Layout
8925 \begin_inset Flex CharStyle:Code
8928 \begin_layout Plain Layout
8934 If 1, marks the layout as being part of a title block (see also the
8935 \begin_inset Flex CharStyle:Code
8938 \begin_layout Plain Layout
8945 \begin_inset Flex CharStyle:Code
8948 \begin_layout Plain Layout
8957 \begin_layout Description
8958 \begin_inset Flex CharStyle:Code
8961 \begin_layout Plain Layout
8968 \begin_inset Flex CharStyle:Code
8971 \begin_layout Plain Layout
8977 ] This provides extra space between paragraphs that have the same layout.
8978 If you put other layouts into an environment, each is separated with the
8980 \begin_inset Flex CharStyle:Code
8983 \begin_layout Plain Layout
8990 But the whole items of the environment are additionally separated with
8992 \begin_inset Flex CharStyle:Code
8995 \begin_layout Plain Layout
9007 \begin_layout Description
9008 \begin_inset Flex CharStyle:Code
9011 \begin_layout Plain Layout
9017 [[FIXME]] (Used only with XML-type formats.)
9020 \begin_layout Description
9021 \begin_inset Flex CharStyle:Code
9024 \begin_layout Plain Layout
9031 \begin_inset CommandInset label
9033 name "des:KeepEmpty"
9040 \begin_inset Flex CharStyle:Code
9043 \begin_layout Plain Layout
9054 \begin_inset Flex CharStyle:Code
9057 \begin_layout Plain Layout
9063 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9064 lead to empty LaTeX output.
9065 There are some cases where this could be desirable however: in a letter
9066 template, the required fields can be provided as empty fields, so that
9067 people do not forget them; in some special classes, a layout can be used
9068 as some kind of break, which does not contain actual text.
9071 \begin_layout Description
9072 \begin_inset Flex CharStyle:Code
9075 \begin_layout Plain Layout
9081 [float=0] The vertical space between the label and the text body.
9082 Only used for labels that are above the text body (
9083 \begin_inset Flex CharStyle:Code
9086 \begin_layout Plain Layout
9093 \begin_inset Flex CharStyle:Code
9096 \begin_layout Plain Layout
9097 Centered_Top_Environment
9105 \begin_layout Description
9106 \begin_inset Flex CharStyle:Code
9109 \begin_layout Plain Layout
9116 \begin_inset Flex CharStyle:Code
9119 \begin_layout Plain Layout
9126 \begin_inset Newline newline
9129 The name of the counter for automatic numbering.
9131 \begin_inset Newline newline
9139 \begin_inset Flex CharStyle:Code
9142 \begin_layout Plain Layout
9149 \begin_inset Flex CharStyle:Code
9152 \begin_layout Plain Layout
9159 In that case, the counter will be stepped each time the layout appears.
9161 \begin_inset Newline newline
9169 \begin_inset Flex CharStyle:Code
9172 \begin_layout Plain Layout
9179 \begin_inset Flex CharStyle:Code
9182 \begin_layout Plain Layout
9188 , though this case is a bit complicated.
9190 \begin_inset Quotes eld
9194 \begin_inset Flex CharStyle:Code
9197 \begin_layout Plain Layout
9204 \begin_inset Quotes erd
9208 Then the actual counters used are
9209 \begin_inset Flex CharStyle:Code
9212 \begin_layout Plain Layout
9219 \begin_inset Flex CharStyle:Code
9222 \begin_layout Plain Layout
9229 \begin_inset Flex CharStyle:Code
9232 \begin_layout Plain Layout
9239 \begin_inset Flex CharStyle:Code
9242 \begin_layout Plain Layout
9249 These counters must all be declared separately.
9250 \begin_inset Newline newline
9254 \begin_inset CommandInset ref
9256 reference "sub:Counters"
9260 for details on counters.
9263 \begin_layout Description
9264 \begin_inset Flex CharStyle:Code
9267 \begin_layout Plain Layout
9273 The font used for the label.
9275 \begin_inset space ~
9279 \begin_inset CommandInset ref
9281 reference "sub:Font-description"
9288 \begin_layout Description
9289 \begin_inset Flex CharStyle:Code
9292 \begin_layout Plain Layout
9298 Text that indicates how far a label should be indented.
9301 \begin_layout Description
9302 \begin_inset Flex CharStyle:Code
9305 \begin_layout Plain Layout
9312 \begin_inset Flex CharStyle:Code
9315 \begin_layout Plain Layout
9321 ] The horizontal space between the label and the text body.
9322 Only used for labels that are not above the text body.
9325 \begin_layout Description
9326 \begin_inset Flex CharStyle:Code
9329 \begin_layout Plain Layout
9336 \begin_inset Flex CharStyle:Code
9339 \begin_layout Plain Layout
9345 ] The string used for a label with a
9346 \begin_inset Flex CharStyle:Code
9349 \begin_layout Plain Layout
9357 \begin_inset Flex CharStyle:Code
9360 \begin_layout Plain Layout
9366 is set, this string can be contain the special formatting commands described
9368 \begin_inset CommandInset ref
9370 reference "sub:Counters"
9378 \begin_layout Plain Layout
9379 For the sake of backwards compatibility, the string
9380 \begin_inset Flex CharStyle:Code
9383 \begin_layout Plain Layout
9393 will be replaced by the expanded
9394 \begin_inset Flex CharStyle:Code
9397 \begin_layout Plain Layout
9404 \begin_inset Flex CharStyle:Code
9407 \begin_layout Plain Layout
9416 This feature is now obsolete and should be replaced by the mechanisms of
9418 \begin_inset CommandInset ref
9420 reference "sub:Counters"
9432 \begin_layout Description
9433 \begin_inset Flex CharStyle:Code
9436 \begin_layout Plain Layout
9443 \begin_inset Flex CharStyle:Code
9446 \begin_layout Plain Layout
9452 ] This is used inside the appendix instead of
9453 \begin_inset Flex CharStyle:Code
9456 \begin_layout Plain Layout
9464 \begin_inset Flex CharStyle:Code
9467 \begin_layout Plain Layout
9474 \begin_inset Flex CharStyle:Code
9477 \begin_layout Plain Layout
9486 \begin_layout Description
9487 \begin_inset Flex CharStyle:Code
9490 \begin_layout Plain Layout
9496 [FIXME] (Used only with XML-type formats.)
9499 \begin_layout Description
9500 \begin_inset Flex CharStyle:Code
9503 \begin_layout Plain Layout
9510 \begin_inset Flex CharStyle:Code
9513 \begin_layout Plain Layout
9518 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
9519 Enumerate, Itemize, Bibliography
9528 \begin_layout Itemize
9529 \begin_inset Flex CharStyle:Code
9532 \begin_layout Plain Layout
9538 means the label is the very first word (up to the first real blank).
9539 Use protected spaces (like
9540 \begin_inset space ~
9543 that one) if you want more than one word as the label.
9547 \begin_layout Itemize
9548 \begin_inset Flex CharStyle:Code
9551 \begin_layout Plain Layout
9557 means the label is simply whatever
9558 \begin_inset Flex CharStyle:Code
9561 \begin_layout Plain Layout
9568 Note that this really is `static'.
9571 \begin_layout Itemize
9572 \begin_inset Flex CharStyle:Code
9575 \begin_layout Plain Layout
9582 \begin_inset Flex CharStyle:Code
9585 \begin_layout Plain Layout
9586 Centered_Top_Environment
9591 are special cases of
9592 \begin_inset Flex CharStyle:Code
9595 \begin_layout Plain Layout
9602 The label will be printed above the paragraph, but only at the top of an
9603 environment or the top of a chain of paragraphs with this layout.
9604 This might be used with the
9605 \begin_inset Flex CharStyle:MenuItem
9608 \begin_layout Plain Layout
9614 layout, for example.
9617 \begin_layout Itemize
9618 \begin_inset Flex CharStyle:Code
9621 \begin_layout Plain Layout
9627 is a special case for the caption-labels
9628 \begin_inset Quotes eld
9632 \begin_inset Quotes erd
9636 \begin_inset Quotes eld
9640 \begin_inset Quotes erd
9645 \begin_inset Flex CharStyle:Code
9648 \begin_layout Plain Layout
9654 means the (hardcoded) label string depends on the kind of float: It is
9655 hardcoded to be `FloatType N', where N is the value of the counter associated
9659 \begin_layout Itemize
9661 \begin_inset Flex CharStyle:Code
9664 \begin_layout Plain Layout
9670 label type defines automatically numbered labels.
9672 \begin_inset Flex CharStyle:Code
9675 \begin_layout Plain Layout
9681 will be expanded to resolve any counter references it contains: For example,
9683 \begin_inset Quotes eld
9687 \begin_inset Flex CharStyle:Code
9690 \begin_layout Plain Layout
9701 \begin_inset Quotes erd
9706 \begin_inset CommandInset ref
9708 reference "sub:Counters"
9712 for more information on counters.
9715 \begin_layout Itemize
9716 \begin_inset Flex CharStyle:Code
9719 \begin_layout Plain Layout
9725 produces the usual sort of enumeration labels.
9726 At present, it is hardcoded to use Arabic numerals, lowercase letters,
9727 small Roman numerals, and uppercase letters for the four possible depths.
9730 \begin_layout Itemize
9731 \begin_inset Flex CharStyle:Code
9734 \begin_layout Plain Layout
9740 produces various bullets at the different levels.
9741 It is also hardcoded.
9744 \begin_layout Itemize
9745 \begin_inset Flex CharStyle:Code
9748 \begin_layout Plain Layout
9754 is used internally by LyX and should be used only with
9755 \begin_inset Flex CharStyle:Code
9758 \begin_layout Plain Layout
9759 LatexType BibEnvironment
9768 \begin_layout Description
9769 \begin_inset Flex CharStyle:Code
9772 \begin_layout Plain Layout
9779 \begin_inset Flex CharStyle:Code
9782 \begin_layout Plain Layout
9788 , but this preamble snippet occurs independently from the babel package,
9789 and only for the document language.
9791 \begin_inset Quotes eld
9795 \begin_inset Flex CharStyle:Code
9798 \begin_layout Plain Layout
9805 \begin_inset Quotes erd
9812 \begin_layout Standard
9813 If the style defines text that appears in the typeset document, it may use
9815 \begin_inset Flex CharStyle:Code
9818 \begin_layout Plain Layout
9825 \begin_inset Flex CharStyle:Code
9828 \begin_layout Plain Layout
9834 to support non-english and even multilanguage documents correctly.
9835 The following excerpt (from the
9836 \begin_inset Flex CharStyle:Code
9839 \begin_layout Plain Layout
9845 file) shows how this works:
9848 \begin_layout LyX-Code
9852 \begin_layout LyX-Code
9855 theoremstyle{remark}
9858 \begin_layout LyX-Code
9861 newtheorem{claim}[thm]{
9868 \begin_layout LyX-Code
9872 \begin_layout LyX-Code
9876 \begin_layout LyX-Code
9881 claimname}{_(Claim)}
9884 \begin_layout LyX-Code
9888 \begin_layout LyX-Code
9892 \begin_layout LyX-Code
9896 \begin_layout LyX-Code
9905 claimname}{_(Claim)}}
9908 \begin_layout LyX-Code
9912 \begin_layout Standard
9913 The key to correct translation of the user visible text is the definition
9915 \begin_inset Flex CharStyle:Code
9918 \begin_layout Plain Layout
9926 in the language preamble.
9927 This command holds the name of the theorem that will appear in the output.
9929 \begin_inset Flex CharStyle:Code
9932 \begin_layout Plain Layout
9938 then uses the commands offered by the babel package to redefine
9939 \begin_inset Flex CharStyle:Code
9942 \begin_layout Plain Layout
9950 for each used language in multilanguage documents.
9954 \begin_layout Description
9955 \begin_inset Flex CharStyle:Code
9958 \begin_layout Plain Layout
9964 The name of the corresponding LaTeX stuff.
9965 Either the environment or command name.
9968 \begin_layout Description
9969 \begin_inset Flex CharStyle:Code
9972 \begin_layout Plain Layout
9978 An optional parameter for the corresponding
9979 \begin_inset Flex CharStyle:Code
9982 \begin_layout Plain Layout
9989 This parameter cannot be changed from within LyX.
9992 \begin_layout Description
9993 \begin_inset Flex CharStyle:Code
9996 \begin_layout Plain Layout
10003 \begin_inset CommandInset label
10005 name "des:LatexType"
10010 \begin_inset Flex CharStyle:Code
10013 \begin_layout Plain Layout
10018 , Command, Environment, Item_Environment,
10024 \begin_inset Flex CharStyle:Code
10027 \begin_layout Plain Layout
10028 List_Environment, Bib_Environment
10033 ] How the layout should be translated into LaTeX.
10037 \begin_layout Plain Layout
10038 \begin_inset Flex CharStyle:Code
10041 \begin_layout Plain Layout
10047 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10048 Visit the SGML class files for specific examples.
10057 \begin_layout Itemize
10058 \begin_inset Flex CharStyle:Code
10061 \begin_layout Plain Layout
10067 means nothing special.
10071 \begin_layout Itemize
10072 \begin_inset Flex CharStyle:Code
10075 \begin_layout Plain Layout
10082 \begin_inset Flex CharStyle:Code
10085 \begin_layout Plain Layout
10092 {\SpecialChar \ldots{}
10101 \begin_layout Itemize
10102 \begin_inset Flex CharStyle:Code
10105 \begin_layout Plain Layout
10112 \begin_inset Flex CharStyle:Code
10115 \begin_layout Plain Layout
10122 }\SpecialChar \ldots{}
10138 \begin_layout Itemize
10139 \begin_inset Flex CharStyle:Code
10142 \begin_layout Plain Layout
10149 \begin_inset Flex CharStyle:Code
10152 \begin_layout Plain Layout
10159 \begin_inset Flex CharStyle:Code
10162 \begin_layout Plain Layout
10170 is generated for each paragraph of this environment.
10174 \begin_layout Itemize
10175 \begin_inset Flex CharStyle:Code
10178 \begin_layout Plain Layout
10185 \begin_inset Flex CharStyle:Code
10188 \begin_layout Plain Layout
10195 \begin_inset Flex CharStyle:Code
10198 \begin_layout Plain Layout
10204 is passed as an argument to the environment.
10206 \begin_inset Flex CharStyle:Code
10209 \begin_layout Plain Layout
10215 can be defined in the
10216 \begin_inset Flex CharStyle:MenuItem
10219 \begin_layout Plain Layout
10224 ayout\SpecialChar \menuseparator
10238 \begin_layout Standard
10239 Putting the last few things together, the LaTeX output will be either:
10242 \begin_layout LyX-Code
10245 latexname[latexparam]{\SpecialChar \ldots{}
10249 \begin_layout Standard
10253 \begin_layout LyX-Code
10256 begin{latexname}[latexparam] \SpecialChar \ldots{}
10262 \begin_layout Standard
10263 depending upon the LaTeX type.
10267 \begin_layout Description
10268 \begin_inset Flex CharStyle:Code
10271 \begin_layout Plain Layout
10278 \begin_inset Flex CharStyle:Code
10281 \begin_layout Plain Layout
10287 ] If you put layouts into environments, the leftmargins are not simply added,
10288 but added with a factor
10289 \begin_inset Formula $\frac{4}{depth+4}
10294 Note that this parameter is also used when the margin is defined as
10295 \begin_inset Flex CharStyle:Code
10298 \begin_layout Plain Layout
10305 \begin_inset Flex CharStyle:Code
10308 \begin_layout Plain Layout
10315 Then it is added to the manual or dynamic margin.
10317 \begin_inset Newline newline
10320 The argument is passed as a string.
10322 \begin_inset Quotes eld
10326 \begin_inset Flex CharStyle:Code
10329 \begin_layout Plain Layout
10336 \begin_inset Quotes erd
10339 means that the paragraph is indented with the width of
10340 \begin_inset Quotes eld
10344 \begin_inset Flex CharStyle:Code
10347 \begin_layout Plain Layout
10354 \begin_inset Quotes erd
10357 in the normal font.
10358 You can get a negative width by prefixing the string with
10359 \begin_inset Quotes eld
10363 \begin_inset Flex CharStyle:Code
10366 \begin_layout Plain Layout
10373 \begin_inset Quotes erd
10377 This way was chosen so that the look is the same with each used screen
10382 \begin_layout Description
10383 \begin_inset Flex CharStyle:Code
10386 \begin_layout Plain Layout
10393 \begin_inset Flex CharStyle:Code
10396 \begin_layout Plain Layout
10401 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10407 \begin_inset Newline newline
10410 The kind of margin that the layout has on the left side.
10412 \begin_inset Flex CharStyle:Code
10415 \begin_layout Plain Layout
10421 just means a fixed margin.
10423 \begin_inset Flex CharStyle:Code
10426 \begin_layout Plain Layout
10432 means that the left margin depends on the string entered in the
10433 \begin_inset Flex CharStyle:MenuItem
10436 \begin_layout Plain Layout
10437 Edit\SpecialChar \menuseparator
10439 \begin_inset space ~
10448 This is used to typeset nice lists without tabulators.
10450 \begin_inset Flex CharStyle:Code
10453 \begin_layout Plain Layout
10459 means that the margin depends on the size of the label.
10460 This is used for automatic enumerated headlines.
10461 It is obvious that the headline
10462 \begin_inset Quotes eld
10465 5.4.3.2.1 Very long headline
10466 \begin_inset Quotes erd
10469 must have a wider left margin (as wide as
10470 \begin_inset Quotes eld
10474 \begin_inset Quotes erd
10477 plus the space) than
10478 \begin_inset Quotes eld
10481 3.2 Very long headline
10482 \begin_inset Quotes erd
10486 \begin_inset Quotes eld
10490 \begin_inset Quotes erd
10493 are not able to do this.
10495 \begin_inset Flex CharStyle:Code
10498 \begin_layout Plain Layout
10504 is similar, but only the very first row of the paragraph is dynamic, while
10505 the others are static; this is used, for example, for descriptions.
10507 \begin_inset Flex CharStyle:Code
10510 \begin_layout Plain Layout
10516 means the margin is chosen in a way that the longest row of this paragraph
10517 fits to the right margin.
10518 This is used to typeset an address on the right edge of the page.
10521 \begin_layout Description
10522 \begin_inset Flex CharStyle:Code
10525 \begin_layout Plain Layout
10532 \begin_inset Flex CharStyle:Code
10535 \begin_layout Plain Layout
10544 \begin_inset Flex CharStyle:Code
10547 \begin_layout Plain Layout
10553 ] Whether fragile commands in this layout should be
10554 \begin_inset Flex CharStyle:Code
10557 \begin_layout Plain Layout
10570 whether this command should itself be protected.)
10573 \begin_layout Description
10574 \begin_inset Flex CharStyle:Code
10577 \begin_layout Plain Layout
10584 \begin_inset Flex CharStyle:Code
10587 \begin_layout Plain Layout
10594 \begin_inset Flex CharStyle:Code
10597 \begin_layout Plain Layout
10605 ] Whether newlines are translated into LaTeX newlines (
10606 \begin_inset Flex CharStyle:Code
10609 \begin_layout Plain Layout
10620 The translation can be switched off to allow more comfortable LaTeX editing
10624 \begin_layout Description
10625 \begin_inset Flex CharStyle:Code
10628 \begin_layout Plain Layout
10635 \begin_inset Flex CharStyle:Code
10638 \begin_layout Plain Layout
10645 \begin_inset Flex CharStyle:Code
10648 \begin_layout Plain Layout
10656 ] Whether the following Paragraph is allowed to indent its very first row.
10658 \begin_inset Flex CharStyle:Code
10661 \begin_layout Plain Layout
10667 means that it is not allowed to do so;
10668 \begin_inset Flex CharStyle:Code
10671 \begin_layout Plain Layout
10677 means it could do so if it wants to.
10680 \begin_layout Description
10681 \begin_inset Flex CharStyle:Code
10684 \begin_layout Plain Layout
10690 Name of a layout that has replaced this layout.
10691 This is used to rename a layout, while keeping backward compatibility.
10694 \begin_layout Description
10695 \begin_inset Flex CharStyle:Code
10698 \begin_layout Plain Layout
10705 \begin_inset Flex CharStyle:Code
10708 \begin_layout Plain Layout
10714 ] The number of optional arguments that can be used with this layout.
10715 This is useful for things like section headings, and only makes sense with
10719 \begin_layout Description
10720 \begin_inset Flex CharStyle:Code
10723 \begin_layout Plain Layout
10730 \begin_inset Flex CharStyle:Code
10733 \begin_layout Plain Layout
10739 ] The indent of the very first line of a paragraph.
10741 \begin_inset Flex CharStyle:Code
10744 \begin_layout Plain Layout
10750 will be fixed for a certain layout.
10751 The exception is Standard layout, since the indentation of a Standard layout
10752 paragraph can be prohibited with
10753 \begin_inset Flex CharStyle:Code
10756 \begin_layout Plain Layout
10763 Also, Standard layout paragraphs inside environments use the
10764 \begin_inset Flex CharStyle:Code
10767 \begin_layout Plain Layout
10773 of the environment, not their native one.
10774 For example, Standard paragraphs inside an enumeration are not indented.
10777 \begin_layout Description
10778 \begin_inset Flex CharStyle:Code
10781 \begin_layout Plain Layout
10788 \begin_inset Flex CharStyle:Code
10791 \begin_layout Plain Layout
10797 ] The vertical space between two paragraphs of this layout.
10800 \begin_layout Description
10801 \begin_inset Flex CharStyle:Code
10804 \begin_layout Plain Layout
10811 \begin_inset Flex CharStyle:Code
10814 \begin_layout Plain Layout
10820 ] LyX allows the user to choose either
10821 \begin_inset Quotes eld
10825 \begin_inset Quotes erd
10829 \begin_inset Quotes eld
10833 \begin_inset Quotes erd
10836 to typeset a document.
10838 \begin_inset Quotes eld
10842 \begin_inset Quotes erd
10845 is chosen, this value is completely ignored.
10847 \begin_inset Quotes eld
10851 \begin_inset Quotes erd
10854 is chosen, the parindent of a LaTeXtype
10855 \begin_inset Quotes eld
10859 \begin_inset Quotes erd
10862 layout is ignored and all paragraphs are separated by this parskip argument.
10863 The vertical space is calculated with
10864 \begin_inset Flex CharStyle:Code
10867 \begin_layout Plain Layout
10869 \begin_inset space ~
10878 \begin_inset Flex CharStyle:Code
10881 \begin_layout Plain Layout
10887 is the height of a row with the normal font.
10888 This way, the look stays the same with different screen fonts.
10891 \begin_layout Description
10892 \begin_inset Flex CharStyle:Code
10895 \begin_layout Plain Layout
10902 \begin_inset CommandInset label
10904 name "des:PathThru"
10911 \begin_inset Flex CharStyle:Code
10914 \begin_layout Plain Layout
10925 \begin_inset Flex CharStyle:Code
10928 \begin_layout Plain Layout
10934 ] Whether the contents of this paragraph should be output in raw form, meaning
10935 without special translations that LaTeX would require.
10938 \begin_layout Description
10939 \begin_inset Flex CharStyle:Code
10942 \begin_layout Plain Layout
10949 \begin_inset CommandInset label
10951 name "des:Preamble"
10955 Information to be included in the LaTeX preamble when this style is used.
10956 Used to define macros, load packages, etc., required by this particular
10959 \begin_inset Quotes eld
10963 \begin_inset Flex CharStyle:Code
10966 \begin_layout Plain Layout
10973 \begin_inset Quotes erd
10979 \begin_layout Description
10980 \begin_inset Flex CharStyle:Code
10983 \begin_layout Plain Layout
10990 \begin_inset Flex CharStyle:Code
10993 \begin_layout Plain Layout
11000 \begin_inset CommandInset label
11002 name "des:Requires"
11006 Whether the layout requires the feature
11007 \begin_inset Flex CharStyle:Code
11010 \begin_layout Plain Layout
11017 See the description of
11018 \begin_inset Flex CharStyle:Code
11021 \begin_layout Plain Layout
11028 \begin_inset CommandInset ref
11029 LatexCommand pageref
11030 reference "des:FreeSpacing"
11034 ) for information on `features'.
11038 \begin_layout Description
11039 \begin_inset Flex CharStyle:Code
11042 \begin_layout Plain Layout
11049 \begin_inset Flex CharStyle:Code
11052 \begin_layout Plain Layout
11059 \begin_inset Flex CharStyle:Code
11062 \begin_layout Plain Layout
11071 \begin_layout Description
11072 \begin_inset Flex CharStyle:Code
11075 \begin_layout Plain Layout
11082 \begin_inset Flex CharStyle:Code
11085 \begin_layout Plain Layout
11090 , onehalf, double, other
11099 ] This defines what the default spacing should be in the layout.
11101 \begin_inset Flex CharStyle:Code
11104 \begin_layout Plain Layout
11111 \begin_inset Flex CharStyle:Code
11114 \begin_layout Plain Layout
11121 \begin_inset Flex CharStyle:Code
11124 \begin_layout Plain Layout
11130 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
11131 If you specify the argument
11132 \begin_inset Flex CharStyle:Code
11135 \begin_layout Plain Layout
11141 , then you should also provide a numerical argument which will be the actual
11143 Note that, contrary to other parameters,
11144 \begin_inset Flex CharStyle:Code
11147 \begin_layout Plain Layout
11153 implies the generation of specific LaTeX code, using the package
11156 \begin_inset Flex CharStyle:Code
11159 \begin_layout Plain Layout
11168 \begin_layout Description
11169 \begin_inset Flex CharStyle:Code
11172 \begin_layout Plain Layout
11178 The font used for the text body .
11180 \begin_inset CommandInset ref
11182 reference "sub:Font-description"
11189 \begin_layout Description
11190 \begin_inset Flex CharStyle:Code
11193 \begin_layout Plain Layout
11201 The level of the style in the table of contents.
11202 This is used for automatic numbering of section headings.
11205 \begin_layout Description
11206 \begin_inset Flex CharStyle:Code
11209 \begin_layout Plain Layout
11216 \begin_inset Flex CharStyle:Code
11219 \begin_layout Plain Layout
11225 ] The vertical space with which the very first of a chain of paragraphs
11226 with this layout is separated from the previous paragraph.
11227 If the previous paragraph has another layout, the separations are not simply
11228 added, but the maximum is taken.
11231 \begin_layout Subsection
11233 \begin_inset CommandInset label
11242 \begin_layout Standard
11243 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11244 define the floats (
11245 \begin_inset Flex CharStyle:MenuItem
11248 \begin_layout Plain Layout
11255 \begin_inset Flex CharStyle:MenuItem
11258 \begin_layout Plain Layout
11264 , \SpecialChar \ldots{}
11265 ) in the text class itself.
11266 Standard floats are included in the file
11267 \begin_inset Flex CharStyle:Code
11270 \begin_layout Plain Layout
11276 , so you may have to do no more than add
11279 \begin_layout LyX-Code
11280 Input stdfloats.inc
11283 \begin_layout Standard
11284 to your layout file.
11285 If you want to implement a text class that proposes some other float types
11286 (like the AGU class bundled with LyX), the information below will hopefully
11290 \begin_layout Description
11291 \begin_inset Flex CharStyle:Code
11294 \begin_layout Plain Layout
11301 \begin_inset Flex CharStyle:Code
11304 \begin_layout Plain Layout
11311 \begin_inset Quotes erd
11315 \begin_inset Quotes erd
11318 ] The file name extension of an auxiliary file for the list of figures (or
11320 LaTeX writes the captions to this file.
11323 \begin_layout Description
11324 \begin_inset Flex CharStyle:Code
11327 \begin_layout Plain Layout
11334 \begin_inset Flex CharStyle:Code
11337 \begin_layout Plain Layout
11344 \begin_inset Quotes erd
11348 \begin_inset Quotes erd
11351 ] The string that will be used in the menus and also for the caption.
11352 This is translated to the current language if babel is used.
11355 \begin_layout Description
11356 \begin_inset Flex CharStyle:Code
11359 \begin_layout Plain Layout
11366 \begin_inset Flex CharStyle:Code
11369 \begin_layout Plain Layout
11378 \begin_inset Flex CharStyle:Code
11381 \begin_layout Plain Layout
11388 \begin_inset Flex CharStyle:Code
11391 \begin_layout Plain Layout
11397 if the float is already defined by the LaTeX document class.
11399 \begin_inset Flex CharStyle:Code
11402 \begin_layout Plain Layout
11408 , the float will be defined using the LaTeX package
11409 \begin_inset Flex CharStyle:Code
11412 \begin_layout Plain Layout
11421 \begin_layout Description
11422 \begin_inset Flex CharStyle:Code
11425 \begin_layout Plain Layout
11432 \begin_inset Flex CharStyle:Code
11435 \begin_layout Plain Layout
11442 \begin_inset Quotes erd
11446 \begin_inset Quotes erd
11449 ] The heading used for the list of floats.
11450 This is translated to the document language.
11453 \begin_layout Description
11454 \begin_inset Flex CharStyle:Code
11457 \begin_layout Plain Layout
11464 \begin_inset Flex CharStyle:Code
11467 \begin_layout Plain Layout
11474 \begin_inset Quotes erd
11478 \begin_inset Quotes erd
11481 ] This (optional) argument determines whether floats of this class will
11482 be numbered within some sectional unit of the document.
11483 For example, if within is equal to
11484 \begin_inset Flex CharStyle:Code
11487 \begin_layout Plain Layout
11493 , the floats will be numbered within chapters.
11497 \begin_layout Description
11498 \begin_inset Flex CharStyle:Code
11501 \begin_layout Plain Layout
11508 \begin_inset Flex CharStyle:Code
11511 \begin_layout Plain Layout
11518 \begin_inset Quotes erd
11522 \begin_inset Quotes erd
11525 ] The default placement for the given class of floats.
11526 The string should be as in standard LaTeX:
11527 \begin_inset Flex CharStyle:Code
11530 \begin_layout Plain Layout
11537 \begin_inset Flex CharStyle:Code
11540 \begin_layout Plain Layout
11547 \begin_inset Flex CharStyle:Code
11550 \begin_layout Plain Layout
11557 \begin_inset Flex CharStyle:Code
11560 \begin_layout Plain Layout
11566 for top, bottom, page, and here, respectively.
11570 \begin_layout Plain Layout
11571 Note that the order of these letters in the string is irrelevant, like in
11577 On top of that there is a new type,
11578 \begin_inset Flex CharStyle:Code
11581 \begin_layout Plain Layout
11587 , which does not really correspond to a float, since it means: put it
11588 \begin_inset Quotes eld
11592 \begin_inset Quotes erd
11596 Note however that the
11597 \begin_inset Flex CharStyle:Code
11600 \begin_layout Plain Layout
11606 specifier is special and, because of implementation details, cannot be
11607 used in non-built in float types.
11608 If you do not understand what this means, just use
11609 \begin_inset Quotes eld
11613 \begin_inset Flex CharStyle:Code
11616 \begin_layout Plain Layout
11623 \begin_inset Quotes erd
11629 \begin_layout Description
11630 \begin_inset Flex CharStyle:Code
11633 \begin_layout Plain Layout
11640 \begin_inset Flex CharStyle:Code
11643 \begin_layout Plain Layout
11650 \begin_inset Quotes erd
11654 \begin_inset Quotes erd
11657 ] The style used when defining the float using
11658 \begin_inset Flex CharStyle:Code
11661 \begin_layout Plain Layout
11672 \begin_layout Description
11673 \begin_inset Flex CharStyle:Code
11676 \begin_layout Plain Layout
11683 \begin_inset Flex CharStyle:Code
11686 \begin_layout Plain Layout
11693 \begin_inset Quotes erd
11697 \begin_inset Quotes erd
11701 \begin_inset Quotes eld
11705 \begin_inset Quotes erd
11708 of the new class of floats, like program or algorithm.
11709 After the appropriate
11710 \begin_inset Flex CharStyle:Code
11713 \begin_layout Plain Layout
11722 \begin_inset Flex CharStyle:Code
11725 \begin_layout Plain Layout
11734 \begin_inset Flex CharStyle:Code
11737 \begin_layout Plain Layout
11748 \begin_layout Standard
11749 Note that defining a float with type
11750 \begin_inset Flex CharStyle:Code
11753 \begin_layout Plain Layout
11761 automatically defines the corresponding counter with name
11762 \begin_inset Flex CharStyle:Code
11765 \begin_layout Plain Layout
11776 \begin_layout Subsection
11777 Flex insets and InsetLayout
11778 \begin_inset CommandInset label
11780 name "sub:Flex-insets-and"
11787 \begin_layout Standard
11788 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11789 these are called Flex insets.
11793 \begin_layout Standard
11794 Flex insets come in three different kinds:
11797 \begin_layout Itemize
11799 \begin_inset Flex CharStyle:Code
11802 \begin_layout Plain Layout
11808 ): These define semantic markup corresponding to such LaTeX commands as
11810 \begin_inset Flex CharStyle:Code
11813 \begin_layout Plain Layout
11822 \begin_inset Flex CharStyle:Code
11825 \begin_layout Plain Layout
11836 \begin_layout Itemize
11838 \begin_inset Flex CharStyle:Code
11841 \begin_layout Plain Layout
11847 ): These can be used to define custom collapsible insets, similar to TeX
11848 code, footnote, and the like.
11849 An obvious example is an endnote inset, which is defined in the
11850 \begin_inset Flex CharStyle:Code
11853 \begin_layout Plain Layout
11862 \begin_layout Itemize
11864 \begin_inset Flex CharStyle:Code
11867 \begin_layout Plain Layout
11873 ): For use with DocBook classes.
11876 \begin_layout Standard
11877 Flex insets are defined using the
11878 \begin_inset Flex CharStyle:Code
11881 \begin_layout Plain Layout
11887 tag, which shall be explained in a moment.
11890 \begin_layout Standard
11892 \begin_inset Flex CharStyle:Code
11895 \begin_layout Plain Layout
11901 tag also serves another function: It can be used to customize the general
11902 layout of many different types of insets.
11904 \begin_inset Flex CharStyle:Code
11907 \begin_layout Plain Layout
11913 can be used to customize the layout parameters for footnotes, marginal
11914 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11915 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11916 define Flex insets.
11919 \begin_layout Standard
11921 \begin_inset Flex CharStyle:Code
11924 \begin_layout Plain Layout
11930 definition must begin with a line of the form:
11933 \begin_layout LyX-Code
11937 \begin_layout Standard
11939 \begin_inset Flex CharStyle:Code
11942 \begin_layout Plain Layout
11948 indicates the inset whose layout is being defined, and here there are two
11952 \begin_layout Enumerate
11953 The layout for a pre-existing inset is being modified.
11954 In this case, can be
11955 \begin_inset Flex CharStyle:Code
11958 \begin_layout Plain Layout
11964 any one of the following:
11965 \begin_inset Flex CharStyle:Code
11968 \begin_layout Plain Layout
11975 \begin_inset Flex CharStyle:Code
11978 \begin_layout Plain Layout
11985 \begin_inset Flex CharStyle:Code
11988 \begin_layout Plain Layout
11995 \begin_inset Flex CharStyle:Code
11998 \begin_layout Plain Layout
12005 \begin_inset Flex CharStyle:Code
12008 \begin_layout Plain Layout
12015 \begin_inset Flex CharStyle:Code
12018 \begin_layout Plain Layout
12025 \begin_inset Flex CharStyle:Code
12028 \begin_layout Plain Layout
12035 \begin_inset Flex CharStyle:Code
12038 \begin_layout Plain Layout
12045 \begin_inset Flex CharStyle:Code
12048 \begin_layout Plain Layout
12055 \begin_inset Flex CharStyle:Code
12058 \begin_layout Plain Layout
12065 \begin_inset Flex CharStyle:Code
12068 \begin_layout Plain Layout
12075 \begin_inset Flex CharStyle:Code
12078 \begin_layout Plain Layout
12085 \begin_inset Flex CharStyle:Code
12088 \begin_layout Plain Layout
12095 \begin_inset Flex CharStyle:Code
12098 \begin_layout Plain Layout
12105 \begin_inset Flex CharStyle:Code
12108 \begin_layout Plain Layout
12115 \begin_inset Flex CharStyle:Code
12118 \begin_layout Plain Layout
12125 \begin_inset Flex CharStyle:Code
12128 \begin_layout Plain Layout
12135 \begin_inset Flex CharStyle:Code
12138 \begin_layout Plain Layout
12145 \begin_inset Flex CharStyle:Code
12148 \begin_layout Plain Layout
12155 \begin_inset Flex CharStyle:Code
12158 \begin_layout Plain Layout
12167 \begin_layout Enumerate
12168 The layout for a Flex inset is being defined.
12170 \begin_inset Flex CharStyle:Code
12173 \begin_layout Plain Layout
12179 can be any valid identifier not used by a pre-existing inset.
12180 Note that the definition of a flex inset must
12185 \begin_inset Flex CharStyle:Code
12188 \begin_layout Plain Layout
12197 \begin_layout Standard
12199 \begin_inset Flex CharStyle:Code
12202 \begin_layout Plain Layout
12208 definition can contain the following entries:
12211 \begin_layout Description
12212 \begin_inset Flex CharStyle:Code
12215 \begin_layout Plain Layout
12221 The color for the inset's background.
12222 The valid colors are defined in
12223 \begin_inset Flex CharStyle:Code
12226 \begin_layout Plain Layout
12235 \begin_layout Description
12236 \begin_inset Flex CharStyle:Code
12239 \begin_layout Plain Layout
12245 As with paragraph styles (see page
12246 \begin_inset CommandInset ref
12248 reference "des:CopyStyle"
12255 \begin_layout Description
12256 \begin_inset Flex CharStyle:Code
12259 \begin_layout Plain Layout
12266 \begin_inset Flex CharStyle:Code
12269 \begin_layout Plain Layout
12278 \begin_inset Flex CharStyle:Code
12281 \begin_layout Plain Layout
12287 ] Indicates whether the user may employ the Paragraph Settings dialog to
12288 customize the paragraph.
12291 \begin_layout Description
12292 \begin_inset Flex CharStyle:Code
12295 \begin_layout Plain Layout
12302 \begin_inset Flex CharStyle:Code
12305 \begin_layout Plain Layout
12312 \begin_inset Flex CharStyle:Code
12315 \begin_layout Plain Layout
12322 \begin_inset Flex CharStyle:Code
12325 \begin_layout Plain Layout
12331 , describing the rendering style used for the inset's frame and buttons.
12332 Footnotes generally use
12333 \begin_inset Flex CharStyle:Code
12336 \begin_layout Plain Layout
12342 , ERT insets generally
12343 \begin_inset Flex CharStyle:Code
12346 \begin_layout Plain Layout
12352 , and character styles
12353 \begin_inset Flex CharStyle:Code
12356 \begin_layout Plain Layout
12365 \begin_layout Description
12366 \begin_inset Flex CharStyle:Code
12369 \begin_layout Plain Layout
12375 Required at the end of the InsetLayout declarations.
12378 \begin_layout Description
12379 \begin_inset Flex CharStyle:Code
12382 \begin_layout Plain Layout
12388 The font used for both the text body
12394 \begin_inset space ~
12398 \begin_inset CommandInset ref
12400 reference "sub:Font-description"
12405 Note that defining this font automatically defines the
12406 \begin_inset Flex CharStyle:Code
12409 \begin_layout Plain Layout
12415 to the same value, so define this first and define
12416 \begin_inset Flex CharStyle:Code
12419 \begin_layout Plain Layout
12425 later if you want them to be different.
12428 \begin_layout Description
12429 \begin_inset Flex CharStyle:Code
12432 \begin_layout Plain Layout
12439 \begin_inset Quotes eld
12443 \begin_inset Quotes erd
12446 language, leading to Left-to-Right (latin) output, e.
12447 \begin_inset space \thinspace{}
12451 \begin_inset space \space{}
12454 in TeX code or URL.
12458 \begin_layout Description
12459 \begin_inset Flex CharStyle:Code
12462 \begin_layout Plain Layout
12469 \begin_inset Flex CharStyle:Code
12472 \begin_layout Plain Layout
12481 \begin_inset Flex CharStyle:Code
12484 \begin_layout Plain Layout
12490 ] Indicates whether the PlainLayout should be used or, instead, the user
12491 can change the paragraph style used in the inset.
12494 \begin_layout Description
12495 \begin_inset Flex CharStyle:Code
12498 \begin_layout Plain Layout
12504 As with paragraph styles (see page
12505 \begin_inset CommandInset ref
12506 LatexCommand pageref
12507 reference "des:FreeSpacing"
12514 \begin_layout Description
12515 \begin_inset Flex CharStyle:Code
12518 \begin_layout Plain Layout
12525 \begin_inset Flex CharStyle:Code
12528 \begin_layout Plain Layout
12537 \begin_inset Flex CharStyle:Code
12540 \begin_layout Plain Layout
12546 ] Whether to include the contents of this inset in the strings generated
12547 for the `Outline' pane.
12548 One would not, for example, want the content of a footnote in a section
12549 header to be included in the TOC displayed in the outline, but one would
12550 normally want the content of a character style displayed.
12551 Default is false: not to include.
12554 \begin_layout Description
12555 \begin_inset Flex CharStyle:Code
12558 \begin_layout Plain Layout
12564 As with paragraph styles (see page
12565 \begin_inset CommandInset ref
12566 LatexCommand pageref
12567 reference "des:KeepEmpty"
12574 \begin_layout Description
12575 \begin_inset Flex CharStyle:Code
12578 \begin_layout Plain Layout
12584 The font used for the label.
12586 \begin_inset space ~
12590 \begin_inset CommandInset ref
12592 reference "sub:Font-description"
12597 Note that this definition can never appear before
12598 \begin_inset Flex CharStyle:Code
12601 \begin_layout Plain Layout
12607 , lest it be ineffective.
12610 \begin_layout Description
12611 \begin_inset Flex CharStyle:Code
12614 \begin_layout Plain Layout
12620 What will be displayed on the button or elsewhere as the inset label.
12621 Some inset types (TeX code and Branch) modify this label on the fly.
12624 \begin_layout Description
12625 \begin_inset Flex CharStyle:Code
12628 \begin_layout Plain Layout
12634 The name of the corresponding LaTeX stuff.
12635 Either the environment or command name.
12638 \begin_layout Description
12639 \begin_inset Flex CharStyle:Code
12642 \begin_layout Plain Layout
12648 The optional parameter for the corresponding
12649 \begin_inset Flex CharStyle:Code
12652 \begin_layout Plain Layout
12658 stuff, including possible bracket pairs like
12659 \begin_inset Flex CharStyle:Code
12662 \begin_layout Plain Layout
12669 This parameter cannot be changed from within LyX.
12672 \begin_layout Description
12673 \begin_inset Flex CharStyle:Code
12676 \begin_layout Plain Layout
12682 As with paragraph styles (see page
12683 \begin_inset CommandInset ref
12684 LatexCommand pageref
12685 reference "des:LatexType"
12692 \begin_layout Description
12693 \begin_inset Flex CharStyle:Code
12696 \begin_layout Plain Layout
12703 \begin_inset Flex CharStyle:Code
12706 \begin_layout Plain Layout
12713 \begin_inset Flex CharStyle:Code
12716 \begin_layout Plain Layout
12723 \begin_inset Flex CharStyle:Code
12726 \begin_layout Plain Layout
12733 \begin_inset Flex CharStyle:Code
12736 \begin_layout Plain Layout
12742 (indicating a dummy definition ending definitions of charstyles, etc).
12743 This entry is required in and is only meaningful for Flex insets.
12744 Among other things, it determines on which menu this inset will appear.
12747 \begin_layout Description
12748 \begin_inset Flex CharStyle:Code
12751 \begin_layout Plain Layout
12758 \begin_inset Flex CharStyle:Code
12761 \begin_layout Plain Layout
12770 \begin_inset Flex CharStyle:Code
12773 \begin_layout Plain Layout
12779 ] Whether multiple paragraphs are permitted in this inset.
12780 This will also set CustomPars to the same value and ForcePlain to the opposite
12782 These can be reset to other values, if they are used
12789 \begin_layout Description
12790 \begin_inset Flex CharStyle:Code
12793 \begin_layout Plain Layout
12800 \begin_inset Flex CharStyle:Code
12803 \begin_layout Plain Layout
12812 \begin_inset Flex CharStyle:Code
12815 \begin_layout Plain Layout
12821 ] Whether fragile commands in this layout should be
12822 \begin_inset Flex CharStyle:Code
12825 \begin_layout Plain Layout
12838 whether the command should itself be protected.)
12841 \begin_layout Description
12842 \begin_inset Flex CharStyle:Code
12845 \begin_layout Plain Layout
12852 \begin_inset Flex CharStyle:Code
12855 \begin_layout Plain Layout
12864 \begin_inset Flex CharStyle:Code
12867 \begin_layout Plain Layout
12873 ] As with paragraph styles (see page
12874 \begin_inset CommandInset ref
12876 reference "des:PathThru"
12883 \begin_layout Description
12884 \begin_inset Flex CharStyle:Code
12887 \begin_layout Plain Layout
12893 As with paragraph styles (see page
12894 \begin_inset CommandInset ref
12895 LatexCommand pageref
12896 reference "des:Preamble"
12903 \begin_layout Description
12904 \begin_inset Flex CharStyle:Code
12907 \begin_layout Plain Layout
12914 \begin_inset Flex CharStyle:Code
12917 \begin_layout Plain Layout
12923 ] As with paragraph styles (see page
12924 \begin_inset CommandInset ref
12925 LatexCommand pageref
12926 reference "des:Requires"
12933 \begin_layout Subsection
12935 \begin_inset CommandInset label
12937 name "sub:Counters"
12944 \begin_layout Standard
12945 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12947 \begin_inset Flex CharStyle:MenuItem
12950 \begin_layout Plain Layout
12957 \begin_inset Flex CharStyle:MenuItem
12960 \begin_layout Plain Layout
12966 , \SpecialChar \ldots{}
12967 ) in the text class itself.
12968 The standard counters are defined in the file
12969 \begin_inset Flex CharStyle:Code
12972 \begin_layout Plain Layout
12978 , so you may have to do no more than add
12981 \begin_layout LyX-Code
12982 Input stdcounters.inc
12985 \begin_layout Standard
12986 to your layout file to get them to work.
12987 But if you want to define custom counters, then you can do so.
12988 The counter declaration must begin with:
12991 \begin_layout LyX-Code
12995 \begin_layout Standard
12996 where of course `name' is replaced by the name of the counter.
12997 And it must end with
12998 \begin_inset Quotes eld
13002 \begin_inset Flex CharStyle:Code
13005 \begin_layout Plain Layout
13012 \begin_inset Quotes erd
13016 The following parameters can also be used:
13019 \begin_layout Description
13020 \begin_inset Flex CharStyle:Code
13023 \begin_layout Plain Layout
13024 LabelString [string=""]
13029 when this is defined, this string defines how the counter is displayed.
13030 Setting this value sets
13031 \begin_inset Flex CharStyle:Code
13034 \begin_layout Plain Layout
13035 LabelStringAppendix
13041 The following special constructs can be used in the string:
13045 \begin_layout Itemize
13046 \begin_inset Flex CharStyle:Code
13049 \begin_layout Plain Layout
13057 will be replaced by the expansion of the
13058 \begin_inset Flex CharStyle:Code
13061 \begin_layout Plain Layout
13068 \begin_inset Flex CharStyle:Code
13071 \begin_layout Plain Layout
13072 LabelStringAppendix
13078 \begin_inset Flex CharStyle:Code
13081 \begin_layout Plain Layout
13091 \begin_layout Itemize
13092 counter values can be expressed using LaTeX-like macros
13093 \begin_inset Flex CharStyle:Code
13096 \begin_layout Plain Layout
13113 \begin_inset Flex CharStyle:Code
13116 \begin_layout Plain Layout
13128 \begin_layout Plain Layout
13138 Actually, the situation is a bit more complicated: any
13157 other than those described below will produce arabic numerals.
13158 It would not be surprising to see this change in the future.
13164 \begin_inset Flex CharStyle:Code
13167 \begin_layout Plain Layout
13173 : 1, 2, 3,\SpecialChar \ldots{}
13175 \begin_inset Flex CharStyle:Code
13178 \begin_layout Plain Layout
13184 for lower-case letters: a, b, c, \SpecialChar \ldots{}
13186 \begin_inset Flex CharStyle:Code
13189 \begin_layout Plain Layout
13195 for upper-case letters: A, B, C, \SpecialChar \ldots{}
13197 \begin_inset Flex CharStyle:Code
13200 \begin_layout Plain Layout
13206 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
13208 \begin_inset Flex CharStyle:Code
13211 \begin_layout Plain Layout
13217 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
13219 \begin_inset Flex CharStyle:Code
13222 \begin_layout Plain Layout
13228 for hebrew numerals.
13232 \begin_layout Standard
13233 If LabelString is not defined, a default value is constructed as follows:
13234 if the counter has a master counter
13235 \begin_inset Flex CharStyle:Code
13238 \begin_layout Plain Layout
13245 \begin_inset Flex CharStyle:Code
13248 \begin_layout Plain Layout
13255 \begin_inset Flex CharStyle:Code
13258 \begin_layout Plain Layout
13268 is used; otherwise the string
13269 \begin_inset Flex CharStyle:Code
13272 \begin_layout Plain Layout
13283 \begin_layout Description
13284 \begin_inset Flex CharStyle:Code
13287 \begin_layout Plain Layout
13288 LabelStringAppendix [string=""]
13294 \begin_inset Flex CharStyle:Code
13297 \begin_layout Plain Layout
13303 , but for use in the Appendix.
13306 \begin_layout Description
13307 \begin_inset Flex CharStyle:Code
13310 \begin_layout Plain Layout
13317 \begin_inset Flex CharStyle:Code
13320 \begin_layout Plain Layout
13327 \begin_inset Quotes erd
13331 \begin_inset Quotes erd
13334 ] If this is set to the name of another counter, the present counter will
13335 be reset every time the other one is increased.
13337 \begin_inset Flex CharStyle:Code
13340 \begin_layout Plain Layout
13347 \begin_inset Flex CharStyle:Code
13350 \begin_layout Plain Layout
13359 \begin_layout Subsection
13361 \begin_inset CommandInset label
13363 name "sub:Font-description"
13370 \begin_layout Standard
13371 A font description looks like this:
13374 \begin_layout LyX-Code
13384 \begin_layout LyX-Code
13388 \begin_layout LyX-Code
13392 \begin_layout Standard
13393 The following commands are available:
13396 \begin_layout Description
13397 \begin_inset Flex CharStyle:Code
13400 \begin_layout Plain Layout
13407 \begin_inset Flex CharStyle:Code
13410 \begin_layout Plain Layout
13419 \begin_inset Flex CharStyle:Code
13422 \begin_layout Plain Layout
13429 \begin_inset Flex CharStyle:Code
13432 \begin_layout Plain Layout
13439 \begin_inset Flex CharStyle:Code
13442 \begin_layout Plain Layout
13449 \begin_inset Flex CharStyle:Code
13452 \begin_layout Plain Layout
13459 \begin_inset Flex CharStyle:Code
13462 \begin_layout Plain Layout
13469 \begin_inset Flex CharStyle:Code
13472 \begin_layout Plain Layout
13479 \begin_inset Flex CharStyle:Code
13482 \begin_layout Plain Layout
13489 \begin_inset Flex CharStyle:Code
13492 \begin_layout Plain Layout
13501 \begin_layout Description
13502 \begin_inset Flex CharStyle:Code
13505 \begin_layout Plain Layout
13514 \begin_inset Flex CharStyle:Code
13517 \begin_layout Plain Layout
13528 \begin_inset Flex CharStyle:Code
13531 \begin_layout Plain Layout
13538 \begin_inset Flex CharStyle:Code
13541 \begin_layout Plain Layout
13550 \begin_layout Description
13551 \begin_inset Flex CharStyle:Code
13554 \begin_layout Plain Layout
13561 \begin_inset Flex CharStyle:Code
13564 \begin_layout Plain Layout
13570 ] Valid argument are:
13571 \begin_inset Flex CharStyle:Code
13574 \begin_layout Plain Layout
13581 \begin_inset Flex CharStyle:Code
13584 \begin_layout Plain Layout
13591 \begin_inset Flex CharStyle:Code
13594 \begin_layout Plain Layout
13601 \begin_inset Flex CharStyle:Code
13604 \begin_layout Plain Layout
13611 \begin_inset Flex CharStyle:Code
13614 \begin_layout Plain Layout
13621 \begin_inset Flex CharStyle:Code
13624 \begin_layout Plain Layout
13631 Each of these turns on or off the corresponding attribute.
13634 \begin_layout Description
13635 \begin_inset Flex CharStyle:Code
13638 \begin_layout Plain Layout
13647 \begin_inset Flex CharStyle:Code
13650 \begin_layout Plain Layout
13661 \begin_inset Flex CharStyle:Code
13664 \begin_layout Plain Layout
13673 \begin_layout Description
13674 \begin_inset Flex CharStyle:Code
13677 \begin_layout Plain Layout
13686 \begin_inset Flex CharStyle:Code
13689 \begin_layout Plain Layout
13700 \begin_inset Flex CharStyle:Code
13703 \begin_layout Plain Layout
13710 \begin_inset Flex CharStyle:Code
13713 \begin_layout Plain Layout
13720 \begin_inset Flex CharStyle:Code
13723 \begin_layout Plain Layout
13732 \begin_layout Description
13733 \begin_inset Flex CharStyle:Code
13736 \begin_layout Plain Layout
13743 \begin_inset Flex CharStyle:Code
13746 \begin_layout Plain Layout
13753 \begin_inset Flex CharStyle:Code
13756 \begin_layout Plain Layout
13763 \begin_inset Flex CharStyle:Code
13766 \begin_layout Plain Layout
13775 \begin_inset Flex CharStyle:Code
13778 \begin_layout Plain Layout
13785 \begin_inset Flex CharStyle:Code
13788 \begin_layout Plain Layout
13795 \begin_inset Flex CharStyle:Code
13798 \begin_layout Plain Layout
13805 \begin_inset Flex CharStyle:Code
13808 \begin_layout Plain Layout
13815 \begin_inset Flex CharStyle:Code
13818 \begin_layout Plain Layout
13827 \begin_layout Subsection
13828 Upgrading old layout files
13831 \begin_layout Standard
13832 The file format of layout files changes from time to time, so old layout
13833 files need to be converted.
13834 This process has been automated since LyX 1.4.0: If LyX reads an old format
13835 layout file it will call the conversion tool
13836 \begin_inset Flex CharStyle:Code
13839 \begin_layout Plain Layout
13840 LyXDir/scripts/layout2layout.py
13845 and convert it to a temporary file in current format.
13846 The original file is left untouched.
13847 If you want to convert the layout file permanently, just call the converter
13851 \begin_layout LyX-Code
13852 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13855 \begin_layout Standard
13856 (You need to replace
13857 \begin_inset Flex CharStyle:Code
13860 \begin_layout Plain Layout
13866 with the name of your LyX system directory, unless you happen to have defined
13867 such an environment variable.) Then copy
13868 \begin_inset Flex CharStyle:Code
13871 \begin_layout Plain Layout
13878 \begin_inset Flex CharStyle:Code
13881 \begin_layout Plain Layout
13890 \begin_layout Standard
13891 The automatic conversion only handles syntax changes.
13892 It cannot handle the case where the contents of included files was changed,
13893 so these will have to be converted separately.
13896 \begin_layout Section
13898 \begin_inset CommandInset label
13900 name "sec:Creating-Templates"
13907 \begin_layout Standard
13908 Templates are created just like usual documents.
13909 The only difference is that usual documents contain all possible settings,
13910 including the font scheme and the paper size.
13911 Usually a user doesn't want a template to overwrite his defaults in these
13913 For that reason, the designer of a template should remove the corresponding
13915 \begin_inset Flex CharStyle:Code
13918 \begin_layout Plain Layout
13927 \begin_inset Flex CharStyle:Code
13930 \begin_layout Plain Layout
13938 from the template LyX file.
13939 This can be done with any simple text-editor, for example
13940 \begin_inset Flex CharStyle:Code
13943 \begin_layout Plain Layout
13950 \begin_inset Flex CharStyle:Code
13953 \begin_layout Plain Layout
13963 \begin_layout Standard
13964 Put the edited template files you create in
13965 \begin_inset Flex CharStyle:Code
13968 \begin_layout Plain Layout
13974 , copy the ones you use from the global template directory in
13975 \begin_inset Flex CharStyle:Code
13978 \begin_layout Plain Layout
13984 to the same place, and redefine the template path in the
13985 \begin_inset Flex CharStyle:MenuItem
13988 \begin_layout Plain Layout
13989 Tools\SpecialChar \menuseparator
13990 Preferences\SpecialChar \menuseparator
13999 \begin_layout Standard
14000 Note that there is a template which has a particular meaning:
14001 \begin_inset Flex CharStyle:Code
14004 \begin_layout Plain Layout
14011 This template is loaded every time you create a new document with
14012 \begin_inset Flex CharStyle:MenuItem
14015 \begin_layout Plain Layout
14016 File\SpecialChar \menuseparator
14022 in order to provide useful defaults.
14023 To create this template from inside LyX, all you have to do is to open
14024 a document with the correct settings, and use the
14025 \begin_inset Flex CharStyle:MenuItem
14028 \begin_layout Plain Layout
14029 Save as Document Defaults
14037 \begin_layout Chapter
14038 Including External Material
14041 \begin_layout Standard
14042 \begin_inset Box Shadowbox
14051 height_special "totalheight"
14054 \begin_layout Plain Layout
14055 WARNING: This portion of the documentation has not been updated for some
14057 We certainly hope that it is still accurate, but there are no guarantees.
14065 \begin_layout Standard
14066 The use of material from sources external to LyX is covered in detail in
14072 This part of the manual covers what needs to happen behind the scenes for
14073 new sorts of material to be included.
14076 \begin_layout Section
14080 \begin_layout Standard
14081 The external material feature is based on the concept of a
14086 A template is a specification of how LyX should interface with a certain
14088 As bundled, LyX comes with predefined templates for Xfig figures, various
14089 raster format images, chess diagrams, and LilyPond music notation.
14090 You can check the actual list by using the menu
14091 \begin_inset Flex CharStyle:MenuItem
14094 \begin_layout Plain Layout
14095 Insert\SpecialChar \menuseparator
14096 File\SpecialChar \menuseparator
14103 Furthermore, it is possible to roll your own template to support a specific
14105 Later we'll describe in more detail what is involved, and hopefully you
14106 will submit all the templates you create so we can include them in a later
14110 \begin_layout Standard
14111 Another basic idea of the external material feature is to distinguish between
14112 the original file that serves as a base for final material and the produced
14113 file that is included in your exported or printed document.
14114 For example, consider the case of a figure produced with
14115 \begin_inset Flex CharStyle:Code
14118 \begin_layout Plain Layout
14125 The Xfig application itself works on an original file with the
14126 \begin_inset Flex CharStyle:Code
14129 \begin_layout Plain Layout
14136 Within Xfig, you create and change your figure, and when you are done,
14138 \begin_inset Flex CharStyle:Code
14141 \begin_layout Plain Layout
14148 When you want to include the figure in your document, you invoke
14149 \begin_inset Flex CharStyle:Code
14152 \begin_layout Plain Layout
14158 in order to create a PostScript file that can readily be included in your
14161 \begin_inset Flex CharStyle:Code
14164 \begin_layout Plain Layout
14170 file is the original file, and the PostScript file is the produced file.
14173 \begin_layout Standard
14174 This distinction is important in order to allow updating of the material
14175 while you are in the process of writing the document.
14176 Furthermore, it provides us with the flexibility that is needed to support
14177 multiple export formats.
14178 For instance, in the case of a plain text file, it is not exactly an award-winn
14179 ing idea to include the figure as raw PostScript.
14180 Instead, you'd either prefer to just include a reference to the figure
14181 or try to invoke some graphics to ASCII converter to make the final result
14182 look similar to the real graphics.
14183 The external material management allows you to do this, because it is parametri
14184 zed on the different export formats that LyX supports.
14187 \begin_layout Standard
14188 Besides supporting the production of different products according to the
14189 exported format, it supports tight integration with editing and viewing
14191 In the case of an Xfig figure, you are able to invoke Xfig on the original
14192 file with a single click from within the external material dialog in LyX,
14193 and also preview the produced PostScript file with Ghostview with another
14195 No more fiddling around with the command line and/or file browsers to locate
14196 and manipulate the original or produced files.
14197 In this way, you are finally able to take full advantage of the many different
14198 applications that are relevant to use when you write your documents, and
14199 ultimately be more productive.
14202 \begin_layout Section
14203 The external template configuration file
14206 \begin_layout Standard
14207 It is relatively easy to add custom external template definitions to LyX.
14208 However, be aware that doing this in an careless manner most probably
14212 introduce an easily exploitable security hole.
14213 So before you do this, please read the discussion about security in section
14215 \begin_inset CommandInset ref
14217 reference "sec:Security-discussion"
14224 \begin_layout Standard
14225 Having said that, we encourage you to submit any interesting templates that
14230 \begin_layout Standard
14231 The external templates are defined in the
14232 \begin_inset Flex CharStyle:Code
14235 \begin_layout Plain Layout
14236 LyXDir/lib/external_templates
14242 You can place your own version in
14243 \begin_inset Flex CharStyle:Code
14246 \begin_layout Plain Layout
14247 UserDir/external_templates
14255 \begin_layout Standard
14256 A typical template looks like this:
14259 \begin_layout LyX-Code
14263 \begin_layout LyX-Code
14264 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14267 \begin_layout LyX-Code
14271 \begin_layout LyX-Code
14275 \begin_layout LyX-Code
14279 \begin_layout LyX-Code
14283 \begin_layout LyX-Code
14287 \begin_layout LyX-Code
14288 AutomaticProduction true
14291 \begin_layout LyX-Code
14295 \begin_layout LyX-Code
14299 \begin_layout LyX-Code
14303 \begin_layout LyX-Code
14304 TransformCommand Rotate RotationLatexCommand
14307 \begin_layout LyX-Code
14308 TransformCommand Resize ResizeLatexCommand
14311 \begin_layout LyX-Code
14312 Product "$$RotateFront$$ResizeFront
14315 \begin_layout LyX-Code
14320 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14323 \begin_layout LyX-Code
14324 $$ResizeBack$$RotateBack"
14327 \begin_layout LyX-Code
14331 \begin_layout LyX-Code
14332 UpdateResult "$$AbsPath$$Basename.pstex_t"
14335 \begin_layout LyX-Code
14336 Requirement "graphicx"
14339 \begin_layout LyX-Code
14340 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14343 \begin_layout LyX-Code
14344 ReferencedFile latex "$$AbsPath$$Basename.eps"
14347 \begin_layout LyX-Code
14348 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14351 \begin_layout LyX-Code
14355 \begin_layout LyX-Code
14359 \begin_layout LyX-Code
14360 TransformCommand Rotate RotationLatexCommand
14363 \begin_layout LyX-Code
14364 TransformCommand Resize ResizeLatexCommand
14367 \begin_layout LyX-Code
14368 Product "$$RotateFront$$ResizeFront
14371 \begin_layout LyX-Code
14376 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14379 \begin_layout LyX-Code
14380 $$ResizeBack$$RotateBack"
14383 \begin_layout LyX-Code
14384 UpdateFormat pdftex
14387 \begin_layout LyX-Code
14388 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14391 \begin_layout LyX-Code
14392 Requirement "graphicx"
14395 \begin_layout LyX-Code
14396 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14399 \begin_layout LyX-Code
14400 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14403 \begin_layout LyX-Code
14407 \begin_layout LyX-Code
14411 \begin_layout LyX-Code
14412 Product "$$Contents(
14414 "$$AbsPath$$Basename.asc
14419 \begin_layout LyX-Code
14420 UpdateFormat asciixfig
14423 \begin_layout LyX-Code
14424 UpdateResult "$$AbsPath$$Basename.asc"
14427 \begin_layout LyX-Code
14431 \begin_layout LyX-Code
14435 \begin_layout LyX-Code
14436 Product "<graphic fileref=
14438 "$$AbsOrRelPathMaster$$Basename.eps
14443 \begin_layout LyX-Code
14447 \begin_layout LyX-Code
14451 \begin_layout LyX-Code
14452 UpdateResult "$$AbsPath$$Basename.eps"
14455 \begin_layout LyX-Code
14456 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14459 \begin_layout LyX-Code
14460 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14463 \begin_layout LyX-Code
14467 \begin_layout LyX-Code
14468 Product "[XFig: $$FName]"
14471 \begin_layout LyX-Code
14475 \begin_layout LyX-Code
14479 \begin_layout Standard
14480 As you can see, the template is enclosed in
14481 \begin_inset Flex CharStyle:Code
14484 \begin_layout Plain Layout
14490 \SpecialChar \ldots{}
14492 \begin_inset Flex CharStyle:Code
14495 \begin_layout Plain Layout
14502 It contains a header specifying some general settings and, for each supported
14503 primary document file format, a section
14504 \begin_inset Flex CharStyle:Code
14507 \begin_layout Plain Layout
14513 \SpecialChar \ldots{}
14515 \begin_inset Flex CharStyle:Code
14518 \begin_layout Plain Layout
14527 \begin_layout Subsection
14528 The template header
14531 \begin_layout Description
14532 \begin_inset Flex CharStyle:Code
14535 \begin_layout Plain Layout
14536 AutomaticProduction
14537 \begin_inset space ~
14545 Whether the file represented by the template must be generated by LyX.
14546 This command must occur exactly once.
14549 \begin_layout Description
14550 \begin_inset Flex CharStyle:Code
14553 \begin_layout Plain Layout
14555 \begin_inset space ~
14563 A glob pattern that is used in the file dialog to filter out the desired
14565 If there is more than one possible file extension (e.
14566 \begin_inset space \thinspace{}
14570 \begin_inset space \space{}
14574 \begin_inset Flex CharStyle:Code
14577 \begin_layout Plain Layout
14584 \begin_inset Flex CharStyle:Code
14587 \begin_layout Plain Layout
14593 ), use something like
14594 \begin_inset Flex CharStyle:Code
14597 \begin_layout Plain Layout
14604 This command must occur exactly once.
14607 \begin_layout Description
14608 \begin_inset Flex CharStyle:Code
14611 \begin_layout Plain Layout
14613 \begin_inset space ~
14621 The text that is displayed on the button.
14622 This command must occur exactly once.
14625 \begin_layout Description
14626 \begin_inset Flex CharStyle:Code
14629 \begin_layout Plain Layout
14631 \begin_inset space ~
14635 \begin_inset space ~
14643 The help text that is used in the External dialog.
14644 Provide enough information to explain to the user just what the template
14645 can provide him with.
14646 This command must occur exactly once.
14649 \begin_layout Description
14650 \begin_inset Flex CharStyle:Code
14653 \begin_layout Plain Layout
14655 \begin_inset space ~
14663 The file format of the original file.
14664 This must be the name of a format that is known to LyX (see section
14665 \begin_inset CommandInset ref
14667 reference "sec:Formats"
14673 \begin_inset Quotes eld
14677 \begin_inset Flex CharStyle:Code
14680 \begin_layout Plain Layout
14687 \begin_inset Quotes erd
14690 if the template can handle original files of more than one format.
14691 LyX will attempt to interrogate the file itself in order to deduce its
14692 format in this case.
14693 This command must occur exactly once.
14696 \begin_layout Description
14697 \begin_inset Flex CharStyle:Code
14700 \begin_layout Plain Layout
14702 \begin_inset space ~
14710 A unique name for the template.
14711 It must not contain substitution macros (see below).
14714 \begin_layout Description
14715 \begin_inset Flex CharStyle:Code
14718 \begin_layout Plain Layout
14720 \begin_inset space ~
14723 Rotate|Resize|Clip|Extra
14728 This command specifies which transformations are supported by this template.
14729 It may occur zero or more times.
14730 This command enables the corresponding tabs in the external dialog.
14732 \begin_inset Flex CharStyle:Code
14735 \begin_layout Plain Layout
14741 command must have either a corresponding
14742 \begin_inset Flex CharStyle:Code
14745 \begin_layout Plain Layout
14752 \begin_inset Flex CharStyle:Code
14755 \begin_layout Plain Layout
14762 \begin_inset Flex CharStyle:Code
14765 \begin_layout Plain Layout
14772 Otherwise the transformation will not be supported by that format.
14775 \begin_layout Subsection
14779 \begin_layout Description
14780 \begin_inset Flex CharStyle:Code
14783 \begin_layout Plain Layout
14785 \begin_inset space ~
14788 LaTeX|PDFLaTeX|PlainText|DocBook
14793 The primary document file format that this format definition is for.
14794 Not every template has a sensible representation in all document file formats.
14795 Please define nevertheless a
14796 \begin_inset Flex CharStyle:Code
14799 \begin_layout Plain Layout
14805 section for all formats.
14806 Use a dummy text when no representation is available.
14807 Then you can at least see a reference to the external material in the exported
14811 \begin_layout Description
14812 \begin_inset Flex CharStyle:Code
14815 \begin_layout Plain Layout
14817 \begin_inset space ~
14821 \begin_inset space ~
14829 This command defines an additional macro
14830 \begin_inset Flex CharStyle:Code
14833 \begin_layout Plain Layout
14839 for substitution in
14840 \begin_inset Flex CharStyle:Code
14843 \begin_layout Plain Layout
14851 \begin_inset Flex CharStyle:Code
14854 \begin_layout Plain Layout
14860 itself may contain substitution macros.
14861 The advantage over using
14862 \begin_inset Flex CharStyle:Code
14865 \begin_layout Plain Layout
14872 \begin_inset Flex CharStyle:Code
14875 \begin_layout Plain Layout
14881 is that the substituted value of
14882 \begin_inset Flex CharStyle:Code
14885 \begin_layout Plain Layout
14891 is sanitized so that it is a valid optional argument in the document format.
14892 This command may occur zero or more times.
14895 \begin_layout Description
14896 \begin_inset Flex CharStyle:Code
14899 \begin_layout Plain Layout
14901 \begin_inset space ~
14909 The text that is inserted in the exported document.
14910 This is actually the most important command and can be quite complex.
14911 This command must occur exactly once.
14914 \begin_layout Description
14915 \begin_inset Flex CharStyle:Code
14918 \begin_layout Plain Layout
14920 \begin_inset space ~
14928 This command specifies a preamble snippet that will be included in the
14930 It has to be defined using
14931 \begin_inset Flex CharStyle:Code
14934 \begin_layout Plain Layout
14940 \SpecialChar \ldots{}
14942 \begin_inset Flex CharStyle:Code
14945 \begin_layout Plain Layout
14952 This command may occur zero or more times.
14955 \begin_layout Description
14956 \begin_inset Flex CharStyle:Code
14959 \begin_layout Plain Layout
14961 \begin_inset space ~
14965 \begin_inset space ~
14973 This command denotes files that are created by the conversion process and
14974 are needed for a particular export format.
14975 If the filename is relative, it is interpreted relative to the master document.
14976 This command may be given zero or more times.
14979 \begin_layout Description
14980 \begin_inset Flex CharStyle:Code
14983 \begin_layout Plain Layout
14985 \begin_inset space ~
14993 The name of a required LaTeX package.
14994 The package is included via
14995 \begin_inset Flex CharStyle:Code
14998 \begin_layout Plain Layout
15006 in the LaTeX preamble.
15007 This command may occur zero or more times.
15010 \begin_layout Description
15011 \begin_inset Flex CharStyle:Code
15014 \begin_layout Plain Layout
15016 \begin_inset space ~
15020 \begin_inset space ~
15023 RotationLatexCommand
15028 This command specifies that the built in LaTeX command should be used for
15030 This command may occur once or not at all.
15033 \begin_layout Description
15034 \begin_inset Flex CharStyle:Code
15037 \begin_layout Plain Layout
15039 \begin_inset space ~
15043 \begin_inset space ~
15051 This command specifies that the built in LaTeX command should be used for
15053 This command may occur once or not at all.
15056 \begin_layout Description
15057 \begin_inset Flex CharStyle:Code
15060 \begin_layout Plain Layout
15062 \begin_inset space ~
15066 \begin_inset space ~
15069 RotationLatexOption
15074 This command specifies that rotation is done via an optional argument.
15075 This command may occur once or not at all.
15078 \begin_layout Description
15079 \begin_inset Flex CharStyle:Code
15082 \begin_layout Plain Layout
15084 \begin_inset space ~
15088 \begin_inset space ~
15096 This command specifies that resizing is done via an optional argument.
15097 This command may occur once or not at all.
15100 \begin_layout Description
15101 \begin_inset Flex CharStyle:Code
15104 \begin_layout Plain Layout
15106 \begin_inset space ~
15110 \begin_inset space ~
15118 This command specifies that clipping is done via an optional argument.
15119 This command may occur once or not at all.
15122 \begin_layout Description
15123 \begin_inset Flex CharStyle:Code
15126 \begin_layout Plain Layout
15128 \begin_inset space ~
15132 \begin_inset space ~
15140 This command specifies that an extra optional argument is used.
15141 This command may occur once or not at all.
15144 \begin_layout Description
15145 \begin_inset Flex CharStyle:Code
15148 \begin_layout Plain Layout
15150 \begin_inset space ~
15158 The file format of the converted file.
15159 This must be the name of a format that is known to LyX (see the
15160 \begin_inset Flex CharStyle:MenuItem
15163 \begin_layout Plain Layout
15168 ools\SpecialChar \menuseparator
15173 references:Conversion
15179 This command must occur exactly once.
15182 \begin_layout Description
15183 \begin_inset Flex CharStyle:Code
15186 \begin_layout Plain Layout
15188 \begin_inset space ~
15196 The file name of the converted file.
15197 The file name must be absolute.
15198 This command must occur exactly once.
15201 \begin_layout Subsection
15202 Preamble definitions
15205 \begin_layout Standard
15206 The external template configuration file may contain additional preamble
15207 definitions enclosed by
15208 \begin_inset Flex CharStyle:Code
15211 \begin_layout Plain Layout
15217 \SpecialChar \ldots{}
15219 \begin_inset Flex CharStyle:Code
15222 \begin_layout Plain Layout
15229 They can be used by the templates in the
15230 \begin_inset Flex CharStyle:Code
15233 \begin_layout Plain Layout
15242 \begin_layout Section
15243 The substitution mechanism
15246 \begin_layout Standard
15247 When the external material facility invokes an external program, it is done
15248 on the basis of a command defined in the template configuration file.
15249 These commands can contain various macros that are expanded before execution.
15250 Execution always take place in the directory of the containing document.
15253 \begin_layout Standard
15254 Also, whenever external material is to be displayed, the name will be produced
15255 by the substitution mechanism, and most other commands in the template
15256 definition support substitution as well.
15259 \begin_layout Standard
15260 The available macros are the following:
15263 \begin_layout Description
15264 \begin_inset Flex CharStyle:Code
15267 \begin_layout Plain Layout
15268 $$AbsOrRelPathMaster
15273 The file path, absolute or relative to the master LyX document.
15276 \begin_layout Description
15277 \begin_inset Flex CharStyle:Code
15280 \begin_layout Plain Layout
15281 $$AbsOrRelPathParent
15286 The file path, absolute or relative to the LyX document.
15289 \begin_layout Description
15290 \begin_inset Flex CharStyle:Code
15293 \begin_layout Plain Layout
15299 The absolute file path.
15302 \begin_layout Description
15303 \begin_inset Flex CharStyle:Code
15306 \begin_layout Plain Layout
15312 The filename without path and without the extension.
15315 \begin_layout Description
15316 \begin_inset Flex CharStyle:Code
15319 \begin_layout Plain Layout
15321 \begin_inset Quotes eld
15325 \begin_inset Quotes erd
15333 This macro will expand to the contents of the file with the name
15334 \begin_inset Flex CharStyle:Code
15337 \begin_layout Plain Layout
15346 \begin_layout Description
15347 \begin_inset Flex CharStyle:Code
15350 \begin_layout Plain Layout
15356 The file extension (including the dot).
15359 \begin_layout Description
15360 \begin_inset Flex CharStyle:Code
15363 \begin_layout Plain Layout
15369 The filename of the file specified in the external material dialog.
15370 This is either an absolute name, or it is relative to the LyX document.
15373 \begin_layout Description
15374 \begin_inset Flex CharStyle:Code
15377 \begin_layout Plain Layout
15384 \begin_inset Flex CharStyle:Code
15387 \begin_layout Plain Layout
15393 (absolute name or relative to the LyX document).
15396 \begin_layout Description
15397 \begin_inset Flex CharStyle:Code
15400 \begin_layout Plain Layout
15406 The file path, relative to the master LyX document.
15409 \begin_layout Description
15410 \begin_inset Flex CharStyle:Code
15413 \begin_layout Plain Layout
15419 The file path, relative to the LyX document.
15422 \begin_layout Description
15423 \begin_inset Flex CharStyle:Code
15426 \begin_layout Plain Layout
15432 This macro will expand to the absolute path of the system directory.
15433 This is typically used to point to the various helper scripts that are
15437 \begin_layout Description
15438 \begin_inset Flex CharStyle:Code
15441 \begin_layout Plain Layout
15447 A name and full path to a temporary file which will be automatically deleted
15448 whenever the containing document is closed, or the external material insertion
15452 \begin_layout Standard
15453 All path macros contain a trailing directory separator, so you can construct
15455 \begin_inset space \thinspace{}
15459 \begin_inset space \space{}
15462 the absolute filename with
15463 \begin_inset Flex CharStyle:Code
15466 \begin_layout Plain Layout
15467 $$AbsPath$$Basename$$Extension
15475 \begin_layout Standard
15476 The macros above are substituted in all commands unless otherwise noted.
15478 \begin_inset Flex CharStyle:Code
15481 \begin_layout Plain Layout
15487 supports additionally the following substitutions if they are enabled by
15489 \begin_inset Flex CharStyle:Code
15492 \begin_layout Plain Layout
15499 \begin_inset Flex CharStyle:Code
15502 \begin_layout Plain Layout
15511 \begin_layout Description
15512 \begin_inset Flex CharStyle:Code
15515 \begin_layout Plain Layout
15521 The front part of the resize command.
15524 \begin_layout Description
15525 \begin_inset Flex CharStyle:Code
15528 \begin_layout Plain Layout
15534 The back part of the resize command.
15537 \begin_layout Description
15538 \begin_inset Flex CharStyle:Code
15541 \begin_layout Plain Layout
15547 The front part of the rotation command.
15550 \begin_layout Description
15551 \begin_inset Flex CharStyle:Code
15554 \begin_layout Plain Layout
15560 The back part of the rotation command.
15563 \begin_layout Standard
15564 The value string of the
15565 \begin_inset Flex CharStyle:Code
15568 \begin_layout Plain Layout
15574 command supports additionally the following substitutions if they are enabled
15576 \begin_inset Flex CharStyle:Code
15579 \begin_layout Plain Layout
15586 \begin_inset Flex CharStyle:Code
15589 \begin_layout Plain Layout
15598 \begin_layout Description
15599 \begin_inset Flex CharStyle:Code
15602 \begin_layout Plain Layout
15611 \begin_layout Description
15612 \begin_inset Flex CharStyle:Code
15615 \begin_layout Plain Layout
15624 \begin_layout Description
15625 \begin_inset Flex CharStyle:Code
15628 \begin_layout Plain Layout
15637 \begin_layout Description
15638 \begin_inset Flex CharStyle:Code
15641 \begin_layout Plain Layout
15647 The rotation option.
15650 \begin_layout Standard
15651 You may ask why there are so many path macros.
15652 There are mainly two reasons:
15655 \begin_layout Enumerate
15656 Relative and absolute file names should remain relative or absolute, respectivel
15658 Users may have reasons to prefer either form.
15659 Relative names are useful for portable documents that should work on different
15660 machines, for example.
15661 Absolute names may be required by some programs.
15664 \begin_layout Enumerate
15665 LaTeX treats relative file names differently than LyX and other programs
15666 in nested included files.
15667 For LyX, a relative file name is always relative to the document that contains
15669 For LaTeX, it is always relative to the master document.
15670 These two definitions are identical if you have only one document, but
15671 differ if you have a master document that includes part documents.
15672 That means that relative filenames must be transformed when presented to
15674 Fortunately LyX does this automatically for you if you choose the right
15678 \begin_layout Standard
15679 So which path macro should be used in new template definitions? The rule
15683 \begin_layout Itemize
15685 \begin_inset Flex CharStyle:Code
15688 \begin_layout Plain Layout
15694 if an absolute path is required.
15697 \begin_layout Itemize
15699 \begin_inset Flex CharStyle:Code
15702 \begin_layout Plain Layout
15703 $$AbsOrRelPathMaster
15708 if the substituted string is some kind of LaTeX input.
15711 \begin_layout Itemize
15713 \begin_inset Flex CharStyle:Code
15716 \begin_layout Plain Layout
15717 $$AbsOrRelPathParent
15722 in order to preserve the user's choice.
15725 \begin_layout Standard
15726 There are special cases where this rule does not work and e.
15727 \begin_inset space \thinspace{}
15731 \begin_inset space \space{}
15734 relative names are needed, but normally it will work just fine.
15735 One example for such a case is the command
15736 \begin_inset Flex CharStyle:Code
15739 \begin_layout Plain Layout
15740 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15745 in the XFig template above: We can't use the absolute name because the
15747 \begin_inset Flex CharStyle:Code
15750 \begin_layout Plain Layout
15756 files needs the relative name in order to rewrite the file content.
15759 \begin_layout Section
15760 Security discussion
15761 \begin_inset CommandInset label
15763 name "sec:Security-discussion"
15770 \begin_layout Standard
15771 The external material feature interfaces with a lot of external programs
15772 and does so automatically, so we have to consider the security implications
15774 In particular, since you have the option of including your own filenames
15775 and/or parameter strings and those are expanded into a command, it seems
15776 that it would be possible to create a malicious document which executes
15777 arbitrary commands when a user views or prints the document.
15778 This is something we definitely want to avoid.
15781 \begin_layout Standard
15782 However, since the external program commands are specified in the template
15783 configuration file only, there are no security issues if LyX is properly
15784 configured with safe templates only.
15785 This is so because the external programs are invoked with the
15786 \begin_inset Flex CharStyle:Code
15789 \begin_layout Plain Layout
15795 -system call rather than the
15796 \begin_inset Flex CharStyle:Code
15799 \begin_layout Plain Layout
15805 system-call, so it's not possible to execute arbitrary commands from the
15806 filename or parameter section via the shell.
15809 \begin_layout Standard
15810 This also implies that you are restricted in what command strings you can
15811 use in the external material templates.
15812 In particular, pipes and redirection are not readily available.
15813 This has to be so if LyX should remain safe.
15814 If you want to use some of the shell features, you should write a safe
15815 script to do this in a controlled manner, and then invoke the script from
15816 the command string.
15820 \begin_layout Standard
15821 It is possible to design a template that interacts directly with the shell,
15822 but since this would allow a malicious user to execute arbitrary commands
15823 by writing clever filenames and/or parameters, we generally recommend that
15824 you only use safe scripts that work with the
15825 \begin_inset Flex CharStyle:Code
15828 \begin_layout Plain Layout
15834 system call in a controlled manner.
15835 Of course, for use in a controlled environment, it can be tempting to just
15836 fall back to use ordinary shell scripts.
15837 If you do so, be aware that you
15841 provide an easily exploitable security hole in your system.
15842 Of course it stands to reason that such unsafe templates will never be
15843 included in the standard LyX distribution, although we do encourage people
15844 to submit new templates in the open source tradition.
15845 But LyX as shipped from the official distribution channels will never have
15849 \begin_layout Standard
15850 Including external material provides a lot of power, and you have to be
15851 careful not to introduce security hazards with this power.
15852 A subtle error in a single line in an innocent looking script can open
15853 the door to huge security problems.
15854 So if you do not fully understand the issues, we recommend that you consult
15855 a knowledgeable security professional or the LyX development team if you
15856 have any questions about whether a given template is safe or not.
15857 And do this before you use it in an uncontrolled environment.