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
129 \paragraph_separation indent
130 \paragraph_indentation default
131 \quotes_language english
134 \paperpagestyle headings
135 \tracking_changes false
136 \output_changes false
144 Customizing LyX: Features for the Advanced User
152 \begin_layout Plain Layout
154 If you have comments or error corrections, please send them to the LyX Documenta
156 \begin_inset CommandInset href
158 target "lyx-docs@lists.lyx.org"
165 \begin_inset Quotes eld
169 \begin_inset Quotes erd
172 in the subject header, and please cc the current maintainer of this file,
173 Richard Heck <rgheck@comcast.net>.
179 \begin_inset Newline newline
183 \begin_inset Newline newline
189 \begin_layout Standard
190 \begin_inset CommandInset toc
191 LatexCommand tableofcontents
198 \begin_layout Standard
199 \begin_inset Note Note
202 \begin_layout Plain Layout
203 Please use change tracking when modifying this document.
204 This makes it easier for our translators to recognize things that have
205 been changed, and it helps the maintainer keep up-to-date with what's been
214 \begin_layout Chapter
218 \begin_layout Standard
219 This manual covers the customization features present in LyX.
220 In it, we discuss issues like keyboard shortcuts, screen previewing options,
221 printer options, sending commands to LyX via the LyX Server, internationalizati
222 on, installing new LaTeX classes and LyX layouts, etc.
223 We can't possibly hope to touch on everything you can change—our developers
224 add new features faster than we can document them—but we will explain the
225 most common customizations and hopefully point you in the right direction
226 for some of the more obscure ones.
229 \begin_layout Standard
230 \begin_inset Branch OutDated
233 \begin_layout Standard
234 Information from previous versions of this document that now seems to be
235 outdated is contained in the OutDated branch of this document.
236 By default, this information will not appear in the LaTeX output.
244 \begin_layout Chapter
245 LyX configuration files
248 \begin_layout Standard
249 This chapter aims to help you to find your way through the LyX configuration
251 Before continuing to read this chapter, you should find out where your
252 LyX library and user directories are by using
253 \begin_inset Flex MenuItem
256 \begin_layout Plain Layout
257 Help\SpecialChar \menuseparator
268 The library directory is the place where LyX places its system-wide configurati
269 on files; the user directory is where you can place your modified versions.
270 We will call the former
271 \begin_inset Flex Code
274 \begin_layout Plain Layout
281 \begin_inset Flex MenuItem
284 \begin_layout Plain Layout
290 in the remainder of this document.
294 \begin_layout Section
296 \begin_inset Flex Code
299 \begin_layout Plain Layout
308 \begin_layout Standard
309 \begin_inset Flex Code
312 \begin_layout Plain Layout
318 and its sub-directories contain a number of files and that can be used
319 to customize LyX's behavior.
320 You can change many of these files from within LyX itself through the
321 \begin_inset Flex MenuItem
324 \begin_layout Plain Layout
325 Tools\SpecialChar \menuseparator
332 Most customization that you will want to do in LyX is possible through
334 However, many other inner aspects of LyX can be customized by modifying
336 \begin_inset Flex Code
339 \begin_layout Plain Layout
346 These files fall in different categories, described in the following subsection
350 \begin_layout Subsection
351 Automatically generated files
354 \begin_layout Standard
355 The files, which are to be found in
356 \begin_inset Flex MenuItem
359 \begin_layout Plain Layout
365 , are generated when you configure LyX.
366 They contain various default values that are guessed by inspection.
367 In general, it is not a good idea to modify them, since they might be overwritt
371 \begin_layout Labeling
372 \labelwidthstring 00.00.0000
373 \begin_inset Flex Code
376 \begin_layout Plain Layout
382 contains defaults for various commands.
385 \begin_layout Labeling
386 \labelwidthstring 00.00.0000
387 \begin_inset Flex Code
390 \begin_layout Plain Layout
396 contains the list of packages that have been recognized by LyX.
397 It is currently unused by the LyX program itself, but the information extracted
398 , and more, is made available with
399 \begin_inset Flex MenuItem
402 \begin_layout Plain Layout
403 Help\SpecialChar \menuseparator
416 \begin_layout Labeling
417 \labelwidthstring 00.00.0000
418 \begin_inset Flex Code
421 \begin_layout Plain Layout
427 the list of text classes that have been found in your
428 \begin_inset Flex Code
431 \begin_layout Plain Layout
437 directories, along with the associated LaTeX document class and their descripti
441 \begin_layout Labeling
442 \labelwidthstring 00.00.0000
443 \begin_inset Flex Code
446 \begin_layout Plain Layout
452 the list of layout modules found in your
453 \begin_inset Flex Code
456 \begin_layout Plain Layout
465 \begin_layout Labeling
466 \labelwidthstring 00.00.0000
467 \begin_inset Flex Code
470 \begin_layout Plain Layout
476 lists of various sorts of LaTeX-related files found on your system
479 \begin_layout Labeling
480 \labelwidthstring 00.00.0000
481 \begin_inset Flex Code
484 \begin_layout Plain Layout
490 is automatically generated during configuration from the file
491 \begin_inset Flex Code
494 \begin_layout Plain Layout
501 It contains information on your LaTeX configuration.
504 \begin_layout Subsection
508 \begin_layout Standard
509 These directories are duplicated between
510 \begin_inset Flex Code
513 \begin_layout Plain Layout
520 \begin_inset Flex Code
523 \begin_layout Plain Layout
530 If a particular files exists in both places, the one in
531 \begin_inset Flex Code
534 \begin_layout Plain Layout
543 \begin_layout Labeling
544 \labelwidthstring 00.00.0000
545 \begin_inset Flex Code
548 \begin_layout Plain Layout
554 this directory contains files with the extension
555 \begin_inset Flex Code
558 \begin_layout Plain Layout
564 that define the keybindings used in LyX.
565 If there exists an internationalized version of the bind file named
566 \begin_inset Flex Code
569 \begin_layout Plain Layout
575 , that will be used first.
578 \begin_layout Labeling
579 \labelwidthstring 00.00.0000
580 \begin_inset Flex Code
583 \begin_layout Plain Layout
589 contains graphics files that can be included in documents.
593 \begin_layout Labeling
594 \labelwidthstring 00.00.0000
595 \begin_inset Flex Code
598 \begin_layout Plain Layout
604 contains LyX documentation files (including the one you are currently reading).
606 \begin_inset Flex Code
609 \begin_layout Plain Layout
615 deserves special attention, as noted above.
616 The internationalized help docs are in subdirectories
617 \begin_inset Flex Code
620 \begin_layout Plain Layout
627 \begin_inset Quotes eld
631 \begin_inset Quotes erd
634 is the ISO language code.
640 \begin_inset CommandInset ref
642 reference "cha:Internationalizing-LyX"
649 \begin_layout Labeling
650 \labelwidthstring 00.00.0000
651 \begin_inset Flex Code
654 \begin_layout Plain Layout
660 contains example files that explain how to use some features.
661 In the file browser, press the
662 \begin_inset Flex MenuItem
665 \begin_layout Plain Layout
674 \begin_layout Labeling
675 \labelwidthstring 00.00.0000
676 \begin_inset Flex Code
679 \begin_layout Plain Layout
685 contains image files that are used by the
686 \begin_inset Flex MenuItem
689 \begin_layout Plain Layout
696 In addition, it also contains the individual icons used in the toolbar
697 and the banners that can be shown when LyX is launched.
700 \begin_layout Labeling
701 \labelwidthstring 00.00.0000
702 \begin_inset Flex Code
705 \begin_layout Plain Layout
711 contains keyboard keymapping files.
717 \begin_inset CommandInset ref
719 reference "sec:International-Keymap-Stuff"
726 \begin_layout Labeling
727 \labelwidthstring 00.00.0000
728 \begin_inset Flex Code
731 \begin_layout Plain Layout
737 contains the text class and module files described in Chapter
742 \begin_inset CommandInset ref
744 reference "cha:Installing-New-Document"
751 \begin_layout Labeling
752 \labelwidthstring 00.00.0000
753 \begin_inset Flex Code
756 \begin_layout Plain Layout
763 \begin_inset Flex Code
766 \begin_layout Plain Layout
772 Python scripts used to convert between LyX versions.
773 These can be run from the command line if, say, you want to batch-convert
777 \begin_layout Labeling
778 \labelwidthstring 00.00.0000
779 \begin_inset Flex Code
782 \begin_layout Plain Layout
788 contains some files that demonstrate the capabilities of the
789 \begin_inset Flex MenuItem
792 \begin_layout Plain Layout
803 Also contains some scripts used by LyX itself.
806 \begin_layout Labeling
807 \labelwidthstring 00.00.0000
808 \begin_inset Flex Code
811 \begin_layout Plain Layout
817 contains the standard LyX template files described in Chapter
822 \begin_inset CommandInset ref
824 reference "sub:Creating-Templates"
831 \begin_layout Labeling
832 \labelwidthstring 00.00.0000
833 \begin_inset Flex Code
836 \begin_layout Plain Layout
842 contains files with the extension
843 \begin_inset Flex Code
846 \begin_layout Plain Layout
852 that define the user interface to LyX.
853 That is, the files define which items appear in which menus and the items
854 appearing on the toolbar.
857 \begin_layout Subsection
858 Files you don't want to modify
861 \begin_layout Standard
862 These files are used internally by LyX and you generally do not need to
863 modify them unless you are a developer.
866 \begin_layout Labeling
867 \labelwidthstring 00.00.0000
868 \begin_inset Flex Code
871 \begin_layout Plain Layout
877 this file contains the list of LyX developers.
878 The contents are displayed with the menu entry
879 \begin_inset Flex MenuItem
882 \begin_layout Plain Layout
883 Help\SpecialChar \menuseparator
896 \begin_layout Labeling
897 \labelwidthstring 00.00.0000
898 \begin_inset Flex Code
901 \begin_layout Plain Layout
907 this is a LaTeX script used during the configuration process.
911 \begin_layout Labeling
912 \labelwidthstring 00.00.0000
913 \begin_inset Flex Code
916 \begin_layout Plain Layout
922 this is the script that is used to re-configure LyX.
923 It creates configuration files in the directory it was run from.
926 \begin_layout Subsection
927 Other files needing a line or two...
930 \begin_layout Labeling
931 \labelwidthstring 00.00.0000
932 \begin_inset Flex Code
935 \begin_layout Plain Layout
941 this contains tables describing how different character encodings can be
945 \begin_layout Labeling
946 \labelwidthstring 00.00.0000
947 \begin_inset Flex Code
950 \begin_layout Plain Layout
956 this file contains the templates available to the new
957 \begin_inset Flex MenuItem
960 \begin_layout Plain Layout
973 \begin_layout Labeling
974 \labelwidthstring 00.00.0000
975 \begin_inset Flex Code
978 \begin_layout Plain Layout
984 this file contains a list of all the languages currently supported by LyX.
987 \begin_layout Section
988 Your local configuration directory
991 \begin_layout Standard
992 Even if you are using LyX as an unprivileged user, you might want to change
993 LyX configuration for your own use.
995 \begin_inset Flex Code
998 \begin_layout Plain Layout
1004 directory contains all your personal configuration files.
1005 This is the directory described as
1006 \begin_inset Quotes eld
1010 \begin_inset Quotes erd
1014 \begin_inset Flex MenuItem
1017 \begin_layout Plain Layout
1018 Help\SpecialChar \menuseparator
1020 \begin_inset space ~
1029 This directory is used as a mirror of
1030 \begin_inset Flex Code
1033 \begin_layout Plain Layout
1039 , which means that every file in
1040 \begin_inset Flex Code
1043 \begin_layout Plain Layout
1049 is a replacement for the corresponding file in
1050 \begin_inset Flex Code
1053 \begin_layout Plain Layout
1060 Any configuration file described in the above sections can be placed either
1061 in the system-wide directory, in which case it will affect all users, or
1062 in your local directory for your own use.
1065 \begin_layout Standard
1066 To make things clearer, let's provide a few examples:
1069 \begin_layout Itemize
1070 The preferences set in the
1071 \begin_inset Flex MenuItem
1074 \begin_layout Plain Layout
1075 Tools\SpecialChar \menuseparator
1081 dialog are saved to a file
1082 \begin_inset Flex Code
1085 \begin_layout Plain Layout
1092 \begin_inset Flex Code
1095 \begin_layout Plain Layout
1104 \begin_layout Itemize
1105 When you reconfigure using
1106 \begin_inset Flex MenuItem
1109 \begin_layout Plain Layout
1110 Tools\SpecialChar \menuseparator
1117 \begin_inset Flex Code
1120 \begin_layout Plain Layout
1126 script, and the resulting files are written in your local configuration
1128 This means that any additional text class file that you might have added
1130 \begin_inset Flex Code
1133 \begin_layout Plain Layout
1139 will be added to the list of classes in the
1140 \begin_inset Flex MenuItem
1143 \begin_layout Plain Layout
1144 Document\SpecialChar \menuseparator
1153 \begin_layout Itemize
1154 If you get some updated documentation from LyX ftp site and cannot install
1155 it because you do not have sysadmin rights on your system, you can just
1157 \begin_inset Flex Code
1160 \begin_layout Plain Layout
1166 and the items in the
1167 \begin_inset Flex MenuItem
1170 \begin_layout Plain Layout
1176 menu will open them!
1179 \begin_layout Section
1180 Running LyX with multiple configurations
1183 \begin_layout Standard
1184 The configuration freedom of the local configuration directory may not suffice
1185 if you want to have more than one configuration at your disposal.
1186 For example, you may want to be use different key bindings or printer settings
1188 You can achieve this by having several such directories.
1189 You then specify which directory to use at run-time.
1192 \begin_layout Standard
1193 Invoking LyX with the command line switch
1194 \begin_inset Flex Code
1197 \begin_layout Plain Layout
1207 instructs the program to read the configuration from that directory, and
1208 not from the default directory.
1209 (You can determine the default directory by running LyX without the
1210 \begin_inset Flex Code
1213 \begin_layout Plain Layout
1219 switch.) If the specified directory does not exist, LyX offers to create
1220 it for you, just like it does for the default directory on the first time
1221 you run the program.
1222 You can modify the configuration options in this additional user directory
1223 exactly as you would for the default directory.
1224 These directories are completely independent (but read on).
1225 Note that setting the environment variable
1226 \begin_inset Flex Code
1229 \begin_layout Plain Layout
1235 to some value has exactly the same effect.
1238 \begin_layout Standard
1239 Having several configurations also requires more maintenance: if you want
1240 to add a new layout to
1241 \begin_inset Flex Code
1244 \begin_layout Plain Layout
1250 which you want available from all your configurations, you must add it
1251 to each directory separately.
1252 You can avoid this with the following trick: after LyX creates the additional
1253 directory, most of the subdirectories (see above) are empty.
1254 If you want the new configuration to mirror an existing one, replace the
1255 empty subdirectory with a symbolic link to the matching subdirectory in
1256 the existing configuration.
1258 \begin_inset Flex Code
1261 \begin_layout Plain Layout
1267 subdirectory, however, since it contains a file written by the configuration
1268 script (also accessible through
1269 \begin_inset Flex MenuItem
1272 \begin_layout Plain Layout
1273 Tools\SpecialChar \menuseparator
1279 ) which is configuration-specific.
1282 \begin_layout Chapter
1283 The Preferences dialog
1286 \begin_layout Standard
1287 All options of the preferences dialog are described in the Appendix
1289 The Preferences Dialog
1296 For some options you might find here more details.
1299 \begin_layout Section
1301 \begin_inset CommandInset label
1310 \begin_layout Standard
1311 The first step is to define your file formats if they are not already defined.
1313 \begin_inset Flex MenuItem
1316 \begin_layout Plain Layout
1317 Tools\SpecialChar \menuseparator
1325 \begin_inset Flex MenuItem
1328 \begin_layout Plain Layout
1329 File Handling\SpecialChar \menuseparator
1336 \begin_inset Flex MenuItem
1339 \begin_layout Plain Layout
1340 New\SpecialChar \ldots{}
1346 button to define your new format.
1348 \begin_inset Flex MenuItem
1351 \begin_layout Plain Layout
1357 field contains the name used to identify the format in the GUI.
1359 \begin_inset Flex MenuItem
1362 \begin_layout Plain Layout
1368 is used to identify the format internally.
1369 You will also need to enter a file extension.
1370 These are all required.
1372 \begin_inset Flex MenuItem
1375 \begin_layout Plain Layout
1381 field is used to provide a keyboard shortcut on the menus.
1382 (For example, pressing
1383 \begin_inset Flex MenuItem
1386 \begin_layout Plain Layout
1393 \begin_inset Flex MenuItem
1396 \begin_layout Plain Layout
1397 View\SpecialChar \menuseparator
1406 \begin_layout Standard
1408 \begin_inset Flex MenuItem
1411 \begin_layout Plain Layout
1418 \begin_inset Flex MenuItem
1421 \begin_layout Plain Layout
1428 For example, you might want to use
1429 \begin_inset Flex MenuItem
1432 \begin_layout Plain Layout
1438 to view PostScript files.
1439 You can enter the command needed to start the program in the corresponding
1441 In defining this command, you can use the four variables listed in the
1443 The viewer is launched when you view an image in LyX or use the
1444 \begin_inset Flex MenuItem
1447 \begin_layout Plain Layout
1454 The editor is for example launched when you right-click on an image and
1456 \begin_inset Flex MenuItem
1459 \begin_layout Plain Layout
1465 in the appearing context menu.
1468 \begin_layout Standard
1470 \begin_inset Flex MenuItem
1473 \begin_layout Plain Layout
1479 option tells LyX that a format is suitable for document export.
1480 If this is set and if a suitable conversion route exists (see sec.
1481 \begin_inset space \thinspace{}
1485 \begin_inset CommandInset ref
1487 reference "sec:Converters"
1491 ), the format will appear in the
1492 \begin_inset Flex MenuItem
1495 \begin_layout Plain Layout
1496 File\SpecialChar \menuseparator
1503 The format will also appear in the
1504 \begin_inset Flex MenuItem
1507 \begin_layout Plain Layout
1513 menu if a viewer is specified for the format.
1514 Pure image formats, such as
1515 \begin_inset Flex Code
1518 \begin_layout Plain Layout
1524 , should not use this option.
1525 Formats that can both represent vector graphics and documents like
1526 \begin_inset Flex Code
1529 \begin_layout Plain Layout
1538 \begin_layout Standard
1540 \begin_inset Flex MenuItem
1543 \begin_layout Plain Layout
1544 Vector graphics format
1549 tells LyX that a format can contain vector graphics.
1550 This information is used to determine the target format of included graphics
1552 \begin_inset Flex MenuItem
1555 \begin_layout Plain Layout
1562 Included graphics may need to be converted to either
1563 \begin_inset Flex MenuItem
1566 \begin_layout Plain Layout
1573 \begin_inset Flex MenuItem
1576 \begin_layout Plain Layout
1583 \begin_inset Flex MenuItem
1586 \begin_layout Plain Layout
1593 \begin_inset Flex MenuItem
1596 \begin_layout Plain Layout
1602 cannot handle other image formats.
1603 If an included graphic is not already in
1604 \begin_inset Flex MenuItem
1607 \begin_layout Plain Layout
1614 \begin_inset Flex MenuItem
1617 \begin_layout Plain Layout
1624 \begin_inset Flex MenuItem
1627 \begin_layout Plain Layout
1633 format, it is converted to
1634 \begin_inset Flex MenuItem
1637 \begin_layout Plain Layout
1643 if the vector format option is set, and otherwise to
1644 \begin_inset Flex MenuItem
1647 \begin_layout Plain Layout
1656 \begin_layout Section
1660 \begin_layout Standard
1661 Since all conversions from one format to another take place in LyX's temporary
1662 directory, it is sometimes necessary to modify a file before copying it
1663 to the temporary directory in order that the conversion may be performed.
1667 \begin_layout Plain Layout
1668 For example, the file may refer to other files—images, for example—using
1669 relative file names, and these may become invalid when the file is copied
1670 to the temporary directory.
1675 This is done by a Copier: It copies a file to (or from) the temporary directory
1676 and may modify it in the process.
1679 \begin_layout Standard
1680 The definitions of the copiers may use four variables:
1683 \begin_layout Labeling
1684 \labelwidthstring 00.00.0000
1685 \begin_inset Flex Code
1688 \begin_layout Plain Layout
1694 The LyX system directory (e.
1695 \begin_inset space \thinspace{}
1699 \begin_inset space \space{}
1703 \begin_inset Flex MenuItem
1706 \begin_layout Plain Layout
1715 \begin_layout Labeling
1716 \labelwidthstring 00.00.0000
1717 \begin_inset Flex Code
1720 \begin_layout Plain Layout
1729 \begin_layout Labeling
1730 \labelwidthstring 00.00.0000
1731 \begin_inset Flex Code
1734 \begin_layout Plain Layout
1743 \begin_layout Labeling
1744 \labelwidthstring 00.00.0000
1745 \begin_inset Flex Code
1748 \begin_layout Plain Layout
1757 \begin_layout Standard
1758 The latter should be the filename as it would be used in a LaTeX's
1765 It is relevant only when exporting files suitable for such inclusion.
1768 \begin_layout Standard
1769 Copiers can be used to do almost anything with output files.
1770 For example, suppose you want generated pdf files to be copied to a special
1772 \begin_inset Flex Code
1775 \begin_layout Plain Layout
1782 Then you could write a shell script such as this one:
1785 \begin_layout Standard
1786 \begin_inset listings
1790 \begin_layout Plain Layout
1795 \begin_layout Plain Layout
1800 \begin_layout Plain Layout
1802 TOFILE=`basename $2`
1805 \begin_layout Plain Layout
1807 cp $FROMFILE /home/you/pdf/$TOFILE
1812 Save it in your local LyX directory—say,
1813 \begin_inset Flex Code
1816 \begin_layout Plain Layout
1817 /home/you/.lyx/scripts/pdfcopier.sh
1822 —and make it executable, if you need to do so on your platform.
1824 \begin_inset Flex MenuItem
1827 \begin_layout Plain Layout
1828 Tools\SpecialChar \menuseparator
1834 dialog, select under
1835 \begin_inset Flex MenuItem
1838 \begin_layout Plain Layout
1839 File Handling\SpecialChar \menuseparator
1846 \begin_inset Flex MenuItem
1849 \begin_layout Plain Layout
1855 format—or one of the other pdf formats—and enter
1856 \begin_inset Flex Code
1859 \begin_layout Plain Layout
1860 pdfcopier.sh $$i $$o
1866 \begin_inset Flex MenuItem
1869 \begin_layout Plain Layout
1879 \begin_layout Standard
1880 Copiers are used by LyX in various of its own conversions.
1881 For example, if appropriate programs are found, LyX will automatically
1882 install copiers for the
1883 \begin_inset Flex MenuItem
1886 \begin_layout Plain Layout
1893 \begin_inset Flex MenuItem
1896 \begin_layout Plain Layout
1898 \begin_inset space ~
1907 When these formats are exported, the copier sees that not just the main
1908 HTML file but various associated files (style files, images, etc.) are also
1910 All these files are written to a subdirectory of the directory in which
1911 the original LyX file was found.
1915 \begin_layout Plain Layout
1916 This copier can be customized.
1918 \begin_inset Quotes eld
1922 \begin_inset Quotes erd
1925 argument takes a comma-separated list of extensions to be copied; if it
1926 is omitted, all files will be copied.
1928 \begin_inset Quotes eld
1932 \begin_inset Quotes erd
1935 argument determines the extension added to the generated directory.
1937 \begin_inset Quotes eld
1941 \begin_inset Flex MenuItem
1944 \begin_layout Plain Layout
1951 \begin_inset Quotes erd
1954 , so HTML generated from
1955 \begin_inset Flex MenuItem
1958 \begin_layout Plain Layout
1959 /path/to/filename.lyx
1965 \begin_inset Flex MenuItem
1968 \begin_layout Plain Layout
1969 /path/to/filename.html.LyXconv
1983 \begin_layout Section
1985 \begin_inset CommandInset label
1987 name "sec:Converters"
1994 \begin_layout Standard
1995 You can define your own Converters to convert files between different formats.
1997 \begin_inset Flex MenuItem
2000 \begin_layout Plain Layout
2001 Tools\SpecialChar \menuseparator
2002 Preferences\SpecialChar \menuseparator
2003 File Handling\SpecialChar \menuseparator
2012 \begin_layout Standard
2013 To define a new converter, select the
2014 \begin_inset Flex MenuItem
2017 \begin_layout Plain Layout
2019 \begin_inset space ~
2028 \begin_inset Flex MenuItem
2031 \begin_layout Plain Layout
2033 \begin_inset space ~
2041 from the drop-down lists, enter the command needed for the conversion,
2043 \begin_inset Flex MenuItem
2046 \begin_layout Plain Layout
2053 Several variables can be used in the definition of converters:
2056 \begin_layout Labeling
2057 \labelwidthstring 00.00.0000
2058 \begin_inset Flex Code
2061 \begin_layout Plain Layout
2067 The LyX system directory
2070 \begin_layout Labeling
2071 \labelwidthstring 00.00.0000
2072 \begin_inset Flex Code
2075 \begin_layout Plain Layout
2084 \begin_layout Labeling
2085 \labelwidthstring 00.00.0000
2086 \begin_inset Flex Code
2089 \begin_layout Plain Layout
2098 \begin_layout Labeling
2099 \labelwidthstring 00.00.0000
2100 \begin_inset Flex Code
2103 \begin_layout Plain Layout
2109 The base filename of the input file (i.
2110 \begin_inset space \thinspace{}
2113 g., without the extension)
2116 \begin_layout Labeling
2117 \labelwidthstring 00.00.0000
2118 \begin_inset Flex Code
2121 \begin_layout Plain Layout
2127 The path to the input file
2130 \begin_layout Labeling
2131 \labelwidthstring 00.00.0000
2132 \begin_inset Flex Code
2135 \begin_layout Plain Layout
2141 The path to the original input file (this is different from $$p when a
2142 chain of converters is called).
2145 \begin_layout Standard
2147 \begin_inset Flex MenuItem
2150 \begin_layout Plain Layout
2152 \begin_inset space ~
2160 field you can enter the following flags, separated by commas:
2163 \begin_layout Labeling
2164 \labelwidthstring 00.00.0000
2165 \begin_inset Flex Code
2168 \begin_layout Plain Layout
2174 This converter runs some form of LaTeX.
2175 This will make LyX's LaTeX error logs available.
2178 \begin_layout Labeling
2179 \labelwidthstring 00.00.0000
2180 \begin_inset Flex Code
2183 \begin_layout Plain Layout
2190 \begin_inset Flex MenuItem
2193 \begin_layout Plain Layout
2199 file for the conversion.
2202 \begin_layout Labeling
2203 \labelwidthstring 00.00.0000
2204 \begin_inset Flex Code
2207 \begin_layout Plain Layout
2216 \begin_layout Standard
2217 The following three flags are not really flags at all because they take
2219 \begin_inset Flex MenuItem
2222 \begin_layout Plain Layout
2224 \begin_inset space ~
2228 \begin_inset space ~
2239 \begin_layout Labeling
2240 \labelwidthstring 00.00.0000
2241 \begin_inset Flex Code
2244 \begin_layout Plain Layout
2250 If set, the converter's standard error will be redirected to a file
2251 \begin_inset Flex Code
2254 \begin_layout Plain Layout
2260 , and the script given as argument will be run as:
2261 \begin_inset Flex Code
2264 \begin_layout Plain Layout
2265 script < infile.out > infile.log
2271 The argument may contain
2272 \begin_inset Flex Code
2275 \begin_layout Plain Layout
2284 \begin_layout Labeling
2285 \labelwidthstring 00.00.0000
2286 \begin_inset Flex Code
2289 \begin_layout Plain Layout
2295 The name of the directory in which the converter will dump the generated
2297 LyX will not create this directory, and it does not copy anything into
2298 it, though it will copy this directory to the destination.
2299 The argument may contain
2300 \begin_inset Flex Code
2303 \begin_layout Plain Layout
2309 , which will be replaced by the base name of the input and output files,
2310 respectively, when the directory is copied.
2311 \begin_inset Newline newline
2314 Note that resultdir and usetempdir make no sense together.
2315 The latter will be ignored if the former is given.
2318 \begin_layout Labeling
2319 \labelwidthstring 00.00.0000
2320 \begin_inset Flex Code
2323 \begin_layout Plain Layout
2329 Determines the output file name and may, contain
2330 \begin_inset Flex Code
2333 \begin_layout Plain Layout
2340 Sensible only with resultdir and optional even then; if not given, it defaults
2344 \begin_layout Standard
2345 None of these last three are presently used in any of the converters that
2346 are installed with LyX.
2350 \begin_layout Standard
2351 You do not have to define converters for all formats between which you want
2353 For example, you will note that there is no `LyX to PostScript' converter,
2354 but LyX will export PostScript.
2355 It does so by first creating a LaTeX file (no converter needs to be defined
2356 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2357 and finally converting the resulting DVI file to PostScript.
2358 LyX finds such `chains' of converters automatically, and it will always
2359 choose the shortest possible chain.
2360 You can, though, still define multiple conversion methods between file
2362 For example, the standard LyX configuration provides three ways to convert
2363 LaTeX to PDF: Directly, using
2364 \begin_inset Flex MenuItem
2367 \begin_layout Plain Layout
2373 ; via (DVI and) PostScript, using
2374 \begin_inset Flex MenuItem
2377 \begin_layout Plain Layout
2384 \begin_inset Flex MenuItem
2387 \begin_layout Plain Layout
2394 To define such alternate chains, you must define multiple target `file
2395 formats', as described in section
2396 \begin_inset CommandInset ref
2398 reference "sec:Formats"
2403 For example, in the standard configuration, the formats named
2404 \begin_inset Flex MenuItem
2407 \begin_layout Plain Layout
2414 \begin_inset Flex MenuItem
2417 \begin_layout Plain Layout
2424 \begin_inset Flex MenuItem
2427 \begin_layout Plain Layout
2433 are defined, all of which share the extension
2434 \begin_inset Flex MenuItem
2437 \begin_layout Plain Layout
2443 , and which correspond to the conversion methods just mentioned.
2446 \begin_layout Chapter
2447 Internationalizing LyX
2448 \begin_inset CommandInset label
2450 name "cha:Internationalizing-LyX"
2457 \begin_layout Standard
2458 LyX supports using a translated interface.
2459 Last time we checked, LyX provided text in thirty languages.
2460 The language of choice is called your
2465 (For further reading on locale settings, see also the documentation for
2466 locale that comes with your operating system.
2467 For Linux, the manual page for
2468 \begin_inset Flex Code
2471 \begin_layout Plain Layout
2477 could be a good place to start).
2480 \begin_layout Standard
2481 Notice that these translations will work, but do contain a few flaws.
2482 In particular, all dialogs have been designed with the English text in
2483 mind, which means that some of the translated text will be too large to
2484 fit within the space allocated.
2485 This is only a display problem and will not cause any harm.
2486 Also, you will find that some of the translations do not define shortcut
2487 keys for everything.
2488 Sometimes, there are simply not enough free letters to do it.
2489 Other times, the translator just hasn't got around to doing it yet.
2490 Our localization team, which you may wish to join,
2494 \begin_layout Plain Layout
2495 If you are a fluent speaker of a language other than English, joining these
2496 teams is a great way to give back to the LyX community!
2501 will of course try to fix these shortcomings in future versions of LyX.
2504 \begin_layout Section
2508 \begin_layout Subsection
2509 Translating the graphical user interface (text messages).
2512 \begin_layout Standard
2514 \begin_inset Flex Code
2517 \begin_layout Plain Layout
2523 library to handle the internationalization of the interface.
2524 To have LyX speak your favorite language in all menus and dialogs, you
2526 \begin_inset Flex Code
2529 \begin_layout Plain Layout
2535 -file for that language.
2536 When this is available, you'll have to generate a
2537 \begin_inset Flex Code
2540 \begin_layout Plain Layout
2546 -file from it and install the
2547 \begin_inset Flex Code
2550 \begin_layout Plain Layout
2557 The process of doing all of this is explained in the documentation for
2559 \begin_inset Flex Code
2562 \begin_layout Plain Layout
2569 It is possible to do this just for yourself, but if you're going to do
2570 it, you might as well share the results of your labors with the rest of
2572 Send a message to the LyX developers' list for more information about how
2576 \begin_layout Standard
2577 In short, this is what you should do (xx denotes the language code):
2580 \begin_layout Itemize
2581 Check out the LyX source code.
2583 \begin_inset CommandInset href
2585 name "information on the web"
2586 target "http://www.lyx.org/devel/cvs.php"
2593 \begin_layout Itemize
2595 \begin_inset Flex Code
2598 \begin_layout Plain Layout
2604 to the folder of the
2605 \begin_inset Flex Code
2608 \begin_layout Plain Layout
2616 \begin_inset Flex Code
2619 \begin_layout Plain Layout
2627 \begin_inset Flex Code
2630 \begin_layout Plain Layout
2636 doesn't exist anywhere, it can be remade with the console command
2637 \begin_inset Flex Code
2640 \begin_layout Plain Layout
2646 in that directory, or you can use an existing po-file for some other language
2650 \begin_layout Itemize
2652 \begin_inset Flex Code
2655 \begin_layout Plain Layout
2665 \begin_layout Plain Layout
2666 This is just a text file, so it can be edited in any text editor.
2667 But there are also specialized programs that support such editing, such
2672 (for all platforms) or
2681 contains a `mode' for editing
2682 \begin_inset Flex Code
2685 \begin_layout Plain Layout
2696 For some menu- and widget-labels, there are also shortcut keys that should
2698 Those keys are marked after a `|', and should be translated according to
2699 the words and phrases of the language.
2700 You should also fill also out the information at the beginning of the new
2702 \begin_inset Flex Code
2705 \begin_layout Plain Layout
2711 -file with your email-address, etc., so people know where to reach you with
2712 suggestions and entertaining flames.
2715 \begin_layout Standard
2716 If you are just doing this on your own, then:
2719 \begin_layout Itemize
2721 \begin_inset Flex Code
2724 \begin_layout Plain Layout
2731 This can be done with
2732 \begin_inset Flex Code
2735 \begin_layout Plain Layout
2736 msgfmt -o xx.mo < xx.po
2744 \begin_layout Itemize
2746 \begin_inset Flex Code
2749 \begin_layout Plain Layout
2755 -file to your locale-tree, at the correct directory for application messages
2760 xx, and under the name
2761 \begin_inset Flex Code
2764 \begin_layout Plain Layout
2771 \begin_inset space \thinspace{}
2775 \begin_inset space \space{}
2779 \begin_inset Flex Code
2782 \begin_layout Plain Layout
2783 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2793 \begin_layout Standard
2794 As said, however, it would be best if the new
2795 \begin_inset Flex Code
2798 \begin_layout Plain Layout
2804 -file could be added to the LyX distribution, so others can use it.
2805 Adding it involves making additional changes to LyX.
2806 So send an email to the developers' mailing list if you're interested in
2810 \begin_layout Subsubsection
2814 \begin_layout Standard
2815 Sometimes it turns out that one English message needs to be translated into
2816 different messages in the target language.
2817 One example is the message
2818 \begin_inset Flex Code
2821 \begin_layout Plain Layout
2827 which has the German translation
2835 , depending upon exactly what the English
2836 \begin_inset Quotes eld
2840 \begin_inset Quotes erd
2845 \begin_inset Flex Code
2848 \begin_layout Plain Layout
2854 does not handle such ambiguous translations.
2855 Therefore you have to add some context information to the message: Instead
2857 \begin_inset Flex Code
2860 \begin_layout Plain Layout
2867 \begin_inset Flex Code
2870 \begin_layout Plain Layout
2871 To[[as in 'From format x to format y']]
2877 \begin_inset Flex Code
2880 \begin_layout Plain Layout
2881 To[[as in 'From page x to page y']].
2886 Now the two occurrences of
2887 \begin_inset Flex Code
2890 \begin_layout Plain Layout
2897 \begin_inset Flex Code
2900 \begin_layout Plain Layout
2906 and can be translated correctly to
2917 \begin_layout Standard
2918 Of course the context information needs to be stripped off the original
2919 message when no translation is used.
2920 Therefore you have to put it in double square brackets at the end of the
2921 message (see the example above).
2922 The translation mechanism of LyX ensures that everything in double square
2923 brackets at the end of messages is removed before displaying the message.
2926 \begin_layout Subsection
2927 Translating the documentation.
2930 \begin_layout Standard
2931 The online documentation (in the
2932 \begin_inset Flex MenuItem
2935 \begin_layout Plain Layout
2941 -menu) can (and should!) be translated.
2942 If there are translated versions of the documentation available
2946 \begin_layout Plain Layout
2947 As of March 2008, at least some of the documents have been translated into
2948 fourteen languages, with the Tutorial available in a few more.
2953 and the locale is set accordingly, these will be used automagically by
2955 LyX looks for translated versions as
2956 \begin_inset Flex Code
2959 \begin_layout Plain Layout
2960 LyXDir/doc/xx/DocName.lyx
2966 \begin_inset Flex Code
2969 \begin_layout Plain Layout
2975 is the code for the language currently in use.
2976 If there are no translated documents, the default English versions will
2978 Note that the translated versions must have the same filenames (
2979 \begin_inset Flex Code
2982 \begin_layout Plain Layout
2988 above) as the original.
2989 If you feel up to translating the documentation (an excellent way to proof-read
2990 the original documentation by the way!), there are a few things you should
2994 \begin_layout Itemize
2995 Check out the documentation translation web page at
2996 \begin_inset CommandInset href
2998 name "http://www.lyx.org/Translation"
2999 target "http://www.lyx.org/Translation"
3004 That way, you can find out which (if any) documents have already been translate
3005 d into your language.
3006 You can also find out who (if anyone) is organizing the effort to translate
3007 the documentation into your language.
3008 If no one is organizing the effort, please let us know that you're interested.
3011 \begin_layout Standard
3012 Once you get to actually translating, here's a few hints for you that may
3016 \begin_layout Itemize
3017 Join the documentation team! There is information on how to do that in
3018 \begin_inset Flex Code
3021 \begin_layout Plain Layout
3028 \begin_inset Flex MenuItem
3031 \begin_layout Plain Layout
3032 Help\SpecialChar \menuseparator
3038 ), which by the way is the first document you should translate.
3041 \begin_layout Itemize
3042 Learn the typographic conventions for the language you are translating to.
3043 Typography is an ancient art and over the centuries, a great variety of
3044 conventions have developed throughout different parts of the world.
3045 Also study the professional terminology amongst typographers in your country.
3046 Inventing your own terminology will only confuse the users.
3049 (Warning! Typography is addictive!)
3052 \begin_layout Itemize
3053 Make a copy of the document.
3054 This will be your working copy.
3055 You can use this as your personal translated help-file by placing it in
3057 \begin_inset Flex Code
3060 \begin_layout Plain Layout
3069 \begin_layout Itemize
3070 Sometimes the original document (from the LyX-team) will be updated.
3071 Use the source viewer at
3072 \begin_inset CommandInset href
3074 name "http://www.lyx.org/trac/timeline"
3075 target "http://www.lyx.org/trac/timeline"
3079 to see what has been changed.
3080 That way you can easily see which parts of the translated document need
3084 \begin_layout Standard
3085 If you ever find an error in the original document, fix it and notify the
3086 rest of the documentation team of the changes! (You didn't forget to join
3087 the documentation team, did you?)
3090 \begin_layout Standard
3091 \begin_inset Branch OutDated
3094 \begin_layout Section
3095 International Keyboard Support
3098 \begin_layout Standard
3101 [Editor's Note: The following section is by
3109 It needs to be fixed to conform to the new Documentation Style sheet and
3110 to make use of the new v1.0 features.
3111 The whole thing also needs to be merged with the section following it.-jw
3112 It may also be badly out of date.-rh (2008)]
3115 \begin_layout Subsection
3116 Defining Own Keymaps: Keymap File Format
3119 \begin_layout Standard
3120 Let's look at a keyboard definition file a little closer.
3121 It is a plain text file defining
3124 \begin_layout Itemize
3125 key-to-key or key-to-string translations
3128 \begin_layout Itemize
3132 \begin_layout Itemize
3133 dead keys exceptions
3136 \begin_layout Standard
3137 To define key-to-key or key-to-string translation, use this command:
3140 \begin_layout Quotation
3141 \begin_inset Flex Code
3144 \begin_layout Plain Layout
3153 \begin_inset Flex Code
3156 \begin_layout Plain Layout
3165 \begin_layout Standard
3167 \begin_inset Flex Code
3170 \begin_layout Plain Layout
3176 is the key to be translated and
3177 \begin_inset Flex Code
3180 \begin_layout Plain Layout
3186 is the string to be inserted into the document.
3187 To define dead keys, use:
3190 \begin_layout Quotation
3191 \begin_inset Flex Code
3194 \begin_layout Plain Layout
3203 \begin_inset Flex Code
3206 \begin_layout Plain Layout
3215 \begin_layout Standard
3217 \begin_inset Flex Code
3220 \begin_layout Plain Layout
3226 is a keyboard key and
3227 \begin_inset Flex Code
3230 \begin_layout Plain Layout
3237 The following dead keys are supported (shortcut name is in parentheses):
3240 \begin_layout Quotation
3244 \begin_inset space \hfill{}
3250 \begin_layout Quotation
3252 \begin_inset space \hfill{}
3258 \begin_layout Quotation
3260 \begin_inset space \hfill{}
3266 \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{}
3291 \begin_layout Plain Layout
3303 \begin_layout Quotation
3305 \begin_inset space \hfill{}
3311 \begin_layout Quotation
3313 \begin_inset space \hfill{}
3320 \begin_layout Plain Layout
3332 \begin_layout Quotation
3334 \begin_inset space \hfill{}
3340 \begin_layout Quotation
3342 \begin_inset space \hfill{}
3348 \begin_layout Quotation
3350 \begin_inset space \hfill{}
3357 \begin_layout Plain Layout
3369 \begin_layout Quotation
3371 \begin_inset space \hfill{}
3378 \begin_layout Plain Layout
3390 \begin_layout Quotation
3392 \begin_inset space \hfill{}
3398 \begin_layout Quotation
3399 hungarian umlaut (hug)
3400 \begin_inset space \hfill{}
3406 \begin_layout Quotation
3408 \begin_inset space \hfill{}
3414 \begin_layout Quotation
3416 \begin_inset space \hfill{}
3423 \begin_layout Plain Layout
3435 \begin_layout Standard
3436 Since in many international keyboards there are exceptions to what some
3437 dead keys should do, you can define them using
3440 \begin_layout Quotation
3441 \begin_inset Flex Code
3444 \begin_layout Plain Layout
3452 deadkey key outstring
3455 \begin_layout Standard
3456 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3460 \begin_layout Quotation
3461 \begin_inset Flex Code
3464 \begin_layout Plain Layout
3477 \begin_layout Standard
3478 to make it work correctly.
3479 Also, you have to define as exceptions dead keys over i and j, to remove
3480 the dot from them before inserting an accent mark.
3481 I will change this when the time comes, but so far I haven't had time.
3484 \begin_layout Standard
3485 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3488 \begin_inset Flex Code
3491 \begin_layout Plain Layout
3497 have different meaning.
3499 \begin_inset Flex Code
3502 \begin_layout Plain Layout
3508 marks comments, quotes start and end LaTeX-style commands.
3509 To enter quote, you'll need to use
3510 \begin_inset Flex Code
3513 \begin_layout Plain Layout
3522 \begin_inset Flex Code
3525 \begin_layout Plain Layout
3532 \begin_inset Flex Code
3535 \begin_layout Plain Layout
3546 \begin_layout Standard
3547 If you make a keyboard description file that works for your language, please
3548 mail it to me, so I can include it in the next keymap distribution.
3551 \begin_layout Standard
3552 More keywords will be supported in keymap configuration file in future,
3556 \begin_layout Itemize
3557 \begin_inset Flex Code
3560 \begin_layout Plain Layout
3571 \begin_inset space \hfill{}
3575 \begin_inset Flex Code
3578 \begin_layout Plain Layout
3587 \begin_layout Itemize
3588 \begin_inset Flex Code
3591 \begin_layout Plain Layout
3602 \begin_inset space \hfill{}
3606 \begin_inset Flex Code
3609 \begin_layout Plain Layout
3615 an external keymap translation program
3618 \begin_layout Standard
3619 Also, it should look into
3620 \begin_inset Flex Code
3623 \begin_layout Plain Layout
3629 file for defaults, too (for example, a
3630 \begin_inset Flex Code
3633 \begin_layout Plain Layout
3641 option to include default keyboard).
3649 \begin_layout Section
3650 International Keymap Stuff
3651 \begin_inset CommandInset label
3653 name "sec:International-Keymap-Stuff"
3660 \begin_layout Standard
3661 \begin_inset Note Note
3664 \begin_layout Plain Layout
3665 In doing the revisions on this document in March 2008, I did not look over
3666 this stuff, as I do not understand it.
3667 It would be good if someone else could do so.
3676 \begin_layout Standard
3677 The next two sections describe the
3678 \begin_inset Flex Code
3681 \begin_layout Plain Layout
3690 \begin_inset Flex Code
3693 \begin_layout Plain Layout
3701 file syntax in detail.
3702 These sections should help you design your own key map if the ones provided
3703 do not meet your needs.
3706 \begin_layout Subsection
3710 \begin_layout Standard
3714 \begin_inset Flex Code
3717 \begin_layout Plain Layout
3723 file maps keystrokes to characters or strings.
3724 As the name suggests, it sets a keyboard mapping.
3726 \begin_inset Flex Code
3729 \begin_layout Plain Layout
3740 \begin_inset Flex Code
3743 \begin_layout Plain Layout
3758 \begin_inset Flex Code
3761 \begin_layout Plain Layout
3774 \begin_inset Flex Code
3777 \begin_layout Plain Layout
3786 \begin_inset Flex Code
3789 \begin_layout Plain Layout
3797 are described in this section.
3800 \begin_layout Labeling
3801 \labelwidthstring 00.00.0000
3802 \begin_inset Flex Code
3805 \begin_layout Plain Layout
3813 Map a character to a string
3816 \begin_layout LyX-Code
3831 \begin_layout Standard
3864 the double-quote (")
3881 must be escaped with a preceding backslash (
3892 \begin_layout Standard
3894 \begin_inset Flex MenuItem
3897 \begin_layout Plain Layout
3905 statement to cause the symbol
3906 \begin_inset Flex MenuItem
3909 \begin_layout Plain Layout
3917 to be output for the keystroke
3918 \begin_inset Flex MenuItem
3921 \begin_layout Plain Layout
3932 \begin_layout LyX-Code
3938 \begin_layout Labeling
3939 \labelwidthstring 00.00.0000
3940 \begin_inset Flex Code
3943 \begin_layout Plain Layout
3951 Specify an accent character
3954 \begin_layout LyX-Code
3963 \begin_layout Standard
3964 This will make the cha
4002 This is the dead key
4006 \begin_layout Plain Layout
4013 refers to a key that does not produce a character by itself, but when followed
4014 with another key, produces the desired accent character.
4015 For example, a German characte
4017 r with an umlaut like
4027 can be produced in this manner.
4036 \begin_layout Standard
4049 and then another key not in
4066 followed by the other, not allowed key, as output.
4070 \begin_inset Flex MenuItem
4073 \begin_layout Plain Layout
4081 cancels a dead key, so if
4092 \begin_inset Flex MenuItem
4095 \begin_layout Plain Layout
4104 , the cursor will not go one position backwards but will instead cancel
4120 might have had on the next keystroke.
4124 \begin_layout Standard
4125 The following example specifies that the character ' is to be an acute accent,
4126 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4129 \begin_layout LyX-Code
4132 kmod ' acute aeiouAEIOU
4135 \begin_layout Labeling
4136 \labelwidthstring 00.00.0000
4137 \begin_inset Flex Code
4140 \begin_layout Plain Layout
4146 Specify an exception to the accent character
4149 \begin_layout LyX-Code
4158 \begin_layout Standard
4159 This defines an exce
4200 have been assigned a keystroke with a previous
4203 \begin_inset Flex Code
4206 \begin_layout Plain Layout
4230 must not belong in the
4277 If such a declaration does not exist in
4285 \begin_inset Flex Code
4288 \begin_layout Plain Layout
4322 \begin_inset Flex Code
4325 \begin_layout Plain Layout
4339 \begin_layout Standard
4340 The following command produces causes äi to be produced when you enter acute-i
4344 \begin_layout LyX-Code
4358 \begin_layout Labeling
4359 \labelwidthstring 00.00.0000
4360 \begin_inset Flex Code
4363 \begin_layout Plain Layout
4369 Combine two accent characters
4372 \begin_layout LyX-Code
4378 accent1 accent2 allowed
4381 \begin_layout Standard
4382 This one is getting pretty esoteric.
4383 It allows you to combine the effect
4439 \begin_inset Flex Code
4442 \begin_layout Plain Layout
4470 \begin_layout Standard
4471 Consider this example from the
4472 \begin_inset Flex Code
4475 \begin_layout Plain Layout
4486 \begin_layout LyX-Code
4489 kmod ; acute aeioyvhAEIOYVH
4493 kcomb acute umlaut iyIY
4496 \begin_layout Standard
4497 This allows you to press
4498 \begin_inset Flex MenuItem
4501 \begin_layout Plain Layout
4509 and get the effect of
4510 \begin_inset Flex Code
4513 \begin_layout Plain Layout
4532 in this case cancels the last dead key, so if you press
4533 \begin_inset Flex MenuItem
4536 \begin_layout Plain Layout
4545 \begin_inset Flex Code
4548 \begin_layout Plain Layout
4561 \begin_layout Subsection
4565 \begin_layout Standard
4567 \begin_inset Flex Code
4570 \begin_layout Plain Layout
4578 mapping is performed, a
4579 \begin_inset Flex Code
4582 \begin_layout Plain Layout
4592 file maps the strings that the symbols generate to characters in the current
4594 The LyX distribution currently includes at least the
4595 \begin_inset Flex Code
4598 \begin_layout Plain Layout
4607 \begin_inset Flex Code
4610 \begin_layout Plain Layout
4621 \begin_layout Standard
4623 \begin_inset Flex Code
4626 \begin_layout Plain Layout
4634 file is a sequence of declarations of the form
4637 \begin_layout LyX-Code
4650 \begin_layout Standard
4651 For example, in order to map
4652 \begin_inset Flex MenuItem
4655 \begin_layout Plain Layout
4665 to the corresponding character in the iso-8859-1 set (233), the following
4669 \begin_layout LyX-Code
4677 \begin_layout Standard
4679 \begin_inset Flex Code
4682 \begin_layout Plain Layout
4691 \begin_inset Flex Code
4694 \begin_layout Plain Layout
4712 the same character can apply to more than one string.
4714 \begin_inset Flex Code
4717 \begin_layout Plain Layout
4728 \begin_layout LyX-Code
4740 \begin_inset Newline newline
4756 \begin_layout Standard
4757 If LyX cannot find a mapping for the string produced by the keystroke or
4758 a deadkey sequence, it will check if it looks like an accented char and
4759 try to draw an accent over the character on screen.
4762 \begin_layout Subsection
4766 \begin_layout Standard
4767 There is a second way to add support for international characters through
4768 so-called dead-keys.
4769 A dead-key works in combination with a letter to produce an accented character.
4770 Here, we'll explain how to create a really simple dead-key to illustrate
4774 \begin_layout Standard
4775 Suppose you happen to need the circumflex character,
4776 \begin_inset Quotes eld
4780 \begin_inset Quotes erd
4785 \begin_inset Flex MenuItem
4788 \begin_layout Plain Layout
4795 \begin_inset space ~
4799 \begin_inset Flex MenuItem
4802 \begin_layout Plain Layout
4808 ] to the LyX command
4809 \begin_inset Flex Code
4812 \begin_layout Plain Layout
4819 \begin_inset Flex Code
4822 \begin_layout Plain Layout
4829 Now, whenever you type the
4830 \begin_inset Flex MenuItem
4833 \begin_layout Plain Layout
4839 -key followed by a letter, that letter will have a circumflex accent on
4841 For example, the sequence
4842 \begin_inset Quotes eld
4846 \begin_inset Flex MenuItem
4849 \begin_layout Plain Layout
4856 \begin_inset Quotes erd
4859 produces the letter:
4860 \begin_inset Quotes eld
4864 \begin_inset Quotes erd
4868 If you tried to type
4869 \begin_inset Quotes eld
4873 \begin_inset Flex MenuItem
4876 \begin_layout Plain Layout
4883 \begin_inset Quotes erd
4886 , however, LyX will complain with a beep, since a
4887 \begin_inset Quotes eld
4891 \begin_inset Flex MenuItem
4894 \begin_layout Plain Layout
4901 \begin_inset Quotes erd
4904 never takes a circumflex accent.
4906 \begin_inset Flex MenuItem
4909 \begin_layout Plain Layout
4915 after a dead-key produces the bare-accent.
4916 Please note this last point! If you bind a key to a dead-key, you'll need
4917 to rebind the character on that key to yet another key.
4919 \begin_inset Flex MenuItem
4922 \begin_layout Plain Layout
4928 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
4931 \begin_layout Standard
4932 One common way to bind dead-keys is to use
4933 \begin_inset Flex MenuItem
4936 \begin_layout Plain Layout
4943 \begin_inset Flex MenuItem
4946 \begin_layout Plain Layout
4953 \begin_inset Flex MenuItem
4956 \begin_layout Plain Layout
4962 in combination with an accent, like
4963 \begin_inset Quotes eld
4967 \begin_inset Flex MenuItem
4970 \begin_layout Plain Layout
4977 \begin_inset Quotes erd
4981 \begin_inset Quotes eld
4985 \begin_inset Flex MenuItem
4988 \begin_layout Plain Layout
4995 \begin_inset Quotes erd
4999 \begin_inset Quotes eld
5003 \begin_inset Flex MenuItem
5006 \begin_layout Plain Layout
5013 \begin_inset Quotes erd
5017 Another way involves using
5018 \begin_inset Flex Code
5021 \begin_layout Plain Layout
5028 \begin_inset Flex Code
5031 \begin_layout Plain Layout
5037 to set up the special
5038 \begin_inset Flex Code
5041 \begin_layout Plain Layout
5049 \begin_inset Flex Code
5052 \begin_layout Plain Layout
5058 acts in some ways just like
5059 \begin_inset Flex MenuItem
5062 \begin_layout Plain Layout
5068 and permits you to bind keys to accented characters.
5069 You can also turn keys into dead-keys by binding them to something like
5071 \begin_inset Flex Code
5074 \begin_layout Plain Layout
5080 and then binding this symbolic key to the corresponding LyX command.
5084 \begin_layout Plain Layout
5089 : This is exactly what I do in my
5090 \begin_inset Flex Code
5093 \begin_layout Plain Layout
5100 \begin_inset Flex Code
5103 \begin_layout Plain Layout
5111 \begin_inset Flex MenuItem
5114 \begin_layout Plain Layout
5116 \begin_inset space ~
5125 \begin_inset Flex Code
5128 \begin_layout Plain Layout
5134 and a bunch of these
5135 \begin_inset Quotes eld
5139 \begin_inset Flex Code
5142 \begin_layout Plain Layout
5149 \begin_inset Quotes erd
5152 symbolic keys bound such things as
5153 \begin_inset Flex MenuItem
5156 \begin_layout Plain Layout
5158 \begin_inset space ~
5167 \begin_inset Flex MenuItem
5170 \begin_layout Plain Layout
5172 \begin_inset space ~
5181 This is how I produce my accented characters.
5186 You can make just about anything into the
5187 \begin_inset Flex Code
5190 \begin_layout Plain Layout
5197 \begin_inset Flex MenuItem
5200 \begin_layout Plain Layout
5206 keys, a spare function key, etc.
5207 As for the LyX commands that produce accents, check the entry for
5208 \begin_inset Flex Code
5211 \begin_layout Plain Layout
5222 You'll find the complete list there.
5225 \begin_layout Subsection
5226 Saving your Language Configuration
5229 \begin_layout Standard
5230 You can edit your preferences so that your desired language environment
5231 is automatically configured when LyX starts up, via the
5232 \begin_inset Flex MenuItem
5235 \begin_layout Plain Layout
5236 Edit\SpecialChar \menuseparator
5245 \begin_layout Chapter
5246 Installing New Document Classes, Layouts, and Templates
5247 \begin_inset CommandInset label
5249 name "cha:Installing-New-Document"
5254 \begin_inset Argument
5257 \begin_layout Plain Layout
5258 Installing New Document Classes
5266 \begin_layout Standard
5267 In this chapter, we describe the procedures for creating and installing
5268 new LyX layout and template files, as well as offer a refresher on correctly
5269 installing new LaTeX document classes.
5273 \begin_layout Standard
5274 First, let us a say a few words about how one ought to think about the relation
5275 between LyX and LaTeX.
5276 The thing to understand is that, in a certain sense, LyX doesn't know anything
5278 Indeed, from LyX's point of view, LaTeX is just one of several
5279 \begin_inset Quotes eld
5283 \begin_inset Quotes erd
5286 in which it is capable of producing output.
5287 Other such formats are DocBook, plaintext, and XHTML.
5288 LaTeX is, of course, a particularly important format, but very little of
5289 the information LyX has about LaTeX is actually contained in the program
5294 \begin_layout Plain Layout
5295 Some commands are sufficiently complex that they are
5296 \begin_inset Quotes eld
5300 \begin_inset Quotes erd
5304 But the developers generally regard this as a Bad Thing.
5309 Rather, that information, even for the standard classes like
5310 \begin_inset Flex Code
5313 \begin_layout Plain Layout
5319 , is contained in `layout files'.
5320 Similarly, LyX itself does not know much about DocBook or XHTML.
5321 What it knows is contained in layout files.
5324 \begin_layout Standard
5325 You can think of the layout file for a given document class as a translation
5326 manual between LyX constructs---paragraphs with their corresponding styles,
5327 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5329 Almost everything LyX knows about
5330 \begin_inset Flex Code
5333 \begin_layout Plain Layout
5339 , for example, is contained in the file
5340 \begin_inset Flex Code
5343 \begin_layout Plain Layout
5349 and in various other files it includes.
5350 For this reason, anyone intending to write layout files should plan to
5351 study the existing files.
5352 A good place to start is with
5353 \begin_inset Flex Code
5356 \begin_layout Plain Layout
5362 , which is included in
5363 \begin_inset Flex Code
5366 \begin_layout Plain Layout
5373 \begin_inset Flex Code
5376 \begin_layout Plain Layout
5382 , and many of the other layout files for document classes.
5383 This file is where sections and the like are defined:
5384 \begin_inset Flex Code
5387 \begin_layout Plain Layout
5393 tells LyX how paragraphs that are marked with the Section, Subsection,
5394 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5397 \begin_inset Flex Code
5400 \begin_layout Plain Layout
5406 file basically just includes several of these
5407 \begin_inset Flex Code
5410 \begin_layout Plain Layout
5419 \begin_layout Standard
5420 Defining the LyX--LaTeX correspondence is not the only thing layout files
5422 Their other job is to define how the LyX constructs themselves will appear
5424 The fact that layout files have these two jobs is often a source of confusion,
5425 because they are completely separate.
5426 Telling LyX how to translate a certain paragraph style into LaTeX does
5427 not tell LyX how to display it; conversely, telling LyX how to display
5428 a certain paragraph style does not tell LyX how to translate it into LaTeX
5429 (let alone tell LaTeX how to display it).
5430 So, in general, when you define a new LyX construct, you must always do
5431 two quite separate things: (i)
5432 \begin_inset space ~
5435 tell LyX how to translate it into LaTeX and (ii)
5436 \begin_inset space ~
5439 tell LyX how to display it.
5442 \begin_layout Standard
5443 Much the same is true, of course, as regards LyX's other backend formats,
5444 though XHTML is in some ways different, because in that case LyX
5448 able, to some extent, to use information about how it should display a
5449 paragraph on the screen to output information (in the form of CSS) about
5450 how the paragraph should be displayed in a browser.
5451 Even in this case, however, the distinction between what LyX does internally
5452 and how things are rendered externally remains in force, and the two can
5453 be controlled separately.
5455 \begin_inset CommandInset ref
5457 reference "sec:Tags-for-XHTML"
5464 \begin_layout Section
5465 Installing new LaTeX files
5468 \begin_layout Standard
5469 Some installations may not include a LaTeX package or class file that you
5470 would like to use within LyX.
5471 For example, you might need FoilTeX, a package for preparing slides for
5472 overhead projectors.
5473 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5474 a user interface for installing such packages.
5475 For example, with MiKTeX, you start the program
5476 \begin_inset Quotes eld
5480 \begin_inset space ~
5484 \begin_inset Quotes erd
5487 to get a list of available packages.
5488 To install one of them, right click on it or use the corresponding toolbar
5492 \begin_layout Standard
5493 If your LaTeX distribution does not provide such a `package manager', or
5494 if the package is not available from your distribution, then follow these
5495 steps to install it manually:
5498 \begin_layout Enumerate
5499 Get the package from
5500 \begin_inset CommandInset href
5503 target "http://www.ctan.org/"
5510 \begin_layout Enumerate
5511 If the package contains a file with the ending
5512 \begin_inset Quotes eld
5516 \begin_inset Flex Code
5519 \begin_layout Plain Layout
5526 \begin_inset Quotes erd
5529 (is the case for FoilTeX) then open a console, change to the folder of
5530 this file and execute the command
5531 \begin_inset Flex Code
5534 \begin_layout Plain Layout
5541 You have now unpacked the package and have all files to install it.
5542 Most LaTeX-packages are not packed and you can skip this step.
5545 \begin_layout Enumerate
5546 Now you need to decide if the package should be available for all users
5551 \begin_layout Enumerate
5552 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5553 for all users on your system, then install it in your `local' TeX tree,
5554 otherwise install it in your own `user' TeX tree.
5555 Where these trees should be created, if they do not already exist, depends
5557 To find this out, look in the file
5558 \begin_inset Flex Code
5561 \begin_layout Plain Layout
5571 \begin_layout Plain Layout
5572 This is usually in the directory
5573 \begin_inset Flex Code
5576 \begin_layout Plain Layout
5582 , though you can execute the command
5583 \begin_inset Flex Code
5586 \begin_layout Plain Layout
5597 The location of the `local' TeX tree is defined by the
5598 \begin_inset Flex Code
5601 \begin_layout Plain Layout
5607 variable; this is usually somewhere like
5608 \begin_inset Flex Code
5611 \begin_layout Plain Layout
5612 /usr/local/share/texmf
5618 The location of the `user' TeX tree is defined by
5619 \begin_inset Flex Code
5622 \begin_layout Plain Layout
5629 \begin_inset Flex Code
5632 \begin_layout Plain Layout
5639 (If these variables are not predefined, you have to define them.) You'll
5640 probably need root permissions to create or modify the `local' tree, but
5641 not for your `user' tree.
5642 \begin_inset Newline newline
5645 In general, it is recommended to install in the user tree because your user
5646 will not be modified or even overwritten when you upgrade your system.
5647 It will typically also be backed up together with everything else when
5648 you backup your home directory (which, of course, you do on a regular basis).
5651 \begin_layout Enumerate
5652 On Windows, if you want the new package to be available for all users on
5653 your system, change to the folder where LaTeX is installed and then change
5655 \begin_inset Flex Code
5658 \begin_layout Plain Layout
5669 (For MiKTeX, this would be by default the folder
5670 \begin_inset Flex Code
5673 \begin_layout Plain Layout
5691 \begin_layout Plain Layout
5692 Note that this will be the correct path only on English installations.
5693 On a German one, it would be
5694 \begin_inset Flex Code
5697 \begin_layout Plain Layout
5711 , and similarly for other languages.
5716 Create there a new folder
5717 \begin_inset Flex Code
5720 \begin_layout Plain Layout
5726 and copy all files of the package into it.
5728 \begin_inset Newline newline
5731 If the package should only available for you or you don't have admin permissions
5732 , do the same, but in the local LaTeX folder.
5734 \begin_inset space \thinspace{}
5738 \begin_inset space ~
5741 2.8 under Windows XP, this would be the folder:
5742 \begin_inset Newline newline
5748 \begin_inset Flex Code
5751 \begin_layout Plain Layout
5754 Documents and Settings
5766 \begin_inset Newline newline
5772 \begin_inset Phantom HPhantom
5775 \begin_layout Plain Layout
5786 \begin_inset Flex Code
5789 \begin_layout Plain Layout
5802 \begin_inset Newline newline
5805 On Vista, it would be:
5806 \begin_inset Newline newline
5810 \begin_inset Flex Code
5813 \begin_layout Plain Layout
5839 \begin_layout Enumerate
5840 Now one only need to tell LaTeX that there are new files.
5841 This depends on the used LaTeX-Distribution:
5845 \begin_layout Enumerate
5846 For TeXLive execute the command
5847 \begin_inset Flex Code
5850 \begin_layout Plain Layout
5857 If you installed the package for all users, then you will probably need
5858 to have root permissions for that.
5861 \begin_layout Enumerate
5862 For MiKTeX, if you have installed the package for all users, start the program
5864 \begin_inset Quotes eld
5868 \begin_inset space ~
5872 \begin_inset Quotes erd
5875 and press the button marked
5876 \begin_inset Quotes eld
5880 \begin_inset Quotes erd
5884 Otherwise start the program
5885 \begin_inset Quotes eld
5889 \begin_inset Quotes erd
5896 \begin_layout Enumerate
5897 Finally, you need to tell LyX that there are new packages available.
5898 So, in LyX, use the menu
5899 \begin_inset Flex MenuItem
5902 \begin_layout Plain Layout
5905 \SpecialChar \menuseparator
5911 and then restart LyX.
5914 \begin_layout Standard
5915 Now the package is installed.
5916 In our example, the document class
5917 \begin_inset Flex Code
5920 \begin_layout Plain Layout
5922 \begin_inset space ~
5929 \begin_layout Plain Layout
5941 will now be available under
5942 \begin_inset Flex MenuItem
5945 \begin_layout Plain Layout
5946 Document\SpecialChar \menuseparator
5947 Settings\SpecialChar \menuseparator
5957 \begin_layout Standard
5958 If you would like to use a LaTeX document class that is not even listed
5960 \begin_inset Flex MenuItem
5963 \begin_layout Plain Layout
5964 Document\SpecialChar \menuseparator
5965 Settings\SpecialChar \menuseparator
5971 , then you need to create a `layout' file for it.
5972 That is the topic of the next section.
5975 \begin_layout Section
5976 Types of layout files
5979 \begin_layout Standard
5980 This section describes the various sorts of LyX files that contain layout
5982 These files describe various paragraph and character styles, determining
5983 how LyX should display them and how they should be translated into LaTeX,
5984 DocBook, XHTML, or whatever output format is being used.
5988 \begin_layout Standard
5989 We shall try to provide a thorough description of the process of writing
5991 However, there are so many different types of documents supported even
5992 by just LaTeX that we can't hope to cover every different possibility or
5993 problem you might encounter.
5994 The LyX users' list is frequented by people with lots of experience with
5995 layout design who are willing to share what they've learned, so please
5996 feel free to ask questions there.
5999 \begin_layout Standard
6000 As you prepare to write a new layout, it is extremely helpful to look at
6001 the layouts distributed with LyX.
6002 If you write a LyX layout for a LaTeX document class that might also be
6003 used by others, or write a module that might be useful to others, then
6004 you should consider posting your layout to the
6005 \begin_inset CommandInset href
6007 name "layout section on the LyX wiki"
6008 target "http://wiki.lyx.org/Layouts/Layouts"
6012 or even to the LyX developers' list, so that it might be included in LyX
6017 \begin_layout Plain Layout
6018 Note that LyX is licensed under the General Public License, so any material
6019 that is contributed to LyX must be similarly licensed.
6027 \begin_layout Subsection
6029 \begin_inset CommandInset label
6031 name "sub:Layout-modules"
6038 \begin_layout Standard
6039 We have spoken to this point about `layout files'.
6040 But there are different sorts of files that contain layout information.
6041 Layout files, strictly so called, have the
6042 \begin_inset Flex Code
6045 \begin_layout Plain Layout
6051 extension and provide LyX with information about document classes.
6052 As of LyX 1.6, however, layout information can also be contained in layout
6058 \begin_inset Flex Code
6061 \begin_layout Plain Layout
6068 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6069 some modules—such as the
6070 \begin_inset Flex Code
6073 \begin_layout Plain Layout
6079 module—specifcally provide support for one package.
6080 In a sense, layout modules are similar to included
6084 \begin_layout Plain Layout
6085 These can have any extension, but by convention have the
6086 \begin_inset Flex Code
6089 \begin_layout Plain Layout
6101 \begin_inset Flex Code
6104 \begin_layout Plain Layout
6110 —in that modules are not specific to a given document class but may be used
6111 with many different classes.
6112 The difference is that using an included file with
6113 \begin_inset Flex Code
6116 \begin_layout Plain Layout
6122 requires editing that file.
6123 Modules, by contrast, are selected in the
6124 \begin_inset Flex MenuItem
6127 \begin_layout Plain Layout
6128 Document\SpecialChar \menuseparator
6137 \begin_layout Standard
6138 Building modules is the easiest way to get started with layout editing,
6139 since it can be as simple as adding a single new paragraph style or flex
6141 But modules may, in principle, contain anything a layout file can contain.
6144 \begin_layout Standard
6145 After creating a new module and copying it to the
6146 \begin_inset Flex Code
6149 \begin_layout Plain Layout
6155 folder, you will need to reconfigure and then restart LyX for the module
6156 to appear in the menu.
6157 However, changes you make to the module will be seen immediately, if you
6159 \begin_inset Flex MenuItem
6162 \begin_layout Plain Layout
6163 Document\SpecialChar \menuseparator
6169 , highlight something, and then hit
6170 \begin_inset Quotes eld
6174 \begin_inset Quotes erd
6180 It is strongly recommended that you save your work before doing this
6185 it is strongly recommended that you not attempt to edit modules while simultaneo
6186 usly working on actual documents
6189 Though of course the developers strive to keep LyX stable in such situations,
6190 syntax errors and the like in your module file could cause strange behavior.
6193 \begin_layout Subsection
6195 \begin_inset Flex MenuItem
6198 \begin_layout Plain Layout
6207 \begin_layout Standard
6208 There are two situations you are likely to encounter when wanting to support
6209 a new LaTeX document class, involving LaTeX2e class (
6210 \begin_inset Flex Code
6213 \begin_layout Plain Layout
6220 \begin_inset Flex Code
6223 \begin_layout Plain Layout
6230 Supporting a style file is usually fairly easy.
6231 Supporting a new class file is a bit harder.
6232 We'll discuss the former in this section and the latter in the next.
6233 Similar remarks apply, of course, if you want to support a new DocBook
6237 \begin_layout Standard
6238 The easier case is the one in which your new document class is provided
6239 as a style file that is to be used in conjunction with an already supported
6241 For the sake of the example, we'll assume that the style file is called
6243 \begin_inset Flex MenuItem
6246 \begin_layout Plain Layout
6252 and that it is meant to be used with
6253 \begin_inset Flex MenuItem
6256 \begin_layout Plain Layout
6262 , which is a standard class.
6266 \begin_layout Standard
6267 Start by copying the existing class's layout file into your local directory:
6271 \begin_layout Plain Layout
6272 Of course, which directory is your local directory will vary by platform,
6273 and LyX allows you to specify your local directory on startup, too, using
6275 \begin_inset Flex Code
6278 \begin_layout Plain Layout
6292 \begin_layout LyX-Code
6293 cp report.layout ~/.lyx/layouts/myclass.layout
6296 \begin_layout Standard
6298 \begin_inset Flex Code
6301 \begin_layout Plain Layout
6307 and change the line:
6310 \begin_layout LyX-Code
6313 DeclareLaTeXClass{report}
6316 \begin_layout Standard
6320 \begin_layout LyX-Code
6323 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6326 \begin_layout Standard
6330 \begin_layout LyX-Code
6332 \begin_inset Newline newline
6338 \begin_inset Newline newline
6344 \begin_layout Standard
6345 near the top of the file.
6348 \begin_layout Standard
6349 Start LyX and select
6350 \begin_inset Flex MenuItem
6353 \begin_layout Plain Layout
6354 Tools\SpecialChar \menuseparator
6361 Then restart LyX and try creating a new document.
6363 \begin_inset Flex MenuItem
6366 \begin_layout Plain Layout
6372 " as a document class option in the
6373 \begin_inset Flex MenuItem
6376 \begin_layout Plain Layout
6377 Document\SpecialChar \menuseparator
6384 It is likely that some of the sectioning commands and such in your new
6385 class will work differently from how they worked in the base class—
6386 \begin_inset Flex Code
6389 \begin_layout Plain Layout
6395 in this example—so you can fiddle around with the settings for the different
6396 sections if you wish.
6397 The layout information for sections is contained in
6398 \begin_inset Flex Code
6401 \begin_layout Plain Layout
6407 , but you do not need to copy and change this file.
6408 Instead, you can simply add your changes to your layout file, after the
6410 \begin_inset Flex Code
6413 \begin_layout Plain Layout
6419 , which itself includes
6420 \begin_inset Flex Code
6423 \begin_layout Plain Layout
6430 For example, you might add these lines:
6433 \begin_layout LyX-Code
6437 \begin_layout LyX-Code
6441 \begin_layout LyX-Code
6445 \begin_layout LyX-Code
6449 \begin_layout LyX-Code
6453 \begin_layout Standard
6454 to change the font for chapter headings to sans-serif.
6455 This will override (or, in this case, add to) the existing declaration
6456 for the Chapter style.
6460 \begin_layout Standard
6461 Your new package may also provide commands or environments not present in
6463 In this case, you will want to add these to the layout file.
6465 \begin_inset CommandInset ref
6467 reference "sec:TextClass"
6471 for information on how to do so.
6474 \begin_layout Standard
6476 \begin_inset Flex MenuItem
6479 \begin_layout Plain Layout
6485 can be used with several different document classes, and even if it cannot,
6486 you might find it easiest just to write a module that you can load with
6488 The simplest possible such module would be:
6491 \begin_layout LyX-Code
6494 DeclareLyXModule{My Package}
6497 \begin_layout LyX-Code
6501 \begin_layout LyX-Code
6502 #Support for mypkg.sty.
6505 \begin_layout LyX-Code
6507 \begin_inset Newline newline
6513 \begin_layout LyX-Code
6515 \begin_inset Newline newline
6521 \begin_layout LyX-Code
6523 \begin_inset Newline newline
6529 \begin_inset Newline newline
6535 \begin_layout Standard
6536 A more complex module might modify the behavior of some existing constructs
6537 or define some new ones.
6539 \begin_inset CommandInset ref
6541 reference "sec:TextClass"
6548 \begin_layout Subsection
6550 \begin_inset Flex MenuItem
6553 \begin_layout Plain Layout
6562 \begin_layout Standard
6563 There are two possibilities here.
6564 One is that the class file is itself based upon an existing document class.
6565 For example, many thesis classes are based upon
6566 \begin_inset Flex MenuItem
6569 \begin_layout Plain Layout
6576 To see whether yours is, look for a line like
6579 \begin_layout LyX-Code
6585 \begin_layout Standard
6587 If so, then you may proceed largely as in the previous section, though
6589 \begin_inset Flex Code
6592 \begin_layout Plain Layout
6598 line will be different.
6599 If your new class is
6600 \begin_inset Flex Code
6603 \begin_layout Plain Layout
6609 and it is based upon
6610 \begin_inset Flex Code
6613 \begin_layout Plain Layout
6619 , then the line should read:
6623 \begin_layout Plain Layout
6624 And it will be easiest if you save the file to
6625 \begin_inset Flex Code
6628 \begin_layout Plain Layout
6634 : LyX assumes that the document class has the same name as the layout file.
6643 \begin_layout LyX-Code
6646 DeclareLaTeXClass[thesis,book]{thesis}
6649 \begin_layout Standard
6650 If, on the other hand, the new class is not based upon an existing class,
6651 you will probably have to
6652 \begin_inset Quotes eld
6656 \begin_inset Quotes erd
6660 We strongly suggest copying an existing layout file which uses a similar
6661 LaTeX class and then modifying it, if you can do so.
6662 At least use an existing file as a starting point so you can find out what
6663 items you need to worry about.
6664 Again, the specifics are covered below.
6667 \begin_layout Subsection
6669 \begin_inset CommandInset label
6671 name "sub:Creating-Templates"
6678 \begin_layout Standard
6679 Once you have written a layout file for a new document class, you might
6680 want to consider writing a
6685 A template acts as a kind of tutorial for your layout, showing how it might
6686 be used, though containing dummy content.
6687 You can of course look at the various templates included with LyX for ideas.
6690 \begin_layout Standard
6691 Templates are created just like usual documents: using LyX.
6692 The only difference is that usual documents contain all possible settings,
6693 including the font scheme and the paper size.
6694 Usually a user doesn't want a template to overwrite his preferred settings
6695 for such parameters.
6696 For that reason, the designer of a template should remove the corresponding
6698 \begin_inset Flex Code
6701 \begin_layout Plain Layout
6710 \begin_inset Flex Code
6713 \begin_layout Plain Layout
6721 from the template LyX file.
6722 This can be done with any simple text-editor, for example
6723 \begin_inset Flex Code
6726 \begin_layout Plain Layout
6733 \begin_inset Flex Code
6736 \begin_layout Plain Layout
6746 \begin_layout Standard
6747 Put the edited template files you create in
6748 \begin_inset Flex Code
6751 \begin_layout Plain Layout
6757 , copy the ones you use from the global template directory in
6758 \begin_inset Flex Code
6761 \begin_layout Plain Layout
6767 to the same place, and redefine the template path in the
6768 \begin_inset Flex MenuItem
6771 \begin_layout Plain Layout
6772 Tools\SpecialChar \menuseparator
6773 Preferences\SpecialChar \menuseparator
6782 \begin_layout Standard
6783 Note, by the way, that there is a template which has a particular meaning:
6785 \begin_inset Flex Code
6788 \begin_layout Plain Layout
6795 This template is loaded every time you create a new document with
6796 \begin_inset Flex MenuItem
6799 \begin_layout Plain Layout
6800 File\SpecialChar \menuseparator
6806 in order to provide useful defaults.
6807 To create this template from inside LyX, all you have to do is to open
6808 a document with the correct settings, and use the
6809 \begin_inset Flex MenuItem
6812 \begin_layout Plain Layout
6813 Save as Document Defaults
6821 \begin_layout Subsection
6822 Upgrading old layout files
6825 \begin_layout Standard
6826 The format of layout files changes with each LyX release, so old layout
6827 files need to be converted to the new format.
6828 This process has been automated since LyX 1.4: If LyX reads a layout file
6829 in an older format, it automatically calls the script
6830 \begin_inset Flex Code
6833 \begin_layout Plain Layout
6839 to convert it to a temporary file in current format.
6840 The original file is left untouched.
6841 If you use the layout file often, then, you may want to convert it permanently,
6842 so that LyX does not have to do so itself every time.
6843 To do this, you can call the converter manually:
6846 \begin_layout LyX-Code
6847 mv myclass.layout myclass.old
6850 \begin_layout LyX-Code
6851 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
6854 \begin_layout Standard
6856 \begin_inset Flex Code
6859 \begin_layout Plain Layout
6865 with the name of your LyX system directory, of course.
6868 \begin_layout Standard
6869 Note that manual conversion does not affect included files, so these will
6870 have to be converted separately.
6873 \begin_layout Section
6874 \begin_inset CommandInset label
6876 name "sec:TextClass"
6880 The layout file format
6883 \begin_layout Standard
6884 When it's finally time to get your hands dirty and create or edit your own
6885 layout file, the following sections describe what you're up against.
6886 Our advice is to go slowly, save and test often, listen to soothing music,
6887 and enjoy one or two of your favorite adult beverages; more if you are
6888 getting particularly stuck.
6889 It's really not that hard, except that the multitude of options can become
6890 overwhelming if you try to do too much in one sitting.
6891 Go have another adult beverage, just for good measure.
6894 \begin_layout Standard
6895 Note that all the tags used in layout files are case-insensitive.
6897 \begin_inset Flex Code
6900 \begin_layout Plain Layout
6907 \begin_inset Flex Code
6910 \begin_layout Plain Layout
6917 \begin_inset Flex Code
6920 \begin_layout Plain Layout
6926 are really the same tag.
6927 The possible values are printed in brackets after the feature's name.
6928 The default value if a feature isn't specified inside a text class-description
6930 \begin_inset Flex Code
6933 \begin_layout Plain Layout
6942 If the argument has a data type like
6943 \begin_inset Quotes eld
6947 \begin_inset Quotes erd
6951 \begin_inset Quotes eld
6955 \begin_inset Quotes erd
6958 , the default is shown like this:
6959 \begin_inset Flex Code
6962 \begin_layout Plain Layout
6973 \begin_layout Subsection
6974 The document class declaration
6977 \begin_layout Standard
6978 Lines in a layout file which begin with
6979 \begin_inset Flex Code
6982 \begin_layout Plain Layout
6989 There is one exception to this rule.
6991 \begin_inset Flex Code
6994 \begin_layout Plain Layout
7000 files should begin with a line like:
7003 \begin_layout LyX-Code
7006 #% Do not delete the line below; configure depends on this
7009 \begin_layout LyX-Code
7014 DeclareLaTeXClass{article}
7017 \begin_layout Standard
7018 The second line is used when you (re)configure LyX.
7019 The layout file is read by the LaTeX script
7020 \begin_inset Flex Code
7023 \begin_layout Plain Layout
7029 , in a special mode where
7030 \begin_inset Flex Code
7033 \begin_layout Plain Layout
7040 The first line is just a LaTeX comment, and the second one contains the
7041 declaration of the text class.
7042 If these lines appear in a file named
7043 \begin_inset Flex Code
7046 \begin_layout Plain Layout
7052 , then they define a text class of name
7053 \begin_inset Flex Code
7056 \begin_layout Plain Layout
7062 (the name of the layout file) which uses the LaTeX document class
7063 \begin_inset Flex Code
7066 \begin_layout Plain Layout
7072 (the default is to use the same name as the layout).
7074 \begin_inset Quotes eld
7078 \begin_inset Quotes erd
7081 that appears above is used as a description of the text class in the
7082 \begin_inset Flex MenuItem
7085 \begin_layout Plain Layout
7086 Document\SpecialChar \menuseparator
7095 \begin_layout Standard
7096 Let's assume that you wrote your own text class that uses the
7097 \begin_inset Flex Code
7100 \begin_layout Plain Layout
7106 document class, but where you changed the appearance of the section headings.
7107 If you put it in a file
7108 \begin_inset Flex Code
7111 \begin_layout Plain Layout
7117 , the header of this file should be:
7120 \begin_layout LyX-Code
7123 #% Do not delete the line below; configure depends on this
7126 \begin_layout LyX-Code
7131 DeclareLaTeXClass[article]{article (with my own headings)}
7134 \begin_layout Standard
7135 This declares a text class
7136 \begin_inset Flex Code
7139 \begin_layout Plain Layout
7145 , associated with the LaTeX document class
7146 \begin_inset Flex Code
7149 \begin_layout Plain Layout
7156 \begin_inset Quotes eld
7159 article (with my own headings)
7160 \begin_inset Quotes erd
7164 If your text class depends on several packages, you can declare it as:
7167 \begin_layout LyX-Code
7170 #% Do not delete the line below; configure depends on this
7173 \begin_layout LyX-Code
7178 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7181 \begin_layout Standard
7182 This indicates that your text class uses the
7183 \begin_inset Flex Code
7186 \begin_layout Plain Layout
7193 Finally, it is also possible to declare classes for DocBook code.
7194 Typical declarations will look like:
7197 \begin_layout LyX-Code
7200 #% Do not delete the line below; configure depends on this
7203 \begin_layout LyX-Code
7208 DeclareDocBookClass[article]{SGML (DocBook article)}
7211 \begin_layout Standard
7212 Note that these declarations can also be given an optional parameter declaring
7213 the name of the document class (but not a list).
7216 \begin_layout Standard
7217 So, to be as explicit as possible, the form of the layout declaration is:
7220 \begin_layout LyX-Code
7225 DeclareLaTeXClass[class,package.sty]{layout description}
7228 \begin_layout Standard
7229 The class need only be specified if the name of the LaTeX class file and
7230 the name of the layout file are different or if there are packages to load.
7231 If the name of the class file is not specified, then LyX will simply assume
7232 that it is the same as the name of the layout file.
7235 \begin_layout Standard
7236 When the text class has been modified to your taste, all you have to do
7237 is to copy it either to
7238 \begin_inset Flex Code
7241 \begin_layout Plain Layout
7248 \begin_inset Flex Code
7251 \begin_layout Plain Layout
7258 \begin_inset Flex MenuItem
7261 \begin_layout Plain Layout
7262 Tools\SpecialChar \menuseparator
7268 , exit LyX and restart.
7269 Then your new text class should be available along with the others.
7272 \begin_layout Standard
7273 Once the layout file is installed, you can edit it and see your changes
7274 without having to reconfigure or to restart LyX.
7279 \begin_layout Plain Layout
7280 In versions of LyX prior to 1.6, this was not true.
7281 As a result, editing layout files was very time consuming, since you had
7282 constantly to restart LyX to see changes.
7287 You can force a reload of the current layout by using the LyX function
7289 \begin_inset Flex MenuItem
7292 \begin_layout Plain Layout
7299 There is no default binding for this function—though, of course, you can
7300 bind it to a key yourself.
7301 But you will normally use this function simply by entering it in the mini-buffe
7306 \begin_layout Standard
7312 \begin_inset Flex MenuItem
7315 \begin_layout Plain Layout
7321 is very much an `advanced feature'.
7326 recommended that you save your work before using this function.
7331 recommended that you not attempt to edit layout information while simultaneousl
7332 y working on a document that you care about.
7333 Use a test document.
7334 Syntax errors and the like in your layout file could cause peculiar behavior.
7335 In particular, such errors could cause LyX to regard the current layout
7336 as invalid and to attempt to switch to some other layout.
7340 \begin_layout Plain Layout
7341 Really bad syntax errors may even caused LyX to exit.
7342 This is because certain sorts of errors may make LyX unable to read
7352 The LyX team strives to keep LyX stable in such situations, but safe is
7357 \begin_layout Plain Layout
7358 While we're giving advice: make regular backups.
7359 And be nice to your mother.
7367 \begin_layout Subsection
7368 The Module declaration
7371 \begin_layout Standard
7372 A module must begin with a line like the following:
7375 \begin_layout LyX-Code
7378 DeclareLyXModule[endnotes.sty]{Endnotes}
7381 \begin_layout Standard
7382 The mandatory argument, in curly brackets, is the name of the module, as
7384 \begin_inset Flex MenuItem
7387 \begin_layout Plain Layout
7388 Document\SpecialChar \menuseparator
7395 The argument in square brackets is optional: It declares any LaTeX packages
7396 on which the module depends.
7397 Please note that only packages about which LyX knows should be listed in
7398 the square brackets.
7402 \begin_layout Plain Layout
7403 The list of such packages is documented only in the source code.
7408 LyX will not check for arbitrary packages.
7409 It is also possible to use the form
7410 \begin_inset Flex MenuItem
7413 \begin_layout Plain Layout
7419 as an optional argument, which declares that the module can only be used
7420 when there exists a conversion chain between the formats `
7421 \begin_inset Flex Code
7424 \begin_layout Plain Layout
7431 \begin_inset Flex Code
7434 \begin_layout Plain Layout
7443 \begin_layout Standard
7444 The module declaration should then be followed by lines like the following:
7447 \begin_layout LyX-Code
7451 \begin_layout LyX-Code
7452 #Adds an endnote command, in addition to footnotes.
7456 \begin_layout LyX-Code
7457 #You will need to add
7459 theendnotes in TeX code where you
7462 \begin_layout LyX-Code
7463 #want the endnotes to appear.
7467 \begin_layout LyX-Code
7471 \begin_layout LyX-Code
7472 #Requires: somemodule | othermodule
7475 \begin_layout LyX-Code
7476 #Excludes: badmodule
7479 \begin_layout Standard
7480 The description is used in
7481 \begin_inset Flex MenuItem
7484 \begin_layout Plain Layout
7485 Document\SpecialChar \menuseparator
7491 to provide the user with information about what the module does.
7493 \begin_inset Flex Code
7496 \begin_layout Plain Layout
7502 line is used to identify other modules with which this one must be used;
7504 \begin_inset Flex Code
7507 \begin_layout Plain Layout
7513 line is used to identify modules with which this one may not be used.
7514 Both are optional, and, as shown, multiple modules should be separated
7515 with the pipe symbol: |.
7516 Note that the required modules are treated disjunctively:
7520 of the required modules must be used.
7525 excluded module may be used.
7526 Note that modules are identified here by their
7531 \begin_inset Flex Code
7534 \begin_layout Plain Layout
7542 \begin_inset Flex Code
7545 \begin_layout Plain Layout
7552 \begin_inset Flex Code
7555 \begin_layout Plain Layout
7564 \begin_layout Subsection
7568 \begin_layout Standard
7569 The first non-comment line of any layout file, included file, or module
7574 contain the file format number:
7577 \begin_layout Description
7578 \begin_inset Flex Code
7581 \begin_layout Plain Layout
7588 \begin_inset Flex Code
7591 \begin_layout Plain Layout
7597 ] The format of the layout file.
7600 \begin_layout Standard
7601 This tag was introduced with LyX 1.4.0.
7602 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7603 and are considered to be of format 1.
7604 The format for the present version of LyX is format 21.
7605 But each version of LyX is capable of reading earlier versions' layout
7606 files, just as they are capable of reading files produced by earlier versions
7608 There is, however, no provision for converting to earlier formats.
7609 So LyX 1.6.x will not read layout files in format 21 but only files in format
7613 \begin_layout Subsection
7614 \begin_inset CommandInset label
7616 name "sub:General-text-class"
7620 General text class parameters
7623 \begin_layout Standard
7624 These are general parameters that govern the behavior of an entire document
7630 mean that they must appear in
7631 \begin_inset Flex Code
7634 \begin_layout Plain Layout
7640 files rather than in modules.
7641 A module can contain any layout tag.)
7644 \begin_layout Description
7645 \begin_inset Flex Code
7648 \begin_layout Plain Layout
7654 Adds information that will be output in the
7655 \begin_inset Flex Code
7658 \begin_layout Plain Layout
7664 block when this document class is output to XHTML.
7665 Typically, this would be used to output CSS style information, but it can
7666 be used for anything that can appear in
7667 \begin_inset Flex Code
7670 \begin_layout Plain Layout
7678 \begin_inset Quotes eld
7682 \begin_inset Flex Code
7685 \begin_layout Plain Layout
7692 \begin_inset Quotes erd
7698 \begin_layout Description
7699 \begin_inset Flex Code
7702 \begin_layout Plain Layout
7708 Adds information to the document preamble.
7710 \begin_inset Quotes eld
7714 \begin_inset Flex Code
7717 \begin_layout Plain Layout
7724 \begin_inset Quotes erd
7730 \begin_layout Description
7731 \begin_inset Flex Code
7734 \begin_layout Plain Layout
7740 Defines formats for use in the display of bibliographic information.
7742 \begin_inset CommandInset ref
7744 reference "sub:Citation-format-description"
7750 \begin_inset Quotes eld
7754 \begin_inset Flex Code
7757 \begin_layout Plain Layout
7764 \begin_inset Quotes erd
7770 \begin_layout Description
7771 \begin_inset Flex Code
7774 \begin_layout Plain Layout
7780 Describes various global options supported by the document class.
7782 \begin_inset space ~
7786 \begin_inset CommandInset ref
7788 reference "sub:ClassOptions"
7794 \begin_inset Quotes eld
7798 \begin_inset Flex Code
7801 \begin_layout Plain Layout
7808 \begin_inset Quotes erd
7814 \begin_layout Description
7815 \begin_inset Flex Code
7818 \begin_layout Plain Layout
7825 \begin_inset Flex Code
7828 \begin_layout Plain Layout
7837 \begin_inset Flex Code
7840 \begin_layout Plain Layout
7846 ] Whether the class should
7850 to having one or two columns.
7851 Can be changed in the
7852 \begin_inset Flex MenuItem
7855 \begin_layout Plain Layout
7856 Document\SpecialChar \menuseparator
7865 \begin_layout Description
7866 \begin_inset Flex Code
7869 \begin_layout Plain Layout
7876 \begin_inset Flex Code
7879 \begin_layout Plain Layout
7885 ] This sequence defines the properties for a counter.
7886 If the counter does not yet exist, it is created; if it does exist, it
7889 \begin_inset Quotes eld
7893 \begin_inset Flex Code
7896 \begin_layout Plain Layout
7903 \begin_inset Quotes erd
7907 \begin_inset Newline newline
7911 \begin_inset space ~
7915 \begin_inset CommandInset ref
7917 reference "sub:Counters"
7921 for details on counters.
7924 \begin_layout Description
7925 \begin_inset Flex Code
7928 \begin_layout Plain Layout
7934 Sets the default font used to display the document.
7936 \begin_inset space ~
7940 \begin_inset CommandInset ref
7942 reference "sub:Font-description"
7946 for how to declare fonts.
7948 \begin_inset Quotes eld
7952 \begin_inset Flex Code
7955 \begin_layout Plain Layout
7962 \begin_inset Quotes erd
7968 \begin_layout Description
7969 \begin_inset Flex Code
7972 \begin_layout Plain Layout
7979 \begin_inset Flex Code
7982 \begin_layout Plain Layout
7988 Specifies a module to be included by default with this document class.
7989 The module should be specified by filename without the
7990 \begin_inset Flex Code
7993 \begin_layout Plain Layout
8000 The user can still remove the module, but it will be active at the outset.
8001 (This applies only when new files are created, or when this class is chosen
8002 for an existing document.)
8005 \begin_layout Description
8006 \begin_inset Flex Code
8009 \begin_layout Plain Layout
8016 \begin_inset Flex Code
8019 \begin_layout Plain Layout
8025 ] This is the style that will be assigned to new paragraphs, usually
8026 \begin_inset Flex MenuItem
8029 \begin_layout Plain Layout
8036 This will default to the first defined style if not given, but you are
8037 encouraged to use this directive.
8040 \begin_layout Description
8041 \begin_inset Flex Code
8044 \begin_layout Plain Layout
8051 \begin_inset Flex Code
8054 \begin_layout Plain Layout
8060 ] This tag indicates that the module in question—which should be specified
8061 by filename without the
8062 \begin_inset Flex Code
8065 \begin_layout Plain Layout
8071 extension—cannot be used with this document class.
8072 This might be used in a journal-specific layout file to prevent, say, the
8074 \begin_inset Flex Code
8077 \begin_layout Plain Layout
8083 module that numbers theorems by section.
8088 be used in a module.
8089 Modules have their own way of excluding other modules (see
8090 \begin_inset CommandInset ref
8092 reference "sub:Layout-modules"
8099 \begin_layout Description
8100 \begin_inset Flex Code
8103 \begin_layout Plain Layout
8109 Defines a new float.
8111 \begin_inset space ~
8115 \begin_inset CommandInset ref
8117 reference "sub:Floats"
8123 \begin_inset Quotes eld
8127 \begin_inset Flex Code
8130 \begin_layout Plain Layout
8137 \begin_inset Quotes erd
8143 \begin_layout Description
8144 \begin_inset Flex Code
8147 \begin_layout Plain Layout
8153 Sets the information that will be output in the
8154 \begin_inset Flex Code
8157 \begin_layout Plain Layout
8163 block when this document class is output to XHTML.
8164 Note that this will completely override any prior
8165 \begin_inset Flex Code
8168 \begin_layout Plain Layout
8175 \begin_inset Flex Code
8178 \begin_layout Plain Layout
8186 \begin_inset Flex Code
8189 \begin_layout Plain Layout
8195 if you just want to add material to the preamble.) Must end with
8196 \begin_inset Quotes eld
8200 \begin_inset Flex Code
8203 \begin_layout Plain Layout
8210 \begin_inset Quotes erd
8216 \begin_layout Description
8217 \begin_inset Flex Code
8220 \begin_layout Plain Layout
8227 \begin_inset Flex Code
8230 \begin_layout Plain Layout
8236 ] The layout to use for the table of contents, bibliography, and so forth,
8237 when the document is output to HTML.
8238 For articles, this should normally be Section; for books, Chapter.
8239 If it is not given, then LyX will attempt to figure out which layout to
8243 \begin_layout Description
8244 \begin_inset Flex Code
8247 \begin_layout Plain Layout
8254 \begin_inset Flex Code
8257 \begin_layout Plain Layout
8263 ] Modifies the properties of the given counter.
8264 If the counter does not exist, the section is ignored.
8266 \begin_inset Quotes eld
8270 \begin_inset Flex Code
8273 \begin_layout Plain Layout
8280 \begin_inset Quotes erd
8284 \begin_inset Newline newline
8288 \begin_inset space ~
8292 \begin_inset CommandInset ref
8294 reference "sub:Counters"
8298 for details on counters.
8301 \begin_layout Description
8302 \begin_inset Flex Code
8305 \begin_layout Plain Layout
8312 \begin_inset Flex Code
8315 \begin_layout Plain Layout
8321 ] Modifies the properties of the given paragraph style.
8322 If the style does not exist, the section is ignored.
8324 \begin_inset Quotes eld
8328 \begin_inset Flex Code
8331 \begin_layout Plain Layout
8338 \begin_inset Quotes erd
8344 \begin_layout Description
8345 \begin_inset Flex Code
8348 \begin_layout Plain Layout
8354 As its name implies, this command allows you to include another layout
8355 definition file within yours to avoid duplicating commands.
8356 Common examples are the standard layout files, for example,
8357 \begin_inset Flex Code
8360 \begin_layout Plain Layout
8366 , which contains most of the basic layouts.
8369 \begin_layout Description
8370 \begin_inset Flex Code
8373 \begin_layout Plain Layout
8379 This section (re-)defines the layout of an inset.
8380 It can be applied to an existing inset or to a new, user-defined inset,
8381 e.g., a new character style.
8383 \begin_inset Quotes eld
8387 \begin_inset Flex Code
8390 \begin_layout Plain Layout
8397 \begin_inset Quotes erd
8401 \begin_inset Newline newline
8405 \begin_inset space ~
8409 \begin_inset CommandInset ref
8411 reference "sub:Flex-insets-and"
8415 for more information.
8419 \begin_layout Description
8420 \begin_inset Flex Code
8423 \begin_layout Plain Layout
8430 \begin_inset Flex Code
8433 \begin_layout Plain Layout
8439 ] A string that indicates the width of the left margin on the screen, for
8441 \begin_inset Quotes eld
8445 \begin_inset Quotes erd
8449 (Note that this is not a `length', like
8450 \begin_inset Quotes eld
8454 \begin_inset Quotes erd
8460 \begin_layout Description
8461 \begin_inset Flex Code
8464 \begin_layout Plain Layout
8470 This command deletes an existing float.
8471 This is particularly useful when you want to suppress a float that has
8472 been defined in an input file.
8475 \begin_layout Description
8476 \begin_inset Flex Code
8479 \begin_layout Plain Layout
8485 This command deletes an existing style.
8486 This is particularly useful when you want to suppress a style that has
8487 be defined in an input file.
8490 \begin_layout Description
8491 \begin_inset Flex Code
8494 \begin_layout Plain Layout
8500 A string indicating the file format (as defined in the Preferences dialog)
8501 produced by this class.
8502 It is mainly useful when
8503 \begin_inset Flex Code
8506 \begin_layout Plain Layout
8512 is `literate' and one wants to define a new type of literate document.
8513 This string is reset to `docbook', `latex', or `literate' when the correspondin
8515 \begin_inset Flex Code
8518 \begin_layout Plain Layout
8524 parameter is encountered.
8527 \begin_layout Description
8528 \begin_inset Flex Code
8531 \begin_layout Plain Layout
8537 A string indicating what sort of output documents using this class will
8539 At present, the options are: `docbook', `latex', and `literate'.
8542 \begin_layout Description
8543 \begin_inset Flex Code
8546 \begin_layout Plain Layout
8553 \begin_inset Flex Code
8556 \begin_layout Plain Layout
8565 \begin_inset Flex Code
8568 \begin_layout Plain Layout
8575 \begin_inset Flex Code
8578 \begin_layout Plain Layout
8584 ] The default pagestyle.
8585 Can be changed in the
8586 \begin_inset Flex MenuItem
8589 \begin_layout Plain Layout
8590 Document\SpecialChar \menuseparator
8599 \begin_layout Description
8600 \begin_inset Flex Code
8603 \begin_layout Plain Layout
8609 Sets the preamble for the LaTeX document.
8610 Note that this will completely override any prior
8611 \begin_inset Flex Code
8614 \begin_layout Plain Layout
8621 \begin_inset Flex Code
8624 \begin_layout Plain Layout
8632 \begin_inset Flex Code
8635 \begin_layout Plain Layout
8641 if you just want to add material to the preamble.) Must end with
8642 \begin_inset Quotes eld
8646 \begin_inset Flex Code
8649 \begin_layout Plain Layout
8656 \begin_inset Quotes erd
8662 \begin_layout Description
8663 \begin_inset Flex Code
8666 \begin_layout Plain Layout
8673 \begin_inset Flex Code
8676 \begin_layout Plain Layout
8683 \begin_inset Flex Code
8686 \begin_layout Plain Layout
8695 \begin_inset Flex Code
8698 \begin_layout Plain Layout
8704 ] Whether the class already provides the feature
8705 \begin_inset Flex Code
8708 \begin_layout Plain Layout
8715 A feature is in general the name of a package (
8716 \begin_inset Flex Code
8719 \begin_layout Plain Layout
8726 \begin_inset Flex Code
8729 \begin_layout Plain Layout
8735 , \SpecialChar \ldots{}
8737 \begin_inset Flex Code
8740 \begin_layout Plain Layout
8747 \begin_inset Flex Code
8750 \begin_layout Plain Layout
8756 ,\SpecialChar \ldots{}
8757 ); the complete list of supported features is unfortunately not documented
8758 outside the LyX source code—but see
8759 \begin_inset Flex Code
8762 \begin_layout Plain Layout
8768 if you're interested.
8770 \begin_inset Flex MenuItem
8773 \begin_layout Plain Layout
8774 Help\SpecialChar \menuseparator
8780 also gives an overview of the supported packages.
8783 \begin_layout Description
8784 \begin_inset Flex Code
8787 \begin_layout Plain Layout
8794 \begin_inset Flex Code
8797 \begin_layout Plain Layout
8803 ] Indicates that this layout provides the functionality of the module mentioned,
8804 which should be specified by the filename without the
8805 \begin_inset Flex Code
8808 \begin_layout Plain Layout
8815 This will typically be used if the layout includes the module directly,
8816 rather than using the
8817 \begin_inset Flex Code
8820 \begin_layout Plain Layout
8826 tag to indicate that it ought to be used.
8827 It could also be used in a module that provided an alternate implementation
8828 of the same functionality.
8831 \begin_layout Description
8832 \begin_inset Flex Code
8835 \begin_layout Plain Layout
8842 \begin_inset Flex Code
8845 \begin_layout Plain Layout
8851 ] Whether the class requires the feature
8852 \begin_inset Flex Code
8855 \begin_layout Plain Layout
8862 Multiple features must be separated by commas.
8863 Note that you can only request supported features.
8865 \begin_inset Flex Code
8868 \begin_layout Plain Layout
8874 for a list of these.)
8877 \begin_layout Description
8878 \begin_inset Flex Code
8881 \begin_layout Plain Layout
8887 A string that indicates the width of the right margin on the screen, for
8889 \begin_inset Quotes eld
8893 \begin_inset Quotes erd
8899 \begin_layout Description
8900 \begin_inset Flex Code
8903 \begin_layout Plain Layout
8909 Sets which divisions get numbered.
8911 \begin_inset Flex Code
8914 \begin_layout Plain Layout
8923 \begin_layout Description
8924 \begin_inset Flex Code
8927 \begin_layout Plain Layout
8934 \begin_inset Flex Code
8937 \begin_layout Plain Layout
8946 \begin_inset Flex Code
8949 \begin_layout Plain Layout
8955 ] Whether the class-default should be printing on one or both sides of the
8957 Can be changed in the
8958 \begin_inset Flex MenuItem
8961 \begin_layout Plain Layout
8962 Document\SpecialChar \menuseparator
8971 \begin_layout Description
8972 \begin_inset Flex Code
8975 \begin_layout Plain Layout
8981 This sequence defines a paragraph style.
8982 If the style does not yet exist, it is created; if it does exist, its parameter
8985 \begin_inset Quotes eld
8989 \begin_inset Flex Code
8992 \begin_layout Plain Layout
8999 \begin_inset Quotes erd
9003 \begin_inset Newline newline
9007 \begin_inset space ~
9011 \begin_inset CommandInset ref
9013 reference "sub:Paragraph-Styles"
9017 for details on paragraph styles.
9020 \begin_layout Description
9021 \begin_inset Flex Code
9024 \begin_layout Plain Layout
9031 \begin_inset Flex Code
9034 \begin_layout Plain Layout
9040 ] The name of the command or environment to be used with
9041 \begin_inset Flex Code
9044 \begin_layout Plain Layout
9053 \begin_layout Description
9054 \begin_inset Flex Code
9057 \begin_layout Plain Layout
9064 \begin_inset Flex Code
9067 \begin_layout Plain Layout
9076 \begin_inset Flex Code
9079 \begin_layout Plain Layout
9085 ] Indicates what kind of markup is used to define the title of a document.
9087 \begin_inset Flex Code
9090 \begin_layout Plain Layout
9096 means that the macro with name
9097 \begin_inset Flex Code
9100 \begin_layout Plain Layout
9106 will be inserted after the last layout which has
9107 \begin_inset Quotes eld
9111 \begin_inset Flex Code
9114 \begin_layout Plain Layout
9121 \begin_inset Quotes erd
9126 \begin_inset Flex Code
9129 \begin_layout Plain Layout
9135 corresponds to the case where the block of paragraphs which have
9136 \begin_inset Quotes eld
9140 \begin_inset Flex Code
9143 \begin_layout Plain Layout
9150 \begin_inset Quotes erd
9153 should be enclosed into the
9154 \begin_inset Flex Code
9157 \begin_layout Plain Layout
9166 \begin_layout Description
9167 \begin_inset Flex Code
9170 \begin_layout Plain Layout
9176 Sets which divisions are included in the table of contents.
9178 \begin_inset Flex Code
9181 \begin_layout Plain Layout
9190 \begin_layout Subsection
9191 \begin_inset Flex Code
9194 \begin_layout Plain Layout
9201 \begin_inset CommandInset label
9203 name "sub:ClassOptions"
9210 \begin_layout Standard
9212 \begin_inset Flex Code
9215 \begin_layout Plain Layout
9221 section can contain the following entries:
9224 \begin_layout Description
9225 \begin_inset Flex Code
9228 \begin_layout Plain Layout
9235 \begin_inset Flex Code
9238 \begin_layout Plain Layout
9244 ] The list of available font sizes for the document's main font, separated
9246 \begin_inset Quotes eld
9250 \begin_inset Flex Code
9253 \begin_layout Plain Layout
9260 \begin_inset Quotes erd
9266 \begin_layout Description
9267 \begin_inset Flex Code
9270 \begin_layout Plain Layout
9276 Used to set the DTD line with XML-based output classes.
9278 \begin_inset space \thinspace{}
9282 \begin_inset Quotes eld
9285 -//OASIS//DTD DocBook V4.2//EN
9286 \begin_inset Quotes erd
9292 \begin_layout Description
9293 \begin_inset Flex Code
9296 \begin_layout Plain Layout
9303 \begin_inset Flex Code
9306 \begin_layout Plain Layout
9307 string="empty|plain|headings|fancy"
9312 ] The list of available page styles, separated by
9313 \begin_inset Quotes eld
9317 \begin_inset Flex Code
9320 \begin_layout Plain Layout
9327 \begin_inset Quotes erd
9333 \begin_layout Description
9334 \begin_inset Flex Code
9337 \begin_layout Plain Layout
9344 \begin_inset Flex Code
9347 \begin_layout Plain Layout
9353 ] Some document class options, separated by a comma, that will be added
9354 to the optional part of the
9355 \begin_inset Flex Code
9358 \begin_layout Plain Layout
9369 \begin_layout Standard
9371 \begin_inset Flex Code
9374 \begin_layout Plain Layout
9380 section must end with
9381 \begin_inset Quotes eld
9385 \begin_inset Flex Code
9388 \begin_layout Plain Layout
9395 \begin_inset Quotes erd
9401 \begin_layout Subsection
9403 \begin_inset CommandInset label
9405 name "sub:Paragraph-Styles"
9412 \begin_layout Standard
9413 A paragraph style description looks like this:
9417 \begin_layout Plain Layout
9418 Note that this will either define a new layout or modify an existing one.
9426 \begin_layout LyX-Code
9433 \begin_layout LyX-Code
9437 \begin_layout LyX-Code
9441 \begin_layout Standard
9442 where the following commands are allowed:
9445 \begin_layout Description
9446 \begin_inset Flex Code
9449 \begin_layout Plain Layout
9456 \begin_inset Flex Code
9459 \begin_layout Plain Layout
9464 , left, right, center
9469 ] Paragraph alignment.
9472 \begin_layout Description
9473 \begin_inset Flex Code
9476 \begin_layout Plain Layout
9483 \begin_inset Flex Code
9486 \begin_layout Plain Layout
9491 , left, right, center
9496 ] A comma separated list of permitted alignments.
9497 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9499 For example a right-aligned or centered enumeration isn't possible.)
9502 \begin_layout Description
9503 \begin_inset Flex Code
9506 \begin_layout Plain Layout
9512 Note that this will completely override any prior
9513 \begin_inset Flex Code
9516 \begin_layout Plain Layout
9522 declaration for this style.
9524 \begin_inset Quotes eld
9528 \begin_inset Flex Code
9531 \begin_layout Plain Layout
9538 \begin_inset Quotes erd
9543 \begin_inset CommandInset ref
9545 reference "sub:I18n"
9549 for details on its use.
9552 \begin_layout Description
9553 \begin_inset Flex Code
9556 \begin_layout Plain Layout
9563 \begin_inset Flex Code
9566 \begin_layout Plain Layout
9576 \begin_layout Plain Layout
9577 Note that a `float' here is a real number, such as: 1.5.
9582 The vertical space with which the last of a chain of paragraphs with this
9583 layout is separated from the following paragraph.
9584 If the next paragraph has another layout, the separations are not simply
9585 added, but the maximum is taken.
9588 \begin_layout Description
9589 \begin_inset Flex Code
9592 \begin_layout Plain Layout
9599 \begin_inset Flex Code
9602 \begin_layout Plain Layout
9608 The category for this style.
9609 This is used to group related styles in the Layout combobox on the toolbar.
9610 Any string can be used, but you may want to use existing categories with
9615 \begin_layout Description
9616 \begin_inset Flex Code
9619 \begin_layout Plain Layout
9625 Depth of XML command.
9626 Used only with XML-type formats.
9629 \begin_layout Description
9630 \begin_inset Flex Code
9633 \begin_layout Plain Layout
9640 \begin_inset CommandInset label
9642 name "des:CopyStyle"
9647 \begin_inset Flex Code
9650 \begin_layout Plain Layout
9656 Copies all the features of an existing style into the current one.
9660 \begin_layout Description
9661 \begin_inset Flex Code
9664 \begin_layout Plain Layout
9670 The name of a style whose preamble should be output
9675 This allows to ensure some ordering of the preamble snippets when macros
9676 definitions depend on one another.
9680 \begin_layout Plain Layout
9681 Note that, besides that functionality, there is no way to ensure any ordering
9683 The ordering that you see in a given version of LyX may change without
9684 warning in later versions.
9692 \begin_layout Description
9693 \begin_inset Flex Code
9696 \begin_layout Plain Layout
9703 \begin_inset Flex Code
9706 \begin_layout Plain Layout
9711 , Box, Filled_Box, Static
9716 ] The type of label that stands at the end of the paragraph (or sequence
9718 \begin_inset Flex Code
9721 \begin_layout Plain Layout
9728 \begin_inset Flex Code
9731 \begin_layout Plain Layout
9738 \begin_inset Flex Code
9741 \begin_layout Plain Layout
9748 \begin_inset Flex Code
9751 \begin_layout Plain Layout
9759 \begin_inset Flex Code
9762 \begin_layout Plain Layout
9769 \begin_inset Quotes eld
9773 \begin_inset Quotes erd
9777 \begin_inset Flex Code
9780 \begin_layout Plain Layout
9787 \begin_inset Flex Code
9790 \begin_layout Plain Layout
9791 \begin_inset space ~
9800 \begin_inset space ~
9803 black) square suitable for end of proof markers,
9804 \begin_inset Flex Code
9807 \begin_layout Plain Layout
9813 is an explicit text string.
9816 \begin_layout Description
9817 \begin_inset Flex Code
9820 \begin_layout Plain Layout
9827 \begin_inset Flex Code
9830 \begin_layout Plain Layout
9836 ] The string used for a label with a
9837 \begin_inset Flex Code
9840 \begin_layout Plain Layout
9847 \begin_inset Flex Code
9850 \begin_layout Plain Layout
9860 \begin_layout Description
9861 \begin_inset Flex Code
9864 \begin_layout Plain Layout
9871 \begin_inset Flex Code
9874 \begin_layout Plain Layout
9885 \begin_inset Flex Code
9888 \begin_layout Plain Layout
9897 \begin_layout Description
9898 \begin_inset Flex Code
9901 \begin_layout Plain Layout
9908 \begin_inset Flex Code
9911 \begin_layout Plain Layout
9921 ] With this parameter the
9922 \begin_inset Flex MenuItem
9925 \begin_layout Plain Layout
9932 \begin_inset Quotes eld
9935 Vertical space above
9936 \begin_inset Quotes erd
9940 \begin_inset Flex MenuItem
9943 \begin_layout Plain Layout
9944 Edit\SpecialChar \menuseparator
9946 \begin_inset space ~
9954 dialog can be set when initializing a paragraph with this style.
9958 \begin_layout Plain Layout
9961 Note from Jean-Marc:
9963 I'm not sure that this setting has much use, and it should probably be
9964 removed in later versions.
9972 \begin_layout Description
9973 \begin_inset Flex Code
9976 \begin_layout Plain Layout
9982 The font used for both the text body
9988 \begin_inset space ~
9992 \begin_inset CommandInset ref
9994 reference "sub:Font-description"
9999 Note that defining this font automatically defines the
10000 \begin_inset Flex Code
10003 \begin_layout Plain Layout
10010 So you should define this one first if you also want to define
10011 \begin_inset Flex Code
10014 \begin_layout Plain Layout
10023 \begin_layout Description
10024 \begin_inset Flex Code
10027 \begin_layout Plain Layout
10034 \begin_inset CommandInset label
10036 name "des:FreeSpacing"
10041 \begin_inset Flex Code
10044 \begin_layout Plain Layout
10053 \begin_inset Flex Code
10056 \begin_layout Plain Layout
10062 ] Usually LyX doesn't allow you to insert more than one space between words,
10063 since a space is considered as the separation between two words, not a
10064 character or symbol of its own.
10065 This is a very fine thing but sometimes annoying, for example, when typing
10066 program code or plain LaTeX code.
10068 \begin_inset Flex Code
10071 \begin_layout Plain Layout
10078 Note that LyX will create protected blanks for the additional blanks when
10079 in another mode than LaTeX-mode.
10082 \begin_layout Description
10083 \begin_inset Flex Code
10086 \begin_layout Plain Layout
10092 These tags are used with XHTML output.
10094 \begin_inset CommandInset ref
10096 reference "sub:Paragraph-Style-XHTML"
10103 \begin_layout Description
10104 \begin_inset Flex Code
10107 \begin_layout Plain Layout
10113 [[FIXME]] (Used only with XML-type formats.)
10116 \begin_layout Description
10117 \begin_inset Flex Code
10120 \begin_layout Plain Layout
10127 \begin_inset Flex Code
10130 \begin_layout Plain Layout
10136 If 1, marks the layout as to be included in the document preamble rather
10137 than in the document body.
10138 This is useful for document classes that want such information as the title
10139 and author to appear in the preamble.
10140 Note that this works only for layouts for which the
10141 \begin_inset Flex Code
10144 \begin_layout Plain Layout
10151 \begin_inset Flex Code
10154 \begin_layout Plain Layout
10163 \begin_layout Description
10164 \begin_inset Flex Code
10167 \begin_layout Plain Layout
10174 \begin_inset Flex Code
10177 \begin_layout Plain Layout
10183 If 1, marks the layout as being part of a title block (see also the
10184 \begin_inset Flex Code
10187 \begin_layout Plain Layout
10194 \begin_inset Flex Code
10197 \begin_layout Plain Layout
10206 \begin_layout Description
10207 \begin_inset Flex Code
10210 \begin_layout Plain Layout
10217 \begin_inset Flex Code
10220 \begin_layout Plain Layout
10226 ] This provides extra space between paragraphs that have the same layout.
10227 If you put other layouts into an environment, each is separated with the
10229 \begin_inset Flex Code
10232 \begin_layout Plain Layout
10239 But the whole items of the environment are additionally separated with
10241 \begin_inset Flex Code
10244 \begin_layout Plain Layout
10251 Note that this is a
10256 \begin_layout Description
10257 \begin_inset Flex Code
10260 \begin_layout Plain Layout
10266 [[FIXME]] (Used only with XML-type formats.)
10269 \begin_layout Description
10270 \begin_inset Flex Code
10273 \begin_layout Plain Layout
10280 \begin_inset CommandInset label
10282 name "des:KeepEmpty"
10287 \begin_inset Flex Code
10290 \begin_layout Plain Layout
10299 \begin_inset Flex Code
10302 \begin_layout Plain Layout
10308 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10309 lead to empty LaTeX output.
10310 There are some cases where this could be desirable however: in a letter
10311 template, the required fields can be provided as empty fields, so that
10312 people do not forget them; in some special classes, a layout can be used
10313 as some kind of break, which does not contain actual text.
10316 \begin_layout Description
10317 \begin_inset Flex Code
10320 \begin_layout Plain Layout
10326 [float=0] The vertical space between the label and the text body.
10327 Only used for labels that are above the text body (
10328 \begin_inset Flex Code
10331 \begin_layout Plain Layout
10338 \begin_inset Flex Code
10341 \begin_layout Plain Layout
10342 Centered_Top_Environment
10350 \begin_layout Description
10351 \begin_inset Flex Code
10354 \begin_layout Plain Layout
10361 \begin_inset Flex Code
10364 \begin_layout Plain Layout
10371 \begin_inset Newline newline
10374 The name of the counter for automatic numbering.
10376 \begin_inset Newline newline
10384 \begin_inset Flex Code
10387 \begin_layout Plain Layout
10394 \begin_inset Flex Code
10397 \begin_layout Plain Layout
10404 In that case, the counter will be stepped each time the layout appears.
10406 \begin_inset Newline newline
10414 \begin_inset Flex Code
10417 \begin_layout Plain Layout
10424 \begin_inset Flex Code
10427 \begin_layout Plain Layout
10433 , though this case is a bit complicated.
10434 Suppose you declare
10435 \begin_inset Quotes eld
10439 \begin_inset Flex Code
10442 \begin_layout Plain Layout
10443 LabelCounter myenum
10449 \begin_inset Quotes erd
10453 Then the actual counters used are
10454 \begin_inset Flex Code
10457 \begin_layout Plain Layout
10464 \begin_inset Flex Code
10467 \begin_layout Plain Layout
10474 \begin_inset Flex Code
10477 \begin_layout Plain Layout
10484 \begin_inset Flex Code
10487 \begin_layout Plain Layout
10493 , much as in LaTeX.
10494 These counters must all be declared separately.
10495 \begin_inset Newline newline
10499 \begin_inset CommandInset ref
10501 reference "sub:Counters"
10505 for details on counters.
10508 \begin_layout Description
10509 \begin_inset Flex Code
10512 \begin_layout Plain Layout
10518 The font used for the label.
10520 \begin_inset space ~
10524 \begin_inset CommandInset ref
10526 reference "sub:Font-description"
10533 \begin_layout Description
10534 \begin_inset Flex Code
10537 \begin_layout Plain Layout
10543 Text that indicates how far a label should be indented.
10546 \begin_layout Description
10547 \begin_inset Flex Code
10550 \begin_layout Plain Layout
10557 \begin_inset Flex Code
10560 \begin_layout Plain Layout
10566 ] The horizontal space between the label and the text body.
10567 Only used for labels that are not above the text body.
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 string used for a label with a
10591 \begin_inset Flex Code
10594 \begin_layout Plain Layout
10602 \begin_inset Flex Code
10605 \begin_layout Plain Layout
10611 is set, this string can be contain the special formatting commands described
10613 \begin_inset CommandInset ref
10615 reference "sub:Counters"
10623 \begin_layout Plain Layout
10624 For the sake of backwards compatibility, the string
10625 \begin_inset Flex Code
10628 \begin_layout Plain Layout
10638 will be replaced by the expanded
10639 \begin_inset Flex Code
10642 \begin_layout Plain Layout
10649 \begin_inset Flex Code
10652 \begin_layout Plain Layout
10661 This feature is now obsolete and should be replaced by the mechanisms of
10663 \begin_inset CommandInset ref
10665 reference "sub:Counters"
10677 \begin_layout Description
10678 \begin_inset Flex Code
10681 \begin_layout Plain Layout
10682 LabelStringAppendix
10688 \begin_inset Flex Code
10691 \begin_layout Plain Layout
10697 ] This is used inside the appendix instead of
10698 \begin_inset Flex Code
10701 \begin_layout Plain Layout
10709 \begin_inset Flex Code
10712 \begin_layout Plain Layout
10719 \begin_inset Flex Code
10722 \begin_layout Plain Layout
10723 LabelStringAppendix
10731 \begin_layout Description
10732 \begin_inset Flex Code
10735 \begin_layout Plain Layout
10741 [FIXME] (Used only with XML-type formats.)
10744 \begin_layout Description
10745 \begin_inset Flex Code
10748 \begin_layout Plain Layout
10755 \begin_inset Flex Code
10758 \begin_layout Plain Layout
10763 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10764 Enumerate, Itemize, Bibliography
10773 \begin_layout Itemize
10774 \begin_inset Flex Code
10777 \begin_layout Plain Layout
10783 means the label is the very first word (up to the first real blank).
10784 Use protected spaces (like
10785 \begin_inset space ~
10788 that one) if you want more than one word as the label.
10792 \begin_layout Itemize
10793 \begin_inset Flex Code
10796 \begin_layout Plain Layout
10802 means the label is simply whatever
10803 \begin_inset Flex Code
10806 \begin_layout Plain Layout
10813 Note that this really is `static'.
10816 \begin_layout Itemize
10817 \begin_inset Flex Code
10820 \begin_layout Plain Layout
10827 \begin_inset Flex Code
10830 \begin_layout Plain Layout
10831 Centered_Top_Environment
10836 are special cases of
10837 \begin_inset Flex Code
10840 \begin_layout Plain Layout
10847 The label will be printed above the paragraph, but only at the top of an
10848 environment or the top of a chain of paragraphs with this layout.
10849 This might be used with the
10850 \begin_inset Flex MenuItem
10853 \begin_layout Plain Layout
10859 layout, for example.
10862 \begin_layout Itemize
10863 \begin_inset Flex Code
10866 \begin_layout Plain Layout
10872 is a special case for the caption-labels
10873 \begin_inset Quotes eld
10877 \begin_inset Quotes erd
10881 \begin_inset Quotes eld
10885 \begin_inset Quotes erd
10890 \begin_inset Flex Code
10893 \begin_layout Plain Layout
10899 means the (hardcoded) label string depends on the kind of float: It is
10900 hardcoded to be `FloatType N', where N is the value of the counter associated
10904 \begin_layout Itemize
10906 \begin_inset Flex Code
10909 \begin_layout Plain Layout
10915 label type defines automatically numbered labels.
10917 \begin_inset Flex Code
10920 \begin_layout Plain Layout
10926 will be expanded to resolve any counter references it contains: For example,
10928 \begin_inset Quotes eld
10932 \begin_inset Flex Code
10935 \begin_layout Plain Layout
10946 \begin_inset Quotes erd
10951 \begin_inset CommandInset ref
10953 reference "sub:Counters"
10957 for more information on counters.
10960 \begin_layout Itemize
10961 \begin_inset Flex Code
10964 \begin_layout Plain Layout
10970 produces the usual sort of enumeration labels.
10971 At present, it is hardcoded to use Arabic numerals, lowercase letters,
10972 small Roman numerals, and uppercase letters for the four possible depths.
10975 \begin_layout Itemize
10976 \begin_inset Flex Code
10979 \begin_layout Plain Layout
10985 produces various bullets at the different levels.
10986 It is also hardcoded.
10989 \begin_layout Itemize
10990 \begin_inset Flex Code
10993 \begin_layout Plain Layout
10999 is used internally by LyX and should be used only with
11000 \begin_inset Flex Code
11003 \begin_layout Plain Layout
11004 LatexType BibEnvironment
11013 \begin_layout Description
11014 \begin_inset Flex Code
11017 \begin_layout Plain Layout
11023 Note that this will completely override any prior
11024 \begin_inset Flex Code
11027 \begin_layout Plain Layout
11033 declaration for this style.
11035 \begin_inset Quotes eld
11039 \begin_inset Flex Code
11042 \begin_layout Plain Layout
11049 \begin_inset Quotes erd
11054 \begin_inset CommandInset ref
11056 reference "sub:I18n"
11060 for details on its use.
11063 \begin_layout Description
11064 \begin_inset Flex Code
11067 \begin_layout Plain Layout
11073 The name of the corresponding LaTeX stuff.
11074 Either the environment or command name.
11077 \begin_layout Description
11078 \begin_inset Flex Code
11081 \begin_layout Plain Layout
11087 An optional parameter for the corresponding
11088 \begin_inset Flex Code
11091 \begin_layout Plain Layout
11098 This parameter cannot be changed from within LyX.
11101 \begin_layout Description
11102 \begin_inset Flex Code
11105 \begin_layout Plain Layout
11112 \begin_inset CommandInset label
11114 name "des:LatexType"
11119 \begin_inset Flex Code
11122 \begin_layout Plain Layout
11127 , Command, Environment, Item_Environment,
11133 \begin_inset Flex Code
11136 \begin_layout Plain Layout
11137 List_Environment, Bib_Environment
11142 ] How the layout should be translated into LaTeX.
11146 \begin_layout Plain Layout
11147 \begin_inset Flex Code
11150 \begin_layout Plain Layout
11156 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11157 Visit the SGML class files for specific examples.
11166 \begin_layout Itemize
11167 \begin_inset Flex Code
11170 \begin_layout Plain Layout
11176 means nothing special.
11180 \begin_layout Itemize
11181 \begin_inset Flex Code
11184 \begin_layout Plain Layout
11191 \begin_inset Flex Code
11194 \begin_layout Plain Layout
11201 {\SpecialChar \ldots{}
11210 \begin_layout Itemize
11211 \begin_inset Flex Code
11214 \begin_layout Plain Layout
11221 \begin_inset Flex Code
11224 \begin_layout Plain Layout
11231 }\SpecialChar \ldots{}
11247 \begin_layout Itemize
11248 \begin_inset Flex Code
11251 \begin_layout Plain Layout
11258 \begin_inset Flex Code
11261 \begin_layout Plain Layout
11268 \begin_inset Flex Code
11271 \begin_layout Plain Layout
11279 is generated for each paragraph of this environment.
11283 \begin_layout Itemize
11284 \begin_inset Flex Code
11287 \begin_layout Plain Layout
11294 \begin_inset Flex Code
11297 \begin_layout Plain Layout
11304 \begin_inset Flex Code
11307 \begin_layout Plain Layout
11313 is passed as an argument to the environment.
11315 \begin_inset Flex Code
11318 \begin_layout Plain Layout
11324 can be defined in the
11325 \begin_inset Flex MenuItem
11328 \begin_layout Plain Layout
11333 ayout\SpecialChar \menuseparator
11347 \begin_layout Standard
11348 Putting the last few things together, the LaTeX output will be either:
11351 \begin_layout LyX-Code
11354 latexname[latexparam]{\SpecialChar \ldots{}
11358 \begin_layout Standard
11362 \begin_layout LyX-Code
11365 begin{latexname}[latexparam] \SpecialChar \ldots{}
11371 \begin_layout Standard
11372 depending upon the LaTeX type.
11376 \begin_layout Description
11377 \begin_inset Flex Code
11380 \begin_layout Plain Layout
11387 \begin_inset Flex Code
11390 \begin_layout Plain Layout
11396 ] If you put layouts into environments, the leftmargins are not simply added,
11397 but added with a factor
11398 \begin_inset Formula $\frac{4}{depth+4}$
11402 Note that this parameter is also used when the margin is defined as
11403 \begin_inset Flex Code
11406 \begin_layout Plain Layout
11413 \begin_inset Flex Code
11416 \begin_layout Plain Layout
11423 Then it is added to the manual or dynamic margin.
11425 \begin_inset Newline newline
11428 The argument is passed as a string.
11430 \begin_inset Quotes eld
11434 \begin_inset Flex Code
11437 \begin_layout Plain Layout
11444 \begin_inset Quotes erd
11447 means that the paragraph is indented with the width of
11448 \begin_inset Quotes eld
11452 \begin_inset Flex Code
11455 \begin_layout Plain Layout
11462 \begin_inset Quotes erd
11465 in the normal font.
11466 You can get a negative width by prefixing the string with
11467 \begin_inset Quotes eld
11471 \begin_inset Flex Code
11474 \begin_layout Plain Layout
11481 \begin_inset Quotes erd
11485 This way was chosen so that the look is the same with each used screen
11490 \begin_layout Description
11491 \begin_inset Flex Code
11494 \begin_layout Plain Layout
11501 \begin_inset Flex Code
11504 \begin_layout Plain Layout
11509 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11515 \begin_inset Newline newline
11518 The kind of margin that the layout has on the left side.
11520 \begin_inset Flex Code
11523 \begin_layout Plain Layout
11529 just means a fixed margin.
11531 \begin_inset Flex Code
11534 \begin_layout Plain Layout
11540 means that the left margin depends on the string entered in the
11541 \begin_inset Flex MenuItem
11544 \begin_layout Plain Layout
11545 Edit\SpecialChar \menuseparator
11547 \begin_inset space ~
11556 This is used to typeset nice lists without tabulators.
11558 \begin_inset Flex Code
11561 \begin_layout Plain Layout
11567 means that the margin depends on the size of the label.
11568 This is used for automatic enumerated headlines.
11569 It is obvious that the headline
11570 \begin_inset Quotes eld
11573 5.4.3.2.1 Very long headline
11574 \begin_inset Quotes erd
11577 must have a wider left margin (as wide as
11578 \begin_inset Quotes eld
11582 \begin_inset Quotes erd
11585 plus the space) than
11586 \begin_inset Quotes eld
11589 3.2 Very long headline
11590 \begin_inset Quotes erd
11594 \begin_inset Quotes eld
11598 \begin_inset Quotes erd
11601 are not able to do this.
11603 \begin_inset Flex Code
11606 \begin_layout Plain Layout
11612 is similar, but only the very first row of the paragraph is dynamic, while
11613 the others are static; this is used, for example, for descriptions.
11615 \begin_inset Flex Code
11618 \begin_layout Plain Layout
11624 means the margin is chosen in a way that the longest row of this paragraph
11625 fits to the right margin.
11626 This is used to typeset an address on the right edge of the page.
11629 \begin_layout Description
11630 \begin_inset Flex Code
11633 \begin_layout Plain Layout
11640 \begin_inset Flex Code
11643 \begin_layout Plain Layout
11652 \begin_inset Flex Code
11655 \begin_layout Plain Layout
11661 ] Whether fragile commands in this layout should be
11662 \begin_inset Flex Code
11665 \begin_layout Plain Layout
11678 whether this command should itself be protected.)
11681 \begin_layout Description
11682 \begin_inset Flex Code
11685 \begin_layout Plain Layout
11692 \begin_inset Flex Code
11695 \begin_layout Plain Layout
11702 \begin_inset Flex Code
11705 \begin_layout Plain Layout
11713 ] Whether newlines are translated into LaTeX newlines (
11714 \begin_inset Flex Code
11717 \begin_layout Plain Layout
11728 The translation can be switched off to allow more comfortable LaTeX editing
11732 \begin_layout Description
11733 \begin_inset Flex Code
11736 \begin_layout Plain Layout
11743 \begin_inset Flex Code
11746 \begin_layout Plain Layout
11753 \begin_inset Flex Code
11756 \begin_layout Plain Layout
11764 ] Whether the following Paragraph is allowed to indent its very first row.
11766 \begin_inset Flex Code
11769 \begin_layout Plain Layout
11775 means that it is not allowed to do so;
11776 \begin_inset Flex Code
11779 \begin_layout Plain Layout
11785 means it could do so if it wants to.
11788 \begin_layout Description
11789 \begin_inset Flex Code
11792 \begin_layout Plain Layout
11798 Name of a layout that has replaced this layout.
11799 This is used to rename a layout, while keeping backward compatibility.
11802 \begin_layout Description
11803 \begin_inset Flex Code
11806 \begin_layout Plain Layout
11813 \begin_inset Flex Code
11816 \begin_layout Plain Layout
11822 ] The number of optional arguments that can be used with this layout.
11823 This is useful for things like section headings, and only makes sense with
11825 Note that, on output, the optional arguments will all precede any required
11826 arguments (see below).
11827 So one can have constructs like:
11831 \begin_layout LyX-Code
11834 mycmd[opt1]{req1}{contents of paragraph}
11837 \begin_layout Standard
11838 but one cannot have things like:
11841 \begin_layout LyX-Code
11844 mycmd[opt1]{req1}[opt2]{contents of paragraph}
11847 \begin_layout Standard
11848 at least, not without ERT (with which you can have anything).
11853 \begin_layout Description
11854 \begin_inset Flex Code
11857 \begin_layout Plain Layout
11864 \begin_inset CommandInset label
11866 name "des:ParbreakIsNewline"
11871 \begin_inset Flex Code
11874 \begin_layout Plain Layout
11883 \begin_inset Flex Code
11886 \begin_layout Plain Layout
11892 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
11893 output, but only by a line break; together with
11894 \begin_inset Flex Code
11897 \begin_layout Plain Layout
11903 , this allows to emulate a plain text editor (like the ERT inset).
11906 \begin_layout Description
11907 \begin_inset Flex Code
11910 \begin_layout Plain Layout
11917 \begin_inset Flex Code
11920 \begin_layout Plain Layout
11926 ] The indent of the very first line of a paragraph.
11928 \begin_inset Flex Code
11931 \begin_layout Plain Layout
11937 will be fixed for a certain layout.
11938 The exception is Standard layout, since the indentation of a Standard layout
11939 paragraph can be prohibited with
11940 \begin_inset Flex Code
11943 \begin_layout Plain Layout
11950 Also, Standard layout paragraphs inside environments use the
11951 \begin_inset Flex Code
11954 \begin_layout Plain Layout
11960 of the environment, not their native one.
11961 For example, Standard paragraphs inside an enumeration are not indented.
11964 \begin_layout Description
11965 \begin_inset Flex Code
11968 \begin_layout Plain Layout
11975 \begin_inset Flex Code
11978 \begin_layout Plain Layout
11984 ] The vertical space between two paragraphs of this layout.
11987 \begin_layout Description
11988 \begin_inset Flex Code
11991 \begin_layout Plain Layout
11998 \begin_inset Flex Code
12001 \begin_layout Plain Layout
12007 ] LyX allows the user to choose either
12008 \begin_inset Quotes eld
12012 \begin_inset Quotes erd
12016 \begin_inset Quotes eld
12020 \begin_inset Quotes erd
12023 to typeset a document.
12025 \begin_inset Quotes eld
12029 \begin_inset Quotes erd
12032 is chosen, this value is completely ignored.
12034 \begin_inset Quotes eld
12038 \begin_inset Quotes erd
12041 is chosen, the parindent of a LaTeXtype
12042 \begin_inset Quotes eld
12046 \begin_inset Quotes erd
12049 layout is ignored and all paragraphs are separated by this parskip argument.
12050 The vertical space is calculated with
12051 \begin_inset Flex Code
12054 \begin_layout Plain Layout
12056 \begin_inset space ~
12065 \begin_inset Flex Code
12068 \begin_layout Plain Layout
12074 is the height of a row with the normal font.
12075 This way, the look stays the same with different screen fonts.
12078 \begin_layout Description
12079 \begin_inset Flex Code
12082 \begin_layout Plain Layout
12089 \begin_inset CommandInset label
12091 name "des:PassThru"
12096 \begin_inset Flex Code
12099 \begin_layout Plain Layout
12108 \begin_inset Flex Code
12111 \begin_layout Plain Layout
12117 ] Whether the contents of this paragraph should be output in raw form, meaning
12118 without special translations that LaTeX would require.
12121 \begin_layout Description
12122 \begin_inset Flex Code
12125 \begin_layout Plain Layout
12132 \begin_inset CommandInset label
12134 name "des:Preamble"
12138 Information to be included in the LaTeX preamble when this style is used.
12139 Used to define macros, load packages, etc., required by this particular
12142 \begin_inset Quotes eld
12146 \begin_inset Flex Code
12149 \begin_layout Plain Layout
12156 \begin_inset Quotes erd
12162 \begin_layout Description
12163 \begin_inset Flex Code
12166 \begin_layout Plain Layout
12173 \begin_inset Flex Code
12176 \begin_layout Plain Layout
12182 ] The prefix to use when creating labels referring to paragraphs of this
12184 This allows the use of formatted references.
12187 \begin_layout Description
12188 \begin_inset Flex Code
12191 \begin_layout Plain Layout
12198 \begin_inset Flex Code
12201 \begin_layout Plain Layout
12207 ] The number of required arguments that the LaTeX command or environment
12208 corresponding to this layout expects.
12209 In the case of a command, these are required arguments
12213 that associated with the content of the paragraph itself.
12214 These do not actually have to be provided: LyX will output empty arguments
12216 Note that optional arguments will be output before required arguments.
12217 See the discussion of the
12218 \begin_inset Flex Code
12221 \begin_layout Plain Layout
12227 tag above for more information.
12230 \begin_layout Description
12231 \begin_inset Flex Code
12234 \begin_layout Plain Layout
12241 \begin_inset Flex Code
12244 \begin_layout Plain Layout
12251 \begin_inset CommandInset label
12253 name "des:Requires"
12257 Whether the layout requires the feature
12258 \begin_inset Flex Code
12261 \begin_layout Plain Layout
12268 See the description of
12269 \begin_inset Flex Code
12272 \begin_layout Plain Layout
12279 \begin_inset CommandInset ref
12280 LatexCommand pageref
12281 reference "des:FreeSpacing"
12285 ) for information on `features'.
12289 \begin_layout Description
12290 \begin_inset Flex Code
12293 \begin_layout Plain Layout
12300 \begin_inset Flex Code
12303 \begin_layout Plain Layout
12310 \begin_inset Flex Code
12313 \begin_layout Plain Layout
12322 \begin_layout Description
12323 \begin_inset Flex Code
12326 \begin_layout Plain Layout
12333 \begin_inset Flex Code
12336 \begin_layout Plain Layout
12341 , onehalf, double, other
12350 ] This defines what the default spacing should be in the layout.
12352 \begin_inset Flex Code
12355 \begin_layout Plain Layout
12362 \begin_inset Flex Code
12365 \begin_layout Plain Layout
12372 \begin_inset Flex Code
12375 \begin_layout Plain Layout
12381 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12382 If you specify the argument
12383 \begin_inset Flex Code
12386 \begin_layout Plain Layout
12392 , then you should also provide a numerical argument which will be the actual
12394 Note that, contrary to other parameters,
12395 \begin_inset Flex Code
12398 \begin_layout Plain Layout
12404 implies the generation of specific LaTeX code, using the package
12407 \begin_inset Flex Code
12410 \begin_layout Plain Layout
12419 \begin_layout Description
12420 \begin_inset Flex Code
12423 \begin_layout Plain Layout
12430 \begin_inset Flex Code
12433 \begin_layout Plain Layout
12440 \begin_inset Flex Code
12443 \begin_layout Plain Layout
12451 ] Spellcheck paragraphs of this style.
12455 \begin_layout Description
12456 \begin_inset Flex Code
12459 \begin_layout Plain Layout
12465 The font used for the text body .
12467 \begin_inset CommandInset ref
12469 reference "sub:Font-description"
12476 \begin_layout Description
12477 \begin_inset Flex Code
12480 \begin_layout Plain Layout
12489 \begin_inset Flex Code
12492 \begin_layout Plain Layout
12502 The level of the style in the table of contents.
12503 This is used for automatic numbering of section headings.
12506 \begin_layout Description
12507 \begin_inset Flex Code
12510 \begin_layout Plain Layout
12517 \begin_inset Flex Code
12520 \begin_layout Plain Layout
12526 ] The vertical space with which the very first of a chain of paragraphs
12527 with this layout is separated from the previous paragraph.
12528 If the previous paragraph has another layout, the separations are not simply
12529 added, but the maximum is taken.
12532 \begin_layout Subsection
12533 \begin_inset CommandInset label
12539 Internationalization of Paragraph Styles
12542 \begin_layout Standard
12543 LyX has long supported internationalization of layout information, but,
12544 until version 2.0, this applied only to the user interface and not to, say,
12546 Thus, French authors were forced to resort to ugly hacks if they wanted
12551 1' instead of `Theorem 1'.
12552 Thanks to Georg Baum, that is no longer the case.
12555 \begin_layout Standard
12557 \begin_inset Flex Code
12560 \begin_layout Plain Layout
12566 defines text that is to appear in the typeset document, it may use
12567 \begin_inset Flex Code
12570 \begin_layout Plain Layout
12577 \begin_inset Flex Code
12580 \begin_layout Plain Layout
12586 to support non-English and even multi-language documents correctly.
12587 The following excerpt (from the
12588 \begin_inset Flex Code
12591 \begin_layout Plain Layout
12597 file) shows how this works:
12600 \begin_layout LyX-Code
12605 \begin_layout LyX-Code
12608 theoremstyle{remark}
12611 \begin_layout LyX-Code
12614 newtheorem{claim}[thm]{
12621 \begin_layout LyX-Code
12625 \begin_layout LyX-Code
12629 \begin_layout LyX-Code
12634 claimname}{_(Claim)}
12637 \begin_layout LyX-Code
12641 \begin_layout LyX-Code
12645 \begin_layout LyX-Code
12654 claimname}{_(Claim)}}
12657 \begin_layout LyX-Code
12662 \begin_layout Standard
12663 In principle, any legal LaTeX may appear in the
12664 \begin_inset Flex Code
12667 \begin_layout Plain Layout
12674 \begin_inset Flex Code
12677 \begin_layout Plain Layout
12683 tags, but in practice they will typically look as they do here.
12684 The key to correct translation of the typeset text is the definition of
12686 \begin_inset Flex Code
12689 \begin_layout Plain Layout
12698 \begin_inset Flex Code
12701 \begin_layout Plain Layout
12713 \begin_layout Standard
12715 \begin_inset Flex Code
12718 \begin_layout Plain Layout
12724 tag provides for internationalization based upon the overall language of
12726 The contents of the tag will be included in the preamble, just as with
12728 \begin_inset Flex Code
12731 \begin_layout Plain Layout
12738 What makes it special is the use of the
12739 \begin_inset Quotes eld
12743 \begin_inset Quotes erd
12747 \begin_inset Flex Code
12750 \begin_layout Plain Layout
12756 , which will be replaced, when LyX produces LaTeX output, with the translation
12757 of its argument into the document language.
12760 \begin_layout Standard
12762 \begin_inset Flex Code
12765 \begin_layout Plain Layout
12771 tag is more complex, since it is meant to provide support for multi-language
12772 documents and so offers an interface to the
12773 \begin_inset Flex Code
12776 \begin_layout Plain Layout
12783 Its contents will be added to the preamble once for each language that
12784 appears in the document.
12785 In this case, the argument to
12786 \begin_inset Flex Code
12789 \begin_layout Plain Layout
12795 will be replaced with its translation into the language in question; the
12797 \begin_inset Flex Code
12800 \begin_layout Plain Layout
12806 is replaced by the language name (as used by the babel package).
12809 \begin_layout Standard
12810 A German document that also included a French section would thus have the
12811 following in the preamble:
12814 \begin_layout LyX-Code
12823 claimname}{Affirmation}}
12831 claimname}{Behauptung}}
12835 claimname}{Behauptung}
12838 \begin_layout Standard
12840 \begin_inset Flex Code
12843 \begin_layout Plain Layout
12849 will then conspire to produce the correct text in the output.
12852 \begin_layout Standard
12853 One important point to note here is that the translations are provided by
12854 LyX itself, through the same mechanism it uses for internationalization
12855 of the user interface.
12856 This means, in effect, that
12857 \begin_inset Flex Code
12860 \begin_layout Plain Layout
12867 \begin_inset Flex Code
12870 \begin_layout Plain Layout
12876 are really only of use in layout files that are provided with LyX, since
12877 text entered in user-created layout files will not be seen by LyX's internation
12878 alization routines.
12879 That said, however, any layout created with the intention that it will
12880 be included with LyX should use these tags where appropriate.
12883 \begin_layout Subsection
12885 \begin_inset CommandInset label
12894 \begin_layout Standard
12895 Since version 1.3.0 of LyX, it is has been both possible and necessary to
12896 define the floats (
12897 \begin_inset Flex MenuItem
12900 \begin_layout Plain Layout
12907 \begin_inset Flex MenuItem
12910 \begin_layout Plain Layout
12916 , \SpecialChar \ldots{}
12917 ) in the text class itself.
12918 Standard floats are included in the file
12919 \begin_inset Flex Code
12922 \begin_layout Plain Layout
12928 , so you may have to do no more than add
12931 \begin_layout LyX-Code
12932 Input stdfloats.inc
12935 \begin_layout Standard
12936 to your layout file.
12937 If you want to implement a text class that proposes some other float types
12938 (like the AGU class bundled with LyX), the information below will hopefully
12942 \begin_layout Description
12943 \begin_inset Flex Code
12946 \begin_layout Plain Layout
12953 \begin_inset Flex Code
12956 \begin_layout Plain Layout
12963 \begin_inset Quotes erd
12967 \begin_inset Quotes erd
12970 ] The file name extension of an auxiliary file for the list of figures (or
12972 LaTeX writes the captions to this file.
12975 \begin_layout Description
12976 \begin_inset Flex Code
12979 \begin_layout Plain Layout
12986 \begin_inset Flex Code
12989 \begin_layout Plain Layout
12996 \begin_inset Quotes erd
13000 \begin_inset Quotes erd
13003 ] The string that will be used in the menus and also for the caption.
13004 This is translated to the current language if babel is used.
13007 \begin_layout Description
13008 \begin_inset Flex Code
13011 \begin_layout Plain Layout
13017 These are used for XHTML output.
13019 \begin_inset CommandInset ref
13021 reference "sec:Tags-for-XHTML"
13028 \begin_layout Description
13029 \begin_inset Flex Code
13032 \begin_layout Plain Layout
13039 \begin_inset Flex Code
13042 \begin_layout Plain Layout
13049 \begin_inset Quotes erd
13053 \begin_inset Quotes erd
13056 ] The command used to generate a list of floats of this type; the leading
13059 ' should be omitted.
13065 \begin_inset Flex Code
13068 \begin_layout Plain Layout
13074 is false, since there is no standard way to generate this command.
13076 \begin_inset Flex Code
13079 \begin_layout Plain Layout
13085 is true, since in that case there is a standard way.
13088 \begin_layout Description
13089 \begin_inset Flex Code
13092 \begin_layout Plain Layout
13099 \begin_inset Flex Code
13102 \begin_layout Plain Layout
13109 \begin_inset Quotes erd
13113 \begin_inset Quotes erd
13116 ] A title for a list of floats of this kind (list of figures, tables, or
13118 It is used for the screen label within LyX; it is passed to LaTeX for use
13119 as the title there; and it is used as the title in XHTML output.
13120 It will be translated to the document language.
13123 \begin_layout Description
13124 \begin_inset Flex Code
13127 \begin_layout Plain Layout
13134 \begin_inset Flex Code
13137 \begin_layout Plain Layout
13144 \begin_inset Flex Code
13147 \begin_layout Plain Layout
13155 ] Indicates whether the float is already defined in the document class or
13156 if we instead need to load
13157 \begin_inset Flex Code
13160 \begin_layout Plain Layout
13166 and use what it provides.
13168 \begin_inset Flex Code
13171 \begin_layout Plain Layout
13178 \begin_inset Flex Code
13181 \begin_layout Plain Layout
13188 It should be set to
13189 \begin_inset Flex Code
13192 \begin_layout Plain Layout
13198 if the float is already defined by the LaTeX document class.
13201 \begin_layout Description
13202 \begin_inset Flex Code
13205 \begin_layout Plain Layout
13212 \begin_inset Flex Code
13215 \begin_layout Plain Layout
13222 \begin_inset Quotes erd
13226 \begin_inset Quotes erd
13229 ] This (optional) argument determines whether floats of this class will
13230 be numbered within some sectional unit of the document.
13231 For example, if within is equal to
13232 \begin_inset Flex Code
13235 \begin_layout Plain Layout
13241 , the floats will be numbered within chapters.
13245 \begin_layout Description
13246 \begin_inset Flex Code
13249 \begin_layout Plain Layout
13256 \begin_inset Flex Code
13259 \begin_layout Plain Layout
13266 \begin_inset Quotes erd
13270 \begin_inset Quotes erd
13273 ] The default placement for the given class of floats.
13274 The string should be as in standard LaTeX:
13275 \begin_inset Flex Code
13278 \begin_layout Plain Layout
13285 \begin_inset Flex Code
13288 \begin_layout Plain Layout
13295 \begin_inset Flex Code
13298 \begin_layout Plain Layout
13305 \begin_inset Flex Code
13308 \begin_layout Plain Layout
13314 for top, bottom, page, and here, respectively.
13318 \begin_layout Plain Layout
13319 Note that the order of these letters in the string is irrelevant, like in
13325 On top of that there is a new type,
13326 \begin_inset Flex Code
13329 \begin_layout Plain Layout
13335 , which does not really correspond to a float, since it means: put it
13336 \begin_inset Quotes eld
13340 \begin_inset Quotes erd
13344 Note however that the
13345 \begin_inset Flex Code
13348 \begin_layout Plain Layout
13354 specifier is special and, because of implementation details, cannot be
13355 used in non-built in float types.
13356 If you do not understand what this means, just use
13357 \begin_inset Quotes eld
13361 \begin_inset Flex Code
13364 \begin_layout Plain Layout
13371 \begin_inset Quotes erd
13377 \begin_layout Description
13378 \begin_inset Flex Code
13381 \begin_layout Plain Layout
13388 \begin_inset Flex Code
13391 \begin_layout Plain Layout
13397 ] The prefix to use when creating labels referring to floats of this type.
13398 This allows the use of formatted references.
13399 Note that you can remove any
13400 \begin_inset Flex Code
13403 \begin_layout Plain Layout
13409 set by a copied style by using the special value
13410 \begin_inset Quotes eld
13414 \begin_inset Quotes erd
13417 , which must be all caps.
13420 \begin_layout Description
13421 \begin_inset Flex Code
13424 \begin_layout Plain Layout
13431 \begin_inset Flex Code
13434 \begin_layout Plain Layout
13441 \begin_inset Quotes erd
13445 \begin_inset Quotes erd
13448 ] The style used when defining the float using
13449 \begin_inset Flex Code
13452 \begin_layout Plain Layout
13463 \begin_layout Description
13464 \begin_inset Flex Code
13467 \begin_layout Plain Layout
13474 \begin_inset Flex Code
13477 \begin_layout Plain Layout
13484 \begin_inset Quotes erd
13488 \begin_inset Quotes erd
13492 \begin_inset Quotes eld
13496 \begin_inset Quotes erd
13499 of the new class of floats, like program or algorithm.
13500 After the appropriate
13501 \begin_inset Flex Code
13504 \begin_layout Plain Layout
13513 \begin_inset Flex Code
13516 \begin_layout Plain Layout
13525 \begin_inset Flex Code
13528 \begin_layout Plain Layout
13539 \begin_layout Standard
13540 Note that defining a float with type
13541 \begin_inset Flex Code
13544 \begin_layout Plain Layout
13552 automatically defines the corresponding counter with name
13553 \begin_inset Flex Code
13556 \begin_layout Plain Layout
13567 \begin_layout Subsection
13568 Flex insets and InsetLayout
13569 \begin_inset CommandInset label
13571 name "sub:Flex-insets-and"
13578 \begin_layout Standard
13579 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
13580 these are called Flex insets.
13584 \begin_layout Standard
13585 Flex insets come in three different kinds:
13588 \begin_layout Itemize
13590 \begin_inset Flex Code
13593 \begin_layout Plain Layout
13599 ): These define semantic markup corresponding to such LaTeX commands as
13601 \begin_inset Flex Code
13604 \begin_layout Plain Layout
13613 \begin_inset Flex Code
13616 \begin_layout Plain Layout
13627 \begin_layout Itemize
13629 \begin_inset Flex Code
13632 \begin_layout Plain Layout
13638 ): These can be used to define custom collapsible insets, similar to TeX
13639 code, footnote, and the like.
13640 An obvious example is an endnote inset, which is defined in the
13641 \begin_inset Flex Code
13644 \begin_layout Plain Layout
13653 \begin_layout Itemize
13655 \begin_inset Flex Code
13658 \begin_layout Plain Layout
13664 ): For use with DocBook classes.
13667 \begin_layout Standard
13668 Flex insets are defined using the
13669 \begin_inset Flex Code
13672 \begin_layout Plain Layout
13678 tag, which shall be explained in a moment.
13681 \begin_layout Standard
13683 \begin_inset Flex Code
13686 \begin_layout Plain Layout
13692 tag also serves another function: It can be used to customize the general
13693 layout of many different types of insets.
13695 \begin_inset Flex Code
13698 \begin_layout Plain Layout
13704 can be used to customize the layout parameters for footnotes, marginal
13705 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
13706 boxes, tables, algorithms, URLs, and optional arguments, as well as to
13707 define Flex insets.
13710 \begin_layout Standard
13712 \begin_inset Flex Code
13715 \begin_layout Plain Layout
13721 definition must begin with a line of the form:
13724 \begin_layout LyX-Code
13728 \begin_layout Standard
13730 \begin_inset Flex Code
13733 \begin_layout Plain Layout
13739 indicates the inset whose layout is being defined, and here there are two
13743 \begin_layout Enumerate
13744 The layout for a pre-existing inset is being modified.
13745 In this case, can be
13746 \begin_inset Flex Code
13749 \begin_layout Plain Layout
13755 any one of the following:
13756 \begin_inset Flex Code
13759 \begin_layout Plain Layout
13766 \begin_inset Flex Code
13769 \begin_layout Plain Layout
13776 \begin_inset Flex Code
13779 \begin_layout Plain Layout
13786 \begin_inset Flex Code
13789 \begin_layout Plain Layout
13796 \begin_inset Flex Code
13799 \begin_layout Plain Layout
13806 \begin_inset Flex Code
13809 \begin_layout Plain Layout
13816 \begin_inset Flex Code
13819 \begin_layout Plain Layout
13826 \begin_inset Flex Code
13829 \begin_layout Plain Layout
13836 \begin_inset Flex Code
13839 \begin_layout Plain Layout
13846 \begin_inset Flex Code
13849 \begin_layout Plain Layout
13856 \begin_inset Flex Code
13859 \begin_layout Plain Layout
13866 \begin_inset Flex Code
13869 \begin_layout Plain Layout
13876 \begin_inset Flex Code
13879 \begin_layout Plain Layout
13886 \begin_inset Flex Code
13889 \begin_layout Plain Layout
13896 \begin_inset Flex Code
13899 \begin_layout Plain Layout
13906 \begin_inset Flex Code
13909 \begin_layout Plain Layout
13916 \begin_inset Flex Code
13919 \begin_layout Plain Layout
13926 \begin_inset Flex Code
13929 \begin_layout Plain Layout
13936 \begin_inset Flex Code
13939 \begin_layout Plain Layout
13946 \begin_inset Flex Code
13949 \begin_layout Plain Layout
13958 \begin_layout Enumerate
13959 The layout for a Flex inset is being defined.
13961 \begin_inset Flex Code
13964 \begin_layout Plain Layout
13970 may be be any valid identifier not used by a pre-existing inset.
13971 The identifier may include spaces, but in that case the whole thing must
13972 be wrapped in quotes.
13973 It may also include a namespace identifier, preceding a colon, such as
13975 \begin_inset Quotes eld
13979 \begin_inset Flex Code
13982 \begin_layout Plain Layout
13989 \begin_inset Quotes erd
13993 Note that the definition of a flex inset
13998 \begin_inset Flex Code
14001 \begin_layout Plain Layout
14007 entry, declaring which type of inset it defines.
14010 \begin_layout Standard
14012 \begin_inset Flex Code
14015 \begin_layout Plain Layout
14021 definition can contain the following entries:
14024 \begin_layout Description
14025 \begin_inset Flex Code
14028 \begin_layout Plain Layout
14034 The color for the inset's background.
14035 The valid colors are defined in
14036 \begin_inset Flex Code
14039 \begin_layout Plain Layout
14048 \begin_layout Description
14049 \begin_inset Flex Code
14052 \begin_layout Plain Layout
14059 \begin_inset Flex Code
14062 \begin_layout Plain Layout
14071 \begin_inset Flex Code
14074 \begin_layout Plain Layout
14080 ] Whether to use the content of the inset as the label, when the inset is
14085 \begin_layout Description
14086 \begin_inset Flex Code
14089 \begin_layout Plain Layout
14095 As with paragraph styles (see page
14096 \begin_inset CommandInset ref
14098 reference "des:CopyStyle"
14105 \begin_layout Description
14106 \begin_inset Flex Code
14109 \begin_layout Plain Layout
14116 \begin_inset Flex Code
14119 \begin_layout Plain Layout
14128 \begin_inset Flex Code
14131 \begin_layout Plain Layout
14137 ] Indicates whether the user may employ the Paragraph Settings dialog to
14138 customize the paragraph.
14141 \begin_layout Description
14142 \begin_inset Flex Code
14145 \begin_layout Plain Layout
14152 \begin_inset Flex Code
14155 \begin_layout Plain Layout
14162 \begin_inset Flex Code
14165 \begin_layout Plain Layout
14172 \begin_inset Flex Code
14175 \begin_layout Plain Layout
14181 , describing the rendering style used for the inset's frame and buttons.
14182 Footnotes generally use
14183 \begin_inset Flex Code
14186 \begin_layout Plain Layout
14192 , ERT insets generally
14193 \begin_inset Flex Code
14196 \begin_layout Plain Layout
14202 , and character styles
14203 \begin_inset Flex Code
14206 \begin_layout Plain Layout
14215 \begin_layout Description
14216 \begin_inset Flex Code
14219 \begin_layout Plain Layout
14225 Required at the end of the InsetLayout declarations.
14228 \begin_layout Description
14229 \begin_inset Flex Code
14232 \begin_layout Plain Layout
14238 The font used for both the text body
14244 \begin_inset space ~
14248 \begin_inset CommandInset ref
14250 reference "sub:Font-description"
14255 Note that defining this font automatically defines the
14256 \begin_inset Flex Code
14259 \begin_layout Plain Layout
14265 to the same value, so define this first and define
14266 \begin_inset Flex Code
14269 \begin_layout Plain Layout
14275 later if you want them to be different.
14278 \begin_layout Description
14279 \begin_inset Flex Code
14282 \begin_layout Plain Layout
14289 \begin_inset Quotes eld
14293 \begin_inset Quotes erd
14296 language, leading to Left-to-Right (latin) output, e.
14297 \begin_inset space \thinspace{}
14301 \begin_inset space \space{}
14304 in TeX code or URL.
14308 \begin_layout Description
14309 \begin_inset Flex Code
14312 \begin_layout Plain Layout
14319 \begin_inset Flex Code
14322 \begin_layout Plain Layout
14331 \begin_inset Flex Code
14334 \begin_layout Plain Layout
14340 ] Indicates whether the PlainLayout should be used or, instead, the user
14341 can change the paragraph style used in the inset.
14345 \begin_layout Description
14346 \begin_inset Flex Code
14349 \begin_layout Plain Layout
14355 As with paragraph styles (see page
14356 \begin_inset CommandInset ref
14357 LatexCommand pageref
14358 reference "des:FreeSpacing"
14366 \begin_layout Description
14367 \begin_inset Flex Code
14370 \begin_layout Plain Layout
14376 These tags control XHTML output.
14378 \begin_inset CommandInset ref
14379 LatexCommand prettyref
14380 reference "sec:Tags-for-XHTML"
14387 \begin_layout Description
14388 \begin_inset Flex Code
14391 \begin_layout Plain Layout
14398 \begin_inset Flex Code
14401 \begin_layout Plain Layout
14410 \begin_inset Flex Code
14413 \begin_layout Plain Layout
14419 ] Whether to include the contents of this inset in the strings generated
14420 for the `Outline' pane.
14421 One would not, for example, want the content of a footnote in a section
14422 header to be included in the TOC displayed in the outline, but one would
14423 normally want the content of a character style displayed.
14424 Default is false: not to include.
14427 \begin_layout Description
14428 \begin_inset Flex Code
14431 \begin_layout Plain Layout
14437 As with paragraph styles (see page
14438 \begin_inset CommandInset ref
14439 LatexCommand pageref
14440 reference "des:KeepEmpty"
14448 \begin_layout Description
14449 \begin_inset Flex Code
14452 \begin_layout Plain Layout
14458 The font used for the label.
14460 \begin_inset space ~
14464 \begin_inset CommandInset ref
14466 reference "sub:Font-description"
14471 Note that this definition can never appear before
14472 \begin_inset Flex Code
14475 \begin_layout Plain Layout
14481 , lest it be ineffective.
14484 \begin_layout Description
14485 \begin_inset Flex Code
14488 \begin_layout Plain Layout
14494 What will be displayed on the button or elsewhere as the inset label.
14495 Some inset types (TeX code and Branch) modify this label on the fly.
14498 \begin_layout Description
14499 \begin_inset Flex Code
14502 \begin_layout Plain Layout
14508 The name of the corresponding LaTeX stuff.
14509 Either the environment or command name.
14512 \begin_layout Description
14513 \begin_inset Flex Code
14516 \begin_layout Plain Layout
14522 The optional parameter for the corresponding
14523 \begin_inset Flex Code
14526 \begin_layout Plain Layout
14532 stuff, including possible bracket pairs like
14533 \begin_inset Flex Code
14536 \begin_layout Plain Layout
14543 This parameter cannot be changed from within LyX.
14546 \begin_layout Description
14547 \begin_inset Flex Code
14550 \begin_layout Plain Layout
14556 As with paragraph styles (see page
14557 \begin_inset CommandInset ref
14558 LatexCommand pageref
14559 reference "des:LatexType"
14566 \begin_layout Description
14567 \begin_inset Flex Code
14570 \begin_layout Plain Layout
14577 \begin_inset Flex Code
14580 \begin_layout Plain Layout
14587 \begin_inset Flex Code
14590 \begin_layout Plain Layout
14597 \begin_inset Flex Code
14600 \begin_layout Plain Layout
14607 \begin_inset Flex Code
14610 \begin_layout Plain Layout
14616 (indicating a dummy definition ending definitions of charstyles, etc).
14617 This entry is required in and is only meaningful for Flex insets.
14618 Among other things, it determines on which menu this inset will appear.
14620 \begin_inset Flex Code
14623 \begin_layout Plain Layout
14630 \begin_inset Flex Code
14633 \begin_layout Plain Layout
14640 \begin_inset Flex Code
14643 \begin_layout Plain Layout
14651 \begin_inset Flex Code
14654 \begin_layout Plain Layout
14660 can be set to true for charstyle insets, if you wish, by setting it
14665 \begin_inset Flex Code
14668 \begin_layout Plain Layout
14677 \begin_layout Description
14678 \begin_inset Flex Code
14681 \begin_layout Plain Layout
14688 \begin_inset Flex Code
14691 \begin_layout Plain Layout
14700 \begin_inset Flex Code
14703 \begin_layout Plain Layout
14709 ] Whether multiple paragraphs are permitted in this inset.
14711 \begin_inset Flex Code
14714 \begin_layout Plain Layout
14720 to the same value and
14721 \begin_inset Flex Code
14724 \begin_layout Plain Layout
14730 to the opposite value.
14731 These can be reset to other values, if they are used
14736 \begin_inset Flex Code
14739 \begin_layout Plain Layout
14749 \begin_layout Description
14750 \begin_inset Flex Code
14753 \begin_layout Plain Layout
14760 \begin_inset Flex Code
14763 \begin_layout Plain Layout
14772 \begin_inset Flex Code
14775 \begin_layout Plain Layout
14781 ] Whether fragile commands in this layout should be
14782 \begin_inset Flex Code
14785 \begin_layout Plain Layout
14798 whether the command should itself be protected.) Default is false.
14801 \begin_layout Description
14802 \begin_inset Flex Code
14805 \begin_layout Plain Layout
14812 \begin_inset Flex Code
14815 \begin_layout Plain Layout
14824 \begin_inset Flex Code
14827 \begin_layout Plain Layout
14833 ] As with paragraph styles (see page
14834 \begin_inset CommandInset ref
14835 LatexCommand pageref
14836 reference "des:ParbreakIsNewline"
14844 \begin_layout Description
14845 \begin_inset Flex Code
14848 \begin_layout Plain Layout
14855 \begin_inset Flex Code
14858 \begin_layout Plain Layout
14867 \begin_inset Flex Code
14870 \begin_layout Plain Layout
14876 ] As with paragraph styles (see page
14877 \begin_inset CommandInset ref
14878 LatexCommand pageref
14879 reference "des:PassThru"
14887 \begin_layout Description
14888 \begin_inset Flex Code
14891 \begin_layout Plain Layout
14897 As with paragraph styles (see page
14898 \begin_inset CommandInset ref
14899 LatexCommand pageref
14900 reference "des:Preamble"
14907 \begin_layout Description
14908 \begin_inset Flex Code
14911 \begin_layout Plain Layout
14918 \begin_inset Flex Code
14921 \begin_layout Plain Layout
14927 ] The prefix to use when creating labels referring to insets of this type.
14928 This allows the use of formatted references.
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 ] As with paragraph styles (see page
14952 \begin_inset CommandInset ref
14953 LatexCommand pageref
14954 reference "des:Requires"
14961 \begin_layout Description
14962 \begin_inset Flex Code
14965 \begin_layout Plain Layout
14972 \begin_inset Flex Code
14975 \begin_layout Plain Layout
14982 \begin_inset Flex Code
14985 \begin_layout Plain Layout
14993 ] Spellcheck the contents of this inset.
14997 \begin_layout Subsection
14999 \begin_inset CommandInset label
15001 name "sub:Counters"
15008 \begin_layout Standard
15009 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15011 \begin_inset Flex MenuItem
15014 \begin_layout Plain Layout
15021 \begin_inset Flex MenuItem
15024 \begin_layout Plain Layout
15030 , \SpecialChar \ldots{}
15031 ) in the text class itself.
15032 The standard counters are defined in the file
15033 \begin_inset Flex Code
15036 \begin_layout Plain Layout
15042 , so you may have to do no more than add
15045 \begin_layout LyX-Code
15046 Input stdcounters.inc
15049 \begin_layout Standard
15050 to your layout file to get them to work.
15051 But if you want to define custom counters, then you can do so.
15052 The counter declaration must begin with:
15055 \begin_layout LyX-Code
15056 Counter CounterName
15059 \begin_layout Standard
15061 \begin_inset Flex Code
15064 \begin_layout Plain Layout
15070 ' is replaced by the name of the counter.
15071 And it must end with
15072 \begin_inset Quotes eld
15076 \begin_inset Flex Code
15079 \begin_layout Plain Layout
15086 \begin_inset Quotes erd
15090 The following parameters can also be used:
15093 \begin_layout Description
15094 \begin_inset Flex Code
15097 \begin_layout Plain Layout
15104 \begin_inset Flex Code
15107 \begin_layout Plain Layout
15114 \begin_inset Quotes erd
15118 \begin_inset Quotes erd
15121 ] When defined, this string defines how the counter is displayed.
15122 Setting this value sets
15123 \begin_inset Flex Code
15126 \begin_layout Plain Layout
15127 LabelStringAppendix
15133 The following special constructs can be used in the string:
15137 \begin_layout Itemize
15138 \begin_inset Flex Code
15141 \begin_layout Plain Layout
15149 will be replaced by the expansion of the
15150 \begin_inset Flex Code
15153 \begin_layout Plain Layout
15160 \begin_inset Flex Code
15163 \begin_layout Plain Layout
15164 LabelStringAppendix
15170 \begin_inset Flex Code
15173 \begin_layout Plain Layout
15183 \begin_layout Itemize
15184 counter values can be expressed using LaTeX-like macros
15185 \begin_inset Flex Code
15188 \begin_layout Plain Layout
15205 \begin_inset Flex Code
15208 \begin_layout Plain Layout
15220 \begin_layout Plain Layout
15230 Actually, the situation is a bit more complicated: any
15249 other than those described below will produce arabic numerals.
15250 It would not be surprising to see this change in the future.
15256 \begin_inset Flex Code
15259 \begin_layout Plain Layout
15265 : 1, 2, 3,\SpecialChar \ldots{}
15267 \begin_inset Flex Code
15270 \begin_layout Plain Layout
15276 for lower-case letters: a, b, c, \SpecialChar \ldots{}
15278 \begin_inset Flex Code
15281 \begin_layout Plain Layout
15287 for upper-case letters: A, B, C, \SpecialChar \ldots{}
15289 \begin_inset Flex Code
15292 \begin_layout Plain Layout
15298 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
15300 \begin_inset Flex Code
15303 \begin_layout Plain Layout
15309 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
15311 \begin_inset Flex Code
15314 \begin_layout Plain Layout
15320 for hebrew numerals.
15324 \begin_layout Standard
15325 If LabelString is not defined, a default value is constructed as follows:
15326 if the counter has a master counter
15327 \begin_inset Flex Code
15330 \begin_layout Plain Layout
15337 \begin_inset Flex Code
15340 \begin_layout Plain Layout
15347 \begin_inset Flex Code
15350 \begin_layout Plain Layout
15360 is used; otherwise the string
15361 \begin_inset Flex Code
15364 \begin_layout Plain Layout
15375 \begin_layout Description
15376 \begin_inset Flex Code
15379 \begin_layout Plain Layout
15380 LabelStringAppendix
15386 \begin_inset Flex Code
15389 \begin_layout Plain Layout
15396 \begin_inset Quotes erd
15400 \begin_inset Quotes erd
15404 \begin_inset Flex Code
15407 \begin_layout Plain Layout
15413 , but for use in the Appendix.
15416 \begin_layout Description
15417 \begin_inset Flex Code
15420 \begin_layout Plain Layout
15427 \begin_inset Flex Code
15430 \begin_layout Plain Layout
15437 \begin_inset Quotes erd
15441 \begin_inset Quotes erd
15444 ] A format for use with formatted references to this counter.
15445 For example, one might want to have references to section numbers appear
15447 \begin_inset Quotes eld
15451 \begin_inset Quotes erd
15455 The string should contain
15456 \begin_inset Quotes eld
15460 \begin_inset Quotes erd
15464 This will be replaced by the counter number itself.
15465 So, for sections, it would be: Section ##.
15468 \begin_layout Description
15469 \begin_inset Flex Code
15472 \begin_layout Plain Layout
15479 \begin_inset Flex Code
15482 \begin_layout Plain Layout
15489 \begin_inset Quotes erd
15493 \begin_inset Quotes erd
15496 ] If this is set to the name of another counter, the present counter will
15497 be reset every time the other one is increased.
15499 \begin_inset Flex Code
15502 \begin_layout Plain Layout
15509 \begin_inset Flex Code
15512 \begin_layout Plain Layout
15521 \begin_layout Subsection
15523 \begin_inset CommandInset label
15525 name "sub:Font-description"
15532 \begin_layout Standard
15533 A font description looks like this:
15536 \begin_layout LyX-Code
15546 \begin_layout LyX-Code
15550 \begin_layout LyX-Code
15554 \begin_layout Standard
15555 The following commands are available:
15558 \begin_layout Description
15559 \begin_inset Flex Code
15562 \begin_layout Plain Layout
15569 \begin_inset Flex Code
15572 \begin_layout Plain Layout
15581 \begin_inset Flex Code
15584 \begin_layout Plain Layout
15591 \begin_inset Flex Code
15594 \begin_layout Plain Layout
15601 \begin_inset Flex Code
15604 \begin_layout Plain Layout
15611 \begin_inset Flex Code
15614 \begin_layout Plain Layout
15621 \begin_inset Flex Code
15624 \begin_layout Plain Layout
15631 \begin_inset Flex Code
15634 \begin_layout Plain Layout
15641 \begin_inset Flex Code
15644 \begin_layout Plain Layout
15651 \begin_inset Flex Code
15654 \begin_layout Plain Layout
15663 \begin_layout Description
15664 \begin_inset Flex Code
15667 \begin_layout Plain Layout
15674 \begin_inset Flex Code
15677 \begin_layout Plain Layout
15686 \begin_inset Flex Code
15689 \begin_layout Plain Layout
15696 \begin_inset Flex Code
15699 \begin_layout Plain Layout
15708 \begin_layout Description
15709 \begin_inset Flex Code
15712 \begin_layout Plain Layout
15719 \begin_inset Flex Code
15722 \begin_layout Plain Layout
15728 ] Valid arguments are:
15729 \begin_inset Flex Code
15732 \begin_layout Plain Layout
15739 \begin_inset Flex Code
15742 \begin_layout Plain Layout
15749 \begin_inset Flex Code
15752 \begin_layout Plain Layout
15759 \begin_inset Flex Code
15762 \begin_layout Plain Layout
15769 \begin_inset Flex Code
15772 \begin_layout Plain Layout
15779 \begin_inset Flex Code
15782 \begin_layout Plain Layout
15789 Each of these turns on or off the corresponding attribute.
15791 \begin_inset Flex Code
15794 \begin_layout Plain Layout
15800 turns on emphasis, and
15801 \begin_inset Flex Code
15804 \begin_layout Plain Layout
15812 \begin_inset Newline newline
15815 If the latter seems puzzling, remember that the font settings for the present
15816 context are generally inherited from the surrounding context.
15818 \begin_inset Flex Code
15821 \begin_layout Plain Layout
15827 would turn off the emphasis that was anyway in effect, say, in a theorem
15831 \begin_layout Description
15832 \begin_inset Flex Code
15835 \begin_layout Plain Layout
15842 \begin_inset Flex Code
15845 \begin_layout Plain Layout
15854 \begin_inset Flex Code
15857 \begin_layout Plain Layout
15866 \begin_layout Description
15867 \begin_inset Flex Code
15870 \begin_layout Plain Layout
15877 \begin_inset Flex Code
15880 \begin_layout Plain Layout
15889 \begin_inset Flex Code
15892 \begin_layout Plain Layout
15899 \begin_inset Flex Code
15902 \begin_layout Plain Layout
15909 \begin_inset Flex Code
15912 \begin_layout Plain Layout
15921 \begin_layout Description
15922 \begin_inset Flex Code
15925 \begin_layout Plain Layout
15932 \begin_inset Flex Code
15935 \begin_layout Plain Layout
15942 \begin_inset Flex Code
15945 \begin_layout Plain Layout
15952 \begin_inset Flex Code
15955 \begin_layout Plain Layout
15964 \begin_inset Flex Code
15967 \begin_layout Plain Layout
15974 \begin_inset Flex Code
15977 \begin_layout Plain Layout
15984 \begin_inset Flex Code
15987 \begin_layout Plain Layout
15994 \begin_inset Flex Code
15997 \begin_layout Plain Layout
16004 \begin_inset Flex Code
16007 \begin_layout Plain Layout
16016 \begin_layout Subsection
16017 \begin_inset CommandInset label
16019 name "sub:Citation-format-description"
16023 Citation format description
16026 \begin_layout Standard
16028 \begin_inset Flex Code
16031 \begin_layout Plain Layout
16037 blocks are used to describe how bibliographic information should be displayed,
16038 both within LyX itself (in the citation dialog and in tooltips, for example)
16039 and in XHTML output.
16040 Such a block might look like this:
16043 \begin_layout LyX-Code
16047 \begin_layout LyX-Code
16051 \begin_layout LyX-Code
16055 \begin_layout LyX-Code
16059 \begin_layout Standard
16060 The individual lines define how the bibliographic information associated
16061 with an article or book, respectively, is to be displayed, and such a definitio
16062 n can be given for any `entry type' that might be present in a BibTeX file.
16063 LyX defines a default format in the source code that will be used if no
16064 specific definition has been given.
16065 LyX predefines several formats in the file
16066 \begin_inset Flex Code
16069 \begin_layout Plain Layout
16075 , which is included in most of LyX's document classes.
16078 \begin_layout Standard
16079 The definitions use a simple language that allows BibTeX keys to be replaced
16081 Keys should be enclosed in
16082 \begin_inset Flex Code
16085 \begin_layout Plain Layout
16092 \begin_inset Flex Code
16095 \begin_layout Plain Layout
16102 So a simple definition might look like this:
16105 \begin_layout LyX-Code
16107 \begin_inset Quotes eld
16111 \begin_inset Quotes erd
16117 \begin_layout Standard
16118 This would print the author, followed by a comma, followed by the title,
16119 in quotes, followed by a period.
16122 \begin_layout Standard
16123 Of course, sometimes you may want to print a key only if it exists.
16124 This can be done by using a conditional construction, such as:
16125 \begin_inset Flex Code
16128 \begin_layout Plain Layout
16130 \begin_inset space ~
16140 \begin_inset Flex Code
16143 \begin_layout Plain Layout
16149 key exists, then print
16150 \begin_inset Quotes eld
16154 \begin_inset space ~
16158 \begin_inset Quotes erd
16161 followed by the volume key.
16162 It is also possible to have an else clause in the conditional, such as:
16164 \begin_inset Flex Code
16167 \begin_layout Plain Layout
16168 {%author%[[%author%]][[%editor%, ed.]]}
16175 \begin_inset Flex Code
16178 \begin_layout Plain Layout
16184 key is printed if it exists; otherwise, the editor key is printed, followed
16186 \begin_inset Quotes eld
16190 \begin_inset space ~
16194 \begin_inset Quotes erd
16197 Note that the key is again enclosed in
16198 \begin_inset Flex Code
16201 \begin_layout Plain Layout
16207 signs; the entire conditional is enclosed in braces; and the if and else
16208 clauses are enclosed in double brackets,
16209 \begin_inset Quotes eld
16213 \begin_inset Flex Code
16216 \begin_layout Plain Layout
16223 \begin_inset Quotes eld
16227 \begin_inset Quotes eld
16231 \begin_inset Flex Code
16234 \begin_layout Plain Layout
16241 \begin_inset Quotes erd
16245 There must be no space between any of these.
16248 \begin_layout Standard
16249 There is one other piece of syntax available in definitions, which looks
16251 \begin_inset Flex Code
16254 \begin_layout Plain Layout
16261 This defines a piece of formatting information that is to be used when
16263 \begin_inset Quotes eld
16267 \begin_inset Quotes erd
16271 Obviously, we do not want to output HTML tags when writing plain text,
16272 so they should be wrapped in
16273 \begin_inset Quotes eld
16277 \begin_inset Quotes erd
16281 \begin_inset Quotes eld
16285 \begin_inset Quotes erd
16291 \begin_layout Standard
16292 Two special sorts of definitions are also possible in a
16293 \begin_inset Flex Code
16296 \begin_layout Plain Layout
16303 An example of the first would be:
16306 \begin_layout LyX-Code
16308 \begin_inset Quotes eld
16312 \begin_inset Quotes erd
16318 \begin_layout Standard
16319 This is an abbreviation, or macro, and it can be used by treating it as
16321 \begin_inset Flex Code
16324 \begin_layout Plain Layout
16332 \begin_inset Flex Code
16335 \begin_layout Plain Layout
16341 exactly as it would treat its definition.
16342 So, let us issue the obvious
16350 \begin_layout LyX-Code
16354 \begin_layout Standard
16355 or anything like it.
16356 LyX shouldn't go into an infinite loop, but it may go into a long one before
16360 \begin_layout Standard
16361 The second sort of special definition might look like this:
16364 \begin_layout LyX-Code
16368 \begin_layout Standard
16369 This defines a translatable piece of text, which allows relevant parts of
16370 the bibliography to be translated.
16371 It can be included in a definition by treating it as a key:
16372 \begin_inset Flex Code
16375 \begin_layout Plain Layout
16382 Several of these are predefined in
16383 \begin_inset Flex Code
16386 \begin_layout Plain Layout
16393 Note that these are not macros, in the sense just defined.
16394 They will not be expanded.
16397 \begin_layout Standard
16398 So here then is an example that use all these features:
16401 \begin_layout LyX-Code
16402 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
16405 \begin_layout Standard
16406 The defines a macro that prints the author, followed by a comma, if the
16408 \begin_inset Flex Code
16411 \begin_layout Plain Layout
16417 key is defined, or else prints the name of the editor, followed by the
16419 \begin_inset Flex Code
16422 \begin_layout Plain Layout
16428 or its translation (it is by default
16429 \begin_inset Quotes eld
16433 \begin_inset Quotes erd
16437 \begin_inset Flex Code
16440 \begin_layout Plain Layout
16447 Note that this is in fact defined in
16448 \begin_inset Flex Code
16451 \begin_layout Plain Layout
16457 , so you can use it in your own definitions, or re-definitions, if you load
16461 \begin_layout Section
16462 \begin_inset CommandInset label
16464 name "sec:Tags-for-XHTML"
16468 Tags for XHTML output
16471 \begin_layout Standard
16472 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
16473 by layout information.
16474 In general, LyX provides sensible defaults and, as mentioned earlier, it
16475 will even construct default CSS style rules from the other layout tags.
16476 For example, LyX will attempt to use the information provided in the
16477 \begin_inset Flex Code
16480 \begin_layout Plain Layout
16486 declaration for the Chapter style to write CSS that will appropriately
16487 format chapter headings.
16490 \begin_layout Standard
16491 In many cases, then, you may not have to do anything at all to get acceptable
16492 XHTML output for your own environments, custom insets, and so forth.
16493 But in some cases you will, and so LyX provides a number of layout tags
16494 that can be used to customize the XHTML and CSS that are generated.
16497 \begin_layout Standard
16498 Note that there are two tags,
16499 \begin_inset Flex Code
16502 \begin_layout Plain Layout
16509 \begin_inset Flex Code
16512 \begin_layout Plain Layout
16518 that may appear outside style and inset declarations.
16520 \begin_inset CommandInset ref
16522 reference "sub:General-text-class"
16526 for details on these.
16529 \begin_layout Subsection
16530 \begin_inset CommandInset label
16532 name "sub:Paragraph-Style-XHTML"
16539 \begin_layout Standard
16540 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
16541 dealing with a normal paragraph, a command, or an environment, where this
16542 is itself determined by the contents of the corresponding
16543 \begin_inset Flex Code
16546 \begin_layout Plain Layout
16556 \begin_layout Standard
16557 For a command or normal paragraph, the output XHTML has the following form:
16560 \begin_layout LyX-Code
16562 \begin_inset Quotes erd
16566 \begin_inset Quotes erd
16572 \begin_layout LyX-Code
16574 \begin_inset Quotes erd
16578 \begin_inset Quotes erd
16584 \begin_layout LyX-Code
16585 Contents of the paragraph.
16588 \begin_layout LyX-Code
16592 \begin_layout Standard
16593 The label tags are of course omitted if the paragraph does not have a label.
16596 \begin_layout Standard
16597 For an environment that is not some sort of list, the XHTML takes this form:
16600 \begin_layout LyX-Code
16602 \begin_inset Quotes erd
16606 \begin_inset Quotes erd
16612 \begin_layout LyX-Code
16614 \begin_inset Quotes erd
16618 \begin_inset Quotes erd
16622 \begin_inset Quotes erd
16626 \begin_inset Quotes erd
16629 >Environment Label</labeltag>First paragraph.</itemtag>
16632 \begin_layout LyX-Code
16633 <itemtag>Second paragraph.</itemtag>
16636 \begin_layout LyX-Code
16640 \begin_layout Standard
16641 Note that the label is output only for the first paragraph, as it should
16642 be for a theorem, for example.
16646 \begin_layout Standard
16647 For a list, we have one of these forms:
16650 \begin_layout LyX-Code
16652 \begin_inset Quotes erd
16656 \begin_inset Quotes erd
16662 \begin_layout LyX-Code
16664 \begin_inset Quotes erd
16668 \begin_inset Quotes erd
16672 \begin_inset Quotes erd
16676 \begin_inset Quotes erd
16679 >List Label</labeltag>First item.</itemtag>
16682 \begin_layout LyX-Code
16684 \begin_inset Quotes erd
16688 \begin_inset Quotes erd
16692 \begin_inset Quotes erd
16696 \begin_inset Quotes erd
16699 >List Label</labeltag>Second item.</itemtag>
16702 \begin_layout LyX-Code
16706 \begin_layout LyX-Code
16710 \begin_layout LyX-Code
16712 \begin_inset Quotes erd
16716 \begin_inset Quotes erd
16722 \begin_layout LyX-Code
16724 \begin_inset Quotes erd
16728 \begin_inset Quotes erd
16731 >List Label</labeltag><itemtag attr=
16732 \begin_inset Quotes erd
16736 \begin_inset Quotes erd
16739 >First item.</itemtag>
16742 \begin_layout LyX-Code
16744 \begin_inset Quotes erd
16748 \begin_inset Quotes erd
16751 >List Label</labeltag><itemtag attr=
16752 \begin_inset Quotes erd
16756 \begin_inset Quotes erd
16759 >Second item.</itemtag>
16762 \begin_layout LyX-Code
16766 \begin_layout Standard
16767 Note the different orders of
16768 \begin_inset Flex Code
16771 \begin_layout Plain Layout
16778 \begin_inset Flex Code
16781 \begin_layout Plain Layout
16788 Which order we get depends upon the setting of
16789 \begin_inset Flex Code
16792 \begin_layout Plain Layout
16799 \begin_inset Flex Code
16802 \begin_layout Plain Layout
16808 is false (the default), you get the first of these, with the label within
16809 the item; if true, you get the second, with the label outside the item.
16812 \begin_layout Standard
16813 The specific tags and attributes output for each paragraph type can be controlle
16814 d by means of the layout tags we are about to describe.
16815 As mentioned earlier, however, LyX uses sensible defaults for many of these,
16816 so you often may not need to do very much to get good XHTML output.
16817 Think of the available tags as there so you can tweak things to your liking.
16820 \begin_layout Description
16821 \begin_inset Flex Code
16824 \begin_layout Plain Layout
16831 \begin_inset Flex Code
16834 \begin_layout Plain Layout
16840 ] Specifies attribute information to be output with the main tag.
16842 \begin_inset Quotes eld
16846 \begin_inset Flex Code
16849 \begin_layout Plain Layout
16856 \begin_inset Quotes erd
16860 By default, LyX will output
16861 \begin_inset Quotes eld
16865 \begin_inset Flex Code
16868 \begin_layout Plain Layout
16875 \begin_inset Quotes erd
16879 \begin_inset Flex Code
16882 \begin_layout Plain Layout
16888 is the LyX name of the layout, made lowercase, for example: chapter.
16893 contain any style information.
16895 \begin_inset Flex Code
16898 \begin_layout Plain Layout
16907 \begin_layout Description
16908 \begin_inset Flex Code
16911 \begin_layout Plain Layout
16918 \begin_inset Flex Code
16921 \begin_layout Plain Layout
16931 ] Whether to output the default CSS information LyX generates for this layout,
16932 even if additional information is explicitly provided via
16933 \begin_inset Flex Code
16936 \begin_layout Plain Layout
16944 \begin_inset Flex Code
16947 \begin_layout Plain Layout
16953 allows you to alter or augment the generated CSS, rather than to override
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
16988 ] The tag to be used for individual paragraphs of environments, replacing
16990 \begin_inset Flex Code
16993 \begin_layout Plain Layout
16999 in the examples above.
17001 \begin_inset Flex Code
17004 \begin_layout Plain Layout
17013 \begin_layout Description
17014 \begin_inset Flex Code
17017 \begin_layout Plain Layout
17024 \begin_inset Flex Code
17027 \begin_layout Plain Layout
17033 ] Attributes for the item tag.
17035 \begin_inset Quotes eld
17039 \begin_inset Flex Code
17042 \begin_layout Plain Layout
17043 class=`layoutname_item'
17049 \begin_inset Quotes erd
17057 contain any style information.
17059 \begin_inset Flex Code
17062 \begin_layout Plain Layout
17071 \begin_layout Description
17072 \begin_inset Flex Code
17075 \begin_layout Plain Layout
17082 \begin_inset Flex Code
17085 \begin_layout Plain Layout
17091 ] The tag to be used for paragraph and item labels, replacing
17092 \begin_inset Flex Code
17095 \begin_layout Plain Layout
17101 in the examples above.
17103 \begin_inset Flex Code
17106 \begin_layout Plain Layout
17113 \begin_inset Flex Code
17116 \begin_layout Plain Layout
17123 \begin_inset Flex Code
17126 \begin_layout Plain Layout
17133 \begin_inset Flex Code
17136 \begin_layout Plain Layout
17137 Centered_Top_Environment
17142 , in which case it defaults to
17143 \begin_inset Flex Code
17146 \begin_layout Plain Layout
17155 \begin_layout Description
17156 \begin_inset Flex Code
17159 \begin_layout Plain Layout
17166 \begin_inset Flex Code
17169 \begin_layout Plain Layout
17175 ] Attributes for the label tag.
17177 \begin_inset Quotes eld
17181 \begin_inset Flex Code
17184 \begin_layout Plain Layout
17185 class=`layoutname_label'
17191 \begin_inset Quotes erd
17199 contain any style information.
17201 \begin_inset Flex Code
17204 \begin_layout Plain Layout
17213 \begin_layout Description
17214 \begin_inset Flex Code
17217 \begin_layout Plain Layout
17224 \begin_inset Flex Code
17227 \begin_layout Plain Layout
17237 ] Meaningful only for list-like environments, this tag controls whether
17238 the label tag is output before or inside the item tag.
17239 This is used, for example, in the description environment, where we want
17241 \begin_inset Flex Code
17244 \begin_layout Plain Layout
17245 <dt>\SpecialChar \ldots{}
17246 </dt><dd>\SpecialChar \ldots{}
17254 \begin_inset Flex Code
17257 \begin_layout Plain Layout
17263 : The label tag is output inside the item tag.
17266 \begin_layout Description
17267 \begin_inset Flex Code
17270 \begin_layout Plain Layout
17276 Information to be output in the
17277 \begin_inset Flex Code
17280 \begin_layout Plain Layout
17286 section when this style is used.
17287 This might, for example, be used to include a
17288 \begin_inset Flex Code
17291 \begin_layout Plain Layout
17298 \begin_inset Flex Code
17301 \begin_layout Plain Layout
17310 \begin_layout Description
17311 \begin_inset Flex Code
17314 \begin_layout Plain Layout
17320 CSS style information to be included when this style is used.
17321 Note that this will automatically be wrapped in a layout-generated
17322 \begin_inset Flex Code
17325 \begin_layout Plain Layout
17331 block, so only the CSS itself need be included.
17334 \begin_layout Description
17335 \begin_inset Flex Code
17338 \begin_layout Plain Layout
17345 \begin_inset Flex Code
17348 \begin_layout Plain Layout
17354 ] The tag to be used for the main label, replacing
17355 \begin_inset Flex Code
17358 \begin_layout Plain Layout
17364 in the examples above.
17366 \begin_inset Flex Code
17369 \begin_layout Plain Layout
17378 \begin_layout Description
17379 \begin_inset Flex Code
17382 \begin_layout Plain Layout
17389 \begin_inset Flex Code
17392 \begin_layout Plain Layout
17402 ] Marks this style as the one to be used to generate the
17403 \begin_inset Flex Code
17406 \begin_layout Plain Layout
17412 tag for the XHTML file.
17413 By default, it is false.
17415 \begin_inset Flex Code
17418 \begin_layout Plain Layout
17424 file sets it to true for the
17425 \begin_inset Flex Code
17428 \begin_layout Plain Layout
17438 \begin_layout Subsection
17442 \begin_layout Standard
17443 The XHTML output of insets can also be controlled by information in layout
17448 \begin_layout Plain Layout
17449 At present, this is true only for
17450 \begin_inset Quotes eld
17454 \begin_inset Quotes erd
17457 insets (insets you can type into) and is not true for
17458 \begin_inset Quotes eld
17462 \begin_inset Quotes erd
17465 insets (insets that are associated with dialog boxes).
17470 Here, too, LyX tries to provide sensible defaults, and it constructs default
17472 But everything can be customized.
17475 \begin_layout Standard
17476 The XHTML LyX outputs for an inset has the following form:
17479 \begin_layout LyX-Code
17481 \begin_inset Quotes erd
17485 \begin_inset Quotes erd
17491 \begin_layout LyX-Code
17492 <labeltag>Label</labeltag>
17495 \begin_layout LyX-Code
17497 \begin_inset Quotes erd
17501 \begin_inset Quotes erd
17504 >Contents of the inset.</innertag>
17507 \begin_layout LyX-Code
17511 \begin_layout Standard
17512 If the inset permits multiple paragraphs---that is, if
17513 \begin_inset Flex Code
17516 \begin_layout Plain Layout
17522 is true---then the contents of the inset will itself be output as paragraphs
17523 formatted according to the styles used for those paragraphs (standard,
17524 quote, and the like).
17525 The label tag is of course omitted if the paragraph does not have a label
17526 and, at present, is always
17527 \begin_inset Flex Code
17530 \begin_layout Plain Layout
17537 The inner tag is optional and, by default, does not appear.
17540 \begin_layout Standard
17541 The specific tags and attributes output for each inset can be controlled
17542 by means of the following layout tags.
17545 \begin_layout Description
17546 \begin_inset Flex Code
17549 \begin_layout Plain Layout
17556 \begin_inset Flex Code
17559 \begin_layout Plain Layout
17565 ] Specifies attribute information to be output with the main tag.
17567 \begin_inset Quotes eld
17571 \begin_inset Flex Code
17574 \begin_layout Plain Layout
17575 class=`myinset' onclick=`\SpecialChar \ldots{}
17582 \begin_inset Quotes erd
17586 By default, LyX will output
17587 \begin_inset Quotes eld
17591 \begin_inset Flex Code
17594 \begin_layout Plain Layout
17601 \begin_inset Quotes erd
17605 \begin_inset Flex Code
17608 \begin_layout Plain Layout
17614 is the LyX name of the inset, made lowercase and with non-alphanumeric
17615 characters converted to underscores, for example: footnote.
17618 \begin_layout Description
17619 \begin_inset Flex Code
17622 \begin_layout Plain Layout
17629 \begin_inset Flex Code
17632 \begin_layout Plain Layout
17642 ] Whether to output the default CSS information LyX generates for this layout,
17643 even if additional information is explicitly provided via
17644 \begin_inset Flex Code
17647 \begin_layout Plain Layout
17655 \begin_inset Flex Code
17658 \begin_layout Plain Layout
17664 allows you to alter or augment the generated CSS, rather than to override
17669 \begin_layout Description
17670 \begin_inset Flex Code
17673 \begin_layout Plain Layout
17680 \begin_inset Flex Code
17683 \begin_layout Plain Layout
17689 ] Attributes for the inner tag.
17691 \begin_inset Quotes eld
17695 \begin_inset Flex Code
17698 \begin_layout Plain Layout
17699 class=`insetname_inner'
17705 \begin_inset Quotes erd
17711 \begin_layout Description
17712 \begin_inset Flex Code
17715 \begin_layout Plain Layout
17722 \begin_inset Flex Code
17725 \begin_layout Plain Layout
17731 ] The inner tag, replacing
17732 \begin_inset Flex Code
17735 \begin_layout Plain Layout
17741 in the examples above.
17742 By default, there is none.
17745 \begin_layout Description
17746 \begin_inset Flex Code
17749 \begin_layout Plain Layout
17756 \begin_inset Flex Code
17759 \begin_layout Plain Layout
17767 ] Whether this inset represents a standalone block of text (such as a footnote)
17768 or instead represents material that is included in the surrounding text
17769 (such as a branch).
17773 \begin_layout Description
17774 \begin_inset Flex Code
17777 \begin_layout Plain Layout
17784 \begin_inset Flex Code
17787 \begin_layout Plain Layout
17793 ] A label for this inset, possibly including a reference to a counter.
17794 For example, for footnote, it might be:
17795 \begin_inset Flex Code
17798 \begin_layout Plain Layout
17807 This is optional, and there is no default.
17810 \begin_layout Description
17811 \begin_inset Flex Code
17814 \begin_layout Plain Layout
17820 Information to be output in the
17821 \begin_inset Flex Code
17824 \begin_layout Plain Layout
17830 section when this style is used.
17831 This might, for example, be used to include a
17832 \begin_inset Flex Code
17835 \begin_layout Plain Layout
17842 \begin_inset Flex Code
17845 \begin_layout Plain Layout
17854 \begin_layout Description
17855 \begin_inset Flex Code
17858 \begin_layout Plain Layout
17864 CSS style information to be included when this style is used.
17865 Note that this will automatically be wrapped in a layout-generated
17866 \begin_inset Flex Code
17869 \begin_layout Plain Layout
17875 block, so only the CSS itself need be included.
17878 \begin_layout Description
17879 \begin_inset Flex Code
17882 \begin_layout Plain Layout
17889 \begin_inset Flex Code
17892 \begin_layout Plain Layout
17898 ] The tag to be used for the main label, replacing
17899 \begin_inset Flex Code
17902 \begin_layout Plain Layout
17908 in the examples above.
17909 The default depends upon the setting of
17910 \begin_inset Flex Code
17913 \begin_layout Plain Layout
17920 \begin_inset Flex Code
17923 \begin_layout Plain Layout
17929 is true, the default is
17930 \begin_inset Flex Code
17933 \begin_layout Plain Layout
17939 ; if it is false, the default is
17940 \begin_inset Flex Code
17943 \begin_layout Plain Layout
17952 \begin_layout Subsection
17956 \begin_layout Standard
17957 The XHTML output for floats too can be controlled by layout information.
17958 The output has the following form:
17961 \begin_layout LyX-Code
17963 \begin_inset Quotes erd
17967 \begin_inset Quotes erd
17973 \begin_layout LyX-Code
17974 Contents of the float.
17977 \begin_layout LyX-Code
17981 \begin_layout Standard
17982 The caption, if there is one, is a separate inset and will be output as
17984 Its appearance can be controlled via the InsetLayout for caption insets.
17988 \begin_layout Description
17989 \begin_inset Flex Code
17992 \begin_layout Plain Layout
17999 \begin_inset Flex Code
18002 \begin_layout Plain Layout
18008 ] Specifies attribute information to be output with the main tag.
18010 \begin_inset Quotes eld
18014 \begin_inset Flex Code
18017 \begin_layout Plain Layout
18018 class=`myfloat' onclick=`\SpecialChar \ldots{}
18025 \begin_inset Quotes erd
18029 By default, LyX will output
18030 \begin_inset Quotes eld
18034 \begin_inset Flex Code
18037 \begin_layout Plain Layout
18038 class=`float float-floattype'
18044 \begin_inset Quotes erd
18048 \begin_inset Flex Code
18051 \begin_layout Plain Layout
18057 is LyX's name for this type of float, as determined by the float delcaration
18059 \begin_inset CommandInset ref
18061 reference "sub:Floats"
18065 ), though made lowercase and with non-alphanumeric characters converted
18066 to underscores, for example: float-table.
18069 \begin_layout Description
18070 \begin_inset Flex Code
18073 \begin_layout Plain Layout
18079 CSS style information to be included when this float is used.
18080 Note that this will automatically be wrapped in a layout-generated
18081 \begin_inset Flex Code
18084 \begin_layout Plain Layout
18090 block, so only the CSS itself need be included.
18093 \begin_layout Description
18094 \begin_inset Flex Code
18097 \begin_layout Plain Layout
18104 \begin_inset Flex Code
18107 \begin_layout Plain Layout
18113 ] The tag to be used for this float, replacing
18114 \begin_inset Quotes eld
18118 \begin_inset Flex Code
18121 \begin_layout Plain Layout
18128 \begin_inset Quotes erd
18131 in the example above.
18133 \begin_inset Flex Code
18136 \begin_layout Plain Layout
18142 and will rarely need changing.
18145 \begin_layout Subsection
18146 Bibliography formatting
18149 \begin_layout Standard
18150 The bibliography can be formatted using
18151 \begin_inset Flex Code
18154 \begin_layout Plain Layout
18162 \begin_inset CommandInset ref
18164 reference "sub:Citation-format-description"
18171 \begin_layout Subsection
18175 \begin_layout Standard
18176 We have several times mentioned that LyX will generate default CSS style
18177 rules for both insets and paragraph styles, based upon the other layout
18178 information that is provided.
18179 In this section, we shall say a word about which layout information LyX
18183 \begin_layout Standard
18184 At present, LyX auto-generates CSS only for font information, making use
18186 \begin_inset Flex Code
18189 \begin_layout Plain Layout
18196 \begin_inset Flex Code
18199 \begin_layout Plain Layout
18206 \begin_inset Flex Code
18209 \begin_layout Plain Layout
18216 \begin_inset Flex Code
18219 \begin_layout Plain Layout
18226 \begin_inset Flex Code
18229 \begin_layout Plain Layout
18237 \begin_inset CommandInset ref
18239 reference "sub:Font-description"
18243 .) The translation is mostly straightforward and obvious.
18245 \begin_inset Quotes eld
18249 \begin_inset Flex Code
18252 \begin_layout Plain Layout
18259 \begin_inset Quotes erd
18263 \begin_inset Quotes eld
18267 \begin_inset Flex Code
18270 \begin_layout Plain Layout
18271 font-family: sans-serif;
18277 \begin_inset Quotes erd
18281 The correspondence of LyX sizes and CSS sizes is a little less obvious
18282 but nonetheless intuitive.
18284 \begin_inset Flex Code
18287 \begin_layout Plain Layout
18294 \begin_inset Flex URL
18297 \begin_layout Plain Layout
18308 \begin_layout Chapter
18309 Including External Material
18312 \begin_layout Standard
18313 \begin_inset Box Shadowbox
18323 height_special "totalheight"
18326 \begin_layout Plain Layout
18327 WARNING: This portion of the documentation has not been updated for some
18329 We certainly hope that it is still accurate, but there are no guarantees.
18337 \begin_layout Standard
18338 The use of material from sources external to LyX is covered in detail in
18344 This part of the manual covers what needs to happen behind the scenes for
18345 new sorts of material to be included.
18348 \begin_layout Section
18352 \begin_layout Standard
18353 The external material feature is based on the concept of a
18358 A template is a specification of how LyX should interface with a certain
18360 As bundled, LyX comes with predefined templates for Xfig figures, various
18361 raster format images, chess diagrams, and LilyPond music notation.
18362 You can check the actual list by using the menu
18363 \begin_inset Flex MenuItem
18366 \begin_layout Plain Layout
18367 Insert\SpecialChar \menuseparator
18368 File\SpecialChar \menuseparator
18375 Furthermore, it is possible to roll your own template to support a specific
18377 Later we'll describe in more detail what is involved, and hopefully you
18378 will submit all the templates you create so we can include them in a later
18382 \begin_layout Standard
18383 Another basic idea of the external material feature is to distinguish between
18384 the original file that serves as a base for final material and the produced
18385 file that is included in your exported or printed document.
18386 For example, consider the case of a figure produced with
18387 \begin_inset Flex Code
18390 \begin_layout Plain Layout
18397 The Xfig application itself works on an original file with the
18398 \begin_inset Flex Code
18401 \begin_layout Plain Layout
18408 Within Xfig, you create and change your figure, and when you are done,
18410 \begin_inset Flex Code
18413 \begin_layout Plain Layout
18420 When you want to include the figure in your document, you invoke
18421 \begin_inset Flex Code
18424 \begin_layout Plain Layout
18430 in order to create a PostScript file that can readily be included in your
18433 \begin_inset Flex Code
18436 \begin_layout Plain Layout
18442 file is the original file, and the PostScript file is the produced file.
18445 \begin_layout Standard
18446 This distinction is important in order to allow updating of the material
18447 while you are in the process of writing the document.
18448 Furthermore, it provides us with the flexibility that is needed to support
18449 multiple export formats.
18450 For instance, in the case of a plain text file, it is not exactly an award-winn
18451 ing idea to include the figure as raw PostScript.
18452 Instead, you'd either prefer to just include a reference to the figure
18453 or try to invoke some graphics to ASCII converter to make the final result
18454 look similar to the real graphics.
18455 The external material management allows you to do this, because it is parametri
18456 zed on the different export formats that LyX supports.
18459 \begin_layout Standard
18460 Besides supporting the production of different products according to the
18461 exported format, it supports tight integration with editing and viewing
18463 In the case of an Xfig figure, you are able to invoke Xfig on the original
18464 file with a single click from within the external material dialog in LyX,
18465 and also preview the produced PostScript file with Ghostview with another
18467 No more fiddling around with the command line and/or file browsers to locate
18468 and manipulate the original or produced files.
18469 In this way, you are finally able to take full advantage of the many different
18470 applications that are relevant to use when you write your documents, and
18471 ultimately be more productive.
18474 \begin_layout Section
18475 The external template configuration file
18478 \begin_layout Standard
18479 It is relatively easy to add custom external template definitions to LyX.
18480 However, be aware that doing this in an careless manner most probably
18484 introduce an easily exploitable security hole.
18485 So before you do this, please read the discussion about security in section
18487 \begin_inset CommandInset ref
18489 reference "sec:Security-discussion"
18496 \begin_layout Standard
18497 Having said that, we encourage you to submit any interesting templates that
18502 \begin_layout Standard
18503 The external templates are defined in the
18504 \begin_inset Flex Code
18507 \begin_layout Plain Layout
18508 LyXDir/lib/external_templates
18514 You can place your own version in
18515 \begin_inset Flex Code
18518 \begin_layout Plain Layout
18519 UserDir/external_templates
18527 \begin_layout Standard
18528 A typical template looks like this:
18531 \begin_layout LyX-Code
18535 \begin_layout LyX-Code
18536 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
18539 \begin_layout LyX-Code
18543 \begin_layout LyX-Code
18547 \begin_layout LyX-Code
18551 \begin_layout LyX-Code
18555 \begin_layout LyX-Code
18559 \begin_layout LyX-Code
18560 AutomaticProduction true
18563 \begin_layout LyX-Code
18567 \begin_layout LyX-Code
18571 \begin_layout LyX-Code
18575 \begin_layout LyX-Code
18576 TransformCommand Rotate RotationLatexCommand
18579 \begin_layout LyX-Code
18580 TransformCommand Resize ResizeLatexCommand
18583 \begin_layout LyX-Code
18584 Product "$$RotateFront$$ResizeFront
18587 \begin_layout LyX-Code
18592 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
18595 \begin_layout LyX-Code
18596 $$ResizeBack$$RotateBack"
18599 \begin_layout LyX-Code
18603 \begin_layout LyX-Code
18604 UpdateResult "$$AbsPath$$Basename.pstex_t"
18607 \begin_layout LyX-Code
18608 Requirement "graphicx"
18611 \begin_layout LyX-Code
18612 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
18615 \begin_layout LyX-Code
18616 ReferencedFile latex "$$AbsPath$$Basename.eps"
18619 \begin_layout LyX-Code
18620 ReferencedFile dvi "$$AbsPath$$Basename.eps"
18623 \begin_layout LyX-Code
18627 \begin_layout LyX-Code
18631 \begin_layout LyX-Code
18632 TransformCommand Rotate RotationLatexCommand
18635 \begin_layout LyX-Code
18636 TransformCommand Resize ResizeLatexCommand
18639 \begin_layout LyX-Code
18640 Product "$$RotateFront$$ResizeFront
18643 \begin_layout LyX-Code
18648 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
18651 \begin_layout LyX-Code
18652 $$ResizeBack$$RotateBack"
18655 \begin_layout LyX-Code
18656 UpdateFormat pdftex
18659 \begin_layout LyX-Code
18660 UpdateResult "$$AbsPath$$Basename.pdftex_t"
18663 \begin_layout LyX-Code
18664 Requirement "graphicx"
18667 \begin_layout LyX-Code
18668 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
18671 \begin_layout LyX-Code
18672 ReferencedFile latex "$$AbsPath$$Basename.pdf"
18675 \begin_layout LyX-Code
18679 \begin_layout LyX-Code
18683 \begin_layout LyX-Code
18684 Product "$$Contents(
18686 "$$AbsPath$$Basename.asc
18691 \begin_layout LyX-Code
18692 UpdateFormat asciixfig
18695 \begin_layout LyX-Code
18696 UpdateResult "$$AbsPath$$Basename.asc"
18699 \begin_layout LyX-Code
18703 \begin_layout LyX-Code
18707 \begin_layout LyX-Code
18708 Product "<graphic fileref=
18710 "$$AbsOrRelPathMaster$$Basename.eps
18715 \begin_layout LyX-Code
18719 \begin_layout LyX-Code
18723 \begin_layout LyX-Code
18724 UpdateResult "$$AbsPath$$Basename.eps"
18727 \begin_layout LyX-Code
18728 ReferencedFile docbook "$$AbsPath$$Basename.eps"
18731 \begin_layout LyX-Code
18732 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
18735 \begin_layout LyX-Code
18739 \begin_layout LyX-Code
18740 Product "[XFig: $$FName]"
18743 \begin_layout LyX-Code
18747 \begin_layout LyX-Code
18751 \begin_layout Standard
18752 As you can see, the template is enclosed in
18753 \begin_inset Flex Code
18756 \begin_layout Plain Layout
18762 \SpecialChar \ldots{}
18764 \begin_inset Flex Code
18767 \begin_layout Plain Layout
18774 It contains a header specifying some general settings and, for each supported
18775 primary document file format, a section
18776 \begin_inset Flex Code
18779 \begin_layout Plain Layout
18785 \SpecialChar \ldots{}
18787 \begin_inset Flex Code
18790 \begin_layout Plain Layout
18799 \begin_layout Subsection
18800 The template header
18803 \begin_layout Description
18804 \begin_inset Flex Code
18807 \begin_layout Plain Layout
18808 AutomaticProduction
18809 \begin_inset space ~
18817 Whether the file represented by the template must be generated by LyX.
18818 This command must occur exactly once.
18821 \begin_layout Description
18822 \begin_inset Flex Code
18825 \begin_layout Plain Layout
18827 \begin_inset space ~
18835 A glob pattern that is used in the file dialog to filter out the desired
18837 If there is more than one possible file extension (e.
18838 \begin_inset space \thinspace{}
18842 \begin_inset space \space{}
18846 \begin_inset Flex Code
18849 \begin_layout Plain Layout
18856 \begin_inset Flex Code
18859 \begin_layout Plain Layout
18865 ), use something like
18866 \begin_inset Flex Code
18869 \begin_layout Plain Layout
18876 This command must occur exactly once.
18879 \begin_layout Description
18880 \begin_inset Flex Code
18883 \begin_layout Plain Layout
18885 \begin_inset space ~
18893 The text that is displayed on the button.
18894 This command must occur exactly once.
18897 \begin_layout Description
18898 \begin_inset Flex Code
18901 \begin_layout Plain Layout
18903 \begin_inset space ~
18907 \begin_inset space ~
18915 The help text that is used in the External dialog.
18916 Provide enough information to explain to the user just what the template
18917 can provide him with.
18918 This command must occur exactly once.
18921 \begin_layout Description
18922 \begin_inset Flex Code
18925 \begin_layout Plain Layout
18927 \begin_inset space ~
18935 The file format of the original file.
18936 This must be the name of a format that is known to LyX (see section
18937 \begin_inset CommandInset ref
18939 reference "sec:Formats"
18945 \begin_inset Quotes eld
18949 \begin_inset Flex Code
18952 \begin_layout Plain Layout
18959 \begin_inset Quotes erd
18962 if the template can handle original files of more than one format.
18963 LyX will attempt to interrogate the file itself in order to deduce its
18964 format in this case.
18965 This command must occur exactly once.
18968 \begin_layout Description
18969 \begin_inset Flex Code
18972 \begin_layout Plain Layout
18974 \begin_inset space ~
18982 A unique name for the template.
18983 It must not contain substitution macros (see below).
18986 \begin_layout Description
18987 \begin_inset Flex Code
18990 \begin_layout Plain Layout
18992 \begin_inset space ~
18995 Rotate|Resize|Clip|Extra
19000 This command specifies which transformations are supported by this template.
19001 It may occur zero or more times.
19002 This command enables the corresponding tabs in the external dialog.
19004 \begin_inset Flex Code
19007 \begin_layout Plain Layout
19013 command must have either a corresponding
19014 \begin_inset Flex Code
19017 \begin_layout Plain Layout
19024 \begin_inset Flex Code
19027 \begin_layout Plain Layout
19034 \begin_inset Flex Code
19037 \begin_layout Plain Layout
19044 Otherwise the transformation will not be supported by that format.
19047 \begin_layout Subsection
19051 \begin_layout Description
19052 \begin_inset Flex Code
19055 \begin_layout Plain Layout
19057 \begin_inset space ~
19060 LaTeX|PDFLaTeX|PlainText|DocBook
19065 The primary document file format that this format definition is for.
19066 Not every template has a sensible representation in all document file formats.
19067 Please define nevertheless a
19068 \begin_inset Flex Code
19071 \begin_layout Plain Layout
19077 section for all formats.
19078 Use a dummy text when no representation is available.
19079 Then you can at least see a reference to the external material in the exported
19083 \begin_layout Description
19084 \begin_inset Flex Code
19087 \begin_layout Plain Layout
19089 \begin_inset space ~
19093 \begin_inset space ~
19101 This command defines an additional macro
19102 \begin_inset Flex Code
19105 \begin_layout Plain Layout
19111 for substitution in
19112 \begin_inset Flex Code
19115 \begin_layout Plain Layout
19123 \begin_inset Flex Code
19126 \begin_layout Plain Layout
19132 itself may contain substitution macros.
19133 The advantage over using
19134 \begin_inset Flex Code
19137 \begin_layout Plain Layout
19144 \begin_inset Flex Code
19147 \begin_layout Plain Layout
19153 is that the substituted value of
19154 \begin_inset Flex Code
19157 \begin_layout Plain Layout
19163 is sanitized so that it is a valid optional argument in the document format.
19164 This command may occur zero or more times.
19167 \begin_layout Description
19168 \begin_inset Flex Code
19171 \begin_layout Plain Layout
19173 \begin_inset space ~
19181 The text that is inserted in the exported document.
19182 This is actually the most important command and can be quite complex.
19183 This command must occur exactly once.
19186 \begin_layout Description
19187 \begin_inset Flex Code
19190 \begin_layout Plain Layout
19192 \begin_inset space ~
19200 This command specifies a preamble snippet that will be included in the
19202 It has to be defined using
19203 \begin_inset Flex Code
19206 \begin_layout Plain Layout
19212 \SpecialChar \ldots{}
19214 \begin_inset Flex Code
19217 \begin_layout Plain Layout
19224 This command may occur zero or more times.
19227 \begin_layout Description
19228 \begin_inset Flex Code
19231 \begin_layout Plain Layout
19233 \begin_inset space ~
19237 \begin_inset space ~
19245 This command denotes files that are created by the conversion process and
19246 are needed for a particular export format.
19247 If the filename is relative, it is interpreted relative to the master document.
19248 This command may be given zero or more times.
19251 \begin_layout Description
19252 \begin_inset Flex Code
19255 \begin_layout Plain Layout
19257 \begin_inset space ~
19265 The name of a required LaTeX package.
19266 The package is included via
19267 \begin_inset Flex Code
19270 \begin_layout Plain Layout
19278 in the LaTeX preamble.
19279 This command may occur zero or more times.
19282 \begin_layout Description
19283 \begin_inset Flex Code
19286 \begin_layout Plain Layout
19288 \begin_inset space ~
19292 \begin_inset space ~
19295 RotationLatexCommand
19300 This command specifies that the built in LaTeX command should be used for
19302 This command may occur once or not at all.
19305 \begin_layout Description
19306 \begin_inset Flex Code
19309 \begin_layout Plain Layout
19311 \begin_inset space ~
19315 \begin_inset space ~
19323 This command specifies that the built in LaTeX command should be used for
19325 This command may occur once or not at all.
19328 \begin_layout Description
19329 \begin_inset Flex Code
19332 \begin_layout Plain Layout
19334 \begin_inset space ~
19338 \begin_inset space ~
19341 RotationLatexOption
19346 This command specifies that rotation is done via an optional argument.
19347 This command may occur once or not at all.
19350 \begin_layout Description
19351 \begin_inset Flex Code
19354 \begin_layout Plain Layout
19356 \begin_inset space ~
19360 \begin_inset space ~
19368 This command specifies that resizing is done via an optional argument.
19369 This command may occur once or not at all.
19372 \begin_layout Description
19373 \begin_inset Flex Code
19376 \begin_layout Plain Layout
19378 \begin_inset space ~
19382 \begin_inset space ~
19390 This command specifies that clipping is done via an optional argument.
19391 This command may occur once or not at all.
19394 \begin_layout Description
19395 \begin_inset Flex Code
19398 \begin_layout Plain Layout
19400 \begin_inset space ~
19404 \begin_inset space ~
19412 This command specifies that an extra optional argument is used.
19413 This command may occur once or not at all.
19416 \begin_layout Description
19417 \begin_inset Flex Code
19420 \begin_layout Plain Layout
19422 \begin_inset space ~
19430 The file format of the converted file.
19431 This must be the name of a format that is known to LyX (see the
19432 \begin_inset Flex MenuItem
19435 \begin_layout Plain Layout
19440 ools\SpecialChar \menuseparator
19445 references:Conversion
19451 This command must occur exactly once.
19454 \begin_layout Description
19455 \begin_inset Flex Code
19458 \begin_layout Plain Layout
19460 \begin_inset space ~
19468 The file name of the converted file.
19469 The file name must be absolute.
19470 This command must occur exactly once.
19473 \begin_layout Subsection
19474 Preamble definitions
19477 \begin_layout Standard
19478 The external template configuration file may contain additional preamble
19479 definitions enclosed by
19480 \begin_inset Flex Code
19483 \begin_layout Plain Layout
19489 \SpecialChar \ldots{}
19491 \begin_inset Flex Code
19494 \begin_layout Plain Layout
19501 They can be used by the templates in the
19502 \begin_inset Flex Code
19505 \begin_layout Plain Layout
19514 \begin_layout Section
19515 The substitution mechanism
19518 \begin_layout Standard
19519 When the external material facility invokes an external program, it is done
19520 on the basis of a command defined in the template configuration file.
19521 These commands can contain various macros that are expanded before execution.
19522 Execution always take place in the directory of the containing document.
19525 \begin_layout Standard
19526 Also, whenever external material is to be displayed, the name will be produced
19527 by the substitution mechanism, and most other commands in the template
19528 definition support substitution as well.
19531 \begin_layout Standard
19532 The available macros are the following:
19535 \begin_layout Description
19536 \begin_inset Flex Code
19539 \begin_layout Plain Layout
19540 $$AbsOrRelPathMaster
19545 The file path, absolute or relative to the master LyX document.
19548 \begin_layout Description
19549 \begin_inset Flex Code
19552 \begin_layout Plain Layout
19553 $$AbsOrRelPathParent
19558 The file path, absolute or relative to the LyX document.
19561 \begin_layout Description
19562 \begin_inset Flex Code
19565 \begin_layout Plain Layout
19571 The absolute file path.
19574 \begin_layout Description
19575 \begin_inset Flex Code
19578 \begin_layout Plain Layout
19584 The filename without path and without the extension.
19587 \begin_layout Description
19588 \begin_inset Flex Code
19591 \begin_layout Plain Layout
19593 \begin_inset Quotes eld
19597 \begin_inset Quotes erd
19605 This macro will expand to the contents of the file with the name
19606 \begin_inset Flex Code
19609 \begin_layout Plain Layout
19618 \begin_layout Description
19619 \begin_inset Flex Code
19622 \begin_layout Plain Layout
19628 The file extension (including the dot).
19631 \begin_layout Description
19632 \begin_inset Flex Code
19635 \begin_layout Plain Layout
19641 The filename of the file specified in the external material dialog.
19642 This is either an absolute name, or it is relative to the LyX document.
19645 \begin_layout Description
19646 \begin_inset Flex Code
19649 \begin_layout Plain Layout
19656 \begin_inset Flex Code
19659 \begin_layout Plain Layout
19665 (absolute name or relative to the LyX document).
19668 \begin_layout Description
19669 \begin_inset Flex Code
19672 \begin_layout Plain Layout
19678 The file path, relative to the master LyX document.
19681 \begin_layout Description
19682 \begin_inset Flex Code
19685 \begin_layout Plain Layout
19691 The file path, relative to the LyX document.
19694 \begin_layout Description
19695 \begin_inset Flex Code
19698 \begin_layout Plain Layout
19704 This macro will expand to the absolute path of the system directory.
19705 This is typically used to point to the various helper scripts that are
19709 \begin_layout Description
19710 \begin_inset Flex Code
19713 \begin_layout Plain Layout
19719 A name and full path to a temporary file which will be automatically deleted
19720 whenever the containing document is closed, or the external material insertion
19724 \begin_layout Standard
19725 All path macros contain a trailing directory separator, so you can construct
19727 \begin_inset space \thinspace{}
19731 \begin_inset space \space{}
19734 the absolute filename with
19735 \begin_inset Flex Code
19738 \begin_layout Plain Layout
19739 $$AbsPath$$Basename$$Extension
19747 \begin_layout Standard
19748 The macros above are substituted in all commands unless otherwise noted.
19750 \begin_inset Flex Code
19753 \begin_layout Plain Layout
19759 supports additionally the following substitutions if they are enabled by
19761 \begin_inset Flex Code
19764 \begin_layout Plain Layout
19771 \begin_inset Flex Code
19774 \begin_layout Plain Layout
19783 \begin_layout Description
19784 \begin_inset Flex Code
19787 \begin_layout Plain Layout
19793 The front part of the resize command.
19796 \begin_layout Description
19797 \begin_inset Flex Code
19800 \begin_layout Plain Layout
19806 The back part of the resize command.
19809 \begin_layout Description
19810 \begin_inset Flex Code
19813 \begin_layout Plain Layout
19819 The front part of the rotation command.
19822 \begin_layout Description
19823 \begin_inset Flex Code
19826 \begin_layout Plain Layout
19832 The back part of the rotation command.
19835 \begin_layout Standard
19836 The value string of the
19837 \begin_inset Flex Code
19840 \begin_layout Plain Layout
19846 command supports additionally the following substitutions if they are enabled
19848 \begin_inset Flex Code
19851 \begin_layout Plain Layout
19858 \begin_inset Flex Code
19861 \begin_layout Plain Layout
19870 \begin_layout Description
19871 \begin_inset Flex Code
19874 \begin_layout Plain Layout
19883 \begin_layout Description
19884 \begin_inset Flex Code
19887 \begin_layout Plain Layout
19896 \begin_layout Description
19897 \begin_inset Flex Code
19900 \begin_layout Plain Layout
19909 \begin_layout Description
19910 \begin_inset Flex Code
19913 \begin_layout Plain Layout
19919 The rotation option.
19922 \begin_layout Standard
19923 You may ask why there are so many path macros.
19924 There are mainly two reasons:
19927 \begin_layout Enumerate
19928 Relative and absolute file names should remain relative or absolute, respectivel
19930 Users may have reasons to prefer either form.
19931 Relative names are useful for portable documents that should work on different
19932 machines, for example.
19933 Absolute names may be required by some programs.
19936 \begin_layout Enumerate
19937 LaTeX treats relative file names differently than LyX and other programs
19938 in nested included files.
19939 For LyX, a relative file name is always relative to the document that contains
19941 For LaTeX, it is always relative to the master document.
19942 These two definitions are identical if you have only one document, but
19943 differ if you have a master document that includes part documents.
19944 That means that relative filenames must be transformed when presented to
19946 Fortunately LyX does this automatically for you if you choose the right
19950 \begin_layout Standard
19951 So which path macro should be used in new template definitions? The rule
19955 \begin_layout Itemize
19957 \begin_inset Flex Code
19960 \begin_layout Plain Layout
19966 if an absolute path is required.
19969 \begin_layout Itemize
19971 \begin_inset Flex Code
19974 \begin_layout Plain Layout
19975 $$AbsOrRelPathMaster
19980 if the substituted string is some kind of LaTeX input.
19983 \begin_layout Itemize
19985 \begin_inset Flex Code
19988 \begin_layout Plain Layout
19989 $$AbsOrRelPathParent
19994 in order to preserve the user's choice.
19997 \begin_layout Standard
19998 There are special cases where this rule does not work and e.
19999 \begin_inset space \thinspace{}
20003 \begin_inset space \space{}
20006 relative names are needed, but normally it will work just fine.
20007 One example for such a case is the command
20008 \begin_inset Flex Code
20011 \begin_layout Plain Layout
20012 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
20017 in the XFig template above: We can't use the absolute name because the
20019 \begin_inset Flex Code
20022 \begin_layout Plain Layout
20028 files needs the relative name in order to rewrite the file content.
20031 \begin_layout Section
20032 Security discussion
20033 \begin_inset CommandInset label
20035 name "sec:Security-discussion"
20042 \begin_layout Standard
20043 The external material feature interfaces with a lot of external programs
20044 and does so automatically, so we have to consider the security implications
20046 In particular, since you have the option of including your own filenames
20047 and/or parameter strings and those are expanded into a command, it seems
20048 that it would be possible to create a malicious document which executes
20049 arbitrary commands when a user views or prints the document.
20050 This is something we definitely want to avoid.
20053 \begin_layout Standard
20054 However, since the external program commands are specified in the template
20055 configuration file only, there are no security issues if LyX is properly
20056 configured with safe templates only.
20057 This is so because the external programs are invoked with the
20058 \begin_inset Flex Code
20061 \begin_layout Plain Layout
20067 -system call rather than the
20068 \begin_inset Flex Code
20071 \begin_layout Plain Layout
20077 system-call, so it's not possible to execute arbitrary commands from the
20078 filename or parameter section via the shell.
20081 \begin_layout Standard
20082 This also implies that you are restricted in what command strings you can
20083 use in the external material templates.
20084 In particular, pipes and redirection are not readily available.
20085 This has to be so if LyX should remain safe.
20086 If you want to use some of the shell features, you should write a safe
20087 script to do this in a controlled manner, and then invoke the script from
20088 the command string.
20092 \begin_layout Standard
20093 It is possible to design a template that interacts directly with the shell,
20094 but since this would allow a malicious user to execute arbitrary commands
20095 by writing clever filenames and/or parameters, we generally recommend that
20096 you only use safe scripts that work with the
20097 \begin_inset Flex Code
20100 \begin_layout Plain Layout
20106 system call in a controlled manner.
20107 Of course, for use in a controlled environment, it can be tempting to just
20108 fall back to use ordinary shell scripts.
20109 If you do so, be aware that you
20113 provide an easily exploitable security hole in your system.
20114 Of course it stands to reason that such unsafe templates will never be
20115 included in the standard LyX distribution, although we do encourage people
20116 to submit new templates in the open source tradition.
20117 But LyX as shipped from the official distribution channels will never have
20121 \begin_layout Standard
20122 Including external material provides a lot of power, and you have to be
20123 careful not to introduce security hazards with this power.
20124 A subtle error in a single line in an innocent looking script can open
20125 the door to huge security problems.
20126 So if you do not fully understand the issues, we recommend that you consult
20127 a knowledgeable security professional or the LyX development team if you
20128 have any questions about whether a given template is safe or not.
20129 And do this before you use it in an uncontrolled environment.