1 #LyX 2.0 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 \options fleqn,bibliography=totoc,index=totoc,BCOR7.5mm,titlepage,captions=tableheading
35 \use_default_options false
39 \maintain_unincluded_children false
42 InsetLayout Flex:MenuItem
51 \newcommand*{\menuitem}[1]{{\sffamily #1}}
54 # In case we need to do with sans...
55 #InsetLayout CharStyle:Code
60 #\renewcommand{\code}[1]{{\sffamily #1}}
65 \language_package default
70 \font_typewriter default
71 \font_default_family default
72 \use_non_tex_fonts false
79 \default_output_format default
81 \bibtex_command default
82 \index_command default
86 \pdf_title "LyX Configuration Manual"
87 \pdf_author "LyX Team"
88 \pdf_subject "LyX-documentation Customization"
89 \pdf_keywords "LyX, documentation, customization"
91 \pdf_bookmarksnumbered true
92 \pdf_bookmarksopen true
93 \pdf_bookmarksopenlevel 1
98 \pdf_pdfusetitle false
99 \pdf_quoted_options "linkcolor=black, citecolor=black, urlcolor=blue, filecolor=blue,pdfpagelayout=OneColumn, pdfnewwindow=true, pdfstartview=XYZ, plainpages=false"
109 \paperorientation portrait
123 \paragraph_separation indent
124 \paragraph_indentation default
125 \quotes_language english
128 \paperpagestyle headings
129 \tracking_changes true
130 \output_changes false
134 \author -195340706 "Georg Baum"
140 Customizing LyX: Features for the Advanced User
148 \begin_layout Plain Layout
150 If you have comments or error corrections, please send them to the LyX Documenta
152 \begin_inset CommandInset href
154 target "lyx-docs@lists.lyx.org"
161 \begin_inset Quotes eld
165 \begin_inset Quotes erd
168 in the subject header, and please cc the current maintainer of this file,
169 Richard Heck <rgheck@comcast.net>.
175 \begin_inset Newline newline
179 \begin_inset Newline newline
185 \begin_layout Standard
186 \begin_inset CommandInset toc
187 LatexCommand tableofcontents
194 \begin_layout Standard
195 \begin_inset Note Note
198 \begin_layout Plain Layout
199 Please use change tracking when modifying this document.
200 This makes it easier for our translators to recognize things that have
201 been changed, and it helps the maintainer keep up-to-date with what's been
210 \begin_layout Chapter
214 \begin_layout Standard
215 This manual covers the customization features present in LyX.
216 In it, we discuss issues like keyboard shortcuts, screen previewing options,
217 printer options, sending commands to LyX via the LyX Server, internationalizati
218 on, installing new LaTeX classes and LyX layouts, etc.
219 We can't possibly hope to touch on everything you can change—our developers
220 add new features faster than we can document them—but we will explain the
221 most common customizations and hopefully point you in the right direction
222 for some of the more obscure ones.
225 \begin_layout Standard
226 \begin_inset Branch OutDated
229 \begin_layout Standard
230 Information from previous versions of this document that now seems to be
231 outdated is contained in the OutDated branch of this document.
232 By default, this information will not appear in the LaTeX output.
240 \begin_layout Chapter
241 LyX configuration files
244 \begin_layout Standard
245 This chapter aims to help you to find your way through the LyX configuration
247 Before continuing to read this chapter, you should find out where your
248 LyX library and user directories are by using
249 \begin_inset Flex MenuItem
252 \begin_layout Plain Layout
253 Help\SpecialChar \menuseparator
264 The library directory is the place where LyX places its system-wide configurati
265 on files; the user directory is where you can place your modified versions.
266 We will call the former
267 \begin_inset Flex Code
270 \begin_layout Plain Layout
277 \begin_inset Flex MenuItem
280 \begin_layout Plain Layout
286 in the remainder of this document.
290 \begin_layout Section
292 \begin_inset Flex Code
295 \begin_layout Plain Layout
304 \begin_layout Standard
305 \begin_inset Flex Code
308 \begin_layout Plain Layout
314 and its sub-directories contain a number of files and that can be used
315 to customize LyX's behavior.
316 You can change many of these files from within LyX itself through the
317 \begin_inset Flex MenuItem
320 \begin_layout Plain Layout
321 Tools\SpecialChar \menuseparator
328 Most customization that you will want to do in LyX is possible through
330 However, many other inner aspects of LyX can be customized by modifying
332 \begin_inset Flex Code
335 \begin_layout Plain Layout
342 These files fall in different categories, described in the following subsection
346 \begin_layout Subsection
347 Automatically generated files
350 \begin_layout Standard
351 The files, which are to be found in
352 \begin_inset Flex MenuItem
355 \begin_layout Plain Layout
361 , are generated when you configure LyX.
362 They contain various default values that are guessed by inspection.
363 In general, it is not a good idea to modify them, since they might be overwritt
367 \begin_layout Labeling
368 \labelwidthstring 00.00.0000
369 \begin_inset Flex Code
372 \begin_layout Plain Layout
378 contains defaults for various commands.
381 \begin_layout Labeling
382 \labelwidthstring 00.00.0000
383 \begin_inset Flex Code
386 \begin_layout Plain Layout
392 contains the list of packages that have been recognized by LyX.
393 It is currently unused by the LyX program itself, but the information extracted
394 , and more, is made available with
395 \begin_inset Flex MenuItem
398 \begin_layout Plain Layout
399 Help\SpecialChar \menuseparator
412 \begin_layout Labeling
413 \labelwidthstring 00.00.0000
414 \begin_inset Flex Code
417 \begin_layout Plain Layout
423 the list of text classes that have been found in your
424 \begin_inset Flex Code
427 \begin_layout Plain Layout
433 directories, along with the associated LaTeX document class and their descripti
437 \begin_layout Labeling
438 \labelwidthstring 00.00.0000
439 \begin_inset Flex Code
442 \begin_layout Plain Layout
448 the list of layout modules found in your
449 \begin_inset Flex Code
452 \begin_layout Plain Layout
461 \begin_layout Labeling
462 \labelwidthstring 00.00.0000
463 \begin_inset Flex Code
466 \begin_layout Plain Layout
472 lists of various sorts of LaTeX-related files found on your system
475 \begin_layout Labeling
476 \labelwidthstring 00.00.0000
477 \begin_inset Flex Code
480 \begin_layout Plain Layout
486 is automatically generated during configuration from the file
487 \begin_inset Flex Code
490 \begin_layout Plain Layout
497 It contains information on your LaTeX configuration.
500 \begin_layout Subsection
504 \begin_layout Standard
505 These directories are duplicated between
506 \begin_inset Flex Code
509 \begin_layout Plain Layout
516 \begin_inset Flex Code
519 \begin_layout Plain Layout
526 If a particular files exists in both places, the one in
527 \begin_inset Flex Code
530 \begin_layout Plain Layout
539 \begin_layout Labeling
540 \labelwidthstring 00.00.0000
541 \begin_inset Flex Code
544 \begin_layout Plain Layout
550 this directory contains files with the extension
551 \begin_inset Flex Code
554 \begin_layout Plain Layout
560 that define the keybindings used in LyX.
561 If there exists an internationalized version of the bind file named
562 \begin_inset Flex Code
565 \begin_layout Plain Layout
571 , that will be used first.
574 \begin_layout Labeling
575 \labelwidthstring 00.00.0000
576 \begin_inset Flex Code
579 \begin_layout Plain Layout
585 contains graphics files that can be included in documents.
589 \begin_layout Labeling
590 \labelwidthstring 00.00.0000
591 \begin_inset Flex Code
594 \begin_layout Plain Layout
600 contains LyX documentation files (including the one you are currently reading).
602 \begin_inset Flex Code
605 \begin_layout Plain Layout
611 deserves special attention, as noted above.
612 The internationalized help docs are in subdirectories
613 \begin_inset Flex Code
616 \begin_layout Plain Layout
623 \begin_inset Quotes eld
627 \begin_inset Quotes erd
630 is the ISO language code.
636 \begin_inset CommandInset ref
638 reference "cha:Internationalizing-LyX"
645 \begin_layout Labeling
646 \labelwidthstring 00.00.0000
647 \begin_inset Flex Code
650 \begin_layout Plain Layout
656 contains example files that explain how to use some features.
657 In the file browser, press the
658 \begin_inset Flex MenuItem
661 \begin_layout Plain Layout
670 \begin_layout Labeling
671 \labelwidthstring 00.00.0000
672 \begin_inset Flex Code
675 \begin_layout Plain Layout
681 contains image files that are used by the
682 \begin_inset Flex MenuItem
685 \begin_layout Plain Layout
692 In addition, it also contains the individual icons used in the toolbar
693 and the banners that can be shown when LyX is launched.
696 \begin_layout Labeling
697 \labelwidthstring 00.00.0000
698 \begin_inset Flex Code
701 \begin_layout Plain Layout
707 contains keyboard keymapping files.
713 \begin_inset CommandInset ref
715 reference "sec:International-Keymap-Stuff"
722 \begin_layout Labeling
723 \labelwidthstring 00.00.0000
724 \begin_inset Flex Code
727 \begin_layout Plain Layout
733 contains the text class and module files described in Chapter
738 \begin_inset CommandInset ref
740 reference "cha:Installing-New-Document"
747 \begin_layout Labeling
748 \labelwidthstring 00.00.0000
749 \begin_inset Flex Code
752 \begin_layout Plain Layout
759 \begin_inset Flex Code
762 \begin_layout Plain Layout
768 Python scripts used to convert between LyX versions.
769 These can be run from the command line if, say, you want to batch-convert
773 \begin_layout Labeling
774 \labelwidthstring 00.00.0000
775 \begin_inset Flex Code
778 \begin_layout Plain Layout
784 contains some files that demonstrate the capabilities of the
785 \begin_inset Flex MenuItem
788 \begin_layout Plain Layout
799 Also contains some scripts used by LyX itself.
802 \begin_layout Labeling
803 \labelwidthstring 00.00.0000
804 \begin_inset Flex Code
807 \begin_layout Plain Layout
813 contains the standard LyX template files described in Chapter
818 \begin_inset CommandInset ref
820 reference "sub:Creating-Templates"
827 \begin_layout Labeling
828 \labelwidthstring 00.00.0000
829 \begin_inset Flex Code
832 \begin_layout Plain Layout
838 contains files with the extension
839 \begin_inset Flex Code
842 \begin_layout Plain Layout
848 that define the user interface to LyX.
849 That is, the files define which items appear in which menus and the items
850 appearing on the toolbar.
853 \begin_layout Subsection
854 Files you don't want to modify
857 \begin_layout Standard
858 These files are used internally by LyX and you generally do not need to
859 modify them unless you are a developer.
862 \begin_layout Labeling
863 \labelwidthstring 00.00.0000
864 \begin_inset Flex Code
867 \begin_layout Plain Layout
873 this file contains the list of LyX developers.
874 The contents are displayed with the menu entry
875 \begin_inset Flex MenuItem
878 \begin_layout Plain Layout
879 Help\SpecialChar \menuseparator
892 \begin_layout Labeling
893 \labelwidthstring 00.00.0000
894 \begin_inset Flex Code
897 \begin_layout Plain Layout
903 this is a LaTeX script used during the configuration process.
907 \begin_layout Labeling
908 \labelwidthstring 00.00.0000
909 \begin_inset Flex Code
912 \begin_layout Plain Layout
918 this is the script that is used to re-configure LyX.
919 It creates configuration files in the directory it was run from.
922 \begin_layout Subsection
923 Other files needing a line or two...
926 \begin_layout Labeling
927 \labelwidthstring 00.00.0000
928 \begin_inset Flex Code
931 \begin_layout Plain Layout
937 this contains tables describing how different character encodings can be
941 \begin_layout Labeling
942 \labelwidthstring 00.00.0000
943 \begin_inset Flex Code
946 \begin_layout Plain Layout
952 this file contains the templates available to the new
953 \begin_inset Flex MenuItem
956 \begin_layout Plain Layout
969 \begin_layout Labeling
970 \labelwidthstring 00.00.0000
971 \begin_inset Flex Code
974 \begin_layout Plain Layout
980 this file contains a list of all the languages currently supported by LyX.
981 \change_inserted -195340706 1334775793
985 \begin_layout Labeling
986 \labelwidthstring 00.00.0000
988 \change_inserted -195340706 1334775793
989 \begin_inset Flex Code
992 \begin_layout Plain Layout
994 \change_inserted -195340706 1334775793
1000 this file contains translations for internationalized paragraph styles
1002 \begin_inset space \thinspace{}
1006 \begin_inset CommandInset ref
1008 reference "sub:I18n"
1017 \begin_layout Section
1018 Your local configuration directory
1021 \begin_layout Standard
1022 Even if you are using LyX as an unprivileged user, you might want to change
1023 LyX configuration for your own use.
1025 \begin_inset Flex Code
1028 \begin_layout Plain Layout
1034 directory contains all your personal configuration files.
1035 This is the directory described as
1036 \begin_inset Quotes eld
1040 \begin_inset Quotes erd
1044 \begin_inset Flex MenuItem
1047 \begin_layout Plain Layout
1048 Help\SpecialChar \menuseparator
1050 \begin_inset space ~
1059 This directory is used as a mirror of
1060 \begin_inset Flex Code
1063 \begin_layout Plain Layout
1069 , which means that every file in
1070 \begin_inset Flex Code
1073 \begin_layout Plain Layout
1079 is a replacement for the corresponding file in
1080 \begin_inset Flex Code
1083 \begin_layout Plain Layout
1090 Any configuration file described in the above sections can be placed either
1091 in the system-wide directory, in which case it will affect all users, or
1092 in your local directory for your own use.
1095 \begin_layout Standard
1096 To make things clearer, let's provide a few examples:
1099 \begin_layout Itemize
1100 The preferences set in the
1101 \begin_inset Flex MenuItem
1104 \begin_layout Plain Layout
1105 Tools\SpecialChar \menuseparator
1111 dialog are saved to a file
1112 \begin_inset Flex Code
1115 \begin_layout Plain Layout
1122 \begin_inset Flex Code
1125 \begin_layout Plain Layout
1134 \begin_layout Itemize
1135 When you reconfigure using
1136 \begin_inset Flex MenuItem
1139 \begin_layout Plain Layout
1140 Tools\SpecialChar \menuseparator
1147 \begin_inset Flex Code
1150 \begin_layout Plain Layout
1156 script, and the resulting files are written in your local configuration
1158 This means that any additional text class file that you might have added
1160 \begin_inset Flex Code
1163 \begin_layout Plain Layout
1169 will be added to the list of classes in the
1170 \begin_inset Flex MenuItem
1173 \begin_layout Plain Layout
1174 Document\SpecialChar \menuseparator
1183 \begin_layout Itemize
1184 If you get some updated documentation from LyX ftp site and cannot install
1185 it because you do not have sysadmin rights on your system, you can just
1187 \begin_inset Flex Code
1190 \begin_layout Plain Layout
1196 and the items in the
1197 \begin_inset Flex MenuItem
1200 \begin_layout Plain Layout
1206 menu will open them!
1209 \begin_layout Section
1210 Running LyX with multiple configurations
1213 \begin_layout Standard
1214 The configuration freedom of the local configuration directory may not suffice
1215 if you want to have more than one configuration at your disposal.
1216 For example, you may want to be use different key bindings or printer settings
1218 You can achieve this by having several such directories.
1219 You then specify which directory to use at run-time.
1222 \begin_layout Standard
1223 Invoking LyX with the command line switch
1224 \begin_inset Flex Code
1227 \begin_layout Plain Layout
1237 instructs the program to read the configuration from that directory, and
1238 not from the default directory.
1239 (You can determine the default directory by running LyX without the
1240 \begin_inset Flex Code
1243 \begin_layout Plain Layout
1249 switch.) If the specified directory does not exist, LyX offers to create
1250 it for you, just like it does for the default directory on the first time
1251 you run the program.
1252 You can modify the configuration options in this additional user directory
1253 exactly as you would for the default directory.
1254 These directories are completely independent (but read on).
1255 Note that setting the environment variable
1256 \begin_inset Flex Code
1259 \begin_layout Plain Layout
1265 to some value has exactly the same effect.
1268 \begin_layout Standard
1269 Having several configurations also requires more maintenance: if you want
1270 to add a new layout to
1271 \begin_inset Flex Code
1274 \begin_layout Plain Layout
1280 which you want available from all your configurations, you must add it
1281 to each directory separately.
1282 You can avoid this with the following trick: after LyX creates the additional
1283 directory, most of the subdirectories (see above) are empty.
1284 If you want the new configuration to mirror an existing one, replace the
1285 empty subdirectory with a symbolic link to the matching subdirectory in
1286 the existing configuration.
1288 \begin_inset Flex Code
1291 \begin_layout Plain Layout
1297 subdirectory, however, since it contains a file written by the configuration
1298 script (also accessible through
1299 \begin_inset Flex MenuItem
1302 \begin_layout Plain Layout
1303 Tools\SpecialChar \menuseparator
1309 ) which is configuration-specific.
1312 \begin_layout Chapter
1313 The Preferences dialog
1316 \begin_layout Standard
1317 All options of the preferences dialog are described in the Appendix
1319 The Preferences Dialog
1326 For some options you might find here more details.
1329 \begin_layout Section
1331 \begin_inset CommandInset label
1340 \begin_layout Standard
1341 The first step is to define your file formats if they are not already defined.
1343 \begin_inset Flex MenuItem
1346 \begin_layout Plain Layout
1347 Tools\SpecialChar \menuseparator
1355 \begin_inset Flex MenuItem
1358 \begin_layout Plain Layout
1359 File Handling\SpecialChar \menuseparator
1366 \begin_inset Flex MenuItem
1369 \begin_layout Plain Layout
1370 New\SpecialChar \ldots{}
1376 button to define your new format.
1378 \begin_inset Flex MenuItem
1381 \begin_layout Plain Layout
1387 field contains the name used to identify the format in the GUI.
1389 \begin_inset Flex MenuItem
1392 \begin_layout Plain Layout
1398 is used to identify the format internally.
1399 You will also need to enter a file extension.
1400 These are all required.
1402 \begin_inset Flex MenuItem
1405 \begin_layout Plain Layout
1411 field is used to provide a keyboard shortcut on the menus.
1412 (For example, pressing
1413 \begin_inset Flex MenuItem
1416 \begin_layout Plain Layout
1423 \begin_inset Flex MenuItem
1426 \begin_layout Plain Layout
1427 View\SpecialChar \menuseparator
1428 View (Other Formats)\SpecialChar \menuseparator
1437 \begin_layout Standard
1439 \begin_inset Flex MenuItem
1442 \begin_layout Plain Layout
1449 \begin_inset Flex MenuItem
1452 \begin_layout Plain Layout
1459 For example, you might want to use
1460 \begin_inset Flex MenuItem
1463 \begin_layout Plain Layout
1469 to view PostScript files.
1470 You can enter the command needed to start the program in the corresponding
1472 In defining this command, you can use the four variables listed in the
1474 The viewer is launched when you view an image in LyX or use the
1475 \begin_inset Flex MenuItem
1478 \begin_layout Plain Layout
1485 The editor is for example launched when you right-click on an image and
1487 \begin_inset Flex MenuItem
1490 \begin_layout Plain Layout
1496 in the appearing context menu.
1499 \begin_layout Standard
1501 \change_inserted -195340706 1329851811
1503 \begin_inset Flex MenuItem
1506 \begin_layout Plain Layout
1512 type of a format is optional, but if it is specified, it must be unique
1514 It is used to detect files of this format from the file contents.
1515 For some important file formats there is no MIME type officially registered
1517 \begin_inset CommandInset href
1520 target "http://www.iana.org/assignments/media-types/"
1525 Therefore LyX uses the extended list of MIME types as specified by
1526 \begin_inset CommandInset href
1528 name "freedesktop.org"
1529 target "http://www.freedesktop.org/wiki/Specifications/shared-mime-info-spec"
1536 \begin_layout Standard
1538 \begin_inset Flex MenuItem
1541 \begin_layout Plain Layout
1547 option tells LyX that a format is suitable for document export.
1548 If this is set and if a suitable conversion route exists (see sec.
1549 \begin_inset space \thinspace{}
1553 \begin_inset CommandInset ref
1555 reference "sec:Converters"
1559 ), the format will appear in the
1560 \begin_inset Flex MenuItem
1563 \begin_layout Plain Layout
1564 File\SpecialChar \menuseparator
1571 The format will also appear in the
1572 \begin_inset Flex MenuItem
1575 \begin_layout Plain Layout
1581 menu if a viewer is specified for the format.
1582 Pure image formats, such as
1583 \begin_inset Flex Code
1586 \begin_layout Plain Layout
1592 , should not use this option.
1593 Formats that can both represent vector graphics and documents like
1594 \begin_inset Flex Code
1597 \begin_layout Plain Layout
1606 \begin_layout Standard
1608 \begin_inset Flex MenuItem
1611 \begin_layout Plain Layout
1612 Vector graphics format
1617 tells LyX that a format can contain vector graphics.
1618 This information is used to determine the target format of included graphics
1620 \begin_inset Flex MenuItem
1623 \begin_layout Plain Layout
1630 Included graphics may need to be converted to either
1631 \begin_inset Flex MenuItem
1634 \begin_layout Plain Layout
1641 \begin_inset Flex MenuItem
1644 \begin_layout Plain Layout
1651 \begin_inset Flex MenuItem
1654 \begin_layout Plain Layout
1661 \begin_inset Flex MenuItem
1664 \begin_layout Plain Layout
1670 cannot handle other image formats.
1671 If an included graphic is not already in
1672 \begin_inset Flex MenuItem
1675 \begin_layout Plain Layout
1682 \begin_inset Flex MenuItem
1685 \begin_layout Plain Layout
1692 \begin_inset Flex MenuItem
1695 \begin_layout Plain Layout
1701 format, it is converted to
1702 \begin_inset Flex MenuItem
1705 \begin_layout Plain Layout
1711 if the vector format option is set, and otherwise to
1712 \begin_inset Flex MenuItem
1715 \begin_layout Plain Layout
1724 \begin_layout Section
1728 \begin_layout Standard
1729 Since all conversions from one format to another take place in LyX's temporary
1730 directory, it is sometimes necessary to modify a file before copying it
1731 to the temporary directory in order that the conversion may be performed.
1735 \begin_layout Plain Layout
1736 For example, the file may refer to other files—images, for example—using
1737 relative file names, and these may become invalid when the file is copied
1738 to the temporary directory.
1743 This is done by a Copier: It copies a file to (or from) the temporary directory
1744 and may modify it in the process.
1747 \begin_layout Standard
1748 The definitions of the copiers may use four variables:
1751 \begin_layout Labeling
1752 \labelwidthstring 00.00.0000
1753 \begin_inset Flex Code
1756 \begin_layout Plain Layout
1762 The LyX system directory (e.
1763 \begin_inset space \thinspace{}
1767 \begin_inset space \space{}
1771 \begin_inset Flex MenuItem
1774 \begin_layout Plain Layout
1783 \begin_layout Labeling
1784 \labelwidthstring 00.00.0000
1785 \begin_inset Flex Code
1788 \begin_layout Plain Layout
1797 \begin_layout Labeling
1798 \labelwidthstring 00.00.0000
1799 \begin_inset Flex Code
1802 \begin_layout Plain Layout
1811 \begin_layout Labeling
1812 \labelwidthstring 00.00.0000
1813 \begin_inset Flex Code
1816 \begin_layout Plain Layout
1825 \begin_layout Standard
1826 The latter should be the filename as it would be used in a LaTeX's
1833 It is relevant only when exporting files suitable for such inclusion.
1836 \begin_layout Standard
1837 Copiers can be used to do almost anything with output files.
1838 For example, suppose you want generated pdf files to be copied to a special
1840 \begin_inset Flex Code
1843 \begin_layout Plain Layout
1850 Then you could write a shell script such as this one:
1853 \begin_layout Standard
1854 \begin_inset listings
1858 \begin_layout Plain Layout
1863 \begin_layout Plain Layout
1868 \begin_layout Plain Layout
1870 TOFILE=`basename $2`
1873 \begin_layout Plain Layout
1875 cp $FROMFILE /home/you/pdf/$TOFILE
1880 Save it in your local LyX directory—say,
1881 \begin_inset Flex Code
1884 \begin_layout Plain Layout
1885 /home/you/.lyx/scripts/pdfcopier.sh
1890 —and make it executable, if you need to do so on your platform.
1892 \begin_inset Flex MenuItem
1895 \begin_layout Plain Layout
1896 Tools\SpecialChar \menuseparator
1902 dialog, select under
1903 \begin_inset Flex MenuItem
1906 \begin_layout Plain Layout
1907 File Handling\SpecialChar \menuseparator
1914 \begin_inset Flex MenuItem
1917 \begin_layout Plain Layout
1923 format—or one of the other pdf formats—and enter
1924 \begin_inset Flex Code
1927 \begin_layout Plain Layout
1928 pdfcopier.sh $$i $$o
1934 \begin_inset Flex MenuItem
1937 \begin_layout Plain Layout
1947 \begin_layout Standard
1948 Copiers are used by LyX in various of its own conversions.
1949 For example, if appropriate programs are found, LyX will automatically
1950 install copiers for the
1951 \begin_inset Flex MenuItem
1954 \begin_layout Plain Layout
1961 \begin_inset Flex MenuItem
1964 \begin_layout Plain Layout
1966 \begin_inset space ~
1975 When these formats are exported, the copier sees that not just the main
1976 HTML file but various associated files (style files, images, etc.) are also
1978 All these files are written to a subdirectory of the directory in which
1979 the original LyX file was found.
1983 \begin_layout Plain Layout
1984 This copier can be customized.
1986 \begin_inset Quotes eld
1990 \begin_inset Quotes erd
1993 argument takes a comma-separated list of extensions to be copied; if it
1994 is omitted, all files will be copied.
1996 \begin_inset Quotes eld
2000 \begin_inset Quotes erd
2003 argument determines the extension added to the generated directory.
2005 \begin_inset Quotes eld
2009 \begin_inset Flex MenuItem
2012 \begin_layout Plain Layout
2019 \begin_inset Quotes erd
2022 , so HTML generated from
2023 \begin_inset Flex MenuItem
2026 \begin_layout Plain Layout
2027 /path/to/filename.lyx
2033 \begin_inset Flex MenuItem
2036 \begin_layout Plain Layout
2037 /path/to/filename.html.LyXconv
2051 \begin_layout Section
2053 \begin_inset CommandInset label
2055 name "sec:Converters"
2062 \begin_layout Standard
2063 You can define your own Converters to convert files between different formats.
2065 \begin_inset Flex MenuItem
2068 \begin_layout Plain Layout
2069 Tools\SpecialChar \menuseparator
2070 Preferences\SpecialChar \menuseparator
2071 File Handling\SpecialChar \menuseparator
2080 \begin_layout Standard
2081 To define a new converter, select the
2082 \begin_inset Flex MenuItem
2085 \begin_layout Plain Layout
2087 \begin_inset space ~
2096 \begin_inset Flex MenuItem
2099 \begin_layout Plain Layout
2101 \begin_inset space ~
2109 from the drop-down lists, enter the command needed for the conversion,
2111 \begin_inset Flex MenuItem
2114 \begin_layout Plain Layout
2121 Several variables can be used in the definition of converters:
2124 \begin_layout Labeling
2125 \labelwidthstring 00.00.0000
2126 \begin_inset Flex Code
2129 \begin_layout Plain Layout
2135 The LyX system directory
2138 \begin_layout Labeling
2139 \labelwidthstring 00.00.0000
2140 \begin_inset Flex Code
2143 \begin_layout Plain Layout
2152 \begin_layout Labeling
2153 \labelwidthstring 00.00.0000
2154 \begin_inset Flex Code
2157 \begin_layout Plain Layout
2166 \begin_layout Labeling
2167 \labelwidthstring 00.00.0000
2168 \begin_inset Flex Code
2171 \begin_layout Plain Layout
2177 The base filename of the input file (i.
2178 \begin_inset space \thinspace{}
2181 g., without the extension)
2184 \begin_layout Labeling
2185 \labelwidthstring 00.00.0000
2186 \begin_inset Flex Code
2189 \begin_layout Plain Layout
2195 The path to the input file
2198 \begin_layout Labeling
2199 \labelwidthstring 00.00.0000
2200 \begin_inset Flex Code
2203 \begin_layout Plain Layout
2209 The path to the original input file (this is different from $$p when a
2210 chain of converters is called)
2213 \begin_layout Labeling
2214 \labelwidthstring 00.00.0000
2215 \begin_inset Flex Code
2218 \begin_layout Plain Layout
2224 The iconv name for the encoding of the document.
2227 \begin_layout Standard
2229 \begin_inset Flex MenuItem
2232 \begin_layout Plain Layout
2234 \begin_inset space ~
2242 field you can enter the following flags, separated by commas:
2245 \begin_layout Labeling
2246 \labelwidthstring 00.00.0000
2247 \begin_inset Flex Code
2250 \begin_layout Plain Layout
2256 This converter runs some form of LaTeX.
2257 This will make LyX's LaTeX error logs available.
2260 \begin_layout Labeling
2261 \labelwidthstring 00.00.0000
2262 \begin_inset Flex Code
2265 \begin_layout Plain Layout
2272 \begin_inset Flex MenuItem
2275 \begin_layout Plain Layout
2281 file for the conversion.
2284 \begin_layout Labeling
2285 \labelwidthstring 00.00.0000
2286 \begin_inset Flex Code
2289 \begin_layout Plain Layout
2298 \begin_layout Standard
2299 The following three flags are not really flags at all because they take
2301 \begin_inset Flex MenuItem
2304 \begin_layout Plain Layout
2306 \begin_inset space ~
2310 \begin_inset space ~
2321 \begin_layout Labeling
2322 \labelwidthstring 00.00.0000
2323 \begin_inset Flex Code
2326 \begin_layout Plain Layout
2332 If set, the converter's standard error will be redirected to a file
2333 \begin_inset Flex Code
2336 \begin_layout Plain Layout
2342 , and the script given as argument will be run as:
2343 \begin_inset Flex Code
2346 \begin_layout Plain Layout
2347 script < infile.out > infile.log
2353 The argument may contain
2354 \begin_inset Flex Code
2357 \begin_layout Plain Layout
2366 \begin_layout Labeling
2367 \labelwidthstring 00.00.0000
2368 \begin_inset Flex Code
2371 \begin_layout Plain Layout
2377 The name of the directory in which the converter will dump the generated
2379 LyX will not create this directory, and it does not copy anything into
2380 it, though it will copy this directory to the destination.
2381 The argument may contain
2382 \begin_inset Flex Code
2385 \begin_layout Plain Layout
2391 , which will be replaced by the base name of the input and output files,
2392 respectively, when the directory is copied.
2393 \begin_inset Newline newline
2396 Note that resultdir and usetempdir make no sense together.
2397 The latter will be ignored if the former is given.
2400 \begin_layout Labeling
2401 \labelwidthstring 00.00.0000
2402 \begin_inset Flex Code
2405 \begin_layout Plain Layout
2411 Determines the output file name and may, contain
2412 \begin_inset Flex Code
2415 \begin_layout Plain Layout
2422 Sensible only with resultdir and optional even then; if not given, it defaults
2426 \begin_layout Standard
2427 None of these last three are presently used in any of the converters that
2428 are installed with LyX.
2432 \begin_layout Standard
2433 You do not have to define converters for all formats between which you want
2435 For example, you will note that there is no `LyX to PostScript' converter,
2436 but LyX will export PostScript.
2437 It does so by first creating a LaTeX file (no converter needs to be defined
2438 for this) which is then converted to DVI using the `LaTeX to DVI' converter,
2439 and finally converting the resulting DVI file to PostScript.
2440 LyX finds such `chains' of converters automatically, and it will always
2441 choose the shortest possible chain.
2442 You can, though, still define multiple conversion methods between file
2444 For example, the standard LyX configuration provides three ways to convert
2445 LaTeX to PDF: Directly, using
2446 \begin_inset Flex MenuItem
2449 \begin_layout Plain Layout
2455 ; via (DVI and) PostScript, using
2456 \begin_inset Flex MenuItem
2459 \begin_layout Plain Layout
2466 \begin_inset Flex MenuItem
2469 \begin_layout Plain Layout
2476 To define such alternate chains, you must define multiple target `file
2477 formats', as described in section
2478 \begin_inset CommandInset ref
2480 reference "sec:Formats"
2485 For example, in the standard configuration, the formats named
2486 \begin_inset Flex MenuItem
2489 \begin_layout Plain Layout
2496 \begin_inset Flex MenuItem
2499 \begin_layout Plain Layout
2506 \begin_inset Flex MenuItem
2509 \begin_layout Plain Layout
2515 are defined, all of which share the extension
2516 \begin_inset Flex MenuItem
2519 \begin_layout Plain Layout
2525 , and which correspond to the conversion methods just mentioned.
2528 \begin_layout Chapter
2529 Internationalizing LyX
2530 \begin_inset CommandInset label
2532 name "cha:Internationalizing-LyX"
2539 \begin_layout Standard
2540 LyX supports using a translated interface.
2541 Last time we checked, LyX provided text in thirty languages.
2542 The language of choice is called your
2547 (For further reading on locale settings, see also the documentation for
2548 locale that comes with your operating system.
2549 For Linux, the manual page for
2550 \begin_inset Flex Code
2553 \begin_layout Plain Layout
2559 could be a good place to start).
2562 \begin_layout Standard
2563 Notice that these translations will work, but do contain a few flaws.
2564 In particular, all dialogs have been designed with the English text in
2565 mind, which means that some of the translated text will be too large to
2566 fit within the space allocated.
2567 This is only a display problem and will not cause any harm.
2568 Also, you will find that some of the translations do not define shortcut
2569 keys for everything.
2570 Sometimes, there are simply not enough free letters to do it.
2571 Other times, the translator just hasn't got around to doing it yet.
2572 Our localization team, which you may wish to join,
2576 \begin_layout Plain Layout
2577 If you are a fluent speaker of a language other than English, joining these
2578 teams is a great way to give back to the LyX community!
2583 will of course try to fix these shortcomings in future versions of LyX.
2586 \begin_layout Section
2590 \begin_layout Subsection
2591 Translating the graphical user interface (text messages).
2594 \begin_layout Standard
2596 \begin_inset Flex Code
2599 \begin_layout Plain Layout
2605 library to handle the internationalization of the interface.
2606 To have LyX speak your favorite language in all menus and dialogs, you
2608 \begin_inset Flex Code
2611 \begin_layout Plain Layout
2617 -file for that language.
2618 When this is available, you'll have to generate a
2619 \begin_inset Flex Code
2622 \begin_layout Plain Layout
2628 -file from it and install the
2629 \begin_inset Flex Code
2632 \begin_layout Plain Layout
2639 The process of doing all of this is explained in the documentation for
2641 \begin_inset Flex Code
2644 \begin_layout Plain Layout
2651 It is possible to do this just for yourself, but if you're going to do
2652 it, you might as well share the results of your labors with the rest of
2654 Send a message to the LyX developers' list for more information about how
2658 \begin_layout Standard
2659 In short, this is what you should do (xx denotes the language code):
2662 \begin_layout Itemize
2663 Check out the LyX source code.
2665 \begin_inset CommandInset href
2667 name "information on the web"
2668 target "http://www.lyx.org/HowToUseSVN"
2675 \begin_layout Itemize
2677 \begin_inset Flex Code
2680 \begin_layout Plain Layout
2686 to the folder of the
2687 \begin_inset Flex Code
2690 \begin_layout Plain Layout
2698 \begin_inset Flex Code
2701 \begin_layout Plain Layout
2709 \begin_inset Flex Code
2712 \begin_layout Plain Layout
2718 doesn't exist anywhere, it can be remade with the console command
2719 \begin_inset Flex Code
2722 \begin_layout Plain Layout
2728 in that directory, or you can use an existing po-file for some other language
2732 \begin_layout Itemize
2734 \begin_inset Flex Code
2737 \begin_layout Plain Layout
2747 \begin_layout Plain Layout
2748 This is just a text file, so it can be edited in any text editor.
2749 But there are also specialized programs that support such editing, such
2754 (for all platforms) or
2763 contains a `mode' for editing
2764 \begin_inset Flex Code
2767 \begin_layout Plain Layout
2778 For some menu- and widget-labels, there are also shortcut keys that should
2780 Those keys are marked after a `|', and should be translated according to
2781 the words and phrases of the language.
2782 You should also fill also out the information at the beginning of the new
2784 \begin_inset Flex Code
2787 \begin_layout Plain Layout
2793 -file with your email-address, etc., so people know where to reach you with
2794 suggestions and entertaining flames.
2797 \begin_layout Standard
2798 If you are just doing this on your own, then:
2801 \begin_layout Itemize
2803 \begin_inset Flex Code
2806 \begin_layout Plain Layout
2813 This can be done with
2814 \begin_inset Flex Code
2817 \begin_layout Plain Layout
2818 msgfmt -o xx.mo < xx.po
2826 \begin_layout Itemize
2828 \begin_inset Flex Code
2831 \begin_layout Plain Layout
2837 -file to your locale-tree, at the correct directory for application messages
2842 xx, and under the name
2843 \begin_inset Flex Code
2846 \begin_layout Plain Layout
2853 \begin_inset space \thinspace{}
2857 \begin_inset space \space{}
2861 \begin_inset Flex Code
2864 \begin_layout Plain Layout
2865 /usr/local/share/locale/xx/LC_MESSAGES/lyx.mo
2875 \begin_layout Standard
2876 As said, however, it would be best if the new
2877 \begin_inset Flex Code
2880 \begin_layout Plain Layout
2886 -file could be added to the LyX distribution, so others can use it.
2887 Adding it involves making additional changes to LyX.
2888 So send an email to the developers' mailing list if you're interested in
2892 \begin_layout Subsubsection
2896 \begin_layout Standard
2897 Sometimes it turns out that one English message needs to be translated into
2898 different messages in the target language.
2899 One example is the message
2900 \begin_inset Flex Code
2903 \begin_layout Plain Layout
2909 which has the German translation
2917 , depending upon exactly what the English
2918 \begin_inset Quotes eld
2922 \begin_inset Quotes erd
2927 \begin_inset Flex Code
2930 \begin_layout Plain Layout
2936 does not handle such ambiguous translations.
2937 Therefore you have to add some context information to the message: Instead
2939 \begin_inset Flex Code
2942 \begin_layout Plain Layout
2949 \begin_inset Flex Code
2952 \begin_layout Plain Layout
2953 To[[as in 'From format x to format y']]
2959 \begin_inset Flex Code
2962 \begin_layout Plain Layout
2963 To[[as in 'From page x to page y']].
2968 Now the two occurrences of
2969 \begin_inset Flex Code
2972 \begin_layout Plain Layout
2979 \begin_inset Flex Code
2982 \begin_layout Plain Layout
2988 and can be translated correctly to
2999 \begin_layout Standard
3000 Of course the context information needs to be stripped off the original
3001 message when no translation is used.
3002 Therefore you have to put it in double square brackets at the end of the
3003 message (see the example above).
3004 The translation mechanism of LyX ensures that everything in double square
3005 brackets at the end of messages is removed before displaying the message.
3008 \begin_layout Subsection
3009 Translating the documentation.
3012 \begin_layout Standard
3013 The online documentation (in the
3014 \begin_inset Flex MenuItem
3017 \begin_layout Plain Layout
3023 -menu) can (and should!) be translated.
3024 If there are translated versions of the documentation available
3028 \begin_layout Plain Layout
3029 As of March 2008, at least some of the documents have been translated into
3030 fourteen languages, with the Tutorial available in a few more.
3035 and the locale is set accordingly, these will be used automagically by
3037 LyX looks for translated versions as
3038 \begin_inset Flex Code
3041 \begin_layout Plain Layout
3042 LyXDir/doc/xx/DocName.lyx
3048 \begin_inset Flex Code
3051 \begin_layout Plain Layout
3057 is the code for the language currently in use.
3058 If there are no translated documents, the default English versions will
3060 Note that the translated versions must have the same filenames (
3061 \begin_inset Flex Code
3064 \begin_layout Plain Layout
3070 above) as the original.
3071 If you feel up to translating the documentation (an excellent way to proof-read
3072 the original documentation by the way!), there are a few things you should
3076 \begin_layout Itemize
3077 Check out the documentation translation web page at
3078 \begin_inset CommandInset href
3080 name "http://www.lyx.org/Translation"
3081 target "http://www.lyx.org/Translation"
3086 That way, you can find out which (if any) documents have already been translate
3087 d into your language.
3088 You can also find out who (if anyone) is organizing the effort to translate
3089 the documentation into your language.
3090 If no one is organizing the effort, please let us know that you're interested.
3093 \begin_layout Standard
3094 Once you get to actually translating, here's a few hints for you that may
3098 \begin_layout Itemize
3099 Join the documentation team! There is information on how to do that in
3100 \begin_inset Flex Code
3103 \begin_layout Plain Layout
3110 \begin_inset Flex MenuItem
3113 \begin_layout Plain Layout
3114 Help\SpecialChar \menuseparator
3120 ), which by the way is the first document you should translate.
3123 \begin_layout Itemize
3124 Learn the typographic conventions for the language you are translating to.
3125 Typography is an ancient art and over the centuries, a great variety of
3126 conventions have developed throughout different parts of the world.
3127 Also study the professional terminology amongst typographers in your country.
3128 Inventing your own terminology will only confuse the users.
3131 (Warning! Typography is addictive!)
3134 \begin_layout Itemize
3135 Make a copy of the document.
3136 This will be your working copy.
3137 You can use this as your personal translated help-file by placing it in
3139 \begin_inset Flex Code
3142 \begin_layout Plain Layout
3151 \begin_layout Itemize
3152 Sometimes the original document (from the LyX-team) will be updated.
3153 Use the source viewer at
3154 \begin_inset CommandInset href
3156 name "http://www.lyx.org/trac/timeline"
3157 target "http://www.lyx.org/trac/timeline"
3161 to see what has been changed.
3162 That way you can easily see which parts of the translated document need
3166 \begin_layout Standard
3167 If you ever find an error in the original document, fix it and notify the
3168 rest of the documentation team of the changes! (You didn't forget to join
3169 the documentation team, did you?)
3172 \begin_layout Standard
3173 \begin_inset Branch OutDated
3176 \begin_layout Section
3177 International Keyboard Support
3180 \begin_layout Standard
3183 [Editor's Note: The following section is by
3191 It needs to be fixed to conform to the new Documentation Style sheet and
3192 to make use of the new v1.0 features.
3193 The whole thing also needs to be merged with the section following it.-jw
3194 It may also be badly out of date.-rh (2008)]
3197 \begin_layout Subsection
3198 Defining Own Keymaps: Keymap File Format
3201 \begin_layout Standard
3202 Let's look at a keyboard definition file a little closer.
3203 It is a plain text file defining
3206 \begin_layout Itemize
3207 key-to-key or key-to-string translations
3210 \begin_layout Itemize
3214 \begin_layout Itemize
3215 dead keys exceptions
3218 \begin_layout Standard
3219 To define key-to-key or key-to-string translation, use this command:
3222 \begin_layout Quotation
3223 \begin_inset Flex Code
3226 \begin_layout Plain Layout
3235 \begin_inset Flex Code
3238 \begin_layout Plain Layout
3247 \begin_layout Standard
3249 \begin_inset Flex Code
3252 \begin_layout Plain Layout
3258 is the key to be translated and
3259 \begin_inset Flex Code
3262 \begin_layout Plain Layout
3268 is the string to be inserted into the document.
3269 To define dead keys, use:
3272 \begin_layout Quotation
3273 \begin_inset Flex Code
3276 \begin_layout Plain Layout
3285 \begin_inset Flex Code
3288 \begin_layout Plain Layout
3297 \begin_layout Standard
3299 \begin_inset Flex Code
3302 \begin_layout Plain Layout
3308 is a keyboard key and
3309 \begin_inset Flex Code
3312 \begin_layout Plain Layout
3319 The following dead keys are supported (shortcut name is in parentheses):
3322 \begin_layout Quotation
3326 \begin_inset space \hfill{}
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{}
3356 \begin_layout Quotation
3358 \begin_inset space \hfill{}
3364 \begin_layout Quotation
3366 \begin_inset space \hfill{}
3373 \begin_layout Plain Layout
3385 \begin_layout Quotation
3387 \begin_inset space \hfill{}
3393 \begin_layout Quotation
3395 \begin_inset space \hfill{}
3402 \begin_layout Plain Layout
3414 \begin_layout Quotation
3416 \begin_inset space \hfill{}
3422 \begin_layout Quotation
3424 \begin_inset space \hfill{}
3430 \begin_layout Quotation
3432 \begin_inset space \hfill{}
3439 \begin_layout Plain Layout
3451 \begin_layout Quotation
3453 \begin_inset space \hfill{}
3460 \begin_layout Plain Layout
3472 \begin_layout Quotation
3474 \begin_inset space \hfill{}
3480 \begin_layout Quotation
3481 hungarian umlaut (hug)
3482 \begin_inset space \hfill{}
3488 \begin_layout Quotation
3490 \begin_inset space \hfill{}
3496 \begin_layout Quotation
3498 \begin_inset space \hfill{}
3505 \begin_layout Plain Layout
3517 \begin_layout Standard
3518 Since in many international keyboards there are exceptions to what some
3519 dead keys should do, you can define them using
3522 \begin_layout Quotation
3523 \begin_inset Flex Code
3526 \begin_layout Plain Layout
3534 deadkey key outstring
3537 \begin_layout Standard
3538 For example, on Slovak keyboard, if you enter caron-o, it generates circumflex-o
3542 \begin_layout Quotation
3543 \begin_inset Flex Code
3546 \begin_layout Plain Layout
3559 \begin_layout Standard
3560 to make it work correctly.
3561 Also, you have to define as exceptions dead keys over i and j, to remove
3562 the dot from them before inserting an accent mark.
3563 I will change this when the time comes, but so far I haven't had time.
3566 \begin_layout Standard
3567 Oh, and about characters: backslash is escaped, so to enter it, you'll need
3570 \begin_inset Flex Code
3573 \begin_layout Plain Layout
3579 have different meaning.
3581 \begin_inset Flex Code
3584 \begin_layout Plain Layout
3590 marks comments, quotes start and end LaTeX-style commands.
3591 To enter quote, you'll need to use
3592 \begin_inset Flex Code
3595 \begin_layout Plain Layout
3604 \begin_inset Flex Code
3607 \begin_layout Plain Layout
3614 \begin_inset Flex Code
3617 \begin_layout Plain Layout
3628 \begin_layout Standard
3629 If you make a keyboard description file that works for your language, please
3630 mail it to me, so I can include it in the next keymap distribution.
3633 \begin_layout Standard
3634 More keywords will be supported in keymap configuration file in future,
3638 \begin_layout Itemize
3639 \begin_inset Flex Code
3642 \begin_layout Plain Layout
3653 \begin_inset space \hfill{}
3657 \begin_inset Flex Code
3660 \begin_layout Plain Layout
3669 \begin_layout Itemize
3670 \begin_inset Flex Code
3673 \begin_layout Plain Layout
3684 \begin_inset space \hfill{}
3688 \begin_inset Flex Code
3691 \begin_layout Plain Layout
3697 an external keymap translation program
3700 \begin_layout Standard
3701 Also, it should look into
3702 \begin_inset Flex Code
3705 \begin_layout Plain Layout
3711 file for defaults, too (for example, a
3712 \begin_inset Flex Code
3715 \begin_layout Plain Layout
3723 option to include default keyboard).
3731 \begin_layout Section
3732 International Keymap Stuff
3733 \begin_inset CommandInset label
3735 name "sec:International-Keymap-Stuff"
3742 \begin_layout Standard
3743 \begin_inset Note Note
3746 \begin_layout Plain Layout
3747 In doing the revisions on this document in March 2008, I did not look over
3748 this stuff, as I do not understand it.
3749 It would be good if someone else could do so.
3758 \begin_layout Standard
3759 The next two sections describe the
3760 \begin_inset Flex Code
3763 \begin_layout Plain Layout
3772 \begin_inset Flex Code
3775 \begin_layout Plain Layout
3783 file syntax in detail.
3784 These sections should help you design your own key map if the ones provided
3785 do not meet your needs.
3788 \begin_layout Subsection
3792 \begin_layout Standard
3796 \begin_inset Flex Code
3799 \begin_layout Plain Layout
3805 file maps keystrokes to characters or strings.
3806 As the name suggests, it sets a keyboard mapping.
3808 \begin_inset Flex Code
3811 \begin_layout Plain Layout
3822 \begin_inset Flex Code
3825 \begin_layout Plain Layout
3840 \begin_inset Flex Code
3843 \begin_layout Plain Layout
3856 \begin_inset Flex Code
3859 \begin_layout Plain Layout
3868 \begin_inset Flex Code
3871 \begin_layout Plain Layout
3879 are described in this section.
3882 \begin_layout Labeling
3883 \labelwidthstring 00.00.0000
3884 \begin_inset Flex Code
3887 \begin_layout Plain Layout
3895 Map a character to a string
3898 \begin_layout LyX-Code
3913 \begin_layout Standard
3946 the double-quote (")
3963 must be escaped with a preceding backslash (
3974 \begin_layout Standard
3976 \begin_inset Flex MenuItem
3979 \begin_layout Plain Layout
3987 statement to cause the symbol
3988 \begin_inset Flex MenuItem
3991 \begin_layout Plain Layout
3999 to be output for the keystroke
4000 \begin_inset Flex MenuItem
4003 \begin_layout Plain Layout
4014 \begin_layout LyX-Code
4020 \begin_layout Labeling
4021 \labelwidthstring 00.00.0000
4022 \begin_inset Flex Code
4025 \begin_layout Plain Layout
4033 Specify an accent character
4036 \begin_layout LyX-Code
4045 \begin_layout Standard
4046 This will make the cha
4084 This is the dead key
4088 \begin_layout Plain Layout
4095 refers to a key that does not produce a character by itself, but when followed
4096 with another key, produces the desired accent character.
4097 For example, a German characte
4099 r with an umlaut like
4109 can be produced in this manner.
4118 \begin_layout Standard
4131 and then another key not in
4148 followed by the other, not allowed key, as output.
4152 \begin_inset Flex MenuItem
4155 \begin_layout Plain Layout
4163 cancels a dead key, so if
4174 \begin_inset Flex MenuItem
4177 \begin_layout Plain Layout
4186 , the cursor will not go one position backwards but will instead cancel
4202 might have had on the next keystroke.
4206 \begin_layout Standard
4207 The following example specifies that the character ' is to be an acute accent,
4208 allowed on the characters a, e, i, o, u, A, E, I, O, and U:
4211 \begin_layout LyX-Code
4214 kmod ' acute aeiouAEIOU
4217 \begin_layout Labeling
4218 \labelwidthstring 00.00.0000
4219 \begin_inset Flex Code
4222 \begin_layout Plain Layout
4228 Specify an exception to the accent character
4231 \begin_layout LyX-Code
4240 \begin_layout Standard
4241 This defines an exce
4282 have been assigned a keystroke with a previous
4285 \begin_inset Flex Code
4288 \begin_layout Plain Layout
4312 must not belong in the
4359 If such a declaration does not exist in
4367 \begin_inset Flex Code
4370 \begin_layout Plain Layout
4404 \begin_inset Flex Code
4407 \begin_layout Plain Layout
4421 \begin_layout Standard
4422 The following command produces causes äi to be produced when you enter acute-i
4426 \begin_layout LyX-Code
4440 \begin_layout Labeling
4441 \labelwidthstring 00.00.0000
4442 \begin_inset Flex Code
4445 \begin_layout Plain Layout
4451 Combine two accent characters
4454 \begin_layout LyX-Code
4460 accent1 accent2 allowed
4463 \begin_layout Standard
4464 This one is getting pretty esoteric.
4465 It allows you to combine the effect
4521 \begin_inset Flex Code
4524 \begin_layout Plain Layout
4552 \begin_layout Standard
4553 Consider this example from the
4554 \begin_inset Flex Code
4557 \begin_layout Plain Layout
4568 \begin_layout LyX-Code
4571 kmod ; acute aeioyvhAEIOYVH
4575 kcomb acute umlaut iyIY
4578 \begin_layout Standard
4579 This allows you to press
4580 \begin_inset Flex MenuItem
4583 \begin_layout Plain Layout
4591 and get the effect of
4592 \begin_inset Flex Code
4595 \begin_layout Plain Layout
4614 in this case cancels the last dead key, so if you press
4615 \begin_inset Flex MenuItem
4618 \begin_layout Plain Layout
4627 \begin_inset Flex Code
4630 \begin_layout Plain Layout
4643 \begin_layout Subsection
4647 \begin_layout Standard
4649 \begin_inset Flex Code
4652 \begin_layout Plain Layout
4660 mapping is performed, a
4661 \begin_inset Flex Code
4664 \begin_layout Plain Layout
4674 file maps the strings that the symbols generate to characters in the current
4676 The LyX distribution currently includes at least the
4677 \begin_inset Flex Code
4680 \begin_layout Plain Layout
4689 \begin_inset Flex Code
4692 \begin_layout Plain Layout
4703 \begin_layout Standard
4705 \begin_inset Flex Code
4708 \begin_layout Plain Layout
4716 file is a sequence of declarations of the form
4719 \begin_layout LyX-Code
4732 \begin_layout Standard
4733 For example, in order to map
4734 \begin_inset Flex MenuItem
4737 \begin_layout Plain Layout
4747 to the corresponding character in the iso-8859-1 set (233), the following
4751 \begin_layout LyX-Code
4759 \begin_layout Standard
4761 \begin_inset Flex Code
4764 \begin_layout Plain Layout
4773 \begin_inset Flex Code
4776 \begin_layout Plain Layout
4794 the same character can apply to more than one string.
4796 \begin_inset Flex Code
4799 \begin_layout Plain Layout
4810 \begin_layout LyX-Code
4822 \begin_inset Newline newline
4838 \begin_layout Standard
4839 If LyX cannot find a mapping for the string produced by the keystroke or
4840 a deadkey sequence, it will check if it looks like an accented char and
4841 try to draw an accent over the character on screen.
4844 \begin_layout Subsection
4848 \begin_layout Standard
4849 There is a second way to add support for international characters through
4850 so-called dead-keys.
4851 A dead-key works in combination with a letter to produce an accented character.
4852 Here, we'll explain how to create a really simple dead-key to illustrate
4856 \begin_layout Standard
4857 Suppose you happen to need the circumflex character,
4858 \begin_inset Quotes eld
4862 \begin_inset Quotes erd
4867 \begin_inset Flex MenuItem
4870 \begin_layout Plain Layout
4877 \begin_inset space ~
4881 \begin_inset Flex MenuItem
4884 \begin_layout Plain Layout
4890 ] to the LyX command
4891 \begin_inset Flex Code
4894 \begin_layout Plain Layout
4901 \begin_inset Flex Code
4904 \begin_layout Plain Layout
4911 Now, whenever you type the
4912 \begin_inset Flex MenuItem
4915 \begin_layout Plain Layout
4921 -key followed by a letter, that letter will have a circumflex accent on
4923 For example, the sequence
4924 \begin_inset Quotes eld
4928 \begin_inset Flex MenuItem
4931 \begin_layout Plain Layout
4938 \begin_inset Quotes erd
4941 produces the letter:
4942 \begin_inset Quotes eld
4946 \begin_inset Quotes erd
4950 If you tried to type
4951 \begin_inset Quotes eld
4955 \begin_inset Flex MenuItem
4958 \begin_layout Plain Layout
4965 \begin_inset Quotes erd
4968 , however, LyX will complain with a beep, since a
4969 \begin_inset Quotes eld
4973 \begin_inset Flex MenuItem
4976 \begin_layout Plain Layout
4983 \begin_inset Quotes erd
4986 never takes a circumflex accent.
4988 \begin_inset Flex MenuItem
4991 \begin_layout Plain Layout
4997 after a dead-key produces the bare-accent.
4998 Please note this last point! If you bind a key to a dead-key, you'll need
4999 to rebind the character on that key to yet another key.
5001 \begin_inset Flex MenuItem
5004 \begin_layout Plain Layout
5010 to a cedilla is a bad idea, since you'll only get cedillas instead of commas.
5013 \begin_layout Standard
5014 One common way to bind dead-keys is to use
5015 \begin_inset Flex MenuItem
5018 \begin_layout Plain Layout
5025 \begin_inset Flex MenuItem
5028 \begin_layout Plain Layout
5035 \begin_inset Flex MenuItem
5038 \begin_layout Plain Layout
5044 in combination with an accent, like
5045 \begin_inset Quotes eld
5049 \begin_inset Flex MenuItem
5052 \begin_layout Plain Layout
5059 \begin_inset Quotes erd
5063 \begin_inset Quotes eld
5067 \begin_inset Flex MenuItem
5070 \begin_layout Plain Layout
5077 \begin_inset Quotes erd
5081 \begin_inset Quotes eld
5085 \begin_inset Flex MenuItem
5088 \begin_layout Plain Layout
5095 \begin_inset Quotes erd
5099 Another way involves using
5100 \begin_inset Flex Code
5103 \begin_layout Plain Layout
5110 \begin_inset Flex Code
5113 \begin_layout Plain Layout
5119 to set up the special
5120 \begin_inset Flex Code
5123 \begin_layout Plain Layout
5131 \begin_inset Flex Code
5134 \begin_layout Plain Layout
5140 acts in some ways just like
5141 \begin_inset Flex MenuItem
5144 \begin_layout Plain Layout
5150 and permits you to bind keys to accented characters.
5151 You can also turn keys into dead-keys by binding them to something like
5153 \begin_inset Flex Code
5156 \begin_layout Plain Layout
5162 and then binding this symbolic key to the corresponding LyX command.
5166 \begin_layout Plain Layout
5171 : This is exactly what I do in my
5172 \begin_inset Flex Code
5175 \begin_layout Plain Layout
5182 \begin_inset Flex Code
5185 \begin_layout Plain Layout
5193 \begin_inset Flex MenuItem
5196 \begin_layout Plain Layout
5198 \begin_inset space ~
5207 \begin_inset Flex Code
5210 \begin_layout Plain Layout
5216 and a bunch of these
5217 \begin_inset Quotes eld
5221 \begin_inset Flex Code
5224 \begin_layout Plain Layout
5231 \begin_inset Quotes erd
5234 symbolic keys bound such things as
5235 \begin_inset Flex MenuItem
5238 \begin_layout Plain Layout
5240 \begin_inset space ~
5249 \begin_inset Flex MenuItem
5252 \begin_layout Plain Layout
5254 \begin_inset space ~
5263 This is how I produce my accented characters.
5268 You can make just about anything into the
5269 \begin_inset Flex Code
5272 \begin_layout Plain Layout
5279 \begin_inset Flex MenuItem
5282 \begin_layout Plain Layout
5288 keys, a spare function key, etc.
5289 As for the LyX commands that produce accents, check the entry for
5290 \begin_inset Flex Code
5293 \begin_layout Plain Layout
5304 You'll find the complete list there.
5307 \begin_layout Subsection
5308 Saving your Language Configuration
5311 \begin_layout Standard
5312 You can edit your preferences so that your desired language environment
5313 is automatically configured when LyX starts up, via the
5314 \begin_inset Flex MenuItem
5317 \begin_layout Plain Layout
5318 Edit\SpecialChar \menuseparator
5327 \begin_layout Chapter
5328 Installing New Document Classes, Layouts, and Templates
5329 \begin_inset CommandInset label
5331 name "cha:Installing-New-Document"
5336 \begin_inset Argument
5339 \begin_layout Plain Layout
5340 Installing New Document Classes
5348 \begin_layout Standard
5349 In this chapter, we describe the procedures for creating and installing
5350 new LyX layout and template files, as well as offer a refresher on correctly
5351 installing new LaTeX document classes.
5355 \begin_layout Standard
5356 First, let us a say a few words about how one ought to think about the relation
5357 between LyX and LaTeX.
5358 The thing to understand is that, in a certain sense, LyX doesn't know anything
5360 Indeed, from LyX's point of view, LaTeX is just one of several
5361 \begin_inset Quotes eld
5365 \begin_inset Quotes erd
5368 in which it is capable of producing output.
5369 Other such formats are DocBook, plaintext, and XHTML.
5370 LaTeX is, of course, a particularly important format, but very little of
5371 the information LyX has about LaTeX is actually contained in the program
5376 \begin_layout Plain Layout
5377 Some commands are sufficiently complex that they are
5378 \begin_inset Quotes eld
5382 \begin_inset Quotes erd
5386 But the developers generally regard this as a Bad Thing.
5391 Rather, that information, even for the standard classes like
5392 \begin_inset Flex Code
5395 \begin_layout Plain Layout
5401 , is contained in `layout files'.
5402 Similarly, LyX itself does not know much about DocBook or XHTML.
5403 What it knows is contained in layout files.
5406 \begin_layout Standard
5407 You can think of the layout file for a given document class as a translation
5408 manual between LyX constructs---paragraphs with their corresponding styles,
5409 certain sorts of insets, etc---and the corresponding LaTeX, DocBook, or
5411 Almost everything LyX knows about
5412 \begin_inset Flex Code
5415 \begin_layout Plain Layout
5421 , for example, is contained in the file
5422 \begin_inset Flex Code
5425 \begin_layout Plain Layout
5431 and in various other files it includes.
5432 For this reason, anyone intending to write layout files should plan to
5433 study the existing files.
5434 A good place to start is with
5435 \begin_inset Flex Code
5438 \begin_layout Plain Layout
5444 , which is included in
5445 \begin_inset Flex Code
5448 \begin_layout Plain Layout
5455 \begin_inset Flex Code
5458 \begin_layout Plain Layout
5464 , and many of the other layout files for document classes.
5465 This file is where sections and the like are defined:
5466 \begin_inset Flex Code
5469 \begin_layout Plain Layout
5475 tells LyX how paragraphs that are marked with the Section, Subsection,
5476 etc, styles can be translated into corresponding LaTeX, DocBook, and XHTML
5479 \begin_inset Flex Code
5482 \begin_layout Plain Layout
5488 file basically just includes several of these
5489 \begin_inset Flex Code
5492 \begin_layout Plain Layout
5501 \begin_layout Standard
5502 Defining the LyX--LaTeX correspondence is not the only thing layout files
5504 Their other job is to define how the LyX constructs themselves will appear
5506 The fact that layout files have these two jobs is often a source of confusion,
5507 because they are completely separate.
5508 Telling LyX how to translate a certain paragraph style into LaTeX does
5509 not tell LyX how to display it; conversely, telling LyX how to display
5510 a certain paragraph style does not tell LyX how to translate it into LaTeX
5511 (let alone tell LaTeX how to display it).
5512 So, in general, when you define a new LyX construct, you must always do
5513 two quite separate things: (i)
5514 \begin_inset space ~
5517 tell LyX how to translate it into LaTeX and (ii)
5518 \begin_inset space ~
5521 tell LyX how to display it.
5524 \begin_layout Standard
5525 Much the same is true, of course, as regards LyX's other backend formats,
5526 though XHTML is in some ways different, because in that case LyX
5530 able, to some extent, to use information about how it should display a
5531 paragraph on the screen to output information (in the form of CSS) about
5532 how the paragraph should be displayed in a browser.
5533 Even in this case, however, the distinction between what LyX does internally
5534 and how things are rendered externally remains in force, and the two can
5535 be controlled separately.
5537 \begin_inset CommandInset ref
5539 reference "sec:Tags-for-XHTML"
5546 \begin_layout Section
5547 Installing new LaTeX files
5550 \begin_layout Standard
5551 Some installations may not include a LaTeX package or class file that you
5552 would like to use within LyX.
5553 For example, you might need FoilTeX, a package for preparing slides for
5554 overhead projectors.
5555 Modern LaTeX distributions like TeXLive (2008 or newer) or MiKTeX provide
5556 a user interface for installing such packages.
5557 For example, with MiKTeX, you start the program
5558 \begin_inset Quotes eld
5562 \begin_inset space ~
5566 \begin_inset Quotes erd
5569 to get a list of available packages.
5570 To install one of them, right click on it or use the corresponding toolbar
5574 \begin_layout Standard
5575 If your LaTeX distribution does not provide such a `package manager', or
5576 if the package is not available from your distribution, then follow these
5577 steps to install it manually:
5580 \begin_layout Enumerate
5581 Get the package from
5582 \begin_inset CommandInset href
5585 target "http://www.ctan.org/"
5592 \begin_layout Enumerate
5593 If the package contains a file with the ending
5594 \begin_inset Quotes eld
5598 \begin_inset Flex Code
5601 \begin_layout Plain Layout
5608 \begin_inset Quotes erd
5611 (is the case for FoilTeX) then open a console, change to the folder of
5612 this file and execute the command
5613 \begin_inset Flex Code
5616 \begin_layout Plain Layout
5623 You have now unpacked the package and have all files to install it.
5624 Most LaTeX-packages are not packed and you can skip this step.
5627 \begin_layout Enumerate
5628 Now you need to decide if the package should be available for all users
5633 \begin_layout Enumerate
5634 On *nix systems (Linux, OSX, etc.), if you want the new package to be available
5635 for all users on your system, then install it in your `local' TeX tree,
5636 otherwise install it in your own `user' TeX tree.
5637 Where these trees should be created, if they do not already exist, depends
5639 To find this out, look in the file
5640 \begin_inset Flex Code
5643 \begin_layout Plain Layout
5653 \begin_layout Plain Layout
5654 This is usually in the directory
5655 \begin_inset Flex Code
5658 \begin_layout Plain Layout
5664 , though you can execute the command
5665 \begin_inset Flex Code
5668 \begin_layout Plain Layout
5679 The location of the `local' TeX tree is defined by the
5680 \begin_inset Flex Code
5683 \begin_layout Plain Layout
5689 variable; this is usually somewhere like
5690 \begin_inset Flex Code
5693 \begin_layout Plain Layout
5694 /usr/local/share/texmf
5700 The location of the `user' TeX tree is defined by
5701 \begin_inset Flex Code
5704 \begin_layout Plain Layout
5711 \begin_inset Flex Code
5714 \begin_layout Plain Layout
5721 (If these variables are not predefined, you have to define them.) You'll
5722 probably need root permissions to create or modify the `local' tree, but
5723 not for your `user' tree.
5724 \begin_inset Newline newline
5727 In general, it is recommended to install in the user tree because your user
5728 will not be modified or even overwritten when you upgrade your system.
5729 It will typically also be backed up together with everything else when
5730 you backup your home directory (which, of course, you do on a regular basis).
5733 \begin_layout Enumerate
5734 On Windows, if you want the new package to be available for all users on
5735 your system, change to the folder where LaTeX is installed and then change
5737 \begin_inset Flex Code
5740 \begin_layout Plain Layout
5751 (For MiKTeX, this would be by default the folder
5752 \begin_inset Flex Code
5755 \begin_layout Plain Layout
5773 \begin_layout Plain Layout
5774 Note that this will be the correct path only on English installations.
5775 On a German one, it would be
5776 \begin_inset Flex Code
5779 \begin_layout Plain Layout
5793 , and similarly for other languages.
5798 Create there a new folder
5799 \begin_inset Flex Code
5802 \begin_layout Plain Layout
5808 and copy all files of the package into it.
5810 \begin_inset Newline newline
5813 If the package should only available for you or you don't have admin permissions
5814 , do the same, but in the local LaTeX folder.
5816 \begin_inset space \thinspace{}
5820 \begin_inset space ~
5823 2.8 under Windows XP, this would be the folder:
5824 \begin_inset Newline newline
5830 \begin_inset Flex Code
5833 \begin_layout Plain Layout
5836 Documents and Settings
5848 \begin_inset Newline newline
5854 \begin_inset Phantom HPhantom
5857 \begin_layout Plain Layout
5868 \begin_inset Flex Code
5871 \begin_layout Plain Layout
5884 \begin_inset Newline newline
5887 On Vista, it would be:
5888 \begin_inset Newline newline
5892 \begin_inset Flex Code
5895 \begin_layout Plain Layout
5921 \begin_layout Enumerate
5922 Now one only need to tell LaTeX that there are new files.
5923 This depends on the used LaTeX-Distribution:
5927 \begin_layout Enumerate
5928 For TeXLive execute the command
5929 \begin_inset Flex Code
5932 \begin_layout Plain Layout
5939 If you installed the package for all users, then you will probably need
5940 to have root permissions for that.
5943 \begin_layout Enumerate
5944 For MiKTeX, if you have installed the package for all users, start the program
5946 \begin_inset Quotes eld
5950 \begin_inset space ~
5954 \begin_inset Quotes erd
5957 and press the button marked
5958 \begin_inset Quotes eld
5962 \begin_inset Quotes erd
5966 Otherwise start the program
5967 \begin_inset Quotes eld
5971 \begin_inset Quotes erd
5978 \begin_layout Enumerate
5979 Finally, you need to tell LyX that there are new packages available.
5980 So, in LyX, use the menu
5981 \begin_inset Flex MenuItem
5984 \begin_layout Plain Layout
5987 \SpecialChar \menuseparator
5993 and then restart LyX.
5996 \begin_layout Standard
5997 Now the package is installed.
5998 In our example, the document class
5999 \begin_inset Flex Code
6002 \begin_layout Plain Layout
6004 \begin_inset space ~
6011 \begin_layout Plain Layout
6023 will now be available under
6024 \begin_inset Flex MenuItem
6027 \begin_layout Plain Layout
6028 Document\SpecialChar \menuseparator
6029 Settings\SpecialChar \menuseparator
6039 \begin_layout Standard
6040 If you would like to use a LaTeX document class that is not even listed
6042 \begin_inset Flex MenuItem
6045 \begin_layout Plain Layout
6046 Document\SpecialChar \menuseparator
6047 Settings\SpecialChar \menuseparator
6053 , then you need to create a `layout' file for it.
6054 That is the topic of the next section.
6057 \begin_layout Section
6058 Types of layout files
6061 \begin_layout Standard
6062 This section describes the various sorts of LyX files that contain layout
6064 These files describe various paragraph and character styles, determining
6065 how LyX should display them and how they should be translated into LaTeX,
6066 DocBook, XHTML, or whatever output format is being used.
6070 \begin_layout Standard
6071 We shall try to provide a thorough description of the process of writing
6073 However, there are so many different types of documents supported even
6074 by just LaTeX that we can't hope to cover every different possibility or
6075 problem you might encounter.
6076 The LyX users' list is frequented by people with lots of experience with
6077 layout design who are willing to share what they've learned, so please
6078 feel free to ask questions there.
6081 \begin_layout Standard
6082 As you prepare to write a new layout, it is extremely helpful to look at
6083 the layouts distributed with LyX.
6084 If you write a LyX layout for a LaTeX document class that might also be
6085 used by others, or write a module that might be useful to others, then
6086 you should consider posting your layout to the
6087 \begin_inset CommandInset href
6089 name "layout section on the LyX wiki"
6090 target "http://wiki.lyx.org/Layouts/Layouts"
6094 or even to the LyX developers' list, so that it might be included in LyX
6099 \begin_layout Plain Layout
6100 Note that LyX is licensed under the General Public License, so any material
6101 that is contributed to LyX must be similarly licensed.
6109 \begin_layout Subsection
6111 \begin_inset CommandInset label
6113 name "sub:Layout-modules"
6120 \begin_layout Standard
6121 We have spoken to this point about `layout files'.
6122 But there are different sorts of files that contain layout information.
6123 Layout files, strictly so called, have the
6124 \begin_inset Flex Code
6127 \begin_layout Plain Layout
6133 extension and provide LyX with information about document classes.
6134 As of LyX 1.6, however, layout information can also be contained in layout
6140 \begin_inset Flex Code
6143 \begin_layout Plain Layout
6150 Modules are to LaTeX packages much as layouts are to LaTeX classes, and
6151 some modules—such as the
6152 \begin_inset Flex Code
6155 \begin_layout Plain Layout
6161 module—specifically provide support for one package.
6162 In a sense, layout modules are similar to included
6166 \begin_layout Plain Layout
6167 These can have any extension, but by convention have the
6168 \begin_inset Flex Code
6171 \begin_layout Plain Layout
6183 \begin_inset Flex Code
6186 \begin_layout Plain Layout
6192 —in that modules are not specific to a given document class but may be used
6193 with many different classes.
6194 The difference is that using an included file with
6195 \begin_inset Flex Code
6198 \begin_layout Plain Layout
6204 requires editing that file.
6205 Modules, by contrast, are selected in the
6206 \begin_inset Flex MenuItem
6209 \begin_layout Plain Layout
6210 Document\SpecialChar \menuseparator
6219 \begin_layout Standard
6220 Building modules is the easiest way to get started with layout editing,
6221 since it can be as simple as adding a single new paragraph style or flex
6223 But modules may, in principle, contain anything a layout file can contain.
6226 \begin_layout Standard
6227 After creating a new module and copying it to the
6228 \begin_inset Flex Code
6231 \begin_layout Plain Layout
6237 folder, you will need to reconfigure and then restart LyX for the module
6238 to appear in the menu.
6239 However, changes you make to the module will be seen immediately, if you
6241 \begin_inset Flex MenuItem
6244 \begin_layout Plain Layout
6245 Document\SpecialChar \menuseparator
6251 , highlight something, and then hit
6252 \begin_inset Quotes eld
6256 \begin_inset Quotes erd
6262 It is strongly recommended that you save your work before doing this
6267 it is strongly recommended that you not attempt to edit modules while simultaneo
6268 usly working on actual documents
6271 Though of course the developers strive to keep LyX stable in such situations,
6272 syntax errors and the like in your module file could cause strange behavior.
6275 \begin_layout Subsubsection
6279 \begin_layout Standard
6280 Modules are to LyX as packages are to LaTeX.
6281 Sometimes, however, you find yourself wanting a specific inset or character
6282 style just for one document and writing a module that will also be available
6283 to other documents makes little sense.
6284 What you need is LyX's
6285 \begin_inset Quotes eld
6289 \begin_inset Quotes erd
6295 \begin_layout Standard
6296 You will find it under
6298 Document\SpecialChar \menuseparator
6299 Settings\SpecialChar \menuseparator
6303 The large text box allows you to enter anything that you might enter in
6304 a layout file or module.
6305 You can think of a document's local layout, in fact, as a module that belongs
6307 So, in particular, you must enter a
6308 \begin_inset Flex Code
6311 \begin_layout Plain Layout
6318 Any format is acceptable, but one would normally use the format current
6320 (In LyX 2.0, the current layout format is 35.) You should be aware that local
6321 layout is not supported by versions of LyX prior to 1.6, so you should not
6322 use it if you want to be able to export your document to LyX 1.5 or earlier
6323 (without, that is, losing the local layout information).
6324 If you wish to be able to export to 1.6---local layout is supported in 1.6,
6325 though there is no UI for it---then you should use format 11 and, of course,
6326 use only layout constructs that were available in LyX 1.6.
6329 \begin_layout Standard
6330 When you have entered something in the
6331 \begin_inset Flex Code
6334 \begin_layout Plain Layout
6340 pane, LyX will enable the
6341 \begin_inset Quotes eld
6345 \begin_inset Quotes erd
6348 button at the bottom.
6349 Clicking this button will cause LyX to determine whether what you have
6350 entered is valid layout information for the chosen format.
6351 LyX will report the result but, unfortunately, will not tell you what errors
6352 there might have been.
6353 These will be written to the terminal, however, if LyX is started from
6355 You will not be permitted to save your local layout until you have entered
6359 \begin_layout Standard
6360 The warnings at the end of the previous section apply here, too.
6361 Do not play with local layout while you are actually working, especially
6362 if you have not saved your document.
6363 That said, using local layout with a test document can be a very convenient
6364 way to try out layout ideas, or even to start developing a module.
6367 \begin_layout Subsection
6369 \begin_inset Flex MenuItem
6372 \begin_layout Plain Layout
6381 \begin_layout Standard
6382 There are two situations you are likely to encounter when wanting to support
6383 a new LaTeX document class, involving style (
6384 \begin_inset Flex Code
6387 \begin_layout Plain Layout
6393 ) files and LaTeX2e class (
6394 \begin_inset Flex Code
6397 \begin_layout Plain Layout
6404 Supporting a style file is usually fairly easy.
6405 Supporting a new class file is a bit harder.
6406 We'll discuss the former in this section and the latter in the next.
6407 Similar remarks apply, of course, if you want to support a new DocBook
6411 \begin_layout Standard
6412 The easier case is the one in which your new document class is provided
6413 as a style file that is to be used in conjunction with an already supported
6415 For the sake of the example, we'll assume that the style file is called
6417 \begin_inset Flex MenuItem
6420 \begin_layout Plain Layout
6426 and that it is meant to be used with
6427 \begin_inset Flex MenuItem
6430 \begin_layout Plain Layout
6436 , which is a standard class.
6440 \begin_layout Standard
6441 Start by copying the existing class's layout file into your local directory:
6445 \begin_layout Plain Layout
6446 Of course, which directory is your local directory will vary by platform,
6447 and LyX allows you to specify your local directory on startup, too, using
6449 \begin_inset Flex Code
6452 \begin_layout Plain Layout
6466 \begin_layout LyX-Code
6467 cp report.layout ~/.lyx/layouts/myclass.layout
6470 \begin_layout Standard
6472 \begin_inset Flex Code
6475 \begin_layout Plain Layout
6481 and change the line:
6484 \begin_layout LyX-Code
6487 DeclareLaTeXClass{report}
6490 \begin_layout Standard
6494 \begin_layout LyX-Code
6497 DeclareLaTeXClass[report, myclass.sty]{report (myclass)}
6500 \begin_layout Standard
6504 \begin_layout LyX-Code
6506 \begin_inset Newline newline
6512 \begin_inset Newline newline
6518 \begin_layout Standard
6519 near the top of the file.
6522 \begin_layout Standard
6523 Start LyX and select
6524 \begin_inset Flex MenuItem
6527 \begin_layout Plain Layout
6528 Tools\SpecialChar \menuseparator
6535 Then restart LyX and try creating a new document.
6537 \begin_inset Flex MenuItem
6540 \begin_layout Plain Layout
6546 " as a document class option in the
6547 \begin_inset Flex MenuItem
6550 \begin_layout Plain Layout
6551 Document\SpecialChar \menuseparator
6558 It is likely that some of the sectioning commands and such in your new
6559 class will work differently from how they worked in the base class—
6560 \begin_inset Flex Code
6563 \begin_layout Plain Layout
6569 in this example—so you can fiddle around with the settings for the different
6570 sections if you wish.
6571 The layout information for sections is contained in
6572 \begin_inset Flex Code
6575 \begin_layout Plain Layout
6581 , but you do not need to copy and change this file.
6582 Instead, you can simply add your changes to your layout file, after the
6584 \begin_inset Flex Code
6587 \begin_layout Plain Layout
6593 , which itself includes
6594 \begin_inset Flex Code
6597 \begin_layout Plain Layout
6604 For example, you might add these lines:
6607 \begin_layout LyX-Code
6611 \begin_layout LyX-Code
6615 \begin_layout LyX-Code
6619 \begin_layout LyX-Code
6623 \begin_layout LyX-Code
6627 \begin_layout Standard
6628 to change the font for chapter headings to sans-serif.
6629 This will override (or, in this case, add to) the existing declaration
6630 for the Chapter style.
6634 \begin_layout Standard
6635 Your new package may also provide commands or environments not present in
6637 In this case, you will want to add these to the layout file.
6639 \begin_inset CommandInset ref
6641 reference "sec:TextClass"
6645 for information on how to do so.
6648 \begin_layout Standard
6650 \begin_inset Flex MenuItem
6653 \begin_layout Plain Layout
6659 can be used with several different document classes, and even if it cannot,
6660 you might find it easiest just to write a module that you can load with
6662 The simplest possible such module would be:
6665 \begin_layout LyX-Code
6668 DeclareLyXModule{My Package}
6671 \begin_layout LyX-Code
6675 \begin_layout LyX-Code
6676 #Support for mypkg.sty.
6679 \begin_layout LyX-Code
6681 \begin_inset Newline newline
6687 \begin_layout LyX-Code
6689 \begin_inset Newline newline
6695 \begin_layout LyX-Code
6697 \begin_inset Newline newline
6703 \begin_inset Newline newline
6709 \begin_layout Standard
6710 A more complex module might modify the behavior of some existing constructs
6711 or define some new ones.
6713 \begin_inset CommandInset ref
6715 reference "sec:TextClass"
6722 \begin_layout Subsection
6724 \begin_inset Flex MenuItem
6727 \begin_layout Plain Layout
6736 \begin_layout Standard
6737 There are two possibilities here.
6738 One is that the class file is itself based upon an existing document class.
6739 For example, many thesis classes are based upon
6740 \begin_inset Flex MenuItem
6743 \begin_layout Plain Layout
6750 To see whether yours is, look for a line like
6753 \begin_layout LyX-Code
6759 \begin_layout Standard
6761 If so, then you may proceed largely as in the previous section, though
6763 \begin_inset Flex Code
6766 \begin_layout Plain Layout
6772 line will be different.
6773 If your new class is
6774 \begin_inset Flex Code
6777 \begin_layout Plain Layout
6783 and it is based upon
6784 \begin_inset Flex Code
6787 \begin_layout Plain Layout
6793 , then the line should read:
6797 \begin_layout Plain Layout
6798 And it will be easiest if you save the file to
6799 \begin_inset Flex Code
6802 \begin_layout Plain Layout
6808 : LyX assumes that the document class has the same name as the layout file.
6817 \begin_layout LyX-Code
6820 DeclareLaTeXClass[thesis,book]{thesis}
6823 \begin_layout Standard
6824 If, on the other hand, the new class is not based upon an existing class,
6825 you will probably have to
6826 \begin_inset Quotes eld
6830 \begin_inset Quotes erd
6834 We strongly suggest copying an existing layout file which uses a similar
6835 LaTeX class and then modifying it, if you can do so.
6836 At least use an existing file as a starting point so you can find out what
6837 items you need to worry about.
6838 Again, the specifics are covered below.
6841 \begin_layout Subsection
6843 \begin_inset CommandInset label
6845 name "sub:Creating-Templates"
6852 \begin_layout Standard
6853 Once you have written a layout file for a new document class, you might
6854 want to consider writing a
6859 A template acts as a kind of tutorial for your layout, showing how it might
6860 be used, though containing dummy content.
6861 You can of course look at the various templates included with LyX for ideas.
6864 \begin_layout Standard
6865 Templates are created just like usual documents: using LyX.
6866 The only difference is that usual documents contain all possible settings,
6867 including the font scheme and the paper size.
6868 Usually a user doesn't want a template to overwrite his preferred settings
6869 for such parameters.
6870 For that reason, the designer of a template should remove the corresponding
6872 \begin_inset Flex Code
6875 \begin_layout Plain Layout
6884 \begin_inset Flex Code
6887 \begin_layout Plain Layout
6895 from the template LyX file.
6896 This can be done with any simple text-editor, for example
6897 \begin_inset Flex Code
6900 \begin_layout Plain Layout
6907 \begin_inset Flex Code
6910 \begin_layout Plain Layout
6920 \begin_layout Standard
6921 Put the edited template files you create in
6922 \begin_inset Flex Code
6925 \begin_layout Plain Layout
6931 , copy the ones you use from the global template directory in
6932 \begin_inset Flex Code
6935 \begin_layout Plain Layout
6941 to the same place, and redefine the template path in the
6942 \begin_inset Flex MenuItem
6945 \begin_layout Plain Layout
6946 Tools\SpecialChar \menuseparator
6947 Preferences\SpecialChar \menuseparator
6956 \begin_layout Standard
6957 Note, by the way, that there is a template which has a particular meaning:
6959 \begin_inset Flex Code
6962 \begin_layout Plain Layout
6969 This template is loaded every time you create a new document with
6970 \begin_inset Flex MenuItem
6973 \begin_layout Plain Layout
6974 File\SpecialChar \menuseparator
6980 in order to provide useful defaults.
6981 To create this template from inside LyX, all you have to do is to open
6982 a document with the correct settings, and use the
6983 \begin_inset Flex MenuItem
6986 \begin_layout Plain Layout
6987 Save as Document Defaults
6995 \begin_layout Subsection
6996 Upgrading old layout files
6999 \begin_layout Standard
7000 The format of layout files changes with each LyX release, so old layout
7001 files need to be converted to the new format.
7002 This process has been automated since LyX 1.4: If LyX reads a layout file
7003 in an older format, it automatically calls the script
7004 \begin_inset Flex Code
7007 \begin_layout Plain Layout
7013 to convert it to a temporary file in current format.
7014 The original file is left untouched.
7015 If you use the layout file often, then, you may want to convert it permanently,
7016 so that LyX does not have to do so itself every time.
7017 To do this, you can call the converter manually:
7020 \begin_layout LyX-Code
7021 mv myclass.layout myclass.old
7024 \begin_layout LyX-Code
7025 python LyXDir/scripts/layout2layout.py myclass.old myclass.layout
7028 \begin_layout Standard
7030 \begin_inset Flex Code
7033 \begin_layout Plain Layout
7039 with the name of your LyX system directory, of course.
7042 \begin_layout Standard
7043 Note that manual conversion does not affect included files, so these will
7044 have to be converted separately.
7047 \begin_layout Section
7048 \begin_inset CommandInset label
7050 name "sec:TextClass"
7054 The layout file format
7057 \begin_layout Standard
7058 When it's finally time to get your hands dirty and create or edit your own
7059 layout file, the following sections describe what you're up against.
7060 Our advice is to go slowly, save and test often, listen to soothing music,
7061 and enjoy one or two of your favorite adult beverages; more if you are
7062 getting particularly stuck.
7063 It's really not that hard, except that the multitude of options can become
7064 overwhelming if you try to do too much in one sitting.
7065 Go have another adult beverage, just for good measure.
7068 \begin_layout Standard
7069 Note that all the tags used in layout files are case-insensitive.
7071 \begin_inset Flex Code
7074 \begin_layout Plain Layout
7081 \begin_inset Flex Code
7084 \begin_layout Plain Layout
7091 \begin_inset Flex Code
7094 \begin_layout Plain Layout
7100 are really the same tag.
7101 The possible values are printed in brackets after the feature's name.
7102 The default value if a feature isn't specified inside a text class-description
7104 \begin_inset Flex Code
7107 \begin_layout Plain Layout
7116 If the argument has a data type like
7117 \begin_inset Quotes eld
7121 \begin_inset Quotes erd
7125 \begin_inset Quotes eld
7129 \begin_inset Quotes erd
7132 , the default is shown like this:
7133 \begin_inset Flex Code
7136 \begin_layout Plain Layout
7147 \begin_layout Subsection
7148 The document class declaration
7151 \begin_layout Standard
7152 Lines in a layout file which begin with
7153 \begin_inset Flex Code
7156 \begin_layout Plain Layout
7163 There is one exception to this rule.
7165 \begin_inset Flex Code
7168 \begin_layout Plain Layout
7174 files should begin with a line like:
7177 \begin_layout LyX-Code
7180 #% Do not delete the line below; configure depends on this
7183 \begin_layout LyX-Code
7188 DeclareLaTeXClass{article}
7191 \begin_layout Standard
7192 The second line is used when you (re)configure LyX.
7193 The layout file is read by the LaTeX script
7194 \begin_inset Flex Code
7197 \begin_layout Plain Layout
7203 , in a special mode where
7204 \begin_inset Flex Code
7207 \begin_layout Plain Layout
7214 The first line is just a LaTeX comment, and the second one contains the
7215 declaration of the text class.
7216 If these lines appear in a file named
7217 \begin_inset Flex Code
7220 \begin_layout Plain Layout
7226 , then they define a text class of name
7227 \begin_inset Flex Code
7230 \begin_layout Plain Layout
7236 (the name of the layout file) which uses the LaTeX document class
7237 \begin_inset Flex Code
7240 \begin_layout Plain Layout
7246 (the default is to use the same name as the layout).
7248 \begin_inset Quotes eld
7252 \begin_inset Quotes erd
7255 that appears above is used as a description of the text class in the
7256 \begin_inset Flex MenuItem
7259 \begin_layout Plain Layout
7260 Document\SpecialChar \menuseparator
7269 \begin_layout Standard
7270 Let's assume that you wrote your own text class that uses the
7271 \begin_inset Flex Code
7274 \begin_layout Plain Layout
7280 document class, but where you changed the appearance of the section headings.
7281 If you put it in a file
7282 \begin_inset Flex Code
7285 \begin_layout Plain Layout
7291 , the header of this file should be:
7294 \begin_layout LyX-Code
7297 #% Do not delete the line below; configure depends on this
7300 \begin_layout LyX-Code
7305 DeclareLaTeXClass[article]{article (with my own headings)}
7308 \begin_layout Standard
7309 This declares a text class
7310 \begin_inset Flex Code
7313 \begin_layout Plain Layout
7319 , associated with the LaTeX document class
7320 \begin_inset Flex Code
7323 \begin_layout Plain Layout
7330 \begin_inset Quotes eld
7333 article (with my own headings)
7334 \begin_inset Quotes erd
7338 If your text class depends on several packages, you can declare it as:
7341 \begin_layout LyX-Code
7344 #% Do not delete the line below; configure depends on this
7347 \begin_layout LyX-Code
7352 DeclareLaTeXClass[article,foo.sty]{article (with my own headings)}
7355 \begin_layout Standard
7356 This indicates that your text class uses the
7357 \begin_inset Flex Code
7360 \begin_layout Plain Layout
7367 Finally, it is also possible to declare classes for DocBook code.
7368 Typical declarations will look like:
7371 \begin_layout LyX-Code
7374 #% Do not delete the line below; configure depends on this
7377 \begin_layout LyX-Code
7382 DeclareDocBookClass[article]{SGML (DocBook article)}
7385 \begin_layout Standard
7386 Note that these declarations can also be given an optional parameter declaring
7387 the name of the document class (but not a list).
7390 \begin_layout Standard
7391 So, to be as explicit as possible, the form of the layout declaration is:
7394 \begin_layout LyX-Code
7399 DeclareLaTeXClass[class,package.sty]{layout description}
7402 \begin_layout Standard
7403 The class need only be specified if the name of the LaTeX class file and
7404 the name of the layout file are different or if there are packages to load.
7405 If the name of the class file is not specified, then LyX will simply assume
7406 that it is the same as the name of the layout file.
7409 \begin_layout Standard
7410 When the text class has been modified to your taste, all you have to do
7411 is to copy it either to
7412 \begin_inset Flex Code
7415 \begin_layout Plain Layout
7422 \begin_inset Flex Code
7425 \begin_layout Plain Layout
7432 \begin_inset Flex MenuItem
7435 \begin_layout Plain Layout
7436 Tools\SpecialChar \menuseparator
7442 , exit LyX and restart.
7443 Then your new text class should be available along with the others.
7446 \begin_layout Standard
7447 Once the layout file is installed, you can edit it and see your changes
7448 without having to reconfigure or to restart LyX.
7453 \begin_layout Plain Layout
7454 In versions of LyX prior to 1.6, this was not true.
7455 As a result, editing layout files was very time consuming, since you had
7456 constantly to restart LyX to see changes.
7461 You can force a reload of the current layout by using the LyX function
7463 \begin_inset Flex MenuItem
7466 \begin_layout Plain Layout
7473 There is no default binding for this function—though, of course, you can
7474 bind it to a key yourself.
7475 But you will normally use this function simply by entering it in the mini-buffe
7480 \begin_layout Standard
7486 \begin_inset Flex MenuItem
7489 \begin_layout Plain Layout
7495 is very much an `advanced feature'.
7500 recommended that you save your work before using this function.
7505 recommended that you not attempt to edit layout information while simultaneousl
7506 y working on a document that you care about.
7507 Use a test document.
7508 Syntax errors and the like in your layout file could cause peculiar behavior.
7509 In particular, such errors could cause LyX to regard the current layout
7510 as invalid and to attempt to switch to some other layout.
7514 \begin_layout Plain Layout
7515 Really bad syntax errors may even caused LyX to exit.
7516 This is because certain sorts of errors may make LyX unable to read
7526 The LyX team strives to keep LyX stable in such situations, but safe is
7531 \begin_layout Plain Layout
7532 While we're giving advice: make regular backups.
7533 And be nice to your mother.
7541 \begin_layout Subsection
7542 The Module declaration
7545 \begin_layout Standard
7546 A module must begin with a line like the following:
7549 \begin_layout LyX-Code
7552 DeclareLyXModule[endnotes.sty]{Endnotes}
7555 \begin_layout Standard
7556 The mandatory argument, in curly brackets, is the name of the module, as
7558 \begin_inset Flex MenuItem
7561 \begin_layout Plain Layout
7562 Document\SpecialChar \menuseparator
7563 Settings\SpecialChar \menuseparator
7570 The argument in square brackets is optional: It declares any LaTeX packages
7571 on which the module depends.
7572 Please note that only packages about which LyX knows should be listed in
7573 the square brackets.
7577 \begin_layout Plain Layout
7578 The list of such packages is documented only in the source code.
7583 LyX will not check for arbitrary packages.
7584 It is also possible to use the form
7585 \begin_inset Flex MenuItem
7588 \begin_layout Plain Layout
7594 as an optional argument, which declares that the module can only be used
7595 when there exists a conversion chain between the formats `
7596 \begin_inset Flex Code
7599 \begin_layout Plain Layout
7606 \begin_inset Flex Code
7609 \begin_layout Plain Layout
7618 \begin_layout Standard
7619 The module declaration should then be followed by lines like the following
7623 \begin_layout Plain Layout
7624 Preferably in English if the module should be published with LyX.
7625 This description will appear in the list of messages to be translated and
7626 will be thus translated with the next interface update.
7634 \begin_layout LyX-Code
7638 \begin_layout LyX-Code
7639 #Adds an endnote command, in addition to footnotes.
7643 \begin_layout LyX-Code
7644 #You will need to add
7646 theendnotes in TeX code where you
7649 \begin_layout LyX-Code
7650 #want the endnotes to appear.
7654 \begin_layout LyX-Code
7658 \begin_layout LyX-Code
7659 #Requires: somemodule | othermodule
7662 \begin_layout LyX-Code
7663 #Excludes: badmodule
7666 \begin_layout Standard
7667 The description is used in
7668 \begin_inset Flex MenuItem
7671 \begin_layout Plain Layout
7672 Document\SpecialChar \menuseparator
7673 Settings\SpecialChar \menuseparator
7679 to provide the user with information about what the module does.
7681 \begin_inset Flex Code
7684 \begin_layout Plain Layout
7690 line is used to identify other modules with which this one must be used;
7692 \begin_inset Flex Code
7695 \begin_layout Plain Layout
7701 line is used to identify modules with which this one may not be used.
7702 Both are optional, and, as shown, multiple modules should be separated
7703 with the pipe symbol: |.
7704 Note that the required modules are treated disjunctively:
7708 of the required modules must be used.
7713 excluded module may be used.
7714 Note that modules are identified here by their
7719 \begin_inset Flex Code
7722 \begin_layout Plain Layout
7730 \begin_inset Flex Code
7733 \begin_layout Plain Layout
7740 \begin_inset Flex Code
7743 \begin_layout Plain Layout
7752 \begin_layout Subsection
7756 \begin_layout Standard
7757 The first non-comment line of any layout file, included file, or module
7762 contain the file format number:
7765 \begin_layout Description
7766 \begin_inset Flex Code
7769 \begin_layout Plain Layout
7776 \begin_inset Flex Code
7779 \begin_layout Plain Layout
7785 ] The format of the layout file.
7788 \begin_layout Standard
7789 This tag was introduced with LyX 1.4.0.
7790 Layout files from LyX 1.3.x and earlier don't have an explicit file format
7791 and are considered to be of format 1.
7792 The format for the present version of LyX is format 21.
7793 But each version of LyX is capable of reading earlier versions' layout
7794 files, just as they are capable of reading files produced by earlier versions
7796 There is, however, no provision for converting to earlier formats.
7797 So LyX 1.6.x will not read layout files in format 21 but only files in format
7801 \begin_layout Subsection
7802 \begin_inset CommandInset label
7804 name "sub:General-text-class"
7808 General text class parameters
7811 \begin_layout Standard
7812 These are general parameters that govern the behavior of an entire document
7818 mean that they must appear in
7819 \begin_inset Flex Code
7822 \begin_layout Plain Layout
7828 files rather than in modules.
7829 A module can contain any layout tag.)
7832 \begin_layout Description
7833 \begin_inset Flex Code
7836 \begin_layout Plain Layout
7842 Adds information that will be output in the
7843 \begin_inset Flex Code
7846 \begin_layout Plain Layout
7852 block when this document class is output to XHTML.
7853 Typically, this would be used to output CSS style information, but it can
7854 be used for anything that can appear in
7855 \begin_inset Flex Code
7858 \begin_layout Plain Layout
7866 \begin_inset Quotes eld
7870 \begin_inset Flex Code
7873 \begin_layout Plain Layout
7880 \begin_inset Quotes erd
7886 \begin_layout Description
7887 \begin_inset Flex Code
7890 \begin_layout Plain Layout
7896 Adds CSS styling information.
7897 This will either be output in a
7898 \begin_inset Quotes eld
7902 \begin_inset Flex Code
7905 \begin_layout Plain Layout
7912 \begin_inset Quotes erd
7915 block or, if the user has so chosen, to a separate CSS file.Must end with
7917 \begin_inset Quotes eld
7921 \begin_inset Flex Code
7924 \begin_layout Plain Layout
7931 \begin_inset Quotes erd
7937 \begin_layout Description
7938 \begin_inset Flex Code
7941 \begin_layout Plain Layout
7947 Adds information to the document preamble.
7949 \begin_inset Quotes eld
7953 \begin_inset Flex Code
7956 \begin_layout Plain Layout
7963 \begin_inset Quotes erd
7969 \begin_layout Description
7970 \begin_inset Flex Code
7973 \begin_layout Plain Layout
7979 Defines formats for use in the display of bibliographic information.
7981 \begin_inset CommandInset ref
7983 reference "sub:Citation-format-description"
7989 \begin_inset Quotes eld
7993 \begin_inset Flex Code
7996 \begin_layout Plain Layout
8003 \begin_inset Quotes erd
8009 \begin_layout Description
8010 \begin_inset Flex Code
8013 \begin_layout Plain Layout
8019 Describes various global options supported by the document class.
8021 \begin_inset space ~
8025 \begin_inset CommandInset ref
8027 reference "sub:ClassOptions"
8033 \begin_inset Quotes eld
8037 \begin_inset Flex Code
8040 \begin_layout Plain Layout
8047 \begin_inset Quotes erd
8053 \begin_layout Description
8054 \begin_inset Flex Code
8057 \begin_layout Plain Layout
8064 \begin_inset Flex Code
8067 \begin_layout Plain Layout
8076 \begin_inset Flex Code
8079 \begin_layout Plain Layout
8085 ] Whether the class should
8089 to having one or two columns.
8090 Can be changed in the
8091 \begin_inset Flex MenuItem
8094 \begin_layout Plain Layout
8095 Document\SpecialChar \menuseparator
8104 \begin_layout Description
8105 \begin_inset Flex Code
8108 \begin_layout Plain Layout
8115 \begin_inset Flex Code
8118 \begin_layout Plain Layout
8124 ] This sequence defines the properties for a counter.
8125 If the counter does not yet exist, it is created; if it does exist, it
8128 \begin_inset Quotes eld
8132 \begin_inset Flex Code
8135 \begin_layout Plain Layout
8142 \begin_inset Quotes erd
8146 \begin_inset Newline newline
8150 \begin_inset space ~
8154 \begin_inset CommandInset ref
8156 reference "sub:Counters"
8160 for details on counters.
8163 \begin_layout Description
8164 \begin_inset Flex Code
8167 \begin_layout Plain Layout
8173 Sets the default font used to display the document.
8175 \begin_inset space ~
8179 \begin_inset CommandInset ref
8181 reference "sub:Font-description"
8185 for how to declare fonts.
8187 \begin_inset Quotes eld
8191 \begin_inset Flex Code
8194 \begin_layout Plain Layout
8201 \begin_inset Quotes erd
8207 \begin_layout Description
8208 \begin_inset Flex Code
8211 \begin_layout Plain Layout
8218 \begin_inset Flex Code
8221 \begin_layout Plain Layout
8227 Specifies a module to be included by default with this document class.
8228 The module should be specified by filename without the
8229 \begin_inset Flex Code
8232 \begin_layout Plain Layout
8239 The user can still remove the module, but it will be active at the outset.
8240 (This applies only when new files are created, or when this class is chosen
8241 for an existing document.)
8244 \begin_layout Description
8245 \begin_inset Flex Code
8248 \begin_layout Plain Layout
8255 \begin_inset Flex Code
8258 \begin_layout Plain Layout
8264 ] This is the style that will be assigned to new paragraphs, usually
8265 \begin_inset Flex MenuItem
8268 \begin_layout Plain Layout
8275 This will default to the first defined style if not given, but you are
8276 encouraged to use this directive.
8279 \begin_layout Description
8280 \begin_inset Flex Code
8283 \begin_layout Plain Layout
8290 \begin_inset Flex Code
8293 \begin_layout Plain Layout
8299 ] This tag indicates that the module in question—which should be specified
8300 by filename without the
8301 \begin_inset Flex Code
8304 \begin_layout Plain Layout
8310 extension—cannot be used with this document class.
8311 This might be used in a journal-specific layout file to prevent, say, the
8313 \begin_inset Flex Code
8316 \begin_layout Plain Layout
8322 module that numbers theorems by section.
8327 be used in a module.
8328 Modules have their own way of excluding other modules (see
8329 \begin_inset CommandInset ref
8331 reference "sub:Layout-modules"
8338 \begin_layout Description
8339 \begin_inset Flex Code
8342 \begin_layout Plain Layout
8348 Defines a new float.
8350 \begin_inset space ~
8354 \begin_inset CommandInset ref
8356 reference "sub:Floats"
8362 \begin_inset Quotes eld
8366 \begin_inset Flex Code
8369 \begin_layout Plain Layout
8376 \begin_inset Quotes erd
8382 \begin_layout Description
8383 \begin_inset Flex Code
8386 \begin_layout Plain Layout
8392 Sets the information that will be output in the
8393 \begin_inset Flex Code
8396 \begin_layout Plain Layout
8402 block when this document class is output to XHTML.
8403 Note that this will completely override any prior
8404 \begin_inset Flex Code
8407 \begin_layout Plain Layout
8414 \begin_inset Flex Code
8417 \begin_layout Plain Layout
8425 \begin_inset Flex Code
8428 \begin_layout Plain Layout
8434 if you just want to add material to the preamble.) Must end with
8435 \begin_inset Quotes eld
8439 \begin_inset Flex Code
8442 \begin_layout Plain Layout
8449 \begin_inset Quotes erd
8455 \begin_layout Description
8456 \begin_inset Flex Code
8459 \begin_layout Plain Layout
8465 Sets CSS styling information.
8466 This will either be output in a
8467 \begin_inset Quotes eld
8471 \begin_inset Flex Code
8474 \begin_layout Plain Layout
8481 \begin_inset Quotes erd
8484 block or, if the user has so chosen, to a separate CSS file.
8485 Note that this will completely override any prior
8486 \begin_inset Flex Code
8489 \begin_layout Plain Layout
8496 \begin_inset Flex Code
8499 \begin_layout Plain Layout
8507 \begin_inset Flex Code
8510 \begin_layout Plain Layout
8516 if you just want to add material.) Must end with
8517 \begin_inset Quotes eld
8521 \begin_inset Flex Code
8524 \begin_layout Plain Layout
8531 \begin_inset Quotes erd
8537 \begin_layout Description
8538 \begin_inset Flex Code
8541 \begin_layout Plain Layout
8548 \begin_inset Flex Code
8551 \begin_layout Plain Layout
8557 ] The layout to use for the table of contents, bibliography, and so forth,
8558 when the document is output to HTML.
8559 For articles, this should normally be Section; for books, Chapter.
8560 If it is not given, then LyX will attempt to figure out which layout to
8564 \begin_layout Description
8565 \begin_inset Flex Code
8568 \begin_layout Plain Layout
8575 \begin_inset Flex Code
8578 \begin_layout Plain Layout
8584 ] Modifies the properties of the given counter.
8585 If the counter does not exist, the section is ignored.
8587 \begin_inset Quotes eld
8591 \begin_inset Flex Code
8594 \begin_layout Plain Layout
8601 \begin_inset Quotes erd
8605 \begin_inset Newline newline
8609 \begin_inset space ~
8613 \begin_inset CommandInset ref
8615 reference "sub:Counters"
8619 for details on counters.
8622 \begin_layout Description
8623 \begin_inset Flex Code
8626 \begin_layout Plain Layout
8633 \begin_inset Flex Code
8636 \begin_layout Plain Layout
8642 ] Modifies the properties of the given paragraph style.
8643 If the style does not exist, the section is ignored.
8645 \begin_inset Quotes eld
8649 \begin_inset Flex Code
8652 \begin_layout Plain Layout
8659 \begin_inset Quotes erd
8665 \begin_layout Description
8666 \begin_inset Flex Code
8669 \begin_layout Plain Layout
8675 As its name implies, this command allows you to include another layout
8676 definition file within yours to avoid duplicating commands.
8677 Common examples are the standard layout files, for example,
8678 \begin_inset Flex Code
8681 \begin_layout Plain Layout
8687 , which contains most of the basic layouts.
8690 \begin_layout Description
8691 \begin_inset Flex Code
8694 \begin_layout Plain Layout
8700 This section (re-)defines the layout of an inset.
8701 It can be applied to an existing inset or to a new, user-defined inset,
8702 e.g., a new character style.
8704 \begin_inset Quotes eld
8708 \begin_inset Flex Code
8711 \begin_layout Plain Layout
8718 \begin_inset Quotes erd
8722 \begin_inset Newline newline
8726 \begin_inset space ~
8730 \begin_inset CommandInset ref
8732 reference "sub:Flex-insets-and"
8736 for more information.
8740 \begin_layout Description
8741 \begin_inset Flex Code
8744 \begin_layout Plain Layout
8751 \begin_inset Flex Code
8754 \begin_layout Plain Layout
8760 ] A string that indicates the width of the left margin on the screen, for
8762 \begin_inset Quotes eld
8766 \begin_inset Quotes erd
8770 (Note that this is not a `length', like
8771 \begin_inset Quotes eld
8775 \begin_inset Quotes erd
8781 \begin_layout Description
8782 \begin_inset Flex Code
8785 \begin_layout Plain Layout
8792 \begin_inset Flex Code
8795 \begin_layout Plain Layout
8801 ] This command deletes an existing counter, usually one defined in an included
8805 \begin_layout Description
8806 \begin_inset Flex Code
8809 \begin_layout Plain Layout
8815 This command deletes an existing float.
8816 This is particularly useful when you want to suppress a float that has
8817 been defined in an input file.
8820 \begin_layout Description
8821 \begin_inset Flex Code
8824 \begin_layout Plain Layout
8830 This command deletes an existing style.
8831 This is particularly useful when you want to suppress a style that has
8832 be defined in an input file.
8835 \begin_layout Description
8836 \begin_inset Flex Code
8839 \begin_layout Plain Layout
8845 A string indicating the file format (as defined in the Preferences dialog)
8846 produced by this class.
8847 It is mainly useful when
8848 \begin_inset Flex Code
8851 \begin_layout Plain Layout
8857 is `literate' and one wants to define a new type of literate document.
8858 This string is reset to `docbook', `latex', or `literate' when the correspondin
8860 \begin_inset Flex Code
8863 \begin_layout Plain Layout
8869 parameter is encountered.
8872 \begin_layout Description
8873 \begin_inset Flex Code
8876 \begin_layout Plain Layout
8882 A string indicating what sort of output documents using this class will
8884 At present, the options are: `docbook', `latex', and `literate'.
8887 \begin_layout Description
8888 \begin_inset Flex Code
8891 \begin_layout Plain Layout
8898 \begin_inset Flex Code
8901 \begin_layout Plain Layout
8910 \begin_inset Flex Code
8913 \begin_layout Plain Layout
8920 \begin_inset Flex Code
8923 \begin_layout Plain Layout
8929 ] The default pagestyle.
8930 Can be changed in the
8931 \begin_inset Flex MenuItem
8934 \begin_layout Plain Layout
8935 Document\SpecialChar \menuseparator
8944 \begin_layout Description
8945 \begin_inset Flex Code
8948 \begin_layout Plain Layout
8954 Sets the preamble for the LaTeX document.
8955 Note that this will completely override any prior
8956 \begin_inset Flex Code
8959 \begin_layout Plain Layout
8966 \begin_inset Flex Code
8969 \begin_layout Plain Layout
8977 \begin_inset Flex Code
8980 \begin_layout Plain Layout
8986 if you just want to add material to the preamble.) Must end with
8987 \begin_inset Quotes eld
8991 \begin_inset Flex Code
8994 \begin_layout Plain Layout
9001 \begin_inset Quotes erd
9007 \begin_layout Description
9008 \begin_inset Flex Code
9011 \begin_layout Plain Layout
9018 \begin_inset Flex Code
9021 \begin_layout Plain Layout
9028 \begin_inset Flex Code
9031 \begin_layout Plain Layout
9040 \begin_inset Flex Code
9043 \begin_layout Plain Layout
9049 ] Whether the class already provides the feature
9050 \begin_inset Flex Code
9053 \begin_layout Plain Layout
9060 A feature is in general the name of a package (
9061 \begin_inset Flex Code
9064 \begin_layout Plain Layout
9071 \begin_inset Flex Code
9074 \begin_layout Plain Layout
9080 , \SpecialChar \ldots{}
9082 \begin_inset Flex Code
9085 \begin_layout Plain Layout
9092 \begin_inset Flex Code
9095 \begin_layout Plain Layout
9101 ,\SpecialChar \ldots{}
9102 ); the complete list of supported features is unfortunately not documented
9103 outside the LyX source code—but see
9104 \begin_inset Flex Code
9107 \begin_layout Plain Layout
9113 if you're interested.
9115 \begin_inset Flex MenuItem
9118 \begin_layout Plain Layout
9119 Help\SpecialChar \menuseparator
9125 also gives an overview of the supported packages.
9128 \begin_layout Description
9129 \begin_inset Flex Code
9132 \begin_layout Plain Layout
9139 \begin_inset Flex Code
9142 \begin_layout Plain Layout
9148 ] Indicates that this layout provides the functionality of the module mentioned,
9149 which should be specified by the filename without the
9150 \begin_inset Flex Code
9153 \begin_layout Plain Layout
9160 This will typically be used if the layout includes the module directly,
9161 rather than using the
9162 \begin_inset Flex Code
9165 \begin_layout Plain Layout
9171 tag to indicate that it ought to be used.
9172 It could also be used in a module that provided an alternate implementation
9173 of the same functionality.
9176 \begin_layout Description
9177 \begin_inset Flex Code
9180 \begin_layout Plain Layout
9187 \begin_inset Flex Code
9190 \begin_layout Plain Layout
9196 ] Whether the class requires the feature
9197 \begin_inset Flex Code
9200 \begin_layout Plain Layout
9207 Multiple features must be separated by commas.
9208 Note that you can only request supported features.
9210 \begin_inset Flex Code
9213 \begin_layout Plain Layout
9219 for a list of these.)
9222 \begin_layout Description
9223 \begin_inset Flex Code
9226 \begin_layout Plain Layout
9232 A string that indicates the width of the right margin on the screen, for
9234 \begin_inset Quotes eld
9238 \begin_inset Quotes erd
9244 \begin_layout Description
9245 \begin_inset Flex Code
9248 \begin_layout Plain Layout
9254 Sets which divisions get numbered.
9256 \begin_inset Flex Code
9259 \begin_layout Plain Layout
9268 \begin_layout Description
9269 \begin_inset Flex Code
9272 \begin_layout Plain Layout
9279 \begin_inset Flex Code
9282 \begin_layout Plain Layout
9291 \begin_inset Flex Code
9294 \begin_layout Plain Layout
9300 ] Whether the class-default should be printing on one or both sides of the
9302 Can be changed in the
9303 \begin_inset Flex MenuItem
9306 \begin_layout Plain Layout
9307 Document\SpecialChar \menuseparator
9316 \begin_layout Description
9317 \begin_inset Flex Code
9320 \begin_layout Plain Layout
9326 This sequence defines a paragraph style.
9327 If the style does not yet exist, it is created; if it does exist, its parameter
9330 \begin_inset Quotes eld
9334 \begin_inset Flex Code
9337 \begin_layout Plain Layout
9344 \begin_inset Quotes erd
9348 \begin_inset Newline newline
9352 \begin_inset space ~
9356 \begin_inset CommandInset ref
9358 reference "sub:Paragraph-Styles"
9362 for details on paragraph styles.
9365 \begin_layout Description
9366 \begin_inset Flex Code
9369 \begin_layout Plain Layout
9376 \begin_inset Flex Code
9379 \begin_layout Plain Layout
9385 ] The name of the command or environment to be used with
9386 \begin_inset Flex Code
9389 \begin_layout Plain Layout
9398 \begin_layout Description
9399 \begin_inset Flex Code
9402 \begin_layout Plain Layout
9409 \begin_inset Flex Code
9412 \begin_layout Plain Layout
9421 \begin_inset Flex Code
9424 \begin_layout Plain Layout
9430 ] Indicates what kind of markup is used to define the title of a document.
9432 \begin_inset Flex Code
9435 \begin_layout Plain Layout
9441 means that the macro with name
9442 \begin_inset Flex Code
9445 \begin_layout Plain Layout
9451 will be inserted after the last layout which has
9452 \begin_inset Quotes eld
9456 \begin_inset Flex Code
9459 \begin_layout Plain Layout
9466 \begin_inset Quotes erd
9471 \begin_inset Flex Code
9474 \begin_layout Plain Layout
9480 corresponds to the case where the block of paragraphs which have
9481 \begin_inset Quotes eld
9485 \begin_inset Flex Code
9488 \begin_layout Plain Layout
9495 \begin_inset Quotes erd
9498 should be enclosed into the
9499 \begin_inset Flex Code
9502 \begin_layout Plain Layout
9511 \begin_layout Description
9512 \begin_inset Flex Code
9515 \begin_layout Plain Layout
9521 Sets which divisions are included in the table of contents.
9523 \begin_inset Flex Code
9526 \begin_layout Plain Layout
9535 \begin_layout Subsection
9536 \begin_inset Flex Code
9539 \begin_layout Plain Layout
9546 \begin_inset CommandInset label
9548 name "sub:ClassOptions"
9555 \begin_layout Standard
9557 \begin_inset Flex Code
9560 \begin_layout Plain Layout
9566 section can contain the following entries:
9569 \begin_layout Description
9570 \begin_inset Flex Code
9573 \begin_layout Plain Layout
9580 \begin_inset Flex Code
9583 \begin_layout Plain Layout
9589 ] The list of available font sizes for the document's main font, separated
9591 \begin_inset Quotes eld
9595 \begin_inset Flex Code
9598 \begin_layout Plain Layout
9605 \begin_inset Quotes erd
9611 \begin_layout Description
9612 \begin_inset Flex Code
9615 \begin_layout Plain Layout
9621 Used to set the DTD line with XML-based output classes.
9623 \begin_inset space \thinspace{}
9627 \begin_inset Quotes eld
9630 -//OASIS//DTD DocBook V4.2//EN
9631 \begin_inset Quotes erd
9637 \begin_layout Description
9638 \begin_inset Flex Code
9641 \begin_layout Plain Layout
9648 \begin_inset Flex Code
9651 \begin_layout Plain Layout
9652 string="empty|plain|headings|fancy"
9657 ] The list of available page styles, separated by
9658 \begin_inset Quotes eld
9662 \begin_inset Flex Code
9665 \begin_layout Plain Layout
9672 \begin_inset Quotes erd
9678 \begin_layout Description
9679 \begin_inset Flex Code
9682 \begin_layout Plain Layout
9689 \begin_inset Flex Code
9692 \begin_layout Plain Layout
9698 ] Some document class options, separated by a comma, that will be added
9699 to the optional part of the
9700 \begin_inset Flex Code
9703 \begin_layout Plain Layout
9714 \begin_layout Standard
9716 \begin_inset Flex Code
9719 \begin_layout Plain Layout
9725 section must end with
9726 \begin_inset Quotes eld
9730 \begin_inset Flex Code
9733 \begin_layout Plain Layout
9740 \begin_inset Quotes erd
9746 \begin_layout Subsection
9748 \begin_inset CommandInset label
9750 name "sub:Paragraph-Styles"
9757 \begin_layout Standard
9758 A paragraph style description looks like this:
9762 \begin_layout Plain Layout
9763 Note that this will either define a new style or modify an existing one.
9771 \begin_layout LyX-Code
9778 \begin_layout LyX-Code
9782 \begin_layout LyX-Code
9786 \begin_layout Standard
9787 where the following commands are allowed:
9790 \begin_layout Description
9791 \begin_inset Flex Code
9794 \begin_layout Plain Layout
9801 \begin_inset Flex Code
9804 \begin_layout Plain Layout
9809 , left, right, center
9814 ] Paragraph alignment.
9817 \begin_layout Description
9818 \begin_inset Flex Code
9821 \begin_layout Plain Layout
9828 \begin_inset Flex Code
9831 \begin_layout Plain Layout
9836 , left, right, center
9841 ] A comma separated list of permitted alignments.
9842 (Some LaTeX styles prohibit certain alignments, since those wouldn't make
9844 For example a right-aligned or centered enumeration isn't possible.)
9847 \begin_layout Description
9848 \begin_inset Flex Code
9851 \begin_layout Plain Layout
9857 Note that this will completely override any prior
9858 \begin_inset Flex Code
9861 \begin_layout Plain Layout
9867 declaration for this style.
9869 \begin_inset Quotes eld
9873 \begin_inset Flex Code
9876 \begin_layout Plain Layout
9883 \begin_inset Quotes erd
9888 \begin_inset CommandInset ref
9890 reference "sub:I18n"
9894 for details on its use.
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 \begin_layout Plain Layout
9922 Note that a `float' here is a real number, such as: 1.5.
9927 The vertical space with which the last of a chain of paragraphs with this
9928 style is separated from the following paragraph.
9929 If the next paragraph has another style, the separations are not simply
9930 added, but the maximum is taken.
9933 \begin_layout Description
9934 \begin_inset Flex Code
9937 \begin_layout Plain Layout
9944 \begin_inset Flex Code
9947 \begin_layout Plain Layout
9953 The category for this style.
9954 This is used to group related styles in the style combobox on the toolbar.
9955 Any string can be used, but you may want to use existing categories with
9960 \begin_layout Description
9961 \begin_inset Flex Code
9964 \begin_layout Plain Layout
9970 Depth of XML command.
9971 Used only with XML-type formats.
9974 \begin_layout Description
9975 \begin_inset Flex Code
9978 \begin_layout Plain Layout
9985 \begin_inset Flex Code
9988 \begin_layout Plain Layout
9994 Copies all the features of an existing style into the current one.
9998 \begin_layout Description
9999 \begin_inset Flex Code
10002 \begin_layout Plain Layout
10008 The name of a style whose preamble should be output
10013 This allows to ensure some ordering of the preamble snippets when macros
10014 definitions depend on one another.
10018 \begin_layout Plain Layout
10019 Note that, besides that functionality, there is no way to ensure any ordering
10021 The ordering that you see in a given version of LyX may change without
10022 warning in later versions.
10030 \begin_layout Description
10031 \begin_inset Flex Code
10034 \begin_layout Plain Layout
10041 \begin_inset Flex Code
10044 \begin_layout Plain Layout
10049 , Box, Filled_Box, Static
10054 ] The type of label that stands at the end of the paragraph (or sequence
10056 \begin_inset Flex Code
10059 \begin_layout Plain Layout
10066 \begin_inset Flex Code
10069 \begin_layout Plain Layout
10076 \begin_inset Flex Code
10079 \begin_layout Plain Layout
10086 \begin_inset Flex Code
10089 \begin_layout Plain Layout
10097 \begin_inset Flex Code
10100 \begin_layout Plain Layout
10107 \begin_inset Quotes eld
10111 \begin_inset Quotes erd
10115 \begin_inset Flex Code
10118 \begin_layout Plain Layout
10125 \begin_inset Flex Code
10128 \begin_layout Plain Layout
10129 \begin_inset space ~
10137 ) is a white (resp.
10138 \begin_inset space ~
10141 black) square suitable for end of proof markers,
10142 \begin_inset Flex Code
10145 \begin_layout Plain Layout
10151 is an explicit text string.
10154 \begin_layout Description
10155 \begin_inset Flex Code
10158 \begin_layout Plain Layout
10165 \begin_inset Flex Code
10168 \begin_layout Plain Layout
10174 ] The string used for a label with a
10175 \begin_inset Flex Code
10178 \begin_layout Plain Layout
10185 \begin_inset Flex Code
10188 \begin_layout Plain Layout
10198 \begin_layout Description
10199 \begin_inset Flex Code
10202 \begin_layout Plain Layout
10208 The font used for both the text body
10214 \begin_inset space ~
10218 \begin_inset CommandInset ref
10220 reference "sub:Font-description"
10225 Note that defining this font automatically defines the
10226 \begin_inset Flex Code
10229 \begin_layout Plain Layout
10236 So you should define this one first if you also want to define
10237 \begin_inset Flex Code
10240 \begin_layout Plain Layout
10249 \begin_layout Description
10250 \begin_inset Flex Code
10253 \begin_layout Plain Layout
10260 \begin_inset CommandInset label
10262 name "des:FreeSpacing"
10267 \begin_inset Flex Code
10270 \begin_layout Plain Layout
10279 \begin_inset Flex Code
10282 \begin_layout Plain Layout
10288 ] Usually LyX doesn't allow you to insert more than one space between words,
10289 since a space is considered as the separation between two words, not a
10290 character or symbol of its own.
10291 This is a very fine thing but sometimes annoying, for example, when typing
10292 program code or plain LaTeX code.
10294 \begin_inset Flex Code
10297 \begin_layout Plain Layout
10304 Note that LyX will create protected blanks for the additional blanks when
10305 in another mode than LaTeX-mode.
10308 \begin_layout Description
10309 \begin_inset Flex Code
10312 \begin_layout Plain Layout
10318 These tags are used with XHTML output.
10320 \begin_inset CommandInset ref
10322 reference "sub:Paragraph-Style-XHTML"
10329 \begin_layout Description
10330 \begin_inset Flex Code
10333 \begin_layout Plain Layout
10339 [[FIXME]] (Used only with XML-type formats.)
10342 \begin_layout Description
10343 \begin_inset Flex Code
10346 \begin_layout Plain Layout
10353 \begin_inset Flex Code
10356 \begin_layout Plain Layout
10362 If 1, marks the style as to be included in the document preamble rather
10363 than in the document body.
10364 This is useful for document classes that want such information as the title
10365 and author to appear in the preamble.
10366 Note that this works only for styles for which the
10367 \begin_inset Flex Code
10370 \begin_layout Plain Layout
10377 \begin_inset Flex Code
10380 \begin_layout Plain Layout
10387 \begin_inset Flex Code
10390 \begin_layout Plain Layout
10399 \begin_layout Description
10400 \begin_inset Flex Code
10403 \begin_layout Plain Layout
10410 \begin_inset Flex Code
10413 \begin_layout Plain Layout
10419 If 1, marks the style as being part of a title block (see also the
10420 \begin_inset Flex Code
10423 \begin_layout Plain Layout
10430 \begin_inset Flex Code
10433 \begin_layout Plain Layout
10442 \begin_layout Description
10443 \begin_inset Flex Code
10446 \begin_layout Plain Layout
10453 \begin_inset Flex Code
10456 \begin_layout Plain Layout
10462 ] This provides extra space between paragraphs that have the same style.
10463 If you put other styles into an environment, each is separated with the
10465 \begin_inset Flex Code
10468 \begin_layout Plain Layout
10475 But the whole items of the environment are additionally separated with
10477 \begin_inset Flex Code
10480 \begin_layout Plain Layout
10487 Note that this is a
10492 \begin_layout Description
10493 \begin_inset Flex Code
10496 \begin_layout Plain Layout
10502 [[FIXME]] (Used only with XML-type formats.)
10505 \begin_layout Description
10506 \begin_inset Flex Code
10509 \begin_layout Plain Layout
10516 \begin_inset Flex Code
10519 \begin_layout Plain Layout
10528 \begin_inset Flex Code
10531 \begin_layout Plain Layout
10537 ] Usually LyX does not allow you to leave a paragraph empty, since it would
10538 lead to empty LaTeX output.
10539 There are some cases where this could be desirable however: in a letter
10540 template, the required fields can be provided as empty fields, so that
10541 people do not forget them; in some special classes, a style can be used
10542 as some kind of break, which does not contain actual text.
10545 \begin_layout Description
10546 \begin_inset Flex Code
10549 \begin_layout Plain Layout
10555 [float=0] The vertical space between the label and the text body.
10556 Only used for labels that are above the text body (
10557 \begin_inset Flex Code
10560 \begin_layout Plain Layout
10567 \begin_inset Flex Code
10570 \begin_layout Plain Layout
10571 Centered_Top_Environment
10579 \begin_layout Description
10580 \begin_inset Flex Code
10583 \begin_layout Plain Layout
10590 \begin_inset Flex Code
10593 \begin_layout Plain Layout
10600 \begin_inset Newline newline
10603 The name of the counter for automatic numbering.
10605 \begin_inset Newline newline
10613 \begin_inset Flex Code
10616 \begin_layout Plain Layout
10623 \begin_inset Flex Code
10626 \begin_layout Plain Layout
10633 In that case, the counter will be stepped each time the style appears.
10635 \begin_inset Newline newline
10643 \begin_inset Flex Code
10646 \begin_layout Plain Layout
10653 \begin_inset Flex Code
10656 \begin_layout Plain Layout
10662 , though this case is a bit complicated.
10663 Suppose you declare
10664 \begin_inset Quotes eld
10668 \begin_inset Flex Code
10671 \begin_layout Plain Layout
10672 LabelCounter myenum
10678 \begin_inset Quotes erd
10682 Then the actual counters used are
10683 \begin_inset Flex Code
10686 \begin_layout Plain Layout
10693 \begin_inset Flex Code
10696 \begin_layout Plain Layout
10703 \begin_inset Flex Code
10706 \begin_layout Plain Layout
10713 \begin_inset Flex Code
10716 \begin_layout Plain Layout
10722 , much as in LaTeX.
10723 These counters must all be declared separately.
10724 \begin_inset Newline newline
10728 \begin_inset CommandInset ref
10730 reference "sub:Counters"
10734 for details on counters.
10737 \begin_layout Description
10738 \begin_inset Flex Code
10741 \begin_layout Plain Layout
10747 The font used for the label.
10749 \begin_inset space ~
10753 \begin_inset CommandInset ref
10755 reference "sub:Font-description"
10762 \begin_layout Description
10763 \begin_inset Flex Code
10766 \begin_layout Plain Layout
10772 Text that indicates how far a label should be indented.
10775 \begin_layout Description
10776 \begin_inset Flex Code
10779 \begin_layout Plain Layout
10786 \begin_inset Flex Code
10789 \begin_layout Plain Layout
10795 ] The horizontal space between the label and the text body.
10796 Only used for labels that are not above the text body.
10799 \begin_layout Description
10800 \begin_inset Flex Code
10803 \begin_layout Plain Layout
10810 \begin_inset Flex Code
10813 \begin_layout Plain Layout
10819 ] The string used for a label with a
10820 \begin_inset Flex Code
10823 \begin_layout Plain Layout
10831 \begin_inset Flex Code
10834 \begin_layout Plain Layout
10840 is set, this string can be contain the special formatting commands described
10842 \begin_inset CommandInset ref
10844 reference "sub:Counters"
10852 \begin_layout Plain Layout
10853 For the sake of backwards compatibility, the string
10854 \begin_inset Flex Code
10857 \begin_layout Plain Layout
10867 will be replaced by the expanded
10868 \begin_inset Flex Code
10871 \begin_layout Plain Layout
10878 \begin_inset Flex Code
10881 \begin_layout Plain Layout
10890 This feature is now obsolete and should be replaced by the mechanisms of
10892 \begin_inset CommandInset ref
10894 reference "sub:Counters"
10906 \begin_layout Description
10907 \begin_inset Flex Code
10910 \begin_layout Plain Layout
10911 LabelStringAppendix
10917 \begin_inset Flex Code
10920 \begin_layout Plain Layout
10926 ] This is used inside the appendix instead of
10927 \begin_inset Flex Code
10930 \begin_layout Plain Layout
10938 \begin_inset Flex Code
10941 \begin_layout Plain Layout
10948 \begin_inset Flex Code
10951 \begin_layout Plain Layout
10952 LabelStringAppendix
10960 \begin_layout Description
10961 \begin_inset Flex Code
10964 \begin_layout Plain Layout
10970 [FIXME] (Used only with XML-type formats.)
10973 \begin_layout Description
10974 \begin_inset Flex Code
10977 \begin_layout Plain Layout
10984 \begin_inset Flex Code
10987 \begin_layout Plain Layout
10992 , Manual, Static, Top_Environment, Centered_Top_Environment, Counter, Sensitive,
10993 Enumerate, Itemize, Bibliography
11002 \begin_layout Itemize
11003 \begin_inset Flex Code
11006 \begin_layout Plain Layout
11012 means the label is the very first word (up to the first real blank).
11013 Use protected spaces (like
11014 \begin_inset space ~
11017 that one) if you want more than one word as the label.
11021 \begin_layout Itemize
11022 \begin_inset Flex Code
11025 \begin_layout Plain Layout
11031 means the label is simply whatever
11032 \begin_inset Flex Code
11035 \begin_layout Plain Layout
11042 Note that this really is `static'.
11045 \begin_layout Itemize
11046 \begin_inset Flex Code
11049 \begin_layout Plain Layout
11056 \begin_inset Flex Code
11059 \begin_layout Plain Layout
11060 Centered_Top_Environment
11065 are special cases of
11066 \begin_inset Flex Code
11069 \begin_layout Plain Layout
11076 The label will be printed above the paragraph, but only at the top of an
11077 environment or the top of a chain of paragraphs with this style.
11078 This might be used with the
11079 \begin_inset Flex MenuItem
11082 \begin_layout Plain Layout
11088 style, for example.
11091 \begin_layout Itemize
11092 \begin_inset Flex Code
11095 \begin_layout Plain Layout
11101 is a special case for the caption-labels
11102 \begin_inset Quotes eld
11106 \begin_inset Quotes erd
11110 \begin_inset Quotes eld
11114 \begin_inset Quotes erd
11119 \begin_inset Flex Code
11122 \begin_layout Plain Layout
11128 means the (hardcoded) label string depends on the kind of float: It is
11129 hardcoded to be `FloatType N', where N is the value of the counter associated
11133 \begin_layout Itemize
11135 \begin_inset Flex Code
11138 \begin_layout Plain Layout
11144 label type defines automatically numbered labels.
11146 \begin_inset Flex Code
11149 \begin_layout Plain Layout
11155 will be expanded to resolve any counter references it contains: For example,
11157 \begin_inset Quotes eld
11161 \begin_inset Flex Code
11164 \begin_layout Plain Layout
11175 \begin_inset Quotes erd
11180 \begin_inset CommandInset ref
11182 reference "sub:Counters"
11186 for more information on counters.
11189 \begin_layout Itemize
11190 \begin_inset Flex Code
11193 \begin_layout Plain Layout
11199 produces the usual sort of enumeration labels.
11200 At present, it is hardcoded to use Arabic numerals, lowercase letters,
11201 small Roman numerals, and uppercase letters for the four possible depths.
11204 \begin_layout Itemize
11205 \begin_inset Flex Code
11208 \begin_layout Plain Layout
11214 produces various bullets at the different levels.
11215 It is also hardcoded.
11218 \begin_layout Itemize
11219 \begin_inset Flex Code
11222 \begin_layout Plain Layout
11228 is used internally by LyX and should be used only with
11229 \begin_inset Flex Code
11232 \begin_layout Plain Layout
11233 LatexType BibEnvironment
11242 \begin_layout Description
11243 \begin_inset Flex Code
11246 \begin_layout Plain Layout
11252 Note that this will completely override any prior
11253 \begin_inset Flex Code
11256 \begin_layout Plain Layout
11262 declaration for this style.
11264 \begin_inset Quotes eld
11268 \begin_inset Flex Code
11271 \begin_layout Plain Layout
11278 \begin_inset Quotes erd
11283 \begin_inset CommandInset ref
11285 reference "sub:I18n"
11289 for details on its use.
11292 \begin_layout Description
11293 \begin_inset Flex Code
11296 \begin_layout Plain Layout
11302 The name of the corresponding LaTeX stuff.
11303 Either the environment or command name.
11306 \begin_layout Description
11307 \begin_inset Flex Code
11310 \begin_layout Plain Layout
11316 An optional parameter for the corresponding
11317 \begin_inset Flex Code
11320 \begin_layout Plain Layout
11327 This parameter cannot be changed from within LyX.
11330 \begin_layout Description
11331 \begin_inset Flex Code
11334 \begin_layout Plain Layout
11341 \begin_inset Flex Code
11344 \begin_layout Plain Layout
11349 , Command, Environment, Item_Environment,
11355 \begin_inset Flex Code
11358 \begin_layout Plain Layout
11359 List_Environment, Bib_Environment
11364 ] How the style should be translated into LaTeX.
11368 \begin_layout Plain Layout
11369 \begin_inset Flex Code
11372 \begin_layout Plain Layout
11378 is perhaps a bit misleading, since these rules apply to SGML classes, too.
11379 Visit the SGML class files for specific examples.
11388 \begin_layout Itemize
11389 \begin_inset Flex Code
11392 \begin_layout Plain Layout
11398 means nothing special.
11402 \begin_layout Itemize
11403 \begin_inset Flex Code
11406 \begin_layout Plain Layout
11413 \begin_inset Flex Code
11416 \begin_layout Plain Layout
11423 {\SpecialChar \ldots{}
11432 \begin_layout Itemize
11433 \begin_inset Flex Code
11436 \begin_layout Plain Layout
11443 \begin_inset Flex Code
11446 \begin_layout Plain Layout
11453 }\SpecialChar \ldots{}
11469 \begin_layout Itemize
11470 \begin_inset Flex Code
11473 \begin_layout Plain Layout
11480 \begin_inset Flex Code
11483 \begin_layout Plain Layout
11490 \begin_inset Flex Code
11493 \begin_layout Plain Layout
11501 is generated for each paragraph of this environment.
11505 \begin_layout Itemize
11506 \begin_inset Flex Code
11509 \begin_layout Plain Layout
11516 \begin_inset Flex Code
11519 \begin_layout Plain Layout
11526 \begin_inset Flex Code
11529 \begin_layout Plain Layout
11535 is passed as an argument to the environment.
11537 \begin_inset Flex Code
11540 \begin_layout Plain Layout
11546 can be defined in the
11547 \begin_inset Flex MenuItem
11550 \begin_layout Plain Layout
11551 Edit\SpecialChar \menuseparator
11553 \begin_inset space ~
11565 \begin_layout Standard
11566 Putting the last few things together, the LaTeX output will be either:
11569 \begin_layout LyX-Code
11572 latexname[latexparam]{\SpecialChar \ldots{}
11576 \begin_layout Standard
11580 \begin_layout LyX-Code
11583 begin{latexname}[latexparam] \SpecialChar \ldots{}
11589 \begin_layout Standard
11590 depending upon the LaTeX type.
11594 \begin_layout Description
11595 \begin_inset Flex Code
11598 \begin_layout Plain Layout
11605 \begin_inset Flex Code
11608 \begin_layout Plain Layout
11614 ] If you put styles into environments, the leftmargins are not simply added,
11615 but added with a factor
11616 \begin_inset Formula $\frac{4}{depth+4}$
11620 Note that this parameter is also used when the margin is defined as
11621 \begin_inset Flex Code
11624 \begin_layout Plain Layout
11631 \begin_inset Flex Code
11634 \begin_layout Plain Layout
11641 Then it is added to the manual or dynamic margin.
11643 \begin_inset Newline newline
11646 The argument is passed as a string.
11648 \begin_inset Quotes eld
11652 \begin_inset Flex Code
11655 \begin_layout Plain Layout
11662 \begin_inset Quotes erd
11665 means that the paragraph is indented with the width of
11666 \begin_inset Quotes eld
11670 \begin_inset Flex Code
11673 \begin_layout Plain Layout
11680 \begin_inset Quotes erd
11683 in the normal font.
11684 You can get a negative width by prefixing the string with
11685 \begin_inset Quotes eld
11689 \begin_inset Flex Code
11692 \begin_layout Plain Layout
11699 \begin_inset Quotes erd
11703 This way was chosen so that the look is the same with each used screen
11708 \begin_layout Description
11709 \begin_inset Flex Code
11712 \begin_layout Plain Layout
11719 \begin_inset Flex Code
11722 \begin_layout Plain Layout
11727 , Manual, Dynamic, First_Dynamic, Right_Address_Box
11733 \begin_inset Newline newline
11736 The kind of margin that the style has on the left side.
11738 \begin_inset Flex Code
11741 \begin_layout Plain Layout
11747 just means a fixed margin.
11749 \begin_inset Flex Code
11752 \begin_layout Plain Layout
11758 means that the left margin depends on the string entered in the
11759 \begin_inset Flex MenuItem
11762 \begin_layout Plain Layout
11763 Edit\SpecialChar \menuseparator
11765 \begin_inset space ~
11774 This is used to typeset nice lists without tabulators.
11776 \begin_inset Flex Code
11779 \begin_layout Plain Layout
11785 means that the margin depends on the size of the label.
11786 This is used for automatic enumerated headlines.
11787 It is obvious that the headline
11788 \begin_inset Quotes eld
11791 5.4.3.2.1 Very long headline
11792 \begin_inset Quotes erd
11795 must have a wider left margin (as wide as
11796 \begin_inset Quotes eld
11800 \begin_inset Quotes erd
11803 plus the space) than
11804 \begin_inset Quotes eld
11807 3.2 Very long headline
11808 \begin_inset Quotes erd
11812 \begin_inset Quotes eld
11816 \begin_inset Quotes erd
11819 are not able to do this.
11821 \begin_inset Flex Code
11824 \begin_layout Plain Layout
11830 is similar, but only the very first row of the paragraph is dynamic, while
11831 the others are static; this is used, for example, for descriptions.
11833 \begin_inset Flex Code
11836 \begin_layout Plain Layout
11842 means the margin is chosen in a way that the longest row of this paragraph
11843 fits to the right margin.
11844 This is used to typeset an address on the right edge of the page.
11847 \begin_layout Description
11848 \begin_inset Flex Code
11851 \begin_layout Plain Layout
11858 \begin_inset Flex Code
11861 \begin_layout Plain Layout
11870 \begin_inset Flex Code
11873 \begin_layout Plain Layout
11879 ] Whether fragile commands in this style should be
11880 \begin_inset Flex Code
11883 \begin_layout Plain Layout
11896 whether this command should itself be protected.)
11899 \begin_layout Description
11900 \begin_inset Flex Code
11903 \begin_layout Plain Layout
11910 \begin_inset Flex Code
11913 \begin_layout Plain Layout
11920 \begin_inset Flex Code
11923 \begin_layout Plain Layout
11931 ] Whether newlines are translated into LaTeX newlines (
11932 \begin_inset Flex Code
11935 \begin_layout Plain Layout
11946 The translation can be switched off to allow more comfortable LaTeX editing
11950 \begin_layout Description
11951 \begin_inset Flex Code
11954 \begin_layout Plain Layout
11961 \begin_inset Flex Code
11964 \begin_layout Plain Layout
11971 \begin_inset Flex Code
11974 \begin_layout Plain Layout
11982 ] If set to true, and if
11983 \begin_inset Flex Code
11986 \begin_layout Plain Layout
11993 \begin_inset Flex Code
11996 \begin_layout Plain Layout
12002 ) paragraphs are being indented, then the indentation of such a paragraph
12003 following one of this type will be suppressed.
12004 (So this will not affect the display of non-default paragraphs.)
12007 \begin_layout Description
12008 \begin_inset Flex Code
12011 \begin_layout Plain Layout
12017 Name of a style that has replaced this style.
12018 This is used to rename a style, while keeping backward compatibility.
12021 \begin_layout Description
12022 \begin_inset Flex Code
12025 \begin_layout Plain Layout
12032 \begin_inset Flex Code
12035 \begin_layout Plain Layout
12041 ] The number of optional arguments that can be used with this style.
12042 This is useful for things like section headings, and only makes sense with
12044 Note that, on output, the optional arguments will all precede any required
12045 arguments (see below).
12046 So one can have constructs like:
12050 \begin_layout LyX-Code
12053 mycmd[opt1]{req1}{contents of paragraph}
12056 \begin_layout Standard
12057 but one cannot have things like:
12060 \begin_layout LyX-Code
12063 mycmd[opt1]{req1}[opt2]{contents of paragraph}
12066 \begin_layout Standard
12067 at least, not without ERT (with which you can have anything).
12072 \begin_layout Description
12073 \begin_inset Flex Code
12076 \begin_layout Plain Layout
12083 \begin_inset Flex Code
12086 \begin_layout Plain Layout
12095 \begin_inset Flex Code
12098 \begin_layout Plain Layout
12104 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
12105 output, but only by a line break; together with
12106 \begin_inset Flex Code
12109 \begin_layout Plain Layout
12115 , this allows to emulate a plain text editor (like the ERT inset).
12118 \begin_layout Description
12119 \begin_inset Flex Code
12122 \begin_layout Plain Layout
12129 \begin_inset Flex Code
12132 \begin_layout Plain Layout
12138 ] The indent of the very first line of a paragraph.
12140 \begin_inset Flex Code
12143 \begin_layout Plain Layout
12149 will be fixed for a certain style.
12150 The exception is the default style, since the indentation for these paragraphs
12151 can be prohibited with
12152 \begin_inset Flex Code
12155 \begin_layout Plain Layout
12163 \begin_inset Flex Code
12166 \begin_layout Plain Layout
12172 style paragraphs inside environments use the
12173 \begin_inset Flex Code
12176 \begin_layout Plain Layout
12182 of the environment, not their native one.
12184 \begin_inset Flex Code
12187 \begin_layout Plain Layout
12193 paragraphs inside an enumeration are not indented.
12196 \begin_layout Description
12197 \begin_inset Flex Code
12200 \begin_layout Plain Layout
12207 \begin_inset Flex Code
12210 \begin_layout Plain Layout
12216 ] The vertical space between two paragraphs of this style.
12219 \begin_layout Description
12220 \begin_inset Flex Code
12223 \begin_layout Plain Layout
12230 \begin_inset Flex Code
12233 \begin_layout Plain Layout
12239 ] LyX allows the user to choose either
12240 \begin_inset Quotes eld
12244 \begin_inset Quotes erd
12248 \begin_inset Quotes eld
12252 \begin_inset Quotes erd
12255 to typeset a document.
12257 \begin_inset Quotes eld
12261 \begin_inset Quotes erd
12264 is chosen, this value is completely ignored.
12266 \begin_inset Quotes eld
12270 \begin_inset Quotes erd
12273 is chosen, the parindent of a LaTeXtype
12274 \begin_inset Quotes eld
12278 \begin_inset Quotes erd
12281 style is ignored and all paragraphs are separated by this parskip argument.
12282 The vertical space is calculated with
12283 \begin_inset Flex Code
12286 \begin_layout Plain Layout
12288 \begin_inset space ~
12297 \begin_inset Flex Code
12300 \begin_layout Plain Layout
12306 is the height of a row with the normal font.
12307 This way, the look stays the same with different screen fonts.
12310 \begin_layout Description
12311 \begin_inset Flex Code
12314 \begin_layout Plain Layout
12321 \begin_inset Flex Code
12324 \begin_layout Plain Layout
12333 \begin_inset Flex Code
12336 \begin_layout Plain Layout
12342 ] Whether the contents of this paragraph should be output in raw form, meaning
12343 without special translations that LaTeX would require.
12346 \begin_layout Description
12347 \begin_inset Flex Code
12350 \begin_layout Plain Layout
12356 Information to be included in the LaTeX preamble when this style is used.
12357 Used to define macros, load packages, etc., required by this particular
12360 \begin_inset Quotes eld
12364 \begin_inset Flex Code
12367 \begin_layout Plain Layout
12374 \begin_inset Quotes erd
12380 \begin_layout Description
12381 \begin_inset Flex Code
12384 \begin_layout Plain Layout
12391 \begin_inset Flex Code
12394 \begin_layout Plain Layout
12400 ] The prefix to use when creating labels referring to paragraphs of this
12402 This allows the use of formatted references.
12405 \begin_layout Description
12406 \begin_inset Flex Code
12409 \begin_layout Plain Layout
12416 \begin_inset Flex Code
12419 \begin_layout Plain Layout
12425 ] The number of required arguments that the LaTeX command or environment
12426 corresponding to this style expects.
12427 In the case of a command, these are required arguments
12431 that associated with the content of the paragraph itself.
12432 These do not actually have to be provided: LyX will output empty arguments
12434 Note that optional arguments will be output before required arguments.
12435 See the discussion of the
12436 \begin_inset Flex Code
12439 \begin_layout Plain Layout
12445 tag above for more information.
12448 \begin_layout Description
12449 \begin_inset Flex Code
12452 \begin_layout Plain Layout
12459 \begin_inset Flex Code
12462 \begin_layout Plain Layout
12468 ] Whether the style requires the feature
12469 \begin_inset Flex Code
12472 \begin_layout Plain Layout
12479 See the description of
12480 \begin_inset Flex Code
12483 \begin_layout Plain Layout
12490 \begin_inset CommandInset ref
12491 LatexCommand pageref
12492 reference "des:FreeSpacing"
12496 ) for information on `features'.
12500 \begin_layout Description
12501 \begin_inset Flex Code
12504 \begin_layout Plain Layout
12511 \begin_inset Flex Code
12514 \begin_layout Plain Layout
12521 \begin_inset Flex Code
12524 \begin_layout Plain Layout
12533 \begin_layout Description
12534 \begin_inset Flex Code
12537 \begin_layout Plain Layout
12544 \begin_inset Flex Code
12547 \begin_layout Plain Layout
12552 , onehalf, double, other
12561 ] This defines what the default spacing should be in the style.
12563 \begin_inset Flex Code
12566 \begin_layout Plain Layout
12573 \begin_inset Flex Code
12576 \begin_layout Plain Layout
12583 \begin_inset Flex Code
12586 \begin_layout Plain Layout
12592 correspond respectively to a multiplier value of 1, 1.25 and 1.667.
12593 If you specify the argument
12594 \begin_inset Flex Code
12597 \begin_layout Plain Layout
12603 , then you should also provide a numerical argument which will be the actual
12605 Note that, contrary to other parameters,
12606 \begin_inset Flex Code
12609 \begin_layout Plain Layout
12615 implies the generation of specific LaTeX code, using the package
12618 \begin_inset Flex Code
12621 \begin_layout Plain Layout
12630 \begin_layout Description
12631 \begin_inset Flex Code
12634 \begin_layout Plain Layout
12641 \begin_inset Flex Code
12644 \begin_layout Plain Layout
12651 \begin_inset Flex Code
12654 \begin_layout Plain Layout
12662 ] Spellcheck paragraphs of this style.
12666 \begin_layout Description
12667 \begin_inset Flex Code
12670 \begin_layout Plain Layout
12676 The font used for the text body .
12678 \begin_inset CommandInset ref
12680 reference "sub:Font-description"
12687 \begin_layout Description
12688 \begin_inset Flex Code
12691 \begin_layout Plain Layout
12700 \begin_inset Flex Code
12703 \begin_layout Plain Layout
12713 The level of the style in the table of contents.
12714 This is used for automatic numbering of section headings.
12717 \begin_layout Description
12718 \begin_inset Flex Code
12721 \begin_layout Plain Layout
12728 \begin_inset Flex Code
12731 \begin_layout Plain Layout
12737 ] The vertical space with which the very first of a chain of paragraphs
12738 with this style is separated from the previous paragraph.
12739 If the previous paragraph has another style, the separations are not simply
12740 added, but the maximum is taken.
12743 \begin_layout Subsection
12744 \begin_inset CommandInset label
12750 Internationalization of Paragraph Styles
12753 \begin_layout Standard
12754 LyX has long supported internationalization of layout information, but,
12755 until version 2.0, this applied only to the user interface and not to, say,
12757 Thus, French authors were forced to resort to ugly hacks if they wanted
12762 1' instead of `Theorem 1'.
12763 Thanks to Georg Baum, that is no longer the case.
12766 \begin_layout Standard
12768 \begin_inset Flex Code
12771 \begin_layout Plain Layout
12777 defines text that is to appear in the typeset document, it may use
12778 \begin_inset Flex Code
12781 \begin_layout Plain Layout
12788 \begin_inset Flex Code
12791 \begin_layout Plain Layout
12797 to support non-English and even multi-language documents correctly.
12798 The following excerpt (from the
12799 \begin_inset Flex Code
12802 \begin_layout Plain Layout
12808 file) shows how this works:
12811 \begin_layout LyX-Code
12816 \begin_layout LyX-Code
12819 theoremstyle{remark}
12822 \begin_layout LyX-Code
12825 newtheorem{claim}[thm]{
12832 \begin_layout LyX-Code
12836 \begin_layout LyX-Code
12840 \begin_layout LyX-Code
12845 claimname}{_(Claim)}
12848 \begin_layout LyX-Code
12852 \begin_layout LyX-Code
12856 \begin_layout LyX-Code
12865 claimname}{_(Claim)}}
12868 \begin_layout LyX-Code
12873 \begin_layout Standard
12874 In principle, any legal LaTeX may appear in the
12875 \begin_inset Flex Code
12878 \begin_layout Plain Layout
12885 \begin_inset Flex Code
12888 \begin_layout Plain Layout
12894 tags, but in practice they will typically look as they do here.
12895 The key to correct translation of the typeset text is the definition of
12897 \begin_inset Flex Code
12900 \begin_layout Plain Layout
12909 \begin_inset Flex Code
12912 \begin_layout Plain Layout
12924 \begin_layout Standard
12926 \begin_inset Flex Code
12929 \begin_layout Plain Layout
12935 tag provides for internationalization based upon the overall language of
12937 The contents of the tag will be included in the preamble, just as with
12939 \begin_inset Flex Code
12942 \begin_layout Plain Layout
12949 What makes it special is the use of the
12950 \begin_inset Quotes eld
12954 \begin_inset Quotes erd
12958 \begin_inset Flex Code
12961 \begin_layout Plain Layout
12967 , which will be replaced, when LyX produces LaTeX output, with the translation
12968 of its argument into the document language.
12971 \begin_layout Standard
12973 \begin_inset Flex Code
12976 \begin_layout Plain Layout
12982 tag is more complex, since it is meant to provide support for multi-language
12983 documents and so offers an interface to the
12984 \begin_inset Flex Code
12987 \begin_layout Plain Layout
12994 Its contents will be added to the preamble once for each language that
12995 appears in the document.
12996 In this case, the argument to
12997 \begin_inset Flex Code
13000 \begin_layout Plain Layout
13006 will be replaced with its translation into the language in question; the
13008 \begin_inset Flex Code
13011 \begin_layout Plain Layout
13017 is replaced by the language name (as used by the babel package).
13020 \begin_layout Standard
13021 A German document that also included a French section would thus have the
13022 following in the preamble:
13025 \begin_layout LyX-Code
13034 claimname}{Affirmation}}
13042 claimname}{Behauptung}}
13046 claimname}{Behauptung}
13049 \begin_layout Standard
13051 \begin_inset Flex Code
13054 \begin_layout Plain Layout
13060 will then conspire to produce the correct text in the output.
13063 \begin_layout Standard
13064 One important point to note here is that the translations are provided by
13065 LyX itself, through the
13066 \change_inserted -195340706 1334775793
13068 \begin_inset Flex Code
13071 \begin_layout Plain Layout
13073 \change_inserted -195340706 1334775793
13080 \change_deleted -195340706 1334775793
13081 same mechanism it uses for internationalization of the user interface
13084 This means, in effect, that
13085 \begin_inset Flex Code
13088 \begin_layout Plain Layout
13095 \begin_inset Flex Code
13098 \begin_layout Plain Layout
13104 are really only of use in layout files that are provided with LyX, since
13105 text entered in user-created layout files will not be seen by LyX's internation
13107 \change_inserted -195340706 1334775793
13109 \begin_inset Flex Code
13112 \begin_layout Plain Layout
13114 \change_inserted -195340706 1334775793
13120 file is modified accordingly
13123 That said, however, any layout created with the intention that it will
13124 be included with LyX should use these tags where appropriate.
13126 \change_inserted -195340706 1334775793
13127 Please note that the paragraph style translations provided by LyX will
13128 never change with a minor update (e.g.
13129 from version 2.1.x to 2.1.y).
13130 It is however quite likely that a major update (e.g.
13131 from 2.0.x to 2.1.y) will introduce new translations or corrections.
13136 \begin_layout Subsection
13138 \begin_inset CommandInset label
13147 \begin_layout Standard
13148 Since version 1.3.0 of LyX, it is has been both possible and necessary to
13149 define the floats (
13150 \begin_inset Flex MenuItem
13153 \begin_layout Plain Layout
13160 \begin_inset Flex MenuItem
13163 \begin_layout Plain Layout
13169 , \SpecialChar \ldots{}
13170 ) in the text class itself.
13171 Standard floats are included in the file
13172 \begin_inset Flex Code
13175 \begin_layout Plain Layout
13181 , so you may have to do no more than add
13184 \begin_layout LyX-Code
13185 Input stdfloats.inc
13188 \begin_layout Standard
13189 to your layout file.
13190 If you want to implement a text class that proposes some other float types
13191 (like the AGU class bundled with LyX), the information below will hopefully
13195 \begin_layout Description
13196 \begin_inset Flex Code
13199 \begin_layout Plain Layout
13206 \begin_inset Flex Code
13209 \begin_layout Plain Layout
13216 \begin_inset Quotes erd
13220 \begin_inset Quotes erd
13223 ] The file name extension of an auxiliary file for the list of figures (or
13225 LaTeX writes the captions to this file.
13228 \begin_layout Description
13229 \begin_inset Flex Code
13232 \begin_layout Plain Layout
13239 \begin_inset Flex Code
13242 \begin_layout Plain Layout
13249 \begin_inset Quotes erd
13253 \begin_inset Quotes erd
13256 ] The string that will be used in the menus and also for the caption.
13257 This is translated to the current language if babel is used.
13260 \begin_layout Description
13261 \begin_inset Flex Code
13264 \begin_layout Plain Layout
13270 These are used for XHTML output.
13272 \begin_inset CommandInset ref
13274 reference "sec:Tags-for-XHTML"
13281 \begin_layout Description
13282 \begin_inset Flex Code
13285 \begin_layout Plain Layout
13294 \begin_inset Flex Code
13297 \begin_layout Plain Layout
13306 \begin_inset Flex Code
13309 \begin_layout Plain Layout
13315 ] Indicates whether the float is already defined in the document class or
13316 if we instead need to load
13317 \begin_inset Flex Code
13320 \begin_layout Plain Layout
13326 and use what it provides to define it on-the-fly.
13328 \begin_inset Flex Code
13331 \begin_layout Plain Layout
13338 \begin_inset Flex Code
13341 \begin_layout Plain Layout
13348 It should be set to
13349 \begin_inset Flex Code
13352 \begin_layout Plain Layout
13358 if the float is already defined by the LaTeX document class.
13361 \begin_layout Description
13362 \begin_inset Flex Code
13365 \begin_layout Plain Layout
13372 \begin_inset Flex Code
13375 \begin_layout Plain Layout
13382 \begin_inset Quotes erd
13386 \begin_inset Quotes erd
13389 ] The command used to generate a list of floats of this type; the leading
13392 ' should be omitted.
13398 \begin_inset Flex Code
13401 \begin_layout Plain Layout
13407 is false, since there is no standard way to generate this command.
13409 \begin_inset Flex Code
13412 \begin_layout Plain Layout
13418 is true, since in that case there is a standard way to define the command.
13421 \begin_layout Description
13422 \begin_inset Flex Code
13425 \begin_layout Plain Layout
13432 \begin_inset Flex Code
13435 \begin_layout Plain Layout
13442 \begin_inset Quotes erd
13446 \begin_inset Quotes erd
13449 ] A title for a list of floats of this kind (list of figures, tables, or
13451 It is used for the screen label within LyX; it is passed to LaTeX for use
13452 as the title there; and it is used as the title in XHTML output.
13453 It will be translated to the document language.
13456 \begin_layout Description
13457 \begin_inset Flex Code
13460 \begin_layout Plain Layout
13467 \begin_inset Flex Code
13470 \begin_layout Plain Layout
13477 \begin_inset Quotes erd
13481 \begin_inset Quotes erd
13484 ] This (optional) argument determines whether floats of this class will
13485 be numbered within some sectional unit of the document.
13486 For example, if within is equal to
13487 \begin_inset Flex Code
13490 \begin_layout Plain Layout
13496 , the floats will be numbered within chapters.
13500 \begin_layout Description
13501 \begin_inset Flex Code
13504 \begin_layout Plain Layout
13511 \begin_inset Flex Code
13514 \begin_layout Plain Layout
13521 \begin_inset Quotes erd
13525 \begin_inset Quotes erd
13528 ] The default placement for the given class of floats.
13529 The string should be as in standard LaTeX:
13530 \begin_inset Flex Code
13533 \begin_layout Plain Layout
13540 \begin_inset Flex Code
13543 \begin_layout Plain Layout
13550 \begin_inset Flex Code
13553 \begin_layout Plain Layout
13560 \begin_inset Flex Code
13563 \begin_layout Plain Layout
13569 for top, bottom, page, and here, respectively.
13573 \begin_layout Plain Layout
13574 Note that the order of these letters in the string is irrelevant, like in
13580 On top of that there is a new type,
13581 \begin_inset Flex Code
13584 \begin_layout Plain Layout
13590 , which does not really correspond to a float, since it means: put it
13591 \begin_inset Quotes eld
13595 \begin_inset Quotes erd
13599 Note however that the
13600 \begin_inset Flex Code
13603 \begin_layout Plain Layout
13609 specifier is special and, because of implementation details, cannot be
13610 used in non-built in float types.
13611 If you do not understand what this means, just use
13612 \begin_inset Quotes eld
13616 \begin_inset Flex Code
13619 \begin_layout Plain Layout
13626 \begin_inset Quotes erd
13632 \begin_layout Description
13633 \begin_inset Flex Code
13636 \begin_layout Plain Layout
13643 \begin_inset Flex Code
13646 \begin_layout Plain Layout
13652 ] The prefix to use when creating labels referring to floats of this type.
13653 This allows the use of formatted references.
13654 Note that you can remove any
13655 \begin_inset Flex Code
13658 \begin_layout Plain Layout
13664 set by a copied style by using the special value
13665 \begin_inset Quotes eld
13669 \begin_inset Quotes erd
13672 , which must be all caps.
13675 \begin_layout Description
13676 \begin_inset Flex Code
13679 \begin_layout Plain Layout
13686 \begin_inset Flex Code
13689 \begin_layout Plain Layout
13696 \begin_inset Quotes erd
13700 \begin_inset Quotes erd
13703 ] The style used when defining the float using
13704 \begin_inset Flex Code
13707 \begin_layout Plain Layout
13718 \begin_layout Description
13719 \begin_inset Flex Code
13722 \begin_layout Plain Layout
13729 \begin_inset Flex Code
13732 \begin_layout Plain Layout
13739 \begin_inset Quotes erd
13743 \begin_inset Quotes erd
13747 \begin_inset Quotes eld
13751 \begin_inset Quotes erd
13754 of the new class of floats, like program or algorithm.
13755 After the appropriate
13756 \begin_inset Flex Code
13759 \begin_layout Plain Layout
13768 \begin_inset Flex Code
13771 \begin_layout Plain Layout
13780 \begin_inset Flex Code
13783 \begin_layout Plain Layout
13794 \begin_layout Description
13795 \begin_inset Flex Code
13798 \begin_layout Plain Layout
13805 \begin_inset Flex Code
13808 \begin_layout Plain Layout
13815 \begin_inset Flex Code
13818 \begin_layout Plain Layout
13826 ] Tells us whether this float is defined using the facilities provided by
13828 \begin_inset Flex Code
13831 \begin_layout Plain Layout
13837 , either by the class file or a package, or on-the-fly by LyX itself.
13840 \begin_layout Standard
13841 Note that defining a float with type
13842 \begin_inset Flex Code
13845 \begin_layout Plain Layout
13853 automatically defines the corresponding counter with name
13854 \begin_inset Flex Code
13857 \begin_layout Plain Layout
13868 \begin_layout Subsection
13869 Flex insets and InsetLayout
13870 \begin_inset CommandInset label
13872 name "sub:Flex-insets-and"
13879 \begin_layout Standard
13880 LyX has supported character styles since version 1.4.0; as of version 1.6.0,
13881 these are called Flex insets.
13885 \begin_layout Standard
13886 Flex insets come in three different kinds:
13889 \begin_layout Itemize
13891 \begin_inset Flex Code
13894 \begin_layout Plain Layout
13900 ): These define semantic markup corresponding to such LaTeX commands as
13902 \begin_inset Flex Code
13905 \begin_layout Plain Layout
13914 \begin_inset Flex Code
13917 \begin_layout Plain Layout
13928 \begin_layout Itemize
13930 \begin_inset Flex Code
13933 \begin_layout Plain Layout
13939 ): These can be used to define custom collapsible insets, similar to TeX
13940 code, footnote, and the like.
13941 An obvious example is an endnote inset, which is defined in the
13942 \begin_inset Flex Code
13945 \begin_layout Plain Layout
13954 \begin_layout Itemize
13956 \begin_inset Flex Code
13959 \begin_layout Plain Layout
13965 ): For use with DocBook classes.
13968 \begin_layout Standard
13969 Flex insets are defined using the
13970 \begin_inset Flex Code
13973 \begin_layout Plain Layout
13979 tag, which shall be explained in a moment.
13982 \begin_layout Standard
13984 \begin_inset Flex Code
13987 \begin_layout Plain Layout
13993 tag also serves another function: It can be used to customize the general
13994 layout of many different types of insets.
13996 \begin_inset Flex Code
13999 \begin_layout Plain Layout
14005 can be used to customize the layout parameters for footnotes, marginal
14006 notes, note insets, TeX code (ERT) insets, branches, listings, indexes,
14007 boxes, tables, algorithms, URLs, and optional arguments, as well as to
14008 define Flex insets.
14011 \begin_layout Standard
14013 \begin_inset Flex Code
14016 \begin_layout Plain Layout
14022 definition must begin with a line of the form:
14025 \begin_layout LyX-Code
14029 \begin_layout Standard
14031 \begin_inset Flex Code
14034 \begin_layout Plain Layout
14040 indicates the inset whose layout is being defined, and here there are two
14044 \begin_layout Enumerate
14045 The layout for a pre-existing inset is being modified.
14046 In this case, can be
14047 \begin_inset Flex Code
14050 \begin_layout Plain Layout
14056 any one of the following:
14057 \begin_inset Flex Code
14060 \begin_layout Plain Layout
14067 \begin_inset Flex Code
14070 \begin_layout Plain Layout
14077 \begin_inset Flex Code
14080 \begin_layout Plain Layout
14087 \begin_inset Flex Code
14090 \begin_layout Plain Layout
14097 \begin_inset Flex Code
14100 \begin_layout Plain Layout
14107 \begin_inset Flex Code
14110 \begin_layout Plain Layout
14117 \begin_inset Flex Code
14120 \begin_layout Plain Layout
14127 \begin_inset Flex Code
14130 \begin_layout Plain Layout
14137 \begin_inset Flex Code
14140 \begin_layout Plain Layout
14147 \begin_inset Flex Code
14150 \begin_layout Plain Layout
14157 \begin_inset Flex Code
14160 \begin_layout Plain Layout
14167 \begin_inset Flex Code
14170 \begin_layout Plain Layout
14177 \begin_inset Flex Code
14180 \begin_layout Plain Layout
14187 \begin_inset Flex Code
14190 \begin_layout Plain Layout
14197 \begin_inset Flex Code
14200 \begin_layout Plain Layout
14207 \begin_inset Flex Code
14210 \begin_layout Plain Layout
14217 \begin_inset Flex Code
14220 \begin_layout Plain Layout
14227 \begin_inset Flex Code
14230 \begin_layout Plain Layout
14237 \begin_inset Flex Code
14240 \begin_layout Plain Layout
14247 \begin_inset Flex Code
14250 \begin_layout Plain Layout
14259 \begin_layout Enumerate
14260 The layout for a Flex inset is being defined.
14262 \begin_inset Flex Code
14265 \begin_layout Plain Layout
14271 must be of the form
14272 \begin_inset Quotes eld
14276 \begin_inset Flex Code
14279 \begin_layout Plain Layout
14286 \begin_inset Quotes erd
14290 \begin_inset Flex Code
14293 \begin_layout Plain Layout
14299 may be be any valid identifier not used by a pre-existing Flex inset.
14300 The identifier may include spaces, but in that case the whole thing must
14301 be wrapped in quotes.
14302 Note that the definition of a flex inset
14307 \begin_inset Flex Code
14310 \begin_layout Plain Layout
14316 entry, declaring which type of inset it defines.
14319 \begin_layout Standard
14321 \begin_inset Flex Code
14324 \begin_layout Plain Layout
14330 definition can contain the following entries:
14333 \begin_layout Description
14335 \change_inserted -195340706 1333913893
14336 \begin_inset Flex Code
14339 \begin_layout Plain Layout
14345 Preamble for changing languages.
14347 \begin_inset space ~
14351 \begin_inset CommandInset ref
14353 reference "sub:I18n"
14360 \begin_layout Description
14361 \begin_inset Flex Code
14364 \begin_layout Plain Layout
14370 The color for the inset's background.
14371 The valid colors are defined in
14372 \begin_inset Flex Code
14375 \begin_layout Plain Layout
14384 \begin_layout Description
14385 \begin_inset Flex Code
14388 \begin_layout Plain Layout
14395 \begin_inset Flex Code
14398 \begin_layout Plain Layout
14407 \begin_inset Flex Code
14410 \begin_layout Plain Layout
14416 ] Whether to use the content of the inset as the label, when the inset is
14421 \begin_layout Description
14422 \begin_inset Flex Code
14425 \begin_layout Plain Layout
14432 \begin_inset Flex Code
14435 \begin_layout Plain Layout
14441 Copies all the features of an existing style into the current one.
14445 \begin_layout Description
14446 \begin_inset Flex Code
14449 \begin_layout Plain Layout
14456 \begin_inset Flex Code
14459 \begin_layout Plain Layout
14468 \begin_inset Flex Code
14471 \begin_layout Plain Layout
14477 ] Indicates whether the user may employ the Paragraph Settings dialog to
14478 customize the paragraph.
14481 \begin_layout Description
14482 \begin_inset Flex Code
14485 \begin_layout Plain Layout
14492 \begin_inset Flex Code
14495 \begin_layout Plain Layout
14502 \begin_inset Flex Code
14505 \begin_layout Plain Layout
14512 \begin_inset Flex Code
14515 \begin_layout Plain Layout
14521 , describing the rendering style used for the inset's frame and buttons.
14522 Footnotes generally use
14523 \begin_inset Flex Code
14526 \begin_layout Plain Layout
14532 , ERT insets generally
14533 \begin_inset Flex Code
14536 \begin_layout Plain Layout
14542 , and character styles
14543 \begin_inset Flex Code
14546 \begin_layout Plain Layout
14555 \begin_layout Description
14556 \begin_inset Flex Code
14559 \begin_layout Plain Layout
14566 \begin_inset Flex Code
14569 \begin_layout Plain Layout
14576 \begin_inset Flex Code
14579 \begin_layout Plain Layout
14588 \begin_inset Flex Code
14591 \begin_layout Plain Layout
14598 \begin_inset Flex Code
14601 \begin_layout Plain Layout
14608 Indicates whether the environment will stand on its own in LaTeX output
14609 or will appear inline with the surrounding text.
14610 If set to false, it is supposed that the LaTeX environment ignores white
14611 space (including one newline character) after the
14612 \begin_inset Flex Code
14615 \begin_layout Plain Layout
14628 \begin_inset Flex Code
14631 \begin_layout Plain Layout
14647 \begin_layout Description
14648 \begin_inset Flex Code
14651 \begin_layout Plain Layout
14657 Required at the end of the InsetLayout declarations.
14660 \begin_layout Description
14661 \begin_inset Flex Code
14664 \begin_layout Plain Layout
14670 The font used for both the text body
14676 \begin_inset space ~
14680 \begin_inset CommandInset ref
14682 reference "sub:Font-description"
14687 Note that defining this font automatically defines the
14688 \begin_inset Flex Code
14691 \begin_layout Plain Layout
14697 to the same value, so define this first and define
14698 \begin_inset Flex Code
14701 \begin_layout Plain Layout
14707 later if you want them to be different.
14710 \begin_layout Description
14711 \begin_inset Flex Code
14714 \begin_layout Plain Layout
14721 \begin_inset Quotes eld
14725 \begin_inset Quotes erd
14728 language, leading to Left-to-Right (latin) output, e.
14729 \begin_inset space \thinspace{}
14733 \begin_inset space \space{}
14736 in TeX code or URL.
14740 \begin_layout Description
14741 \begin_inset Flex Code
14744 \begin_layout Plain Layout
14751 \begin_inset Flex Code
14754 \begin_layout Plain Layout
14763 \begin_inset Flex Code
14766 \begin_layout Plain Layout
14772 ] Indicates whether the
14773 \begin_inset Flex Code
14776 \begin_layout Plain Layout
14782 should be used or, instead, the user can change the paragraph style used
14787 \begin_layout Description
14788 \begin_inset Flex Code
14791 \begin_layout Plain Layout
14798 \begin_inset Flex Code
14801 \begin_layout Plain Layout
14810 \begin_inset Flex Code
14813 \begin_layout Plain Layout
14819 ] Usually LyX doesn't allow you to insert more than one space between words,
14820 since a space is considered as the separation between two words, not a
14821 character or symbol of its own.
14822 This is a very fine thing but sometimes annoying, for example, when typing
14823 program code or plain LaTeX code.
14825 \begin_inset Flex Code
14828 \begin_layout Plain Layout
14835 Note that LyX will create protected blanks for the additional blanks when
14836 in another mode than LaTeX-mode.
14840 \begin_layout Description
14841 \begin_inset Flex Code
14844 \begin_layout Plain Layout
14850 These tags control XHTML output.
14852 \begin_inset CommandInset ref
14854 reference "sec:Tags-for-XHTML"
14861 \begin_layout Description
14862 \begin_inset Flex Code
14865 \begin_layout Plain Layout
14872 \begin_inset Flex Code
14875 \begin_layout Plain Layout
14884 \begin_inset Flex Code
14887 \begin_layout Plain Layout
14893 ] Whether to include the contents of this inset in the strings generated
14894 for the `Outline' pane.
14895 One would not, for example, want the content of a footnote in a section
14896 header to be included in the TOC displayed in the outline, but one would
14897 normally want the content of a character style displayed.
14898 Default is false: not to include.
14901 \begin_layout Description
14902 \begin_inset Flex Code
14905 \begin_layout Plain Layout
14912 \begin_inset Flex Code
14915 \begin_layout Plain Layout
14924 \begin_inset Flex Code
14927 \begin_layout Plain Layout
14933 ] Usually LyX does not allow you to leave a paragraph empty, since it would
14934 lead to empty LaTeX output.
14935 There are some cases where this could be desirable however: in a letter
14936 template, the required fields can be provided as empty fields, so that
14937 people do not forget them; in some special classes, a style can be used
14938 as some kind of break, which does not contain actual text.
14942 \begin_layout Description
14943 \begin_inset Flex Code
14946 \begin_layout Plain Layout
14952 The font used for the label.
14954 \begin_inset space ~
14958 \begin_inset CommandInset ref
14960 reference "sub:Font-description"
14965 Note that this definition can never appear before
14966 \begin_inset Flex Code
14969 \begin_layout Plain Layout
14975 , lest it be ineffective.
14978 \begin_layout Description
14979 \begin_inset Flex Code
14982 \begin_layout Plain Layout
14988 What will be displayed on the button or elsewhere as the inset label.
14990 \begin_inset Flex Code
14993 \begin_layout Plain Layout
15000 \begin_inset Flex Code
15003 \begin_layout Plain Layout
15009 ) modify this label on the fly.
15012 \begin_layout Description
15014 \change_inserted -195340706 1333913893
15015 \begin_inset Flex Code
15018 \begin_layout Plain Layout
15024 Language dependent preamble.
15026 \begin_inset space ~
15030 \begin_inset CommandInset ref
15032 reference "sub:I18n"
15039 \begin_layout Description
15040 \begin_inset Flex Code
15043 \begin_layout Plain Layout
15049 The name of the corresponding LaTeX stuff.
15050 Either the environment or command name.
15053 \begin_layout Description
15054 \begin_inset Flex Code
15057 \begin_layout Plain Layout
15063 The optional parameter for the corresponding
15064 \begin_inset Flex Code
15067 \begin_layout Plain Layout
15073 stuff, including possible bracket pairs like
15074 \begin_inset Flex Code
15077 \begin_layout Plain Layout
15084 This parameter cannot be changed from within LyX.
15087 \begin_layout Description
15088 \begin_inset Flex Code
15091 \begin_layout Plain Layout
15098 \begin_inset Flex Code
15101 \begin_layout Plain Layout
15106 , Command, Environment, Item_Environment,
15112 \begin_inset Flex Code
15115 \begin_layout Plain Layout
15116 List_Environment, Bib_Environment
15121 ] How the style should be translated into LaTeX.
15125 \begin_layout Plain Layout
15126 \begin_inset Flex Code
15129 \begin_layout Plain Layout
15135 is perhaps a bit misleading, since these rules apply to SGML classes, too.
15136 Visit the SGML class files for specific examples.
15145 \begin_layout Itemize
15146 \begin_inset Flex Code
15149 \begin_layout Plain Layout
15155 means nothing special.
15159 \begin_layout Itemize
15160 \begin_inset Flex Code
15163 \begin_layout Plain Layout
15170 \begin_inset Flex Code
15173 \begin_layout Plain Layout
15180 {\SpecialChar \ldots{}
15189 \begin_layout Itemize
15190 \begin_inset Flex Code
15193 \begin_layout Plain Layout
15200 \begin_inset Flex Code
15203 \begin_layout Plain Layout
15210 }\SpecialChar \ldots{}
15226 \begin_layout Itemize
15227 \begin_inset Flex Code
15230 \begin_layout Plain Layout
15237 \begin_inset Flex Code
15240 \begin_layout Plain Layout
15247 \begin_inset Flex Code
15250 \begin_layout Plain Layout
15258 is generated for each paragraph of this environment.
15262 \begin_layout Itemize
15263 \begin_inset Flex Code
15266 \begin_layout Plain Layout
15273 \begin_inset Flex Code
15276 \begin_layout Plain Layout
15283 \begin_inset Flex Code
15286 \begin_layout Plain Layout
15292 is passed as an argument to the environment.
15294 \begin_inset Flex Code
15297 \begin_layout Plain Layout
15303 can be defined in the
15304 \begin_inset Flex MenuItem
15307 \begin_layout Plain Layout
15312 \SpecialChar \menuseparator
15318 \begin_inset space ~
15330 \begin_layout Standard
15331 Putting the last few things together, the LaTeX output will be either:
15334 \begin_layout LyX-Code
15337 latexname[latexparam]{\SpecialChar \ldots{}
15341 \begin_layout Standard
15345 \begin_layout LyX-Code
15348 begin{latexname}[latexparam] \SpecialChar \ldots{}
15354 \begin_layout Standard
15355 depending upon the LaTeX type.
15359 \begin_layout Description
15360 \begin_inset Flex Code
15363 \begin_layout Plain Layout
15370 \begin_inset Flex Code
15373 \begin_layout Plain Layout
15380 \begin_inset Flex Code
15383 \begin_layout Plain Layout
15390 \begin_inset Flex Code
15393 \begin_layout Plain Layout
15400 \begin_inset Flex Code
15403 \begin_layout Plain Layout
15409 (indicating a dummy definition ending definitions of charstyles, etc).
15410 This entry is required in and is only meaningful for Flex insets.
15411 Among other things, it determines on which menu this inset will appear.
15413 \begin_inset Flex Code
15416 \begin_layout Plain Layout
15423 \begin_inset Flex Code
15426 \begin_layout Plain Layout
15433 \begin_inset Flex Code
15436 \begin_layout Plain Layout
15444 \begin_inset Flex Code
15447 \begin_layout Plain Layout
15453 can be set to true for charstyle insets, if you wish, by setting it
15458 \begin_inset Flex Code
15461 \begin_layout Plain Layout
15470 \begin_layout Description
15471 \begin_inset Flex Code
15474 \begin_layout Plain Layout
15481 \begin_inset Flex Code
15484 \begin_layout Plain Layout
15493 \begin_inset Flex Code
15496 \begin_layout Plain Layout
15502 ] Whether multiple paragraphs are permitted in this inset.
15504 \begin_inset Flex Code
15507 \begin_layout Plain Layout
15513 to the same value and
15514 \begin_inset Flex Code
15517 \begin_layout Plain Layout
15523 to the opposite value.
15524 These can be reset to other values, if they are used
15529 \begin_inset Flex Code
15532 \begin_layout Plain Layout
15542 \begin_layout Description
15543 \begin_inset Flex Code
15546 \begin_layout Plain Layout
15553 \begin_inset Flex Code
15556 \begin_layout Plain Layout
15565 \begin_inset Flex Code
15568 \begin_layout Plain Layout
15574 ] Whether fragile commands in this inset should be
15575 \begin_inset Flex Code
15578 \begin_layout Plain Layout
15591 whether the command should itself be protected.) Default is false.
15594 \begin_layout Description
15595 \begin_inset Flex Code
15598 \begin_layout Plain Layout
15605 \begin_inset Flex Code
15608 \begin_layout Plain Layout
15617 \begin_inset Flex Code
15620 \begin_layout Plain Layout
15626 ] Indicates that paragraphs will not be separated by an empty line in LaTeX
15627 output, but only by a line break; together with
15628 \begin_inset Flex Code
15631 \begin_layout Plain Layout
15637 , this allows to emulate a plain text editor (like the ERT inset).
15641 \begin_layout Description
15642 \begin_inset Flex Code
15645 \begin_layout Plain Layout
15652 \begin_inset Flex Code
15655 \begin_layout Plain Layout
15664 \begin_inset Flex Code
15667 \begin_layout Plain Layout
15673 ] Whether the contents of this paragraph should be output in raw form, meaning
15674 without special translations that LaTeX would require.
15677 \begin_layout Description
15678 \begin_inset Flex Code
15681 \begin_layout Plain Layout
15687 Information to be included in the LaTeX preamble when this style is used.
15688 Used to define macros, load packages, etc., required by this particular
15691 \begin_inset Quotes eld
15695 \begin_inset Flex Code
15698 \begin_layout Plain Layout
15705 \begin_inset Quotes erd
15711 \begin_layout Description
15712 \begin_inset Flex Code
15715 \begin_layout Plain Layout
15722 \begin_inset Flex Code
15725 \begin_layout Plain Layout
15731 ] The prefix to use when creating labels referring to insets of this type.
15732 This allows the use of formatted references.
15735 \begin_layout Description
15736 \begin_inset Flex Code
15739 \begin_layout Plain Layout
15746 \begin_inset Flex Code
15749 \begin_layout Plain Layout
15755 ] Whether the style requires the feature
15756 \begin_inset Flex Code
15759 \begin_layout Plain Layout
15766 See the description of
15767 \begin_inset Flex Code
15770 \begin_layout Plain Layout
15777 \begin_inset CommandInset ref
15778 LatexCommand pageref
15779 reference "des:FreeSpacing"
15783 ) for information on `features'.
15787 \begin_layout Description
15788 \begin_inset Flex Code
15791 \begin_layout Plain Layout
15798 \begin_inset Flex Code
15801 \begin_layout Plain Layout
15808 \begin_inset Flex Code
15811 \begin_layout Plain Layout
15819 ] Whether this inset should use the font of its surrounding environment
15821 Default is true: uses its own.
15824 \begin_layout Description
15825 \begin_inset Flex Code
15828 \begin_layout Plain Layout
15835 \begin_inset Flex Code
15838 \begin_layout Plain Layout
15845 \begin_inset Flex Code
15848 \begin_layout Plain Layout
15856 ] Spellcheck the contents of this inset.
15860 \begin_layout Subsection
15862 \begin_inset CommandInset label
15864 name "sub:Counters"
15871 \begin_layout Standard
15872 Since version 1.3.0 of LyX, it is both possible and necessary to define the
15874 \begin_inset Flex MenuItem
15877 \begin_layout Plain Layout
15884 \begin_inset Flex MenuItem
15887 \begin_layout Plain Layout
15893 , \SpecialChar \ldots{}
15894 ) in the text class itself.
15895 The standard counters are defined in the file
15896 \begin_inset Flex Code
15899 \begin_layout Plain Layout
15905 , so you may have to do no more than add
15908 \begin_layout LyX-Code
15909 Input stdcounters.inc
15912 \begin_layout Standard
15913 to your layout file to get them to work.
15914 But if you want to define custom counters, then you can do so.
15915 The counter declaration must begin with:
15918 \begin_layout LyX-Code
15919 Counter CounterName
15922 \begin_layout Standard
15924 \begin_inset Flex Code
15927 \begin_layout Plain Layout
15933 ' is replaced by the name of the counter.
15934 And it must end with
15935 \begin_inset Quotes eld
15939 \begin_inset Flex Code
15942 \begin_layout Plain Layout
15949 \begin_inset Quotes erd
15953 The following parameters can also be used:
15956 \begin_layout Description
15957 \begin_inset Flex Code
15960 \begin_layout Plain Layout
15967 \begin_inset Flex Code
15970 \begin_layout Plain Layout
15977 \begin_inset Quotes erd
15981 \begin_inset Quotes erd
15984 ] When defined, this string defines how the counter is displayed.
15985 Setting this value sets
15986 \begin_inset Flex Code
15989 \begin_layout Plain Layout
15990 LabelStringAppendix
15996 The following special constructs can be used in the string:
16000 \begin_layout Itemize
16001 \begin_inset Flex Code
16004 \begin_layout Plain Layout
16012 will be replaced by the expansion of the
16013 \begin_inset Flex Code
16016 \begin_layout Plain Layout
16023 \begin_inset Flex Code
16026 \begin_layout Plain Layout
16027 LabelStringAppendix
16033 \begin_inset Flex Code
16036 \begin_layout Plain Layout
16046 \begin_layout Itemize
16047 counter values can be expressed using LaTeX-like macros
16048 \begin_inset Flex Code
16051 \begin_layout Plain Layout
16068 \begin_inset Flex Code
16071 \begin_layout Plain Layout
16083 \begin_layout Plain Layout
16093 Actually, the situation is a bit more complicated: any
16112 other than those described below will produce arabic numerals.
16113 It would not be surprising to see this change in the future.
16119 \begin_inset Flex Code
16122 \begin_layout Plain Layout
16128 : 1, 2, 3,\SpecialChar \ldots{}
16130 \begin_inset Flex Code
16133 \begin_layout Plain Layout
16139 for lower-case letters: a, b, c, \SpecialChar \ldots{}
16141 \begin_inset Flex Code
16144 \begin_layout Plain Layout
16150 for upper-case letters: A, B, C, \SpecialChar \ldots{}
16152 \begin_inset Flex Code
16155 \begin_layout Plain Layout
16161 for lower-case roman numerals: i, ii, iii, \SpecialChar \ldots{}
16163 \begin_inset Flex Code
16166 \begin_layout Plain Layout
16172 for upper-case roman numerals: I, II, III\SpecialChar \ldots{}
16174 \begin_inset Flex Code
16177 \begin_layout Plain Layout
16183 for hebrew numerals.
16187 \begin_layout Standard
16188 If LabelString is not defined, a default value is constructed as follows:
16189 if the counter has a master counter
16190 \begin_inset Flex Code
16193 \begin_layout Plain Layout
16200 \begin_inset Flex Code
16203 \begin_layout Plain Layout
16210 \begin_inset Flex Code
16213 \begin_layout Plain Layout
16223 is used; otherwise the string
16224 \begin_inset Flex Code
16227 \begin_layout Plain Layout
16238 \begin_layout Description
16239 \begin_inset Flex Code
16242 \begin_layout Plain Layout
16243 LabelStringAppendix
16249 \begin_inset Flex Code
16252 \begin_layout Plain Layout
16259 \begin_inset Quotes erd
16263 \begin_inset Quotes erd
16267 \begin_inset Flex Code
16270 \begin_layout Plain Layout
16276 , but for use in the Appendix.
16279 \begin_layout Description
16280 \begin_inset Flex Code
16283 \begin_layout Plain Layout
16290 \begin_inset Flex Code
16293 \begin_layout Plain Layout
16300 \begin_inset Quotes erd
16304 \begin_inset Quotes erd
16307 ] A format for use with formatted references to this counter.
16308 For example, one might want to have references to section numbers appear
16310 \begin_inset Quotes eld
16314 \begin_inset Quotes erd
16318 The string should contain
16319 \begin_inset Quotes eld
16323 \begin_inset Quotes erd
16327 This will be replaced by the counter number itself.
16328 So, for sections, it would be: Section ##.
16331 \begin_layout Description
16332 \begin_inset Flex Code
16335 \begin_layout Plain Layout
16342 \begin_inset Flex Code
16345 \begin_layout Plain Layout
16352 \begin_inset Quotes erd
16356 \begin_inset Quotes erd
16359 ] If this is set to the name of another counter, the present counter will
16360 be reset every time the other one is increased.
16362 \begin_inset Flex Code
16365 \begin_layout Plain Layout
16372 \begin_inset Flex Code
16375 \begin_layout Plain Layout
16384 \begin_layout Subsection
16386 \begin_inset CommandInset label
16388 name "sub:Font-description"
16395 \begin_layout Standard
16396 A font description looks like this:
16399 \begin_layout LyX-Code
16409 \begin_layout LyX-Code
16413 \begin_layout LyX-Code
16417 \begin_layout Standard
16418 The following commands are available:
16421 \begin_layout Description
16422 \begin_inset Flex Code
16425 \begin_layout Plain Layout
16432 \begin_inset Flex Code
16435 \begin_layout Plain Layout
16444 \begin_inset Flex Code
16447 \begin_layout Plain Layout
16454 \begin_inset Flex Code
16457 \begin_layout Plain Layout
16464 \begin_inset Flex Code
16467 \begin_layout Plain Layout
16474 \begin_inset Flex Code
16477 \begin_layout Plain Layout
16484 \begin_inset Flex Code
16487 \begin_layout Plain Layout
16494 \begin_inset Flex Code
16497 \begin_layout Plain Layout
16504 \begin_inset Flex Code
16507 \begin_layout Plain Layout
16514 \begin_inset Flex Code
16517 \begin_layout Plain Layout
16526 \begin_layout Description
16527 \begin_inset Flex Code
16530 \begin_layout Plain Layout
16537 \begin_inset Flex Code
16540 \begin_layout Plain Layout
16549 \begin_inset Flex Code
16552 \begin_layout Plain Layout
16559 \begin_inset Flex Code
16562 \begin_layout Plain Layout
16571 \begin_layout Description
16572 \begin_inset Flex Code
16575 \begin_layout Plain Layout
16582 \begin_inset Flex Code
16585 \begin_layout Plain Layout
16591 ] Valid arguments are:
16592 \begin_inset Flex Code
16595 \begin_layout Plain Layout
16602 \begin_inset Flex Code
16605 \begin_layout Plain Layout
16612 \begin_inset Flex Code
16615 \begin_layout Plain Layout
16622 \begin_inset Flex Code
16625 \begin_layout Plain Layout
16632 \begin_inset Flex Code
16635 \begin_layout Plain Layout
16642 \begin_inset Flex Code
16645 \begin_layout Plain Layout
16652 \begin_inset Flex Code
16655 \begin_layout Plain Layout
16662 \begin_inset Flex Code
16665 \begin_layout Plain Layout
16672 \begin_inset Flex Code
16675 \begin_layout Plain Layout
16682 \begin_inset Flex Code
16685 \begin_layout Plain Layout
16692 \begin_inset Flex Code
16695 \begin_layout Plain Layout
16702 \begin_inset Flex Code
16705 \begin_layout Plain Layout
16712 Each of these turns on or off the corresponding attribute.
16714 \begin_inset Flex Code
16717 \begin_layout Plain Layout
16723 turns on emphasis, and
16724 \begin_inset Flex Code
16727 \begin_layout Plain Layout
16735 \begin_inset Newline newline
16738 If the latter seems puzzling, remember that the font settings for the present
16739 context are generally inherited from the surrounding context.
16741 \begin_inset Flex Code
16744 \begin_layout Plain Layout
16750 would turn off the emphasis that was anyway in effect, say, in a theorem
16754 \begin_layout Description
16755 \begin_inset Flex Code
16758 \begin_layout Plain Layout
16765 \begin_inset Flex Code
16768 \begin_layout Plain Layout
16777 \begin_inset Flex Code
16780 \begin_layout Plain Layout
16789 \begin_layout Description
16790 \begin_inset Flex Code
16793 \begin_layout Plain Layout
16800 \begin_inset Flex Code
16803 \begin_layout Plain Layout
16812 \begin_inset Flex Code
16815 \begin_layout Plain Layout
16822 \begin_inset Flex Code
16825 \begin_layout Plain Layout
16832 \begin_inset Flex Code
16835 \begin_layout Plain Layout
16844 \begin_layout Description
16845 \begin_inset Flex Code
16848 \begin_layout Plain Layout
16855 \begin_inset Flex Code
16858 \begin_layout Plain Layout
16865 \begin_inset Flex Code
16868 \begin_layout Plain Layout
16875 \begin_inset Flex Code
16878 \begin_layout Plain Layout
16887 \begin_inset Flex Code
16890 \begin_layout Plain Layout
16897 \begin_inset Flex Code
16900 \begin_layout Plain Layout
16907 \begin_inset Flex Code
16910 \begin_layout Plain Layout
16917 \begin_inset Flex Code
16920 \begin_layout Plain Layout
16927 \begin_inset Flex Code
16930 \begin_layout Plain Layout
16939 \begin_layout Subsection
16940 \begin_inset CommandInset label
16942 name "sub:Citation-format-description"
16946 Citation format description
16949 \begin_layout Standard
16951 \begin_inset Flex Code
16954 \begin_layout Plain Layout
16960 blocks are used to describe how bibliographic information should be displayed,
16961 both within LyX itself (in the citation dialog and in tooltips, for example)
16962 and in XHTML output.
16963 Such a block might look like this:
16966 \begin_layout LyX-Code
16970 \begin_layout LyX-Code
16974 \begin_layout LyX-Code
16978 \begin_layout LyX-Code
16982 \begin_layout Standard
16983 The individual lines define how the bibliographic information associated
16984 with an article or book, respectively, is to be displayed, and such a definitio
16985 n can be given for any `entry type' that might be present in a BibTeX file.
16986 LyX defines a default format in the source code that will be used if no
16987 specific definition has been given.
16988 LyX predefines several formats in the file
16989 \begin_inset Flex Code
16992 \begin_layout Plain Layout
16998 , which is included in most of LyX's document classes.
17001 \begin_layout Standard
17002 The definitions use a simple language that allows BibTeX keys to be replaced
17004 Keys should be enclosed in
17005 \begin_inset Flex Code
17008 \begin_layout Plain Layout
17015 \begin_inset Flex Code
17018 \begin_layout Plain Layout
17025 So a simple definition might look like this:
17028 \begin_layout LyX-Code
17030 \begin_inset Quotes eld
17034 \begin_inset Quotes erd
17040 \begin_layout Standard
17041 This would print the author, followed by a comma, followed by the title,
17042 in quotes, followed by a period.
17045 \begin_layout Standard
17046 Of course, sometimes you may want to print a key only if it exists.
17047 This can be done by using a conditional construction, such as:
17048 \begin_inset Flex Code
17051 \begin_layout Plain Layout
17053 \begin_inset space ~
17063 \begin_inset Flex Code
17066 \begin_layout Plain Layout
17072 key exists, then print
17073 \begin_inset Quotes eld
17077 \begin_inset space ~
17081 \begin_inset Quotes erd
17084 followed by the volume key.
17085 It is also possible to have an else clause in the conditional, such as:
17087 \begin_inset Flex Code
17090 \begin_layout Plain Layout
17091 {%author%[[%author%]][[%editor%, ed.]]}
17098 \begin_inset Flex Code
17101 \begin_layout Plain Layout
17107 key is printed if it exists; otherwise, the editor key is printed, followed
17109 \begin_inset Quotes eld
17113 \begin_inset space ~
17117 \begin_inset Quotes erd
17120 Note that the key is again enclosed in
17121 \begin_inset Flex Code
17124 \begin_layout Plain Layout
17130 signs; the entire conditional is enclosed in braces; and the if and else
17131 clauses are enclosed in double brackets,
17132 \begin_inset Quotes eld
17136 \begin_inset Flex Code
17139 \begin_layout Plain Layout
17146 \begin_inset Quotes eld
17150 \begin_inset Quotes eld
17154 \begin_inset Flex Code
17157 \begin_layout Plain Layout
17164 \begin_inset Quotes erd
17168 There must be no space between any of these.
17171 \begin_layout Standard
17172 There is one other piece of syntax available in definitions, which looks
17174 \begin_inset Flex Code
17177 \begin_layout Plain Layout
17184 This defines a piece of formatting information that is to be used when
17186 \begin_inset Quotes eld
17190 \begin_inset Quotes erd
17194 Obviously, we do not want to output HTML tags when writing plain text,
17195 so they should be wrapped in
17196 \begin_inset Quotes eld
17200 \begin_inset Quotes erd
17204 \begin_inset Quotes eld
17208 \begin_inset Quotes erd
17214 \begin_layout Standard
17215 Two special sorts of definitions are also possible in a
17216 \begin_inset Flex Code
17219 \begin_layout Plain Layout
17226 An example of the first would be:
17229 \begin_layout LyX-Code
17231 \begin_inset Quotes eld
17235 \begin_inset Quotes erd
17241 \begin_layout Standard
17242 This is an abbreviation, or macro, and it can be used by treating it as
17244 \begin_inset Flex Code
17247 \begin_layout Plain Layout
17255 \begin_inset Flex Code
17258 \begin_layout Plain Layout
17264 exactly as it would treat its definition.
17265 So, let us issue the obvious
17273 \begin_layout LyX-Code
17277 \begin_layout Standard
17278 or anything like it.
17279 LyX shouldn't go into an infinite loop, but it may go into a long one before
17283 \begin_layout Standard
17284 The second sort of special definition might look like this:
17287 \begin_layout LyX-Code
17291 \begin_layout Standard
17292 This defines a translatable piece of text, which allows relevant parts of
17293 the bibliography to be translated.
17294 It can be included in a definition by treating it as a key:
17295 \begin_inset Flex Code
17298 \begin_layout Plain Layout
17305 Several of these are predefined in
17306 \begin_inset Flex Code
17309 \begin_layout Plain Layout
17316 Note that these are not macros, in the sense just defined.
17317 They will not be expanded.
17320 \begin_layout Standard
17321 So here then is an example that use all these features:
17324 \begin_layout LyX-Code
17325 !authoredit {%author%[[%author%, ]][[{%editor%[[%editor%, %_edtext%, ]]}]]}
17328 \begin_layout Standard
17329 This defines a macro that prints the author, followed by a comma, if the
17331 \begin_inset Flex Code
17334 \begin_layout Plain Layout
17340 key is defined, or else prints the name of the editor, followed by the
17342 \begin_inset Flex Code
17345 \begin_layout Plain Layout
17351 or its translation (it is by default
17352 \begin_inset Quotes eld
17356 \begin_inset Quotes erd
17360 \begin_inset Flex Code
17363 \begin_layout Plain Layout
17370 Note that this is in fact defined in
17371 \begin_inset Flex Code
17374 \begin_layout Plain Layout
17380 , so you can use it in your own definitions, or re-definitions, if you load
17384 \begin_layout Section
17385 \begin_inset CommandInset label
17387 name "sec:Tags-for-XHTML"
17391 Tags for XHTML output
17394 \begin_layout Standard
17395 As with LaTeX or DocBook, the format of LyX's XHTML output is also controlled
17396 by layout information.
17397 In general, LyX provides sensible defaults and, as mentioned earlier, it
17398 will even construct default CSS style rules from the other layout tags.
17399 For example, LyX will attempt to use the information provided in the
17400 \begin_inset Flex Code
17403 \begin_layout Plain Layout
17409 declaration for the Chapter style to write CSS that will appropriately
17410 format chapter headings.
17413 \begin_layout Standard
17414 In many cases, then, you may not have to do anything at all to get acceptable
17415 XHTML output for your own environments, custom insets, and so forth.
17416 But in some cases you will, and so LyX provides a number of layout tags
17417 that can be used to customize the XHTML and CSS that are generated.
17420 \begin_layout Standard
17421 Note that there are two tags,
17422 \begin_inset Flex Code
17425 \begin_layout Plain Layout
17432 \begin_inset Flex Code
17435 \begin_layout Plain Layout
17441 that may appear outside style and inset declarations.
17443 \begin_inset CommandInset ref
17445 reference "sub:General-text-class"
17449 for details on these.
17452 \begin_layout Subsection
17453 \begin_inset CommandInset label
17455 name "sub:Paragraph-Style-XHTML"
17462 \begin_layout Standard
17463 The sort of XHTML LyX outputs for a paragraph depends upon whether we are
17464 dealing with a normal paragraph, a command, or an environment, where this
17465 is itself determined by the contents of the corresponding
17466 \begin_inset Flex Code
17469 \begin_layout Plain Layout
17479 \begin_layout Standard
17480 For a command or normal paragraph, the output XHTML has the following form:
17483 \begin_layout LyX-Code
17485 \begin_inset Quotes erd
17489 \begin_inset Quotes erd
17495 \begin_layout LyX-Code
17497 \begin_inset Quotes erd
17501 \begin_inset Quotes erd
17507 \begin_layout LyX-Code
17508 Contents of the paragraph.
17511 \begin_layout LyX-Code
17515 \begin_layout Standard
17516 The label tags are of course omitted if the paragraph does not have a label.
17519 \begin_layout Standard
17520 For an environment that is not some sort of list, the XHTML takes this form:
17523 \begin_layout LyX-Code
17525 \begin_inset Quotes erd
17529 \begin_inset Quotes erd
17535 \begin_layout LyX-Code
17537 \begin_inset Quotes erd
17541 \begin_inset Quotes erd
17545 \begin_inset Quotes erd
17549 \begin_inset Quotes erd
17552 >Environment Label</labeltag>First paragraph.</itemtag>
17555 \begin_layout LyX-Code
17556 <itemtag>Second paragraph.</itemtag>
17559 \begin_layout LyX-Code
17563 \begin_layout Standard
17564 Note that the label is output only for the first paragraph, as it should
17565 be for a theorem, for example.
17569 \begin_layout Standard
17570 For a list, we have one of these forms:
17573 \begin_layout LyX-Code
17575 \begin_inset Quotes erd
17579 \begin_inset Quotes erd
17585 \begin_layout LyX-Code
17587 \begin_inset Quotes erd
17591 \begin_inset Quotes erd
17595 \begin_inset Quotes erd
17599 \begin_inset Quotes erd
17602 >List Label</labeltag>First item.</itemtag>
17605 \begin_layout LyX-Code
17607 \begin_inset Quotes erd
17611 \begin_inset Quotes erd
17615 \begin_inset Quotes erd
17619 \begin_inset Quotes erd
17622 >List Label</labeltag>Second item.</itemtag>
17625 \begin_layout LyX-Code
17629 \begin_layout LyX-Code
17633 \begin_layout LyX-Code
17635 \begin_inset Quotes erd
17639 \begin_inset Quotes erd
17645 \begin_layout LyX-Code
17647 \begin_inset Quotes erd
17651 \begin_inset Quotes erd
17654 >List Label</labeltag><itemtag attr=
17655 \begin_inset Quotes erd
17659 \begin_inset Quotes erd
17662 >First item.</itemtag>
17665 \begin_layout LyX-Code
17667 \begin_inset Quotes erd
17671 \begin_inset Quotes erd
17674 >List Label</labeltag><itemtag attr=
17675 \begin_inset Quotes erd
17679 \begin_inset Quotes erd
17682 >Second item.</itemtag>
17685 \begin_layout LyX-Code
17689 \begin_layout Standard
17690 Note the different orders of
17691 \begin_inset Flex Code
17694 \begin_layout Plain Layout
17701 \begin_inset Flex Code
17704 \begin_layout Plain Layout
17711 Which order we get depends upon the setting of
17712 \begin_inset Flex Code
17715 \begin_layout Plain Layout
17722 \begin_inset Flex Code
17725 \begin_layout Plain Layout
17731 is false (the default), you get the first of these, with the label within
17732 the item; if true, you get the second, with the label outside the item.
17735 \begin_layout Standard
17736 The specific tags and attributes output for each paragraph type can be controlle
17737 d by means of the layout tags we are about to describe.
17738 As mentioned earlier, however, LyX uses sensible defaults for many of these,
17739 so you often may not need to do very much to get good XHTML output.
17740 Think of the available tags as there so you can tweak things to your liking.
17743 \begin_layout Description
17744 \begin_inset Flex Code
17747 \begin_layout Plain Layout
17754 \begin_inset Flex Code
17757 \begin_layout Plain Layout
17763 ] Specifies attribute information to be output with the main tag.
17765 \begin_inset Quotes eld
17769 \begin_inset Flex Code
17772 \begin_layout Plain Layout
17779 \begin_inset Quotes erd
17783 By default, LyX will output
17784 \begin_inset Quotes eld
17788 \begin_inset Flex Code
17791 \begin_layout Plain Layout
17798 \begin_inset Quotes erd
17802 \begin_inset Flex Code
17805 \begin_layout Plain Layout
17811 is the LyX name of the layout, made lowercase, for example: chapter.
17816 contain any style information.
17818 \begin_inset Flex Code
17821 \begin_layout Plain Layout
17830 \begin_layout Description
17831 \begin_inset Flex Code
17834 \begin_layout Plain Layout
17841 \begin_inset Flex Code
17844 \begin_layout Plain Layout
17854 ] Whether to output the default CSS information LyX generates for this layout,
17855 even if additional information is explicitly provided via
17856 \begin_inset Flex Code
17859 \begin_layout Plain Layout
17867 \begin_inset Flex Code
17870 \begin_layout Plain Layout
17876 allows you to alter or augment the generated CSS, rather than to override
17879 \begin_inset Flex Code
17882 \begin_layout Plain Layout
17891 \begin_layout Description
17892 \begin_inset Flex Code
17895 \begin_layout Plain Layout
17902 \begin_inset Flex Code
17905 \begin_layout Plain Layout
17911 ] The tag to be used for individual paragraphs of environments, replacing
17913 \begin_inset Flex Code
17916 \begin_layout Plain Layout
17922 in the examples above.
17924 \begin_inset Flex Code
17927 \begin_layout Plain Layout
17936 \begin_layout Description
17937 \begin_inset Flex Code
17940 \begin_layout Plain Layout
17947 \begin_inset Flex Code
17950 \begin_layout Plain Layout
17956 ] Attributes for the item tag.
17958 \begin_inset Quotes eld
17962 \begin_inset Flex Code
17965 \begin_layout Plain Layout
17966 class=`layoutname_item'
17972 \begin_inset Quotes erd
17980 contain any style information.
17982 \begin_inset Flex Code
17985 \begin_layout Plain Layout
17994 \begin_layout Description
17995 \begin_inset Flex Code
17998 \begin_layout Plain Layout
18005 \begin_inset Flex Code
18008 \begin_layout Plain Layout
18014 ] The tag to be used for paragraph and item labels, replacing
18015 \begin_inset Flex Code
18018 \begin_layout Plain Layout
18024 in the examples above.
18026 \begin_inset Flex Code
18029 \begin_layout Plain Layout
18036 \begin_inset Flex Code
18039 \begin_layout Plain Layout
18046 \begin_inset Flex Code
18049 \begin_layout Plain Layout
18056 \begin_inset Flex Code
18059 \begin_layout Plain Layout
18060 Centered_Top_Environment
18065 , in which case it defaults to
18066 \begin_inset Flex Code
18069 \begin_layout Plain Layout
18078 \begin_layout Description
18079 \begin_inset Flex Code
18082 \begin_layout Plain Layout
18089 \begin_inset Flex Code
18092 \begin_layout Plain Layout
18098 ] Attributes for the label tag.
18100 \begin_inset Quotes eld
18104 \begin_inset Flex Code
18107 \begin_layout Plain Layout
18108 class=`layoutname_label'
18114 \begin_inset Quotes erd
18122 contain any style information.
18124 \begin_inset Flex Code
18127 \begin_layout Plain Layout
18136 \begin_layout Description
18137 \begin_inset Flex Code
18140 \begin_layout Plain Layout
18147 \begin_inset Flex Code
18150 \begin_layout Plain Layout
18160 ] Meaningful only for list-like environments, this tag controls whether
18161 the label tag is output before or inside the item tag.
18162 This is used, for example, in the description environment, where we want
18164 \begin_inset Flex Code
18167 \begin_layout Plain Layout
18168 <dt>\SpecialChar \ldots{}
18169 </dt><dd>\SpecialChar \ldots{}
18177 \begin_inset Flex Code
18180 \begin_layout Plain Layout
18186 : The label tag is output inside the item tag.
18189 \begin_layout Description
18190 \begin_inset Flex Code
18193 \begin_layout Plain Layout
18199 Information to be output in the
18200 \begin_inset Flex Code
18203 \begin_layout Plain Layout
18209 section when this style is used.
18210 This might, for example, be used to include a
18211 \begin_inset Flex Code
18214 \begin_layout Plain Layout
18221 \begin_inset Flex Code
18224 \begin_layout Plain Layout
18233 \begin_layout Description
18234 \begin_inset Flex Code
18237 \begin_layout Plain Layout
18243 CSS style information to be included when this style is used.
18244 Note that this will automatically be wrapped in a layout-generated
18245 \begin_inset Flex Code
18248 \begin_layout Plain Layout
18254 block, so only the CSS itself need be included.
18257 \begin_layout Description
18258 \begin_inset Flex Code
18261 \begin_layout Plain Layout
18268 \begin_inset Flex Code
18271 \begin_layout Plain Layout
18277 ] The tag to be used for the main label, replacing
18278 \begin_inset Flex Code
18281 \begin_layout Plain Layout
18287 in the examples above.
18289 \begin_inset Flex Code
18292 \begin_layout Plain Layout
18301 \begin_layout Description
18302 \begin_inset Flex Code
18305 \begin_layout Plain Layout
18312 \begin_inset Flex Code
18315 \begin_layout Plain Layout
18325 ] Marks this style as the one to be used to generate the
18326 \begin_inset Flex Code
18329 \begin_layout Plain Layout
18335 tag for the XHTML file.
18336 By default, it is false.
18338 \begin_inset Flex Code
18341 \begin_layout Plain Layout
18347 file sets it to true for the
18348 \begin_inset Flex Code
18351 \begin_layout Plain Layout
18361 \begin_layout Subsection
18365 \begin_layout Standard
18366 The XHTML output of insets can also be controlled by information in layout
18371 \begin_layout Plain Layout
18372 At present, this is true only for
18373 \begin_inset Quotes eld
18377 \begin_inset Quotes erd
18380 insets (insets you can type into) and is not true for
18381 \begin_inset Quotes eld
18385 \begin_inset Quotes erd
18388 insets (insets that are associated with dialog boxes).
18393 Here, too, LyX tries to provide sensible defaults, and it constructs default
18395 But everything can be customized.
18398 \begin_layout Standard
18399 The XHTML LyX outputs for an inset has the following form:
18402 \begin_layout LyX-Code
18404 \begin_inset Quotes erd
18408 \begin_inset Quotes erd
18414 \begin_layout LyX-Code
18415 <labeltag>Label</labeltag>
18418 \begin_layout LyX-Code
18420 \begin_inset Quotes erd
18424 \begin_inset Quotes erd
18427 >Contents of the inset.</innertag>
18430 \begin_layout LyX-Code
18434 \begin_layout Standard
18435 If the inset permits multiple paragraphs---that is, if
18436 \begin_inset Flex Code
18439 \begin_layout Plain Layout
18445 is true---then the contents of the inset will itself be output as paragraphs
18446 formatted according to the styles used for those paragraphs (standard,
18447 quote, and the like).
18448 The label tag is of course omitted if the paragraph does not have a label
18449 and, at present, is always
18450 \begin_inset Flex Code
18453 \begin_layout Plain Layout
18460 The inner tag is optional and, by default, does not appear.
18463 \begin_layout Standard
18464 The specific tags and attributes output for each inset can be controlled
18465 by means of the following layout tags.
18468 \begin_layout Description
18469 \begin_inset Flex Code
18472 \begin_layout Plain Layout
18479 \begin_inset Flex Code
18482 \begin_layout Plain Layout
18488 ] Specifies attribute information to be output with the main tag.
18490 \begin_inset Quotes eld
18494 \begin_inset Flex Code
18497 \begin_layout Plain Layout
18498 class=`myinset' onclick=`\SpecialChar \ldots{}
18505 \begin_inset Quotes erd
18509 By default, LyX will output
18510 \begin_inset Quotes eld
18514 \begin_inset Flex Code
18517 \begin_layout Plain Layout
18524 \begin_inset Quotes erd
18528 \begin_inset Flex Code
18531 \begin_layout Plain Layout
18537 is the LyX name of the inset, made lowercase and with non-alphanumeric
18538 characters converted to underscores, for example: footnote.
18541 \begin_layout Description
18542 \begin_inset Flex Code
18545 \begin_layout Plain Layout
18552 \begin_inset Flex Code
18555 \begin_layout Plain Layout
18565 ] Whether to output the default CSS information LyX generates for this layout,
18566 even if additional information is explicitly provided via
18567 \begin_inset Flex Code
18570 \begin_layout Plain Layout
18578 \begin_inset Flex Code
18581 \begin_layout Plain Layout
18587 allows you to alter or augment the generated CSS, rather than to override
18592 \begin_layout Description
18593 \begin_inset Flex Code
18596 \begin_layout Plain Layout
18603 \begin_inset Flex Code
18606 \begin_layout Plain Layout
18612 ] Attributes for the inner tag.
18614 \begin_inset Quotes eld
18618 \begin_inset Flex Code
18621 \begin_layout Plain Layout
18622 class=`insetname_inner'
18628 \begin_inset Quotes erd
18634 \begin_layout Description
18635 \begin_inset Flex Code
18638 \begin_layout Plain Layout
18645 \begin_inset Flex Code
18648 \begin_layout Plain Layout
18654 ] The inner tag, replacing
18655 \begin_inset Flex Code
18658 \begin_layout Plain Layout
18664 in the examples above.
18665 By default, there is none.
18668 \begin_layout Description
18669 \begin_inset Flex Code
18672 \begin_layout Plain Layout
18679 \begin_inset Flex Code
18682 \begin_layout Plain Layout
18690 ] Whether this inset represents a standalone block of text (such as a footnote)
18691 or instead represents material that is included in the surrounding text
18692 (such as a branch).
18696 \begin_layout Description
18697 \begin_inset Flex Code
18700 \begin_layout Plain Layout
18707 \begin_inset Flex Code
18710 \begin_layout Plain Layout
18716 ] A label for this inset, possibly including a reference to a counter.
18717 For example, for footnote, it might be:
18718 \begin_inset Flex Code
18721 \begin_layout Plain Layout
18730 This is optional, and there is no default.
18733 \begin_layout Description
18734 \begin_inset Flex Code
18737 \begin_layout Plain Layout
18743 Information to be output in the
18744 \begin_inset Flex Code
18747 \begin_layout Plain Layout
18753 section when this style is used.
18754 This might, for example, be used to include a
18755 \begin_inset Flex Code
18758 \begin_layout Plain Layout
18765 \begin_inset Flex Code
18768 \begin_layout Plain Layout
18777 \begin_layout Description
18778 \begin_inset Flex Code
18781 \begin_layout Plain Layout
18787 CSS style information to be included when this style is used.
18788 Note that this will automatically be wrapped in a layout-generated
18789 \begin_inset Flex Code
18792 \begin_layout Plain Layout
18798 block, so only the CSS itself need be included.
18801 \begin_layout Description
18802 \begin_inset Flex Code
18805 \begin_layout Plain Layout
18812 \begin_inset Flex Code
18815 \begin_layout Plain Layout
18821 ] The tag to be used for the main label, replacing
18822 \begin_inset Flex Code
18825 \begin_layout Plain Layout
18831 in the examples above.
18832 The default depends upon the setting of
18833 \begin_inset Flex Code
18836 \begin_layout Plain Layout
18843 \begin_inset Flex Code
18846 \begin_layout Plain Layout
18852 is true, the default is
18853 \begin_inset Flex Code
18856 \begin_layout Plain Layout
18862 ; if it is false, the default is
18863 \begin_inset Flex Code
18866 \begin_layout Plain Layout
18875 \begin_layout Subsection
18879 \begin_layout Standard
18880 The XHTML output for floats too can be controlled by layout information.
18881 The output has the following form:
18884 \begin_layout LyX-Code
18886 \begin_inset Quotes erd
18890 \begin_inset Quotes erd
18896 \begin_layout LyX-Code
18897 Contents of the float.
18900 \begin_layout LyX-Code
18904 \begin_layout Standard
18905 The caption, if there is one, is a separate inset and will be output as
18907 Its appearance can be controlled via the InsetLayout for caption insets.
18911 \begin_layout Description
18912 \begin_inset Flex Code
18915 \begin_layout Plain Layout
18922 \begin_inset Flex Code
18925 \begin_layout Plain Layout
18931 ] Specifies attribute information to be output with the main tag.
18933 \begin_inset Quotes eld
18937 \begin_inset Flex Code
18940 \begin_layout Plain Layout
18941 class=`myfloat' onclick=`\SpecialChar \ldots{}
18948 \begin_inset Quotes erd
18952 By default, LyX will output
18953 \begin_inset Quotes eld
18957 \begin_inset Flex Code
18960 \begin_layout Plain Layout
18961 class=`float float-floattype'
18967 \begin_inset Quotes erd
18971 \begin_inset Flex Code
18974 \begin_layout Plain Layout
18980 is LyX's name for this type of float, as determined by the float declaration
18982 \begin_inset CommandInset ref
18984 reference "sub:Floats"
18988 ), though made lowercase and with non-alphanumeric characters converted
18989 to underscores, for example: float-table.
18992 \begin_layout Description
18993 \begin_inset Flex Code
18996 \begin_layout Plain Layout
19002 CSS style information to be included when this float is used.
19003 Note that this will automatically be wrapped in a layout-generated
19004 \begin_inset Flex Code
19007 \begin_layout Plain Layout
19013 block, so only the CSS itself need be included.
19016 \begin_layout Description
19017 \begin_inset Flex Code
19020 \begin_layout Plain Layout
19027 \begin_inset Flex Code
19030 \begin_layout Plain Layout
19036 ] The tag to be used for this float, replacing
19037 \begin_inset Quotes eld
19041 \begin_inset Flex Code
19044 \begin_layout Plain Layout
19051 \begin_inset Quotes erd
19054 in the example above.
19056 \begin_inset Flex Code
19059 \begin_layout Plain Layout
19065 and will rarely need changing.
19068 \begin_layout Subsection
19069 Bibliography formatting
19072 \begin_layout Standard
19073 The bibliography can be formatted using
19074 \begin_inset Flex Code
19077 \begin_layout Plain Layout
19085 \begin_inset CommandInset ref
19087 reference "sub:Citation-format-description"
19094 \begin_layout Subsection
19098 \begin_layout Standard
19099 We have several times mentioned that LyX will generate default CSS style
19100 rules for both insets and paragraph styles, based upon the other layout
19101 information that is provided.
19102 In this section, we shall say a word about which layout information LyX
19106 \begin_layout Standard
19107 At present, LyX auto-generates CSS only for font information, making use
19109 \begin_inset Flex Code
19112 \begin_layout Plain Layout
19119 \begin_inset Flex Code
19122 \begin_layout Plain Layout
19129 \begin_inset Flex Code
19132 \begin_layout Plain Layout
19139 \begin_inset Flex Code
19142 \begin_layout Plain Layout
19149 \begin_inset Flex Code
19152 \begin_layout Plain Layout
19160 \begin_inset CommandInset ref
19162 reference "sub:Font-description"
19166 .) The translation is mostly straightforward and obvious.
19168 \begin_inset Quotes eld
19172 \begin_inset Flex Code
19175 \begin_layout Plain Layout
19182 \begin_inset Quotes erd
19186 \begin_inset Quotes eld
19190 \begin_inset Flex Code
19193 \begin_layout Plain Layout
19194 font-family: sans-serif;
19200 \begin_inset Quotes erd
19204 The correspondence of LyX sizes and CSS sizes is a little less obvious
19205 but nonetheless intuitive.
19207 \begin_inset Flex Code
19210 \begin_layout Plain Layout
19217 \begin_inset Flex URL
19220 \begin_layout Plain Layout
19230 \begin_layout Chapter
19231 Including External Material
19234 \begin_layout Standard
19235 \begin_inset Box Shadowbox
19245 height_special "totalheight"
19248 \begin_layout Plain Layout
19249 WARNING: This portion of the documentation has not been updated for some
19251 We certainly hope that it is still accurate, but there are no guarantees.
19259 \begin_layout Standard
19260 The use of material from sources external to LyX is covered in detail in
19266 This part of the manual covers what needs to happen behind the scenes for
19267 new sorts of material to be included.
19270 \begin_layout Section
19274 \begin_layout Standard
19275 The external material feature is based on the concept of a
19280 A template is a specification of how LyX should interface with a certain
19282 As bundled, LyX comes with predefined templates for Xfig figures, various
19283 raster format images, chess diagrams, and LilyPond music notation.
19284 You can check the actual list by using the menu
19285 \begin_inset Flex MenuItem
19288 \begin_layout Plain Layout
19289 Insert\SpecialChar \menuseparator
19290 File\SpecialChar \menuseparator
19297 Furthermore, it is possible to roll your own template to support a specific
19299 Later we'll describe in more detail what is involved, and hopefully you
19300 will submit all the templates you create so we can include them in a later
19304 \begin_layout Standard
19305 Another basic idea of the external material feature is to distinguish between
19306 the original file that serves as a base for final material and the produced
19307 file that is included in your exported or printed document.
19308 For example, consider the case of a figure produced with
19309 \begin_inset Flex Code
19312 \begin_layout Plain Layout
19319 The Xfig application itself works on an original file with the
19320 \begin_inset Flex Code
19323 \begin_layout Plain Layout
19330 Within Xfig, you create and change your figure, and when you are done,
19332 \begin_inset Flex Code
19335 \begin_layout Plain Layout
19342 When you want to include the figure in your document, you invoke
19343 \begin_inset Flex Code
19346 \begin_layout Plain Layout
19352 in order to create a PostScript file that can readily be included in your
19355 \begin_inset Flex Code
19358 \begin_layout Plain Layout
19364 file is the original file, and the PostScript file is the produced file.
19367 \begin_layout Standard
19368 This distinction is important in order to allow updating of the material
19369 while you are in the process of writing the document.
19370 Furthermore, it provides us with the flexibility that is needed to support
19371 multiple export formats.
19372 For instance, in the case of a plain text file, it is not exactly an award-winn
19373 ing idea to include the figure as raw PostScript.
19374 Instead, you would either prefer to just include a reference to the figure
19375 or try to invoke some graphics to ASCII converter to make the final result
19376 look similar to the real graphics.
19377 The external material management allows you to do this, because it is parametri
19378 zed on the different export formats that LyX supports.
19381 \begin_layout Standard
19382 Besides supporting the production of different products according to the
19383 exported format, it supports tight integration with editing and viewing
19385 In the case of an Xfig figure, you are able to invoke Xfig on the original
19386 file with a single click from within the external material dialog in LyX,
19387 and also preview the produced PostScript file with Ghostview with another
19389 No more fiddling around with the command line and/or file browsers to locate
19390 and manipulate the original or produced files.
19391 In this way, you are finally able to take full advantage of the many different
19392 applications that are relevant to use when you write your documents, and
19393 ultimately be more productive.
19396 \begin_layout Section
19397 The external template configuration file
19400 \begin_layout Standard
19401 It is relatively easy to add custom external template definitions to LyX.
19402 However, be aware that doing this in an careless manner most probably
19406 introduce an easily exploitable security hole.
19407 So before you do this, please read the discussion about security in section
19409 \begin_inset CommandInset ref
19411 reference "sec:Security-discussion"
19418 \begin_layout Standard
19419 Having said that, we encourage you to submit any interesting templates that
19424 \begin_layout Standard
19425 The external templates are defined in the
19426 \begin_inset Flex Code
19429 \begin_layout Plain Layout
19430 LyXDir/lib/external_templates
19436 You can place your own version in
19437 \begin_inset Flex Code
19440 \begin_layout Plain Layout
19441 UserDir/external_templates
19449 \begin_layout Standard
19450 A typical template looks like this:
19453 \begin_layout LyX-Code
19457 \begin_layout LyX-Code
19458 GuiName "XFig: $$AbsOrRelPathParent$$Basename"
19461 \begin_layout LyX-Code
19465 \begin_layout LyX-Code
19469 \begin_layout LyX-Code
19473 \begin_layout LyX-Code
19477 \begin_layout LyX-Code
19481 \begin_layout LyX-Code
19482 AutomaticProduction true
19485 \begin_layout LyX-Code
19489 \begin_layout LyX-Code
19493 \begin_layout LyX-Code
19497 \begin_layout LyX-Code
19498 TransformCommand Rotate RotationLatexCommand
19501 \begin_layout LyX-Code
19502 TransformCommand Resize ResizeLatexCommand
19505 \begin_layout LyX-Code
19506 Product "$$RotateFront$$ResizeFront
19509 \begin_layout LyX-Code
19514 input{$$AbsOrRelPathMaster$$Basename.pstex_t}
19517 \begin_layout LyX-Code
19518 $$ResizeBack$$RotateBack"
19521 \begin_layout LyX-Code
19525 \begin_layout LyX-Code
19526 UpdateResult "$$AbsPath$$Basename.pstex_t"
19529 \begin_layout LyX-Code
19530 Requirement "graphicx"
19533 \begin_layout LyX-Code
19534 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
19537 \begin_layout LyX-Code
19538 ReferencedFile latex "$$AbsPath$$Basename.eps"
19541 \begin_layout LyX-Code
19542 ReferencedFile dvi "$$AbsPath$$Basename.eps"
19545 \begin_layout LyX-Code
19549 \begin_layout LyX-Code
19553 \begin_layout LyX-Code
19554 TransformCommand Rotate RotationLatexCommand
19557 \begin_layout LyX-Code
19558 TransformCommand Resize ResizeLatexCommand
19561 \begin_layout LyX-Code
19562 Product "$$RotateFront$$ResizeFront
19565 \begin_layout LyX-Code
19570 input{$$AbsOrRelPathMaster$$Basename.pdftex_t}
19573 \begin_layout LyX-Code
19574 $$ResizeBack$$RotateBack"
19577 \begin_layout LyX-Code
19578 UpdateFormat pdftex
19581 \begin_layout LyX-Code
19582 UpdateResult "$$AbsPath$$Basename.pdftex_t"
19585 \begin_layout LyX-Code
19586 Requirement "graphicx"
19589 \begin_layout LyX-Code
19590 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pdftex_t"
19593 \begin_layout LyX-Code
19594 ReferencedFile latex "$$AbsPath$$Basename.pdf"
19597 \begin_layout LyX-Code
19601 \begin_layout LyX-Code
19605 \begin_layout LyX-Code
19606 Product "$$Contents(
19608 "$$AbsPath$$Basename.asc
19613 \begin_layout LyX-Code
19614 UpdateFormat asciixfig
19617 \begin_layout LyX-Code
19618 UpdateResult "$$AbsPath$$Basename.asc"
19621 \begin_layout LyX-Code
19625 \begin_layout LyX-Code
19629 \begin_layout LyX-Code
19630 Product "<graphic fileref=
19632 "$$AbsOrRelPathMaster$$Basename.eps
19637 \begin_layout LyX-Code
19641 \begin_layout LyX-Code
19645 \begin_layout LyX-Code
19646 UpdateResult "$$AbsPath$$Basename.eps"
19649 \begin_layout LyX-Code
19650 ReferencedFile docbook "$$AbsPath$$Basename.eps"
19653 \begin_layout LyX-Code
19654 ReferencedFile docbook-xml "$$AbsPath$$Basename.eps"
19657 \begin_layout LyX-Code
19661 \begin_layout LyX-Code
19662 Product "[XFig: $$FName]"
19665 \begin_layout LyX-Code
19669 \begin_layout LyX-Code
19673 \begin_layout Standard
19674 As you can see, the template is enclosed in
19675 \begin_inset Flex Code
19678 \begin_layout Plain Layout
19684 \SpecialChar \ldots{}
19686 \begin_inset Flex Code
19689 \begin_layout Plain Layout
19696 It contains a header specifying some general settings and, for each supported
19697 primary document file format, a section
19698 \begin_inset Flex Code
19701 \begin_layout Plain Layout
19707 \SpecialChar \ldots{}
19709 \begin_inset Flex Code
19712 \begin_layout Plain Layout
19721 \begin_layout Subsection
19722 The template header
19725 \begin_layout Description
19726 \begin_inset Flex Code
19729 \begin_layout Plain Layout
19730 AutomaticProduction
19731 \begin_inset space ~
19739 Whether the file represented by the template must be generated by LyX.
19740 This command must occur exactly once.
19743 \begin_layout Description
19744 \begin_inset Flex Code
19747 \begin_layout Plain Layout
19749 \begin_inset space ~
19757 A glob pattern that is used in the file dialog to filter out the desired
19759 If there is more than one possible file extension (e.
19760 \begin_inset space \thinspace{}
19764 \begin_inset space \space{}
19768 \begin_inset Flex Code
19771 \begin_layout Plain Layout
19778 \begin_inset Flex Code
19781 \begin_layout Plain Layout
19787 ), use something like
19788 \begin_inset Flex Code
19791 \begin_layout Plain Layout
19798 This command must occur exactly once.
19801 \begin_layout Description
19802 \begin_inset Flex Code
19805 \begin_layout Plain Layout
19807 \begin_inset space ~
19815 The text that is displayed on the button.
19816 This command must occur exactly once.
19819 \begin_layout Description
19820 \begin_inset Flex Code
19823 \begin_layout Plain Layout
19825 \begin_inset space ~
19829 \begin_inset space ~
19837 The help text that is used in the External dialog.
19838 Provide enough information to explain to the user just what the template
19839 can provide him with.
19840 This command must occur exactly once.
19843 \begin_layout Description
19844 \begin_inset Flex Code
19847 \begin_layout Plain Layout
19849 \begin_inset space ~
19857 The file format of the original file.
19858 This must be the name of a format that is known to LyX (see section
19859 \begin_inset space ~
19863 \begin_inset CommandInset ref
19865 reference "sec:Formats"
19871 \begin_inset Quotes eld
19875 \begin_inset Flex Code
19878 \begin_layout Plain Layout
19885 \begin_inset Quotes erd
19888 if the template can handle original files of more than one format.
19889 LyX will attempt to interrogate the file itself in order to deduce its
19890 format in this case.
19891 This command must occur exactly once.
19894 \begin_layout Description
19895 \begin_inset Flex Code
19898 \begin_layout Plain Layout
19900 \begin_inset space ~
19908 A unique name for the template.
19909 It must not contain substitution macros (see below).
19912 \begin_layout Description
19913 \begin_inset Flex Code
19916 \begin_layout Plain Layout
19918 \begin_inset space ~
19921 Rotate|Resize|Clip|Extra
19926 This command specifies which transformations are supported by this template.
19927 It may occur zero or more times.
19928 This command enables the corresponding tabs in the external dialog.
19930 \begin_inset Flex Code
19933 \begin_layout Plain Layout
19939 command must have either a corresponding
19940 \begin_inset Flex Code
19943 \begin_layout Plain Layout
19950 \begin_inset Flex Code
19953 \begin_layout Plain Layout
19960 \begin_inset Flex Code
19963 \begin_layout Plain Layout
19970 Otherwise the transformation will not be supported by that format.
19973 \begin_layout Subsection
19977 \begin_layout Description
19978 \begin_inset Flex Code
19981 \begin_layout Plain Layout
19983 \begin_inset space ~
19986 LaTeX|PDFLaTeX|PlainText|DocBook
19991 The primary document file format that this format definition is for.
19992 Not every template has a sensible representation in all document file formats.
19993 Please define nevertheless a
19994 \begin_inset Flex Code
19997 \begin_layout Plain Layout
20003 section for all templates.
20004 Use a dummy text when no representation is available.
20005 Then you can at least see a reference to the external material in the exported
20009 \begin_layout Description
20010 \begin_inset Flex Code
20013 \begin_layout Plain Layout
20015 \begin_inset space ~
20019 \begin_inset space ~
20027 This command defines an additional macro
20028 \begin_inset Flex Code
20031 \begin_layout Plain Layout
20037 for substitution in
20038 \begin_inset Flex Code
20041 \begin_layout Plain Layout
20049 \begin_inset Flex Code
20052 \begin_layout Plain Layout
20058 itself may contain substitution macros.
20059 The advantage over using
20060 \begin_inset Flex Code
20063 \begin_layout Plain Layout
20070 \begin_inset Flex Code
20073 \begin_layout Plain Layout
20079 is that the substituted value of
20080 \begin_inset Flex Code
20083 \begin_layout Plain Layout
20089 is sanitized so that it is a valid optional argument in the document format.
20090 This command may occur zero or more times.
20093 \begin_layout Description
20094 \begin_inset Flex Code
20097 \begin_layout Plain Layout
20099 \begin_inset space ~
20107 The text that is inserted in the exported document.
20108 This is actually the most important command and can be quite complex.
20109 This command must occur exactly once.
20112 \begin_layout Description
20113 \begin_inset Flex Code
20116 \begin_layout Plain Layout
20118 \begin_inset space ~
20126 This command specifies a preamble snippet that will be included in the
20128 It has to be defined using
20129 \begin_inset Flex Code
20132 \begin_layout Plain Layout
20138 \SpecialChar \ldots{}
20140 \begin_inset Flex Code
20143 \begin_layout Plain Layout
20150 This command may occur zero or more times.
20153 \begin_layout Description
20154 \begin_inset Flex Code
20157 \begin_layout Plain Layout
20159 \begin_inset space ~
20163 \begin_inset space ~
20171 This command denotes files that are created by the conversion process and
20172 are needed for a particular export format.
20173 If the filename is relative, it is interpreted relative to the master document.
20174 This command may be given zero or more times.
20177 \begin_layout Description
20178 \begin_inset Flex Code
20181 \begin_layout Plain Layout
20183 \begin_inset space ~
20191 The name of a required LaTeX package.
20192 The package is included via
20193 \begin_inset Flex Code
20196 \begin_layout Plain Layout
20204 in the LaTeX preamble.
20205 This command may occur zero or more times.
20208 \begin_layout Description
20209 \begin_inset Flex Code
20212 \begin_layout Plain Layout
20214 \begin_inset space ~
20218 \begin_inset space ~
20221 RotationLatexCommand
20226 This command specifies that the built in LaTeX command should be used for
20228 This command may occur once or not at all.
20231 \begin_layout Description
20232 \begin_inset Flex Code
20235 \begin_layout Plain Layout
20237 \begin_inset space ~
20241 \begin_inset space ~
20249 This command specifies that the built in LaTeX command should be used for
20251 This command may occur once or not at all.
20254 \begin_layout Description
20255 \begin_inset Flex Code
20258 \begin_layout Plain Layout
20260 \begin_inset space ~
20264 \begin_inset space ~
20267 RotationLatexOption
20272 This command specifies that rotation is done via an optional argument.
20273 This command may occur once or not at all.
20276 \begin_layout Description
20277 \begin_inset Flex Code
20280 \begin_layout Plain Layout
20282 \begin_inset space ~
20286 \begin_inset space ~
20294 This command specifies that resizing is done via an optional argument.
20295 This command may occur once or not at all.
20298 \begin_layout Description
20299 \begin_inset Flex Code
20302 \begin_layout Plain Layout
20304 \begin_inset space ~
20308 \begin_inset space ~
20316 This command specifies that clipping is done via an optional argument.
20317 This command may occur once or not at all.
20320 \begin_layout Description
20321 \begin_inset Flex Code
20324 \begin_layout Plain Layout
20326 \begin_inset space ~
20330 \begin_inset space ~
20338 This command specifies that an extra optional argument is used.
20339 This command may occur once or not at all.
20342 \begin_layout Description
20343 \begin_inset Flex Code
20346 \begin_layout Plain Layout
20348 \begin_inset space ~
20356 The file format of the converted file.
20357 This must be the name of a format that is known to LyX (see the
20358 \begin_inset Flex MenuItem
20361 \begin_layout Plain Layout
20366 ools\SpecialChar \menuseparator
20371 references\SpecialChar \menuseparator
20372 File Handling\SpecialChar \menuseparator
20379 This command must occur exactly once.
20382 \begin_layout Description
20383 \begin_inset Flex Code
20386 \begin_layout Plain Layout
20388 \begin_inset space ~
20396 The file name of the converted file.
20397 The file name must be absolute.
20398 This command must occur exactly once.
20401 \begin_layout Subsection
20402 Preamble definitions
20405 \begin_layout Standard
20406 The external template configuration file may contain additional preamble
20407 definitions enclosed by
20408 \begin_inset Flex Code
20411 \begin_layout Plain Layout
20417 \SpecialChar \ldots{}
20419 \begin_inset Flex Code
20422 \begin_layout Plain Layout
20429 They can be used by the templates in the
20430 \begin_inset Flex Code
20433 \begin_layout Plain Layout
20442 \begin_layout Section
20443 The substitution mechanism
20446 \begin_layout Standard
20447 When the external material facility invokes an external program, it is done
20448 on the basis of a command defined in the template configuration file.
20449 These commands can contain various macros that are expanded before execution.
20450 Execution always take place in the directory of the containing document.
20453 \begin_layout Standard
20454 Also, whenever external material is to be displayed, the name will be produced
20455 by the substitution mechanism, and most other commands in the template
20456 definition support substitution as well.
20459 \begin_layout Standard
20460 The available macros are the following:
20463 \begin_layout Description
20464 \begin_inset Flex Code
20467 \begin_layout Plain Layout
20468 $$AbsOrRelPathMaster
20473 The file path, absolute or relative to the master LyX document.
20476 \begin_layout Description
20477 \begin_inset Flex Code
20480 \begin_layout Plain Layout
20481 $$AbsOrRelPathParent
20486 The file path, absolute or relative to the LyX document.
20489 \begin_layout Description
20490 \begin_inset Flex Code
20493 \begin_layout Plain Layout
20499 The absolute file path.
20502 \begin_layout Description
20503 \begin_inset Flex Code
20506 \begin_layout Plain Layout
20512 The filename without path and without the extension.
20515 \begin_layout Description
20516 \begin_inset Flex Code
20519 \begin_layout Plain Layout
20521 \begin_inset Quotes eld
20525 \begin_inset Quotes erd
20533 This macro will expand to the contents of the file with the name
20534 \begin_inset Flex Code
20537 \begin_layout Plain Layout
20546 \begin_layout Description
20547 \begin_inset Flex Code
20550 \begin_layout Plain Layout
20556 The file extension (including the dot).
20559 \begin_layout Description
20560 \begin_inset Flex Code
20563 \begin_layout Plain Layout
20569 The filename of the file specified in the external material dialog.
20570 This is either an absolute name, or it is relative to the LyX document.
20573 \begin_layout Description
20574 \begin_inset Flex Code
20577 \begin_layout Plain Layout
20584 \begin_inset Flex Code
20587 \begin_layout Plain Layout
20593 (absolute name or relative to the LyX document).
20596 \begin_layout Description
20597 \begin_inset Flex Code
20600 \begin_layout Plain Layout
20606 The file path, relative to the master LyX document.
20609 \begin_layout Description
20610 \begin_inset Flex Code
20613 \begin_layout Plain Layout
20619 The file path, relative to the LyX document.
20622 \begin_layout Description
20623 \begin_inset Flex Code
20626 \begin_layout Plain Layout
20632 This macro will expand to the absolute path of the system directory.
20633 This is typically used to point to the various helper scripts that are
20637 \begin_layout Description
20638 \begin_inset Flex Code
20641 \begin_layout Plain Layout
20647 A name and full path to a temporary file which will be automatically deleted
20648 whenever the containing document is closed, or the external material insertion
20652 \begin_layout Standard
20653 All path macros contain a trailing directory separator, so you can construct
20655 \begin_inset space \thinspace{}
20659 \begin_inset space \space{}
20662 the absolute filename with
20663 \begin_inset Flex Code
20666 \begin_layout Plain Layout
20667 $$AbsPath$$Basename$$Extension
20675 \begin_layout Standard
20676 The macros above are substituted in all commands unless otherwise noted.
20678 \begin_inset Flex Code
20681 \begin_layout Plain Layout
20687 supports additionally the following substitutions if they are enabled by
20689 \begin_inset Flex Code
20692 \begin_layout Plain Layout
20699 \begin_inset Flex Code
20702 \begin_layout Plain Layout
20711 \begin_layout Description
20712 \begin_inset Flex Code
20715 \begin_layout Plain Layout
20721 The front part of the resize command.
20724 \begin_layout Description
20725 \begin_inset Flex Code
20728 \begin_layout Plain Layout
20734 The back part of the resize command.
20737 \begin_layout Description
20738 \begin_inset Flex Code
20741 \begin_layout Plain Layout
20747 The front part of the rotation command.
20750 \begin_layout Description
20751 \begin_inset Flex Code
20754 \begin_layout Plain Layout
20760 The back part of the rotation command.
20763 \begin_layout Standard
20764 The value string of the
20765 \begin_inset Flex Code
20768 \begin_layout Plain Layout
20774 command supports additionally the following substitutions if they are enabled
20776 \begin_inset Flex Code
20779 \begin_layout Plain Layout
20786 \begin_inset Flex Code
20789 \begin_layout Plain Layout
20798 \begin_layout Description
20799 \begin_inset Flex Code
20802 \begin_layout Plain Layout
20811 \begin_layout Description
20812 \begin_inset Flex Code
20815 \begin_layout Plain Layout
20824 \begin_layout Description
20825 \begin_inset Flex Code
20828 \begin_layout Plain Layout
20837 \begin_layout Description
20838 \begin_inset Flex Code
20841 \begin_layout Plain Layout
20847 The rotation option.
20850 \begin_layout Standard
20851 You may ask why there are so many path macros.
20852 There are mainly two reasons:
20855 \begin_layout Enumerate
20856 Relative and absolute file names should remain relative or absolute, respectivel
20858 Users may have reasons to prefer either form.
20859 Relative names are useful for portable documents that should work on different
20860 machines, for example.
20861 Absolute names may be required by some programs.
20864 \begin_layout Enumerate
20865 LaTeX treats relative file names differently than LyX and other programs
20866 in nested included files.
20867 For LyX, a relative file name is always relative to the document that contains
20869 For LaTeX, it is always relative to the master document.
20870 These two definitions are identical if you have only one document, but
20871 differ if you have a master document that includes part documents.
20872 That means that relative filenames must be transformed when presented to
20874 Fortunately LyX does this automatically for you if you choose the right
20878 \begin_layout Standard
20879 So which path macro should be used in new template definitions? The rule
20883 \begin_layout Itemize
20885 \begin_inset Flex Code
20888 \begin_layout Plain Layout
20894 if an absolute path is required.
20897 \begin_layout Itemize
20899 \begin_inset Flex Code
20902 \begin_layout Plain Layout
20903 $$AbsOrRelPathMaster
20908 if the substituted string is some kind of LaTeX input.
20911 \begin_layout Itemize
20913 \begin_inset Flex Code
20916 \begin_layout Plain Layout
20917 $$AbsOrRelPathParent
20922 in order to preserve the user's choice.
20925 \begin_layout Standard
20926 There are special cases where this rule does not work and e.
20927 \begin_inset space \thinspace{}
20931 \begin_inset space \space{}
20934 relative names are needed, but normally it will work just fine.
20935 One example for such a case is the command
20936 \begin_inset Flex Code
20939 \begin_layout Plain Layout
20940 ReferencedFile latex "$$AbsOrRelPathMaster$$Basename.pstex_t"
20945 in the XFig template above: We can't use the absolute name because the
20947 \begin_inset Flex Code
20950 \begin_layout Plain Layout
20956 files needs the relative name in order to rewrite the file content.
20959 \begin_layout Section
20960 Security discussion
20961 \begin_inset CommandInset label
20963 name "sec:Security-discussion"
20970 \begin_layout Standard
20971 The external material feature interfaces with a lot of external programs
20972 and does so automatically, so we have to consider the security implications
20974 In particular, since you have the option of including your own filenames
20975 and/or parameter strings and those are expanded into a command, it seems
20976 that it would be possible to create a malicious document which executes
20977 arbitrary commands when a user views or prints the document.
20978 This is something we definitely want to avoid.
20981 \begin_layout Standard
20982 However, since the external program commands are specified in the template
20983 configuration file only, there are no security issues if LyX is properly
20984 configured with safe templates only.
20985 This is so because the external programs are invoked with the
20986 \begin_inset Flex Code
20989 \begin_layout Plain Layout
20995 -system call rather than the
20996 \begin_inset Flex Code
20999 \begin_layout Plain Layout
21005 system-call, so it's not possible to execute arbitrary commands from the
21006 filename or parameter section via the shell.
21009 \begin_layout Standard
21010 This also implies that you are restricted in what command strings you can
21011 use in the external material templates.
21012 In particular, pipes and redirection are not readily available.
21013 This has to be so if LyX should remain safe.
21014 If you want to use some of the shell features, you should write a safe
21015 script to do this in a controlled manner, and then invoke the script from
21016 the command string.
21020 \begin_layout Standard
21021 It is possible to design a template that interacts directly with the shell,
21022 but since this would allow a malicious user to execute arbitrary commands
21023 by writing clever filenames and/or parameters, we generally recommend that
21024 you only use safe scripts that work with the
21025 \begin_inset Flex Code
21028 \begin_layout Plain Layout
21034 system call in a controlled manner.
21035 Of course, for use in a controlled environment, it can be tempting to just
21036 fall back to use ordinary shell scripts.
21037 If you do so, be aware that you
21041 provide an easily exploitable security hole in your system.
21042 Of course it stands to reason that such unsafe templates will never be
21043 included in the standard LyX distribution, although we do encourage people
21044 to submit new templates in the open source tradition.
21045 But LyX as shipped from the official distribution channels will never have
21049 \begin_layout Standard
21050 Including external material provides a lot of power, and you have to be
21051 careful not to introduce security hazards with this power.
21052 A subtle error in a single line in an innocent looking script can open
21053 the door to huge security problems.
21054 So if you do not fully understand the issues, we recommend that you consult
21055 a knowledgeable security professional or the LyX development team if you
21056 have any questions about whether a given template is safe or not.
21057 And do this before you use it in an uncontrolled environment.