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
42 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
43 \use_default_options false
47 \maintain_unincluded_children false
50 InsetLayout CharStyle:MenuItem
59 \newcommand*{\menuitem}[1]{{\sffamily #1}}
62 # In case we need to do with sans...
63 #InsetLayout CharStyle:Code
68 #\renewcommand{\code}[1]{{\sffamily #1}}
77 \font_typewriter default
78 \font_default_family default
86 \default_output_format default
88 \bibtex_command default
89 \index_command default
93 \pdf_title "LyX Configuration Manual"
94 \pdf_author "LyX Team"
95 \pdf_subject "LyX-documentation Customization"
96 \pdf_keywords "LyX, documentation, customization"
98 \pdf_bookmarksnumbered true
99 \pdf_bookmarksopen true
100 \pdf_bookmarksopenlevel 1
101 \pdf_breaklinks false
105 \pdf_pdfusetitle false
106 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
116 \paperorientation portrait
130 \paragraph_separation indent
131 \paragraph_indentation default
132 \quotes_language english
135 \paperpagestyle headings
136 \tracking_changes true
137 \output_changes false
140 \author 1 "Jean-Marc Lasgouttes"
146 Customizing LyX: Features for the Advanced User
154 \begin_layout Plain Layout
156 If you have comments or error corrections, please send them to the LyX Documenta
158 \begin_inset CommandInset href
160 target "lyx-docs@lists.lyx.org"
167 \begin_inset Quotes eld
171 \begin_inset Quotes erd
174 in the subject header, and please cc the current maintainer of this file,
175 Richard Heck <rgheck@comcast.net>.
181 \begin_inset Newline newline
185 \begin_inset Newline newline
191 \begin_layout Standard
192 \begin_inset CommandInset toc
193 LatexCommand tableofcontents
200 \begin_layout Standard
201 \begin_inset Note Note
204 \begin_layout Plain Layout
205 Please use change tracking when modifying this document.
206 This makes it easier for our translators to recognize things that have
207 been changed, and it helps the maintainer keep up-to-date with what's been
216 \begin_layout Chapter
220 \begin_layout Standard
221 This manual covers the customization features present in LyX.
222 In it, we discuss issues like keyboard shortcuts, screen previewing options,
223 printer options, sending commands to LyX via the LyX Server, internationalizati
224 on, installing new LaTeX classes and LyX layouts, etc.
225 We can't possibly hope to touch on everything you can change—our developers
226 add new features faster than we can document them—but we will explain the
227 most common customizations and hopefully point you in the right direction
228 for some of the more obscure ones.
231 \begin_layout Standard
232 \begin_inset Branch OutDated
235 \begin_layout Standard
236 Information from previous versions of this document that now seems to be
237 outdated is contained in the OutDated branch of this document.
238 By default, this information will not appear in the LaTeX output.
246 \begin_layout Chapter
247 LyX configuration files
250 \begin_layout Standard
251 This chapter aims to help you to find your way through the LyX configuration
253 Before continuing to read this chapter, you should find out where your
254 LyX library and user directories are by using
255 \begin_inset Flex MenuItem
258 \begin_layout Plain Layout
259 Help\SpecialChar \menuseparator
270 The library directory is the place where LyX places its system-wide configurati
271 on files; the user directory is where you can place your modified versions.
272 We will call the former
273 \begin_inset Flex Code
276 \begin_layout Plain Layout
283 \begin_inset Flex MenuItem
286 \begin_layout Plain Layout
292 in the remainder of this document.
296 \begin_layout Section
298 \begin_inset Flex Code
301 \begin_layout Plain Layout
310 \begin_layout Standard
311 \begin_inset Flex Code
314 \begin_layout Plain Layout
320 and its sub-directories contain a number of files and that can be used
321 to customize LyX's behavior.
322 You can change many of these files from within LyX itself through the
323 \begin_inset Flex MenuItem
326 \begin_layout Plain Layout
327 Tools\SpecialChar \menuseparator
334 Most customization that you will want to do in LyX is possible through
336 However, many other inner aspects of LyX can be customized by modifying
338 \begin_inset Flex Code
341 \begin_layout Plain Layout
348 These files fall in different categories, described in the following subsection
352 \begin_layout Subsection
353 Automatically generated files
356 \begin_layout Standard
357 The files, which are to be found in
358 \begin_inset Flex MenuItem
361 \begin_layout Plain Layout
367 , are generated when you configure LyX.
368 They contain various default values that are guessed by inspection.
369 In general, it is not a good idea to modify them, since they might be overwritt
373 \begin_layout Labeling
374 \labelwidthstring 00.00.0000
375 \begin_inset Flex Code
378 \begin_layout Plain Layout
384 contains defaults for various commands.
387 \begin_layout Labeling
388 \labelwidthstring 00.00.0000
389 \begin_inset Flex Code
392 \begin_layout Plain Layout
398 contains the list of packages that have been recognized by LyX.
399 It is currently unused by the LyX program itself, but the information extracted
400 , and more, is made available with
401 \begin_inset Flex MenuItem
404 \begin_layout Plain Layout
405 Help\SpecialChar \menuseparator
418 \begin_layout Labeling
419 \labelwidthstring 00.00.0000
420 \begin_inset Flex Code
423 \begin_layout Plain Layout
429 the list of text classes that have been found in your
430 \begin_inset Flex Code
433 \begin_layout Plain Layout
439 directories, along with the associated LaTeX document class and their descripti
443 \begin_layout Labeling
444 \labelwidthstring 00.00.0000
445 \begin_inset Flex Code
448 \begin_layout Plain Layout
454 the list of layout modules found in your
455 \begin_inset Flex Code
458 \begin_layout Plain Layout
467 \begin_layout Labeling
468 \labelwidthstring 00.00.0000
469 \begin_inset Flex Code
472 \begin_layout Plain Layout
478 lists of various sorts of LaTeX-related files found on your system
481 \begin_layout Labeling
482 \labelwidthstring 00.00.0000
483 \begin_inset Flex Code
486 \begin_layout Plain Layout
492 is automatically generated during configuration from the file
493 \begin_inset Flex Code
496 \begin_layout Plain Layout
503 It contains information on your LaTeX configuration.
506 \begin_layout Subsection
510 \begin_layout Standard
511 These directories are duplicated between
512 \begin_inset Flex Code
515 \begin_layout Plain Layout
522 \begin_inset Flex Code
525 \begin_layout Plain Layout
532 If a particular files exists in both places, the one in
533 \begin_inset Flex Code
536 \begin_layout Plain Layout
545 \begin_layout Labeling
546 \labelwidthstring 00.00.0000
547 \begin_inset Flex Code
550 \begin_layout Plain Layout
556 this directory contains files with the extension
557 \begin_inset Flex Code
560 \begin_layout Plain Layout
566 that define the keybindings used in LyX.
567 If there exists an internationalized version of the bind file named
568 \begin_inset Flex Code
571 \begin_layout Plain Layout
577 , that will be used first.
580 \begin_layout Labeling
581 \labelwidthstring 00.00.0000
582 \begin_inset Flex Code
585 \begin_layout Plain Layout
591 contains graphics files that can be included in documents.
595 \begin_layout Labeling
596 \labelwidthstring 00.00.0000
597 \begin_inset Flex Code
600 \begin_layout Plain Layout
606 contains LyX documentation files (including the one you are currently reading).
608 \begin_inset Flex Code
611 \begin_layout Plain Layout
617 deserves special attention, as noted above.
618 The internationalized help docs are in subdirectories
619 \begin_inset Flex Code
622 \begin_layout Plain Layout
629 \begin_inset Quotes eld
633 \begin_inset Quotes erd
636 is the ISO language code.
642 \begin_inset CommandInset ref
644 reference "cha:Internationalizing-LyX"
651 \begin_layout Labeling
652 \labelwidthstring 00.00.0000
653 \begin_inset Flex Code
656 \begin_layout Plain Layout
662 contains example files that explain how to use some features.
663 In the file browser, press the
664 \begin_inset Flex MenuItem
667 \begin_layout Plain Layout
676 \begin_layout Labeling
677 \labelwidthstring 00.00.0000
678 \begin_inset Flex Code
681 \begin_layout Plain Layout
687 contains image files that are used by the
688 \begin_inset Flex MenuItem
691 \begin_layout Plain Layout
698 In addition, it also contains the individual icons used in the toolbar
699 and the banners that can be shown when LyX is launched.
702 \begin_layout Labeling
703 \labelwidthstring 00.00.0000
704 \begin_inset Flex Code
707 \begin_layout Plain Layout
713 contains keyboard keymapping files.
719 \begin_inset CommandInset ref
721 reference "sec:International-Keymap-Stuff"
728 \begin_layout Labeling
729 \labelwidthstring 00.00.0000
730 \begin_inset Flex Code
733 \begin_layout Plain Layout
739 contains the text class and module files described in Chapter
744 \begin_inset CommandInset ref
746 reference "cha:Installing-New-Document"
753 \begin_layout Labeling
754 \labelwidthstring 00.00.0000
755 \begin_inset Flex Code
758 \begin_layout Plain Layout
765 \begin_inset Flex Code
768 \begin_layout Plain Layout
774 Python scripts used to convert between LyX versions.
775 These can be run from the command line if, say, you want to batch-convert
779 \begin_layout Labeling
780 \labelwidthstring 00.00.0000
781 \begin_inset Flex Code
784 \begin_layout Plain Layout
790 contains some files that demonstrate the capabilities of the
791 \begin_inset Flex MenuItem
794 \begin_layout Plain Layout
805 Also contains some scripts used by LyX itself.
808 \begin_layout Labeling
809 \labelwidthstring 00.00.0000
810 \begin_inset Flex Code
813 \begin_layout Plain Layout
819 contains the standard LyX template files described in Chapter
824 \begin_inset CommandInset ref
826 reference "sub:Creating-Templates"
833 \begin_layout Labeling
834 \labelwidthstring 00.00.0000
835 \begin_inset Flex Code
838 \begin_layout Plain Layout
844 contains files with the extension
845 \begin_inset Flex Code
848 \begin_layout Plain Layout
854 that define the user interface to LyX.
855 That is, the files define which items appear in which menus and the items
856 appearing on the toolbar.
859 \begin_layout Subsection
860 Files you don't want to modify
863 \begin_layout Standard
864 These files are used internally by LyX and you generally do not need to
865 modify them unless you are a developer.
868 \begin_layout Labeling
869 \labelwidthstring 00.00.0000
870 \begin_inset Flex Code
873 \begin_layout Plain Layout
879 this file contains the list of LyX developers.
880 The contents are displayed with the menu entry
881 \begin_inset Flex MenuItem
884 \begin_layout Plain Layout
885 Help\SpecialChar \menuseparator
898 \begin_layout Labeling
899 \labelwidthstring 00.00.0000
900 \begin_inset Flex Code
903 \begin_layout Plain Layout
909 this is a LaTeX script used during the configuration process.
913 \begin_layout Labeling
914 \labelwidthstring 00.00.0000
915 \begin_inset Flex Code
918 \begin_layout Plain Layout
924 this is the script that is used to re-configure LyX.
925 It creates configuration files in the directory it was run from.
928 \begin_layout Subsection
929 Other files needing a line or two...
932 \begin_layout Labeling
933 \labelwidthstring 00.00.0000
934 \begin_inset Flex Code
937 \begin_layout Plain Layout
943 this contains tables describing how different character encodings can be
947 \begin_layout Labeling
948 \labelwidthstring 00.00.0000
949 \begin_inset Flex Code
952 \begin_layout Plain Layout
958 this file contains the templates available to the new
959 \begin_inset Flex MenuItem
962 \begin_layout Plain Layout
975 \begin_layout Labeling
976 \labelwidthstring 00.00.0000
977 \begin_inset Flex Code
980 \begin_layout Plain Layout
986 this file contains a list of all the languages currently supported by LyX.
989 \begin_layout Section
990 Your local configuration directory
993 \begin_layout Standard
994 Even if you are using LyX as an unprivileged user, you might want to change
995 LyX configuration for your own use.
997 \begin_inset Flex Code
1000 \begin_layout Plain Layout
1006 directory contains all your personal configuration files.
1007 This is the directory described as
1008 \begin_inset Quotes eld
1012 \begin_inset Quotes erd
1016 \begin_inset Flex MenuItem
1019 \begin_layout Plain Layout
1020 Help\SpecialChar \menuseparator
1022 \begin_inset space ~
1031 This directory is used as a mirror of
1032 \begin_inset Flex Code
1035 \begin_layout Plain Layout
1041 , which means that every file in
1042 \begin_inset Flex Code
1045 \begin_layout Plain Layout
1051 is a replacement for the corresponding file in
1052 \begin_inset Flex Code
1055 \begin_layout Plain Layout
1062 Any configuration file described in the above sections can be placed either
1063 in the system-wide directory, in which case it will affect all users, or
1064 in your local directory for your own use.
1067 \begin_layout Standard
1068 To make things clearer, let's provide a few examples:
1071 \begin_layout Itemize
1072 The preferences set in the
1073 \begin_inset Flex MenuItem
1076 \begin_layout Plain Layout
1077 Tools\SpecialChar \menuseparator
1083 dialog are saved to a file
1084 \begin_inset Flex Code
1087 \begin_layout Plain Layout
1094 \begin_inset Flex Code
1097 \begin_layout Plain Layout
1106 \begin_layout Itemize
1107 When you reconfigure using
1108 \begin_inset Flex MenuItem
1111 \begin_layout Plain Layout
1112 Tools\SpecialChar \menuseparator
1119 \begin_inset Flex Code
1122 \begin_layout Plain Layout
1128 script, and the resulting files are written in your local configuration
1130 This means that any additional text class file that you might have added
1132 \begin_inset Flex Code
1135 \begin_layout Plain Layout
1141 will be added to the list of classes in the
1142 \begin_inset Flex MenuItem
1145 \begin_layout Plain Layout
1146 Document\SpecialChar \menuseparator
1155 \begin_layout Itemize
1156 If you get some updated documentation from LyX ftp site and cannot install
1157 it because you do not have sysadmin rights on your system, you can just
1159 \begin_inset Flex Code
1162 \begin_layout Plain Layout
1168 and the items in the
1169 \begin_inset Flex MenuItem
1172 \begin_layout Plain Layout
1178 menu will open them!
1181 \begin_layout Section
1182 Running LyX with multiple configurations
1185 \begin_layout Standard
1186 The configuration freedom of the local configuration directory may not suffice
1187 if you want to have more than one configuration at your disposal.
1188 For example, you may want to be use different key bindings or printer settings
1190 You can achieve this by having several such directories.
1191 You then specify which directory to use at run-time.
1194 \begin_layout Standard
1195 Invoking LyX with the command line switch
1196 \begin_inset Flex Code
1199 \begin_layout Plain Layout
1209 instructs the program to read the configuration from that directory, and
1210 not from the default directory.
1211 (You can determine the default directory by running LyX without the
1212 \begin_inset Flex Code
1215 \begin_layout Plain Layout
1221 switch.) If the specified directory does not exist, LyX offers to create
1222 it for you, just like it does for the default directory on the first time
1223 you run the program.
1224 You can modify the configuration options in this additional user directory
1225 exactly as you would for the default directory.
1226 These directories are completely independent (but read on).
1227 Note that setting the environment variable
1228 \begin_inset Flex Code
1231 \begin_layout Plain Layout
1237 to some value has exactly the same effect.
1240 \begin_layout Standard
1241 Having several configurations also requires more maintenance: if you want
1242 to add a new layout to
1243 \begin_inset Flex Code
1246 \begin_layout Plain Layout
1252 which you want available from all your configurations, you must add it
1253 to each directory separately.
1254 You can avoid this with the following trick: after LyX creates the additional
1255 directory, most of the subdirectories (see above) are empty.
1256 If you want the new configuration to mirror an existing one, replace the
1257 empty subdirectory with a symbolic link to the matching subdirectory in
1258 the existing configuration.
1260 \begin_inset Flex Code
1263 \begin_layout Plain Layout
1269 subdirectory, however, since it contains a file written by the configuration
1270 script (also accessible through
1271 \begin_inset Flex MenuItem
1274 \begin_layout Plain Layout
1275 Tools\SpecialChar \menuseparator
1281 ) which is configuration-specific.
1284 \begin_layout Chapter
1285 The Preferences dialog
1288 \begin_layout Standard
1289 All options of the preferences dialog are described in the Appendix
1291 The Preferences Dialog
1298 For some options you might find here more details.
1301 \begin_layout Section
1303 \begin_inset CommandInset label
1312 \begin_layout Standard
1313 The first step is to define your file formats if they are not already defined.
1315 \begin_inset Flex MenuItem
1318 \begin_layout Plain Layout
1319 Tools\SpecialChar \menuseparator
1327 \begin_inset Flex MenuItem
1330 \begin_layout Plain Layout
1331 File Handling\SpecialChar \menuseparator
1338 \begin_inset Flex MenuItem
1341 \begin_layout Plain Layout
1342 New\SpecialChar \ldots{}
1348 button to define your new format.
1350 \begin_inset Flex MenuItem
1353 \begin_layout Plain Layout
1359 field contains the name used to identify the format in the GUI.
1361 \begin_inset Flex MenuItem
1364 \begin_layout Plain Layout
1370 is used to identify the format internally.
1371 You will also need to enter a file extension.
1372 These are all required.
1374 \begin_inset Flex MenuItem
1377 \begin_layout Plain Layout
1383 field is used to provide a keyboard shortcut on the menus.
1384 (For example, pressing
1385 \begin_inset Flex MenuItem
1388 \begin_layout Plain Layout
1395 \begin_inset Flex MenuItem
1398 \begin_layout Plain Layout
1399 View\SpecialChar \menuseparator
1408 \begin_layout Standard
1410 \begin_inset Flex MenuItem
1413 \begin_layout Plain Layout
1420 \begin_inset Flex MenuItem
1423 \begin_layout Plain Layout
1430 For example, you might want to use
1431 \begin_inset Flex MenuItem
1434 \begin_layout Plain Layout
1440 to view PostScript files.
1441 You can enter the command needed to start the program in the corresponding
1443 In defining this command, you can use the four variables listed in the
1445 The viewer is launched when you view an image in LyX or use the
1446 \begin_inset Flex MenuItem
1449 \begin_layout Plain Layout
1456 The editor is for example launched when you right-click on an image and
1458 \begin_inset Flex MenuItem
1461 \begin_layout Plain Layout
1467 in the appearing context menu.
1470 \begin_layout Standard
1472 \begin_inset Flex MenuItem
1475 \begin_layout Plain Layout
1481 option tells LyX that a format is suitable for document export.
1482 If this is set and if a suitable conversion route exists (see sec.
1483 \begin_inset space \thinspace{}
1487 \begin_inset CommandInset ref
1489 reference "sec:Converters"
1493 ), the format will appear in the
1494 \begin_inset Flex MenuItem
1497 \begin_layout Plain Layout
1498 File\SpecialChar \menuseparator
1505 The format will also appear in the
1506 \begin_inset Flex MenuItem
1509 \begin_layout Plain Layout
1515 menu if a viewer is specified for the format.
1516 Pure image formats, such as
1517 \begin_inset Flex Code
1520 \begin_layout Plain Layout
1526 , should not use this option.
1527 Formats that can both represent vector graphics and documents like
1528 \begin_inset Flex Code
1531 \begin_layout Plain Layout
1540 \begin_layout Standard
1542 \begin_inset Flex MenuItem
1545 \begin_layout Plain Layout
1546 Vector graphics format
1551 tells LyX that a format can contain vector graphics.
1552 This information is used to determine the target format of included graphics
1554 \begin_inset Flex MenuItem
1557 \begin_layout Plain Layout
1564 Included graphics may need to be converted to either
1565 \begin_inset Flex MenuItem
1568 \begin_layout Plain Layout
1575 \begin_inset Flex MenuItem
1578 \begin_layout Plain Layout
1585 \begin_inset Flex MenuItem
1588 \begin_layout Plain Layout
1595 \begin_inset Flex MenuItem
1598 \begin_layout Plain Layout
1604 cannot handle other image formats.
1605 If an included graphic is not already in
1606 \begin_inset Flex MenuItem
1609 \begin_layout Plain Layout
1616 \begin_inset Flex MenuItem
1619 \begin_layout Plain Layout
1626 \begin_inset Flex MenuItem
1629 \begin_layout Plain Layout
1635 format, it is converted to
1636 \begin_inset Flex MenuItem
1639 \begin_layout Plain Layout
1645 if the vector format option is set, and otherwise to
1646 \begin_inset Flex MenuItem
1649 \begin_layout Plain Layout
1658 \begin_layout Section
1662 \begin_layout Standard
1663 Since all conversions from one format to another take place in LyX's temporary
1664 directory, it is sometimes necessary to modify a file before copying it
1665 to the temporary directory in order that the conversion may be performed.
1669 \begin_layout Plain Layout
1670 For example, the file may refer to other files—images, for example—using
1671 relative file names, and these may become invalid when the file is copied
1672 to the temporary directory.
1677 This is done by a Copier: It copies a file to (or from) the temporary directory
1678 and may modify it in the process.
1681 \begin_layout Standard
1682 The definitions of the copiers may use four variables:
1685 \begin_layout Labeling
1686 \labelwidthstring 00.00.0000
1687 \begin_inset Flex Code
1690 \begin_layout Plain Layout
1696 The LyX system directory (e.
1697 \begin_inset space \thinspace{}
1701 \begin_inset space \space{}
1705 \begin_inset Flex MenuItem
1708 \begin_layout Plain Layout
1717 \begin_layout Labeling
1718 \labelwidthstring 00.00.0000
1719 \begin_inset Flex Code
1722 \begin_layout Plain Layout
1731 \begin_layout Labeling
1732 \labelwidthstring 00.00.0000
1733 \begin_inset Flex Code
1736 \begin_layout Plain Layout
1745 \begin_layout Labeling
1746 \labelwidthstring 00.00.0000
1747 \begin_inset Flex Code
1750 \begin_layout Plain Layout
1759 \begin_layout Standard
1760 The latter should be the filename as it would be used in a LaTeX's
1767 It is relevant only when exporting files suitable for such inclusion.
1770 \begin_layout Standard
1771 Copiers can be used to do almost anything with output files.
1772 For example, suppose you want generated pdf files to be copied to a special
1774 \begin_inset Flex Code
1777 \begin_layout Plain Layout
1784 Then you could write a shell script such as this one:
1787 \begin_layout Standard
1788 \begin_inset listings
1792 \begin_layout Plain Layout
1797 \begin_layout Plain Layout
1802 \begin_layout Plain Layout
1804 TOFILE=`basename $2`
1807 \begin_layout Plain Layout
1809 cp $FROMFILE /home/you/pdf/$TOFILE
1814 Save it in your local LyX directory—say,
1815 \begin_inset Flex Code
1818 \begin_layout Plain Layout
1819 /home/you/.lyx/scripts/pdfcopier.sh
1824 —and make it executable, if you need to do so on your platform.
1826 \begin_inset Flex MenuItem
1829 \begin_layout Plain Layout
1830 Tools\SpecialChar \menuseparator
1836 dialog, select under
1837 \begin_inset Flex MenuItem
1840 \begin_layout Plain Layout
1841 File Handling\SpecialChar \menuseparator
1848 \begin_inset Flex MenuItem
1851 \begin_layout Plain Layout
1857 format—or one of the other pdf formats—and enter
1858 \begin_inset Flex Code
1861 \begin_layout Plain Layout
1862 pdfcopier.sh $$i $$o
1868 \begin_inset Flex MenuItem
1871 \begin_layout Plain Layout
1881 \begin_layout Standard
1882 Copiers are used by LyX in various of its own conversions.
1883 For example, if appropriate programs are found, LyX will automatically
1884 install copiers for the
1885 \begin_inset Flex MenuItem
1888 \begin_layout Plain Layout
1895 \begin_inset Flex MenuItem
1898 \begin_layout Plain Layout
1900 \begin_inset space ~
1909 When these formats are exported, the copier sees that not just the main
1910 HTML file but various associated files (style files, images, etc.) are also
1912 All these files are written to a subdirectory of the directory in which
1913 the original LyX file was found.
1917 \begin_layout Plain Layout
1918 This copier can be customized.
1920 \begin_inset Quotes eld
1924 \begin_inset Quotes erd
1927 argument takes a comma-separated list of extensions to be copied; if it
1928 is omitted, all files will be copied.
1930 \begin_inset Quotes eld
1934 \begin_inset Quotes erd
1937 argument determines the extension added to the generated directory.
1939 \begin_inset Quotes eld
1943 \begin_inset Flex MenuItem
1946 \begin_layout Plain Layout
1953 \begin_inset Quotes erd
1956 , so HTML generated from
1957 \begin_inset Flex MenuItem
1960 \begin_layout Plain Layout
1961 /path/to/filename.lyx
1967 \begin_inset Flex MenuItem
1970 \begin_layout Plain Layout
1971 /path/to/filename.html.LyXconv
1985 \begin_layout Section
1987 \begin_inset CommandInset label
1989 name "sec:Converters"
1996 \begin_layout Standard
1997 You can define your own Converters to convert files between different formats.
1999 \begin_inset Flex MenuItem
2002 \begin_layout Plain Layout
2003 Tools\SpecialChar \menuseparator
2004 Preferences\SpecialChar \menuseparator
2005 File Handling\SpecialChar \menuseparator
2014 \begin_layout Standard
2015 To define a new converter, select the
2016 \begin_inset Flex MenuItem
2019 \begin_layout Plain Layout
2021 \begin_inset space ~
2030 \begin_inset Flex MenuItem
2033 \begin_layout Plain Layout
2035 \begin_inset space ~
2043 from the drop-down lists, enter the command needed for the conversion,
2045 \begin_inset Flex MenuItem
2048 \begin_layout Plain Layout
2055 Several variables can be used in the definition of converters:
2058 \begin_layout Labeling
2059 \labelwidthstring 00.00.0000
2060 \begin_inset Flex Code
2063 \begin_layout Plain Layout
2069 The LyX system directory
2072 \begin_layout Labeling
2073 \labelwidthstring 00.00.0000
2074 \begin_inset Flex Code
2077 \begin_layout Plain Layout
2086 \begin_layout Labeling
2087 \labelwidthstring 00.00.0000
2088 \begin_inset Flex Code
2091 \begin_layout Plain Layout
2100 \begin_layout Labeling
2101 \labelwidthstring 00.00.0000
2102 \begin_inset Flex Code
2105 \begin_layout Plain Layout
2111 The base filename of the input file (i.
2112 \begin_inset space \thinspace{}
2115 g., without the extension)
2118 \begin_layout Labeling
2119 \labelwidthstring 00.00.0000
2120 \begin_inset Flex Code
2123 \begin_layout Plain Layout
2129 The path to the input file
2132 \begin_layout Labeling
2133 \labelwidthstring 00.00.0000
2134 \begin_inset Flex Code
2137 \begin_layout Plain Layout
2143 The path to the original input file (this is different from $$p when a
2144 chain of converters is called)
2145 \change_deleted 1 1287732759
2147 \change_inserted 1 1287732721
2151 \begin_layout Labeling
2152 \labelwidthstring 00.00.0000
2154 \change_inserted 1 1287732753
2155 \begin_inset Flex Code
2158 \begin_layout Plain Layout
2160 \change_inserted 1 1287732729
2166 The iconv name for the encoding of the document.
2169 \begin_layout Standard
2171 \begin_inset Flex MenuItem
2174 \begin_layout Plain Layout
2176 \begin_inset space ~
2184 field you can enter the following flags, separated by commas:
2187 \begin_layout Labeling
2188 \labelwidthstring 00.00.0000
2189 \begin_inset Flex Code
2192 \begin_layout Plain Layout
2198 This converter runs some form of LaTeX.
2199 This will make LyX's LaTeX error logs available.
2202 \begin_layout Labeling
2203 \labelwidthstring 00.00.0000
2204 \begin_inset Flex Code
2207 \begin_layout Plain Layout
2214 \begin_inset Flex MenuItem
2217 \begin_layout Plain Layout
2223 file for the conversion.
2226 \begin_layout Labeling
2227 \labelwidthstring 00.00.0000
2228 \begin_inset Flex Code
2231 \begin_layout Plain Layout
2240 \begin_layout Standard
2241 The following three flags are not really flags at all because they take
2243 \begin_inset Flex MenuItem
2246 \begin_layout Plain Layout
2248 \begin_inset space ~
2252 \begin_inset space ~
2263 \begin_layout Labeling
2264 \labelwidthstring 00.00.0000
2265 \begin_inset Flex Code
2268 \begin_layout Plain Layout
2274 If set, the converter's standard error will be redirected to a file
2275 \begin_inset Flex Code
2278 \begin_layout Plain Layout
2284 , and the script given as argument will be run as:
2285 \begin_inset Flex Code
2288 \begin_layout Plain Layout
2289 script < infile.out > infile.log
2295 The argument may contain
2296 \begin_inset Flex Code
2299 \begin_layout Plain Layout
2308 \begin_layout Labeling
2309 \labelwidthstring 00.00.0000
2310 \begin_inset Flex Code
2313 \begin_layout Plain Layout
2319 The name of the directory in which the converter will dump the generated
2321 LyX will not create this directory, and it does not copy anything into
2322 it, though it will copy this directory to the destination.
2323 The argument may contain
2324 \begin_inset Flex Code
2327 \begin_layout Plain Layout
2333 , which will be replaced by the base name of the input and output files,
2334 respectively, when the directory is copied.
2335 \begin_inset Newline newline
2338 Note that resultdir and usetempdir make no sense together.
2339 The latter will be ignored if the former is given.
2342 \begin_layout Labeling
2343 \labelwidthstring 00.00.0000
2344 \begin_inset Flex Code
2347 \begin_layout Plain Layout
2353 Determines the output file name and may, contain
2354 \begin_inset Flex Code
2357 \begin_layout Plain Layout
2364 Sensible only with resultdir and optional even then; if not given, it defaults
2368 \begin_layout Standard
2369 None of these last three are presently used in any of the converters that
2370 are installed with LyX.
2374 \begin_layout Standard
2375 You do not have to define converters for all formats between which you want
2377 For example, you will note that there is no `LyX to PostScript' converter,
2378 but LyX will export PostScript.
2379 It does so by first creating a LaTeX file (no converter needs to be defined
2380 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2381 and finally converting the resulting DVI file to PostScript.
2382 LyX finds such `chains' of converters automatically, and it will always
2383 choose the shortest possible chain.
2384 You can, though, still define multiple conversion methods between file
2386 For example, the standard LyX configuration provides three ways to convert
2387 LaTeX to PDF: Directly, using
2388 \begin_inset Flex MenuItem
2391 \begin_layout Plain Layout
2397 ; via (DVI and) PostScript, using
2398 \begin_inset Flex MenuItem
2401 \begin_layout Plain Layout
2408 \begin_inset Flex MenuItem
2411 \begin_layout Plain Layout
2418 To define such alternate chains, you must define multiple target `file
2419 formats', as described in section
2420 \begin_inset CommandInset ref
2422 reference "sec:Formats"
2427 For example, in the standard configuration, the formats named
2428 \begin_inset Flex MenuItem
2431 \begin_layout Plain Layout
2438 \begin_inset Flex MenuItem
2441 \begin_layout Plain Layout
2448 \begin_inset Flex MenuItem
2451 \begin_layout Plain Layout
2457 are defined, all of which share the extension
2458 \begin_inset Flex MenuItem
2461 \begin_layout Plain Layout
2467 , and which correspond to the conversion methods just mentioned.
2470 \begin_layout Chapter
2471 Internationalizing LyX
2472 \begin_inset CommandInset label
2474 name "cha:Internationalizing-LyX"
2481 \begin_layout Standard
2482 LyX supports using a translated interface.
2483 Last time we checked, LyX provided text in thirty languages.
2484 The language of choice is called your
2489 (For further reading on locale settings, see also the documentation for
2490 locale that comes with your operating system.
2491 For Linux, the manual page for
2492 \begin_inset Flex Code
2495 \begin_layout Plain Layout
2501 could be a good place to start).
2504 \begin_layout Standard
2505 Notice that these translations will work, but do contain a few flaws.
2506 In particular, all dialogs have been designed with the English text in
2507 mind, which means that some of the translated text will be too large to
2508 fit within the space allocated.
2509 This is only a display problem and will not cause any harm.
2510 Also, you will find that some of the translations do not define shortcut
2511 keys for everything.
2512 Sometimes, there are simply not enough free letters to do it.
2513 Other times, the translator just hasn't got around to doing it yet.
2514 Our localization team, which you may wish to join,
2518 \begin_layout Plain Layout
2519 If you are a fluent speaker of a language other than English, joining these
2520 teams is a great way to give back to the LyX community!
2525 will of course try to fix these shortcomings in future versions of LyX.
2528 \begin_layout Section
2532 \begin_layout Subsection
2533 Translating the graphical user interface (text messages).
2536 \begin_layout Standard
2538 \begin_inset Flex Code
2541 \begin_layout Plain Layout
2547 library to handle the internationalization of the interface.
2548 To have LyX speak your favorite language in all menus and dialogs, you
2550 \begin_inset Flex Code
2553 \begin_layout Plain Layout
2559 -file for that language.
2560 When this is available, you'll have to generate a
2561 \begin_inset Flex Code
2564 \begin_layout Plain Layout
2570 -file from it and install the
2571 \begin_inset Flex Code
2574 \begin_layout Plain Layout
2581 The process of doing all of this is explained in the documentation for
2583 \begin_inset Flex Code
2586 \begin_layout Plain Layout
2593 It is possible to do this just for yourself, but if you're going to do
2594 it, you might as well share the results of your labors with the rest of
2596 Send a message to the LyX developers' list for more information about how
2600 \begin_layout Standard
2601 In short, this is what you should do (xx denotes the language code):
2604 \begin_layout Itemize
2605 Check out the LyX source code.
2607 \begin_inset CommandInset href
2609 name "information on the web"
2610 target "http://www.lyx.org/devel/cvs.php"
2617 \begin_layout Itemize
2619 \begin_inset Flex Code
2622 \begin_layout Plain Layout
2628 to the folder of the
2629 \begin_inset Flex Code
2632 \begin_layout Plain Layout
2640 \begin_inset Flex Code
2643 \begin_layout Plain Layout
2651 \begin_inset Flex Code
2654 \begin_layout Plain Layout
2660 doesn't exist anywhere, it can be remade with the console command
2661 \begin_inset Flex Code
2664 \begin_layout Plain Layout
2670 in that directory, or you can use an existing po-file for some other language
2674 \begin_layout Itemize
2676 \begin_inset Flex Code
2679 \begin_layout Plain Layout
2689 \begin_layout Plain Layout
2690 This is just a text file, so it can be edited in any text editor.
2691 But there are also specialized programs that support such editing, such
2696 (for all platforms) or
2705 contains a `mode' for editing
2706 \begin_inset Flex Code
2709 \begin_layout Plain Layout
2720 For some menu- and widget-labels, there are also shortcut keys that should
2722 Those keys are marked after a `|', and should be translated according to
2723 the words and phrases of the language.
2724 You should also fill also out the information at the beginning of the new
2726 \begin_inset Flex Code
2729 \begin_layout Plain Layout
2735 -file with your email-address, etc., so people know where to reach you with
2736 suggestions and entertaining flames.
2739 \begin_layout Standard
2740 If you are just doing this on your own, then:
2743 \begin_layout Itemize
2745 \begin_inset Flex Code
2748 \begin_layout Plain Layout
2755 This can be done with
2756 \begin_inset Flex Code
2759 \begin_layout Plain Layout
2760 msgfmt -o xx.mo < xx.po
2768 \begin_layout Itemize
2770 \begin_inset Flex Code
2773 \begin_layout Plain Layout
2779 -file to your locale-tree, at the correct directory for application messages
2784 xx, and under the name
2785 \begin_inset Flex Code
2788 \begin_layout Plain Layout
2795 \begin_inset space \thinspace{}
2799 \begin_inset space \space{}
2803 \begin_inset Flex Code
2806 \begin_layout Plain Layout
2807 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2817 \begin_layout Standard
2818 As said, however, it would be best if the new
2819 \begin_inset Flex Code
2822 \begin_layout Plain Layout
2828 -file could be added to the LyX distribution, so others can use it.
2829 Adding it involves making additional changes to LyX.
2830 So send an email to the developers' mailing list if you're interested in
2834 \begin_layout Subsubsection
2838 \begin_layout Standard
2839 Sometimes it turns out that one English message needs to be translated into
2840 different messages in the target language.
2841 One example is the message
2842 \begin_inset Flex Code
2845 \begin_layout Plain Layout
2851 which has the German translation
2859 , depending upon exactly what the English
2860 \begin_inset Quotes eld
2864 \begin_inset Quotes erd
2869 \begin_inset Flex Code
2872 \begin_layout Plain Layout
2878 does not handle such ambiguous translations.
2879 Therefore you have to add some context information to the message: Instead
2881 \begin_inset Flex Code
2884 \begin_layout Plain Layout
2891 \begin_inset Flex Code
2894 \begin_layout Plain Layout
2895 To[[as in 'From format x to format y']]
2901 \begin_inset Flex Code
2904 \begin_layout Plain Layout
2905 To[[as in 'From page x to page y']].
2910 Now the two occurrences of
2911 \begin_inset Flex Code
2914 \begin_layout Plain Layout
2921 \begin_inset Flex Code
2924 \begin_layout Plain Layout
2930 and can be translated correctly to
2941 \begin_layout Standard
2942 Of course the context information needs to be stripped off the original
2943 message when no translation is used.
2944 Therefore you have to put it in double square brackets at the end of the
2945 message (see the example above).
2946 The translation mechanism of LyX ensures that everything in double square
2947 brackets at the end of messages is removed before displaying the message.
2950 \begin_layout Subsection
2951 Translating the documentation.
2954 \begin_layout Standard
2955 The online documentation (in the
2956 \begin_inset Flex MenuItem
2959 \begin_layout Plain Layout
2965 -menu) can (and should!) be translated.
2966 If there are translated versions of the documentation available
2970 \begin_layout Plain Layout
2971 As of March 2008, at least some of the documents have been translated into
2972 fourteen languages, with the Tutorial available in a few more.
2977 and the locale is set accordingly, these will be used automagically by
2979 LyX looks for translated versions as
2980 \begin_inset Flex Code
2983 \begin_layout Plain Layout
2984 LyXDir/doc/xx/DocName.lyx
2990 \begin_inset Flex Code
2993 \begin_layout Plain Layout
2999 is the code for the language currently in use.
3000 If there are no translated documents, the default English versions will
3002 Note that the translated versions must have the same filenames (
3003 \begin_inset Flex Code
3006 \begin_layout Plain Layout
3012 above) as the original.
3013 If you feel up to translating the documentation (an excellent way to proof-read
3014 the original documentation by the way!), there are a few things you should
3018 \begin_layout Itemize
3019 Check out the documentation translation web page at
3020 \begin_inset CommandInset href
3022 name "http://www.lyx.org/Translation"
3023 target "http://www.lyx.org/Translation"
3028 That way, you can find out which (if any) documents have already been translate
3029 d into your language.
3030 You can also find out who (if anyone) is organizing the effort to translate
3031 the documentation into your language.
3032 If no one is organizing the effort, please let us know that you're interested.
3035 \begin_layout Standard
3036 Once you get to actually translating, here's a few hints for you that may
3040 \begin_layout Itemize
3041 Join the documentation team! There is information on how to do that in
3042 \begin_inset Flex Code
3045 \begin_layout Plain Layout
3052 \begin_inset Flex MenuItem
3055 \begin_layout Plain Layout
3056 Help\SpecialChar \menuseparator
3062 ), which by the way is the first document you should translate.
3065 \begin_layout Itemize
3066 Learn the typographic conventions for the language you are translating to.
3067 Typography is an ancient art and over the centuries, a great variety of
3068 conventions have developed throughout different parts of the world.
3069 Also study the professional terminology amongst typographers in your country.
3070 Inventing your own terminology will only confuse the users.
3073 (Warning! Typography is addictive!)
3076 \begin_layout Itemize
3077 Make a copy of the document.
3078 This will be your working copy.
3079 You can use this as your personal translated help-file by placing it in
3081 \begin_inset Flex Code
3084 \begin_layout Plain Layout
3093 \begin_layout Itemize
3094 Sometimes the original document (from the LyX-team) will be updated.
3095 Use the source viewer at
3096 \begin_inset CommandInset href
3098 name "http://www.lyx.org/trac/timeline"
3099 target "http://www.lyx.org/trac/timeline"
3103 to see what has been changed.
3104 That way you can easily see which parts of the translated document need
3108 \begin_layout Standard
3109 If you ever find an error in the original document, fix it and notify the
3110 rest of the documentation team of the changes! (You didn't forget to join
3111 the documentation team, did you?)
3114 \begin_layout Standard
3115 \begin_inset Branch OutDated
3118 \begin_layout Section
3119 International Keyboard Support
3122 \begin_layout Standard
3125 [Editor's Note: The following section is by
3133 It needs to be fixed to conform to the new Documentation Style sheet and
3134 to make use of the new v1.0 features.
3135 The whole thing also needs to be merged with the section following it.-jw
3136 It may also be badly out of date.-rh (2008)]
3139 \begin_layout Subsection
3140 Defining Own Keymaps: Keymap File Format
3143 \begin_layout Standard
3144 Let's look at a keyboard definition file a little closer.
3145 It is a plain text file defining
3148 \begin_layout Itemize
3149 key-to-key or key-to-string translations
3152 \begin_layout Itemize
3156 \begin_layout Itemize
3157 dead keys exceptions
3160 \begin_layout Standard
3161 To define key-to-key or key-to-string translation, use this command:
3164 \begin_layout Quotation
3165 \begin_inset Flex Code
3168 \begin_layout Plain Layout
3177 \begin_inset Flex Code
3180 \begin_layout Plain Layout
3189 \begin_layout Standard
3191 \begin_inset Flex Code
3194 \begin_layout Plain Layout
3200 is the key to be translated and
3201 \begin_inset Flex Code
3204 \begin_layout Plain Layout
3210 is the string to be inserted into the document.
3211 To define dead keys, use:
3214 \begin_layout Quotation
3215 \begin_inset Flex Code
3218 \begin_layout Plain Layout
3227 \begin_inset Flex Code
3230 \begin_layout Plain Layout
3239 \begin_layout Standard
3241 \begin_inset Flex Code
3244 \begin_layout Plain Layout
3250 is a keyboard key and
3251 \begin_inset Flex Code
3254 \begin_layout Plain Layout
3261 The following dead keys are supported (shortcut name is in parentheses):
3264 \begin_layout Quotation
3268 \begin_inset space \hfill{}
3274 \begin_layout Quotation
3276 \begin_inset space \hfill{}
3282 \begin_layout Quotation
3284 \begin_inset space \hfill{}
3290 \begin_layout Quotation
3292 \begin_inset space \hfill{}
3298 \begin_layout Quotation
3300 \begin_inset space \hfill{}
3306 \begin_layout Quotation
3308 \begin_inset space \hfill{}
3315 \begin_layout Plain Layout
3327 \begin_layout Quotation
3329 \begin_inset space \hfill{}
3335 \begin_layout Quotation
3337 \begin_inset space \hfill{}
3344 \begin_layout Plain Layout
3356 \begin_layout Quotation
3358 \begin_inset space \hfill{}
3364 \begin_layout Quotation
3366 \begin_inset space \hfill{}
3372 \begin_layout Quotation
3374 \begin_inset space \hfill{}
3381 \begin_layout Plain Layout
3393 \begin_layout Quotation
3395 \begin_inset space \hfill{}
3402 \begin_layout Plain Layout
3414 \begin_layout Quotation
3416 \begin_inset space \hfill{}
3422 \begin_layout Quotation
3423 hungarian umlaut (hug)
3424 \begin_inset space \hfill{}
3430 \begin_layout Quotation
3432 \begin_inset space \hfill{}
3438 \begin_layout Quotation
3440 \begin_inset space \hfill{}
3447 \begin_layout Plain Layout
3459 \begin_layout Standard
3460 Since in many international keyboards there are exceptions to what some
3461 dead keys should do, you can define them using
3464 \begin_layout Quotation
3465 \begin_inset Flex Code
3468 \begin_layout Plain Layout
3476 deadkey key outstring
3479 \begin_layout Standard
3480 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3484 \begin_layout Quotation
3485 \begin_inset Flex Code
3488 \begin_layout Plain Layout
3501 \begin_layout Standard
3502 to make it work correctly.
3503 Also, you have to define as exceptions dead keys over i and j, to remove
3504 the dot from them before inserting an accent mark.
3505 I will change this when the time comes, but so far I haven't had time.
3508 \begin_layout Standard
3509 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3512 \begin_inset Flex Code
3515 \begin_layout Plain Layout
3521 have different meaning.
3523 \begin_inset Flex Code
3526 \begin_layout Plain Layout
3532 marks comments, quotes start and end LaTeX-style commands.
3533 To enter quote, you'll need to use
3534 \begin_inset Flex Code
3537 \begin_layout Plain Layout
3546 \begin_inset Flex Code
3549 \begin_layout Plain Layout
3556 \begin_inset Flex Code
3559 \begin_layout Plain Layout
3570 \begin_layout Standard
3571 If you make a keyboard description file that works for your language, please
3572 mail it to me, so I can include it in the next keymap distribution.
3575 \begin_layout Standard
3576 More keywords will be supported in keymap configuration file in future,
3580 \begin_layout Itemize
3581 \begin_inset Flex Code
3584 \begin_layout Plain Layout
3595 \begin_inset space \hfill{}
3599 \begin_inset Flex Code
3602 \begin_layout Plain Layout
3611 \begin_layout Itemize
3612 \begin_inset Flex Code
3615 \begin_layout Plain Layout
3626 \begin_inset space \hfill{}
3630 \begin_inset Flex Code
3633 \begin_layout Plain Layout
3639 an external keymap translation program
3642 \begin_layout Standard
3643 Also, it should look into
3644 \begin_inset Flex Code
3647 \begin_layout Plain Layout
3653 file for defaults, too (for example, a
3654 \begin_inset Flex Code
3657 \begin_layout Plain Layout
3665 option to include default keyboard).
3673 \begin_layout Section
3674 International Keymap Stuff
3675 \begin_inset CommandInset label
3677 name "sec:International-Keymap-Stuff"
3684 \begin_layout Standard
3685 \begin_inset Note Note
3688 \begin_layout Plain Layout
3689 In doing the revisions on this document in March 2008, I did not look over
3690 this stuff, as I do not understand it.
3691 It would be good if someone else could do so.
3700 \begin_layout Standard
3701 The next two sections describe the
3702 \begin_inset Flex Code
3705 \begin_layout Plain Layout
3714 \begin_inset Flex Code
3717 \begin_layout Plain Layout
3725 file syntax in detail.
3726 These sections should help you design your own key map if the ones provided
3727 do not meet your needs.
3730 \begin_layout Subsection
3734 \begin_layout Standard
3738 \begin_inset Flex Code
3741 \begin_layout Plain Layout
3747 file maps keystrokes to characters or strings.
3748 As the name suggests, it sets a keyboard mapping.
3750 \begin_inset Flex Code
3753 \begin_layout Plain Layout
3764 \begin_inset Flex Code
3767 \begin_layout Plain Layout
3782 \begin_inset Flex Code
3785 \begin_layout Plain Layout
3798 \begin_inset Flex Code
3801 \begin_layout Plain Layout
3810 \begin_inset Flex Code
3813 \begin_layout Plain Layout
3821 are described in this section.
3824 \begin_layout Labeling
3825 \labelwidthstring 00.00.0000
3826 \begin_inset Flex Code
3829 \begin_layout Plain Layout
3837 Map a character to a string
3840 \begin_layout LyX-Code
3855 \begin_layout Standard
3888 the double-quote (")
3905 must be escaped with a preceding backslash (
3916 \begin_layout Standard
3918 \begin_inset Flex MenuItem
3921 \begin_layout Plain Layout
3929 statement to cause the symbol
3930 \begin_inset Flex MenuItem
3933 \begin_layout Plain Layout
3941 to be output for the keystroke
3942 \begin_inset Flex MenuItem
3945 \begin_layout Plain Layout
3956 \begin_layout LyX-Code
3962 \begin_layout Labeling
3963 \labelwidthstring 00.00.0000
3964 \begin_inset Flex Code
3967 \begin_layout Plain Layout
3975 Specify an accent character
3978 \begin_layout LyX-Code
3987 \begin_layout Standard
3988 This will make the cha
4026 This is the dead key
4030 \begin_layout Plain Layout
4037 refers to a key that does not produce a character by itself, but when followed
4038 with another key, produces the desired accent character.
4039 For example, a German characte
4041 r with an umlaut like
4051 can be produced in this manner.
4060 \begin_layout Standard
4073 and then another key not in
4090 followed by the other, not allowed key, as output.
4094 \begin_inset Flex MenuItem
4097 \begin_layout Plain Layout
4105 cancels a dead key, so if
4116 \begin_inset Flex MenuItem
4119 \begin_layout Plain Layout
4128 , the cursor will not go one position backwards but will instead cancel
4144 might have had on the next keystroke.
4148 \begin_layout Standard
4149 The following example specifies that the character ' is to be an acute accent,
4150 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4153 \begin_layout LyX-Code
4156 kmod ' acute aeiouAEIOU
4159 \begin_layout Labeling
4160 \labelwidthstring 00.00.0000
4161 \begin_inset Flex Code
4164 \begin_layout Plain Layout
4170 Specify an exception to the accent character
4173 \begin_layout LyX-Code
4182 \begin_layout Standard
4183 This defines an exce
4224 have been assigned a keystroke with a previous
4227 \begin_inset Flex Code
4230 \begin_layout Plain Layout
4254 must not belong in the
4301 If such a declaration does not exist in
4309 \begin_inset Flex Code
4312 \begin_layout Plain Layout
4346 \begin_inset Flex Code
4349 \begin_layout Plain Layout
4363 \begin_layout Standard
4364 The following command produces causes äi to be produced when you enter acute-i
4368 \begin_layout LyX-Code
4382 \begin_layout Labeling
4383 \labelwidthstring 00.00.0000
4384 \begin_inset Flex Code
4387 \begin_layout Plain Layout
4393 Combine two accent characters
4396 \begin_layout LyX-Code
4402 accent1 accent2 allowed
4405 \begin_layout Standard
4406 This one is getting pretty esoteric.
4407 It allows you to combine the effect
4463 \begin_inset Flex Code
4466 \begin_layout Plain Layout
4494 \begin_layout Standard
4495 Consider this example from the
4496 \begin_inset Flex Code
4499 \begin_layout Plain Layout
4510 \begin_layout LyX-Code
4513 kmod ; acute aeioyvhAEIOYVH
4517 kcomb acute umlaut iyIY
4520 \begin_layout Standard
4521 This allows you to press
4522 \begin_inset Flex MenuItem
4525 \begin_layout Plain Layout
4533 and get the effect of
4534 \begin_inset Flex Code
4537 \begin_layout Plain Layout
4556 in this case cancels the last dead key, so if you press
4557 \begin_inset Flex MenuItem
4560 \begin_layout Plain Layout
4569 \begin_inset Flex Code
4572 \begin_layout Plain Layout
4585 \begin_layout Subsection
4589 \begin_layout Standard
4591 \begin_inset Flex Code
4594 \begin_layout Plain Layout
4602 mapping is performed, a
4603 \begin_inset Flex Code
4606 \begin_layout Plain Layout
4616 file maps the strings that the symbols generate to characters in the current
4618 The LyX distribution currently includes at least the
4619 \begin_inset Flex Code
4622 \begin_layout Plain Layout
4631 \begin_inset Flex Code
4634 \begin_layout Plain Layout
4645 \begin_layout Standard
4647 \begin_inset Flex Code
4650 \begin_layout Plain Layout
4658 file is a sequence of declarations of the form
4661 \begin_layout LyX-Code
4674 \begin_layout Standard
4675 For example, in order to map
4676 \begin_inset Flex MenuItem
4679 \begin_layout Plain Layout
4689 to the corresponding character in the iso-8859-1 set (233), the following
4693 \begin_layout LyX-Code
4701 \begin_layout Standard
4703 \begin_inset Flex Code
4706 \begin_layout Plain Layout
4715 \begin_inset Flex Code
4718 \begin_layout Plain Layout
4736 the same character can apply to more than one string.
4738 \begin_inset Flex Code
4741 \begin_layout Plain Layout
4752 \begin_layout LyX-Code
4764 \begin_inset Newline newline
4780 \begin_layout Standard
4781 If LyX cannot find a mapping for the string produced by the keystroke or
4782 a deadkey sequence, it will check if it looks like an accented char and
4783 try to draw an accent over the character on screen.
4786 \begin_layout Subsection
4790 \begin_layout Standard
4791 There is a second way to add support for international characters through
4792 so-called dead-keys.
4793 A dead-key works in combination with a letter to produce an accented character.
4794 Here, we'll explain how to create a really simple dead-key to illustrate
4798 \begin_layout Standard
4799 Suppose you happen to need the circumflex character,
4800 \begin_inset Quotes eld
4804 \begin_inset Quotes erd
4809 \begin_inset Flex MenuItem
4812 \begin_layout Plain Layout
4819 \begin_inset space ~
4823 \begin_inset Flex MenuItem
4826 \begin_layout Plain Layout
4832 ] to the LyX command
4833 \begin_inset Flex Code
4836 \begin_layout Plain Layout
4843 \begin_inset Flex Code
4846 \begin_layout Plain Layout
4853 Now, whenever you type the
4854 \begin_inset Flex MenuItem
4857 \begin_layout Plain Layout
4863 -key followed by a letter, that letter will have a circumflex accent on
4865 For example, the sequence
4866 \begin_inset Quotes eld
4870 \begin_inset Flex MenuItem
4873 \begin_layout Plain Layout
4880 \begin_inset Quotes erd
4883 produces the letter:
4884 \begin_inset Quotes eld
4888 \begin_inset Quotes erd
4892 If you tried to type
4893 \begin_inset Quotes eld
4897 \begin_inset Flex MenuItem
4900 \begin_layout Plain Layout
4907 \begin_inset Quotes erd
4910 , however, LyX will complain with a beep, since a
4911 \begin_inset Quotes eld
4915 \begin_inset Flex MenuItem
4918 \begin_layout Plain Layout
4925 \begin_inset Quotes erd
4928 never takes a circumflex accent.
4930 \begin_inset Flex MenuItem
4933 \begin_layout Plain Layout
4939 after a dead-key produces the bare-accent.
4940 Please note this last point! If you bind a key to a dead-key, you'll need
4941 to rebind the character on that key to yet another key.
4943 \begin_inset Flex MenuItem
4946 \begin_layout Plain Layout
4952 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4955 \begin_layout Standard
4956 One common way to bind dead-keys is to use
4957 \begin_inset Flex MenuItem
4960 \begin_layout Plain Layout
4967 \begin_inset Flex MenuItem
4970 \begin_layout Plain Layout
4977 \begin_inset Flex MenuItem
4980 \begin_layout Plain Layout
4986 in combination with an accent, like
4987 \begin_inset Quotes eld
4991 \begin_inset Flex MenuItem
4994 \begin_layout Plain Layout
5001 \begin_inset Quotes erd
5005 \begin_inset Quotes eld
5009 \begin_inset Flex MenuItem
5012 \begin_layout Plain Layout
5019 \begin_inset Quotes erd
5023 \begin_inset Quotes eld
5027 \begin_inset Flex MenuItem
5030 \begin_layout Plain Layout
5037 \begin_inset Quotes erd
5041 Another way involves using
5042 \begin_inset Flex Code
5045 \begin_layout Plain Layout
5052 \begin_inset Flex Code
5055 \begin_layout Plain Layout
5061 to set up the special
5062 \begin_inset Flex Code
5065 \begin_layout Plain Layout
5073 \begin_inset Flex Code
5076 \begin_layout Plain Layout
5082 acts in some ways just like
5083 \begin_inset Flex MenuItem
5086 \begin_layout Plain Layout
5092 and permits you to bind keys to accented characters.
5093 You can also turn keys into dead-keys by binding them to something like
5095 \begin_inset Flex Code
5098 \begin_layout Plain Layout
5104 and then binding this symbolic key to the corresponding LyX command.
5108 \begin_layout Plain Layout
5113 : This is exactly what I do in my
5114 \begin_inset Flex Code
5117 \begin_layout Plain Layout
5124 \begin_inset Flex Code
5127 \begin_layout Plain Layout
5135 \begin_inset Flex MenuItem
5138 \begin_layout Plain Layout
5140 \begin_inset space ~
5149 \begin_inset Flex Code
5152 \begin_layout Plain Layout
5158 and a bunch of these
5159 \begin_inset Quotes eld
5163 \begin_inset Flex Code
5166 \begin_layout Plain Layout
5173 \begin_inset Quotes erd
5176 symbolic keys bound such things as
5177 \begin_inset Flex MenuItem
5180 \begin_layout Plain Layout
5182 \begin_inset space ~
5191 \begin_inset Flex MenuItem
5194 \begin_layout Plain Layout
5196 \begin_inset space ~
5205 This is how I produce my accented characters.
5210 You can make just about anything into the
5211 \begin_inset Flex Code
5214 \begin_layout Plain Layout
5221 \begin_inset Flex MenuItem
5224 \begin_layout Plain Layout
5230 keys, a spare function key, etc.
5231 As for the LyX commands that produce accents, check the entry for
5232 \begin_inset Flex Code
5235 \begin_layout Plain Layout
5246 You'll find the complete list there.
5249 \begin_layout Subsection
5250 Saving your Language Configuration
5253 \begin_layout Standard
5254 You can edit your preferences so that your desired language environment
5255 is automatically configured when LyX starts up, via the
5256 \begin_inset Flex MenuItem
5259 \begin_layout Plain Layout
5260 Edit\SpecialChar \menuseparator
5269 \begin_layout Chapter
5270 Installing New Document Classes, Layouts, and Templates
5271 \begin_inset CommandInset label
5273 name "cha:Installing-New-Document"
5278 \begin_inset Argument
5281 \begin_layout Plain Layout
5282 Installing New Document Classes
5290 \begin_layout Standard
5291 In this chapter, we describe the procedures for creating and installing
5292 new LyX layout and template files, as well as offer a refresher on correctly
5293 installing new LaTeX document classes.
5297 \begin_layout Standard
5298 First, let us a say a few words about how one ought to think about the relation
5299 between LyX and LaTeX.
5300 The thing to understand is that, in a certain sense, LyX doesn't know anything
5302 Indeed, from LyX's point of view, LaTeX is just one of several
5303 \begin_inset Quotes eld
5307 \begin_inset Quotes erd
5310 in which it is capable of producing output.
5311 Other such formats are DocBook, plaintext, and XHTML.
5312 LaTeX is, of course, a particularly important format, but very little of
5313 the information LyX has about LaTeX is actually contained in the program
5318 \begin_layout Plain Layout
5319 Some commands are sufficiently complex that they are
5320 \begin_inset Quotes eld
5324 \begin_inset Quotes erd
5328 But the developers generally regard this as a Bad Thing.
5333 Rather, that information, even for the standard classes like
5334 \begin_inset Flex Code
5337 \begin_layout Plain Layout
5343 , is contained in `layout files'.
5344 Similarly, LyX itself does not know much about DocBook or XHTML.
5345 What it knows is contained in layout files.
5348 \begin_layout Standard
5349 You can think of the layout file for a given document class as a translation
5350 manual between LyX constructs---paragraphs with their corresponding styles,
5351 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5353 Almost everything LyX knows about
5354 \begin_inset Flex Code
5357 \begin_layout Plain Layout
5363 , for example, is contained in the file
5364 \begin_inset Flex Code
5367 \begin_layout Plain Layout
5373 and in various other files it includes.
5374 For this reason, anyone intending to write layout files should plan to
5375 study the existing files.
5376 A good place to start is with
5377 \begin_inset Flex Code
5380 \begin_layout Plain Layout
5386 , which is included in
5387 \begin_inset Flex Code
5390 \begin_layout Plain Layout
5397 \begin_inset Flex Code
5400 \begin_layout Plain Layout
5406 , and many of the other layout files for document classes.
5407 This file is where sections and the like are defined:
5408 \begin_inset Flex Code
5411 \begin_layout Plain Layout
5417 tells LyX how paragraphs that are marked with the Section, Subsection,
5418 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5421 \begin_inset Flex Code
5424 \begin_layout Plain Layout
5430 file basically just includes several of these
5431 \begin_inset Flex Code
5434 \begin_layout Plain Layout
5443 \begin_layout Standard
5444 Defining the LyX--LaTeX correspondence is not the only thing layout files
5446 Their other job is to define how the LyX constructs themselves will appear
5448 The fact that layout files have these two jobs is often a source of confusion,
5449 because they are completely separate.
5450 Telling LyX how to translate a certain paragraph style into LaTeX does
5451 not tell LyX how to display it; conversely, telling LyX how to display
5452 a certain paragraph style does not tell LyX how to translate it into LaTeX
5453 (let alone tell LaTeX how to display it).
5454 So, in general, when you define a new LyX construct, you must always do
5455 two quite separate things: (i)
5456 \begin_inset space ~
5459 tell LyX how to translate it into LaTeX and (ii)
5460 \begin_inset space ~
5463 tell LyX how to display it.
5466 \begin_layout Standard
5467 Much the same is true, of course, as regards LyX's other backend formats,
5468 though XHTML is in some ways different, because in that case LyX
5472 able, to some extent, to use information about how it should display a
5473 paragraph on the screen to output information (in the form of CSS) about
5474 how the paragraph should be displayed in a browser.
5475 Even in this case, however, the distinction between what LyX does internally
5476 and how things are rendered externally remains in force, and the two can
5477 be controlled separately.
5479 \begin_inset CommandInset ref
5481 reference "sec:Tags-for-XHTML"
5488 \begin_layout Section
5489 Installing new LaTeX files
5492 \begin_layout Standard
5493 Some installations may not include a LaTeX package or class file that you
5494 would like to use within LyX.
5495 For example, you might need FoilTeX, a package for preparing slides for
5496 overhead projectors.
5497 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5498 a user interface for installing such packages.
5499 For example, with MiKTeX, you start the program
5500 \begin_inset Quotes eld
5504 \begin_inset space ~
5508 \begin_inset Quotes erd
5511 to get a list of available packages.
5512 To install one of them, right click on it or use the corresponding toolbar
5516 \begin_layout Standard
5517 If your LaTeX distribution does not provide such a `package manager', or
5518 if the package is not available from your distribution, then follow these
5519 steps to install it manually:
5522 \begin_layout Enumerate
5523 Get the package from
5524 \begin_inset CommandInset href
5527 target "http://www.ctan.org/"
5534 \begin_layout Enumerate
5535 If the package contains a file with the ending
5536 \begin_inset Quotes eld
5540 \begin_inset Flex Code
5543 \begin_layout Plain Layout
5550 \begin_inset Quotes erd
5553 (is the case for FoilTeX) then open a console, change to the folder of
5554 this file and execute the command
5555 \begin_inset Flex Code
5558 \begin_layout Plain Layout
5565 You have now unpacked the package and have all files to install it.
5566 Most LaTeX-packages are not packed and you can skip this step.
5569 \begin_layout Enumerate
5570 Now you need to decide if the package should be available for all users
5575 \begin_layout Enumerate
5576 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5577 for all users on your system, then install it in your `local' TeX tree,
5578 otherwise install it in your own `user' TeX tree.
5579 Where these trees should be created, if they do not already exist, depends
5581 To find this out, look in the file
5582 \begin_inset Flex Code
5585 \begin_layout Plain Layout
5595 \begin_layout Plain Layout
5596 This is usually in the directory
5597 \begin_inset Flex Code
5600 \begin_layout Plain Layout
5606 , though you can execute the command
5607 \begin_inset Flex Code
5610 \begin_layout Plain Layout
5621 The location of the `local' TeX tree is defined by the
5622 \begin_inset Flex Code
5625 \begin_layout Plain Layout
5631 variable; this is usually somewhere like
5632 \begin_inset Flex Code
5635 \begin_layout Plain Layout
5636 /usr/local/share/texmf
5642 The location of the `user' TeX tree is defined by
5643 \begin_inset Flex Code
5646 \begin_layout Plain Layout
5653 \begin_inset Flex Code
5656 \begin_layout Plain Layout
5663 (If these variables are not predefined, you have to define them.) You'll
5664 probably need root permissions to create or modify the `local' tree, but
5665 not for your `user' tree.
5666 \begin_inset Newline newline
5669 In general, it is recommended to install in the user tree because your user
5670 will not be modified or even overwritten when you upgrade your system.
5671 It will typically also be backed up together with everything else when
5672 you backup your home directory (which, of course, you do on a regular basis).
5675 \begin_layout Enumerate
5676 On Windows, if you want the new package to be available for all users on
5677 your system, change to the folder where LaTeX is installed and then change
5679 \begin_inset Flex Code
5682 \begin_layout Plain Layout
5693 (For MiKTeX, this would be by default the folder
5694 \begin_inset Flex Code
5697 \begin_layout Plain Layout
5715 \begin_layout Plain Layout
5716 Note that this will be the correct path only on English installations.
5717 On a German one, it would be
5718 \begin_inset Flex Code
5721 \begin_layout Plain Layout
5735 , and similarly for other languages.
5740 Create there a new folder
5741 \begin_inset Flex Code
5744 \begin_layout Plain Layout
5750 and copy all files of the package into it.
5752 \begin_inset Newline newline
5755 If the package should only available for you or you don't have admin permissions
5756 , do the same, but in the local LaTeX folder.
5758 \begin_inset space \thinspace{}
5762 \begin_inset space ~
5765 2.8 under Windows XP, this would be the folder:
5766 \begin_inset Newline newline
5772 \begin_inset Flex Code
5775 \begin_layout Plain Layout
5778 Documents and Settings
5790 \begin_inset Newline newline
5796 \begin_inset Phantom HPhantom
5799 \begin_layout Plain Layout
5810 \begin_inset Flex Code
5813 \begin_layout Plain Layout
5826 \begin_inset Newline newline
5829 On Vista, it would be:
5830 \begin_inset Newline newline
5834 \begin_inset Flex Code
5837 \begin_layout Plain Layout
5863 \begin_layout Enumerate
5864 Now one only need to tell LaTeX that there are new files.
5865 This depends on the used LaTeX-Distribution:
5869 \begin_layout Enumerate
5870 For TeXLive execute the command
5871 \begin_inset Flex Code
5874 \begin_layout Plain Layout
5881 If you installed the package for all users, then you will probably need
5882 to have root permissions for that.
5885 \begin_layout Enumerate
5886 For MiKTeX, if you have installed the package for all users, start the program
5888 \begin_inset Quotes eld
5892 \begin_inset space ~
5896 \begin_inset Quotes erd
5899 and press the button marked
5900 \begin_inset Quotes eld
5904 \begin_inset Quotes erd
5908 Otherwise start the program
5909 \begin_inset Quotes eld
5913 \begin_inset Quotes erd
5920 \begin_layout Enumerate
5921 Finally, you need to tell LyX that there are new packages available.
5922 So, in LyX, use the menu
5923 \begin_inset Flex MenuItem
5926 \begin_layout Plain Layout
5929 \SpecialChar \menuseparator
5935 and then restart LyX.
5938 \begin_layout Standard
5939 Now the package is installed.
5940 In our example, the document class
5941 \begin_inset Flex Code
5944 \begin_layout Plain Layout
5946 \begin_inset space ~
5953 \begin_layout Plain Layout
5965 will now be available under
5966 \begin_inset Flex MenuItem
5969 \begin_layout Plain Layout
5970 Document\SpecialChar \menuseparator
5971 Settings\SpecialChar \menuseparator
5981 \begin_layout Standard
5982 If you would like to use a LaTeX document class that is not even listed
5984 \begin_inset Flex MenuItem
5987 \begin_layout Plain Layout
5988 Document\SpecialChar \menuseparator
5989 Settings\SpecialChar \menuseparator
5995 , then you need to create a `layout' file for it.
5996 That is the topic of the next section.
5999 \begin_layout Section
6000 Types of layout files
6003 \begin_layout Standard
6004 This section describes the various sorts of LyX files that contain layout
6006 These files describe various paragraph and character styles, determining
6007 how LyX should display them and how they should be translated into LaTeX,
6008 DocBook, XHTML, or whatever output format is being used.
6012 \begin_layout Standard
6013 We shall try to provide a thorough description of the process of writing
6015 However, there are so many different types of documents supported even
6016 by just LaTeX that we can't hope to cover every different possibility or
6017 problem you might encounter.
6018 The LyX users' list is frequented by people with lots of experience with
6019 layout design who are willing to share what they've learned, so please
6020 feel free to ask questions there.
6023 \begin_layout Standard
6024 As you prepare to write a new layout, it is extremely helpful to look at
6025 the layouts distributed with LyX.
6026 If you write a LyX layout for a LaTeX document class that might also be
6027 used by others, or write a module that might be useful to others, then
6028 you should consider posting your layout to the
6029 \begin_inset CommandInset href
6031 name "layout section on the LyX wiki"
6032 target "http://wiki.lyx.org/Layouts/Layouts"
6036 or even to the LyX developers' list, so that it might be included in LyX
6041 \begin_layout Plain Layout
6042 Note that LyX is licensed under the General Public License, so any material
6043 that is contributed to LyX must be similarly licensed.
6051 \begin_layout Subsection
6053 \begin_inset CommandInset label
6055 name "sub:Layout-modules"
6062 \begin_layout Standard
6063 We have spoken to this point about `layout files'.
6064 But there are different sorts of files that contain layout information.
6065 Layout files, strictly so called, have the
6066 \begin_inset Flex Code
6069 \begin_layout Plain Layout
6075 extension and provide LyX with information about document classes.
6076 As of LyX 1.6, however, layout information can also be contained in layout
6082 \begin_inset Flex Code
6085 \begin_layout Plain Layout
6092 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6093 some modules—such as the
6094 \begin_inset Flex Code
6097 \begin_layout Plain Layout
6103 module—specifcally provide support for one package.
6104 In a sense, layout modules are similar to included
6108 \begin_layout Plain Layout
6109 These can have any extension, but by convention have the
6110 \begin_inset Flex Code
6113 \begin_layout Plain Layout
6125 \begin_inset Flex Code
6128 \begin_layout Plain Layout
6134 —in that modules are not specific to a given document class but may be used
6135 with many different classes.
6136 The difference is that using an included file with
6137 \begin_inset Flex Code
6140 \begin_layout Plain Layout
6146 requires editing that file.
6147 Modules, by contrast, are selected in the
6148 \begin_inset Flex MenuItem
6151 \begin_layout Plain Layout
6152 Document\SpecialChar \menuseparator
6161 \begin_layout Standard
6162 Building modules is the easiest way to get started with layout editing,
6163 since it can be as simple as adding a single new paragraph style or flex
6165 But modules may, in principle, contain anything a layout file can contain.
6168 \begin_layout Standard
6169 After creating a new module and copying it to the
6170 \begin_inset Flex Code
6173 \begin_layout Plain Layout
6179 folder, you will need to reconfigure and then restart LyX for the module
6180 to appear in the menu.
6181 However, changes you make to the module will be seen immediately, if you
6183 \begin_inset Flex MenuItem
6186 \begin_layout Plain Layout
6187 Document\SpecialChar \menuseparator
6193 , highlight something, and then hit
6194 \begin_inset Quotes eld
6198 \begin_inset Quotes erd
6204 It is strongly recommended that you save your work before doing this
6209 it is strongly recommended that you not attempt to edit modules while simultaneo
6210 usly working on actual documents
6213 Though of course the developers strive to keep LyX stable in such situations,
6214 syntax errors and the like in your module file could cause strange behavior.
6217 \begin_layout Subsection
6219 \begin_inset Flex MenuItem
6222 \begin_layout Plain Layout
6231 \begin_layout Standard
6232 There are two situations you are likely to encounter when wanting to support
6233 a new LaTeX document class, involving LaTeX2e class (
6234 \begin_inset Flex Code
6237 \begin_layout Plain Layout
6244 \begin_inset Flex Code
6247 \begin_layout Plain Layout
6254 Supporting a style file is usually fairly easy.
6255 Supporting a new class file is a bit harder.
6256 We'll discuss the former in this section and the latter in the next.
6257 Similar remarks apply, of course, if you want to support a new DocBook
6261 \begin_layout Standard
6262 The easier case is the one in which your new document class is provided
6263 as a style file that is to be used in conjunction with an already supported
6265 For the sake of the example, we'll assume that the style file is called
6267 \begin_inset Flex MenuItem
6270 \begin_layout Plain Layout
6276 and that it is meant to be used with
6277 \begin_inset Flex MenuItem
6280 \begin_layout Plain Layout
6286 , which is a standard class.
6290 \begin_layout Standard
6291 Start by copying the existing class's layout file into your local directory:
6295 \begin_layout Plain Layout
6296 Of course, which directory is your local directory will vary by platform,
6297 and LyX allows you to specify your local directory on startup, too, using
6299 \begin_inset Flex Code
6302 \begin_layout Plain Layout
6316 \begin_layout LyX-Code
6317 cp report.layout ~/.lyx/layouts/myclass.layout
6320 \begin_layout Standard
6322 \begin_inset Flex Code
6325 \begin_layout Plain Layout
6331 and change the line:
6334 \begin_layout LyX-Code
6337 DeclareLaTeXClass{report}
6340 \begin_layout Standard
6344 \begin_layout LyX-Code
6347 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6350 \begin_layout Standard
6354 \begin_layout LyX-Code
6356 \begin_inset Newline newline
6362 \begin_inset Newline newline
6368 \begin_layout Standard
6369 near the top of the file.
6372 \begin_layout Standard
6373 Start LyX and select
6374 \begin_inset Flex MenuItem
6377 \begin_layout Plain Layout
6378 Tools\SpecialChar \menuseparator
6385 Then restart LyX and try creating a new document.
6387 \begin_inset Flex MenuItem
6390 \begin_layout Plain Layout
6396 " as a document class option in the
6397 \begin_inset Flex MenuItem
6400 \begin_layout Plain Layout
6401 Document\SpecialChar \menuseparator
6408 It is likely that some of the sectioning commands and such in your new
6409 class will work differently from how they worked in the base class—
6410 \begin_inset Flex Code
6413 \begin_layout Plain Layout
6419 in this example—so you can fiddle around with the settings for the different
6420 sections if you wish.
6421 The layout information for sections is contained in
6422 \begin_inset Flex Code
6425 \begin_layout Plain Layout
6431 , but you do not need to copy and change this file.
6432 Instead, you can simply add your changes to your layout file, after the
6434 \begin_inset Flex Code
6437 \begin_layout Plain Layout
6443 , which itself includes
6444 \begin_inset Flex Code
6447 \begin_layout Plain Layout
6454 For example, you might add these lines:
6457 \begin_layout LyX-Code
6461 \begin_layout LyX-Code
6465 \begin_layout LyX-Code
6469 \begin_layout LyX-Code
6473 \begin_layout LyX-Code
6477 \begin_layout Standard
6478 to change the font for chapter headings to sans-serif.
6479 This will override (or, in this case, add to) the existing declaration
6480 for the Chapter style.
6484 \begin_layout Standard
6485 Your new package may also provide commands or environments not present in
6487 In this case, you will want to add these to the layout file.
6489 \begin_inset CommandInset ref
6491 reference "sec:TextClass"
6495 for information on how to do so.
6498 \begin_layout Standard
6500 \begin_inset Flex MenuItem
6503 \begin_layout Plain Layout
6509 can be used with several different document classes, and even if it cannot,
6510 you might find it easiest just to write a module that you can load with
6512 The simplest possible such module would be:
6515 \begin_layout LyX-Code
6518 DeclareLyXModule{My Package}
6521 \begin_layout LyX-Code
6525 \begin_layout LyX-Code
6526 #Support for mypkg.sty.
6529 \begin_layout LyX-Code
6531 \begin_inset Newline newline
6537 \begin_layout LyX-Code
6539 \begin_inset Newline newline
6545 \begin_layout LyX-Code
6547 \begin_inset Newline newline
6553 \begin_inset Newline newline
6559 \begin_layout Standard
6560 A more complex module might modify the behavior of some existing constructs
6561 or define some new ones.
6563 \begin_inset CommandInset ref
6565 reference "sec:TextClass"
6572 \begin_layout Subsection
6574 \begin_inset Flex MenuItem
6577 \begin_layout Plain Layout
6586 \begin_layout Standard
6587 There are two possibilities here.
6588 One is that the class file is itself based upon an existing document class.
6589 For example, many thesis classes are based upon
6590 \begin_inset Flex MenuItem
6593 \begin_layout Plain Layout
6600 To see whether yours is, look for a line like
6603 \begin_layout LyX-Code
6609 \begin_layout Standard
6611 If so, then you may proceed largely as in the previous section, though
6613 \begin_inset Flex Code
6616 \begin_layout Plain Layout
6622 line will be different.
6623 If your new class is
6624 \begin_inset Flex Code
6627 \begin_layout Plain Layout
6633 and it is based upon
6634 \begin_inset Flex Code
6637 \begin_layout Plain Layout
6643 , then the line should read:
6647 \begin_layout Plain Layout
6648 And it will be easiest if you save the file to
6649 \begin_inset Flex Code
6652 \begin_layout Plain Layout
6658 : LyX assumes that the document class has the same name as the layout file.
6667 \begin_layout LyX-Code
6670 DeclareLaTeXClass[thesis,book]{thesis}
6673 \begin_layout Standard
6674 If, on the other hand, the new class is not based upon an existing class,
6675 you will probably have to
6676 \begin_inset Quotes eld
6680 \begin_inset Quotes erd
6684 We strongly suggest copying an existing layout file which uses a similar
6685 LaTeX class and then modifying it, if you can do so.
6686 At least use an existing file as a starting point so you can find out what
6687 items you need to worry about.
6688 Again, the specifics are covered below.
6691 \begin_layout Subsection
6693 \begin_inset CommandInset label
6695 name "sub:Creating-Templates"
6702 \begin_layout Standard
6703 Once you have written a layout file for a new document class, you might
6704 want to consider writing a
6709 A template acts as a kind of tutorial for your layout, showing how it might
6710 be used, though containing dummy content.
6711 You can of course look at the various templates included with LyX for ideas.
6714 \begin_layout Standard
6715 Templates are created just like usual documents: using LyX.
6716 The only difference is that usual documents contain all possible settings,
6717 including the font scheme and the paper size.
6718 Usually a user doesn't want a template to overwrite his preferred settings
6719 for such parameters.
6720 For that reason, the designer of a template should remove the corresponding
6722 \begin_inset Flex Code
6725 \begin_layout Plain Layout
6734 \begin_inset Flex Code
6737 \begin_layout Plain Layout
6745 from the template LyX file.
6746 This can be done with any simple text-editor, for example
6747 \begin_inset Flex Code
6750 \begin_layout Plain Layout
6757 \begin_inset Flex Code
6760 \begin_layout Plain Layout
6770 \begin_layout Standard
6771 Put the edited template files you create in
6772 \begin_inset Flex Code
6775 \begin_layout Plain Layout
6781 , copy the ones you use from the global template directory in
6782 \begin_inset Flex Code
6785 \begin_layout Plain Layout
6791 to the same place, and redefine the template path in the
6792 \begin_inset Flex MenuItem
6795 \begin_layout Plain Layout
6796 Tools\SpecialChar \menuseparator
6797 Preferences\SpecialChar \menuseparator
6806 \begin_layout Standard
6807 Note, by the way, that there is a template which has a particular meaning:
6809 \begin_inset Flex Code
6812 \begin_layout Plain Layout
6819 This template is loaded every time you create a new document with
6820 \begin_inset Flex MenuItem
6823 \begin_layout Plain Layout
6824 File\SpecialChar \menuseparator
6830 in order to provide useful defaults.
6831 To create this template from inside LyX, all you have to do is to open
6832 a document with the correct settings, and use the
6833 \begin_inset Flex MenuItem
6836 \begin_layout Plain Layout
6837 Save as Document Defaults
6845 \begin_layout Subsection
6846 Upgrading old layout files
6849 \begin_layout Standard
6850 The format of layout files changes with each LyX release, so old layout
6851 files need to be converted to the new format.
6852 This process has been automated since LyX 1.4: If LyX reads a layout file
6853 in an older format, it automatically calls the script
6854 \begin_inset Flex Code
6857 \begin_layout Plain Layout
6863 to convert it to a temporary file in current format.
6864 The original file is left untouched.
6865 If you use the layout file often, then, you may want to convert it permanently,
6866 so that LyX does not have to do so itself every time.
6867 To do this, you can call the converter manually:
6870 \begin_layout LyX-Code
6871 mv myclass.layout myclass.old
6874 \begin_layout LyX-Code
6875 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
6878 \begin_layout Standard
6880 \begin_inset Flex Code
6883 \begin_layout Plain Layout
6889 with the name of your LyX system directory, of course.
6892 \begin_layout Standard
6893 Note that manual conversion does not affect included files, so these will
6894 have to be converted separately.
6897 \begin_layout Section
6898 \begin_inset CommandInset label
6900 name "sec:TextClass"
6904 The layout file format
6907 \begin_layout Standard
6908 When it's finally time to get your hands dirty and create or edit your own
6909 layout file, the following sections describe what you're up against.
6910 Our advice is to go slowly, save and test often, listen to soothing music,
6911 and enjoy one or two of your favorite adult beverages; more if you are
6912 getting particularly stuck.
6913 It's really not that hard, except that the multitude of options can become
6914 overwhelming if you try to do too much in one sitting.
6915 Go have another adult beverage, just for good measure.
6918 \begin_layout Standard
6919 Note that all the tags used in layout files are case-insensitive.
6921 \begin_inset Flex Code
6924 \begin_layout Plain Layout
6931 \begin_inset Flex Code
6934 \begin_layout Plain Layout
6941 \begin_inset Flex Code
6944 \begin_layout Plain Layout
6950 are really the same tag.
6951 The possible values are printed in brackets after the feature's name.
6952 The default value if a feature isn't specified inside a text class-description
6954 \begin_inset Flex Code
6957 \begin_layout Plain Layout
6966 If the argument has a data type like
6967 \begin_inset Quotes eld
6971 \begin_inset Quotes erd
6975 \begin_inset Quotes eld
6979 \begin_inset Quotes erd
6982 , the default is shown like this:
6983 \begin_inset Flex Code
6986 \begin_layout Plain Layout
6997 \begin_layout Subsection
6998 The document class declaration
7001 \begin_layout Standard
7002 Lines in a layout file which begin with
7003 \begin_inset Flex Code
7006 \begin_layout Plain Layout
7013 There is one exception to this rule.
7015 \begin_inset Flex Code
7018 \begin_layout Plain Layout
7024 files should begin with a line like:
7027 \begin_layout LyX-Code
7030 #% Do not delete the line below; configure depends on this
7033 \begin_layout LyX-Code
7038 DeclareLaTeXClass{article}
7041 \begin_layout Standard
7042 The second line is used when you (re)configure LyX.
7043 The layout file is read by the LaTeX script
7044 \begin_inset Flex Code
7047 \begin_layout Plain Layout
7053 , in a special mode where
7054 \begin_inset Flex Code
7057 \begin_layout Plain Layout
7064 The first line is just a LaTeX comment, and the second one contains the
7065 declaration of the text class.
7066 If these lines appear in a file named
7067 \begin_inset Flex Code
7070 \begin_layout Plain Layout
7076 , then they define a text class of name
7077 \begin_inset Flex Code
7080 \begin_layout Plain Layout
7086 (the name of the layout file) which uses the LaTeX document class
7087 \begin_inset Flex Code
7090 \begin_layout Plain Layout
7096 (the default is to use the same name as the layout).
7098 \begin_inset Quotes eld
7102 \begin_inset Quotes erd
7105 that appears above is used as a description of the text class in the
7106 \begin_inset Flex MenuItem
7109 \begin_layout Plain Layout
7110 Document\SpecialChar \menuseparator
7119 \begin_layout Standard
7120 Let's assume that you wrote your own text class that uses the
7121 \begin_inset Flex Code
7124 \begin_layout Plain Layout
7130 document class, but where you changed the appearance of the section headings.
7131 If you put it in a file
7132 \begin_inset Flex Code
7135 \begin_layout Plain Layout
7141 , the header of this file should be:
7144 \begin_layout LyX-Code
7147 #% Do not delete the line below; configure depends on this
7150 \begin_layout LyX-Code
7155 DeclareLaTeXClass[article]{article (with my own headings)}
7158 \begin_layout Standard
7159 This declares a text class
7160 \begin_inset Flex Code
7163 \begin_layout Plain Layout
7169 , associated with the LaTeX document class
7170 \begin_inset Flex Code
7173 \begin_layout Plain Layout
7180 \begin_inset Quotes eld
7183 article (with my own headings)
7184 \begin_inset Quotes erd
7188 If your text class depends on several packages, you can declare it as:
7191 \begin_layout LyX-Code
7194 #% Do not delete the line below; configure depends on this
7197 \begin_layout LyX-Code
7202 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7205 \begin_layout Standard
7206 This indicates that your text class uses the
7207 \begin_inset Flex Code
7210 \begin_layout Plain Layout
7217 Finally, it is also possible to declare classes for DocBook code.
7218 Typical declarations will look like:
7221 \begin_layout LyX-Code
7224 #% Do not delete the line below; configure depends on this
7227 \begin_layout LyX-Code
7232 DeclareDocBookClass[article]{SGML (DocBook article)}
7235 \begin_layout Standard
7236 Note that these declarations can also be given an optional parameter declaring
7237 the name of the document class (but not a list).
7240 \begin_layout Standard
7241 So, to be as explicit as possible, the form of the layout declaration is:
7244 \begin_layout LyX-Code
7249 DeclareLaTeXClass[class,package.sty]{layout description}
7252 \begin_layout Standard
7253 The class need only be specified if the name of the LaTeX class file and
7254 the name of the layout file are different or if there are packages to load.
7255 If the name of the class file is not specified, then LyX will simply assume
7256 that it is the same as the name of the layout file.
7259 \begin_layout Standard
7260 When the text class has been modified to your taste, all you have to do
7261 is to copy it either to
7262 \begin_inset Flex Code
7265 \begin_layout Plain Layout
7272 \begin_inset Flex Code
7275 \begin_layout Plain Layout
7282 \begin_inset Flex MenuItem
7285 \begin_layout Plain Layout
7286 Tools\SpecialChar \menuseparator
7292 , exit LyX and restart.
7293 Then your new text class should be available along with the others.
7296 \begin_layout Standard
7297 Once the layout file is installed, you can edit it and see your changes
7298 without having to reconfigure or to restart LyX.
7303 \begin_layout Plain Layout
7304 In versions of LyX prior to 1.6, this was not true.
7305 As a result, editing layout files was very time consuming, since you had
7306 constantly to restart LyX to see changes.
7311 You can force a reload of the current layout by using the LyX function
7313 \begin_inset Flex MenuItem
7316 \begin_layout Plain Layout
7323 There is no default binding for this function—though, of course, you can
7324 bind it to a key yourself.
7325 But you will normally use this function simply by entering it in the mini-buffe
7330 \begin_layout Standard
7336 \begin_inset Flex MenuItem
7339 \begin_layout Plain Layout
7345 is very much an `advanced feature'.
7350 recommended that you save your work before using this function.
7355 recommended that you not attempt to edit layout information while simultaneousl
7356 y working on a document that you care about.
7357 Use a test document.
7358 Syntax errors and the like in your layout file could cause peculiar behavior.
7359 In particular, such errors could cause LyX to regard the current layout
7360 as invalid and to attempt to switch to some other layout.
7364 \begin_layout Plain Layout
7365 Really bad syntax errors may even caused LyX to exit.
7366 This is because certain sorts of errors may make LyX unable to read
7376 The LyX team strives to keep LyX stable in such situations, but safe is
7381 \begin_layout Plain Layout
7382 While we're giving advice: make regular backups.
7383 And be nice to your mother.
7391 \begin_layout Subsection
7392 The Module declaration
7395 \begin_layout Standard
7396 A module must begin with a line like the following:
7399 \begin_layout LyX-Code
7402 DeclareLyXModule[endnotes.sty]{Endnotes}
7405 \begin_layout Standard
7406 The mandatory argument, in curly brackets, is the name of the module, as
7408 \begin_inset Flex MenuItem
7411 \begin_layout Plain Layout
7412 Document\SpecialChar \menuseparator
7419 The argument in square brackets is optional: It declares any LaTeX packages
7420 on which the module depends.
7421 Please note that only packages about which LyX knows should be listed in
7422 the square brackets.
7426 \begin_layout Plain Layout
7427 The list of such packages is documented only in the source code.
7432 LyX will not check for arbitrary packages.
7433 It is also possible to use the form
7434 \begin_inset Flex MenuItem
7437 \begin_layout Plain Layout
7443 as an optional argument, which declares that the module can only be used
7444 when there exists a conversion chain between the formats `
7445 \begin_inset Flex Code
7448 \begin_layout Plain Layout
7455 \begin_inset Flex Code
7458 \begin_layout Plain Layout
7467 \begin_layout Standard
7468 The module declaration should then be followed by lines like the following:
7471 \begin_layout LyX-Code
7475 \begin_layout LyX-Code
7476 #Adds an endnote command, in addition to footnotes.
7480 \begin_layout LyX-Code
7481 #You will need to add
7483 theendnotes in TeX code where you
7486 \begin_layout LyX-Code
7487 #want the endnotes to appear.
7491 \begin_layout LyX-Code
7495 \begin_layout LyX-Code
7496 #Requires: somemodule | othermodule
7499 \begin_layout LyX-Code
7500 #Excludes: badmodule
7503 \begin_layout Standard
7504 The description is used in
7505 \begin_inset Flex MenuItem
7508 \begin_layout Plain Layout
7509 Document\SpecialChar \menuseparator
7515 to provide the user with information about what the module does.
7517 \begin_inset Flex Code
7520 \begin_layout Plain Layout
7526 line is used to identify other modules with which this one must be used;
7528 \begin_inset Flex Code
7531 \begin_layout Plain Layout
7537 line is used to identify modules with which this one may not be used.
7538 Both are optional, and, as shown, multiple modules should be separated
7539 with the pipe symbol: |.
7540 Note that the required modules are treated disjunctively:
7544 of the required modules must be used.
7549 excluded module may be used.
7550 Note that modules are identified here by their
7555 \begin_inset Flex Code
7558 \begin_layout Plain Layout
7566 \begin_inset Flex Code
7569 \begin_layout Plain Layout
7576 \begin_inset Flex Code
7579 \begin_layout Plain Layout
7588 \begin_layout Subsection
7592 \begin_layout Standard
7593 The first non-comment line of any layout file, included file, or module
7598 contain the file format number:
7601 \begin_layout Description
7602 \begin_inset Flex Code
7605 \begin_layout Plain Layout
7612 \begin_inset Flex Code
7615 \begin_layout Plain Layout
7621 ] The format of the layout file.
7624 \begin_layout Standard
7625 This tag was introduced with LyX 1.4.0.
7626 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7627 and are considered to be of format 1.
7628 The format for the present version of LyX is format 21.
7629 But each version of LyX is capable of reading earlier versions' layout
7630 files, just as they are capable of reading files produced by earlier versions
7632 There is, however, no provision for converting to earlier formats.
7633 So LyX 1.6.x will not read layout files in format 21 but only files in format
7637 \begin_layout Subsection
7638 \begin_inset CommandInset label
7640 name "sub:General-text-class"
7644 General text class parameters
7647 \begin_layout Standard
7648 These are general parameters that govern the behavior of an entire document
7654 mean that they must appear in
7655 \begin_inset Flex Code
7658 \begin_layout Plain Layout
7664 files rather than in modules.
7665 A module can contain any layout tag.)
7668 \begin_layout Description
7669 \begin_inset Flex Code
7672 \begin_layout Plain Layout
7678 Adds information that will be output in the
7679 \begin_inset Flex Code
7682 \begin_layout Plain Layout
7688 block when this document class is output to XHTML.
7689 Typically, this would be used to output CSS style information, but it can
7690 be used for anything that can appear in
7691 \begin_inset Flex Code
7694 \begin_layout Plain Layout
7702 \begin_inset Quotes eld
7706 \begin_inset Flex Code
7709 \begin_layout Plain Layout
7716 \begin_inset Quotes erd
7722 \begin_layout Description
7723 \begin_inset Flex Code
7726 \begin_layout Plain Layout
7732 Adds information to the document preamble.
7734 \begin_inset Quotes eld
7738 \begin_inset Flex Code
7741 \begin_layout Plain Layout
7748 \begin_inset Quotes erd
7754 \begin_layout Description
7755 \begin_inset Flex Code
7758 \begin_layout Plain Layout
7764 Defines formats for use in the display of bibliographic information.
7766 \begin_inset CommandInset ref
7768 reference "sub:Citation-format-description"
7774 \begin_inset Quotes eld
7778 \begin_inset Flex Code
7781 \begin_layout Plain Layout
7788 \begin_inset Quotes erd
7794 \begin_layout Description
7795 \begin_inset Flex Code
7798 \begin_layout Plain Layout
7804 Describes various global options supported by the document class.
7806 \begin_inset space ~
7810 \begin_inset CommandInset ref
7812 reference "sub:ClassOptions"
7818 \begin_inset Quotes eld
7822 \begin_inset Flex Code
7825 \begin_layout Plain Layout
7832 \begin_inset Quotes erd
7838 \begin_layout Description
7839 \begin_inset Flex Code
7842 \begin_layout Plain Layout
7849 \begin_inset Flex Code
7852 \begin_layout Plain Layout
7861 \begin_inset Flex Code
7864 \begin_layout Plain Layout
7870 ] Whether the class should
7874 to having one or two columns.
7875 Can be changed in the
7876 \begin_inset Flex MenuItem
7879 \begin_layout Plain Layout
7880 Document\SpecialChar \menuseparator
7889 \begin_layout Description
7890 \begin_inset Flex Code
7893 \begin_layout Plain Layout
7900 \begin_inset Flex Code
7903 \begin_layout Plain Layout
7909 ] This sequence defines the properties for a counter.
7910 If the counter does not yet exist, it is created; if it does exist, it
7913 \begin_inset Quotes eld
7917 \begin_inset Flex Code
7920 \begin_layout Plain Layout
7927 \begin_inset Quotes erd
7931 \begin_inset Newline newline
7935 \begin_inset space ~
7939 \begin_inset CommandInset ref
7941 reference "sub:Counters"
7945 for details on counters.
7948 \begin_layout Description
7949 \begin_inset Flex Code
7952 \begin_layout Plain Layout
7958 Sets the default font used to display the document.
7960 \begin_inset space ~
7964 \begin_inset CommandInset ref
7966 reference "sub:Font-description"
7970 for how to declare fonts.
7972 \begin_inset Quotes eld
7976 \begin_inset Flex Code
7979 \begin_layout Plain Layout
7986 \begin_inset Quotes erd
7992 \begin_layout Description
7993 \begin_inset Flex Code
7996 \begin_layout Plain Layout
8003 \begin_inset Flex Code
8006 \begin_layout Plain Layout
8012 Specifies a module to be included by default with this document class.
8013 The module should be specified by filename without the
8014 \begin_inset Flex Code
8017 \begin_layout Plain Layout
8024 The user can still remove the module, but it will be active at the outset.
8025 (This applies only when new files are created, or when this class is chosen
8026 for an existing document.)
8029 \begin_layout Description
8030 \begin_inset Flex Code
8033 \begin_layout Plain Layout
8040 \begin_inset Flex Code
8043 \begin_layout Plain Layout
8049 ] This is the style that will be assigned to new paragraphs, usually
8050 \begin_inset Flex MenuItem
8053 \begin_layout Plain Layout
8060 This will default to the first defined style if not given, but you are
8061 encouraged to use this directive.
8064 \begin_layout Description
8065 \begin_inset Flex Code
8068 \begin_layout Plain Layout
8075 \begin_inset Flex Code
8078 \begin_layout Plain Layout
8084 ] This tag indicates that the module in question—which should be specified
8085 by filename without the
8086 \begin_inset Flex Code
8089 \begin_layout Plain Layout
8095 extension—cannot be used with this document class.
8096 This might be used in a journal-specific layout file to prevent, say, the
8098 \begin_inset Flex Code
8101 \begin_layout Plain Layout
8107 module that numbers theorems by section.
8112 be used in a module.
8113 Modules have their own way of excluding other modules (see
8114 \begin_inset CommandInset ref
8116 reference "sub:Layout-modules"
8123 \begin_layout Description
8124 \begin_inset Flex Code
8127 \begin_layout Plain Layout
8133 Defines a new float.
8135 \begin_inset space ~
8139 \begin_inset CommandInset ref
8141 reference "sub:Floats"
8147 \begin_inset Quotes eld
8151 \begin_inset Flex Code
8154 \begin_layout Plain Layout
8161 \begin_inset Quotes erd
8167 \begin_layout Description
8168 \begin_inset Flex Code
8171 \begin_layout Plain Layout
8177 Sets the information that will be output in the
8178 \begin_inset Flex Code
8181 \begin_layout Plain Layout
8187 block when this document class is output to XHTML.
8188 Note that this will completely override any prior
8189 \begin_inset Flex Code
8192 \begin_layout Plain Layout
8199 \begin_inset Flex Code
8202 \begin_layout Plain Layout
8210 \begin_inset Flex Code
8213 \begin_layout Plain Layout
8219 if you just want to add material to the preamble.) Must end with
8220 \begin_inset Quotes eld
8224 \begin_inset Flex Code
8227 \begin_layout Plain Layout
8234 \begin_inset Quotes erd
8240 \begin_layout Description
8241 \begin_inset Flex Code
8244 \begin_layout Plain Layout
8251 \begin_inset Flex Code
8254 \begin_layout Plain Layout
8260 ] The layout to use for the table of contents, bibliography, and so forth,
8261 when the document is output to HTML.
8262 For articles, this should normally be Section; for books, Chapter.
8263 If it is not given, then LyX will attempt to figure out which layout to
8267 \begin_layout Description
8268 \begin_inset Flex Code
8271 \begin_layout Plain Layout
8278 \begin_inset Flex Code
8281 \begin_layout Plain Layout
8287 ] Modifies the properties of the given counter.
8288 If the counter does not exist, the section is ignored.
8290 \begin_inset Quotes eld
8294 \begin_inset Flex Code
8297 \begin_layout Plain Layout
8304 \begin_inset Quotes erd
8308 \begin_inset Newline newline
8312 \begin_inset space ~
8316 \begin_inset CommandInset ref
8318 reference "sub:Counters"
8322 for details on counters.
8325 \begin_layout Description
8326 \begin_inset Flex Code
8329 \begin_layout Plain Layout
8336 \begin_inset Flex Code
8339 \begin_layout Plain Layout
8345 ] Modifies the properties of the given paragraph style.
8346 If the style does not exist, the section is ignored.
8348 \begin_inset Quotes eld
8352 \begin_inset Flex Code
8355 \begin_layout Plain Layout
8362 \begin_inset Quotes erd
8368 \begin_layout Description
8369 \begin_inset Flex Code
8372 \begin_layout Plain Layout
8378 As its name implies, this command allows you to include another layout
8379 definition file within yours to avoid duplicating commands.
8380 Common examples are the standard layout files, for example,
8381 \begin_inset Flex Code
8384 \begin_layout Plain Layout
8390 , which contains most of the basic layouts.
8393 \begin_layout Description
8394 \begin_inset Flex Code
8397 \begin_layout Plain Layout
8403 This section (re-)defines the layout of an inset.
8404 It can be applied to an existing inset or to a new, user-defined inset,
8405 e.g., a new character style.
8407 \begin_inset Quotes eld
8411 \begin_inset Flex Code
8414 \begin_layout Plain Layout
8421 \begin_inset Quotes erd
8425 \begin_inset Newline newline
8429 \begin_inset space ~
8433 \begin_inset CommandInset ref
8435 reference "sub:Flex-insets-and"
8439 for more information.
8443 \begin_layout Description
8444 \begin_inset Flex Code
8447 \begin_layout Plain Layout
8454 \begin_inset Flex Code
8457 \begin_layout Plain Layout
8463 ] A string that indicates the width of the left margin on the screen, for
8465 \begin_inset Quotes eld
8469 \begin_inset Quotes erd
8473 (Note that this is not a `length', like
8474 \begin_inset Quotes eld
8478 \begin_inset Quotes erd
8484 \begin_layout Description
8485 \begin_inset Flex Code
8488 \begin_layout Plain Layout
8494 This command deletes an existing float.
8495 This is particularly useful when you want to suppress a float that has
8496 been defined in an input file.
8499 \begin_layout Description
8500 \begin_inset Flex Code
8503 \begin_layout Plain Layout
8509 This command deletes an existing style.
8510 This is particularly useful when you want to suppress a style that has
8511 be defined in an input file.
8514 \begin_layout Description
8515 \begin_inset Flex Code
8518 \begin_layout Plain Layout
8524 A string indicating the file format (as defined in the Preferences dialog)
8525 produced by this class.
8526 It is mainly useful when
8527 \begin_inset Flex Code
8530 \begin_layout Plain Layout
8536 is `literate' and one wants to define a new type of literate document.
8537 This string is reset to `docbook', `latex', or `literate' when the correspondin
8539 \begin_inset Flex Code
8542 \begin_layout Plain Layout
8548 parameter is encountered.
8551 \begin_layout Description
8552 \begin_inset Flex Code
8555 \begin_layout Plain Layout
8561 A string indicating what sort of output documents using this class will
8563 At present, the options are: `docbook', `latex', and `literate'.
8566 \begin_layout Description
8567 \begin_inset Flex Code
8570 \begin_layout Plain Layout
8577 \begin_inset Flex Code
8580 \begin_layout Plain Layout
8589 \begin_inset Flex Code
8592 \begin_layout Plain Layout
8599 \begin_inset Flex Code
8602 \begin_layout Plain Layout
8608 ] The default pagestyle.
8609 Can be changed in the
8610 \begin_inset Flex MenuItem
8613 \begin_layout Plain Layout
8614 Document\SpecialChar \menuseparator
8623 \begin_layout Description
8624 \begin_inset Flex Code
8627 \begin_layout Plain Layout
8633 Sets the preamble for the LaTeX document.
8634 Note that this will completely override any prior
8635 \begin_inset Flex Code
8638 \begin_layout Plain Layout
8645 \begin_inset Flex Code
8648 \begin_layout Plain Layout
8656 \begin_inset Flex Code
8659 \begin_layout Plain Layout
8665 if you just want to add material to the preamble.) Must end with
8666 \begin_inset Quotes eld
8670 \begin_inset Flex Code
8673 \begin_layout Plain Layout
8680 \begin_inset Quotes erd
8686 \begin_layout Description
8687 \begin_inset Flex Code
8690 \begin_layout Plain Layout
8697 \begin_inset Flex Code
8700 \begin_layout Plain Layout
8707 \begin_inset Flex Code
8710 \begin_layout Plain Layout
8719 \begin_inset Flex Code
8722 \begin_layout Plain Layout
8728 ] Whether the class already provides the feature
8729 \begin_inset Flex Code
8732 \begin_layout Plain Layout
8739 A feature is in general the name of a package (
8740 \begin_inset Flex Code
8743 \begin_layout Plain Layout
8750 \begin_inset Flex Code
8753 \begin_layout Plain Layout
8759 , \SpecialChar \ldots{}
8761 \begin_inset Flex Code
8764 \begin_layout Plain Layout
8771 \begin_inset Flex Code
8774 \begin_layout Plain Layout
8780 ,\SpecialChar \ldots{}
8781 ); the complete list of supported features is unfortunately not documented
8782 outside the LyX source code—but see
8783 \begin_inset Flex Code
8786 \begin_layout Plain Layout
8792 if you're interested.
8794 \begin_inset Flex MenuItem
8797 \begin_layout Plain Layout
8798 Help\SpecialChar \menuseparator
8804 also gives an overview of the supported packages.
8807 \begin_layout Description
8808 \begin_inset Flex Code
8811 \begin_layout Plain Layout
8818 \begin_inset Flex Code
8821 \begin_layout Plain Layout
8827 ] Indicates that this layout provides the functionality of the module mentioned,
8828 which should be specified by the filename without the
8829 \begin_inset Flex Code
8832 \begin_layout Plain Layout
8839 This will typically be used if the layout includes the module directly,
8840 rather than using the
8841 \begin_inset Flex Code
8844 \begin_layout Plain Layout
8850 tag to indicate that it ought to be used.
8851 It could also be used in a module that provided an alternate implementation
8852 of the same functionality.
8855 \begin_layout Description
8856 \begin_inset Flex Code
8859 \begin_layout Plain Layout
8866 \begin_inset Flex Code
8869 \begin_layout Plain Layout
8875 ] Whether the class requires the feature
8876 \begin_inset Flex Code
8879 \begin_layout Plain Layout
8886 Multiple features must be separated by commas.
8887 Note that you can only request supported features.
8889 \begin_inset Flex Code
8892 \begin_layout Plain Layout
8898 for a list of these.)
8901 \begin_layout Description
8902 \begin_inset Flex Code
8905 \begin_layout Plain Layout
8911 A string that indicates the width of the right margin on the screen, for
8913 \begin_inset Quotes eld
8917 \begin_inset Quotes erd
8923 \begin_layout Description
8924 \begin_inset Flex Code
8927 \begin_layout Plain Layout
8933 Sets which divisions get numbered.
8935 \begin_inset Flex Code
8938 \begin_layout Plain Layout
8947 \begin_layout Description
8948 \begin_inset Flex Code
8951 \begin_layout Plain Layout
8958 \begin_inset Flex Code
8961 \begin_layout Plain Layout
8970 \begin_inset Flex Code
8973 \begin_layout Plain Layout
8979 ] Whether the class-default should be printing on one or both sides of the
8981 Can be changed in the
8982 \begin_inset Flex MenuItem
8985 \begin_layout Plain Layout
8986 Document\SpecialChar \menuseparator
8995 \begin_layout Description
8996 \begin_inset Flex Code
8999 \begin_layout Plain Layout
9005 This sequence defines a paragraph style.
9006 If the style does not yet exist, it is created; if it does exist, its parameter
9009 \begin_inset Quotes eld
9013 \begin_inset Flex Code
9016 \begin_layout Plain Layout
9023 \begin_inset Quotes erd
9027 \begin_inset Newline newline
9031 \begin_inset space ~
9035 \begin_inset CommandInset ref
9037 reference "sub:Paragraph-Styles"
9041 for details on paragraph styles.
9044 \begin_layout Description
9045 \begin_inset Flex Code
9048 \begin_layout Plain Layout
9055 \begin_inset Flex Code
9058 \begin_layout Plain Layout
9064 ] The name of the command or environment to be used with
9065 \begin_inset Flex Code
9068 \begin_layout Plain Layout
9077 \begin_layout Description
9078 \begin_inset Flex Code
9081 \begin_layout Plain Layout
9088 \begin_inset Flex Code
9091 \begin_layout Plain Layout
9100 \begin_inset Flex Code
9103 \begin_layout Plain Layout
9109 ] Indicates what kind of markup is used to define the title of a document.
9111 \begin_inset Flex Code
9114 \begin_layout Plain Layout
9120 means that the macro with name
9121 \begin_inset Flex Code
9124 \begin_layout Plain Layout
9130 will be inserted after the last layout which has
9131 \begin_inset Quotes eld
9135 \begin_inset Flex Code
9138 \begin_layout Plain Layout
9145 \begin_inset Quotes erd
9150 \begin_inset Flex Code
9153 \begin_layout Plain Layout
9159 corresponds to the case where the block of paragraphs which have
9160 \begin_inset Quotes eld
9164 \begin_inset Flex Code
9167 \begin_layout Plain Layout
9174 \begin_inset Quotes erd
9177 should be enclosed into the
9178 \begin_inset Flex Code
9181 \begin_layout Plain Layout
9190 \begin_layout Description
9191 \begin_inset Flex Code
9194 \begin_layout Plain Layout
9200 Sets which divisions are included in the table of contents.
9202 \begin_inset Flex Code
9205 \begin_layout Plain Layout
9214 \begin_layout Subsection
9215 \begin_inset Flex Code
9218 \begin_layout Plain Layout
9225 \begin_inset CommandInset label
9227 name "sub:ClassOptions"
9234 \begin_layout Standard
9236 \begin_inset Flex Code
9239 \begin_layout Plain Layout
9245 section can contain the following entries:
9248 \begin_layout Description
9249 \begin_inset Flex Code
9252 \begin_layout Plain Layout
9259 \begin_inset Flex Code
9262 \begin_layout Plain Layout
9268 ] The list of available font sizes for the document's main font, separated
9270 \begin_inset Quotes eld
9274 \begin_inset Flex Code
9277 \begin_layout Plain Layout
9284 \begin_inset Quotes erd
9290 \begin_layout Description
9291 \begin_inset Flex Code
9294 \begin_layout Plain Layout
9300 Used to set the DTD line with XML-based output classes.
9302 \begin_inset space \thinspace{}
9306 \begin_inset Quotes eld
9309 -//OASIS//DTD DocBook V4.2//EN
9310 \begin_inset Quotes erd
9316 \begin_layout Description
9317 \begin_inset Flex Code
9320 \begin_layout Plain Layout
9327 \begin_inset Flex Code
9330 \begin_layout Plain Layout
9331 string="empty|plain|headings|fancy"
9336 ] The list of available page styles, separated by
9337 \begin_inset Quotes eld
9341 \begin_inset Flex Code
9344 \begin_layout Plain Layout
9351 \begin_inset Quotes erd
9357 \begin_layout Description
9358 \begin_inset Flex Code
9361 \begin_layout Plain Layout
9368 \begin_inset Flex Code
9371 \begin_layout Plain Layout
9377 ] Some document class options, separated by a comma, that will be added
9378 to the optional part of the
9379 \begin_inset Flex Code
9382 \begin_layout Plain Layout
9393 \begin_layout Standard
9395 \begin_inset Flex Code
9398 \begin_layout Plain Layout
9404 section must end with
9405 \begin_inset Quotes eld
9409 \begin_inset Flex Code
9412 \begin_layout Plain Layout
9419 \begin_inset Quotes erd
9425 \begin_layout Subsection
9427 \begin_inset CommandInset label
9429 name "sub:Paragraph-Styles"
9436 \begin_layout Standard
9437 A paragraph style description looks like this:
9441 \begin_layout Plain Layout
9442 Note that this will either define a new layout or modify an existing one.
9450 \begin_layout LyX-Code
9457 \begin_layout LyX-Code
9461 \begin_layout LyX-Code
9465 \begin_layout Standard
9466 where the following commands are allowed:
9469 \begin_layout Description
9470 \begin_inset Flex Code
9473 \begin_layout Plain Layout
9480 \begin_inset Flex Code
9483 \begin_layout Plain Layout
9488 , left, right, center
9493 ] Paragraph alignment.
9496 \begin_layout Description
9497 \begin_inset Flex Code
9500 \begin_layout Plain Layout
9507 \begin_inset Flex Code
9510 \begin_layout Plain Layout
9515 , left, right, center
9520 ] A comma separated list of permitted alignments.
9521 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9523 For example a right-aligned or centered enumeration isn't possible.)
9526 \begin_layout Description
9527 \begin_inset Flex Code
9530 \begin_layout Plain Layout
9536 Note that this will completely override any prior
9537 \begin_inset Flex Code
9540 \begin_layout Plain Layout
9546 declaration for this style.
9548 \begin_inset Quotes eld
9552 \begin_inset Flex Code
9555 \begin_layout Plain Layout
9562 \begin_inset Quotes erd
9567 \begin_inset CommandInset ref
9569 reference "sub:I18n"
9573 for details on its use.
9576 \begin_layout Description
9577 \begin_inset Flex Code
9580 \begin_layout Plain Layout
9587 \begin_inset Flex Code
9590 \begin_layout Plain Layout
9600 \begin_layout Plain Layout
9601 Note that a `float' here is a real number, such as: 1.5.
9606 The vertical space with which the last of a chain of paragraphs with this
9607 layout is separated from the following paragraph.
9608 If the next paragraph has another layout, the separations are not simply
9609 added, but the maximum is taken.
9612 \begin_layout Description
9613 \begin_inset Flex Code
9616 \begin_layout Plain Layout
9623 \begin_inset Flex Code
9626 \begin_layout Plain Layout
9632 The category for this style.
9633 This is used to group related styles in the Layout combobox on the toolbar.
9634 Any string can be used, but you may want to use existing categories with
9639 \begin_layout Description
9640 \begin_inset Flex Code
9643 \begin_layout Plain Layout
9649 Depth of XML command.
9650 Used only with XML-type formats.
9653 \begin_layout Description
9654 \begin_inset Flex Code
9657 \begin_layout Plain Layout
9664 \begin_inset CommandInset label
9666 name "des:CopyStyle"
9671 \begin_inset Flex Code
9674 \begin_layout Plain Layout
9680 Copies all the features of an existing style into the current one.
9684 \begin_layout Description
9685 \begin_inset Flex Code
9688 \begin_layout Plain Layout
9694 The name of a style whose preamble should be output
9699 This allows to ensure some ordering of the preamble snippets when macros
9700 definitions depend on one another.
9704 \begin_layout Plain Layout
9705 Note that, besides that functionality, there is no way to ensure any ordering
9707 The ordering that you see in a given version of LyX may change without
9708 warning in later versions.
9716 \begin_layout Description
9717 \begin_inset Flex Code
9720 \begin_layout Plain Layout
9727 \begin_inset Flex Code
9730 \begin_layout Plain Layout
9735 , Box, Filled_Box, Static
9740 ] The type of label that stands at the end of the paragraph (or sequence
9742 \begin_inset Flex Code
9745 \begin_layout Plain Layout
9752 \begin_inset Flex Code
9755 \begin_layout Plain Layout
9762 \begin_inset Flex Code
9765 \begin_layout Plain Layout
9772 \begin_inset Flex Code
9775 \begin_layout Plain Layout
9783 \begin_inset Flex Code
9786 \begin_layout Plain Layout
9793 \begin_inset Quotes eld
9797 \begin_inset Quotes erd
9801 \begin_inset Flex Code
9804 \begin_layout Plain Layout
9811 \begin_inset Flex Code
9814 \begin_layout Plain Layout
9815 \begin_inset space ~
9824 \begin_inset space ~
9827 black) square suitable for end of proof markers,
9828 \begin_inset Flex Code
9831 \begin_layout Plain Layout
9837 is an explicit text string.
9840 \begin_layout Description
9841 \begin_inset Flex Code
9844 \begin_layout Plain Layout
9851 \begin_inset Flex Code
9854 \begin_layout Plain Layout
9860 ] The string used for a label with a
9861 \begin_inset Flex Code
9864 \begin_layout Plain Layout
9871 \begin_inset Flex Code
9874 \begin_layout Plain Layout
9884 \begin_layout Description
9885 \begin_inset Flex Code
9888 \begin_layout Plain Layout
9895 \begin_inset Flex Code
9898 \begin_layout Plain Layout
9909 \begin_inset Flex Code
9912 \begin_layout Plain Layout
9921 \begin_layout Description
9922 \begin_inset Flex Code
9925 \begin_layout Plain Layout
9932 \begin_inset Flex Code
9935 \begin_layout Plain Layout
9945 ] With this parameter the
9946 \begin_inset Flex MenuItem
9949 \begin_layout Plain Layout
9956 \begin_inset Quotes eld
9959 Vertical space above
9960 \begin_inset Quotes erd
9964 \begin_inset Flex MenuItem
9967 \begin_layout Plain Layout
9968 Edit\SpecialChar \menuseparator
9970 \begin_inset space ~
9978 dialog can be set when initializing a paragraph with this style.
9982 \begin_layout Plain Layout
9985 Note from Jean-Marc:
9987 I'm not sure that this setting has much use, and it should probably be
9988 removed in later versions.
9996 \begin_layout Description
9997 \begin_inset Flex Code
10000 \begin_layout Plain Layout
10006 The font used for both the text body
10012 \begin_inset space ~
10016 \begin_inset CommandInset ref
10018 reference "sub:Font-description"
10023 Note that defining this font automatically defines the
10024 \begin_inset Flex Code
10027 \begin_layout Plain Layout
10034 So you should define this one first if you also want to define
10035 \begin_inset Flex Code
10038 \begin_layout Plain Layout
10047 \begin_layout Description
10048 \begin_inset Flex Code
10051 \begin_layout Plain Layout
10058 \begin_inset CommandInset label
10060 name "des:FreeSpacing"
10065 \begin_inset Flex Code
10068 \begin_layout Plain Layout
10077 \begin_inset Flex Code
10080 \begin_layout Plain Layout
10086 ] Usually LyX doesn't allow you to insert more than one space between words,
10087 since a space is considered as the separation between two words, not a
10088 character or symbol of its own.
10089 This is a very fine thing but sometimes annoying, for example, when typing
10090 program code or plain LaTeX code.
10092 \begin_inset Flex Code
10095 \begin_layout Plain Layout
10102 Note that LyX will create protected blanks for the additional blanks when
10103 in another mode than LaTeX-mode.
10106 \begin_layout Description
10107 \begin_inset Flex Code
10110 \begin_layout Plain Layout
10116 These tags are used with XHTML output.
10118 \begin_inset CommandInset ref
10120 reference "sub:Paragraph-Style-XHTML"
10127 \begin_layout Description
10128 \begin_inset Flex Code
10131 \begin_layout Plain Layout
10137 [[FIXME]] (Used only with XML-type formats.)
10140 \begin_layout Description
10141 \begin_inset Flex Code
10144 \begin_layout Plain Layout
10151 \begin_inset Flex Code
10154 \begin_layout Plain Layout
10160 If 1, marks the layout as to be included in the document preamble rather
10161 than in the document body.
10162 This is useful for document classes that want such information as the title
10163 and author to appear in the preamble.
10164 Note that this works only for layouts for which the
10165 \begin_inset Flex Code
10168 \begin_layout Plain Layout
10175 \begin_inset Flex Code
10178 \begin_layout Plain Layout
10187 \begin_layout Description
10188 \begin_inset Flex Code
10191 \begin_layout Plain Layout
10198 \begin_inset Flex Code
10201 \begin_layout Plain Layout
10207 If 1, marks the layout as being part of a title block (see also the
10208 \begin_inset Flex Code
10211 \begin_layout Plain Layout
10218 \begin_inset Flex Code
10221 \begin_layout Plain Layout
10230 \begin_layout Description
10231 \begin_inset Flex Code
10234 \begin_layout Plain Layout
10241 \begin_inset Flex Code
10244 \begin_layout Plain Layout
10250 ] This provides extra space between paragraphs that have the same layout.
10251 If you put other layouts into an environment, each is separated with the
10253 \begin_inset Flex Code
10256 \begin_layout Plain Layout
10263 But the whole items of the environment are additionally separated with
10265 \begin_inset Flex Code
10268 \begin_layout Plain Layout
10275 Note that this is a
10280 \begin_layout Description
10281 \begin_inset Flex Code
10284 \begin_layout Plain Layout
10290 [[FIXME]] (Used only with XML-type formats.)
10293 \begin_layout Description
10294 \begin_inset Flex Code
10297 \begin_layout Plain Layout
10304 \begin_inset CommandInset label
10306 name "des:KeepEmpty"
10311 \begin_inset Flex Code
10314 \begin_layout Plain Layout
10323 \begin_inset Flex Code
10326 \begin_layout Plain Layout
10332 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10333 lead to empty LaTeX output.
10334 There are some cases where this could be desirable however: in a letter
10335 template, the required fields can be provided as empty fields, so that
10336 people do not forget them; in some special classes, a layout can be used
10337 as some kind of break, which does not contain actual text.
10340 \begin_layout Description
10341 \begin_inset Flex Code
10344 \begin_layout Plain Layout
10350 [float=0] The vertical space between the label and the text body.
10351 Only used for labels that are above the text body (
10352 \begin_inset Flex Code
10355 \begin_layout Plain Layout
10362 \begin_inset Flex Code
10365 \begin_layout Plain Layout
10366 Centered_Top_Environment
10374 \begin_layout Description
10375 \begin_inset Flex Code
10378 \begin_layout Plain Layout
10385 \begin_inset Flex Code
10388 \begin_layout Plain Layout
10395 \begin_inset Newline newline
10398 The name of the counter for automatic numbering.
10400 \begin_inset Newline newline
10408 \begin_inset Flex Code
10411 \begin_layout Plain Layout
10418 \begin_inset Flex Code
10421 \begin_layout Plain Layout
10428 In that case, the counter will be stepped each time the layout appears.
10430 \begin_inset Newline newline
10438 \begin_inset Flex Code
10441 \begin_layout Plain Layout
10448 \begin_inset Flex Code
10451 \begin_layout Plain Layout
10457 , though this case is a bit complicated.
10458 Suppose you declare
10459 \begin_inset Quotes eld
10463 \begin_inset Flex Code
10466 \begin_layout Plain Layout
10467 LabelCounter myenum
10473 \begin_inset Quotes erd
10477 Then the actual counters used are
10478 \begin_inset Flex Code
10481 \begin_layout Plain Layout
10488 \begin_inset Flex Code
10491 \begin_layout Plain Layout
10498 \begin_inset Flex Code
10501 \begin_layout Plain Layout
10508 \begin_inset Flex Code
10511 \begin_layout Plain Layout
10517 , much as in LaTeX.
10518 These counters must all be declared separately.
10519 \begin_inset Newline newline
10523 \begin_inset CommandInset ref
10525 reference "sub:Counters"
10529 for details on counters.
10532 \begin_layout Description
10533 \begin_inset Flex Code
10536 \begin_layout Plain Layout
10542 The font used for the label.
10544 \begin_inset space ~
10548 \begin_inset CommandInset ref
10550 reference "sub:Font-description"
10557 \begin_layout Description
10558 \begin_inset Flex Code
10561 \begin_layout Plain Layout
10567 Text that indicates how far a label should be indented.
10570 \begin_layout Description
10571 \begin_inset Flex Code
10574 \begin_layout Plain Layout
10581 \begin_inset Flex Code
10584 \begin_layout Plain Layout
10590 ] The horizontal space between the label and the text body.
10591 Only used for labels that are not above the text body.
10594 \begin_layout Description
10595 \begin_inset Flex Code
10598 \begin_layout Plain Layout
10605 \begin_inset Flex Code
10608 \begin_layout Plain Layout
10614 ] The string used for a label with a
10615 \begin_inset Flex Code
10618 \begin_layout Plain Layout
10626 \begin_inset Flex Code
10629 \begin_layout Plain Layout
10635 is set, this string can be contain the special formatting commands described
10637 \begin_inset CommandInset ref
10639 reference "sub:Counters"
10647 \begin_layout Plain Layout
10648 For the sake of backwards compatibility, the string
10649 \begin_inset Flex Code
10652 \begin_layout Plain Layout
10662 will be replaced by the expanded
10663 \begin_inset Flex Code
10666 \begin_layout Plain Layout
10673 \begin_inset Flex Code
10676 \begin_layout Plain Layout
10685 This feature is now obsolete and should be replaced by the mechanisms of
10687 \begin_inset CommandInset ref
10689 reference "sub:Counters"
10701 \begin_layout Description
10702 \begin_inset Flex Code
10705 \begin_layout Plain Layout
10706 LabelStringAppendix
10712 \begin_inset Flex Code
10715 \begin_layout Plain Layout
10721 ] This is used inside the appendix instead of
10722 \begin_inset Flex Code
10725 \begin_layout Plain Layout
10733 \begin_inset Flex Code
10736 \begin_layout Plain Layout
10743 \begin_inset Flex Code
10746 \begin_layout Plain Layout
10747 LabelStringAppendix
10755 \begin_layout Description
10756 \begin_inset Flex Code
10759 \begin_layout Plain Layout
10765 [FIXME] (Used only with XML-type formats.)
10768 \begin_layout Description
10769 \begin_inset Flex Code
10772 \begin_layout Plain Layout
10779 \begin_inset Flex Code
10782 \begin_layout Plain Layout
10787 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10788 Enumerate, Itemize, Bibliography
10797 \begin_layout Itemize
10798 \begin_inset Flex Code
10801 \begin_layout Plain Layout
10807 means the label is the very first word (up to the first real blank).
10808 Use protected spaces (like
10809 \begin_inset space ~
10812 that one) if you want more than one word as the label.
10816 \begin_layout Itemize
10817 \begin_inset Flex Code
10820 \begin_layout Plain Layout
10826 means the label is simply whatever
10827 \begin_inset Flex Code
10830 \begin_layout Plain Layout
10837 Note that this really is `static'.
10840 \begin_layout Itemize
10841 \begin_inset Flex Code
10844 \begin_layout Plain Layout
10851 \begin_inset Flex Code
10854 \begin_layout Plain Layout
10855 Centered_Top_Environment
10860 are special cases of
10861 \begin_inset Flex Code
10864 \begin_layout Plain Layout
10871 The label will be printed above the paragraph, but only at the top of an
10872 environment or the top of a chain of paragraphs with this layout.
10873 This might be used with the
10874 \begin_inset Flex MenuItem
10877 \begin_layout Plain Layout
10883 layout, for example.
10886 \begin_layout Itemize
10887 \begin_inset Flex Code
10890 \begin_layout Plain Layout
10896 is a special case for the caption-labels
10897 \begin_inset Quotes eld
10901 \begin_inset Quotes erd
10905 \begin_inset Quotes eld
10909 \begin_inset Quotes erd
10914 \begin_inset Flex Code
10917 \begin_layout Plain Layout
10923 means the (hardcoded) label string depends on the kind of float: It is
10924 hardcoded to be `FloatType N', where N is the value of the counter associated
10928 \begin_layout Itemize
10930 \begin_inset Flex Code
10933 \begin_layout Plain Layout
10939 label type defines automatically numbered labels.
10941 \begin_inset Flex Code
10944 \begin_layout Plain Layout
10950 will be expanded to resolve any counter references it contains: For example,
10952 \begin_inset Quotes eld
10956 \begin_inset Flex Code
10959 \begin_layout Plain Layout
10970 \begin_inset Quotes erd
10975 \begin_inset CommandInset ref
10977 reference "sub:Counters"
10981 for more information on counters.
10984 \begin_layout Itemize
10985 \begin_inset Flex Code
10988 \begin_layout Plain Layout
10994 produces the usual sort of enumeration labels.
10995 At present, it is hardcoded to use Arabic numerals, lowercase letters,
10996 small Roman numerals, and uppercase letters for the four possible depths.
10999 \begin_layout Itemize
11000 \begin_inset Flex Code
11003 \begin_layout Plain Layout
11009 produces various bullets at the different levels.
11010 It is also hardcoded.
11013 \begin_layout Itemize
11014 \begin_inset Flex Code
11017 \begin_layout Plain Layout
11023 is used internally by LyX and should be used only with
11024 \begin_inset Flex Code
11027 \begin_layout Plain Layout
11028 LatexType BibEnvironment
11037 \begin_layout Description
11038 \begin_inset Flex Code
11041 \begin_layout Plain Layout
11047 Note that this will completely override any prior
11048 \begin_inset Flex Code
11051 \begin_layout Plain Layout
11057 declaration for this style.
11059 \begin_inset Quotes eld
11063 \begin_inset Flex Code
11066 \begin_layout Plain Layout
11073 \begin_inset Quotes erd
11078 \begin_inset CommandInset ref
11080 reference "sub:I18n"
11084 for details on its use.
11087 \begin_layout Description
11088 \begin_inset Flex Code
11091 \begin_layout Plain Layout
11097 The name of the corresponding LaTeX stuff.
11098 Either the environment or command name.
11101 \begin_layout Description
11102 \begin_inset Flex Code
11105 \begin_layout Plain Layout
11111 An optional parameter for the corresponding
11112 \begin_inset Flex Code
11115 \begin_layout Plain Layout
11122 This parameter cannot be changed from within LyX.
11125 \begin_layout Description
11126 \begin_inset Flex Code
11129 \begin_layout Plain Layout
11136 \begin_inset CommandInset label
11138 name "des:LatexType"
11143 \begin_inset Flex Code
11146 \begin_layout Plain Layout
11151 , Command, Environment, Item_Environment,
11157 \begin_inset Flex Code
11160 \begin_layout Plain Layout
11161 List_Environment, Bib_Environment
11166 ] How the layout should be translated into LaTeX.
11170 \begin_layout Plain Layout
11171 \begin_inset Flex Code
11174 \begin_layout Plain Layout
11180 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11181 Visit the SGML class files for specific examples.
11190 \begin_layout Itemize
11191 \begin_inset Flex Code
11194 \begin_layout Plain Layout
11200 means nothing special.
11204 \begin_layout Itemize
11205 \begin_inset Flex Code
11208 \begin_layout Plain Layout
11215 \begin_inset Flex Code
11218 \begin_layout Plain Layout
11225 {\SpecialChar \ldots{}
11234 \begin_layout Itemize
11235 \begin_inset Flex Code
11238 \begin_layout Plain Layout
11245 \begin_inset Flex Code
11248 \begin_layout Plain Layout
11255 }\SpecialChar \ldots{}
11271 \begin_layout Itemize
11272 \begin_inset Flex Code
11275 \begin_layout Plain Layout
11282 \begin_inset Flex Code
11285 \begin_layout Plain Layout
11292 \begin_inset Flex Code
11295 \begin_layout Plain Layout
11303 is generated for each paragraph of this environment.
11307 \begin_layout Itemize
11308 \begin_inset Flex Code
11311 \begin_layout Plain Layout
11318 \begin_inset Flex Code
11321 \begin_layout Plain Layout
11328 \begin_inset Flex Code
11331 \begin_layout Plain Layout
11337 is passed as an argument to the environment.
11339 \begin_inset Flex Code
11342 \begin_layout Plain Layout
11348 can be defined in the
11349 \begin_inset Flex MenuItem
11352 \begin_layout Plain Layout
11357 ayout\SpecialChar \menuseparator
11371 \begin_layout Standard
11372 Putting the last few things together, the LaTeX output will be either:
11375 \begin_layout LyX-Code
11378 latexname[latexparam]{\SpecialChar \ldots{}
11382 \begin_layout Standard
11386 \begin_layout LyX-Code
11389 begin{latexname}[latexparam] \SpecialChar \ldots{}
11395 \begin_layout Standard
11396 depending upon the LaTeX type.
11400 \begin_layout Description
11401 \begin_inset Flex Code
11404 \begin_layout Plain Layout
11411 \begin_inset Flex Code
11414 \begin_layout Plain Layout
11420 ] If you put layouts into environments, the leftmargins are not simply added,
11421 but added with a factor
11422 \begin_inset Formula $\frac{4}{depth+4}$
11426 Note that this parameter is also used when the margin is defined as
11427 \begin_inset Flex Code
11430 \begin_layout Plain Layout
11437 \begin_inset Flex Code
11440 \begin_layout Plain Layout
11447 Then it is added to the manual or dynamic margin.
11449 \begin_inset Newline newline
11452 The argument is passed as a string.
11454 \begin_inset Quotes eld
11458 \begin_inset Flex Code
11461 \begin_layout Plain Layout
11468 \begin_inset Quotes erd
11471 means that the paragraph is indented with the width of
11472 \begin_inset Quotes eld
11476 \begin_inset Flex Code
11479 \begin_layout Plain Layout
11486 \begin_inset Quotes erd
11489 in the normal font.
11490 You can get a negative width by prefixing the string with
11491 \begin_inset Quotes eld
11495 \begin_inset Flex Code
11498 \begin_layout Plain Layout
11505 \begin_inset Quotes erd
11509 This way was chosen so that the look is the same with each used screen
11514 \begin_layout Description
11515 \begin_inset Flex Code
11518 \begin_layout Plain Layout
11525 \begin_inset Flex Code
11528 \begin_layout Plain Layout
11533 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11539 \begin_inset Newline newline
11542 The kind of margin that the layout has on the left side.
11544 \begin_inset Flex Code
11547 \begin_layout Plain Layout
11553 just means a fixed margin.
11555 \begin_inset Flex Code
11558 \begin_layout Plain Layout
11564 means that the left margin depends on the string entered in the
11565 \begin_inset Flex MenuItem
11568 \begin_layout Plain Layout
11569 Edit\SpecialChar \menuseparator
11571 \begin_inset space ~
11580 This is used to typeset nice lists without tabulators.
11582 \begin_inset Flex Code
11585 \begin_layout Plain Layout
11591 means that the margin depends on the size of the label.
11592 This is used for automatic enumerated headlines.
11593 It is obvious that the headline
11594 \begin_inset Quotes eld
11597 5.4.3.2.1 Very long headline
11598 \begin_inset Quotes erd
11601 must have a wider left margin (as wide as
11602 \begin_inset Quotes eld
11606 \begin_inset Quotes erd
11609 plus the space) than
11610 \begin_inset Quotes eld
11613 3.2 Very long headline
11614 \begin_inset Quotes erd
11618 \begin_inset Quotes eld
11622 \begin_inset Quotes erd
11625 are not able to do this.
11627 \begin_inset Flex Code
11630 \begin_layout Plain Layout
11636 is similar, but only the very first row of the paragraph is dynamic, while
11637 the others are static; this is used, for example, for descriptions.
11639 \begin_inset Flex Code
11642 \begin_layout Plain Layout
11648 means the margin is chosen in a way that the longest row of this paragraph
11649 fits to the right margin.
11650 This is used to typeset an address on the right edge of the page.
11653 \begin_layout Description
11654 \begin_inset Flex Code
11657 \begin_layout Plain Layout
11664 \begin_inset Flex Code
11667 \begin_layout Plain Layout
11676 \begin_inset Flex Code
11679 \begin_layout Plain Layout
11685 ] Whether fragile commands in this layout should be
11686 \begin_inset Flex Code
11689 \begin_layout Plain Layout
11702 whether this command should itself be protected.)
11705 \begin_layout Description
11706 \begin_inset Flex Code
11709 \begin_layout Plain Layout
11716 \begin_inset Flex Code
11719 \begin_layout Plain Layout
11726 \begin_inset Flex Code
11729 \begin_layout Plain Layout
11737 ] Whether newlines are translated into LaTeX newlines (
11738 \begin_inset Flex Code
11741 \begin_layout Plain Layout
11752 The translation can be switched off to allow more comfortable LaTeX editing
11756 \begin_layout Description
11757 \begin_inset Flex Code
11760 \begin_layout Plain Layout
11767 \begin_inset Flex Code
11770 \begin_layout Plain Layout
11777 \begin_inset Flex Code
11780 \begin_layout Plain Layout
11788 ] Whether the following Paragraph is allowed to indent its very first row.
11790 \begin_inset Flex Code
11793 \begin_layout Plain Layout
11799 means that it is not allowed to do so;
11800 \begin_inset Flex Code
11803 \begin_layout Plain Layout
11809 means it could do so if it wants to.
11812 \begin_layout Description
11813 \begin_inset Flex Code
11816 \begin_layout Plain Layout
11822 Name of a layout that has replaced this layout.
11823 This is used to rename a layout, while keeping backward compatibility.
11826 \begin_layout Description
11827 \begin_inset Flex Code
11830 \begin_layout Plain Layout
11837 \begin_inset Flex Code
11840 \begin_layout Plain Layout
11846 ] The number of optional arguments that can be used with this layout.
11847 This is useful for things like section headings, and only makes sense with
11849 Note that, on output, the optional arguments will all precede any required
11850 arguments (see below).
11851 So one can have constructs like:
11855 \begin_layout LyX-Code
11858 mycmd[opt1]{req1}{contents of paragraph}
11861 \begin_layout Standard
11862 but one cannot have things like:
11865 \begin_layout LyX-Code
11868 mycmd[opt1]{req1}[opt2]{contents of paragraph}
11871 \begin_layout Standard
11872 at least, not without ERT (with which you can have anything).
11877 \begin_layout Description
11878 \begin_inset Flex Code
11881 \begin_layout Plain Layout
11888 \begin_inset CommandInset label
11890 name "des:ParbreakIsNewline"
11895 \begin_inset Flex Code
11898 \begin_layout Plain Layout
11907 \begin_inset Flex Code
11910 \begin_layout Plain Layout
11916 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
11917 output, but only by a line break; together with
11918 \begin_inset Flex Code
11921 \begin_layout Plain Layout
11927 , this allows to emulate a plain text editor (like the ERT inset).
11930 \begin_layout Description
11931 \begin_inset Flex Code
11934 \begin_layout Plain Layout
11941 \begin_inset Flex Code
11944 \begin_layout Plain Layout
11950 ] The indent of the very first line of a paragraph.
11952 \begin_inset Flex Code
11955 \begin_layout Plain Layout
11961 will be fixed for a certain layout.
11962 The exception is Standard layout, since the indentation of a Standard layout
11963 paragraph can be prohibited with
11964 \begin_inset Flex Code
11967 \begin_layout Plain Layout
11974 Also, Standard layout paragraphs inside environments use the
11975 \begin_inset Flex Code
11978 \begin_layout Plain Layout
11984 of the environment, not their native one.
11985 For example, Standard paragraphs inside an enumeration are not indented.
11988 \begin_layout Description
11989 \begin_inset Flex Code
11992 \begin_layout Plain Layout
11999 \begin_inset Flex Code
12002 \begin_layout Plain Layout
12008 ] The vertical space between two paragraphs of this layout.
12011 \begin_layout Description
12012 \begin_inset Flex Code
12015 \begin_layout Plain Layout
12022 \begin_inset Flex Code
12025 \begin_layout Plain Layout
12031 ] LyX allows the user to choose either
12032 \begin_inset Quotes eld
12036 \begin_inset Quotes erd
12040 \begin_inset Quotes eld
12044 \begin_inset Quotes erd
12047 to typeset a document.
12049 \begin_inset Quotes eld
12053 \begin_inset Quotes erd
12056 is chosen, this value is completely ignored.
12058 \begin_inset Quotes eld
12062 \begin_inset Quotes erd
12065 is chosen, the parindent of a LaTeXtype
12066 \begin_inset Quotes eld
12070 \begin_inset Quotes erd
12073 layout is ignored and all paragraphs are separated by this parskip argument.
12074 The vertical space is calculated with
12075 \begin_inset Flex Code
12078 \begin_layout Plain Layout
12080 \begin_inset space ~
12089 \begin_inset Flex Code
12092 \begin_layout Plain Layout
12098 is the height of a row with the normal font.
12099 This way, the look stays the same with different screen fonts.
12102 \begin_layout Description
12103 \begin_inset Flex Code
12106 \begin_layout Plain Layout
12113 \begin_inset CommandInset label
12115 name "des:PassThru"
12120 \begin_inset Flex Code
12123 \begin_layout Plain Layout
12132 \begin_inset Flex Code
12135 \begin_layout Plain Layout
12141 ] Whether the contents of this paragraph should be output in raw form, meaning
12142 without special translations that LaTeX would require.
12145 \begin_layout Description
12146 \begin_inset Flex Code
12149 \begin_layout Plain Layout
12156 \begin_inset CommandInset label
12158 name "des:Preamble"
12162 Information to be included in the LaTeX preamble when this style is used.
12163 Used to define macros, load packages, etc., required by this particular
12166 \begin_inset Quotes eld
12170 \begin_inset Flex Code
12173 \begin_layout Plain Layout
12180 \begin_inset Quotes erd
12186 \begin_layout Description
12187 \begin_inset Flex Code
12190 \begin_layout Plain Layout
12197 \begin_inset Flex Code
12200 \begin_layout Plain Layout
12206 ] The prefix to use when creating labels referring to paragraphs of this
12208 This allows the use of formatted references.
12211 \begin_layout Description
12212 \begin_inset Flex Code
12215 \begin_layout Plain Layout
12222 \begin_inset Flex Code
12225 \begin_layout Plain Layout
12231 ] The number of required arguments that the LaTeX command or environment
12232 corresponding to this layout expects.
12233 In the case of a command, these are required arguments
12237 that associated with the content of the paragraph itself.
12238 These do not actually have to be provided: LyX will output empty arguments
12240 Note that optional arguments will be output before required arguments.
12241 See the discussion of the
12242 \begin_inset Flex Code
12245 \begin_layout Plain Layout
12251 tag above for more information.
12254 \begin_layout Description
12255 \begin_inset Flex Code
12258 \begin_layout Plain Layout
12265 \begin_inset Flex Code
12268 \begin_layout Plain Layout
12275 \begin_inset CommandInset label
12277 name "des:Requires"
12281 Whether the layout requires the feature
12282 \begin_inset Flex Code
12285 \begin_layout Plain Layout
12292 See the description of
12293 \begin_inset Flex Code
12296 \begin_layout Plain Layout
12303 \begin_inset CommandInset ref
12304 LatexCommand pageref
12305 reference "des:FreeSpacing"
12309 ) for information on `features'.
12313 \begin_layout Description
12314 \begin_inset Flex Code
12317 \begin_layout Plain Layout
12324 \begin_inset Flex Code
12327 \begin_layout Plain Layout
12334 \begin_inset Flex Code
12337 \begin_layout Plain Layout
12346 \begin_layout Description
12347 \begin_inset Flex Code
12350 \begin_layout Plain Layout
12357 \begin_inset Flex Code
12360 \begin_layout Plain Layout
12365 , onehalf, double, other
12374 ] This defines what the default spacing should be in the layout.
12376 \begin_inset Flex Code
12379 \begin_layout Plain Layout
12386 \begin_inset Flex Code
12389 \begin_layout Plain Layout
12396 \begin_inset Flex Code
12399 \begin_layout Plain Layout
12405 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12406 If you specify the argument
12407 \begin_inset Flex Code
12410 \begin_layout Plain Layout
12416 , then you should also provide a numerical argument which will be the actual
12418 Note that, contrary to other parameters,
12419 \begin_inset Flex Code
12422 \begin_layout Plain Layout
12428 implies the generation of specific LaTeX code, using the package
12431 \begin_inset Flex Code
12434 \begin_layout Plain Layout
12443 \begin_layout Description
12444 \begin_inset Flex Code
12447 \begin_layout Plain Layout
12454 \begin_inset Flex Code
12457 \begin_layout Plain Layout
12464 \begin_inset Flex Code
12467 \begin_layout Plain Layout
12475 ] Spellcheck paragraphs of this style.
12479 \begin_layout Description
12480 \begin_inset Flex Code
12483 \begin_layout Plain Layout
12489 The font used for the text body .
12491 \begin_inset CommandInset ref
12493 reference "sub:Font-description"
12500 \begin_layout Description
12501 \begin_inset Flex Code
12504 \begin_layout Plain Layout
12513 \begin_inset Flex Code
12516 \begin_layout Plain Layout
12526 The level of the style in the table of contents.
12527 This is used for automatic numbering of section headings.
12530 \begin_layout Description
12531 \begin_inset Flex Code
12534 \begin_layout Plain Layout
12541 \begin_inset Flex Code
12544 \begin_layout Plain Layout
12550 ] The vertical space with which the very first of a chain of paragraphs
12551 with this layout is separated from the previous paragraph.
12552 If the previous paragraph has another layout, the separations are not simply
12553 added, but the maximum is taken.
12556 \begin_layout Subsection
12557 \begin_inset CommandInset label
12563 Internationalization of Paragraph Styles
12566 \begin_layout Standard
12567 LyX has long supported internationalization of layout information, but,
12568 until version 2.0, this applied only to the user interface and not to, say,
12570 Thus, French authors were forced to resort to ugly hacks if they wanted
12575 1' instead of `Theorem 1'.
12576 Thanks to Georg Baum, that is no longer the case.
12579 \begin_layout Standard
12581 \begin_inset Flex Code
12584 \begin_layout Plain Layout
12590 defines text that is to appear in the typeset document, it may use
12591 \begin_inset Flex Code
12594 \begin_layout Plain Layout
12601 \begin_inset Flex Code
12604 \begin_layout Plain Layout
12610 to support non-English and even multi-language documents correctly.
12611 The following excerpt (from the
12612 \begin_inset Flex Code
12615 \begin_layout Plain Layout
12621 file) shows how this works:
12624 \begin_layout LyX-Code
12629 \begin_layout LyX-Code
12632 theoremstyle{remark}
12635 \begin_layout LyX-Code
12638 newtheorem{claim}[thm]{
12645 \begin_layout LyX-Code
12649 \begin_layout LyX-Code
12653 \begin_layout LyX-Code
12658 claimname}{_(Claim)}
12661 \begin_layout LyX-Code
12665 \begin_layout LyX-Code
12669 \begin_layout LyX-Code
12678 claimname}{_(Claim)}}
12681 \begin_layout LyX-Code
12686 \begin_layout Standard
12687 In principle, any legal LaTeX may appear in the
12688 \begin_inset Flex Code
12691 \begin_layout Plain Layout
12698 \begin_inset Flex Code
12701 \begin_layout Plain Layout
12707 tags, but in practice they will typically look as they do here.
12708 The key to correct translation of the typeset text is the definition of
12710 \begin_inset Flex Code
12713 \begin_layout Plain Layout
12722 \begin_inset Flex Code
12725 \begin_layout Plain Layout
12737 \begin_layout Standard
12739 \begin_inset Flex Code
12742 \begin_layout Plain Layout
12748 tag provides for internationalization based upon the overall language of
12750 The contents of the tag will be included in the preamble, just as with
12752 \begin_inset Flex Code
12755 \begin_layout Plain Layout
12762 What makes it special is the use of the
12763 \begin_inset Quotes eld
12767 \begin_inset Quotes erd
12771 \begin_inset Flex Code
12774 \begin_layout Plain Layout
12780 , which will be replaced, when LyX produces LaTeX output, with the translation
12781 of its argument into the document language.
12784 \begin_layout Standard
12786 \begin_inset Flex Code
12789 \begin_layout Plain Layout
12795 tag is more complex, since it is meant to provide support for multi-language
12796 documents and so offers an interface to the
12797 \begin_inset Flex Code
12800 \begin_layout Plain Layout
12807 Its contents will be added to the preamble once for each language that
12808 appears in the document.
12809 In this case, the argument to
12810 \begin_inset Flex Code
12813 \begin_layout Plain Layout
12819 will be replaced with its translation into the language in question; the
12821 \begin_inset Flex Code
12824 \begin_layout Plain Layout
12830 is replaced by the language name (as used by the babel package).
12833 \begin_layout Standard
12834 A German document that also included a French section would thus have the
12835 following in the preamble:
12838 \begin_layout LyX-Code
12847 claimname}{Affirmation}}
12855 claimname}{Behauptung}}
12859 claimname}{Behauptung}
12862 \begin_layout Standard
12864 \begin_inset Flex Code
12867 \begin_layout Plain Layout
12873 will then conspire to produce the correct text in the output.
12876 \begin_layout Standard
12877 One important point to note here is that the translations are provided by
12878 LyX itself, through the same mechanism it uses for internationalization
12879 of the user interface.
12880 This means, in effect, that
12881 \begin_inset Flex Code
12884 \begin_layout Plain Layout
12891 \begin_inset Flex Code
12894 \begin_layout Plain Layout
12900 are really only of use in layout files that are provided with LyX, since
12901 text entered in user-created layout files will not be seen by LyX's internation
12902 alization routines.
12903 That said, however, any layout created with the intention that it will
12904 be included with LyX should use these tags where appropriate.
12907 \begin_layout Subsection
12909 \begin_inset CommandInset label
12918 \begin_layout Standard
12919 Since version 1.3.0 of LyX, it is has been both possible and necessary to
12920 define the floats (
12921 \begin_inset Flex MenuItem
12924 \begin_layout Plain Layout
12931 \begin_inset Flex MenuItem
12934 \begin_layout Plain Layout
12940 , \SpecialChar \ldots{}
12941 ) in the text class itself.
12942 Standard floats are included in the file
12943 \begin_inset Flex Code
12946 \begin_layout Plain Layout
12952 , so you may have to do no more than add
12955 \begin_layout LyX-Code
12956 Input stdfloats.inc
12959 \begin_layout Standard
12960 to your layout file.
12961 If you want to implement a text class that proposes some other float types
12962 (like the AGU class bundled with LyX), the information below will hopefully
12966 \begin_layout Description
12967 \begin_inset Flex Code
12970 \begin_layout Plain Layout
12977 \begin_inset Flex Code
12980 \begin_layout Plain Layout
12987 \begin_inset Quotes erd
12991 \begin_inset Quotes erd
12994 ] The file name extension of an auxiliary file for the list of figures (or
12996 LaTeX writes the captions to this file.
12999 \begin_layout Description
13000 \begin_inset Flex Code
13003 \begin_layout Plain Layout
13010 \begin_inset Flex Code
13013 \begin_layout Plain Layout
13020 \begin_inset Quotes erd
13024 \begin_inset Quotes erd
13027 ] The string that will be used in the menus and also for the caption.
13028 This is translated to the current language if babel is used.
13031 \begin_layout Description
13032 \begin_inset Flex Code
13035 \begin_layout Plain Layout
13041 These are used for XHTML output.
13043 \begin_inset CommandInset ref
13045 reference "sec:Tags-for-XHTML"
13052 \begin_layout Description
13053 \begin_inset Flex Code
13056 \begin_layout Plain Layout
13063 \begin_inset Flex Code
13066 \begin_layout Plain Layout
13073 \begin_inset Quotes erd
13077 \begin_inset Quotes erd
13080 ] The command used to generate a list of floats of this type; the leading
13083 ' should be omitted.
13089 \begin_inset Flex Code
13092 \begin_layout Plain Layout
13098 is false, since there is no standard way to generate this command.
13100 \begin_inset Flex Code
13103 \begin_layout Plain Layout
13109 is true, since in that case there is a standard way.
13112 \begin_layout Description
13113 \begin_inset Flex Code
13116 \begin_layout Plain Layout
13123 \begin_inset Flex Code
13126 \begin_layout Plain Layout
13133 \begin_inset Quotes erd
13137 \begin_inset Quotes erd
13140 ] A title for a list of floats of this kind (list of figures, tables, or
13142 It is used for the screen label within LyX; it is passed to LaTeX for use
13143 as the title there; and it is used as the title in XHTML output.
13144 It will be translated to the document language.
13147 \begin_layout Description
13148 \begin_inset Flex Code
13151 \begin_layout Plain Layout
13158 \begin_inset Flex Code
13161 \begin_layout Plain Layout
13168 \begin_inset Flex Code
13171 \begin_layout Plain Layout
13179 ] Indicates whether the float is already defined in the document class or
13180 if we instead need to load
13181 \begin_inset Flex Code
13184 \begin_layout Plain Layout
13190 and use what it provides.
13192 \begin_inset Flex Code
13195 \begin_layout Plain Layout
13202 \begin_inset Flex Code
13205 \begin_layout Plain Layout
13212 It should be set to
13213 \begin_inset Flex Code
13216 \begin_layout Plain Layout
13222 if the float is already defined by the LaTeX document class.
13225 \begin_layout Description
13226 \begin_inset Flex Code
13229 \begin_layout Plain Layout
13236 \begin_inset Flex Code
13239 \begin_layout Plain Layout
13246 \begin_inset Quotes erd
13250 \begin_inset Quotes erd
13253 ] This (optional) argument determines whether floats of this class will
13254 be numbered within some sectional unit of the document.
13255 For example, if within is equal to
13256 \begin_inset Flex Code
13259 \begin_layout Plain Layout
13265 , the floats will be numbered within chapters.
13269 \begin_layout Description
13270 \begin_inset Flex Code
13273 \begin_layout Plain Layout
13280 \begin_inset Flex Code
13283 \begin_layout Plain Layout
13290 \begin_inset Quotes erd
13294 \begin_inset Quotes erd
13297 ] The default placement for the given class of floats.
13298 The string should be as in standard LaTeX:
13299 \begin_inset Flex Code
13302 \begin_layout Plain Layout
13309 \begin_inset Flex Code
13312 \begin_layout Plain Layout
13319 \begin_inset Flex Code
13322 \begin_layout Plain Layout
13329 \begin_inset Flex Code
13332 \begin_layout Plain Layout
13338 for top, bottom, page, and here, respectively.
13342 \begin_layout Plain Layout
13343 Note that the order of these letters in the string is irrelevant, like in
13349 On top of that there is a new type,
13350 \begin_inset Flex Code
13353 \begin_layout Plain Layout
13359 , which does not really correspond to a float, since it means: put it
13360 \begin_inset Quotes eld
13364 \begin_inset Quotes erd
13368 Note however that the
13369 \begin_inset Flex Code
13372 \begin_layout Plain Layout
13378 specifier is special and, because of implementation details, cannot be
13379 used in non-built in float types.
13380 If you do not understand what this means, just use
13381 \begin_inset Quotes eld
13385 \begin_inset Flex Code
13388 \begin_layout Plain Layout
13395 \begin_inset Quotes erd
13401 \begin_layout Description
13402 \begin_inset Flex Code
13405 \begin_layout Plain Layout
13412 \begin_inset Flex Code
13415 \begin_layout Plain Layout
13421 ] The prefix to use when creating labels referring to floats of this type.
13422 This allows the use of formatted references.
13423 Note that you can remove any
13424 \begin_inset Flex Code
13427 \begin_layout Plain Layout
13433 set by a copied style by using the special value
13434 \begin_inset Quotes eld
13438 \begin_inset Quotes erd
13441 , which must be all caps.
13444 \begin_layout Description
13445 \begin_inset Flex Code
13448 \begin_layout Plain Layout
13455 \begin_inset Flex Code
13458 \begin_layout Plain Layout
13465 \begin_inset Quotes erd
13469 \begin_inset Quotes erd
13472 ] The style used when defining the float using
13473 \begin_inset Flex Code
13476 \begin_layout Plain Layout
13487 \begin_layout Description
13488 \begin_inset Flex Code
13491 \begin_layout Plain Layout
13498 \begin_inset Flex Code
13501 \begin_layout Plain Layout
13508 \begin_inset Quotes erd
13512 \begin_inset Quotes erd
13516 \begin_inset Quotes eld
13520 \begin_inset Quotes erd
13523 of the new class of floats, like program or algorithm.
13524 After the appropriate
13525 \begin_inset Flex Code
13528 \begin_layout Plain Layout
13537 \begin_inset Flex Code
13540 \begin_layout Plain Layout
13549 \begin_inset Flex Code
13552 \begin_layout Plain Layout
13563 \begin_layout Standard
13564 Note that defining a float with type
13565 \begin_inset Flex Code
13568 \begin_layout Plain Layout
13576 automatically defines the corresponding counter with name
13577 \begin_inset Flex Code
13580 \begin_layout Plain Layout
13591 \begin_layout Subsection
13592 Flex insets and InsetLayout
13593 \begin_inset CommandInset label
13595 name "sub:Flex-insets-and"
13602 \begin_layout Standard
13603 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
13604 these are called Flex insets.
13608 \begin_layout Standard
13609 Flex insets come in three different kinds:
13612 \begin_layout Itemize
13614 \begin_inset Flex Code
13617 \begin_layout Plain Layout
13623 ): These define semantic markup corresponding to such LaTeX commands as
13625 \begin_inset Flex Code
13628 \begin_layout Plain Layout
13637 \begin_inset Flex Code
13640 \begin_layout Plain Layout
13651 \begin_layout Itemize
13653 \begin_inset Flex Code
13656 \begin_layout Plain Layout
13662 ): These can be used to define custom collapsible insets, similar to TeX
13663 code, footnote, and the like.
13664 An obvious example is an endnote inset, which is defined in the
13665 \begin_inset Flex Code
13668 \begin_layout Plain Layout
13677 \begin_layout Itemize
13679 \begin_inset Flex Code
13682 \begin_layout Plain Layout
13688 ): For use with DocBook classes.
13691 \begin_layout Standard
13692 Flex insets are defined using the
13693 \begin_inset Flex Code
13696 \begin_layout Plain Layout
13702 tag, which shall be explained in a moment.
13705 \begin_layout Standard
13707 \begin_inset Flex Code
13710 \begin_layout Plain Layout
13716 tag also serves another function: It can be used to customize the general
13717 layout of many different types of insets.
13719 \begin_inset Flex Code
13722 \begin_layout Plain Layout
13728 can be used to customize the layout parameters for footnotes, marginal
13729 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
13730 boxes, tables, algorithms, URLs, and optional arguments, as well as to
13731 define Flex insets.
13734 \begin_layout Standard
13736 \begin_inset Flex Code
13739 \begin_layout Plain Layout
13745 definition must begin with a line of the form:
13748 \begin_layout LyX-Code
13752 \begin_layout Standard
13754 \begin_inset Flex Code
13757 \begin_layout Plain Layout
13763 indicates the inset whose layout is being defined, and here there are two
13767 \begin_layout Enumerate
13768 The layout for a pre-existing inset is being modified.
13769 In this case, can be
13770 \begin_inset Flex Code
13773 \begin_layout Plain Layout
13779 any one of the following:
13780 \begin_inset Flex Code
13783 \begin_layout Plain Layout
13790 \begin_inset Flex Code
13793 \begin_layout Plain Layout
13800 \begin_inset Flex Code
13803 \begin_layout Plain Layout
13810 \begin_inset Flex Code
13813 \begin_layout Plain Layout
13820 \begin_inset Flex Code
13823 \begin_layout Plain Layout
13830 \begin_inset Flex Code
13833 \begin_layout Plain Layout
13840 \begin_inset Flex Code
13843 \begin_layout Plain Layout
13850 \begin_inset Flex Code
13853 \begin_layout Plain Layout
13860 \begin_inset Flex Code
13863 \begin_layout Plain Layout
13870 \begin_inset Flex Code
13873 \begin_layout Plain Layout
13880 \begin_inset Flex Code
13883 \begin_layout Plain Layout
13890 \begin_inset Flex Code
13893 \begin_layout Plain Layout
13900 \begin_inset Flex Code
13903 \begin_layout Plain Layout
13910 \begin_inset Flex Code
13913 \begin_layout Plain Layout
13920 \begin_inset Flex Code
13923 \begin_layout Plain Layout
13930 \begin_inset Flex Code
13933 \begin_layout Plain Layout
13940 \begin_inset Flex Code
13943 \begin_layout Plain Layout
13950 \begin_inset Flex Code
13953 \begin_layout Plain Layout
13960 \begin_inset Flex Code
13963 \begin_layout Plain Layout
13970 \begin_inset Flex Code
13973 \begin_layout Plain Layout
13982 \begin_layout Enumerate
13983 The layout for a Flex inset is being defined.
13985 \begin_inset Flex Code
13988 \begin_layout Plain Layout
13994 may be be any valid identifier not used by a pre-existing inset.
13995 The identifier may include spaces, but in that case the whole thing must
13996 be wrapped in quotes.
13997 It may also include a namespace identifier, preceding a colon, such as
13999 \begin_inset Quotes eld
14003 \begin_inset Flex Code
14006 \begin_layout Plain Layout
14013 \begin_inset Quotes erd
14017 Note that the definition of a flex inset
14022 \begin_inset Flex Code
14025 \begin_layout Plain Layout
14031 entry, declaring which type of inset it defines.
14034 \begin_layout Standard
14036 \begin_inset Flex Code
14039 \begin_layout Plain Layout
14045 definition can contain the following entries:
14048 \begin_layout Description
14049 \begin_inset Flex Code
14052 \begin_layout Plain Layout
14058 The color for the inset's background.
14059 The valid colors are defined in
14060 \begin_inset Flex Code
14063 \begin_layout Plain Layout
14072 \begin_layout Description
14073 \begin_inset Flex Code
14076 \begin_layout Plain Layout
14083 \begin_inset Flex Code
14086 \begin_layout Plain Layout
14095 \begin_inset Flex Code
14098 \begin_layout Plain Layout
14104 ] Whether to use the content of the inset as the label, when the inset is
14109 \begin_layout Description
14110 \begin_inset Flex Code
14113 \begin_layout Plain Layout
14119 As with paragraph styles (see page
14120 \begin_inset CommandInset ref
14122 reference "des:CopyStyle"
14129 \begin_layout Description
14130 \begin_inset Flex Code
14133 \begin_layout Plain Layout
14140 \begin_inset Flex Code
14143 \begin_layout Plain Layout
14152 \begin_inset Flex Code
14155 \begin_layout Plain Layout
14161 ] Indicates whether the user may employ the Paragraph Settings dialog to
14162 customize the paragraph.
14165 \begin_layout Description
14166 \begin_inset Flex Code
14169 \begin_layout Plain Layout
14176 \begin_inset Flex Code
14179 \begin_layout Plain Layout
14186 \begin_inset Flex Code
14189 \begin_layout Plain Layout
14196 \begin_inset Flex Code
14199 \begin_layout Plain Layout
14205 , describing the rendering style used for the inset's frame and buttons.
14206 Footnotes generally use
14207 \begin_inset Flex Code
14210 \begin_layout Plain Layout
14216 , ERT insets generally
14217 \begin_inset Flex Code
14220 \begin_layout Plain Layout
14226 , and character styles
14227 \begin_inset Flex Code
14230 \begin_layout Plain Layout
14239 \begin_layout Description
14240 \begin_inset Flex Code
14243 \begin_layout Plain Layout
14249 Required at the end of the InsetLayout declarations.
14252 \begin_layout Description
14253 \begin_inset Flex Code
14256 \begin_layout Plain Layout
14262 The font used for both the text body
14268 \begin_inset space ~
14272 \begin_inset CommandInset ref
14274 reference "sub:Font-description"
14279 Note that defining this font automatically defines the
14280 \begin_inset Flex Code
14283 \begin_layout Plain Layout
14289 to the same value, so define this first and define
14290 \begin_inset Flex Code
14293 \begin_layout Plain Layout
14299 later if you want them to be different.
14302 \begin_layout Description
14303 \begin_inset Flex Code
14306 \begin_layout Plain Layout
14313 \begin_inset Quotes eld
14317 \begin_inset Quotes erd
14320 language, leading to Left-to-Right (latin) output, e.
14321 \begin_inset space \thinspace{}
14325 \begin_inset space \space{}
14328 in TeX code or URL.
14332 \begin_layout Description
14333 \begin_inset Flex Code
14336 \begin_layout Plain Layout
14343 \begin_inset Flex Code
14346 \begin_layout Plain Layout
14355 \begin_inset Flex Code
14358 \begin_layout Plain Layout
14364 ] Indicates whether the PlainLayout should be used or, instead, the user
14365 can change the paragraph style used in the inset.
14369 \begin_layout Description
14370 \begin_inset Flex Code
14373 \begin_layout Plain Layout
14379 As with paragraph styles (see page
14380 \begin_inset CommandInset ref
14381 LatexCommand pageref
14382 reference "des:FreeSpacing"
14390 \begin_layout Description
14391 \begin_inset Flex Code
14394 \begin_layout Plain Layout
14400 These tags control XHTML output.
14402 \begin_inset CommandInset ref
14403 LatexCommand formatted
14404 reference "sec:Tags-for-XHTML"
14411 \begin_layout Description
14412 \begin_inset Flex Code
14415 \begin_layout Plain Layout
14422 \begin_inset Flex Code
14425 \begin_layout Plain Layout
14434 \begin_inset Flex Code
14437 \begin_layout Plain Layout
14443 ] Whether to include the contents of this inset in the strings generated
14444 for the `Outline' pane.
14445 One would not, for example, want the content of a footnote in a section
14446 header to be included in the TOC displayed in the outline, but one would
14447 normally want the content of a character style displayed.
14448 Default is false: not to include.
14451 \begin_layout Description
14452 \begin_inset Flex Code
14455 \begin_layout Plain Layout
14461 As with paragraph styles (see page
14462 \begin_inset CommandInset ref
14463 LatexCommand pageref
14464 reference "des:KeepEmpty"
14472 \begin_layout Description
14473 \begin_inset Flex Code
14476 \begin_layout Plain Layout
14482 The font used for the label.
14484 \begin_inset space ~
14488 \begin_inset CommandInset ref
14490 reference "sub:Font-description"
14495 Note that this definition can never appear before
14496 \begin_inset Flex Code
14499 \begin_layout Plain Layout
14505 , lest it be ineffective.
14508 \begin_layout Description
14509 \begin_inset Flex Code
14512 \begin_layout Plain Layout
14518 What will be displayed on the button or elsewhere as the inset label.
14519 Some inset types (TeX code and Branch) modify this label on the fly.
14522 \begin_layout Description
14523 \begin_inset Flex Code
14526 \begin_layout Plain Layout
14532 The name of the corresponding LaTeX stuff.
14533 Either the environment or command name.
14536 \begin_layout Description
14537 \begin_inset Flex Code
14540 \begin_layout Plain Layout
14546 The optional parameter for the corresponding
14547 \begin_inset Flex Code
14550 \begin_layout Plain Layout
14556 stuff, including possible bracket pairs like
14557 \begin_inset Flex Code
14560 \begin_layout Plain Layout
14567 This parameter cannot be changed from within LyX.
14570 \begin_layout Description
14571 \begin_inset Flex Code
14574 \begin_layout Plain Layout
14580 As with paragraph styles (see page
14581 \begin_inset CommandInset ref
14582 LatexCommand pageref
14583 reference "des:LatexType"
14590 \begin_layout Description
14591 \begin_inset Flex Code
14594 \begin_layout Plain Layout
14601 \begin_inset Flex Code
14604 \begin_layout Plain Layout
14611 \begin_inset Flex Code
14614 \begin_layout Plain Layout
14621 \begin_inset Flex Code
14624 \begin_layout Plain Layout
14631 \begin_inset Flex Code
14634 \begin_layout Plain Layout
14640 (indicating a dummy definition ending definitions of charstyles, etc).
14641 This entry is required in and is only meaningful for Flex insets.
14642 Among other things, it determines on which menu this inset will appear.
14644 \begin_inset Flex Code
14647 \begin_layout Plain Layout
14654 \begin_inset Flex Code
14657 \begin_layout Plain Layout
14664 \begin_inset Flex Code
14667 \begin_layout Plain Layout
14675 \begin_inset Flex Code
14678 \begin_layout Plain Layout
14684 can be set to true for charstyle insets, if you wish, by setting it
14689 \begin_inset Flex Code
14692 \begin_layout Plain Layout
14701 \begin_layout Description
14702 \begin_inset Flex Code
14705 \begin_layout Plain Layout
14712 \begin_inset Flex Code
14715 \begin_layout Plain Layout
14724 \begin_inset Flex Code
14727 \begin_layout Plain Layout
14733 ] Whether multiple paragraphs are permitted in this inset.
14735 \begin_inset Flex Code
14738 \begin_layout Plain Layout
14744 to the same value and
14745 \begin_inset Flex Code
14748 \begin_layout Plain Layout
14754 to the opposite value.
14755 These can be reset to other values, if they are used
14760 \begin_inset Flex Code
14763 \begin_layout Plain Layout
14773 \begin_layout Description
14774 \begin_inset Flex Code
14777 \begin_layout Plain Layout
14784 \begin_inset Flex Code
14787 \begin_layout Plain Layout
14796 \begin_inset Flex Code
14799 \begin_layout Plain Layout
14805 ] Whether fragile commands in this layout should be
14806 \begin_inset Flex Code
14809 \begin_layout Plain Layout
14822 whether the command should itself be protected.) Default is false.
14825 \begin_layout Description
14826 \begin_inset Flex Code
14829 \begin_layout Plain Layout
14836 \begin_inset Flex Code
14839 \begin_layout Plain Layout
14848 \begin_inset Flex Code
14851 \begin_layout Plain Layout
14857 ] As with paragraph styles (see page
14858 \begin_inset CommandInset ref
14859 LatexCommand pageref
14860 reference "des:ParbreakIsNewline"
14868 \begin_layout Description
14869 \begin_inset Flex Code
14872 \begin_layout Plain Layout
14879 \begin_inset Flex Code
14882 \begin_layout Plain Layout
14891 \begin_inset Flex Code
14894 \begin_layout Plain Layout
14900 ] As with paragraph styles (see page
14901 \begin_inset CommandInset ref
14902 LatexCommand pageref
14903 reference "des:PassThru"
14911 \begin_layout Description
14912 \begin_inset Flex Code
14915 \begin_layout Plain Layout
14921 As with paragraph styles (see page
14922 \begin_inset CommandInset ref
14923 LatexCommand pageref
14924 reference "des:Preamble"
14931 \begin_layout Description
14932 \begin_inset Flex Code
14935 \begin_layout Plain Layout
14942 \begin_inset Flex Code
14945 \begin_layout Plain Layout
14951 ] The prefix to use when creating labels referring to insets of this type.
14952 This allows the use of formatted references.
14955 \begin_layout Description
14956 \begin_inset Flex Code
14959 \begin_layout Plain Layout
14966 \begin_inset Flex Code
14969 \begin_layout Plain Layout
14975 ] As with paragraph styles (see page
14976 \begin_inset CommandInset ref
14977 LatexCommand pageref
14978 reference "des:Requires"
14985 \begin_layout Description
14986 \begin_inset Flex Code
14989 \begin_layout Plain Layout
14996 \begin_inset Flex Code
14999 \begin_layout Plain Layout
15006 \begin_inset Flex Code
15009 \begin_layout Plain Layout
15017 ] Whether this inset should use the font of its surrounding environment
15019 Default is true: uses its own.
15022 \begin_layout Description
15023 \begin_inset Flex Code
15026 \begin_layout Plain Layout
15033 \begin_inset Flex Code
15036 \begin_layout Plain Layout
15043 \begin_inset Flex Code
15046 \begin_layout Plain Layout
15054 ] Spellcheck the contents of this inset.
15058 \begin_layout Subsection
15060 \begin_inset CommandInset label
15062 name "sub:Counters"
15069 \begin_layout Standard
15070 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15072 \begin_inset Flex MenuItem
15075 \begin_layout Plain Layout
15082 \begin_inset Flex MenuItem
15085 \begin_layout Plain Layout
15091 , \SpecialChar \ldots{}
15092 ) in the text class itself.
15093 The standard counters are defined in the file
15094 \begin_inset Flex Code
15097 \begin_layout Plain Layout
15103 , so you may have to do no more than add
15106 \begin_layout LyX-Code
15107 Input stdcounters.inc
15110 \begin_layout Standard
15111 to your layout file to get them to work.
15112 But if you want to define custom counters, then you can do so.
15113 The counter declaration must begin with:
15116 \begin_layout LyX-Code
15117 Counter CounterName
15120 \begin_layout Standard
15122 \begin_inset Flex Code
15125 \begin_layout Plain Layout
15131 ' is replaced by the name of the counter.
15132 And it must end with
15133 \begin_inset Quotes eld
15137 \begin_inset Flex Code
15140 \begin_layout Plain Layout
15147 \begin_inset Quotes erd
15151 The following parameters can also be used:
15154 \begin_layout Description
15155 \begin_inset Flex Code
15158 \begin_layout Plain Layout
15165 \begin_inset Flex Code
15168 \begin_layout Plain Layout
15175 \begin_inset Quotes erd
15179 \begin_inset Quotes erd
15182 ] When defined, this string defines how the counter is displayed.
15183 Setting this value sets
15184 \begin_inset Flex Code
15187 \begin_layout Plain Layout
15188 LabelStringAppendix
15194 The following special constructs can be used in the string:
15198 \begin_layout Itemize
15199 \begin_inset Flex Code
15202 \begin_layout Plain Layout
15210 will be replaced by the expansion of the
15211 \begin_inset Flex Code
15214 \begin_layout Plain Layout
15221 \begin_inset Flex Code
15224 \begin_layout Plain Layout
15225 LabelStringAppendix
15231 \begin_inset Flex Code
15234 \begin_layout Plain Layout
15244 \begin_layout Itemize
15245 counter values can be expressed using LaTeX-like macros
15246 \begin_inset Flex Code
15249 \begin_layout Plain Layout
15266 \begin_inset Flex Code
15269 \begin_layout Plain Layout
15281 \begin_layout Plain Layout
15291 Actually, the situation is a bit more complicated: any
15310 other than those described below will produce arabic numerals.
15311 It would not be surprising to see this change in the future.
15317 \begin_inset Flex Code
15320 \begin_layout Plain Layout
15326 : 1, 2, 3,\SpecialChar \ldots{}
15328 \begin_inset Flex Code
15331 \begin_layout Plain Layout
15337 for lower-case letters: a, b, c, \SpecialChar \ldots{}
15339 \begin_inset Flex Code
15342 \begin_layout Plain Layout
15348 for upper-case letters: A, B, C, \SpecialChar \ldots{}
15350 \begin_inset Flex Code
15353 \begin_layout Plain Layout
15359 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
15361 \begin_inset Flex Code
15364 \begin_layout Plain Layout
15370 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
15372 \begin_inset Flex Code
15375 \begin_layout Plain Layout
15381 for hebrew numerals.
15385 \begin_layout Standard
15386 If LabelString is not defined, a default value is constructed as follows:
15387 if the counter has a master counter
15388 \begin_inset Flex Code
15391 \begin_layout Plain Layout
15398 \begin_inset Flex Code
15401 \begin_layout Plain Layout
15408 \begin_inset Flex Code
15411 \begin_layout Plain Layout
15421 is used; otherwise the string
15422 \begin_inset Flex Code
15425 \begin_layout Plain Layout
15436 \begin_layout Description
15437 \begin_inset Flex Code
15440 \begin_layout Plain Layout
15441 LabelStringAppendix
15447 \begin_inset Flex Code
15450 \begin_layout Plain Layout
15457 \begin_inset Quotes erd
15461 \begin_inset Quotes erd
15465 \begin_inset Flex Code
15468 \begin_layout Plain Layout
15474 , but for use in the Appendix.
15477 \begin_layout Description
15478 \begin_inset Flex Code
15481 \begin_layout Plain Layout
15488 \begin_inset Flex Code
15491 \begin_layout Plain Layout
15498 \begin_inset Quotes erd
15502 \begin_inset Quotes erd
15505 ] A format for use with formatted references to this counter.
15506 For example, one might want to have references to section numbers appear
15508 \begin_inset Quotes eld
15512 \begin_inset Quotes erd
15516 The string should contain
15517 \begin_inset Quotes eld
15521 \begin_inset Quotes erd
15525 This will be replaced by the counter number itself.
15526 So, for sections, it would be: Section ##.
15529 \begin_layout Description
15530 \begin_inset Flex Code
15533 \begin_layout Plain Layout
15540 \begin_inset Flex Code
15543 \begin_layout Plain Layout
15550 \begin_inset Quotes erd
15554 \begin_inset Quotes erd
15557 ] If this is set to the name of another counter, the present counter will
15558 be reset every time the other one is increased.
15560 \begin_inset Flex Code
15563 \begin_layout Plain Layout
15570 \begin_inset Flex Code
15573 \begin_layout Plain Layout
15582 \begin_layout Subsection
15584 \begin_inset CommandInset label
15586 name "sub:Font-description"
15593 \begin_layout Standard
15594 A font description looks like this:
15597 \begin_layout LyX-Code
15607 \begin_layout LyX-Code
15611 \begin_layout LyX-Code
15615 \begin_layout Standard
15616 The following commands are available:
15619 \begin_layout Description
15620 \begin_inset Flex Code
15623 \begin_layout Plain Layout
15630 \begin_inset Flex Code
15633 \begin_layout Plain Layout
15642 \begin_inset Flex Code
15645 \begin_layout Plain Layout
15652 \begin_inset Flex Code
15655 \begin_layout Plain Layout
15662 \begin_inset Flex Code
15665 \begin_layout Plain Layout
15672 \begin_inset Flex Code
15675 \begin_layout Plain Layout
15682 \begin_inset Flex Code
15685 \begin_layout Plain Layout
15692 \begin_inset Flex Code
15695 \begin_layout Plain Layout
15702 \begin_inset Flex Code
15705 \begin_layout Plain Layout
15712 \begin_inset Flex Code
15715 \begin_layout Plain Layout
15724 \begin_layout Description
15725 \begin_inset Flex Code
15728 \begin_layout Plain Layout
15735 \begin_inset Flex Code
15738 \begin_layout Plain Layout
15747 \begin_inset Flex Code
15750 \begin_layout Plain Layout
15757 \begin_inset Flex Code
15760 \begin_layout Plain Layout
15769 \begin_layout Description
15770 \begin_inset Flex Code
15773 \begin_layout Plain Layout
15780 \begin_inset Flex Code
15783 \begin_layout Plain Layout
15789 ] Valid arguments are:
15790 \begin_inset Flex Code
15793 \begin_layout Plain Layout
15800 \begin_inset Flex Code
15803 \begin_layout Plain Layout
15810 \begin_inset Flex Code
15813 \begin_layout Plain Layout
15820 \begin_inset Flex Code
15823 \begin_layout Plain Layout
15830 \begin_inset Flex Code
15833 \begin_layout Plain Layout
15840 \begin_inset Flex Code
15843 \begin_layout Plain Layout
15850 Each of these turns on or off the corresponding attribute.
15852 \begin_inset Flex Code
15855 \begin_layout Plain Layout
15861 turns on emphasis, and
15862 \begin_inset Flex Code
15865 \begin_layout Plain Layout
15873 \begin_inset Newline newline
15876 If the latter seems puzzling, remember that the font settings for the present
15877 context are generally inherited from the surrounding context.
15879 \begin_inset Flex Code
15882 \begin_layout Plain Layout
15888 would turn off the emphasis that was anyway in effect, say, in a theorem
15892 \begin_layout Description
15893 \begin_inset Flex Code
15896 \begin_layout Plain Layout
15903 \begin_inset Flex Code
15906 \begin_layout Plain Layout
15915 \begin_inset Flex Code
15918 \begin_layout Plain Layout
15927 \begin_layout Description
15928 \begin_inset Flex Code
15931 \begin_layout Plain Layout
15938 \begin_inset Flex Code
15941 \begin_layout Plain Layout
15950 \begin_inset Flex Code
15953 \begin_layout Plain Layout
15960 \begin_inset Flex Code
15963 \begin_layout Plain Layout
15970 \begin_inset Flex Code
15973 \begin_layout Plain Layout
15982 \begin_layout Description
15983 \begin_inset Flex Code
15986 \begin_layout Plain Layout
15993 \begin_inset Flex Code
15996 \begin_layout Plain Layout
16003 \begin_inset Flex Code
16006 \begin_layout Plain Layout
16013 \begin_inset Flex Code
16016 \begin_layout Plain Layout
16025 \begin_inset Flex Code
16028 \begin_layout Plain Layout
16035 \begin_inset Flex Code
16038 \begin_layout Plain Layout
16045 \begin_inset Flex Code
16048 \begin_layout Plain Layout
16055 \begin_inset Flex Code
16058 \begin_layout Plain Layout
16065 \begin_inset Flex Code
16068 \begin_layout Plain Layout
16077 \begin_layout Subsection
16078 \begin_inset CommandInset label
16080 name "sub:Citation-format-description"
16084 Citation format description
16087 \begin_layout Standard
16089 \begin_inset Flex Code
16092 \begin_layout Plain Layout
16098 blocks are used to describe how bibliographic information should be displayed,
16099 both within LyX itself (in the citation dialog and in tooltips, for example)
16100 and in XHTML output.
16101 Such a block might look like this:
16104 \begin_layout LyX-Code
16108 \begin_layout LyX-Code
16112 \begin_layout LyX-Code
16116 \begin_layout LyX-Code
16120 \begin_layout Standard
16121 The individual lines define how the bibliographic information associated
16122 with an article or book, respectively, is to be displayed, and such a definitio
16123 n can be given for any `entry type' that might be present in a BibTeX file.
16124 LyX defines a default format in the source code that will be used if no
16125 specific definition has been given.
16126 LyX predefines several formats in the file
16127 \begin_inset Flex Code
16130 \begin_layout Plain Layout
16136 , which is included in most of LyX's document classes.
16139 \begin_layout Standard
16140 The definitions use a simple language that allows BibTeX keys to be replaced
16142 Keys should be enclosed in
16143 \begin_inset Flex Code
16146 \begin_layout Plain Layout
16153 \begin_inset Flex Code
16156 \begin_layout Plain Layout
16163 So a simple definition might look like this:
16166 \begin_layout LyX-Code
16168 \begin_inset Quotes eld
16172 \begin_inset Quotes erd
16178 \begin_layout Standard
16179 This would print the author, followed by a comma, followed by the title,
16180 in quotes, followed by a period.
16183 \begin_layout Standard
16184 Of course, sometimes you may want to print a key only if it exists.
16185 This can be done by using a conditional construction, such as:
16186 \begin_inset Flex Code
16189 \begin_layout Plain Layout
16191 \begin_inset space ~
16201 \begin_inset Flex Code
16204 \begin_layout Plain Layout
16210 key exists, then print
16211 \begin_inset Quotes eld
16215 \begin_inset space ~
16219 \begin_inset Quotes erd
16222 followed by the volume key.
16223 It is also possible to have an else clause in the conditional, such as:
16225 \begin_inset Flex Code
16228 \begin_layout Plain Layout
16229 {%author%[[%author%]][[%editor%, ed.]]}
16236 \begin_inset Flex Code
16239 \begin_layout Plain Layout
16245 key is printed if it exists; otherwise, the editor key is printed, followed
16247 \begin_inset Quotes eld
16251 \begin_inset space ~
16255 \begin_inset Quotes erd
16258 Note that the key is again enclosed in
16259 \begin_inset Flex Code
16262 \begin_layout Plain Layout
16268 signs; the entire conditional is enclosed in braces; and the if and else
16269 clauses are enclosed in double brackets,
16270 \begin_inset Quotes eld
16274 \begin_inset Flex Code
16277 \begin_layout Plain Layout
16284 \begin_inset Quotes eld
16288 \begin_inset Quotes eld
16292 \begin_inset Flex Code
16295 \begin_layout Plain Layout
16302 \begin_inset Quotes erd
16306 There must be no space between any of these.
16309 \begin_layout Standard
16310 There is one other piece of syntax available in definitions, which looks
16312 \begin_inset Flex Code
16315 \begin_layout Plain Layout
16322 This defines a piece of formatting information that is to be used when
16324 \begin_inset Quotes eld
16328 \begin_inset Quotes erd
16332 Obviously, we do not want to output HTML tags when writing plain text,
16333 so they should be wrapped in
16334 \begin_inset Quotes eld
16338 \begin_inset Quotes erd
16342 \begin_inset Quotes eld
16346 \begin_inset Quotes erd
16352 \begin_layout Standard
16353 Two special sorts of definitions are also possible in a
16354 \begin_inset Flex Code
16357 \begin_layout Plain Layout
16364 An example of the first would be:
16367 \begin_layout LyX-Code
16369 \begin_inset Quotes eld
16373 \begin_inset Quotes erd
16379 \begin_layout Standard
16380 This is an abbreviation, or macro, and it can be used by treating it as
16382 \begin_inset Flex Code
16385 \begin_layout Plain Layout
16393 \begin_inset Flex Code
16396 \begin_layout Plain Layout
16402 exactly as it would treat its definition.
16403 So, let us issue the obvious
16411 \begin_layout LyX-Code
16415 \begin_layout Standard
16416 or anything like it.
16417 LyX shouldn't go into an infinite loop, but it may go into a long one before
16421 \begin_layout Standard
16422 The second sort of special definition might look like this:
16425 \begin_layout LyX-Code
16429 \begin_layout Standard
16430 This defines a translatable piece of text, which allows relevant parts of
16431 the bibliography to be translated.
16432 It can be included in a definition by treating it as a key:
16433 \begin_inset Flex Code
16436 \begin_layout Plain Layout
16443 Several of these are predefined in
16444 \begin_inset Flex Code
16447 \begin_layout Plain Layout
16454 Note that these are not macros, in the sense just defined.
16455 They will not be expanded.
16458 \begin_layout Standard
16459 So here then is an example that use all these features:
16462 \begin_layout LyX-Code
16463 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
16466 \begin_layout Standard
16467 The defines a macro that prints the author, followed by a comma, if the
16469 \begin_inset Flex Code
16472 \begin_layout Plain Layout
16478 key is defined, or else prints the name of the editor, followed by the
16480 \begin_inset Flex Code
16483 \begin_layout Plain Layout
16489 or its translation (it is by default
16490 \begin_inset Quotes eld
16494 \begin_inset Quotes erd
16498 \begin_inset Flex Code
16501 \begin_layout Plain Layout
16508 Note that this is in fact defined in
16509 \begin_inset Flex Code
16512 \begin_layout Plain Layout
16518 , so you can use it in your own definitions, or re-definitions, if you load
16522 \begin_layout Section
16523 \begin_inset CommandInset label
16525 name "sec:Tags-for-XHTML"
16529 Tags for XHTML output
16532 \begin_layout Standard
16533 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
16534 by layout information.
16535 In general, LyX provides sensible defaults and, as mentioned earlier, it
16536 will even construct default CSS style rules from the other layout tags.
16537 For example, LyX will attempt to use the information provided in the
16538 \begin_inset Flex Code
16541 \begin_layout Plain Layout
16547 declaration for the Chapter style to write CSS that will appropriately
16548 format chapter headings.
16551 \begin_layout Standard
16552 In many cases, then, you may not have to do anything at all to get acceptable
16553 XHTML output for your own environments, custom insets, and so forth.
16554 But in some cases you will, and so LyX provides a number of layout tags
16555 that can be used to customize the XHTML and CSS that are generated.
16558 \begin_layout Standard
16559 Note that there are two tags,
16560 \begin_inset Flex Code
16563 \begin_layout Plain Layout
16570 \begin_inset Flex Code
16573 \begin_layout Plain Layout
16579 that may appear outside style and inset declarations.
16581 \begin_inset CommandInset ref
16583 reference "sub:General-text-class"
16587 for details on these.
16590 \begin_layout Subsection
16591 \begin_inset CommandInset label
16593 name "sub:Paragraph-Style-XHTML"
16600 \begin_layout Standard
16601 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
16602 dealing with a normal paragraph, a command, or an environment, where this
16603 is itself determined by the contents of the corresponding
16604 \begin_inset Flex Code
16607 \begin_layout Plain Layout
16617 \begin_layout Standard
16618 For a command or normal paragraph, the output XHTML has the following form:
16621 \begin_layout LyX-Code
16623 \begin_inset Quotes erd
16627 \begin_inset Quotes erd
16633 \begin_layout LyX-Code
16635 \begin_inset Quotes erd
16639 \begin_inset Quotes erd
16645 \begin_layout LyX-Code
16646 Contents of the paragraph.
16649 \begin_layout LyX-Code
16653 \begin_layout Standard
16654 The label tags are of course omitted if the paragraph does not have a label.
16657 \begin_layout Standard
16658 For an environment that is not some sort of list, the XHTML takes this form:
16661 \begin_layout LyX-Code
16663 \begin_inset Quotes erd
16667 \begin_inset Quotes erd
16673 \begin_layout LyX-Code
16675 \begin_inset Quotes erd
16679 \begin_inset Quotes erd
16683 \begin_inset Quotes erd
16687 \begin_inset Quotes erd
16690 >Environment Label</labeltag>First paragraph.</itemtag>
16693 \begin_layout LyX-Code
16694 <itemtag>Second paragraph.</itemtag>
16697 \begin_layout LyX-Code
16701 \begin_layout Standard
16702 Note that the label is output only for the first paragraph, as it should
16703 be for a theorem, for example.
16707 \begin_layout Standard
16708 For a list, we have one of these forms:
16711 \begin_layout LyX-Code
16713 \begin_inset Quotes erd
16717 \begin_inset Quotes erd
16723 \begin_layout LyX-Code
16725 \begin_inset Quotes erd
16729 \begin_inset Quotes erd
16733 \begin_inset Quotes erd
16737 \begin_inset Quotes erd
16740 >List Label</labeltag>First item.</itemtag>
16743 \begin_layout LyX-Code
16745 \begin_inset Quotes erd
16749 \begin_inset Quotes erd
16753 \begin_inset Quotes erd
16757 \begin_inset Quotes erd
16760 >List Label</labeltag>Second item.</itemtag>
16763 \begin_layout LyX-Code
16767 \begin_layout LyX-Code
16771 \begin_layout LyX-Code
16773 \begin_inset Quotes erd
16777 \begin_inset Quotes erd
16783 \begin_layout LyX-Code
16785 \begin_inset Quotes erd
16789 \begin_inset Quotes erd
16792 >List Label</labeltag><itemtag attr=
16793 \begin_inset Quotes erd
16797 \begin_inset Quotes erd
16800 >First item.</itemtag>
16803 \begin_layout LyX-Code
16805 \begin_inset Quotes erd
16809 \begin_inset Quotes erd
16812 >List Label</labeltag><itemtag attr=
16813 \begin_inset Quotes erd
16817 \begin_inset Quotes erd
16820 >Second item.</itemtag>
16823 \begin_layout LyX-Code
16827 \begin_layout Standard
16828 Note the different orders of
16829 \begin_inset Flex Code
16832 \begin_layout Plain Layout
16839 \begin_inset Flex Code
16842 \begin_layout Plain Layout
16849 Which order we get depends upon the setting of
16850 \begin_inset Flex Code
16853 \begin_layout Plain Layout
16860 \begin_inset Flex Code
16863 \begin_layout Plain Layout
16869 is false (the default), you get the first of these, with the label within
16870 the item; if true, you get the second, with the label outside the item.
16873 \begin_layout Standard
16874 The specific tags and attributes output for each paragraph type can be controlle
16875 d by means of the layout tags we are about to describe.
16876 As mentioned earlier, however, LyX uses sensible defaults for many of these,
16877 so you often may not need to do very much to get good XHTML output.
16878 Think of the available tags as there so you can tweak things to your liking.
16881 \begin_layout Description
16882 \begin_inset Flex Code
16885 \begin_layout Plain Layout
16892 \begin_inset Flex Code
16895 \begin_layout Plain Layout
16901 ] Specifies attribute information to be output with the main tag.
16903 \begin_inset Quotes eld
16907 \begin_inset Flex Code
16910 \begin_layout Plain Layout
16917 \begin_inset Quotes erd
16921 By default, LyX will output
16922 \begin_inset Quotes eld
16926 \begin_inset Flex Code
16929 \begin_layout Plain Layout
16936 \begin_inset Quotes erd
16940 \begin_inset Flex Code
16943 \begin_layout Plain Layout
16949 is the LyX name of the layout, made lowercase, for example: chapter.
16954 contain any style information.
16956 \begin_inset Flex Code
16959 \begin_layout Plain Layout
16968 \begin_layout Description
16969 \begin_inset Flex Code
16972 \begin_layout Plain Layout
16979 \begin_inset Flex Code
16982 \begin_layout Plain Layout
16992 ] Whether to output the default CSS information LyX generates for this layout,
16993 even if additional information is explicitly provided via
16994 \begin_inset Flex Code
16997 \begin_layout Plain Layout
17005 \begin_inset Flex Code
17008 \begin_layout Plain Layout
17014 allows you to alter or augment the generated CSS, rather than to override
17017 \begin_inset Flex Code
17020 \begin_layout Plain Layout
17029 \begin_layout Description
17030 \begin_inset Flex Code
17033 \begin_layout Plain Layout
17040 \begin_inset Flex Code
17043 \begin_layout Plain Layout
17049 ] The tag to be used for individual paragraphs of environments, replacing
17051 \begin_inset Flex Code
17054 \begin_layout Plain Layout
17060 in the examples above.
17062 \begin_inset Flex Code
17065 \begin_layout Plain Layout
17074 \begin_layout Description
17075 \begin_inset Flex Code
17078 \begin_layout Plain Layout
17085 \begin_inset Flex Code
17088 \begin_layout Plain Layout
17094 ] Attributes for the item tag.
17096 \begin_inset Quotes eld
17100 \begin_inset Flex Code
17103 \begin_layout Plain Layout
17104 class=`layoutname_item'
17110 \begin_inset Quotes erd
17118 contain any style information.
17120 \begin_inset Flex Code
17123 \begin_layout Plain Layout
17132 \begin_layout Description
17133 \begin_inset Flex Code
17136 \begin_layout Plain Layout
17143 \begin_inset Flex Code
17146 \begin_layout Plain Layout
17152 ] The tag to be used for paragraph and item labels, replacing
17153 \begin_inset Flex Code
17156 \begin_layout Plain Layout
17162 in the examples above.
17164 \begin_inset Flex Code
17167 \begin_layout Plain Layout
17174 \begin_inset Flex Code
17177 \begin_layout Plain Layout
17184 \begin_inset Flex Code
17187 \begin_layout Plain Layout
17194 \begin_inset Flex Code
17197 \begin_layout Plain Layout
17198 Centered_Top_Environment
17203 , in which case it defaults to
17204 \begin_inset Flex Code
17207 \begin_layout Plain Layout
17216 \begin_layout Description
17217 \begin_inset Flex Code
17220 \begin_layout Plain Layout
17227 \begin_inset Flex Code
17230 \begin_layout Plain Layout
17236 ] Attributes for the label tag.
17238 \begin_inset Quotes eld
17242 \begin_inset Flex Code
17245 \begin_layout Plain Layout
17246 class=`layoutname_label'
17252 \begin_inset Quotes erd
17260 contain any style information.
17262 \begin_inset Flex Code
17265 \begin_layout Plain Layout
17274 \begin_layout Description
17275 \begin_inset Flex Code
17278 \begin_layout Plain Layout
17285 \begin_inset Flex Code
17288 \begin_layout Plain Layout
17298 ] Meaningful only for list-like environments, this tag controls whether
17299 the label tag is output before or inside the item tag.
17300 This is used, for example, in the description environment, where we want
17302 \begin_inset Flex Code
17305 \begin_layout Plain Layout
17306 <dt>\SpecialChar \ldots{}
17307 </dt><dd>\SpecialChar \ldots{}
17315 \begin_inset Flex Code
17318 \begin_layout Plain Layout
17324 : The label tag is output inside the item tag.
17327 \begin_layout Description
17328 \begin_inset Flex Code
17331 \begin_layout Plain Layout
17337 Information to be output in the
17338 \begin_inset Flex Code
17341 \begin_layout Plain Layout
17347 section when this style is used.
17348 This might, for example, be used to include a
17349 \begin_inset Flex Code
17352 \begin_layout Plain Layout
17359 \begin_inset Flex Code
17362 \begin_layout Plain Layout
17371 \begin_layout Description
17372 \begin_inset Flex Code
17375 \begin_layout Plain Layout
17381 CSS style information to be included when this style is used.
17382 Note that this will automatically be wrapped in a layout-generated
17383 \begin_inset Flex Code
17386 \begin_layout Plain Layout
17392 block, so only the CSS itself need be included.
17395 \begin_layout Description
17396 \begin_inset Flex Code
17399 \begin_layout Plain Layout
17406 \begin_inset Flex Code
17409 \begin_layout Plain Layout
17415 ] The tag to be used for the main label, replacing
17416 \begin_inset Flex Code
17419 \begin_layout Plain Layout
17425 in the examples above.
17427 \begin_inset Flex Code
17430 \begin_layout Plain Layout
17439 \begin_layout Description
17440 \begin_inset Flex Code
17443 \begin_layout Plain Layout
17450 \begin_inset Flex Code
17453 \begin_layout Plain Layout
17463 ] Marks this style as the one to be used to generate the
17464 \begin_inset Flex Code
17467 \begin_layout Plain Layout
17473 tag for the XHTML file.
17474 By default, it is false.
17476 \begin_inset Flex Code
17479 \begin_layout Plain Layout
17485 file sets it to true for the
17486 \begin_inset Flex Code
17489 \begin_layout Plain Layout
17499 \begin_layout Subsection
17503 \begin_layout Standard
17504 The XHTML output of insets can also be controlled by information in layout
17509 \begin_layout Plain Layout
17510 At present, this is true only for
17511 \begin_inset Quotes eld
17515 \begin_inset Quotes erd
17518 insets (insets you can type into) and is not true for
17519 \begin_inset Quotes eld
17523 \begin_inset Quotes erd
17526 insets (insets that are associated with dialog boxes).
17531 Here, too, LyX tries to provide sensible defaults, and it constructs default
17533 But everything can be customized.
17536 \begin_layout Standard
17537 The XHTML LyX outputs for an inset has the following form:
17540 \begin_layout LyX-Code
17542 \begin_inset Quotes erd
17546 \begin_inset Quotes erd
17552 \begin_layout LyX-Code
17553 <labeltag>Label</labeltag>
17556 \begin_layout LyX-Code
17558 \begin_inset Quotes erd
17562 \begin_inset Quotes erd
17565 >Contents of the inset.</innertag>
17568 \begin_layout LyX-Code
17572 \begin_layout Standard
17573 If the inset permits multiple paragraphs---that is, if
17574 \begin_inset Flex Code
17577 \begin_layout Plain Layout
17583 is true---then the contents of the inset will itself be output as paragraphs
17584 formatted according to the styles used for those paragraphs (standard,
17585 quote, and the like).
17586 The label tag is of course omitted if the paragraph does not have a label
17587 and, at present, is always
17588 \begin_inset Flex Code
17591 \begin_layout Plain Layout
17598 The inner tag is optional and, by default, does not appear.
17601 \begin_layout Standard
17602 The specific tags and attributes output for each inset can be controlled
17603 by means of the following layout tags.
17606 \begin_layout Description
17607 \begin_inset Flex Code
17610 \begin_layout Plain Layout
17617 \begin_inset Flex Code
17620 \begin_layout Plain Layout
17626 ] Specifies attribute information to be output with the main tag.
17628 \begin_inset Quotes eld
17632 \begin_inset Flex Code
17635 \begin_layout Plain Layout
17636 class=`myinset' onclick=`\SpecialChar \ldots{}
17643 \begin_inset Quotes erd
17647 By default, LyX will output
17648 \begin_inset Quotes eld
17652 \begin_inset Flex Code
17655 \begin_layout Plain Layout
17662 \begin_inset Quotes erd
17666 \begin_inset Flex Code
17669 \begin_layout Plain Layout
17675 is the LyX name of the inset, made lowercase and with non-alphanumeric
17676 characters converted to underscores, for example: footnote.
17679 \begin_layout Description
17680 \begin_inset Flex Code
17683 \begin_layout Plain Layout
17690 \begin_inset Flex Code
17693 \begin_layout Plain Layout
17703 ] Whether to output the default CSS information LyX generates for this layout,
17704 even if additional information is explicitly provided via
17705 \begin_inset Flex Code
17708 \begin_layout Plain Layout
17716 \begin_inset Flex Code
17719 \begin_layout Plain Layout
17725 allows you to alter or augment the generated CSS, rather than to override
17730 \begin_layout Description
17731 \begin_inset Flex Code
17734 \begin_layout Plain Layout
17741 \begin_inset Flex Code
17744 \begin_layout Plain Layout
17750 ] Attributes for the inner tag.
17752 \begin_inset Quotes eld
17756 \begin_inset Flex Code
17759 \begin_layout Plain Layout
17760 class=`insetname_inner'
17766 \begin_inset Quotes erd
17772 \begin_layout Description
17773 \begin_inset Flex Code
17776 \begin_layout Plain Layout
17783 \begin_inset Flex Code
17786 \begin_layout Plain Layout
17792 ] The inner tag, replacing
17793 \begin_inset Flex Code
17796 \begin_layout Plain Layout
17802 in the examples above.
17803 By default, there is none.
17806 \begin_layout Description
17807 \begin_inset Flex Code
17810 \begin_layout Plain Layout
17817 \begin_inset Flex Code
17820 \begin_layout Plain Layout
17828 ] Whether this inset represents a standalone block of text (such as a footnote)
17829 or instead represents material that is included in the surrounding text
17830 (such as a branch).
17834 \begin_layout Description
17835 \begin_inset Flex Code
17838 \begin_layout Plain Layout
17845 \begin_inset Flex Code
17848 \begin_layout Plain Layout
17854 ] A label for this inset, possibly including a reference to a counter.
17855 For example, for footnote, it might be:
17856 \begin_inset Flex Code
17859 \begin_layout Plain Layout
17868 This is optional, and there is no default.
17871 \begin_layout Description
17872 \begin_inset Flex Code
17875 \begin_layout Plain Layout
17881 Information to be output in the
17882 \begin_inset Flex Code
17885 \begin_layout Plain Layout
17891 section when this style is used.
17892 This might, for example, be used to include a
17893 \begin_inset Flex Code
17896 \begin_layout Plain Layout
17903 \begin_inset Flex Code
17906 \begin_layout Plain Layout
17915 \begin_layout Description
17916 \begin_inset Flex Code
17919 \begin_layout Plain Layout
17925 CSS style information to be included when this style is used.
17926 Note that this will automatically be wrapped in a layout-generated
17927 \begin_inset Flex Code
17930 \begin_layout Plain Layout
17936 block, so only the CSS itself need be included.
17939 \begin_layout Description
17940 \begin_inset Flex Code
17943 \begin_layout Plain Layout
17950 \begin_inset Flex Code
17953 \begin_layout Plain Layout
17959 ] The tag to be used for the main label, replacing
17960 \begin_inset Flex Code
17963 \begin_layout Plain Layout
17969 in the examples above.
17970 The default depends upon the setting of
17971 \begin_inset Flex Code
17974 \begin_layout Plain Layout
17981 \begin_inset Flex Code
17984 \begin_layout Plain Layout
17990 is true, the default is
17991 \begin_inset Flex Code
17994 \begin_layout Plain Layout
18000 ; if it is false, the default is
18001 \begin_inset Flex Code
18004 \begin_layout Plain Layout
18013 \begin_layout Subsection
18017 \begin_layout Standard
18018 The XHTML output for floats too can be controlled by layout information.
18019 The output has the following form:
18022 \begin_layout LyX-Code
18024 \begin_inset Quotes erd
18028 \begin_inset Quotes erd
18034 \begin_layout LyX-Code
18035 Contents of the float.
18038 \begin_layout LyX-Code
18042 \begin_layout Standard
18043 The caption, if there is one, is a separate inset and will be output as
18045 Its appearance can be controlled via the InsetLayout for caption insets.
18049 \begin_layout Description
18050 \begin_inset Flex Code
18053 \begin_layout Plain Layout
18060 \begin_inset Flex Code
18063 \begin_layout Plain Layout
18069 ] Specifies attribute information to be output with the main tag.
18071 \begin_inset Quotes eld
18075 \begin_inset Flex Code
18078 \begin_layout Plain Layout
18079 class=`myfloat' onclick=`\SpecialChar \ldots{}
18086 \begin_inset Quotes erd
18090 By default, LyX will output
18091 \begin_inset Quotes eld
18095 \begin_inset Flex Code
18098 \begin_layout Plain Layout
18099 class=`float float-floattype'
18105 \begin_inset Quotes erd
18109 \begin_inset Flex Code
18112 \begin_layout Plain Layout
18118 is LyX's name for this type of float, as determined by the float delcaration
18120 \begin_inset CommandInset ref
18122 reference "sub:Floats"
18126 ), though made lowercase and with non-alphanumeric characters converted
18127 to underscores, for example: float-table.
18130 \begin_layout Description
18131 \begin_inset Flex Code
18134 \begin_layout Plain Layout
18140 CSS style information to be included when this float is used.
18141 Note that this will automatically be wrapped in a layout-generated
18142 \begin_inset Flex Code
18145 \begin_layout Plain Layout
18151 block, so only the CSS itself need be included.
18154 \begin_layout Description
18155 \begin_inset Flex Code
18158 \begin_layout Plain Layout
18165 \begin_inset Flex Code
18168 \begin_layout Plain Layout
18174 ] The tag to be used for this float, replacing
18175 \begin_inset Quotes eld
18179 \begin_inset Flex Code
18182 \begin_layout Plain Layout
18189 \begin_inset Quotes erd
18192 in the example above.
18194 \begin_inset Flex Code
18197 \begin_layout Plain Layout
18203 and will rarely need changing.
18206 \begin_layout Subsection
18207 Bibliography formatting
18210 \begin_layout Standard
18211 The bibliography can be formatted using
18212 \begin_inset Flex Code
18215 \begin_layout Plain Layout
18223 \begin_inset CommandInset ref
18225 reference "sub:Citation-format-description"
18232 \begin_layout Subsection
18236 \begin_layout Standard
18237 We have several times mentioned that LyX will generate default CSS style
18238 rules for both insets and paragraph styles, based upon the other layout
18239 information that is provided.
18240 In this section, we shall say a word about which layout information LyX
18244 \begin_layout Standard
18245 At present, LyX auto-generates CSS only for font information, making use
18247 \begin_inset Flex Code
18250 \begin_layout Plain Layout
18257 \begin_inset Flex Code
18260 \begin_layout Plain Layout
18267 \begin_inset Flex Code
18270 \begin_layout Plain Layout
18277 \begin_inset Flex Code
18280 \begin_layout Plain Layout
18287 \begin_inset Flex Code
18290 \begin_layout Plain Layout
18298 \begin_inset CommandInset ref
18300 reference "sub:Font-description"
18304 .) The translation is mostly straightforward and obvious.
18306 \begin_inset Quotes eld
18310 \begin_inset Flex Code
18313 \begin_layout Plain Layout
18320 \begin_inset Quotes erd
18324 \begin_inset Quotes eld
18328 \begin_inset Flex Code
18331 \begin_layout Plain Layout
18332 font-family: sans-serif;
18338 \begin_inset Quotes erd
18342 The correspondence of LyX sizes and CSS sizes is a little less obvious
18343 but nonetheless intuitive.
18345 \begin_inset Flex Code
18348 \begin_layout Plain Layout
18355 \begin_inset Flex URL
18358 \begin_layout Plain Layout
18369 \begin_layout Chapter
18370 Including External Material
18373 \begin_layout Standard
18374 \begin_inset Box Shadowbox
18384 height_special "totalheight"
18387 \begin_layout Plain Layout
18388 WARNING: This portion of the documentation has not been updated for some
18390 We certainly hope that it is still accurate, but there are no guarantees.
18398 \begin_layout Standard
18399 The use of material from sources external to LyX is covered in detail in
18405 This part of the manual covers what needs to happen behind the scenes for
18406 new sorts of material to be included.
18409 \begin_layout Section
18413 \begin_layout Standard
18414 The external material feature is based on the concept of a
18419 A template is a specification of how LyX should interface with a certain
18421 As bundled, LyX comes with predefined templates for Xfig figures, various
18422 raster format images, chess diagrams, and LilyPond music notation.
18423 You can check the actual list by using the menu
18424 \begin_inset Flex MenuItem
18427 \begin_layout Plain Layout
18428 Insert\SpecialChar \menuseparator
18429 File\SpecialChar \menuseparator
18436 Furthermore, it is possible to roll your own template to support a specific
18438 Later we'll describe in more detail what is involved, and hopefully you
18439 will submit all the templates you create so we can include them in a later
18443 \begin_layout Standard
18444 Another basic idea of the external material feature is to distinguish between
18445 the original file that serves as a base for final material and the produced
18446 file that is included in your exported or printed document.
18447 For example, consider the case of a figure produced with
18448 \begin_inset Flex Code
18451 \begin_layout Plain Layout
18458 The Xfig application itself works on an original file with the
18459 \begin_inset Flex Code
18462 \begin_layout Plain Layout
18469 Within Xfig, you create and change your figure, and when you are done,
18471 \begin_inset Flex Code
18474 \begin_layout Plain Layout
18481 When you want to include the figure in your document, you invoke
18482 \begin_inset Flex Code
18485 \begin_layout Plain Layout
18491 in order to create a PostScript file that can readily be included in your
18494 \begin_inset Flex Code
18497 \begin_layout Plain Layout
18503 file is the original file, and the PostScript file is the produced file.
18506 \begin_layout Standard
18507 This distinction is important in order to allow updating of the material
18508 while you are in the process of writing the document.
18509 Furthermore, it provides us with the flexibility that is needed to support
18510 multiple export formats.
18511 For instance, in the case of a plain text file, it is not exactly an award-winn
18512 ing idea to include the figure as raw PostScript.
18513 Instead, you'd either prefer to just include a reference to the figure
18514 or try to invoke some graphics to ASCII converter to make the final result
18515 look similar to the real graphics.
18516 The external material management allows you to do this, because it is parametri
18517 zed on the different export formats that LyX supports.
18520 \begin_layout Standard
18521 Besides supporting the production of different products according to the
18522 exported format, it supports tight integration with editing and viewing
18524 In the case of an Xfig figure, you are able to invoke Xfig on the original
18525 file with a single click from within the external material dialog in LyX,
18526 and also preview the produced PostScript file with Ghostview with another
18528 No more fiddling around with the command line and/or file browsers to locate
18529 and manipulate the original or produced files.
18530 In this way, you are finally able to take full advantage of the many different
18531 applications that are relevant to use when you write your documents, and
18532 ultimately be more productive.
18535 \begin_layout Section
18536 The external template configuration file
18539 \begin_layout Standard
18540 It is relatively easy to add custom external template definitions to LyX.
18541 However, be aware that doing this in an careless manner most probably
18545 introduce an easily exploitable security hole.
18546 So before you do this, please read the discussion about security in section
18548 \begin_inset CommandInset ref
18550 reference "sec:Security-discussion"
18557 \begin_layout Standard
18558 Having said that, we encourage you to submit any interesting templates that
18563 \begin_layout Standard
18564 The external templates are defined in the
18565 \begin_inset Flex Code
18568 \begin_layout Plain Layout
18569 LyXDir/lib/external_templates
18575 You can place your own version in
18576 \begin_inset Flex Code
18579 \begin_layout Plain Layout
18580 UserDir/external_templates
18588 \begin_layout Standard
18589 A typical template looks like this:
18592 \begin_layout LyX-Code
18596 \begin_layout LyX-Code
18597 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
18600 \begin_layout LyX-Code
18604 \begin_layout LyX-Code
18608 \begin_layout LyX-Code
18612 \begin_layout LyX-Code
18616 \begin_layout LyX-Code
18620 \begin_layout LyX-Code
18621 AutomaticProduction true
18624 \begin_layout LyX-Code
18628 \begin_layout LyX-Code
18632 \begin_layout LyX-Code
18636 \begin_layout LyX-Code
18637 TransformCommand Rotate RotationLatexCommand
18640 \begin_layout LyX-Code
18641 TransformCommand Resize ResizeLatexCommand
18644 \begin_layout LyX-Code
18645 Product "$$RotateFront$$ResizeFront
18648 \begin_layout LyX-Code
18653 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
18656 \begin_layout LyX-Code
18657 $$ResizeBack$$RotateBack"
18660 \begin_layout LyX-Code
18664 \begin_layout LyX-Code
18665 UpdateResult "$$AbsPath$$Basename.pstex_t"
18668 \begin_layout LyX-Code
18669 Requirement "graphicx"
18672 \begin_layout LyX-Code
18673 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
18676 \begin_layout LyX-Code
18677 ReferencedFile latex "$$AbsPath$$Basename.eps"
18680 \begin_layout LyX-Code
18681 ReferencedFile dvi "$$AbsPath$$Basename.eps"
18684 \begin_layout LyX-Code
18688 \begin_layout LyX-Code
18692 \begin_layout LyX-Code
18693 TransformCommand Rotate RotationLatexCommand
18696 \begin_layout LyX-Code
18697 TransformCommand Resize ResizeLatexCommand
18700 \begin_layout LyX-Code
18701 Product "$$RotateFront$$ResizeFront
18704 \begin_layout LyX-Code
18709 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
18712 \begin_layout LyX-Code
18713 $$ResizeBack$$RotateBack"
18716 \begin_layout LyX-Code
18717 UpdateFormat pdftex
18720 \begin_layout LyX-Code
18721 UpdateResult "$$AbsPath$$Basename.pdftex_t"
18724 \begin_layout LyX-Code
18725 Requirement "graphicx"
18728 \begin_layout LyX-Code
18729 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
18732 \begin_layout LyX-Code
18733 ReferencedFile latex "$$AbsPath$$Basename.pdf"
18736 \begin_layout LyX-Code
18740 \begin_layout LyX-Code
18744 \begin_layout LyX-Code
18745 Product "$$Contents(
18747 "$$AbsPath$$Basename.asc
18752 \begin_layout LyX-Code
18753 UpdateFormat asciixfig
18756 \begin_layout LyX-Code
18757 UpdateResult "$$AbsPath$$Basename.asc"
18760 \begin_layout LyX-Code
18764 \begin_layout LyX-Code
18768 \begin_layout LyX-Code
18769 Product "<graphic fileref=
18771 "$$AbsOrRelPathMaster$$Basename.eps
18776 \begin_layout LyX-Code
18780 \begin_layout LyX-Code
18784 \begin_layout LyX-Code
18785 UpdateResult "$$AbsPath$$Basename.eps"
18788 \begin_layout LyX-Code
18789 ReferencedFile docbook "$$AbsPath$$Basename.eps"
18792 \begin_layout LyX-Code
18793 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
18796 \begin_layout LyX-Code
18800 \begin_layout LyX-Code
18801 Product "[XFig: $$FName]"
18804 \begin_layout LyX-Code
18808 \begin_layout LyX-Code
18812 \begin_layout Standard
18813 As you can see, the template is enclosed in
18814 \begin_inset Flex Code
18817 \begin_layout Plain Layout
18823 \SpecialChar \ldots{}
18825 \begin_inset Flex Code
18828 \begin_layout Plain Layout
18835 It contains a header specifying some general settings and, for each supported
18836 primary document file format, a section
18837 \begin_inset Flex Code
18840 \begin_layout Plain Layout
18846 \SpecialChar \ldots{}
18848 \begin_inset Flex Code
18851 \begin_layout Plain Layout
18860 \begin_layout Subsection
18861 The template header
18864 \begin_layout Description
18865 \begin_inset Flex Code
18868 \begin_layout Plain Layout
18869 AutomaticProduction
18870 \begin_inset space ~
18878 Whether the file represented by the template must be generated by LyX.
18879 This command must occur exactly once.
18882 \begin_layout Description
18883 \begin_inset Flex Code
18886 \begin_layout Plain Layout
18888 \begin_inset space ~
18896 A glob pattern that is used in the file dialog to filter out the desired
18898 If there is more than one possible file extension (e.
18899 \begin_inset space \thinspace{}
18903 \begin_inset space \space{}
18907 \begin_inset Flex Code
18910 \begin_layout Plain Layout
18917 \begin_inset Flex Code
18920 \begin_layout Plain Layout
18926 ), use something like
18927 \begin_inset Flex Code
18930 \begin_layout Plain Layout
18937 This command must occur exactly once.
18940 \begin_layout Description
18941 \begin_inset Flex Code
18944 \begin_layout Plain Layout
18946 \begin_inset space ~
18954 The text that is displayed on the button.
18955 This command must occur exactly once.
18958 \begin_layout Description
18959 \begin_inset Flex Code
18962 \begin_layout Plain Layout
18964 \begin_inset space ~
18968 \begin_inset space ~
18976 The help text that is used in the External dialog.
18977 Provide enough information to explain to the user just what the template
18978 can provide him with.
18979 This command must occur exactly once.
18982 \begin_layout Description
18983 \begin_inset Flex Code
18986 \begin_layout Plain Layout
18988 \begin_inset space ~
18996 The file format of the original file.
18997 This must be the name of a format that is known to LyX (see section
18998 \begin_inset CommandInset ref
19000 reference "sec:Formats"
19006 \begin_inset Quotes eld
19010 \begin_inset Flex Code
19013 \begin_layout Plain Layout
19020 \begin_inset Quotes erd
19023 if the template can handle original files of more than one format.
19024 LyX will attempt to interrogate the file itself in order to deduce its
19025 format in this case.
19026 This command must occur exactly once.
19029 \begin_layout Description
19030 \begin_inset Flex Code
19033 \begin_layout Plain Layout
19035 \begin_inset space ~
19043 A unique name for the template.
19044 It must not contain substitution macros (see below).
19047 \begin_layout Description
19048 \begin_inset Flex Code
19051 \begin_layout Plain Layout
19053 \begin_inset space ~
19056 Rotate|Resize|Clip|Extra
19061 This command specifies which transformations are supported by this template.
19062 It may occur zero or more times.
19063 This command enables the corresponding tabs in the external dialog.
19065 \begin_inset Flex Code
19068 \begin_layout Plain Layout
19074 command must have either a corresponding
19075 \begin_inset Flex Code
19078 \begin_layout Plain Layout
19085 \begin_inset Flex Code
19088 \begin_layout Plain Layout
19095 \begin_inset Flex Code
19098 \begin_layout Plain Layout
19105 Otherwise the transformation will not be supported by that format.
19108 \begin_layout Subsection
19112 \begin_layout Description
19113 \begin_inset Flex Code
19116 \begin_layout Plain Layout
19118 \begin_inset space ~
19121 LaTeX|PDFLaTeX|PlainText|DocBook
19126 The primary document file format that this format definition is for.
19127 Not every template has a sensible representation in all document file formats.
19128 Please define nevertheless a
19129 \begin_inset Flex Code
19132 \begin_layout Plain Layout
19138 section for all formats.
19139 Use a dummy text when no representation is available.
19140 Then you can at least see a reference to the external material in the exported
19144 \begin_layout Description
19145 \begin_inset Flex Code
19148 \begin_layout Plain Layout
19150 \begin_inset space ~
19154 \begin_inset space ~
19162 This command defines an additional macro
19163 \begin_inset Flex Code
19166 \begin_layout Plain Layout
19172 for substitution in
19173 \begin_inset Flex Code
19176 \begin_layout Plain Layout
19184 \begin_inset Flex Code
19187 \begin_layout Plain Layout
19193 itself may contain substitution macros.
19194 The advantage over using
19195 \begin_inset Flex Code
19198 \begin_layout Plain Layout
19205 \begin_inset Flex Code
19208 \begin_layout Plain Layout
19214 is that the substituted value of
19215 \begin_inset Flex Code
19218 \begin_layout Plain Layout
19224 is sanitized so that it is a valid optional argument in the document format.
19225 This command may occur zero or more times.
19228 \begin_layout Description
19229 \begin_inset Flex Code
19232 \begin_layout Plain Layout
19234 \begin_inset space ~
19242 The text that is inserted in the exported document.
19243 This is actually the most important command and can be quite complex.
19244 This command must occur exactly once.
19247 \begin_layout Description
19248 \begin_inset Flex Code
19251 \begin_layout Plain Layout
19253 \begin_inset space ~
19261 This command specifies a preamble snippet that will be included in the
19263 It has to be defined using
19264 \begin_inset Flex Code
19267 \begin_layout Plain Layout
19273 \SpecialChar \ldots{}
19275 \begin_inset Flex Code
19278 \begin_layout Plain Layout
19285 This command may occur zero or more times.
19288 \begin_layout Description
19289 \begin_inset Flex Code
19292 \begin_layout Plain Layout
19294 \begin_inset space ~
19298 \begin_inset space ~
19306 This command denotes files that are created by the conversion process and
19307 are needed for a particular export format.
19308 If the filename is relative, it is interpreted relative to the master document.
19309 This command may be given zero or more times.
19312 \begin_layout Description
19313 \begin_inset Flex Code
19316 \begin_layout Plain Layout
19318 \begin_inset space ~
19326 The name of a required LaTeX package.
19327 The package is included via
19328 \begin_inset Flex Code
19331 \begin_layout Plain Layout
19339 in the LaTeX preamble.
19340 This command may occur zero or more times.
19343 \begin_layout Description
19344 \begin_inset Flex Code
19347 \begin_layout Plain Layout
19349 \begin_inset space ~
19353 \begin_inset space ~
19356 RotationLatexCommand
19361 This command specifies that the built in LaTeX command should be used for
19363 This command may occur once or not at all.
19366 \begin_layout Description
19367 \begin_inset Flex Code
19370 \begin_layout Plain Layout
19372 \begin_inset space ~
19376 \begin_inset space ~
19384 This command specifies that the built in LaTeX command should be used for
19386 This command may occur once or not at all.
19389 \begin_layout Description
19390 \begin_inset Flex Code
19393 \begin_layout Plain Layout
19395 \begin_inset space ~
19399 \begin_inset space ~
19402 RotationLatexOption
19407 This command specifies that rotation is done via an optional argument.
19408 This command may occur once or not at all.
19411 \begin_layout Description
19412 \begin_inset Flex Code
19415 \begin_layout Plain Layout
19417 \begin_inset space ~
19421 \begin_inset space ~
19429 This command specifies that resizing is done via an optional argument.
19430 This command may occur once or not at all.
19433 \begin_layout Description
19434 \begin_inset Flex Code
19437 \begin_layout Plain Layout
19439 \begin_inset space ~
19443 \begin_inset space ~
19451 This command specifies that clipping is done via an optional argument.
19452 This command may occur once or not at all.
19455 \begin_layout Description
19456 \begin_inset Flex Code
19459 \begin_layout Plain Layout
19461 \begin_inset space ~
19465 \begin_inset space ~
19473 This command specifies that an extra optional argument is used.
19474 This command may occur once or not at all.
19477 \begin_layout Description
19478 \begin_inset Flex Code
19481 \begin_layout Plain Layout
19483 \begin_inset space ~
19491 The file format of the converted file.
19492 This must be the name of a format that is known to LyX (see the
19493 \begin_inset Flex MenuItem
19496 \begin_layout Plain Layout
19501 ools\SpecialChar \menuseparator
19506 references:Conversion
19512 This command must occur exactly once.
19515 \begin_layout Description
19516 \begin_inset Flex Code
19519 \begin_layout Plain Layout
19521 \begin_inset space ~
19529 The file name of the converted file.
19530 The file name must be absolute.
19531 This command must occur exactly once.
19534 \begin_layout Subsection
19535 Preamble definitions
19538 \begin_layout Standard
19539 The external template configuration file may contain additional preamble
19540 definitions enclosed by
19541 \begin_inset Flex Code
19544 \begin_layout Plain Layout
19550 \SpecialChar \ldots{}
19552 \begin_inset Flex Code
19555 \begin_layout Plain Layout
19562 They can be used by the templates in the
19563 \begin_inset Flex Code
19566 \begin_layout Plain Layout
19575 \begin_layout Section
19576 The substitution mechanism
19579 \begin_layout Standard
19580 When the external material facility invokes an external program, it is done
19581 on the basis of a command defined in the template configuration file.
19582 These commands can contain various macros that are expanded before execution.
19583 Execution always take place in the directory of the containing document.
19586 \begin_layout Standard
19587 Also, whenever external material is to be displayed, the name will be produced
19588 by the substitution mechanism, and most other commands in the template
19589 definition support substitution as well.
19592 \begin_layout Standard
19593 The available macros are the following:
19596 \begin_layout Description
19597 \begin_inset Flex Code
19600 \begin_layout Plain Layout
19601 $$AbsOrRelPathMaster
19606 The file path, absolute or relative to the master LyX document.
19609 \begin_layout Description
19610 \begin_inset Flex Code
19613 \begin_layout Plain Layout
19614 $$AbsOrRelPathParent
19619 The file path, absolute or relative to the LyX document.
19622 \begin_layout Description
19623 \begin_inset Flex Code
19626 \begin_layout Plain Layout
19632 The absolute file path.
19635 \begin_layout Description
19636 \begin_inset Flex Code
19639 \begin_layout Plain Layout
19645 The filename without path and without the extension.
19648 \begin_layout Description
19649 \begin_inset Flex Code
19652 \begin_layout Plain Layout
19654 \begin_inset Quotes eld
19658 \begin_inset Quotes erd
19666 This macro will expand to the contents of the file with the name
19667 \begin_inset Flex Code
19670 \begin_layout Plain Layout
19679 \begin_layout Description
19680 \begin_inset Flex Code
19683 \begin_layout Plain Layout
19689 The file extension (including the dot).
19692 \begin_layout Description
19693 \begin_inset Flex Code
19696 \begin_layout Plain Layout
19702 The filename of the file specified in the external material dialog.
19703 This is either an absolute name, or it is relative to the LyX document.
19706 \begin_layout Description
19707 \begin_inset Flex Code
19710 \begin_layout Plain Layout
19717 \begin_inset Flex Code
19720 \begin_layout Plain Layout
19726 (absolute name or relative to the LyX document).
19729 \begin_layout Description
19730 \begin_inset Flex Code
19733 \begin_layout Plain Layout
19739 The file path, relative to the master LyX document.
19742 \begin_layout Description
19743 \begin_inset Flex Code
19746 \begin_layout Plain Layout
19752 The file path, relative to the LyX document.
19755 \begin_layout Description
19756 \begin_inset Flex Code
19759 \begin_layout Plain Layout
19765 This macro will expand to the absolute path of the system directory.
19766 This is typically used to point to the various helper scripts that are
19770 \begin_layout Description
19771 \begin_inset Flex Code
19774 \begin_layout Plain Layout
19780 A name and full path to a temporary file which will be automatically deleted
19781 whenever the containing document is closed, or the external material insertion
19785 \begin_layout Standard
19786 All path macros contain a trailing directory separator, so you can construct
19788 \begin_inset space \thinspace{}
19792 \begin_inset space \space{}
19795 the absolute filename with
19796 \begin_inset Flex Code
19799 \begin_layout Plain Layout
19800 $$AbsPath$$Basename$$Extension
19808 \begin_layout Standard
19809 The macros above are substituted in all commands unless otherwise noted.
19811 \begin_inset Flex Code
19814 \begin_layout Plain Layout
19820 supports additionally the following substitutions if they are enabled by
19822 \begin_inset Flex Code
19825 \begin_layout Plain Layout
19832 \begin_inset Flex Code
19835 \begin_layout Plain Layout
19844 \begin_layout Description
19845 \begin_inset Flex Code
19848 \begin_layout Plain Layout
19854 The front part of the resize command.
19857 \begin_layout Description
19858 \begin_inset Flex Code
19861 \begin_layout Plain Layout
19867 The back part of the resize command.
19870 \begin_layout Description
19871 \begin_inset Flex Code
19874 \begin_layout Plain Layout
19880 The front part of the rotation command.
19883 \begin_layout Description
19884 \begin_inset Flex Code
19887 \begin_layout Plain Layout
19893 The back part of the rotation command.
19896 \begin_layout Standard
19897 The value string of the
19898 \begin_inset Flex Code
19901 \begin_layout Plain Layout
19907 command supports additionally the following substitutions if they are enabled
19909 \begin_inset Flex Code
19912 \begin_layout Plain Layout
19919 \begin_inset Flex Code
19922 \begin_layout Plain Layout
19931 \begin_layout Description
19932 \begin_inset Flex Code
19935 \begin_layout Plain Layout
19944 \begin_layout Description
19945 \begin_inset Flex Code
19948 \begin_layout Plain Layout
19957 \begin_layout Description
19958 \begin_inset Flex Code
19961 \begin_layout Plain Layout
19970 \begin_layout Description
19971 \begin_inset Flex Code
19974 \begin_layout Plain Layout
19980 The rotation option.
19983 \begin_layout Standard
19984 You may ask why there are so many path macros.
19985 There are mainly two reasons:
19988 \begin_layout Enumerate
19989 Relative and absolute file names should remain relative or absolute, respectivel
19991 Users may have reasons to prefer either form.
19992 Relative names are useful for portable documents that should work on different
19993 machines, for example.
19994 Absolute names may be required by some programs.
19997 \begin_layout Enumerate
19998 LaTeX treats relative file names differently than LyX and other programs
19999 in nested included files.
20000 For LyX, a relative file name is always relative to the document that contains
20002 For LaTeX, it is always relative to the master document.
20003 These two definitions are identical if you have only one document, but
20004 differ if you have a master document that includes part documents.
20005 That means that relative filenames must be transformed when presented to
20007 Fortunately LyX does this automatically for you if you choose the right
20011 \begin_layout Standard
20012 So which path macro should be used in new template definitions? The rule
20016 \begin_layout Itemize
20018 \begin_inset Flex Code
20021 \begin_layout Plain Layout
20027 if an absolute path is required.
20030 \begin_layout Itemize
20032 \begin_inset Flex Code
20035 \begin_layout Plain Layout
20036 $$AbsOrRelPathMaster
20041 if the substituted string is some kind of LaTeX input.
20044 \begin_layout Itemize
20046 \begin_inset Flex Code
20049 \begin_layout Plain Layout
20050 $$AbsOrRelPathParent
20055 in order to preserve the user's choice.
20058 \begin_layout Standard
20059 There are special cases where this rule does not work and e.
20060 \begin_inset space \thinspace{}
20064 \begin_inset space \space{}
20067 relative names are needed, but normally it will work just fine.
20068 One example for such a case is the command
20069 \begin_inset Flex Code
20072 \begin_layout Plain Layout
20073 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
20078 in the XFig template above: We can't use the absolute name because the
20080 \begin_inset Flex Code
20083 \begin_layout Plain Layout
20089 files needs the relative name in order to rewrite the file content.
20092 \begin_layout Section
20093 Security discussion
20094 \begin_inset CommandInset label
20096 name "sec:Security-discussion"
20103 \begin_layout Standard
20104 The external material feature interfaces with a lot of external programs
20105 and does so automatically, so we have to consider the security implications
20107 In particular, since you have the option of including your own filenames
20108 and/or parameter strings and those are expanded into a command, it seems
20109 that it would be possible to create a malicious document which executes
20110 arbitrary commands when a user views or prints the document.
20111 This is something we definitely want to avoid.
20114 \begin_layout Standard
20115 However, since the external program commands are specified in the template
20116 configuration file only, there are no security issues if LyX is properly
20117 configured with safe templates only.
20118 This is so because the external programs are invoked with the
20119 \begin_inset Flex Code
20122 \begin_layout Plain Layout
20128 -system call rather than the
20129 \begin_inset Flex Code
20132 \begin_layout Plain Layout
20138 system-call, so it's not possible to execute arbitrary commands from the
20139 filename or parameter section via the shell.
20142 \begin_layout Standard
20143 This also implies that you are restricted in what command strings you can
20144 use in the external material templates.
20145 In particular, pipes and redirection are not readily available.
20146 This has to be so if LyX should remain safe.
20147 If you want to use some of the shell features, you should write a safe
20148 script to do this in a controlled manner, and then invoke the script from
20149 the command string.
20153 \begin_layout Standard
20154 It is possible to design a template that interacts directly with the shell,
20155 but since this would allow a malicious user to execute arbitrary commands
20156 by writing clever filenames and/or parameters, we generally recommend that
20157 you only use safe scripts that work with the
20158 \begin_inset Flex Code
20161 \begin_layout Plain Layout
20167 system call in a controlled manner.
20168 Of course, for use in a controlled environment, it can be tempting to just
20169 fall back to use ordinary shell scripts.
20170 If you do so, be aware that you
20174 provide an easily exploitable security hole in your system.
20175 Of course it stands to reason that such unsafe templates will never be
20176 included in the standard LyX distribution, although we do encourage people
20177 to submit new templates in the open source tradition.
20178 But LyX as shipped from the official distribution channels will never have
20182 \begin_layout Standard
20183 Including external material provides a lot of power, and you have to be
20184 careful not to introduce security hazards with this power.
20185 A subtle error in a single line in an innocent looking script can open
20186 the door to huge security problems.
20187 So if you do not fully understand the issues, we recommend that you consult
20188 a knowledgeable security professional or the LyX development team if you
20189 have any questions about whether a given template is safe or not.
20190 And do this before you use it in an uncontrolled environment.