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
80 \pdf_title "LyX Configuration Manual"
81 \pdf_author "LyX Team"
82 \pdf_subject "LyX-documentation Customization"
83 \pdf_keywords "LyX, documentation, customization"
85 \pdf_bookmarksnumbered true
86 \pdf_bookmarksopen true
87 \pdf_bookmarksopenlevel 1
92 \pdf_pdfusetitle false
93 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true,pdfstartview=XYZ, plainpages=false, pdfpagelabels"
101 \paperorientation portrait
102 \backgroundcolor #ffffff
109 \paragraph_separation indent
111 \quotes_language english
114 \paperpagestyle headings
115 \tracking_changes false
116 \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
2976 \begin_inset Flex CharStyle:Code
2979 \begin_layout Plain Layout
2985 , the guide to writing LyX documentation.
2986 Pay special attention to the translator's section.
2989 \begin_layout Itemize
2990 Check out the documentation translation web page at
2991 \begin_inset CommandInset href
2993 name "http://www.lyx.org/Translation"
2994 target "http://www.lyx.org/Translation"
2999 That way, you can find out which (if any) documents have already been translate
3000 d into your language.
3001 You can also find out who (if anyone) is organizing the effort to translate
3002 the documentation into your language.
3003 If no one is organizing the effort, please let us know that you're interested.
3006 \begin_layout Standard
3007 Once you get to actually translating, here's a few hints for you that may
3011 \begin_layout Itemize
3012 Join the documentation team! There is information on how to do that in
3013 \begin_inset Flex CharStyle:Code
3016 \begin_layout Plain Layout
3023 \begin_inset Flex CharStyle:MenuItem
3026 \begin_layout Plain Layout
3027 Help\SpecialChar \menuseparator
3037 ), which by the way is the first document you should translate.
3040 \begin_layout Itemize
3041 Learn the typographic conventions for the language you are translating to.
3042 Typography is an ancient art and over the centuries, a great variety of
3043 conventions have developed throughout different parts of the world.
3044 Also study the professional terminology amongst typographers in your country.
3045 Inventing your own terminology will only confuse the users.
3048 (Warning! Typography is addictive!)
3051 \begin_layout Itemize
3052 Make a copy of the document.
3053 This will be your working copy.
3054 You can use this as your personal translated help-file by placing it in
3056 \begin_inset Flex CharStyle:Code
3059 \begin_layout Plain Layout
3068 \begin_layout Itemize
3069 Sometimes the original document (from the LyX-team) will be updated.
3070 Use the source viewer at
3071 \begin_inset CommandInset href
3073 name "http://www.lyx.org/trac/timeline"
3074 target "http://www.lyx.org/trac/timeline"
3078 to see what has been changed.
3079 That way you can easily see which parts of the translated document need
3083 \begin_layout Standard
3084 If you ever find an error in the original document, fix it and notify the
3085 rest of the documentation team of the changes! (You didn't forget to join
3086 the documentation team, did you?)
3089 \begin_layout Standard
3090 \begin_inset Branch OutDated
3093 \begin_layout Section
3094 International Keyboard Support
3097 \begin_layout Standard
3100 [Editor's Note: The following section is by
3108 It needs to be fixed to conform to the new Documentation Style sheet and
3109 to make use of the new v1.0 features.
3110 The whole thing also needs to be merged with the section following it.-jw
3111 It may also be badly out of date.-rh (2008)]
3114 \begin_layout Subsection
3115 Defining Own Keymaps: Keymap File Format
3118 \begin_layout Standard
3119 Let's look at a keyboard definition file a little closer.
3120 It is a plain text file defining
3123 \begin_layout Itemize
3124 key-to-key or key-to-string translations
3127 \begin_layout Itemize
3131 \begin_layout Itemize
3132 dead keys exceptions
3135 \begin_layout Standard
3136 To define key-to-key or key-to-string translation, use this command:
3139 \begin_layout Quotation
3140 \begin_inset Flex CharStyle:Code
3143 \begin_layout Plain Layout
3152 \begin_inset Flex CharStyle:Code
3155 \begin_layout Plain Layout
3164 \begin_layout Standard
3166 \begin_inset Flex CharStyle:Code
3169 \begin_layout Plain Layout
3175 is the key to be translated and
3176 \begin_inset Flex CharStyle:Code
3179 \begin_layout Plain Layout
3185 is the string to be inserted into the document.
3186 To define dead keys, use:
3189 \begin_layout Quotation
3190 \begin_inset Flex CharStyle:Code
3193 \begin_layout Plain Layout
3202 \begin_inset Flex CharStyle:Code
3205 \begin_layout Plain Layout
3214 \begin_layout Standard
3216 \begin_inset Flex CharStyle:Code
3219 \begin_layout Plain Layout
3225 is a keyboard key and
3226 \begin_inset Flex CharStyle:Code
3229 \begin_layout Plain Layout
3236 The following dead keys are supported (shortcut name is in parentheses):
3239 \begin_layout Quotation
3243 \begin_inset space \hfill{}
3249 \begin_layout Quotation
3251 \begin_inset space \hfill{}
3257 \begin_layout Quotation
3259 \begin_inset space \hfill{}
3265 \begin_layout Quotation
3267 \begin_inset space \hfill{}
3273 \begin_layout Quotation
3275 \begin_inset space \hfill{}
3281 \begin_layout Quotation
3283 \begin_inset space \hfill{}
3290 \begin_layout Plain Layout
3302 \begin_layout Quotation
3304 \begin_inset space \hfill{}
3310 \begin_layout Quotation
3312 \begin_inset space \hfill{}
3319 \begin_layout Plain Layout
3331 \begin_layout Quotation
3333 \begin_inset space \hfill{}
3339 \begin_layout Quotation
3341 \begin_inset space \hfill{}
3347 \begin_layout Quotation
3349 \begin_inset space \hfill{}
3356 \begin_layout Plain Layout
3368 \begin_layout Quotation
3370 \begin_inset space \hfill{}
3377 \begin_layout Plain Layout
3389 \begin_layout Quotation
3391 \begin_inset space \hfill{}
3397 \begin_layout Quotation
3398 hungarian umlaut (hug)
3399 \begin_inset space \hfill{}
3405 \begin_layout Quotation
3407 \begin_inset space \hfill{}
3413 \begin_layout Quotation
3415 \begin_inset space \hfill{}
3422 \begin_layout Plain Layout
3434 \begin_layout Standard
3435 Since in many international keyboards there are exceptions to what some
3436 dead keys should do, you can define them using
3439 \begin_layout Quotation
3440 \begin_inset Flex CharStyle:Code
3443 \begin_layout Plain Layout
3451 deadkey key outstring
3454 \begin_layout Standard
3455 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3459 \begin_layout Quotation
3460 \begin_inset Flex CharStyle:Code
3463 \begin_layout Plain Layout
3476 \begin_layout Standard
3477 to make it work correctly.
3478 Also, you have to define as exceptions dead keys over i and j, to remove
3479 the dot from them before inserting an accent mark.
3480 I will change this when the time comes, but so far I haven't had time.
3483 \begin_layout Standard
3484 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3487 \begin_inset Flex CharStyle:Code
3490 \begin_layout Plain Layout
3496 have different meaning.
3498 \begin_inset Flex CharStyle:Code
3501 \begin_layout Plain Layout
3507 marks comments, quotes start and end LaTeX-style commands.
3508 To enter quote, you'll need to use
3509 \begin_inset Flex CharStyle:Code
3512 \begin_layout Plain Layout
3521 \begin_inset Flex CharStyle:Code
3524 \begin_layout Plain Layout
3531 \begin_inset Flex CharStyle:Code
3534 \begin_layout Plain Layout
3545 \begin_layout Standard
3546 If you make a keyboard description file that works for your language, please
3547 mail it to me, so I can include it in the next keymap distribution.
3550 \begin_layout Standard
3551 More keywords will be supported in keymap configuration file in future,
3555 \begin_layout Itemize
3556 \begin_inset Flex CharStyle:Code
3559 \begin_layout Plain Layout
3570 \begin_inset space \hfill{}
3574 \begin_inset Flex CharStyle:Code
3577 \begin_layout Plain Layout
3586 \begin_layout Itemize
3587 \begin_inset Flex CharStyle:Code
3590 \begin_layout Plain Layout
3601 \begin_inset space \hfill{}
3605 \begin_inset Flex CharStyle:Code
3608 \begin_layout Plain Layout
3614 an external keymap translation program
3617 \begin_layout Standard
3618 Also, it should look into
3619 \begin_inset Flex CharStyle:Code
3622 \begin_layout Plain Layout
3628 file for defaults, too (for example, a
3629 \begin_inset Flex CharStyle:Code
3632 \begin_layout Plain Layout
3640 option to include default keyboard).
3648 \begin_layout Section
3649 International Keymap Stuff
3650 \begin_inset CommandInset label
3652 name "sec:International-Keymap-Stuff"
3659 \begin_layout Standard
3660 \begin_inset Note Note
3663 \begin_layout Plain Layout
3664 In doing the revisions on this document in March 2008, I did not look over
3665 this stuff, as I do not understand it.
3666 It would be good if someone else could do so.
3675 \begin_layout Standard
3676 The next two sections describe the
3677 \begin_inset Flex CharStyle:Code
3680 \begin_layout Plain Layout
3689 \begin_inset Flex CharStyle:Code
3692 \begin_layout Plain Layout
3700 file syntax in detail.
3701 These sections should help you design your own key map if the ones provided
3702 do not meet your needs.
3705 \begin_layout Subsection
3709 \begin_layout Standard
3713 \begin_inset Flex CharStyle:Code
3716 \begin_layout Plain Layout
3722 file maps keystrokes to characters or strings.
3723 As the name suggests, it sets a keyboard mapping.
3725 \begin_inset Flex CharStyle:Code
3728 \begin_layout Plain Layout
3739 \begin_inset Flex CharStyle:Code
3742 \begin_layout Plain Layout
3757 \begin_inset Flex CharStyle:Code
3760 \begin_layout Plain Layout
3773 \begin_inset Flex CharStyle:Code
3776 \begin_layout Plain Layout
3785 \begin_inset Flex CharStyle:Code
3788 \begin_layout Plain Layout
3796 are described in this section.
3799 \begin_layout Labeling
3800 \labelwidthstring 00.00.0000
3801 \begin_inset Flex CharStyle:Code
3804 \begin_layout Plain Layout
3812 Map a character to a string
3815 \begin_layout LyX-Code
3830 \begin_layout Standard
3863 the double-quote (")
3880 must be escaped with a preceding backslash (
3891 \begin_layout Standard
3893 \begin_inset Flex CharStyle:MenuItem
3896 \begin_layout Plain Layout
3904 statement to cause the symbol
3905 \begin_inset Flex CharStyle:MenuItem
3908 \begin_layout Plain Layout
3916 to be output for the keystroke
3917 \begin_inset Flex CharStyle:MenuItem
3920 \begin_layout Plain Layout
3931 \begin_layout LyX-Code
3937 \begin_layout Labeling
3938 \labelwidthstring 00.00.0000
3939 \begin_inset Flex CharStyle:Code
3942 \begin_layout Plain Layout
3950 Specify an accent character
3953 \begin_layout LyX-Code
3962 \begin_layout Standard
3963 This will make the cha
4001 This is the dead key
4005 \begin_layout Plain Layout
4012 refers to a key that does not produce a character by itself, but when followed
4013 with another key, produces the desired accent character.
4014 For example, a German characte
4016 r with an umlaut like
4026 can be produced in this manner.
4035 \begin_layout Standard
4048 and then another key not in
4065 followed by the other, not allowed key, as output.
4069 \begin_inset Flex CharStyle:MenuItem
4072 \begin_layout Plain Layout
4080 cancels a dead key, so if
4091 \begin_inset Flex CharStyle:MenuItem
4094 \begin_layout Plain Layout
4103 , the cursor will not go one position backwards but will instead cancel
4119 might have had on the next keystroke.
4123 \begin_layout Standard
4124 The following example specifies that the character ' is to be an acute accent,
4125 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4128 \begin_layout LyX-Code
4131 kmod ' acute aeiouAEIOU
4134 \begin_layout Labeling
4135 \labelwidthstring 00.00.0000
4136 \begin_inset Flex CharStyle:Code
4139 \begin_layout Plain Layout
4145 Specify an exception to the accent character
4148 \begin_layout LyX-Code
4157 \begin_layout Standard
4158 This defines an exce
4199 have been assigned a keystroke with a previous
4202 \begin_inset Flex CharStyle:Code
4205 \begin_layout Plain Layout
4229 must not belong in the
4276 If such a declaration does not exist in
4284 \begin_inset Flex CharStyle:Code
4287 \begin_layout Plain Layout
4321 \begin_inset Flex CharStyle:Code
4324 \begin_layout Plain Layout
4338 \begin_layout Standard
4339 The following command produces causes äi to be produced when you enter acute-i
4343 \begin_layout LyX-Code
4357 \begin_layout Labeling
4358 \labelwidthstring 00.00.0000
4359 \begin_inset Flex CharStyle:Code
4362 \begin_layout Plain Layout
4368 Combine two accent characters
4371 \begin_layout LyX-Code
4377 accent1 accent2 allowed
4380 \begin_layout Standard
4381 This one is getting pretty esoteric.
4382 It allows you to combine the effect
4438 \begin_inset Flex CharStyle:Code
4441 \begin_layout Plain Layout
4469 \begin_layout Standard
4470 Consider this example from the
4471 \begin_inset Flex CharStyle:Code
4474 \begin_layout Plain Layout
4485 \begin_layout LyX-Code
4488 kmod ; acute aeioyvhAEIOYVH
4492 kcomb acute umlaut iyIY
4495 \begin_layout Standard
4496 This allows you to press
4497 \begin_inset Flex CharStyle:MenuItem
4500 \begin_layout Plain Layout
4508 and get the effect of
4509 \begin_inset Flex CharStyle:Code
4512 \begin_layout Plain Layout
4531 in this case cancels the last dead key, so if you press
4532 \begin_inset Flex CharStyle:MenuItem
4535 \begin_layout Plain Layout
4544 \begin_inset Flex CharStyle:Code
4547 \begin_layout Plain Layout
4560 \begin_layout Subsection
4564 \begin_layout Standard
4566 \begin_inset Flex CharStyle:Code
4569 \begin_layout Plain Layout
4577 mapping is performed, a
4578 \begin_inset Flex CharStyle:Code
4581 \begin_layout Plain Layout
4591 file maps the strings that the symbols generate to characters in the current
4593 The LyX distribution currently includes at least the
4594 \begin_inset Flex CharStyle:Code
4597 \begin_layout Plain Layout
4606 \begin_inset Flex CharStyle:Code
4609 \begin_layout Plain Layout
4620 \begin_layout Standard
4622 \begin_inset Flex CharStyle:Code
4625 \begin_layout Plain Layout
4633 file is a sequence of declarations of the form
4636 \begin_layout LyX-Code
4649 \begin_layout Standard
4650 For example, in order to map
4651 \begin_inset Flex CharStyle:MenuItem
4654 \begin_layout Plain Layout
4664 to the corresponding character in the iso-8859-1 set (233), the following
4668 \begin_layout LyX-Code
4676 \begin_layout Standard
4678 \begin_inset Flex CharStyle:Code
4681 \begin_layout Plain Layout
4690 \begin_inset Flex CharStyle:Code
4693 \begin_layout Plain Layout
4711 the same character can apply to more than one string.
4713 \begin_inset Flex CharStyle:Code
4716 \begin_layout Plain Layout
4727 \begin_layout LyX-Code
4739 \begin_inset Newline newline
4755 \begin_layout Standard
4756 If LyX cannot find a mapping for the string produced by the keystroke or
4757 a deadkey sequence, it will check if it looks like an accented char and
4758 try to draw an accent over the character on screen.
4761 \begin_layout Subsection
4765 \begin_layout Standard
4766 There is a second way to add support for international characters through
4767 so-called dead-keys.
4768 A dead-key works in combination with a letter to produce an accented character.
4769 Here, we'll explain how to create a really simple dead-key to illustrate
4773 \begin_layout Standard
4774 Suppose you happen to need the circumflex character,
4775 \begin_inset Quotes eld
4779 \begin_inset Quotes erd
4784 \begin_inset Flex CharStyle:MenuItem
4787 \begin_layout Plain Layout
4794 \begin_inset space ~
4798 \begin_inset Flex CharStyle:MenuItem
4801 \begin_layout Plain Layout
4807 ] to the LyX command
4808 \begin_inset Flex CharStyle:Code
4811 \begin_layout Plain Layout
4818 \begin_inset Flex CharStyle:Code
4821 \begin_layout Plain Layout
4828 Now, whenever you type the
4829 \begin_inset Flex CharStyle:MenuItem
4832 \begin_layout Plain Layout
4838 -key followed by a letter, that letter will have a circumflex accent on
4840 For example, the sequence
4841 \begin_inset Quotes eld
4845 \begin_inset Flex CharStyle:MenuItem
4848 \begin_layout Plain Layout
4855 \begin_inset Quotes erd
4858 produces the letter:
4859 \begin_inset Quotes eld
4863 \begin_inset Quotes erd
4867 If you tried to type
4868 \begin_inset Quotes eld
4872 \begin_inset Flex CharStyle:MenuItem
4875 \begin_layout Plain Layout
4882 \begin_inset Quotes erd
4885 , however, LyX will complain with a beep, since a
4886 \begin_inset Quotes eld
4890 \begin_inset Flex CharStyle:MenuItem
4893 \begin_layout Plain Layout
4900 \begin_inset Quotes erd
4903 never takes a circumflex accent.
4905 \begin_inset Flex CharStyle:MenuItem
4908 \begin_layout Plain Layout
4914 after a dead-key produces the bare-accent.
4915 Please note this last point! If you bind a key to a dead-key, you'll need
4916 to rebind the character on that key to yet another key.
4918 \begin_inset Flex CharStyle:MenuItem
4921 \begin_layout Plain Layout
4927 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4930 \begin_layout Standard
4931 One common way to bind dead-keys is to use
4932 \begin_inset Flex CharStyle:MenuItem
4935 \begin_layout Plain Layout
4942 \begin_inset Flex CharStyle:MenuItem
4945 \begin_layout Plain Layout
4952 \begin_inset Flex CharStyle:MenuItem
4955 \begin_layout Plain Layout
4961 in combination with an accent, like
4962 \begin_inset Quotes eld
4966 \begin_inset Flex CharStyle:MenuItem
4969 \begin_layout Plain Layout
4976 \begin_inset Quotes erd
4980 \begin_inset Quotes eld
4984 \begin_inset Flex CharStyle:MenuItem
4987 \begin_layout Plain Layout
4994 \begin_inset Quotes erd
4998 \begin_inset Quotes eld
5002 \begin_inset Flex CharStyle:MenuItem
5005 \begin_layout Plain Layout
5012 \begin_inset Quotes erd
5016 Another way involves using
5017 \begin_inset Flex CharStyle:Code
5020 \begin_layout Plain Layout
5027 \begin_inset Flex CharStyle:Code
5030 \begin_layout Plain Layout
5036 to set up the special
5037 \begin_inset Flex CharStyle:Code
5040 \begin_layout Plain Layout
5048 \begin_inset Flex CharStyle:Code
5051 \begin_layout Plain Layout
5057 acts in some ways just like
5058 \begin_inset Flex CharStyle:MenuItem
5061 \begin_layout Plain Layout
5067 and permits you to bind keys to accented characters.
5068 You can also turn keys into dead-keys by binding them to something like
5070 \begin_inset Flex CharStyle:Code
5073 \begin_layout Plain Layout
5079 and then binding this symbolic key to the corresponding LyX command.
5083 \begin_layout Plain Layout
5088 : This is exactly what I do in my
5089 \begin_inset Flex CharStyle:Code
5092 \begin_layout Plain Layout
5099 \begin_inset Flex CharStyle:Code
5102 \begin_layout Plain Layout
5110 \begin_inset Flex CharStyle:MenuItem
5113 \begin_layout Plain Layout
5115 \begin_inset space ~
5124 \begin_inset Flex CharStyle:Code
5127 \begin_layout Plain Layout
5133 and a bunch of these
5134 \begin_inset Quotes eld
5138 \begin_inset Flex CharStyle:Code
5141 \begin_layout Plain Layout
5148 \begin_inset Quotes erd
5151 symbolic keys bound such things as
5152 \begin_inset Flex CharStyle:MenuItem
5155 \begin_layout Plain Layout
5157 \begin_inset space ~
5166 \begin_inset Flex CharStyle:MenuItem
5169 \begin_layout Plain Layout
5171 \begin_inset space ~
5180 This is how I produce my accented characters.
5185 You can make just about anything into the
5186 \begin_inset Flex CharStyle:Code
5189 \begin_layout Plain Layout
5196 \begin_inset Flex CharStyle:MenuItem
5199 \begin_layout Plain Layout
5205 keys, a spare function key, etc.
5206 As for the LyX commands that produce accents, check the entry for
5207 \begin_inset Flex CharStyle:Code
5210 \begin_layout Plain Layout
5221 You'll find the complete list there.
5224 \begin_layout Subsection
5225 Saving your Language Configuration
5228 \begin_layout Standard
5229 You can edit your preferences so that your desired language environment
5230 is automatically configured when LyX starts up, via the
5231 \begin_inset Flex CharStyle:MenuItem
5234 \begin_layout Plain Layout
5235 Edit\SpecialChar \menuseparator
5244 \begin_layout Chapter
5245 Installing New Document Classes, Layouts, and Templates
5246 \begin_inset CommandInset label
5248 name "cha:Installing-New-Document"
5256 \begin_layout Plain Layout
5257 Installing New Document Classes
5265 \begin_layout Standard
5266 In this chapter, we describe the procedures for creating and installing
5267 new LyX layout and template files, as well as offer a refresher on correctly
5268 installing new LaTeX document classes.
5269 Some definitions: a document class is a LaTeX file (usually ending in
5270 \begin_inset Flex CharStyle:Code
5273 \begin_layout Plain Layout
5280 \begin_inset Flex CharStyle:Code
5283 \begin_layout Plain Layout
5289 ) that describes the format of a document such as an article, report, journal
5290 preprint, etc, and all the commands needed to realize that format.
5291 A layout file is a LyX file that corresponds to a LaTeX document class
5292 and that tells LyX how to
5293 \begin_inset Quotes eld
5297 \begin_inset Quotes erd
5300 things on the screen to make the display look something like the final
5302 More precisely, a layout file describes a
5303 \begin_inset Quotes eld
5307 \begin_inset Quotes erd
5310 which is the internal construct LyX uses to render the screen display.
5312 \begin_inset Quotes eld
5316 \begin_inset Quotes erd
5320 \begin_inset Quotes eld
5324 \begin_inset Quotes erd
5327 can be used somewhat interchangeably, but it is better to refer to the
5328 file as the layout, and the thing living in LyX's memory as the text class.
5329 A template file is simply a LyX document that contains a set of predefined
5330 entries for a given document class—entries that are generally required
5332 Templates are especially useful for things like journal manuscripts that
5333 are to be submitted electronically.
5336 \begin_layout Section
5337 Installing a new LaTeX package
5340 \begin_layout Standard
5341 Some installations may not include a LaTeX package that you would like to
5343 For example, you might need FoilTeX, a package for preparing slides or
5344 viewgraphs for overhead projectors.
5345 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5346 a user interface for that.
5347 For example on MiKTeX you start its program
5348 \begin_inset Quotes eld
5352 \begin_inset Quotes erd
5355 to get a list of available packages.
5356 To install one, right click on it or use the installing toolbar button.
5357 When the package you want to install is not in the list, but you have it
5359 \begin_inset Flex CharStyle:Code
5362 \begin_layout Plain Layout
5369 \begin_inset Flex CharStyle:Code
5372 \begin_layout Plain Layout
5378 -file, then copy these files to a subfolder of your LaTeX distribution,
5379 for example to the folder
5388 Then update the file name database of your LaTeX-distribution.
5389 For example on MiKTeX this is done by pressing the button
5392 \begin_inset space ~
5397 that you find in MiKTeX's
5398 \begin_inset Quotes eld
5402 \begin_inset Quotes erd
5406 In both cases you need afterwards to reconfigure LyX using the menu
5407 \begin_inset Flex CharStyle:MenuItem
5410 \begin_layout Plain Layout
5411 Tools\SpecialChar \menuseparator
5417 and then to restart LyX.
5420 \begin_layout Standard
5421 If your LaTeX distribution doesn't provide a user interface, then you can
5422 follow these steps by using a UNIX/Linux console.
5425 \begin_layout Enumerate
5426 Get the package from
5427 \begin_inset CommandInset href
5430 target "http://www.ctan.org/"
5437 \begin_layout Enumerate
5438 You can install this package in several different places.
5439 If you want it to be available for all users on your system, then you should
5440 install it in your `local' TeX tree; if you want (or need) it to be available
5441 just for you, then you can install it in your own `user' TeX tree.
5442 Where these should be created, if they do not already exist, depends upon
5443 the details of your system.
5444 To find out, look in the file
5445 \begin_inset Flex CharStyle:Code
5448 \begin_layout Plain Layout
5458 \begin_layout Plain Layout
5459 This usually lives in the directory
5460 \begin_inset Flex CharStyle:Code
5463 \begin_layout Plain Layout
5469 , though you can run
5470 \begin_inset Flex CharStyle:Code
5473 \begin_layout Plain Layout
5484 The location of the `local' TeX tree is defined by
5485 \begin_inset Flex CharStyle:Code
5488 \begin_layout Plain Layout
5494 ; this is usually somewhere like
5495 \begin_inset Flex CharStyle:Code
5498 \begin_layout Plain Layout
5499 /usr/local/share/texmf/
5505 The `user' TeX tree is defined by
5506 \begin_inset Flex CharStyle:Code
5509 \begin_layout Plain Layout
5516 \begin_inset Flex CharStyle:Code
5519 \begin_layout Plain Layout
5526 (If these variables are not predefined, you can define them.) You'll probably
5527 need root permissions to create or modify the `local' tree; but your `user'
5528 tree shouldn't have such limitations.
5531 \begin_layout Enumerate
5533 \begin_inset Flex CharStyle:Code
5536 \begin_layout Plain Layout
5543 \begin_inset Flex CharStyle:Code
5546 \begin_layout Plain Layout
5553 \begin_inset Flex CharStyle:Code
5556 \begin_layout Plain Layout
5563 \begin_inset space \thinspace{}
5567 \begin_inset Newline newline
5571 \begin_inset Flex CharStyle:Code
5574 \begin_layout Plain Layout
5575 TEXMF = {$TEXMFHOME,!!$TEXMFLOCAL,!!$TEXMFMAIN}
5581 \begin_inset Newline newline
5584 But, again, most of this will
5585 \begin_inset Quotes eld
5589 \begin_inset Quotes erd
5595 \begin_layout Enumerate
5600 \begin_layout Plain Layout
5601 We'll assume henceforth that you're defining `local' TeX tree.
5602 If you're defining a user tree, just adjust as necessary.
5608 You must follow the directory structure of your existing
5609 \begin_inset Flex CharStyle:Code
5612 \begin_layout Plain Layout
5618 directory, which will be found at
5619 \begin_inset Flex CharStyle:Code
5622 \begin_layout Plain Layout
5629 For example, latex packages should go under
5630 \begin_inset Flex CharStyle:Code
5633 \begin_layout Plain Layout
5634 $TEXMFLOCAL/tex/latex/
5642 \begin_layout Enumerate
5643 Install the package.
5644 For example, you would unpack the FoilTeX tarball and copy it to
5645 \begin_inset Flex CharStyle:Code
5648 \begin_layout Plain Layout
5649 $TEXMFLOCAL/tex/latex/foiltex
5656 \begin_inset Flex CharStyle:Code
5659 \begin_layout Plain Layout
5665 directory contains various files.
5668 \begin_layout Enumerate
5670 \begin_inset Flex CharStyle:Code
5673 \begin_layout Plain Layout
5681 \begin_inset Flex CharStyle:Code
5684 \begin_layout Plain Layout
5693 \begin_layout Standard
5694 Your package is now installed and available to LaTeX.
5695 To make it available to LyX, you need to create a Layout file, if one is
5696 not already available.
5697 (See the next section.) Once you have a layout file, you need only reconfigure
5699 \begin_inset Flex CharStyle:MenuItem
5702 \begin_layout Plain Layout
5703 Tools\SpecialChar \menuseparator
5709 ) and then restart LyX.
5710 You should then see your new package—for example
5711 \begin_inset Flex CharStyle:MenuItem
5714 \begin_layout Plain Layout
5721 \begin_inset Flex CharStyle:MenuItem
5724 \begin_layout Plain Layout
5725 Document\SpecialChar \menuseparator
5732 \begin_inset Flex CharStyle:MenuItem
5735 \begin_layout Plain Layout
5745 \begin_layout Section
5749 \begin_layout Standard
5750 This section describes how to write and install your own LyX layout files
5751 and walks through the
5752 \begin_inset Flex CharStyle:Code
5755 \begin_layout Plain Layout
5761 text class format as an example.
5763 \begin_inset Flex CharStyle:Code
5766 \begin_layout Plain Layout
5772 files describe what paragraph and character styles are available for a
5773 given document class and how LyX should display them.
5774 We try to provide a thorough description of the process here; however,
5775 there are so many different types of documents supported by LaTeX classes
5776 that we can't hope to cover every different possibility or problem you
5778 (The LyX users' list is frequented by people with lots of experience with
5779 layout design who are willing to share what they've learned.)
5782 \begin_layout Standard
5783 As you prepare to write a new layout, it is extremely helpful to look at
5784 the example layouts distributed with LyX.
5785 If you use a nice LaTeX document class that might be of interest for others,
5786 too, and have a nice corresponding LyX layout, feel free to contribute
5787 the stuff to us, so we may put it into the distribution.
5789 \begin_inset CommandInset href
5791 name "section on the LyX wiki"
5792 target "http://wiki.lyx.org/Layouts/Layouts"
5796 for this kind of material.
5799 \begin_layout Standard
5800 All the tags described in this chapter are case-insensitive; this means
5802 \begin_inset Flex CharStyle:Code
5805 \begin_layout Plain Layout
5812 \begin_inset Flex CharStyle:Code
5815 \begin_layout Plain Layout
5822 \begin_inset Flex CharStyle:Code
5825 \begin_layout Plain Layout
5831 are really the same command.
5832 The possible values are printed in brackets after the feature's name.
5833 The default value if a feature isn't specified inside a text class-description
5835 \begin_inset Flex CharStyle:Code
5838 \begin_layout Plain Layout
5847 If the argument has a data type like
5848 \begin_inset Quotes eld
5852 \begin_inset Quotes erd
5856 \begin_inset Quotes eld
5860 \begin_inset Quotes erd
5863 , the default is shown like this:
5864 \begin_inset Flex CharStyle:Code
5867 \begin_layout Plain Layout
5878 \begin_layout Subsection
5880 \begin_inset CommandInset label
5882 name "sub:Layout-modules"
5889 \begin_layout Standard
5890 Similar to layout files, and new with LyX 1.6, are layout
5895 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
5896 some modules—such as the endnotes module—provide support for just such
5898 In a sense, layout modules are similar to included files—files like
5899 \begin_inset Flex CharStyle:Code
5902 \begin_layout Plain Layout
5908 —in that modules are not specific to a given document layout but may be
5909 used with many different layouts.
5910 The difference is that using a layout module does not require editing the
5912 Rather, modules are selected in the
5913 \begin_inset Flex CharStyle:MenuItem
5916 \begin_layout Plain Layout
5917 Document\SpecialChar \menuseparator
5926 \begin_layout Standard
5927 Building modules is the easiest way to get started with layout editing,
5928 since it can be as simple as adding a single new paragraph or flex inset.
5929 But modules may, in principle, contain anything a layout file can contain.
5932 \begin_layout Standard
5933 A module must begin with a line like the following:
5936 \begin_layout LyX-Code
5939 DeclareLyXModule[endnotes.sty]{Endnotes}
5942 \begin_layout Standard
5943 The mandatory argument, in curly brackets, is the name of the module, as
5945 \begin_inset Flex CharStyle:MenuItem
5948 \begin_layout Plain Layout
5949 Document\SpecialChar \menuseparator
5956 The argument in square brackets is optional: It declares any LaTeX packages
5957 on which the module depends.
5958 Please note that only packages about which LyX knows should be listed in
5959 the square brackets.
5963 \begin_layout Plain Layout
5964 The list of such packages is documented only in the source code.
5969 LyX will not check for arbitrary packages.
5972 \begin_layout Standard
5973 The module declaration should then be followed by lines like the following:
5976 \begin_layout LyX-Code
5980 \begin_layout LyX-Code
5981 #Adds an endnote command, in addition to footnotes.
5985 \begin_layout LyX-Code
5986 #You will need to add
5988 theendnotes in TeX code where you
5991 \begin_layout LyX-Code
5992 #want the endnotes to appear.
5996 \begin_layout LyX-Code
6000 \begin_layout LyX-Code
6001 #Requires: somemodule | othermodule
6004 \begin_layout LyX-Code
6005 #Excludes: badmodule
6008 \begin_layout Standard
6009 The description is used in
6010 \begin_inset Flex CharStyle:MenuItem
6013 \begin_layout Plain Layout
6014 Document\SpecialChar \menuseparator
6020 to provide the user with information about what the module does.
6022 \begin_inset Flex CharStyle:Code
6025 \begin_layout Plain Layout
6031 line is used to identify other modules with which this one must be used;
6033 \begin_inset Flex CharStyle:Code
6036 \begin_layout Plain Layout
6042 line is used to identify modules with which this one may not be used.
6043 Both are optional, and, as shown, multiple modules should be separated
6044 with the pipe symbol: |.
6045 Note that the required modules are treated disjunctively:
6049 of the required modules must be used.
6054 excluded module may be used.
6055 Note that modules are identified here by their
6059 without the .module extension.
6061 \begin_inset Flex CharStyle:Code
6064 \begin_layout Plain Layout
6071 \begin_inset Flex CharStyle:Code
6074 \begin_layout Plain Layout
6083 \begin_layout Standard
6084 After creating a new module, you will need to reconfigure and then restart
6085 LyX for the module to appear in the menu.
6086 However, changes you make to the module will be seen immediately, if you
6088 \begin_inset Flex CharStyle:MenuItem
6091 \begin_layout Plain Layout
6092 Document\SpecialChar \menuseparator
6098 , highlight something, and then hit
6099 \begin_inset Quotes eld
6103 \begin_inset Quotes erd
6109 It is strongly recommended that you save your work before doing so
6114 it is strongly recommended that you not attempt to edit modules while simultaneo
6115 usly working on documents
6118 Though of course the developers strive to keep LyX stable in such situations,
6119 syntax errors and the like in your module file could cause strange behavior.
6122 \begin_layout Subsection
6123 Supporting new document classes
6126 \begin_layout Standard
6127 There are two situations you are likely to encounter when wanting to support
6128 a new LaTeX document class, involving LaTeX2e class (
6129 \begin_inset Flex CharStyle:Code
6132 \begin_layout Plain Layout
6139 \begin_inset Flex CharStyle:Code
6142 \begin_layout Plain Layout
6149 Supporting a style file is usually fairly easy.
6150 Supporting a new document class is a bit harder.
6153 \begin_layout Subsection
6155 \begin_inset Flex CharStyle:MenuItem
6158 \begin_layout Plain Layout
6167 \begin_layout Standard
6168 If your new document class is provided as a style file that is used in conjuncti
6169 on with an existing, supported document class—for the sake of the example,
6170 we'll assume that the style file is called
6171 \begin_inset Flex CharStyle:MenuItem
6174 \begin_layout Plain Layout
6180 and it is meant to be used with
6181 \begin_inset Flex CharStyle:MenuItem
6184 \begin_layout Plain Layout
6190 , which is a standard class—start by copying the existing class's layout
6191 file into your local directory:
6194 \begin_layout LyX-Code
6195 cp report.layout ~/.lyx/layouts/myclass.layout
6198 \begin_layout Standard
6200 \begin_inset Flex CharStyle:Code
6203 \begin_layout Plain Layout
6209 and change the line:
6212 \begin_layout LyX-Code
6215 DeclareLaTeXClass{report}
6218 \begin_layout Standard
6222 \begin_layout LyX-Code
6225 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6228 \begin_layout Standard
6232 \begin_layout LyX-Code
6234 \begin_inset Newline newline
6240 \begin_inset Newline newline
6246 \begin_layout Standard
6247 near the top of the file.
6250 \begin_layout Standard
6251 Start LyX and select
6252 \begin_inset Flex CharStyle:MenuItem
6255 \begin_layout Plain Layout
6256 Tools\SpecialChar \menuseparator
6263 Then restart LyX and try creating a new document.
6265 \begin_inset Flex CharStyle:MenuItem
6268 \begin_layout Plain Layout
6274 " as a document class option in the
6275 \begin_inset Flex CharStyle:MenuItem
6278 \begin_layout Plain Layout
6279 Document\SpecialChar \menuseparator
6286 It is likely that some of the sectioning commands and such in your new
6287 class will work differently from how they worked in the base class—
6288 \begin_inset Flex CharStyle:Code
6291 \begin_layout Plain Layout
6297 in this example—so you can fiddle around with the settings for the different
6298 sections if you wish.
6301 \begin_layout Subsection
6303 \begin_inset Flex CharStyle:MenuItem
6306 \begin_layout Plain Layout
6315 \begin_layout Standard
6316 There are two possibilities here.
6317 One is that the class file is itself based upon an existing document class.
6318 For example, many thesis classes are based upon
6319 \begin_inset Flex CharStyle:MenuItem
6322 \begin_layout Plain Layout
6329 To see whether yours is, look for a line like
6332 \begin_layout LyX-Code
6338 \begin_layout Standard
6340 If so, then you may proceed largely as in the previous section, though
6341 the DeclareLaTeXClass line will be different.
6342 If your new class is thesis, and it is based upon book, then the line should
6347 \begin_layout Plain Layout
6348 And it will be easiest if you save the file to
6349 \begin_inset Flex CharStyle:Code
6352 \begin_layout Plain Layout
6358 : LyX assumes that the document class has the same name as the layout file.
6367 \begin_layout LyX-Code
6370 DeclareLaTeXClass[thesis,book]{thesis}
6373 \begin_layout Standard
6374 If, on the other hand, the new class is not based upon an existing class,
6375 you will probably have to
6376 \begin_inset Quotes eld
6380 \begin_inset Quotes erd
6384 We strongly suggest copying an existing layout file which uses a similar
6385 LaTeX class and then modifying it, if you can do so.
6386 At least use an existing file as a starting point so you can find out what
6387 items you need to worry about.
6388 Again, the specifics are covered below.
6391 \begin_layout Section
6392 Declaring a new text class
6395 \begin_layout Standard
6396 When it's finally time to get your hands dirty and create or edit your own
6397 layout file, the following sections describe what you're up against.
6398 Our advice is to go slowly, save and test often, listen to soothing music,
6399 and enjoy one or two of your favorite adult beverages; more if you are
6400 getting particularly stuck.
6401 It's really not that hard, except that the multitude of options can become
6402 overwhelming if you try to do to much in one sitting.
6403 Go have another adult beverage, just for good measure.
6406 \begin_layout Standard
6410 \begin_layout Standard
6411 Lines in a layout file which begin with a
6412 \begin_inset Flex CharStyle:Code
6415 \begin_layout Plain Layout
6422 There is one exception to this rule: all layouts should begin with lines
6426 \begin_layout LyX-Code
6429 #% Do not delete the line below; configure depends on this
6432 \begin_layout LyX-Code
6437 DeclareLaTeXClass{article}
6440 \begin_layout Standard
6441 The second line is used when you configure LyX.
6442 The layout file is read by the LaTeX script
6443 \begin_inset Flex CharStyle:Code
6446 \begin_layout Plain Layout
6452 , in a special mode where
6453 \begin_inset Flex CharStyle:Code
6456 \begin_layout Plain Layout
6463 The first line is just a LaTeX comment, and the second one contains the
6464 declaration of the text class.
6465 If these lines appear in a file named
6466 \begin_inset Flex CharStyle:Code
6469 \begin_layout Plain Layout
6475 , then they define a text class of name
6476 \begin_inset Flex CharStyle:Code
6479 \begin_layout Plain Layout
6485 (the name of the layout file) which uses the LaTeX document class
6486 \begin_inset Flex CharStyle:Code
6489 \begin_layout Plain Layout
6495 (the default is to use the same name as the layout).
6497 \begin_inset Quotes eld
6501 \begin_inset Quotes erd
6504 that appears above is used as a description of the text class in the
6505 \begin_inset Flex CharStyle:MenuItem
6508 \begin_layout Plain Layout
6509 Document\SpecialChar \menuseparator
6518 \begin_layout Standard
6519 Let's assume that you wrote your own text class that uses the
6520 \begin_inset Flex CharStyle:Code
6523 \begin_layout Plain Layout
6529 document class, but where you changed the appearance of the section headings.
6530 If you put it in a file
6531 \begin_inset Flex CharStyle:Code
6534 \begin_layout Plain Layout
6540 , the header of this file should be:
6543 \begin_layout LyX-Code
6546 #% Do not delete the line below; configure depends on this
6549 \begin_layout LyX-Code
6554 DeclareLaTeXClass[article]{article (with my own headings)}
6557 \begin_layout Standard
6558 This declares a text class
6559 \begin_inset Flex CharStyle:Code
6562 \begin_layout Plain Layout
6568 , associated with the LaTeX document class
6569 \begin_inset Flex CharStyle:Code
6572 \begin_layout Plain Layout
6579 \begin_inset Quotes eld
6582 article (with my own headings)
6583 \begin_inset Quotes erd
6587 If your text class depends on several packages, you can declare it as:
6590 \begin_layout LyX-Code
6593 #% Do not delete the line below; configure depends on this
6596 \begin_layout LyX-Code
6601 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
6604 \begin_layout Standard
6605 This indicates that your text class uses the foo.sty package.
6606 Finally, it is also possible to declare classes for DocBook code.
6607 Typical declarations will look like
6610 \begin_layout LyX-Code
6613 #% Do not delete the line below; configure depends on this
6616 \begin_layout LyX-Code
6621 DeclareDocBookClass[article]{SGML (DocBook article)}
6624 \begin_layout Standard
6625 Note that these declarations can also be given an optional parameter declaring
6626 the name of the document class (but not a list).
6629 \begin_layout Standard
6630 So, to be as explicit as possible, the form of the layout declaration is:
6633 \begin_layout LyX-Code
6638 DeclareLaTeXClass[class,package.sty]{layout description}
6641 \begin_layout Standard
6642 The class need only be specified if the name of the LaTeX class file and
6643 the name of the layout file are different; if the name of the class file
6644 is not specified, then LyX will simply assume that it is the same as the
6645 name of the layout file.
6648 \begin_layout Standard
6649 When the text class has been modified to your taste, all you have to do
6650 is to copy it either to
6651 \begin_inset Flex CharStyle:Code
6654 \begin_layout Plain Layout
6661 \begin_inset Flex CharStyle:Code
6664 \begin_layout Plain Layout
6671 \begin_inset Flex CharStyle:MenuItem
6674 \begin_layout Plain Layout
6675 Tools\SpecialChar \menuseparator
6681 , exit LyX and restart it.
6682 Then your new text class should be available along with the others.
6685 \begin_layout Standard
6686 In versions of LyX prior to 1.6, you had to restart LyX to see any changes
6687 you made to your layout files.
6688 As a result, editing layout files could be very time consuming.
6689 Beginning with 1.6, however, you can force a reload of the layout currently
6690 in use by using the LyX function
6691 \begin_inset Flex CharStyle:MenuItem
6694 \begin_layout Plain Layout
6701 There is no default binding for this function—though, of course, you can
6702 bind it to a key yourself.
6703 If you want to use this function, then, you should simply enter it in the
6709 : This is very much an `advanced feature'.
6714 recommended that you save your work before using this function.
6719 recommended that you not attempt to edit your layout while simultaneously
6720 working on a document that you care about.
6721 Use a test document.
6722 Syntax errors and the like in your layout file could cause peculiar behavior.
6723 In particular, such errors could cause LyX to regard the current layout
6724 as invalid and to attempt to switch to some other layout.
6725 The LyX team strives to keep LyX stable in such situations, but safe is
6729 \begin_layout Subsection
6733 \begin_layout Standard
6734 The first non-comment line must contain the file format number:
6737 \begin_layout Description
6738 \begin_inset Flex CharStyle:Code
6741 \begin_layout Plain Layout
6748 \begin_inset Flex CharStyle:Code
6751 \begin_layout Plain Layout
6757 ] This tag was introduced with LyX 1.4.0 (layout files of LyX 1.3.x and earlier
6758 don't have an explicit file format).
6759 The file format that is documented here is format 14.
6762 \begin_layout Subsection
6763 General text class parameters
6766 \begin_layout Standard
6767 These are the general parameters which describe the form of the entire document:
6770 \begin_layout Description
6771 \begin_inset Flex CharStyle:Code
6774 \begin_layout Plain Layout
6780 Adds information to the document preamble.
6782 \begin_inset Quotes eld
6786 \begin_inset Flex CharStyle:Code
6789 \begin_layout Plain Layout
6796 \begin_inset Quotes erd
6802 \begin_layout Description
6803 \begin_inset Flex CharStyle:Code
6806 \begin_layout Plain Layout
6812 Describes various global options supported by the document class.
6814 \begin_inset space ~
6818 \begin_inset CommandInset ref
6820 reference "sub:ClassOptions"
6826 \begin_inset Quotes eld
6830 \begin_inset Flex CharStyle:Code
6833 \begin_layout Plain Layout
6840 \begin_inset Quotes erd
6846 \begin_layout Description
6847 \begin_inset Flex CharStyle:Code
6850 \begin_layout Plain Layout
6857 \begin_inset Flex CharStyle:Code
6860 \begin_layout Plain Layout
6869 \begin_inset Flex CharStyle:Code
6872 \begin_layout Plain Layout
6878 ] Whether the class should default to having one or two columns.
6879 Can be changed in the
6880 \begin_inset Flex CharStyle:MenuItem
6883 \begin_layout Plain Layout
6884 Document\SpecialChar \menuseparator
6893 \begin_layout Description
6894 \begin_inset Flex CharStyle:Code
6897 \begin_layout Plain Layout
6903 This sequence defines a new counter.
6905 \begin_inset space ~
6909 \begin_inset CommandInset ref
6911 reference "sub:Counters"
6917 \begin_inset Quotes eld
6921 \begin_inset Flex CharStyle:Code
6924 \begin_layout Plain Layout
6931 \begin_inset Quotes erd
6937 \begin_layout Description
6938 \begin_inset Flex CharStyle:Code
6941 \begin_layout Plain Layout
6947 Sets the default font used to display the document.
6949 \begin_inset space ~
6953 \begin_inset CommandInset ref
6955 reference "sub:Font-description"
6959 for how to declare fonts.
6961 \begin_inset Quotes eld
6965 \begin_inset Flex CharStyle:Code
6968 \begin_layout Plain Layout
6975 \begin_inset Quotes erd
6981 \begin_layout Description
6982 \begin_inset Flex CharStyle:Code
6985 \begin_layout Plain Layout
6992 \begin_inset Flex CharStyle:Code
6995 \begin_layout Plain Layout
7001 Specifies a module to be included by default with this document class,
7002 which should be specified by filename without the
7003 \begin_inset Flex CharStyle:Code
7006 \begin_layout Plain Layout
7013 The user can still remove the module, but it will be active at the outset.
7014 (This applies only when new files are created, or when this class is chosen
7015 for an existing document.)
7018 \begin_layout Description
7019 \begin_inset Flex CharStyle:Code
7022 \begin_layout Plain Layout
7029 \begin_inset Flex CharStyle:Code
7032 \begin_layout Plain Layout
7038 ] This is the style that will be assigned to new paragraphs, usually
7039 \begin_inset Flex CharStyle:MenuItem
7042 \begin_layout Plain Layout
7049 This will default to the first defined style if not given, but you are
7050 highly encouraged to use this directive.
7053 \begin_layout Description
7054 \begin_inset Flex CharStyle:Code
7057 \begin_layout Plain Layout
7064 \begin_inset Flex CharStyle:Code
7067 \begin_layout Plain Layout
7073 ] Indicates that the module in question—which should be specified by filename
7075 \begin_inset Flex CharStyle:Code
7078 \begin_layout Plain Layout
7084 extension—cannot be used with this document class.
7085 This might be used in a journal-specific layout file to prevent, say, the
7087 \begin_inset Flex CharStyle:Code
7090 \begin_layout Plain Layout
7096 module that numbers theorems by section.
7101 be used in a module.
7102 Modules have their own way of excluding other modules (see
7103 \begin_inset CommandInset ref
7105 reference "sub:Layout-modules"
7112 \begin_layout Description
7113 \begin_inset Flex CharStyle:Code
7116 \begin_layout Plain Layout
7122 Defines a new float.
7124 \begin_inset space ~
7128 \begin_inset CommandInset ref
7130 reference "sub:Floats"
7136 \begin_inset Quotes eld
7140 \begin_inset Flex CharStyle:Code
7143 \begin_layout Plain Layout
7150 \begin_inset Quotes erd
7156 \begin_layout Description
7157 \begin_inset Flex CharStyle:Code
7160 \begin_layout Plain Layout
7166 As its name implies, this command allows you to include another layout
7167 definition file within yours to avoid duplicating commands.
7168 Common examples are the standard layout files, for example,
7169 \begin_inset Flex CharStyle:Code
7172 \begin_layout Plain Layout
7178 , which contains most of the basic layouts.
7181 \begin_layout Description
7182 \begin_inset Flex CharStyle:Code
7185 \begin_layout Plain Layout
7191 This section (re-)defines the layout of an inset.
7192 It can be applied to an existing inset of to a new, user-defined inset,
7194 \begin_inset space \thinspace{}
7198 \begin_inset space \space{}
7201 a new character style.
7203 \begin_inset space ~
7207 \begin_inset CommandInset ref
7209 reference "sub:Flex-insets-and"
7213 for more information.
7215 \begin_inset Quotes eld
7219 \begin_inset Flex CharStyle:Code
7222 \begin_layout Plain Layout
7229 \begin_inset Quotes erd
7235 \begin_layout Description
7236 \begin_inset Flex CharStyle:Code
7239 \begin_layout Plain Layout
7245 A string that indicates the width of the left margin on the screen, for
7247 \begin_inset Quotes eld
7251 \begin_inset Quotes erd
7257 \begin_layout Description
7258 \begin_inset Flex CharStyle:Code
7261 \begin_layout Plain Layout
7267 This command deletes an existing float.
7268 This is particularly useful when you want to suppress a float that has
7269 be defined in an input file.
7272 \begin_layout Description
7273 \begin_inset Flex CharStyle:Code
7276 \begin_layout Plain Layout
7282 This command deletes an existing style.
7283 This is particularly useful when you want to suppress a style that has
7284 be defined in an input file.
7287 \begin_layout Description
7288 \begin_inset Flex CharStyle:Code
7291 \begin_layout Plain Layout
7297 A string indicating what sort of output documents using this class will
7299 At present, the options are: `docbook', `latex', and `literate'.
7302 \begin_layout Description
7303 \begin_inset Flex CharStyle:Code
7306 \begin_layout Plain Layout
7317 \begin_inset Flex CharStyle:Code
7320 \begin_layout Plain Layout
7331 \begin_inset Flex CharStyle:Code
7334 \begin_layout Plain Layout
7341 \begin_inset Flex CharStyle:Code
7344 \begin_layout Plain Layout
7350 ] The class default pagestyle.
7351 Can be changed in the
7352 \begin_inset Flex CharStyle:MenuItem
7355 \begin_layout Plain Layout
7356 Document\SpecialChar \menuseparator
7365 \begin_layout Description
7366 \begin_inset Flex CharStyle:Code
7369 \begin_layout Plain Layout
7375 Sets the preamble for the LaTeX document.
7376 Note that this will completely override any prior
7377 \begin_inset Flex CharStyle:Code
7380 \begin_layout Plain Layout
7387 \begin_inset Flex CharStyle:Code
7390 \begin_layout Plain Layout
7398 \begin_inset Quotes eld
7402 \begin_inset Flex CharStyle:Code
7405 \begin_layout Plain Layout
7412 \begin_inset Quotes erd
7418 \begin_layout Description
7419 \begin_inset Flex CharStyle:Code
7422 \begin_layout Plain Layout
7429 \begin_inset Flex CharStyle:Code
7432 \begin_layout Plain Layout
7439 \begin_inset Flex CharStyle:Code
7442 \begin_layout Plain Layout
7451 \begin_inset Flex CharStyle:Code
7454 \begin_layout Plain Layout
7460 ] Whether the class already provides the feature
7461 \begin_inset Flex CharStyle:Code
7464 \begin_layout Plain Layout
7471 A feature is in general the name of a package (
7472 \begin_inset Flex CharStyle:Code
7475 \begin_layout Plain Layout
7482 \begin_inset Flex CharStyle:Code
7485 \begin_layout Plain Layout
7491 , \SpecialChar \ldots{}
7493 \begin_inset Flex CharStyle:Code
7496 \begin_layout Plain Layout
7503 \begin_inset Flex CharStyle:Code
7506 \begin_layout Plain Layout
7512 ,\SpecialChar \ldots{}
7513 ); the complete list of supported features is unfortunately not documented
7514 outside the LyX source code—but see
7515 \begin_inset Flex CharStyle:Code
7518 \begin_layout Plain Layout
7524 if you're interested.
7526 \begin_inset Flex CharStyle:MenuItem
7529 \begin_layout Plain Layout
7530 Help\SpecialChar \menuseparator
7536 also gives an overview of the supported packages.
7539 \begin_layout Description
7540 \begin_inset Flex CharStyle:Code
7543 \begin_layout Plain Layout
7550 \begin_inset Flex CharStyle:Code
7553 \begin_layout Plain Layout
7559 ] Indicates that this layout provides the functionality of the module mentioned,
7560 which should be specified by the filename without the
7561 \begin_inset Flex CharStyle:Code
7564 \begin_layout Plain Layout
7571 This will typically be used if the layout includes the module directly,
7572 rather than using the
7573 \begin_inset Flex CharStyle:Code
7576 \begin_layout Plain Layout
7582 tag to indicate that it ought to be used.
7583 It could be used in a module that provided an alternate implementation
7584 of the same functionality.
7587 \begin_layout Description
7588 \begin_inset Flex CharStyle:Code
7591 \begin_layout Plain Layout
7598 \begin_inset Flex CharStyle:Code
7601 \begin_layout Plain Layout
7607 ] Whether the class requires the feature
7608 \begin_inset Flex CharStyle:Code
7611 \begin_layout Plain Layout
7618 Multiple features must be separated by commas.
7619 Note that you can only request supported features.
7622 \begin_layout Description
7623 \begin_inset Flex CharStyle:Code
7626 \begin_layout Plain Layout
7632 A string that indicates the width of the right margin on the screen, for
7634 \begin_inset Quotes eld
7638 \begin_inset Quotes erd
7644 \begin_layout Description
7645 \begin_inset Flex CharStyle:Code
7648 \begin_layout Plain Layout
7654 Sets which divisions get numbered.
7656 \begin_inset Flex CharStyle:Code
7659 \begin_layout Plain Layout
7668 \begin_layout Description
7669 \begin_inset Flex CharStyle:Code
7672 \begin_layout Plain Layout
7681 \begin_inset Flex CharStyle:Code
7684 \begin_layout Plain Layout
7695 \begin_inset Flex CharStyle:Code
7698 \begin_layout Plain Layout
7704 ] Whether the class-default should be printing on one or both sides of the
7706 Can be changed in the
7707 \begin_inset Flex CharStyle:MenuItem
7710 \begin_layout Plain Layout
7711 Document\SpecialChar \menuseparator
7720 \begin_layout Description
7721 \begin_inset Flex CharStyle:Code
7724 \begin_layout Plain Layout
7730 This sequence defines a new paragraph style.
7731 If the style already exists, it will redefine some of its parameters instead.
7733 \begin_inset space ~
7737 \begin_inset CommandInset ref
7739 reference "sub:Paragraph-Styles"
7745 \begin_inset Quotes eld
7749 \begin_inset Flex CharStyle:Code
7752 \begin_layout Plain Layout
7759 \begin_inset Quotes erd
7765 \begin_layout Description
7766 \begin_inset Flex CharStyle:Code
7769 \begin_layout Plain Layout
7776 \begin_inset Flex CharStyle:Code
7779 \begin_layout Plain Layout
7785 ] The name of the command or environment to be used with
7786 \begin_inset Flex CharStyle:Code
7789 \begin_layout Plain Layout
7798 \begin_layout Description
7799 \begin_inset Flex CharStyle:Code
7802 \begin_layout Plain Layout
7809 \begin_inset Flex CharStyle:Code
7812 \begin_layout Plain Layout
7821 \begin_inset Flex CharStyle:Code
7824 \begin_layout Plain Layout
7830 ] Indicates what kind of markup is used to define the title of a document.
7832 \begin_inset Flex CharStyle:Code
7835 \begin_layout Plain Layout
7841 means that the macro with name
7842 \begin_inset Flex CharStyle:Code
7845 \begin_layout Plain Layout
7851 will be inserted after the last layout which has
7852 \begin_inset Quotes eld
7856 \begin_inset Flex CharStyle:Code
7859 \begin_layout Plain Layout
7866 \begin_inset Quotes erd
7871 \begin_inset Flex CharStyle:Code
7874 \begin_layout Plain Layout
7880 corresponds to the case where the block of paragraphs which have
7881 \begin_inset Quotes eld
7885 \begin_inset Flex CharStyle:Code
7888 \begin_layout Plain Layout
7895 \begin_inset Quotes erd
7898 should be enclosed into the
7899 \begin_inset Flex CharStyle:Code
7902 \begin_layout Plain Layout
7911 \begin_layout Description
7912 \begin_inset Flex CharStyle:Code
7915 \begin_layout Plain Layout
7921 Sets which divisions are included in the table of contents.
7923 \begin_inset Flex CharStyle:Code
7926 \begin_layout Plain Layout
7935 \begin_layout Subsection
7936 \begin_inset Flex CharStyle:Code
7939 \begin_layout Plain Layout
7946 \begin_inset CommandInset label
7948 name "sub:ClassOptions"
7955 \begin_layout Standard
7957 \begin_inset Flex CharStyle:Code
7960 \begin_layout Plain Layout
7966 section can contain the following entries:
7969 \begin_layout Description
7970 \begin_inset Flex CharStyle:Code
7973 \begin_layout Plain Layout
7980 \begin_inset Flex CharStyle:Code
7983 \begin_layout Plain Layout
7989 ] The list of available font sizes for the document's main font, separated
7991 \begin_inset Quotes eld
7995 \begin_inset Flex CharStyle:Code
7998 \begin_layout Plain Layout
8005 \begin_inset Quotes erd
8011 \begin_layout Description
8012 \begin_inset Flex CharStyle:Code
8015 \begin_layout Plain Layout
8021 Used to set the DTD line with XML-based output classes.
8023 \begin_inset space \thinspace{}
8027 \begin_inset Quotes eld
8030 -//OASIS//DTD DocBook V4.2//EN
8031 \begin_inset Quotes erd
8037 \begin_layout Description
8038 \begin_inset Flex CharStyle:Code
8041 \begin_layout Plain Layout
8048 \begin_inset Flex CharStyle:Code
8051 \begin_layout Plain Layout
8052 string="empty|plain|headings|fancy"
8057 ] The list of available page styles, separated by
8058 \begin_inset Quotes eld
8062 \begin_inset Flex CharStyle:Code
8065 \begin_layout Plain Layout
8072 \begin_inset Quotes erd
8078 \begin_layout Description
8079 \begin_inset Flex CharStyle:Code
8082 \begin_layout Plain Layout
8089 \begin_inset Flex CharStyle:Code
8092 \begin_layout Plain Layout
8098 ] Some document class options, separated by a comma, that will be added
8099 to the optional part of the
8100 \begin_inset Flex CharStyle:Code
8103 \begin_layout Plain Layout
8114 \begin_layout Standard
8116 \begin_inset Flex CharStyle:Code
8119 \begin_layout Plain Layout
8125 section must end with
8126 \begin_inset Quotes eld
8130 \begin_inset Flex CharStyle:Code
8133 \begin_layout Plain Layout
8140 \begin_inset Quotes erd
8146 \begin_layout Subsection
8148 \begin_inset CommandInset label
8150 name "sub:Paragraph-Styles"
8157 \begin_layout Standard
8158 A paragraph style description looks like this:
8162 \begin_layout Plain Layout
8163 Note that this will either define a new layout or modify an existing one.
8171 \begin_layout LyX-Code
8178 \begin_layout LyX-Code
8182 \begin_layout LyX-Code
8186 \begin_layout Standard
8187 where the following commands are allowed:
8190 \begin_layout Description
8191 \begin_inset Flex CharStyle:Code
8194 \begin_layout Plain Layout
8201 \begin_inset Flex CharStyle:Code
8204 \begin_layout Plain Layout
8209 , left, right, center
8214 ] Paragraph alignment.
8217 \begin_layout Description
8218 \begin_inset Flex CharStyle:Code
8221 \begin_layout Plain Layout
8228 \begin_inset Flex CharStyle:Code
8231 \begin_layout Plain Layout
8236 , left, right, center
8241 ] A comma separated list of permitted alignments.
8242 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
8244 For example a right-aligned or centered enumeration isn't possible.)
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
8271 \begin_layout Plain Layout
8272 Note that a `float' here is a real number, such as: 1.5.
8277 The vertical space with which the last of a chain of paragraphs with this
8278 layout is separated from the following paragraph.
8279 If the next paragraph has another layout, the separations are not simply
8280 added, but the maximum is taken.
8283 \begin_layout Description
8284 \begin_inset Flex CharStyle:Code
8287 \begin_layout Plain Layout
8294 \begin_inset Flex CharStyle:Code
8297 \begin_layout Plain Layout
8303 The category for this style.
8304 This is used to group related styles in the Layout combobox on the toolbar.
8305 Any string can be used, but you may want to use existing categories with
8310 \begin_layout Description
8311 \begin_inset Flex CharStyle:Code
8314 \begin_layout Plain Layout
8320 Depth of XML command.
8321 Used only with XML-type formats.
8324 \begin_layout Description
8325 \begin_inset Flex CharStyle:Code
8328 \begin_layout Plain Layout
8335 \begin_inset CommandInset label
8337 name "des:CopyStyle"
8342 \begin_inset Flex CharStyle:Code
8345 \begin_layout Plain Layout
8351 Copies all the features of an existing style into the current one.
8355 \begin_layout Description
8356 \begin_inset Flex CharStyle:Code
8359 \begin_layout Plain Layout
8365 The name of a style whose preamble should be output
8370 This allows to ensure some ordering of the preamble snippets when macros
8371 definitions depend on one another.
8375 \begin_layout Plain Layout
8376 Note that, besides that functionality, there is no way to ensure any ordering
8378 The ordering that you see in a given version of LyX may change without
8379 warning in later versions.
8387 \begin_layout Description
8388 \begin_inset Flex CharStyle:Code
8391 \begin_layout Plain Layout
8398 \begin_inset Flex CharStyle:Code
8401 \begin_layout Plain Layout
8406 , Box, Filled_Box, Static
8411 ] The type of label that stands at the end of the paragraph (or sequence
8413 \begin_inset Flex CharStyle:Code
8416 \begin_layout Plain Layout
8423 \begin_inset Flex CharStyle:Code
8426 \begin_layout Plain Layout
8433 \begin_inset Flex CharStyle:Code
8436 \begin_layout Plain Layout
8443 \begin_inset Flex CharStyle:Code
8446 \begin_layout Plain Layout
8454 \begin_inset Flex CharStyle:Code
8457 \begin_layout Plain Layout
8464 \begin_inset Quotes eld
8468 \begin_inset Quotes erd
8472 \begin_inset Flex CharStyle:Code
8475 \begin_layout Plain Layout
8482 \begin_inset Flex CharStyle:Code
8485 \begin_layout Plain Layout
8486 \begin_inset space ~
8495 \begin_inset space ~
8498 black) square suitable for end of proof markers,
8499 \begin_inset Flex CharStyle:Code
8502 \begin_layout Plain Layout
8508 is an explicit text string.
8511 \begin_layout Description
8512 \begin_inset Flex CharStyle:Code
8515 \begin_layout Plain Layout
8522 \begin_inset Flex CharStyle:Code
8525 \begin_layout Plain Layout
8531 ] The string used for a label with a
8532 \begin_inset Flex CharStyle:Code
8535 \begin_layout Plain Layout
8542 \begin_inset Flex CharStyle:Code
8545 \begin_layout Plain Layout
8555 \begin_layout Description
8556 \begin_inset Flex CharStyle:Code
8559 \begin_layout Plain Layout
8566 \begin_inset Flex CharStyle:Code
8569 \begin_layout Plain Layout
8580 \begin_inset Flex CharStyle:Code
8583 \begin_layout Plain Layout
8592 \begin_layout Description
8593 \begin_inset Flex CharStyle:Code
8596 \begin_layout Plain Layout
8603 \begin_inset Flex CharStyle:Code
8606 \begin_layout Plain Layout
8616 ] With this parameter the
8617 \begin_inset Flex CharStyle:MenuItem
8620 \begin_layout Plain Layout
8627 \begin_inset Quotes eld
8630 Vertical space above
8631 \begin_inset Quotes erd
8635 \begin_inset Flex CharStyle:MenuItem
8638 \begin_layout Plain Layout
8639 Edit\SpecialChar \menuseparator
8641 \begin_inset space ~
8649 dialog can be set when initializing a paragraph with this style.
8653 \begin_layout Plain Layout
8656 Note from Jean-Marc:
8658 I'm not sure that this setting has much use, and it should probably be
8659 removed in later versions.
8667 \begin_layout Description
8668 \begin_inset Flex CharStyle:Code
8671 \begin_layout Plain Layout
8677 The font used for both the text body
8683 \begin_inset space ~
8687 \begin_inset CommandInset ref
8689 reference "sub:Font-description"
8694 Note that defining this font automatically defines the
8695 \begin_inset Flex CharStyle:Code
8698 \begin_layout Plain Layout
8705 So you should define this one first if you also want to define
8706 \begin_inset Flex CharStyle:Code
8709 \begin_layout Plain Layout
8718 \begin_layout Description
8719 \begin_inset Flex CharStyle:Code
8722 \begin_layout Plain Layout
8729 \begin_inset CommandInset label
8731 name "des:FreeSpacing"
8738 \begin_inset Flex CharStyle:Code
8741 \begin_layout Plain Layout
8752 \begin_inset Flex CharStyle:Code
8755 \begin_layout Plain Layout
8761 ] Usually LyX doesn't allow you to insert more than one space between words,
8762 since a space is considered as the separation between two words, not a
8763 character or symbol of its own.
8764 This is a very fine thing but sometimes annoying, for example, when typing
8765 program code or plain LaTeX code.
8767 \begin_inset Flex CharStyle:Code
8770 \begin_layout Plain Layout
8777 Note that LyX will create protected blanks for the additional blanks when
8778 in another mode than LaTeX-mode.
8781 \begin_layout Description
8782 \begin_inset Flex CharStyle:Code
8785 \begin_layout Plain Layout
8791 Language dependent information to be included in the LaTeX preamble when
8793 Note that this will completely override any prior
8794 \begin_inset Flex CharStyle:Code
8797 \begin_layout Plain Layout
8805 \begin_inset Quotes eld
8809 \begin_inset Flex CharStyle:Code
8812 \begin_layout Plain Layout
8819 \begin_inset Quotes erd
8823 The contents of this tag will occur once in the LaTeX preamble for each
8824 language used by the document.
8825 Each time, the following substitutions are made:
8829 \begin_layout Itemize
8830 \begin_inset Flex CharStyle:Code
8833 \begin_layout Plain Layout
8839 is replaced by the language name (as used by the babel package).
8842 \begin_layout Itemize
8844 \begin_inset Quotes eld
8848 \begin_inset Quotes erd
8852 \begin_inset Flex CharStyle:Code
8855 \begin_layout Plain Layout
8861 replaces its argument by the translation of the argument to the current
8865 \begin_layout Standard
8866 This preamble snippet will only be used if the document contains more than
8867 one language and the babel package is used.
8871 \begin_layout Description
8872 \begin_inset Flex CharStyle:Code
8875 \begin_layout Plain Layout
8882 \begin_inset Flex CharStyle:Code
8885 \begin_layout Plain Layout
8891 , but this preamble snippet occurs independently from the babel package,
8892 and only for the document language.
8894 \begin_inset Quotes eld
8898 \begin_inset Flex CharStyle:Code
8901 \begin_layout Plain Layout
8908 \begin_inset Quotes erd
8915 \begin_layout Standard
8916 If the style defines text that appears in the typeset document, it may use
8918 \begin_inset Flex CharStyle:Code
8921 \begin_layout Plain Layout
8928 \begin_inset Flex CharStyle:Code
8931 \begin_layout Plain Layout
8937 to support non-english and even multilanguage documents correctly.
8938 The following excerpt (from the
8939 \begin_inset Flex CharStyle:Code
8942 \begin_layout Plain Layout
8948 file) shows how this works:
8951 \begin_layout LyX-Code
8955 \begin_layout LyX-Code
8958 theoremstyle{remark}
8961 \begin_layout LyX-Code
8964 newtheorem{claim}[thm]{
8971 \begin_layout LyX-Code
8975 \begin_layout LyX-Code
8979 \begin_layout LyX-Code
8984 claimname}{_(Claim)}
8987 \begin_layout LyX-Code
8991 \begin_layout LyX-Code
8995 \begin_layout LyX-Code
8999 \begin_layout LyX-Code
9008 claimname}{_(Claim)}}
9011 \begin_layout LyX-Code
9015 \begin_layout Standard
9016 The key to correct translation of the user visible text is the definition
9018 \begin_inset Flex CharStyle:Code
9021 \begin_layout Plain Layout
9029 in the language preamble.
9030 This command holds the name of the theorem that will appear in the output.
9032 \begin_inset Flex CharStyle:Code
9035 \begin_layout Plain Layout
9041 then uses the commands offered by the babel package to redefine
9042 \begin_inset Flex CharStyle:Code
9045 \begin_layout Plain Layout
9053 for each used language in multilanguage documents.
9057 \begin_layout Description
9058 \begin_inset Flex CharStyle:Code
9061 \begin_layout Plain Layout
9067 [[FIXME]] (Used only with XML-type formats.)
9070 \begin_layout Description
9071 \begin_inset Flex CharStyle:Code
9074 \begin_layout Plain Layout
9081 \begin_inset Flex CharStyle:Code
9084 \begin_layout Plain Layout
9090 If 1, marks the layout as being part of a title block (see also the
9091 \begin_inset Flex CharStyle:Code
9094 \begin_layout Plain Layout
9101 \begin_inset Flex CharStyle:Code
9104 \begin_layout Plain Layout
9113 \begin_layout Description
9114 \begin_inset Flex CharStyle:Code
9117 \begin_layout Plain Layout
9124 \begin_inset Flex CharStyle:Code
9127 \begin_layout Plain Layout
9133 ] This provides extra space between paragraphs that have the same layout.
9134 If you put other layouts into an environment, each is separated with the
9136 \begin_inset Flex CharStyle:Code
9139 \begin_layout Plain Layout
9146 But the whole items of the environment are additionally separated with
9148 \begin_inset Flex CharStyle:Code
9151 \begin_layout Plain Layout
9163 \begin_layout Description
9164 \begin_inset Flex CharStyle:Code
9167 \begin_layout Plain Layout
9173 [[FIXME]] (Used only with XML-type formats.)
9176 \begin_layout Description
9177 \begin_inset Flex CharStyle:Code
9180 \begin_layout Plain Layout
9187 \begin_inset CommandInset label
9189 name "des:KeepEmpty"
9196 \begin_inset Flex CharStyle:Code
9199 \begin_layout Plain Layout
9210 \begin_inset Flex CharStyle:Code
9213 \begin_layout Plain Layout
9219 ] Usually LyX does not allow you to leave a paragraph empty, since it would
9220 lead to empty LaTeX output.
9221 There are some cases where this could be desirable however: in a letter
9222 template, the required fields can be provided as empty fields, so that
9223 people do not forget them; in some special classes, a layout can be used
9224 as some kind of break, which does not contain actual text.
9227 \begin_layout Description
9228 \begin_inset Flex CharStyle:Code
9231 \begin_layout Plain Layout
9237 [float=0] The vertical space between the label and the text body.
9238 Only used for labels that are above the text body (
9239 \begin_inset Flex CharStyle:Code
9242 \begin_layout Plain Layout
9249 \begin_inset Flex CharStyle:Code
9252 \begin_layout Plain Layout
9253 Centered_Top_Environment
9261 \begin_layout Description
9262 \begin_inset Flex CharStyle:Code
9265 \begin_layout Plain Layout
9272 \begin_inset Flex CharStyle:Code
9275 \begin_layout Plain Layout
9282 \begin_inset Newline newline
9285 The name of the counter for automatic numbering (see Section
9286 \begin_inset CommandInset ref
9288 reference "sub:Counters"
9293 This must be given if
9294 \begin_inset Flex CharStyle:Code
9297 \begin_layout Plain Layout
9304 \begin_inset Flex CharStyle:Code
9307 \begin_layout Plain Layout
9316 \begin_layout Description
9317 \begin_inset Flex CharStyle:Code
9320 \begin_layout Plain Layout
9326 The font used for the label.
9328 \begin_inset space ~
9332 \begin_inset CommandInset ref
9334 reference "sub:Font-description"
9341 \begin_layout Description
9342 \begin_inset Flex CharStyle:Code
9345 \begin_layout Plain Layout
9351 Text that indicates how far a label should be indented.
9354 \begin_layout Description
9355 \begin_inset Flex CharStyle:Code
9358 \begin_layout Plain Layout
9365 \begin_inset Flex CharStyle:Code
9368 \begin_layout Plain Layout
9374 ] The horizontal space between the label and the text body.
9375 Only used for labels that are not above the text body.
9378 \begin_layout Description
9379 \begin_inset Flex CharStyle:Code
9382 \begin_layout Plain Layout
9389 \begin_inset Flex CharStyle:Code
9392 \begin_layout Plain Layout
9398 ] The string used for a label with a
9399 \begin_inset Flex CharStyle:Code
9402 \begin_layout Plain Layout
9410 \begin_inset Flex CharStyle:Code
9413 \begin_layout Plain Layout
9419 is set, this string can be contain the special formatting commands described
9421 \begin_inset CommandInset ref
9423 reference "sub:Counters"
9431 \begin_layout Plain Layout
9432 For the sake of backwards compatibility, the string
9433 \begin_inset Flex CharStyle:Code
9436 \begin_layout Plain Layout
9446 will be replaced by the expanded
9447 \begin_inset Flex CharStyle:Code
9450 \begin_layout Plain Layout
9457 \begin_inset Flex CharStyle:Code
9460 \begin_layout Plain Layout
9469 This feature is now obsolete and should be replaced by the mechanisms of
9471 \begin_inset CommandInset ref
9473 reference "sub:Counters"
9485 \begin_layout Description
9486 \begin_inset Flex CharStyle:Code
9489 \begin_layout Plain Layout
9496 \begin_inset Flex CharStyle:Code
9499 \begin_layout Plain Layout
9505 ] This is used inside the appendix instead of
9506 \begin_inset Flex CharStyle:Code
9509 \begin_layout Plain Layout
9517 \begin_inset Flex CharStyle:Code
9520 \begin_layout Plain Layout
9527 \begin_inset Flex CharStyle:Code
9530 \begin_layout Plain Layout
9539 \begin_layout Description
9540 \begin_inset Flex CharStyle:Code
9543 \begin_layout Plain Layout
9549 [FIXME] (Used only with XML-type formats.)
9552 \begin_layout Description
9553 \begin_inset Flex CharStyle:Code
9556 \begin_layout Plain Layout
9563 \begin_inset Flex CharStyle:Code
9566 \begin_layout Plain Layout
9571 , Manual, Static, Top_Environment,
9572 \begin_inset Newline newline
9575 Centered_Top_Environment, Sensitive, Counter
9581 \begin_inset Newline newline
9585 \begin_inset Flex CharStyle:Code
9588 \begin_layout Plain Layout
9594 means the label is the very first word (up to the first real blank).
9598 \begin_layout Plain Layout
9599 Use protected spaces if you want more than one word as the label.
9605 \begin_inset Flex CharStyle:Code
9608 \begin_layout Plain Layout
9614 means it is defined in the layout (see
9615 \begin_inset Flex CharStyle:Code
9618 \begin_layout Plain Layout
9626 \begin_inset Flex CharStyle:Code
9629 \begin_layout Plain Layout
9636 \begin_inset Flex CharStyle:Code
9639 \begin_layout Plain Layout
9640 Centered_Top_Environment
9645 are special cases of
9646 \begin_inset Flex CharStyle:Code
9649 \begin_layout Plain Layout
9656 The label will be printed above the paragraph, but only at the top of an
9657 environment or the top of a chain of paragraphs with this layout.
9658 Usage is for example the
9659 \begin_inset Flex CharStyle:MenuItem
9662 \begin_layout Plain Layout
9669 \begin_inset Flex CharStyle:MenuItem
9672 \begin_layout Plain Layout
9679 This is also the case for
9680 \begin_inset Flex CharStyle:Code
9683 \begin_layout Plain Layout
9689 labels with latex type
9690 \begin_inset Flex CharStyle:Code
9693 \begin_layout Plain Layout
9699 , in order to make layouts for theorems work correctly.
9701 \begin_inset Flex CharStyle:Code
9704 \begin_layout Plain Layout
9710 is a special case for the caption-labels
9711 \begin_inset Quotes eld
9715 \begin_inset Quotes erd
9719 \begin_inset Quotes eld
9723 \begin_inset Quotes erd
9728 \begin_inset Flex CharStyle:Code
9731 \begin_layout Plain Layout
9737 means the (hardcoded) label string depends on the kind of float.
9739 \begin_inset Flex CharStyle:Code
9742 \begin_layout Plain Layout
9748 label type defines automatically numbered labels.
9750 \begin_inset CommandInset ref
9752 reference "sub:Counters"
9759 \begin_layout Description
9760 \begin_inset Flex CharStyle:Code
9763 \begin_layout Plain Layout
9769 The name of the corresponding LaTeX stuff.
9770 Either the environment or command name.
9773 \begin_layout Description
9774 \begin_inset Flex CharStyle:Code
9777 \begin_layout Plain Layout
9783 An optional parameter for the corresponding
9784 \begin_inset Flex CharStyle:Code
9787 \begin_layout Plain Layout
9794 This parameter cannot be changed from within LyX.
9797 \begin_layout Description
9798 \begin_inset Flex CharStyle:Code
9801 \begin_layout Plain Layout
9808 \begin_inset CommandInset label
9810 name "des:LatexType"
9815 \begin_inset Flex CharStyle:Code
9818 \begin_layout Plain Layout
9823 , Command, Environment, Item_Environment,
9829 \begin_inset Flex CharStyle:Code
9832 \begin_layout Plain Layout
9838 ] How the layout should be translated into LaTeX.
9840 \begin_inset Flex CharStyle:Code
9843 \begin_layout Plain Layout
9849 means nothing special.
9851 \begin_inset Flex CharStyle:Code
9854 \begin_layout Plain Layout
9861 \begin_inset Flex CharStyle:Code
9864 \begin_layout Plain Layout
9871 {\SpecialChar \ldots{}
9878 \begin_inset Flex CharStyle:Code
9881 \begin_layout Plain Layout
9888 \begin_inset Flex CharStyle:Code
9891 \begin_layout Plain Layout
9898 }\SpecialChar \ldots{}
9912 \begin_inset Flex CharStyle:Code
9915 \begin_layout Plain Layout
9922 \begin_inset Flex CharStyle:Code
9925 \begin_layout Plain Layout
9932 \begin_inset Flex CharStyle:Code
9935 \begin_layout Plain Layout
9943 is generated for each paragraph of this environment.
9945 \begin_inset Flex CharStyle:Code
9948 \begin_layout Plain Layout
9955 \begin_inset Flex CharStyle:Code
9958 \begin_layout Plain Layout
9965 \begin_inset Flex CharStyle:Code
9968 \begin_layout Plain Layout
9974 is passed as an argument to the environment.
9976 \begin_inset Flex CharStyle:Code
9979 \begin_layout Plain Layout
9985 can be defined in the
9986 \begin_inset Flex CharStyle:MenuItem
9989 \begin_layout Plain Layout
9994 ayout\SpecialChar \menuseparator
10006 \begin_inset Flex CharStyle:Code
10009 \begin_layout Plain Layout
10017 is perhaps a bit misleading, since these rules apply to SGML classes, too.
10018 Visit the SGML class files for specific examples.
10021 \begin_layout Standard
10022 Putting the last few things together, the LaTeX output will be either:
10025 \begin_layout LyX-Code
10028 latexname[latexparam]{\SpecialChar \ldots{}
10032 \begin_layout Standard
10036 \begin_layout LyX-Code
10039 begin{latexname}[latexparam] \SpecialChar \ldots{}
10045 \begin_layout Standard
10046 depending upon the LaTeX type.
10049 \begin_layout Description
10050 \begin_inset Flex CharStyle:Code
10053 \begin_layout Plain Layout
10060 \begin_inset Flex CharStyle:Code
10063 \begin_layout Plain Layout
10069 ] If you put layouts into environments, the leftmargins are not simply added,
10070 but added with a factor
10071 \begin_inset Formula $\frac{4}{depth+4}$
10075 Note that this parameter is also used when the margin is defined as
10076 \begin_inset Flex CharStyle:Code
10079 \begin_layout Plain Layout
10086 \begin_inset Flex CharStyle:Code
10089 \begin_layout Plain Layout
10096 Then it is added to the manual or dynamic margin.
10098 \begin_inset Newline newline
10101 The argument is passed as a string.
10103 \begin_inset Quotes eld
10107 \begin_inset Flex CharStyle:Code
10110 \begin_layout Plain Layout
10117 \begin_inset Quotes erd
10120 means that the paragraph is indented with the width of
10121 \begin_inset Quotes eld
10125 \begin_inset Flex CharStyle:Code
10128 \begin_layout Plain Layout
10135 \begin_inset Quotes erd
10138 in the normal font.
10139 You can get a negative width by prefixing the string with
10140 \begin_inset Quotes eld
10144 \begin_inset Flex CharStyle:Code
10147 \begin_layout Plain Layout
10154 \begin_inset Quotes erd
10158 This way was chosen so that the look is the same with each used screen
10163 \begin_layout Description
10164 \begin_inset Flex CharStyle:Code
10167 \begin_layout Plain Layout
10174 \begin_inset Flex CharStyle:Code
10177 \begin_layout Plain Layout
10182 , Manual, Dynamic, First_Dynamic, Right_Address_Box
10188 \begin_inset Newline newline
10191 The kind of margin that the layout has on the left side.
10193 \begin_inset Flex CharStyle:Code
10196 \begin_layout Plain Layout
10202 just means a fixed margin.
10204 \begin_inset Flex CharStyle:Code
10207 \begin_layout Plain Layout
10213 means that the left margin depends on the string entered in the
10214 \begin_inset Flex CharStyle:MenuItem
10217 \begin_layout Plain Layout
10218 Edit\SpecialChar \menuseparator
10220 \begin_inset space ~
10229 This is used to typeset nice lists without tabulators.
10231 \begin_inset Flex CharStyle:Code
10234 \begin_layout Plain Layout
10240 means that the margin depends on the size of the label.
10241 This is used for automatic enumerated headlines.
10242 It is obvious that the headline
10243 \begin_inset Quotes eld
10246 5.4.3.2.1 Very long headline
10247 \begin_inset Quotes erd
10250 must have a wider left margin (as wide as
10251 \begin_inset Quotes eld
10255 \begin_inset Quotes erd
10258 plus the space) than
10259 \begin_inset Quotes eld
10262 3.2 Very long headline
10263 \begin_inset Quotes erd
10267 \begin_inset Quotes eld
10271 \begin_inset Quotes erd
10274 are not able to do this.
10276 \begin_inset Flex CharStyle:Code
10279 \begin_layout Plain Layout
10285 is similar, but only the very first row of the paragraph is dynamic, while
10286 the others are static; this is used, for example, for descriptions.
10288 \begin_inset Flex CharStyle:Code
10291 \begin_layout Plain Layout
10297 means the margin is chosen in a way that the longest row of this paragraph
10298 fits to the right margin.
10299 This is used to typeset an address on the right edge of the page.
10302 \begin_layout Description
10303 \begin_inset Flex CharStyle:Code
10306 \begin_layout Plain Layout
10313 \begin_inset Flex CharStyle:Code
10316 \begin_layout Plain Layout
10325 \begin_inset Flex CharStyle:Code
10328 \begin_layout Plain Layout
10334 ] Whether fragile commands in this layout should be
10335 \begin_inset Flex CharStyle:Code
10338 \begin_layout Plain Layout
10351 whether this command should itself be protected.)
10354 \begin_layout Description
10355 \begin_inset Flex CharStyle:Code
10358 \begin_layout Plain Layout
10365 \begin_inset Flex CharStyle:Code
10368 \begin_layout Plain Layout
10375 \begin_inset Flex CharStyle:Code
10378 \begin_layout Plain Layout
10386 ] Whether newlines are translated into LaTeX newlines (
10387 \begin_inset Flex CharStyle:Code
10390 \begin_layout Plain Layout
10401 The translation can be switched off to allow more comfortable LaTeX editing
10405 \begin_layout Description
10406 \begin_inset Flex CharStyle:Code
10409 \begin_layout Plain Layout
10416 \begin_inset Flex CharStyle:Code
10419 \begin_layout Plain Layout
10426 \begin_inset Flex CharStyle:Code
10429 \begin_layout Plain Layout
10437 ] Whether the following Paragraph is allowed to indent its very first row.
10439 \begin_inset Flex CharStyle:Code
10442 \begin_layout Plain Layout
10448 means that it is not allowed to do so;
10449 \begin_inset Flex CharStyle:Code
10452 \begin_layout Plain Layout
10458 means it could do so if it wants to.
10461 \begin_layout Description
10462 \begin_inset Flex CharStyle:Code
10465 \begin_layout Plain Layout
10471 Name of a layout that has replaced this layout.
10472 This is used to rename a layout, while keeping backward compatibility.
10475 \begin_layout Description
10476 \begin_inset Flex CharStyle:Code
10479 \begin_layout Plain Layout
10486 \begin_inset Flex CharStyle:Code
10489 \begin_layout Plain Layout
10495 ] The number of optional arguments that can be used with this layout.
10496 This is useful for things like section headings, and only makes sense with
10500 \begin_layout Description
10501 \begin_inset Flex CharStyle:Code
10504 \begin_layout Plain Layout
10511 \begin_inset Flex CharStyle:Code
10514 \begin_layout Plain Layout
10520 ] The indent of the very first line of a paragraph.
10522 \begin_inset Flex CharStyle:Code
10525 \begin_layout Plain Layout
10531 will be fixed for a certain layout.
10532 The exception is Standard layout, since the indentation of a Standard layout
10533 paragraph can be prohibited with
10534 \begin_inset Flex CharStyle:Code
10537 \begin_layout Plain Layout
10544 Also, Standard layout paragraphs inside environments use the
10545 \begin_inset Flex CharStyle:Code
10548 \begin_layout Plain Layout
10554 of the environment, not their native one.
10555 For example, Standard paragraphs inside an enumeration are not indented.
10558 \begin_layout Description
10559 \begin_inset Flex CharStyle:Code
10562 \begin_layout Plain Layout
10569 \begin_inset Flex CharStyle:Code
10572 \begin_layout Plain Layout
10578 ] The vertical space between two paragraphs of this layout.
10581 \begin_layout Description
10582 \begin_inset Flex CharStyle:Code
10585 \begin_layout Plain Layout
10592 \begin_inset Flex CharStyle:Code
10595 \begin_layout Plain Layout
10601 ] LyX allows the user to choose either
10602 \begin_inset Quotes eld
10606 \begin_inset Quotes erd
10610 \begin_inset Quotes eld
10614 \begin_inset Quotes erd
10617 to typeset a document.
10619 \begin_inset Quotes eld
10623 \begin_inset Quotes erd
10626 is chosen, this value is completely ignored.
10628 \begin_inset Quotes eld
10632 \begin_inset Quotes erd
10635 is chosen, the parindent of a LaTeXtype
10636 \begin_inset Quotes eld
10640 \begin_inset Quotes erd
10643 layout is ignored and all paragraphs are separated by this parskip argument.
10644 The vertical space is calculated with
10645 \begin_inset Flex CharStyle:Code
10648 \begin_layout Plain Layout
10650 \begin_inset space ~
10659 \begin_inset Flex CharStyle:Code
10662 \begin_layout Plain Layout
10668 is the height of a row with the normal font.
10669 This way, the look stays the same with different screen fonts.
10672 \begin_layout Description
10673 \begin_inset Flex CharStyle:Code
10676 \begin_layout Plain Layout
10683 \begin_inset CommandInset label
10685 name "des:PathThru"
10692 \begin_inset Flex CharStyle:Code
10695 \begin_layout Plain Layout
10706 \begin_inset Flex CharStyle:Code
10709 \begin_layout Plain Layout
10715 ] Whether the contents of this paragraph should be output in raw form, meaning
10716 without special translations that LaTeX would require.
10719 \begin_layout Description
10720 \begin_inset Flex CharStyle:Code
10723 \begin_layout Plain Layout
10730 \begin_inset CommandInset label
10732 name "des:Preamble"
10736 Information to be included in the LaTeX preamble when this style is used.
10737 Used to define macros, load packages, etc., required by this particular
10740 \begin_inset Quotes eld
10744 \begin_inset Flex CharStyle:Code
10747 \begin_layout Plain Layout
10754 \begin_inset Quotes erd
10760 \begin_layout Description
10761 \begin_inset Flex CharStyle:Code
10764 \begin_layout Plain Layout
10771 \begin_inset Flex CharStyle:Code
10774 \begin_layout Plain Layout
10781 \begin_inset CommandInset label
10783 name "des:Requires"
10787 Whether the layout requires the feature
10788 \begin_inset Flex CharStyle:Code
10791 \begin_layout Plain Layout
10798 See the description of
10799 \begin_inset Flex CharStyle:Code
10802 \begin_layout Plain Layout
10809 \begin_inset CommandInset ref
10810 LatexCommand pageref
10811 reference "des:FreeSpacing"
10815 ) for information on `features'.
10819 \begin_layout Description
10820 \begin_inset Flex CharStyle:Code
10823 \begin_layout Plain Layout
10830 \begin_inset Flex CharStyle:Code
10833 \begin_layout Plain Layout
10840 \begin_inset Flex CharStyle:Code
10843 \begin_layout Plain Layout
10852 \begin_layout Description
10853 \begin_inset Flex CharStyle:Code
10856 \begin_layout Plain Layout
10863 \begin_inset Flex CharStyle:Code
10866 \begin_layout Plain Layout
10871 , onehalf, double, other
10880 ] This defines what the default spacing should be in the layout.
10882 \begin_inset Flex CharStyle:Code
10885 \begin_layout Plain Layout
10892 \begin_inset Flex CharStyle:Code
10895 \begin_layout Plain Layout
10902 \begin_inset Flex CharStyle:Code
10905 \begin_layout Plain Layout
10911 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
10912 If you specify the argument
10913 \begin_inset Flex CharStyle:Code
10916 \begin_layout Plain Layout
10922 , then you should also provide a numerical argument which will be the actual
10924 Note that, contrary to other parameters,
10925 \begin_inset Flex CharStyle:Code
10928 \begin_layout Plain Layout
10934 implies the generation of specific LaTeX code, using the package
10937 \begin_inset Flex CharStyle:Code
10940 \begin_layout Plain Layout
10949 \begin_layout Description
10950 \begin_inset Flex CharStyle:Code
10953 \begin_layout Plain Layout
10959 The font used for the text body .
10961 \begin_inset CommandInset ref
10963 reference "sub:Font-description"
10970 \begin_layout Description
10971 \begin_inset Flex CharStyle:Code
10974 \begin_layout Plain Layout
10982 The level of the style in the table of contents.
10983 This is used for automatic numbering of section headings.
10986 \begin_layout Description
10987 \begin_inset Flex CharStyle:Code
10990 \begin_layout Plain Layout
10997 \begin_inset Flex CharStyle:Code
11000 \begin_layout Plain Layout
11006 ] The vertical space with which the very first of a chain of paragraphs
11007 with this layout is separated from the previous paragraph.
11008 If the previous paragraph has another layout, the separations are not simply
11009 added, but the maximum is taken.
11012 \begin_layout Subsection
11014 \begin_inset CommandInset label
11023 \begin_layout Standard
11024 Since version 1.3.0 of LyX, it is has been both possible and necessary to
11025 define the floats (
11026 \begin_inset Flex CharStyle:MenuItem
11029 \begin_layout Plain Layout
11036 \begin_inset Flex CharStyle:MenuItem
11039 \begin_layout Plain Layout
11045 , \SpecialChar \ldots{}
11046 ) in the text class itself.
11047 Standard floats are included in the file
11048 \begin_inset Flex CharStyle:Code
11051 \begin_layout Plain Layout
11057 , so you may have to do no more than add
11060 \begin_layout LyX-Code
11061 Input stdfloats.inc
11064 \begin_layout Standard
11065 to your layout file.
11066 If you want to implement a text class that proposes some other float types
11067 (like the AGU class bundled with LyX), the information below will hopefully
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
11092 \begin_inset Quotes erd
11096 \begin_inset Quotes erd
11099 ] The file name extension of an auxiliary file for the list of figures (or
11101 LaTeX writes the captions to this file.
11104 \begin_layout Description
11105 \begin_inset Flex CharStyle:Code
11108 \begin_layout Plain Layout
11115 \begin_inset Flex CharStyle:Code
11118 \begin_layout Plain Layout
11125 \begin_inset Quotes erd
11129 \begin_inset Quotes erd
11132 ] The string that will be used in the menus and also for the caption.
11135 \begin_layout Description
11136 \begin_inset Flex CharStyle:Code
11139 \begin_layout Plain Layout
11146 \begin_inset Flex CharStyle:Code
11149 \begin_layout Plain Layout
11158 \begin_inset Flex CharStyle:Code
11161 \begin_layout Plain Layout
11168 \begin_inset Flex CharStyle:Code
11171 \begin_layout Plain Layout
11177 if the float is already defined by the LaTeX document class.
11179 \begin_inset Flex CharStyle:Code
11182 \begin_layout Plain Layout
11188 , the float will be defined using the LaTeX package
11189 \begin_inset Flex CharStyle:Code
11192 \begin_layout Plain Layout
11201 \begin_layout Description
11202 \begin_inset Flex CharStyle:Code
11205 \begin_layout Plain Layout
11212 \begin_inset Flex CharStyle:Code
11215 \begin_layout Plain Layout
11222 \begin_inset Quotes erd
11226 \begin_inset Quotes erd
11229 ] The heading used for the list of floats.
11232 \begin_layout Description
11233 \begin_inset Flex CharStyle:Code
11236 \begin_layout Plain Layout
11243 \begin_inset Flex CharStyle:Code
11246 \begin_layout Plain Layout
11253 \begin_inset Quotes erd
11257 \begin_inset Quotes erd
11260 ] This (optional) argument determines whether floats of this class will
11261 be numbered within some sectional unit of the document.
11262 For example, if within is equal to
11263 \begin_inset Flex CharStyle:Code
11266 \begin_layout Plain Layout
11272 , the floats will be numbered within chapters.
11276 \begin_layout Description
11277 \begin_inset Flex CharStyle:Code
11280 \begin_layout Plain Layout
11287 \begin_inset Flex CharStyle:Code
11290 \begin_layout Plain Layout
11297 \begin_inset Quotes erd
11301 \begin_inset Quotes erd
11304 ] The default placement for the given class of floats.
11305 The string should be as in standard LaTeX:
11306 \begin_inset Flex CharStyle:Code
11309 \begin_layout Plain Layout
11316 \begin_inset Flex CharStyle:Code
11319 \begin_layout Plain Layout
11326 \begin_inset Flex CharStyle:Code
11329 \begin_layout Plain Layout
11336 \begin_inset Flex CharStyle:Code
11339 \begin_layout Plain Layout
11345 for top, bottom, page, and here, respectively.
11349 \begin_layout Plain Layout
11350 Note that the order of these letters in the string is irrelevant, like in
11356 On top of that there is a new type,
11357 \begin_inset Flex CharStyle:Code
11360 \begin_layout Plain Layout
11366 , which does not really correspond to a float, since it means: put it
11367 \begin_inset Quotes eld
11371 \begin_inset Quotes erd
11375 Note however that the
11376 \begin_inset Flex CharStyle:Code
11379 \begin_layout Plain Layout
11385 specifier is special and, because of implementation details, cannot be
11386 used in non-built in float types.
11387 If you do not understand what this means, just use
11388 \begin_inset Quotes eld
11392 \begin_inset Flex CharStyle:Code
11395 \begin_layout Plain Layout
11402 \begin_inset Quotes erd
11408 \begin_layout Description
11409 \begin_inset Flex CharStyle:Code
11412 \begin_layout Plain Layout
11419 \begin_inset Flex CharStyle:Code
11422 \begin_layout Plain Layout
11429 \begin_inset Quotes erd
11433 \begin_inset Quotes erd
11436 ] The style used when defining the float using
11437 \begin_inset Flex CharStyle:Code
11440 \begin_layout Plain Layout
11451 \begin_layout Description
11452 \begin_inset Flex CharStyle:Code
11455 \begin_layout Plain Layout
11462 \begin_inset Flex CharStyle:Code
11465 \begin_layout Plain Layout
11472 \begin_inset Quotes erd
11476 \begin_inset Quotes erd
11480 \begin_inset Quotes eld
11484 \begin_inset Quotes erd
11487 of the new class of floats, like program or algorithm.
11488 After the appropriate
11489 \begin_inset Flex CharStyle:Code
11492 \begin_layout Plain Layout
11501 \begin_inset Flex CharStyle:Code
11504 \begin_layout Plain Layout
11513 \begin_inset Flex CharStyle:Code
11516 \begin_layout Plain Layout
11527 \begin_layout Standard
11528 Note that defining a float with type
11529 \begin_inset Flex CharStyle:Code
11532 \begin_layout Plain Layout
11540 automatically defines the corresponding counter with name
11541 \begin_inset Flex CharStyle:Code
11544 \begin_layout Plain Layout
11555 \begin_layout Subsection
11556 Flex insets and InsetLayout
11557 \begin_inset CommandInset label
11559 name "sub:Flex-insets-and"
11566 \begin_layout Standard
11567 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
11568 these are called Flex insets.
11572 \begin_layout Standard
11573 Flex insets come in three different kinds:
11576 \begin_layout Itemize
11578 \begin_inset Flex CharStyle:Code
11581 \begin_layout Plain Layout
11587 ): These define semantic markup corresponding to such LaTeX commands as
11589 \begin_inset Flex CharStyle:Code
11592 \begin_layout Plain Layout
11601 \begin_inset Flex CharStyle:Code
11604 \begin_layout Plain Layout
11615 \begin_layout Itemize
11617 \begin_inset Flex CharStyle:Code
11620 \begin_layout Plain Layout
11626 ): These can be used to define custom collapsible insets, similar to TeX
11627 code, footnote, and the like.
11628 An obvious example is an endnote inset, which is defined in the
11629 \begin_inset Flex CharStyle:Code
11632 \begin_layout Plain Layout
11641 \begin_layout Itemize
11643 \begin_inset Flex CharStyle:Code
11646 \begin_layout Plain Layout
11652 ): For use with DocBook classes.
11655 \begin_layout Standard
11656 Flex insets are defined using the
11657 \begin_inset Flex CharStyle:Code
11660 \begin_layout Plain Layout
11666 tag, which shall be explained in a moment.
11669 \begin_layout Standard
11671 \begin_inset Flex CharStyle:Code
11674 \begin_layout Plain Layout
11680 tag also serves another function: It can be used to customize the general
11681 layout of many different types of insets.
11683 \begin_inset Flex CharStyle:Code
11686 \begin_layout Plain Layout
11692 can be used to customize the layout parameters for footnotes, marginal
11693 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
11694 boxes, tables, algorithms, URLs, and optional arguments, as well as to
11695 define Flex insets.
11698 \begin_layout Standard
11700 \begin_inset Flex CharStyle:Code
11703 \begin_layout Plain Layout
11709 definition must begin with a line of the form:
11712 \begin_layout LyX-Code
11716 \begin_layout Standard
11718 \begin_inset Flex CharStyle:Code
11721 \begin_layout Plain Layout
11727 indicates the inset whose layout is being defined, and here there are two
11731 \begin_layout Enumerate
11732 The layout for a pre-existing inset is being modified.
11733 In this case, can be
11734 \begin_inset Flex CharStyle:Code
11737 \begin_layout Plain Layout
11743 any one of the following:
11744 \begin_inset Flex CharStyle:Code
11747 \begin_layout Plain Layout
11754 \begin_inset Flex CharStyle:Code
11757 \begin_layout Plain Layout
11764 \begin_inset Flex CharStyle:Code
11767 \begin_layout Plain Layout
11774 \begin_inset Flex CharStyle:Code
11777 \begin_layout Plain Layout
11784 \begin_inset Flex CharStyle:Code
11787 \begin_layout Plain Layout
11794 \begin_inset Flex CharStyle:Code
11797 \begin_layout Plain Layout
11804 \begin_inset Flex CharStyle:Code
11807 \begin_layout Plain Layout
11814 \begin_inset Flex CharStyle:Code
11817 \begin_layout Plain Layout
11824 \begin_inset Flex CharStyle:Code
11827 \begin_layout Plain Layout
11834 \begin_inset Flex CharStyle:Code
11837 \begin_layout Plain Layout
11844 \begin_inset Flex CharStyle:Code
11847 \begin_layout Plain Layout
11854 \begin_inset Flex CharStyle:Code
11857 \begin_layout Plain Layout
11864 \begin_inset Flex CharStyle:Code
11867 \begin_layout Plain Layout
11874 \begin_inset Flex CharStyle:Code
11877 \begin_layout Plain Layout
11884 \begin_inset Flex CharStyle:Code
11887 \begin_layout Plain Layout
11894 \begin_inset Flex CharStyle:Code
11897 \begin_layout Plain Layout
11904 \begin_inset Flex CharStyle:Code
11907 \begin_layout Plain Layout
11914 \begin_inset Flex CharStyle:Code
11917 \begin_layout Plain Layout
11924 \begin_inset Flex CharStyle:Code
11927 \begin_layout Plain Layout
11934 \begin_inset Flex CharStyle:Code
11937 \begin_layout Plain Layout
11947 \begin_layout Enumerate
11948 The layout for a Flex inset is being defined.
11950 \begin_inset Flex CharStyle:Code
11953 \begin_layout Plain Layout
11959 can be any valid identifier not used by a pre-existing inset.
11960 Note that the definition of a flex inset must
11965 \begin_inset Flex CharStyle:Code
11968 \begin_layout Plain Layout
11977 \begin_layout Standard
11979 \begin_inset Flex CharStyle:Code
11982 \begin_layout Plain Layout
11988 definition can contain the following entries:
11991 \begin_layout Description
11992 \begin_inset Flex CharStyle:Code
11995 \begin_layout Plain Layout
12001 The color for the inset's background.
12002 The valid colors are defined in
12003 \begin_inset Flex CharStyle:Code
12006 \begin_layout Plain Layout
12015 \begin_layout Description
12016 \begin_inset Flex CharStyle:Code
12019 \begin_layout Plain Layout
12025 As with paragraph styles (see page
12026 \begin_inset CommandInset ref
12028 reference "des:CopyStyle"
12035 \begin_layout Description
12036 \begin_inset Flex CharStyle:Code
12039 \begin_layout Plain Layout
12046 \begin_inset Flex CharStyle:Code
12049 \begin_layout Plain Layout
12058 \begin_inset Flex CharStyle:Code
12061 \begin_layout Plain Layout
12067 ] Indicates whether the user may employ the Paragraph Settings dialog to
12068 customize the paragraph.
12071 \begin_layout Description
12072 \begin_inset Flex CharStyle:Code
12075 \begin_layout Plain Layout
12082 \begin_inset Flex CharStyle:Code
12085 \begin_layout Plain Layout
12092 \begin_inset Flex CharStyle:Code
12095 \begin_layout Plain Layout
12102 \begin_inset Flex CharStyle:Code
12105 \begin_layout Plain Layout
12111 , describing the rendering style used for the inset's frame and buttons.
12112 Footnotes generally use
12113 \begin_inset Flex CharStyle:Code
12116 \begin_layout Plain Layout
12122 , ERT insets generally
12123 \begin_inset Flex CharStyle:Code
12126 \begin_layout Plain Layout
12132 , and character styles
12133 \begin_inset Flex CharStyle:Code
12136 \begin_layout Plain Layout
12145 \begin_layout Description
12146 \begin_inset Flex CharStyle:Code
12149 \begin_layout Plain Layout
12155 Required at the end of the InsetLayout declarations.
12158 \begin_layout Description
12159 \begin_inset Flex CharStyle:Code
12162 \begin_layout Plain Layout
12168 The font used for both the text body
12174 \begin_inset space ~
12178 \begin_inset CommandInset ref
12180 reference "sub:Font-description"
12185 Note that defining this font automatically defines the
12186 \begin_inset Flex CharStyle:Code
12189 \begin_layout Plain Layout
12195 to the same value, so define this first and define
12196 \begin_inset Flex CharStyle:Code
12199 \begin_layout Plain Layout
12205 later if you want them to be different.
12208 \begin_layout Description
12209 \begin_inset Flex CharStyle:Code
12212 \begin_layout Plain Layout
12219 \begin_inset Quotes eld
12223 \begin_inset Quotes erd
12226 language, leading to Left-to-Right (latin) output, e.
12227 \begin_inset space \thinspace{}
12231 \begin_inset space \space{}
12234 in TeX code or URL.
12238 \begin_layout Description
12239 \begin_inset Flex CharStyle:Code
12242 \begin_layout Plain Layout
12249 \begin_inset Flex CharStyle:Code
12252 \begin_layout Plain Layout
12261 \begin_inset Flex CharStyle:Code
12264 \begin_layout Plain Layout
12270 ] Indicates whether the PlainLayout should be used or, instead, the user
12271 can change the paragraph style used in the inset.
12274 \begin_layout Description
12275 \begin_inset Flex CharStyle:Code
12278 \begin_layout Plain Layout
12284 As with paragraph styles (see page
12285 \begin_inset CommandInset ref
12286 LatexCommand pageref
12287 reference "des:FreeSpacing"
12294 \begin_layout Description
12295 \begin_inset Flex CharStyle:Code
12298 \begin_layout Plain Layout
12305 \begin_inset Flex CharStyle:Code
12308 \begin_layout Plain Layout
12317 \begin_inset Flex CharStyle:Code
12320 \begin_layout Plain Layout
12326 ] Whether to include the contents of this inset in the strings generated
12327 for the `Outline' pane.
12328 One would not, for example, want the content of a footnote in a section
12329 header to be included in the TOC displayed in the outline, but one would
12330 normally want the content of a character style displayed.
12331 Default is false: not to include.
12334 \begin_layout Description
12335 \begin_inset Flex CharStyle:Code
12338 \begin_layout Plain Layout
12344 As with paragraph styles (see page
12345 \begin_inset CommandInset ref
12346 LatexCommand pageref
12347 reference "des:KeepEmpty"
12354 \begin_layout Description
12355 \begin_inset Flex CharStyle:Code
12358 \begin_layout Plain Layout
12364 The font used for the label.
12366 \begin_inset space ~
12370 \begin_inset CommandInset ref
12372 reference "sub:Font-description"
12377 Note that this definition can never appear before
12378 \begin_inset Flex CharStyle:Code
12381 \begin_layout Plain Layout
12387 , lest it be ineffective.
12390 \begin_layout Description
12391 \begin_inset Flex CharStyle:Code
12394 \begin_layout Plain Layout
12400 What will be displayed on the button or elsewhere as the inset label.
12401 Some inset types (TeX code and Branch) modify this label on the fly.
12404 \begin_layout Description
12405 \begin_inset Flex CharStyle:Code
12408 \begin_layout Plain Layout
12414 The name of the corresponding LaTeX stuff.
12415 Either the environment or command name.
12418 \begin_layout Description
12419 \begin_inset Flex CharStyle:Code
12422 \begin_layout Plain Layout
12428 The optional parameter for the corresponding
12429 \begin_inset Flex CharStyle:Code
12432 \begin_layout Plain Layout
12438 stuff, including possible bracket pairs like
12439 \begin_inset Flex CharStyle:Code
12442 \begin_layout Plain Layout
12449 This parameter cannot be changed from within LyX.
12452 \begin_layout Description
12453 \begin_inset Flex CharStyle:Code
12456 \begin_layout Plain Layout
12462 As with paragraph styles (see page
12463 \begin_inset CommandInset ref
12464 LatexCommand pageref
12465 reference "des:LatexType"
12472 \begin_layout Description
12473 \begin_inset Flex CharStyle:Code
12476 \begin_layout Plain Layout
12483 \begin_inset Flex CharStyle:Code
12486 \begin_layout Plain Layout
12493 \begin_inset Flex CharStyle:Code
12496 \begin_layout Plain Layout
12503 \begin_inset Flex CharStyle:Code
12506 \begin_layout Plain Layout
12513 \begin_inset Flex CharStyle:Code
12516 \begin_layout Plain Layout
12522 (indicating a dummy definition ending definitions of charstyles, etc).
12523 This entry is required in and is only meaningful for Flex insets.
12524 Among other things, it determines on which menu this inset will appear.
12527 \begin_layout Description
12528 \begin_inset Flex CharStyle:Code
12531 \begin_layout Plain Layout
12538 \begin_inset Flex CharStyle:Code
12541 \begin_layout Plain Layout
12550 \begin_inset Flex CharStyle:Code
12553 \begin_layout Plain Layout
12559 ] Whether multiple paragraphs are permitted in this inset.
12560 This will also set CustomPars to the same value and ForcePlain to the opposite
12562 These can be reset to other values, if they are used
12569 \begin_layout Description
12570 \begin_inset Flex CharStyle:Code
12573 \begin_layout Plain Layout
12580 \begin_inset Flex CharStyle:Code
12583 \begin_layout Plain Layout
12592 \begin_inset Flex CharStyle:Code
12595 \begin_layout Plain Layout
12601 ] Whether fragile commands in this layout should be
12602 \begin_inset Flex CharStyle:Code
12605 \begin_layout Plain Layout
12618 whether the command should itself be protected.)
12621 \begin_layout Description
12622 \begin_inset Flex CharStyle:Code
12625 \begin_layout Plain Layout
12632 \begin_inset Flex CharStyle:Code
12635 \begin_layout Plain Layout
12644 \begin_inset Flex CharStyle:Code
12647 \begin_layout Plain Layout
12653 ] As with paragraph styles (see page
12654 \begin_inset CommandInset ref
12656 reference "des:PathThru"
12663 \begin_layout Description
12664 \begin_inset Flex CharStyle:Code
12667 \begin_layout Plain Layout
12673 As with paragraph styles (see page
12674 \begin_inset CommandInset ref
12675 LatexCommand pageref
12676 reference "des:Preamble"
12683 \begin_layout Description
12684 \begin_inset Flex CharStyle:Code
12687 \begin_layout Plain Layout
12694 \begin_inset Flex CharStyle:Code
12697 \begin_layout Plain Layout
12703 ] As with paragraph styles (see page
12704 \begin_inset CommandInset ref
12705 LatexCommand pageref
12706 reference "des:Requires"
12713 \begin_layout Subsection
12715 \begin_inset CommandInset label
12717 name "sub:Counters"
12724 \begin_layout Standard
12725 Since version 1.3.0 of LyX, it is both possible and necessary to define the
12727 \begin_inset Flex CharStyle:MenuItem
12730 \begin_layout Plain Layout
12737 \begin_inset Flex CharStyle:MenuItem
12740 \begin_layout Plain Layout
12746 , \SpecialChar \ldots{}
12747 ) in the text class itself.
12748 The standard counters are defined in the file
12749 \begin_inset Flex CharStyle:Code
12752 \begin_layout Plain Layout
12758 , so you may have to do no more than add
12761 \begin_layout LyX-Code
12762 Input stdcounters.inc
12765 \begin_layout Standard
12766 to your layout file to get them to work.
12767 But if you want to define custom counters, then you can do so.
12768 The counter declaration must begin with:
12771 \begin_layout LyX-Code
12775 \begin_layout Standard
12776 where of course `name' is replaced by the name of the counter.
12777 And it must end with
12778 \begin_inset Quotes eld
12782 \begin_inset Flex CharStyle:Code
12785 \begin_layout Plain Layout
12792 \begin_inset Quotes erd
12796 The following parameters can also be used:
12799 \begin_layout Description
12800 \begin_inset Flex CharStyle:Code
12803 \begin_layout Plain Layout
12804 LabelString [string=""]
12809 when this is defined, this string defines how the counter is displayed.
12810 Setting this value sets
12811 \begin_inset Flex CharStyle:Code
12814 \begin_layout Plain Layout
12815 LabelStringAppendix
12821 The following special constructs can be used in the string:
12825 \begin_layout Itemize
12826 \begin_inset Flex CharStyle:Code
12829 \begin_layout Plain Layout
12837 will be replaced by the expansion of the
12838 \begin_inset Flex CharStyle:Code
12841 \begin_layout Plain Layout
12848 \begin_inset Flex CharStyle:Code
12851 \begin_layout Plain Layout
12852 LabelStringAppendix
12858 \begin_inset Flex CharStyle:Code
12861 \begin_layout Plain Layout
12871 \begin_layout Itemize
12872 counter values can be expressed using LaTeX-like macros
12873 \begin_inset Flex CharStyle:Code
12876 \begin_layout Plain Layout
12893 \begin_inset Flex CharStyle:Code
12896 \begin_layout Plain Layout
12908 \begin_layout Plain Layout
12918 Actually, the situation is a bit more complicated: any
12937 other than those described below will produce arabic numerals.
12938 It would not be surprising to see this change in the future.
12944 \begin_inset Flex CharStyle:Code
12947 \begin_layout Plain Layout
12953 : 1, 2, 3,\SpecialChar \ldots{}
12955 \begin_inset Flex CharStyle:Code
12958 \begin_layout Plain Layout
12964 for lower-case letters: a, b, c, \SpecialChar \ldots{}
12966 \begin_inset Flex CharStyle:Code
12969 \begin_layout Plain Layout
12975 for upper-case letters: A, B, C, \SpecialChar \ldots{}
12977 \begin_inset Flex CharStyle:Code
12980 \begin_layout Plain Layout
12986 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
12988 \begin_inset Flex CharStyle:Code
12991 \begin_layout Plain Layout
12997 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
12999 \begin_inset Flex CharStyle:Code
13002 \begin_layout Plain Layout
13008 for hebrew numerals.
13012 \begin_layout Standard
13013 If LabelString is not defined, a default value is constructed as follows:
13014 if the counter has a master counter
13015 \begin_inset Flex CharStyle:Code
13018 \begin_layout Plain Layout
13025 \begin_inset Flex CharStyle:Code
13028 \begin_layout Plain Layout
13035 \begin_inset Flex CharStyle:Code
13038 \begin_layout Plain Layout
13048 is used; otherwise the string
13049 \begin_inset Flex CharStyle:Code
13052 \begin_layout Plain Layout
13063 \begin_layout Description
13064 \begin_inset Flex CharStyle:Code
13067 \begin_layout Plain Layout
13068 LabelStringAppendix [string=""]
13074 \begin_inset Flex CharStyle:Code
13077 \begin_layout Plain Layout
13083 , but for use in the Appendix.
13086 \begin_layout Description
13087 \begin_inset Flex CharStyle:Code
13090 \begin_layout Plain Layout
13097 \begin_inset Flex CharStyle:Code
13100 \begin_layout Plain Layout
13107 \begin_inset Quotes erd
13111 \begin_inset Quotes erd
13114 ] If this is set to the name of another counter, the present counter will
13115 be reset every time the other one is increased.
13117 \begin_inset Flex CharStyle:Code
13120 \begin_layout Plain Layout
13127 \begin_inset Flex CharStyle:Code
13130 \begin_layout Plain Layout
13139 \begin_layout Subsection
13141 \begin_inset CommandInset label
13143 name "sub:Font-description"
13150 \begin_layout Standard
13151 A font description looks like this:
13154 \begin_layout LyX-Code
13164 \begin_layout LyX-Code
13168 \begin_layout LyX-Code
13172 \begin_layout Standard
13173 The following commands are available:
13176 \begin_layout Description
13177 \begin_inset Flex CharStyle:Code
13180 \begin_layout Plain Layout
13187 \begin_inset Flex CharStyle:Code
13190 \begin_layout Plain Layout
13199 \begin_inset Flex CharStyle:Code
13202 \begin_layout Plain Layout
13209 \begin_inset Flex CharStyle:Code
13212 \begin_layout Plain Layout
13219 \begin_inset Flex CharStyle:Code
13222 \begin_layout Plain Layout
13229 \begin_inset Flex CharStyle:Code
13232 \begin_layout Plain Layout
13239 \begin_inset Flex CharStyle:Code
13242 \begin_layout Plain Layout
13249 \begin_inset Flex CharStyle:Code
13252 \begin_layout Plain Layout
13259 \begin_inset Flex CharStyle:Code
13262 \begin_layout Plain Layout
13269 \begin_inset Flex CharStyle:Code
13272 \begin_layout Plain Layout
13281 \begin_layout Description
13282 \begin_inset Flex CharStyle:Code
13285 \begin_layout Plain Layout
13294 \begin_inset Flex CharStyle:Code
13297 \begin_layout Plain Layout
13308 \begin_inset Flex CharStyle:Code
13311 \begin_layout Plain Layout
13318 \begin_inset Flex CharStyle:Code
13321 \begin_layout Plain Layout
13330 \begin_layout Description
13331 \begin_inset Flex CharStyle:Code
13334 \begin_layout Plain Layout
13341 \begin_inset Flex CharStyle:Code
13344 \begin_layout Plain Layout
13350 ] Valid argument are:
13351 \begin_inset Flex CharStyle:Code
13354 \begin_layout Plain Layout
13361 \begin_inset Flex CharStyle:Code
13364 \begin_layout Plain Layout
13371 \begin_inset Flex CharStyle:Code
13374 \begin_layout Plain Layout
13381 \begin_inset Flex CharStyle:Code
13384 \begin_layout Plain Layout
13391 \begin_inset Flex CharStyle:Code
13394 \begin_layout Plain Layout
13401 \begin_inset Flex CharStyle:Code
13404 \begin_layout Plain Layout
13411 Each of these turns on or off the corresponding attribute.
13414 \begin_layout Description
13415 \begin_inset Flex CharStyle:Code
13418 \begin_layout Plain Layout
13427 \begin_inset Flex CharStyle:Code
13430 \begin_layout Plain Layout
13441 \begin_inset Flex CharStyle:Code
13444 \begin_layout Plain Layout
13453 \begin_layout Description
13454 \begin_inset Flex CharStyle:Code
13457 \begin_layout Plain Layout
13466 \begin_inset Flex CharStyle:Code
13469 \begin_layout Plain Layout
13480 \begin_inset Flex CharStyle:Code
13483 \begin_layout Plain Layout
13490 \begin_inset Flex CharStyle:Code
13493 \begin_layout Plain Layout
13500 \begin_inset Flex CharStyle:Code
13503 \begin_layout Plain Layout
13512 \begin_layout Description
13513 \begin_inset Flex CharStyle:Code
13516 \begin_layout Plain Layout
13523 \begin_inset Flex CharStyle:Code
13526 \begin_layout Plain Layout
13533 \begin_inset Flex CharStyle:Code
13536 \begin_layout Plain Layout
13543 \begin_inset Flex CharStyle:Code
13546 \begin_layout Plain Layout
13555 \begin_inset Flex CharStyle:Code
13558 \begin_layout Plain Layout
13565 \begin_inset Flex CharStyle:Code
13568 \begin_layout Plain Layout
13575 \begin_inset Flex CharStyle:Code
13578 \begin_layout Plain Layout
13585 \begin_inset Flex CharStyle:Code
13588 \begin_layout Plain Layout
13595 \begin_inset Flex CharStyle:Code
13598 \begin_layout Plain Layout
13607 \begin_layout Subsection
13608 Upgrading old layout files
13611 \begin_layout Standard
13612 The file format of layout files changes from time to time, so old layout
13613 files need to be converted.
13614 This process has been automated since LyX 1.4.0: If LyX reads an old format
13615 layout file it will call the conversion tool
13616 \begin_inset Flex CharStyle:Code
13619 \begin_layout Plain Layout
13620 LyXDir/scripts/layout2layout.py
13625 and convert it to a temporary file in current format.
13626 The original file is left untouched.
13627 If you want to convert the layout file permanently, just call the converter
13631 \begin_layout LyX-Code
13632 python $LyXDir/scripts/layout2layout.py myclass.layout myclassnew.layout
13635 \begin_layout Standard
13636 (You need to replace
13637 \begin_inset Flex CharStyle:Code
13640 \begin_layout Plain Layout
13646 with the name of your LyX system directory, unless you happen to have defined
13647 such an environment variable.) Then copy
13648 \begin_inset Flex CharStyle:Code
13651 \begin_layout Plain Layout
13658 \begin_inset Flex CharStyle:Code
13661 \begin_layout Plain Layout
13670 \begin_layout Standard
13671 The automatic conversion only handles syntax changes.
13672 It cannot handle the case where the contents of included files was changed,
13673 so these will have to be converted separately.
13676 \begin_layout Section
13678 \begin_inset CommandInset label
13680 name "sec:Creating-Templates"
13687 \begin_layout Standard
13688 Templates are created just like usual documents.
13689 The only difference is that usual documents contain all possible settings,
13690 including the font scheme and the paper size.
13691 Usually a user doesn't want a template to overwrite his defaults in these
13693 For that reason, the designer of a template should remove the corresponding
13695 \begin_inset Flex CharStyle:Code
13698 \begin_layout Plain Layout
13707 \begin_inset Flex CharStyle:Code
13710 \begin_layout Plain Layout
13718 from the template LyX file.
13719 This can be done with any simple text-editor, for example
13720 \begin_inset Flex CharStyle:Code
13723 \begin_layout Plain Layout
13730 \begin_inset Flex CharStyle:Code
13733 \begin_layout Plain Layout
13743 \begin_layout Standard
13744 Put the edited template files you create in
13745 \begin_inset Flex CharStyle:Code
13748 \begin_layout Plain Layout
13754 , copy the ones you use from the global template directory in
13755 \begin_inset Flex CharStyle:Code
13758 \begin_layout Plain Layout
13764 to the same place, and redefine the template path in the
13765 \begin_inset Flex CharStyle:MenuItem
13768 \begin_layout Plain Layout
13769 Tools\SpecialChar \menuseparator
13770 Preferences\SpecialChar \menuseparator
13779 \begin_layout Standard
13780 Note that there is a template which has a particular meaning:
13781 \begin_inset Flex CharStyle:Code
13784 \begin_layout Plain Layout
13791 This template is loaded every time you create a new document with
13792 \begin_inset Flex CharStyle:MenuItem
13795 \begin_layout Plain Layout
13796 File\SpecialChar \menuseparator
13802 in order to provide useful defaults.
13803 To create this template from inside LyX, all you have to do is to open
13804 a document with the correct settings, and use the
13805 \begin_inset Flex CharStyle:MenuItem
13808 \begin_layout Plain Layout
13809 Save as Document Defaults
13817 \begin_layout Chapter
13818 Including External Material
13821 \begin_layout Standard
13822 \begin_inset Box Shadowbox
13831 height_special "totalheight"
13834 \begin_layout Plain Layout
13835 WARNING: This portion of the documentation has not been updated for some
13837 We certainly hope that it is still accurate, but there are no guarantees.
13845 \begin_layout Standard
13846 The use of material from sources external to LyX is covered in detail in
13852 This part of the manual covers what needs to happen behind the scenes for
13853 new sorts of material to be included.
13856 \begin_layout Section
13860 \begin_layout Standard
13861 The external material feature is based on the concept of a
13866 A template is a specification of how LyX should interface with a certain
13868 As bundled, LyX comes with predefined templates for Xfig figures, various
13869 raster format images, chess diagrams, and LilyPond music notation.
13870 You can check the actual list by using the menu
13871 \begin_inset Flex CharStyle:MenuItem
13874 \begin_layout Plain Layout
13875 Insert\SpecialChar \menuseparator
13876 File\SpecialChar \menuseparator
13883 Furthermore, it is possible to roll your own template to support a specific
13885 Later we'll describe in more detail what is involved, and hopefully you
13886 will submit all the templates you create so we can include them in a later
13890 \begin_layout Standard
13891 Another basic idea of the external material feature is to distinguish between
13892 the original file that serves as a base for final material and the produced
13893 file that is included in your exported or printed document.
13894 For example, consider the case of a figure produced with
13895 \begin_inset Flex CharStyle:Code
13898 \begin_layout Plain Layout
13905 The Xfig application itself works on an original file with the
13906 \begin_inset Flex CharStyle:Code
13909 \begin_layout Plain Layout
13916 Within Xfig, you create and change your figure, and when you are done,
13918 \begin_inset Flex CharStyle:Code
13921 \begin_layout Plain Layout
13928 When you want to include the figure in your document, you invoke
13929 \begin_inset Flex CharStyle:Code
13932 \begin_layout Plain Layout
13938 in order to create a PostScript file that can readily be included in your
13941 \begin_inset Flex CharStyle:Code
13944 \begin_layout Plain Layout
13950 file is the original file, and the PostScript file is the produced file.
13953 \begin_layout Standard
13954 This distinction is important in order to allow updating of the material
13955 while you are in the process of writing the document.
13956 Furthermore, it provides us with the flexibility that is needed to support
13957 multiple export formats.
13958 For instance, in the case of a plain text file, it is not exactly an award-winn
13959 ing idea to include the figure as raw PostScript.
13960 Instead, you'd either prefer to just include a reference to the figure
13961 or try to invoke some graphics to ASCII converter to make the final result
13962 look similar to the real graphics.
13963 The external material management allows you to do this, because it is parametri
13964 zed on the different export formats that LyX supports.
13967 \begin_layout Standard
13968 Besides supporting the production of different products according to the
13969 exported format, it supports tight integration with editing and viewing
13971 In the case of an Xfig figure, you are able to invoke Xfig on the original
13972 file with a single click from within the external material dialog in LyX,
13973 and also preview the produced PostScript file with Ghostview with another
13975 No more fiddling around with the command line and/or file browsers to locate
13976 and manipulate the original or produced files.
13977 In this way, you are finally able to take full advantage of the many different
13978 applications that are relevant to use when you write your documents, and
13979 ultimately be more productive.
13982 \begin_layout Section
13983 The external template configuration file
13986 \begin_layout Standard
13987 It is relatively easy to add custom external template definitions to LyX.
13988 However, be aware that doing this in an careless manner most probably
13992 introduce an easily exploitable security hole.
13993 So before you do this, please read the discussion about security in section
13995 \begin_inset CommandInset ref
13997 reference "sec:Security-discussion"
14004 \begin_layout Standard
14005 Having said that, we encourage you to submit any interesting templates that
14010 \begin_layout Standard
14011 The external templates are defined in the
14012 \begin_inset Flex CharStyle:Code
14015 \begin_layout Plain Layout
14016 LyXDir/lib/external_templates
14022 You can place your own version in
14023 \begin_inset Flex CharStyle:Code
14026 \begin_layout Plain Layout
14027 UserDir/external_templates
14035 \begin_layout Standard
14036 A typical template looks like this:
14039 \begin_layout LyX-Code
14043 \begin_layout LyX-Code
14044 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
14047 \begin_layout LyX-Code
14051 \begin_layout LyX-Code
14055 \begin_layout LyX-Code
14059 \begin_layout LyX-Code
14063 \begin_layout LyX-Code
14067 \begin_layout LyX-Code
14068 AutomaticProduction true
14071 \begin_layout LyX-Code
14075 \begin_layout LyX-Code
14079 \begin_layout LyX-Code
14083 \begin_layout LyX-Code
14084 TransformCommand Rotate RotationLatexCommand
14087 \begin_layout LyX-Code
14088 TransformCommand Resize ResizeLatexCommand
14091 \begin_layout LyX-Code
14092 Product "$$RotateFront$$ResizeFront
14095 \begin_layout LyX-Code
14100 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
14103 \begin_layout LyX-Code
14104 $$ResizeBack$$RotateBack"
14107 \begin_layout LyX-Code
14111 \begin_layout LyX-Code
14112 UpdateResult "$$AbsPath$$Basename.pstex_t"
14115 \begin_layout LyX-Code
14116 Requirement "graphicx"
14119 \begin_layout LyX-Code
14120 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
14123 \begin_layout LyX-Code
14124 ReferencedFile latex "$$AbsPath$$Basename.eps"
14127 \begin_layout LyX-Code
14128 ReferencedFile dvi "$$AbsPath$$Basename.eps"
14131 \begin_layout LyX-Code
14135 \begin_layout LyX-Code
14139 \begin_layout LyX-Code
14140 TransformCommand Rotate RotationLatexCommand
14143 \begin_layout LyX-Code
14144 TransformCommand Resize ResizeLatexCommand
14147 \begin_layout LyX-Code
14148 Product "$$RotateFront$$ResizeFront
14151 \begin_layout LyX-Code
14156 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
14159 \begin_layout LyX-Code
14160 $$ResizeBack$$RotateBack"
14163 \begin_layout LyX-Code
14164 UpdateFormat pdftex
14167 \begin_layout LyX-Code
14168 UpdateResult "$$AbsPath$$Basename.pdftex_t"
14171 \begin_layout LyX-Code
14172 Requirement "graphicx"
14175 \begin_layout LyX-Code
14176 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
14179 \begin_layout LyX-Code
14180 ReferencedFile latex "$$AbsPath$$Basename.pdf"
14183 \begin_layout LyX-Code
14187 \begin_layout LyX-Code
14191 \begin_layout LyX-Code
14192 Product "$$Contents(
14194 "$$AbsPath$$Basename.asc
14199 \begin_layout LyX-Code
14200 UpdateFormat asciixfig
14203 \begin_layout LyX-Code
14204 UpdateResult "$$AbsPath$$Basename.asc"
14207 \begin_layout LyX-Code
14211 \begin_layout LyX-Code
14215 \begin_layout LyX-Code
14216 Product "<graphic fileref=
14218 "$$AbsOrRelPathMaster$$Basename.eps
14223 \begin_layout LyX-Code
14227 \begin_layout LyX-Code
14231 \begin_layout LyX-Code
14232 UpdateResult "$$AbsPath$$Basename.eps"
14235 \begin_layout LyX-Code
14236 ReferencedFile docbook "$$AbsPath$$Basename.eps"
14239 \begin_layout LyX-Code
14240 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
14243 \begin_layout LyX-Code
14247 \begin_layout LyX-Code
14248 Product "[XFig: $$FName]"
14251 \begin_layout LyX-Code
14255 \begin_layout LyX-Code
14259 \begin_layout Standard
14260 As you can see, the template is enclosed in
14261 \begin_inset Flex CharStyle:Code
14264 \begin_layout Plain Layout
14270 \SpecialChar \ldots{}
14272 \begin_inset Flex CharStyle:Code
14275 \begin_layout Plain Layout
14282 It contains a header specifying some general settings and, for each supported
14283 primary document file format, a section
14284 \begin_inset Flex CharStyle:Code
14287 \begin_layout Plain Layout
14293 \SpecialChar \ldots{}
14295 \begin_inset Flex CharStyle:Code
14298 \begin_layout Plain Layout
14307 \begin_layout Subsection
14308 The template header
14311 \begin_layout Description
14312 \begin_inset Flex CharStyle:Code
14315 \begin_layout Plain Layout
14316 AutomaticProduction
14317 \begin_inset space ~
14325 Whether the file represented by the template must be generated by LyX.
14326 This command must occur exactly once.
14329 \begin_layout Description
14330 \begin_inset Flex CharStyle:Code
14333 \begin_layout Plain Layout
14335 \begin_inset space ~
14343 A glob pattern that is used in the file dialog to filter out the desired
14345 If there is more than one possible file extension (e.
14346 \begin_inset space \thinspace{}
14350 \begin_inset space \space{}
14354 \begin_inset Flex CharStyle:Code
14357 \begin_layout Plain Layout
14364 \begin_inset Flex CharStyle:Code
14367 \begin_layout Plain Layout
14373 ), use something like
14374 \begin_inset Flex CharStyle:Code
14377 \begin_layout Plain Layout
14384 This command must occur exactly once.
14387 \begin_layout Description
14388 \begin_inset Flex CharStyle:Code
14391 \begin_layout Plain Layout
14393 \begin_inset space ~
14401 The text that is displayed on the button.
14402 This command must occur exactly once.
14405 \begin_layout Description
14406 \begin_inset Flex CharStyle:Code
14409 \begin_layout Plain Layout
14411 \begin_inset space ~
14415 \begin_inset space ~
14423 The help text that is used in the External dialog.
14424 Provide enough information to explain to the user just what the template
14425 can provide him with.
14426 This command must occur exactly once.
14429 \begin_layout Description
14430 \begin_inset Flex CharStyle:Code
14433 \begin_layout Plain Layout
14435 \begin_inset space ~
14443 The file format of the original file.
14444 This must be the name of a format that is known to LyX (see section
14445 \begin_inset CommandInset ref
14447 reference "sec:Formats"
14453 \begin_inset Quotes eld
14457 \begin_inset Flex CharStyle:Code
14460 \begin_layout Plain Layout
14467 \begin_inset Quotes erd
14470 if the template can handle original files of more than one format.
14471 LyX will attempt to interrogate the file itself in order to deduce its
14472 format in this case.
14473 This command must occur exactly once.
14476 \begin_layout Description
14477 \begin_inset Flex CharStyle:Code
14480 \begin_layout Plain Layout
14482 \begin_inset space ~
14490 A unique name for the template.
14491 It must not contain substitution macros (see below).
14494 \begin_layout Description
14495 \begin_inset Flex CharStyle:Code
14498 \begin_layout Plain Layout
14500 \begin_inset space ~
14503 Rotate|Resize|Clip|Extra
14508 This command specifies which transformations are supported by this template.
14509 It may occur zero or more times.
14510 This command enables the corresponding tabs in the external dialog.
14512 \begin_inset Flex CharStyle:Code
14515 \begin_layout Plain Layout
14521 command must have either a corresponding
14522 \begin_inset Flex CharStyle:Code
14525 \begin_layout Plain Layout
14532 \begin_inset Flex CharStyle:Code
14535 \begin_layout Plain Layout
14542 \begin_inset Flex CharStyle:Code
14545 \begin_layout Plain Layout
14552 Otherwise the transformation will not be supported by that format.
14555 \begin_layout Subsection
14559 \begin_layout Description
14560 \begin_inset Flex CharStyle:Code
14563 \begin_layout Plain Layout
14565 \begin_inset space ~
14568 LaTeX|PDFLaTeX|PlainText|DocBook
14573 The primary document file format that this format definition is for.
14574 Not every template has a sensible representation in all document file formats.
14575 Please define nevertheless a
14576 \begin_inset Flex CharStyle:Code
14579 \begin_layout Plain Layout
14585 section for all formats.
14586 Use a dummy text when no representation is available.
14587 Then you can at least see a reference to the external material in the exported
14591 \begin_layout Description
14592 \begin_inset Flex CharStyle:Code
14595 \begin_layout Plain Layout
14597 \begin_inset space ~
14601 \begin_inset space ~
14609 This command defines an additional macro
14610 \begin_inset Flex CharStyle:Code
14613 \begin_layout Plain Layout
14619 for substitution in
14620 \begin_inset Flex CharStyle:Code
14623 \begin_layout Plain Layout
14631 \begin_inset Flex CharStyle:Code
14634 \begin_layout Plain Layout
14640 itself may contain substitution macros.
14641 The advantage over using
14642 \begin_inset Flex CharStyle:Code
14645 \begin_layout Plain Layout
14652 \begin_inset Flex CharStyle:Code
14655 \begin_layout Plain Layout
14661 is that the substituted value of
14662 \begin_inset Flex CharStyle:Code
14665 \begin_layout Plain Layout
14671 is sanitized so that it is a valid optional argument in the document format.
14672 This command may occur zero or more times.
14675 \begin_layout Description
14676 \begin_inset Flex CharStyle:Code
14679 \begin_layout Plain Layout
14681 \begin_inset space ~
14689 The text that is inserted in the exported document.
14690 This is actually the most important command and can be quite complex.
14691 This command must occur exactly once.
14694 \begin_layout Description
14695 \begin_inset Flex CharStyle:Code
14698 \begin_layout Plain Layout
14700 \begin_inset space ~
14708 This command specifies a preamble snippet that will be included in the
14710 It has to be defined using
14711 \begin_inset Flex CharStyle:Code
14714 \begin_layout Plain Layout
14720 \SpecialChar \ldots{}
14722 \begin_inset Flex CharStyle:Code
14725 \begin_layout Plain Layout
14732 This command may occur zero or more times.
14735 \begin_layout Description
14736 \begin_inset Flex CharStyle:Code
14739 \begin_layout Plain Layout
14741 \begin_inset space ~
14745 \begin_inset space ~
14753 This command denotes files that are created by the conversion process and
14754 are needed for a particular export format.
14755 If the filename is relative, it is interpreted relative to the master document.
14756 This command may be given zero or more times.
14759 \begin_layout Description
14760 \begin_inset Flex CharStyle:Code
14763 \begin_layout Plain Layout
14765 \begin_inset space ~
14773 The name of a required LaTeX package.
14774 The package is included via
14775 \begin_inset Flex CharStyle:Code
14778 \begin_layout Plain Layout
14786 in the LaTeX preamble.
14787 This command may occur zero or more times.
14790 \begin_layout Description
14791 \begin_inset Flex CharStyle:Code
14794 \begin_layout Plain Layout
14796 \begin_inset space ~
14800 \begin_inset space ~
14803 RotationLatexCommand
14808 This command specifies that the built in LaTeX command should be used for
14810 This command may occur once or not at all.
14813 \begin_layout Description
14814 \begin_inset Flex CharStyle:Code
14817 \begin_layout Plain Layout
14819 \begin_inset space ~
14823 \begin_inset space ~
14831 This command specifies that the built in LaTeX command should be used for
14833 This command may occur once or not at all.
14836 \begin_layout Description
14837 \begin_inset Flex CharStyle:Code
14840 \begin_layout Plain Layout
14842 \begin_inset space ~
14846 \begin_inset space ~
14849 RotationLatexOption
14854 This command specifies that rotation is done via an optional argument.
14855 This command may occur once or not at all.
14858 \begin_layout Description
14859 \begin_inset Flex CharStyle:Code
14862 \begin_layout Plain Layout
14864 \begin_inset space ~
14868 \begin_inset space ~
14876 This command specifies that resizing is done via an optional argument.
14877 This command may occur once or not at all.
14880 \begin_layout Description
14881 \begin_inset Flex CharStyle:Code
14884 \begin_layout Plain Layout
14886 \begin_inset space ~
14890 \begin_inset space ~
14898 This command specifies that clipping is done via an optional argument.
14899 This command may occur once or not at all.
14902 \begin_layout Description
14903 \begin_inset Flex CharStyle:Code
14906 \begin_layout Plain Layout
14908 \begin_inset space ~
14912 \begin_inset space ~
14920 This command specifies that an extra optional argument is used.
14921 This command may occur once or not at all.
14924 \begin_layout Description
14925 \begin_inset Flex CharStyle:Code
14928 \begin_layout Plain Layout
14930 \begin_inset space ~
14938 The file format of the converted file.
14939 This must be the name of a format that is known to LyX (see the
14940 \begin_inset Flex CharStyle:MenuItem
14943 \begin_layout Plain Layout
14948 ools\SpecialChar \menuseparator
14953 references:Conversion
14959 This command must occur exactly once.
14962 \begin_layout Description
14963 \begin_inset Flex CharStyle:Code
14966 \begin_layout Plain Layout
14968 \begin_inset space ~
14976 The file name of the converted file.
14977 The file name must be absolute.
14978 This command must occur exactly once.
14981 \begin_layout Subsection
14982 Preamble definitions
14985 \begin_layout Standard
14986 The external template configuration file may contain additional preamble
14987 definitions enclosed by
14988 \begin_inset Flex CharStyle:Code
14991 \begin_layout Plain Layout
14997 \SpecialChar \ldots{}
14999 \begin_inset Flex CharStyle:Code
15002 \begin_layout Plain Layout
15009 They can be used by the templates in the
15010 \begin_inset Flex CharStyle:Code
15013 \begin_layout Plain Layout
15022 \begin_layout Section
15023 The substitution mechanism
15026 \begin_layout Standard
15027 When the external material facility invokes an external program, it is done
15028 on the basis of a command defined in the template configuration file.
15029 These commands can contain various macros that are expanded before execution.
15030 Execution always take place in the directory of the containing document.
15033 \begin_layout Standard
15034 Also, whenever external material is to be displayed, the name will be produced
15035 by the substitution mechanism, and most other commands in the template
15036 definition support substitution as well.
15039 \begin_layout Standard
15040 The available macros are the following:
15043 \begin_layout Description
15044 \begin_inset Flex CharStyle:Code
15047 \begin_layout Plain Layout
15048 $$AbsOrRelPathMaster
15053 The file path, absolute or relative to the master LyX document.
15056 \begin_layout Description
15057 \begin_inset Flex CharStyle:Code
15060 \begin_layout Plain Layout
15061 $$AbsOrRelPathParent
15066 The file path, absolute or relative to the LyX document.
15069 \begin_layout Description
15070 \begin_inset Flex CharStyle:Code
15073 \begin_layout Plain Layout
15079 The absolute file path.
15082 \begin_layout Description
15083 \begin_inset Flex CharStyle:Code
15086 \begin_layout Plain Layout
15092 The filename without path and without the extension.
15095 \begin_layout Description
15096 \begin_inset Flex CharStyle:Code
15099 \begin_layout Plain Layout
15101 \begin_inset Quotes eld
15105 \begin_inset Quotes erd
15113 This macro will expand to the contents of the file with the name
15114 \begin_inset Flex CharStyle:Code
15117 \begin_layout Plain Layout
15126 \begin_layout Description
15127 \begin_inset Flex CharStyle:Code
15130 \begin_layout Plain Layout
15136 The file extension (including the dot).
15139 \begin_layout Description
15140 \begin_inset Flex CharStyle:Code
15143 \begin_layout Plain Layout
15149 The filename of the file specified in the external material dialog.
15150 This is either an absolute name, or it is relative to the LyX document.
15153 \begin_layout Description
15154 \begin_inset Flex CharStyle:Code
15157 \begin_layout Plain Layout
15164 \begin_inset Flex CharStyle:Code
15167 \begin_layout Plain Layout
15173 (absolute name or relative to the LyX document).
15176 \begin_layout Description
15177 \begin_inset Flex CharStyle:Code
15180 \begin_layout Plain Layout
15186 The file path, relative to the master LyX document.
15189 \begin_layout Description
15190 \begin_inset Flex CharStyle:Code
15193 \begin_layout Plain Layout
15199 The file path, relative to the LyX document.
15202 \begin_layout Description
15203 \begin_inset Flex CharStyle:Code
15206 \begin_layout Plain Layout
15212 This macro will expand to the absolute path of the system directory.
15213 This is typically used to point to the various helper scripts that are
15217 \begin_layout Description
15218 \begin_inset Flex CharStyle:Code
15221 \begin_layout Plain Layout
15227 A name and full path to a temporary file which will be automatically deleted
15228 whenever the containing document is closed, or the external material insertion
15232 \begin_layout Standard
15233 All path macros contain a trailing directory separator, so you can construct
15235 \begin_inset space \thinspace{}
15239 \begin_inset space \space{}
15242 the absolute filename with
15243 \begin_inset Flex CharStyle:Code
15246 \begin_layout Plain Layout
15247 $$AbsPath$$Basename$$Extension
15255 \begin_layout Standard
15256 The macros above are substituted in all commands unless otherwise noted.
15258 \begin_inset Flex CharStyle:Code
15261 \begin_layout Plain Layout
15267 supports additionally the following substitutions if they are enabled by
15269 \begin_inset Flex CharStyle:Code
15272 \begin_layout Plain Layout
15279 \begin_inset Flex CharStyle:Code
15282 \begin_layout Plain Layout
15291 \begin_layout Description
15292 \begin_inset Flex CharStyle:Code
15295 \begin_layout Plain Layout
15301 The front part of the resize command.
15304 \begin_layout Description
15305 \begin_inset Flex CharStyle:Code
15308 \begin_layout Plain Layout
15314 The back part of the resize command.
15317 \begin_layout Description
15318 \begin_inset Flex CharStyle:Code
15321 \begin_layout Plain Layout
15327 The front part of the rotation command.
15330 \begin_layout Description
15331 \begin_inset Flex CharStyle:Code
15334 \begin_layout Plain Layout
15340 The back part of the rotation command.
15343 \begin_layout Standard
15344 The value string of the
15345 \begin_inset Flex CharStyle:Code
15348 \begin_layout Plain Layout
15354 command supports additionally the following substitutions if they are enabled
15356 \begin_inset Flex CharStyle:Code
15359 \begin_layout Plain Layout
15366 \begin_inset Flex CharStyle:Code
15369 \begin_layout Plain Layout
15378 \begin_layout Description
15379 \begin_inset Flex CharStyle:Code
15382 \begin_layout Plain Layout
15391 \begin_layout Description
15392 \begin_inset Flex CharStyle:Code
15395 \begin_layout Plain Layout
15404 \begin_layout Description
15405 \begin_inset Flex CharStyle:Code
15408 \begin_layout Plain Layout
15417 \begin_layout Description
15418 \begin_inset Flex CharStyle:Code
15421 \begin_layout Plain Layout
15427 The rotation option.
15430 \begin_layout Standard
15431 You may ask why there are so many path macros.
15432 There are mainly two reasons:
15435 \begin_layout Enumerate
15436 Relative and absolute file names should remain relative or absolute, respectivel
15438 Users may have reasons to prefer either form.
15439 Relative names are useful for portable documents that should work on different
15440 machines, for example.
15441 Absolute names may be required by some programs.
15444 \begin_layout Enumerate
15445 LaTeX treats relative file names differently than LyX and other programs
15446 in nested included files.
15447 For LyX, a relative file name is always relative to the document that contains
15449 For LaTeX, it is always relative to the master document.
15450 These two definitions are identical if you have only one document, but
15451 differ if you have a master document that includes part documents.
15452 That means that relative filenames must be transformed when presented to
15454 Fortunately LyX does this automatically for you if you choose the right
15458 \begin_layout Standard
15459 So which path macro should be used in new template definitions? The rule
15463 \begin_layout Itemize
15465 \begin_inset Flex CharStyle:Code
15468 \begin_layout Plain Layout
15474 if an absolute path is required.
15477 \begin_layout Itemize
15479 \begin_inset Flex CharStyle:Code
15482 \begin_layout Plain Layout
15483 $$AbsOrRelPathMaster
15488 if the substituted string is some kind of LaTeX input.
15491 \begin_layout Itemize
15493 \begin_inset Flex CharStyle:Code
15496 \begin_layout Plain Layout
15497 $$AbsOrRelPathParent
15502 in order to preserve the user's choice.
15505 \begin_layout Standard
15506 There are special cases where this rule does not work and e.
15507 \begin_inset space \thinspace{}
15511 \begin_inset space \space{}
15514 relative names are needed, but normally it will work just fine.
15515 One example for such a case is the command
15516 \begin_inset Flex CharStyle:Code
15519 \begin_layout Plain Layout
15520 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
15525 in the XFig template above: We can't use the absolute name because the
15527 \begin_inset Flex CharStyle:Code
15530 \begin_layout Plain Layout
15536 files needs the relative name in order to rewrite the file content.
15539 \begin_layout Section
15540 Security discussion
15541 \begin_inset CommandInset label
15543 name "sec:Security-discussion"
15550 \begin_layout Standard
15551 The external material feature interfaces with a lot of external programs
15552 and does so automatically, so we have to consider the security implications
15554 In particular, since you have the option of including your own filenames
15555 and/or parameter strings and those are expanded into a command, it seems
15556 that it would be possible to create a malicious document which executes
15557 arbitrary commands when a user views or prints the document.
15558 This is something we definitely want to avoid.
15561 \begin_layout Standard
15562 However, since the external program commands are specified in the template
15563 configuration file only, there are no security issues if LyX is properly
15564 configured with safe templates only.
15565 This is so because the external programs are invoked with the
15566 \begin_inset Flex CharStyle:Code
15569 \begin_layout Plain Layout
15575 -system call rather than the
15576 \begin_inset Flex CharStyle:Code
15579 \begin_layout Plain Layout
15585 system-call, so it's not possible to execute arbitrary commands from the
15586 filename or parameter section via the shell.
15589 \begin_layout Standard
15590 This also implies that you are restricted in what command strings you can
15591 use in the external material templates.
15592 In particular, pipes and redirection are not readily available.
15593 This has to be so if LyX should remain safe.
15594 If you want to use some of the shell features, you should write a safe
15595 script to do this in a controlled manner, and then invoke the script from
15596 the command string.
15600 \begin_layout Standard
15601 It is possible to design a template that interacts directly with the shell,
15602 but since this would allow a malicious user to execute arbitrary commands
15603 by writing clever filenames and/or parameters, we generally recommend that
15604 you only use safe scripts that work with the
15605 \begin_inset Flex CharStyle:Code
15608 \begin_layout Plain Layout
15614 system call in a controlled manner.
15615 Of course, for use in a controlled environment, it can be tempting to just
15616 fall back to use ordinary shell scripts.
15617 If you do so, be aware that you
15621 provide an easily exploitable security hole in your system.
15622 Of course it stands to reason that such unsafe templates will never be
15623 included in the standard LyX distribution, although we do encourage people
15624 to submit new templates in the open source tradition.
15625 But LyX as shipped from the official distribution channels will never have
15629 \begin_layout Standard
15630 Including external material provides a lot of power, and you have to be
15631 careful not to introduce security hazards with this power.
15632 A subtle error in a single line in an innocent looking script can open
15633 the door to huge security problems.
15634 So if you do not fully understand the issues, we recommend that you consult
15635 a knowledgeable security professional or the LyX development team if you
15636 have any questions about whether a given template is safe or not.
15637 And do this before you use it in an uncontrolled environment.